See also complementary vignettes on: General introduction to GGIR, Day segment analyses, GGIR parameters, Embedding external functions (pdf), and Reading ad-hoc csv file formats.

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

1 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.

2 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)

3 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.

3.1 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.

3.2 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.

4 Output variables

4.1 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

4.2 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