Generating Parquet Files with GGIR

Prerequisites

The arrow R package must be installed. GGIR requires R ≥ 4.0.

install.packages("arrow")

For full documentation on GGIR installation and configuration, see the official GGIR documentation and the CRAN package page.

How to Enable Parquet Export

Set the parameter save_dashboard_parquet to TRUE in your GGIR() call. The Parquet file is generated automatically after all requested parts and reports have completed.

save_dashboard_parquet defaults to FALSE. No Parquet file is generated unless you explicitly set it to TRUE.

Code Examples

library(GGIR)
GGIR(
  mode = 1:5,
  datadir = "C:/mystudy/mydata",
  outputdir = "C:/myresults",
  do.report = c(2, 4, 5),
  save_dashboard_parquet = TRUE
)

library(GGIR)
GGIR(
  mode = 1:5,
  datadir = "C:/mystudy/mydata",
  outputdir = "C:/myresults",
  studyname = "my_study",
  do.report = c(2, 4, 5),
  threshold.lig = 40,
  threshold.mod = 100,
  threshold.vig = 400,
  save_dashboard_parquet = TRUE
)

Output File

When enabled, the following file is created in the results directory:

<outputdir>/output_<studyname>/results/participant_id.parquet

Replace <outputdir> and <studyname> with the values you passed to GGIR(). If you did not set a studyname, GGIR uses the input folder name.

Using with the Dashboard

Once GGIR has finished processing and the Parquet file has been generated:

1. Navigate to the GGIR Dashboard.
2. Upload your participant_id.parquet file.
3. The dashboard will automatically parse the file and present interactive visualisations of your study data.

No additional software, coding, or data manipulation is required.

What the Parquet File Contains

The Parquet file is a single consolidated table at the day level (one row per participant per calendar day). It is built by automatically joining data from multiple GGIR output parts:

The file also carries embedded metadata such as the acceleration thresholds used, the acceleration metric (e.g., ENMO), epoch length, and a variable dictionary — all of which the dashboard uses to correctly label and interpret your data.

Database Schema & Developer Notes

For users who want to query the Parquet file outside of this dashboard (e.g., via Python, R, or native DuckDB), the file uses a flat, day-level schema where each row represents one participant per calendar day. The primary key is (id, calendar_date).

SELECT id, calendar_date, weekday,
       dur_day_total_mod_min + dur_day_total_vig_min AS mvpa_min,
       dur_spt_sleep_min, sleep_efficiency_after_onset
FROM ggir
WHERE nonwear_perc_day_spt < 25;

SELECT g.id, g.calendar_date, e.*
FROM ggir g, UNNEST(g.epochs) AS e
WHERE g.id = 'participant_001'
  AND g.calendar_date = '2024-03-15';

SELECT * FROM parquet_kv_metadata('participant_id.parquet');

Privacy & Data Security

This dashboard is designed with researcher data privacy as a core principle. It uses DuckDB-WASM to query and process your data entirely within your browser.

• File reading — your file is read directly into browser memory via the File API; no upload occurs.
• SQL queries — all DuckDB queries execute inside a WebAssembly sandbox in your browser tab.
• Visualizations — every chart is rendered client-side; no server-side rendering or data relay.
• No analytics on your data — the app does not send your participant data to any analytics or tracking service.
• Works offline — after the initial page load, the dashboard functions fully without an internet connection. You can verify this by disconnecting after the page loads.

Troubleshooting

If the Parquet file is not created after your GGIR run completes, check the R console for the following warning messages: