In wadpac/GGIR: Raw Accelerometer Data Analysis

NOTE: If you are viewing this page via CRAN note that the main GGIR documentation has been migrated to the GGIR GitHub pages.

Household co-analysis facilitates the analysis of how sleep and physical activity relate between members of the same household.

Accelerometer file names

The household co-analysis requires that households and family member can be recognised. To do this we assume the following logic in the file names:

StudyNumber-HouseholdID-MemberID_anyotherinformation.bin

This example is for a .bin file, but the same applies to .cwa or .csv files.

For example the files:

• 001-002-001_12345-2023.bin
• 001-002-002_23456-2023.bin
• 001-002-M_23456-2023.bin

will be recognised as household ID 002 with member IDs 001, 002, and M.

Configuring GGIR

The following input arguments are needed to run the Household co-analysis:

• The Household co-analysis is integrated in GGIR as part 6, so we need to run GGIR with part 1 to 6, with mode = 1:6.
• windowsizes = c(5, 60, 3600). Setting the second value to 60 ensures that light and temperature, if available, are aggregated per minute.
• part5_agg2_60seconds = TRUE. This ensures that GGIR part 5 stores the time series at 1 minute resolution.
• part6HCA = TRUE to tell GGIR to perform Household Co-Analysis.
• part6_threshold_combi = "30_100_400" where 30, 100 and 400 need to correspond to the accelerometer threshold combination that is used in part 5 that you want to use in part 6. GGIR part 5 facilitates multiple threshold combinations but in part 6 you need to select one.

Other GGIR arguments can be set according to your own needs. For an example:

datadir = "C:/projects/studyZ/binfiles"
outputdir = "C:/projects/studyZ"
library(GGIR)
GGIR(mode = 1:5, 
     datadir = datadir,
     idloc = 2, 
     outputdir = outputdir,
     do.report = c(2, 4, 5),
     do.parallel = TRUE,
     overwrite = FALSE,
     printsummary = TRUE,
     desiredtz = "America/Halifax",
     windowsizes = c(5, 60, 3600),
     threshold.lig = 30,
     threshold.mod = 100,
     threshold.vig = 400,
     part6_threshold_combi = "30_100_400",
     boutcriter.in = 1, boutcriter.lig = 1,  boutcriter.mvpa = 0.9,
     boutdur.in = 30,
     boutdur.lig = 10,
     boutdur.mvpa = 5,
     part6HCA = TRUE,
     save_ms5rawlevels = TRUE, # Not necessary because GGIR will set this to TRUE when part6HCA is TRUE.
     save_ms5raw_without_invalid = FALSE, # <= Needed for household co-analysis
     part5_agg2_60seconds = TRUE,
     visualreport = FALSE) 

Household co-analysis

In GGIR part 1, 2, 3, 4, and 5 each recording is processed individually without considering relations between recordings. Next, part 6 is subdivided in alligning the time series produced by part 1 and 5 per household, and the pairwise analysis of the data.

Align individuals

Household members with only one member are ignored. Next, per household and per household member the code loads and merges the time series produced by GGIR part 1 and part 5. Days, defined from waking-up to waking-up, are removed if they have less than 20% valid data during waking hours, the sleep period time window, or the day as a whole. Next, time series are completed with indicates of valid household member pairs for each time points.

Finally, we store:

• The aligned time series per household in separate csv files in the GGIR output directory (.../results/part6HouseholdCoAnalysis/alignedTimeseries). The columns for this file are documented further down.
• A pdf file names timeseriesPlot.pdf with plots of the aligned time series to facilitate visual inspection of the data completeness per household.

Pairwise analysis

Per household we identify all possible member pairs and loop over these pairs.

Per member pair the code identify wake-up time pairs. Here, wake-up times that occur within the last 15 minutes of the time series are ignored as we need at least some recording time to quantify behaviour after waking up.

Per wake-up pair we assess who woke up first and second, the time difference, and the corresponding calendar dates of waking up.

Next, the code quantifies:

• Activity of person who first woke up during minute before second person woke up
• Activity of second person to wake up before they woke up
• LUX of person who first woke up during tminute before second person woke up
• LUX of second person to wake up before they woke up.

Describe matching waking hours between pairs:

• Correlation between continuous acceleration values (ENMO metric)
• Derive binary class of inactivity/active (ENMO metric, and threshold < 50)
• ICC based on binary scores (irr package, model=twoway, type=agreement, unit=single)
• Cohen’s Kappa (psych package)
• Similarity in binary scores (calculation in line with Sleep Regularity Index)

Describe noon-noon window with a stronger focus on sleep:

• Describe binary class of sleep/wakefulness (note: does not attempt to classify daytime naps)
• ICC based on binary scores (irr package, model=twoway, type=agreement, unit=single)
• Cohen’s Kappa (psych package)
• Similarity in binary scores (calculation in line with Sleep Regularity Index)

Describe wakefulness dynamics during the SPT prior to wakeup:

• Look up indices of spt prior to wakeup where both individuals where in SPT.
• Assess fraction of data valid
• Identify wake up times during the night

For each wake-up time:

• Assess whether both persons woke up at the same time, other person wake up within 5 minutes, or other person does not wake up within 5 minutes.
• Store output to csv one row per unique household pair, with columns to clarify who the household members are in the pair and from which household they are.

Output variables

alignedTimesieres

In the GGIR output folder .../results/part6HouseholdCoAnalysis/alignedTimeseries you will find csv files with the time series per household.

The data dictionary below shows the column names you would get for a household with two members: X and Y. Most of the columns are copied from the time series output files, which are documented here. Therefore, those column are not documented here.

Variable name | Description ---- | ---------- timenum | Timestamp for tSeconds since since 1-1-1970 HID | Household ID ACC.X | Average magnitude of acceleration for household member X SleepPeriodTime.X | - invalidepoch.X | - guider.X | - window.X | - class_id.X | - lightmean.X | Mean light sensor value for member X lightpeak.X | Peak light sensor value for member X temperaturemean.X | Mean temperature value for member X onset.X | 1 to indicate sleep onset time for member X wakeup.X | 1 to indicate waking up for member X validepoch.X | 1 if epoch was valid ACC.Y | Average magnitude of acceleration for household member X SleepPeriodTime.Y | - invalidepoch.Y | - guider.Y | - window.Y | - class_id.Y | - lightmean.Y | See lightmean.X but now for member Y lightpeak.Y | See lightpeak.X but now for member Y temperaturemean.Y | - onset.Y | - wakeup.Y | - validepoch.Y | - time_POSIX | Timestamp in character format N_valid_hhmembers | Number of valid household member pairs validpair_X_Y | TRUE or FALSE to indicate whether the pair had valid data for this timestamp

Pairwise summary report

As stored inside pairwise_summary_all_housholds.csv

Variable name | Description ---- | ---------- HID | Household ID Npairs | Number of unique pairs in a household PID | Pair ID MID1 | Household member ID for the first person in the pair MID2 | Household member ID for the second person in the pair event | Number to count the number of events, for now these are days with valid wake-up estimates in both individuals time1 | Time person 1 wakes up time2 | Time person 2 wakes up date1 | Date person 1 wakes up date2 | Date person 2 wakes up index_wake1 | Index in the time series when person 1 woke up (probably not relevant for end-user) index_wake2 | Index in the time series when person 2 woke up (probably not relevant for end-user) firstawake | Who of the two individuals woke up first? If equal then value will be "equal" wakeup_acc_wake1_before_wake2_mg | Mean acceleration (mg) of the person who wakes up first during the four minutes before the second person wakes up wakeup_acc_wake2_before_wake2_mg | Mean acceleration (mg) of second person to wake up before they woke up wakeup_lux_wake1_before_wake2 | Peak LUX of the person who wakes up first during the four minutes before the second person wakes up wakeup_lux_wake2_before_wake2 | Peak LUX of second person to wake up before they woke up wakeup_deltatime_min | Difference in wake up time in minutes r_acceleration | Pearson correlation in continuous acceleration values ICC_sleep | ICC (from R package irr) calculated based on binary scores of sleep (excluding WASO) ICC_sleep_Fvalue | Fvalue for ICC_sleep ICC_active | ICC (from R package irr) calculated based on binary scores of activity (metric ENMO < 50 chosen for now) ICC_active_Fvalue | Favlue for ICC_active frac_valid | Fraction of pair epochs between individuals for a certain day that were valid SleepSimilarityIndex | Similarity in binary sleep/wake patterns between pairs per calendar day ActivitySimilarityIndex | Similarity in binary active/inactive patterns between pairs per calendar day Kappa_sleep | Weighted Cohen's Kappa coefficient calculated based on binary scores of sleep (excluding WASO) Kappa_sleep_CI_lower | Lower confidence interval of Kappa_sleep Kappa_sleep_CI_lupper | Upper confidence interval of Kappa_sleep Kappa_active | Weighted Cohen's Kappa coefficient calculated based on binary scores of activity (metric ENMO < 50 chosen for now) Kappa_active_CI_lower | Lower confidence interval of Kappa_active Kappa_active_CI_upper | Upper confidence interval of Kappa_active

wadpac/GGIR documentation built on March 5, 2025, 11 p.m.