From 6f44ebfd15e31b99c90b127cdfd8de7a6939c390 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 14:24:45 +0100 Subject: [PATCH 1/8] clarify that header refers to file header, fixes #1237 and expand file header documentation --- vignettes/readmyacccsv.Rmd | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/vignettes/readmyacccsv.Rmd b/vignettes/readmyacccsv.Rmd index e04568b29..16f02cbc1 100644 --- a/vignettes/readmyacccsv.Rmd +++ b/vignettes/readmyacccsv.Rmd @@ -33,7 +33,7 @@ However, the accelerometer manufacturers are proliferating with an increasing nu **How it works:** -Internally GGIR loads csv files with accelerometer data and standardises the output format to make the data compatible with other GGIR functions. Data format standardisation includes unit of measurement, timestamp, header format, and column locations. +Internally GGIR loads csv files with accelerometer data and standardises the output format to make the data compatible with other GGIR functions. Data format standardisation includes unit of measurement, timestamp, file header format, and column locations. # The read.myacc.csv function @@ -59,12 +59,12 @@ Below we present a summary of the available input arguments. Please see the [par ### Arguments for files containing a header {#header} -- `rmc.firstrow.header` - First row (number) of the header. Leave blank (default) if the file does not have a header. +- `rmc.firstrow.header` - First row (number) of the file header. Leave blank (default) if the file does not have a file header. Not to be confused with a one row column header, a file header typically takes up several rows and has one or two columns. If the header has two columns, the first column is assumed to be the header item names and the second column is assumed to have the header item values. If the header has one column then it is assumed that each value contains both the name and the value of the item. - `rmc.header.length` - If file has header, specify header length (numeric). -- `rmc.headername.sf` - If file has a header, row name (character) under which the sample frequency can be found. -- `rmc.headername.sn` - If file has a header, row name (character) under which the serial number can be found. -- `rmc.headername.recordingid` - If file has a header, row name (character) under which the recording ID can be found. -- `rmc.header.structure` - Character used to split the header name from the header value, e.g. ":" or " ". +- `rmc.headername.sf` - If file has a header, row name (character) under which the sample frequency can be found, e.g. "sample_rate". +- `rmc.headername.sn` - If file has a header, row name (character) under which the serial number can be found, e.g. "serial_number". +- `rmc.headername.recordingid` - If file has a header, row name (character) under which the recording ID can be found, e.g. "ID". +- `rmc.header.structure` - Character used to split the header name from the header value, e.g. ":" if a header value would look like "ID: 123" or " " if the ehader value would be like "ID 123". ### Arguments for files including timestamps @@ -110,7 +110,7 @@ dateTime | acc_x | acc_y | acc_z | ambient_temp 1/1/2022 16:48:26.069|-0.42431641|0.4189581|-0.76171875|24 1/1/2022 16:48:26.079|-0.42138672|0.41993469|-0.76513672|24 -This file contains timestamps in the column 1 (formatted as "%d/%m/%Y %H:%M:%OS"), the acceleration signals (in _g_'s) for the x, y, and z axis in the columns 2, 3, and 4, respectively, and temperature information in Celsius in the column 5. Also, this file has no header. +This file contains timestamps in the column 1 (formatted as "%d/%m/%Y %H:%M:%OS"), the acceleration signals (in _g_'s) for the x, y, and z axis in the columns 2, 3, and 4, respectively, and temperature information in Celsius in the column 5. Also, this file has no file header. Before we can use this with GGIR, we first test read this file using the `read.myacc.csv` function directly. From eca5c2871fd8d44ed95b564b38dfed87a18b2227 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 14:46:08 +0100 Subject: [PATCH 2/8] Split large documentation table into shorter tables, fixes #1231 and add section for part 6 --- vignettes/GGIRoutput.Rmd | 92 +++++++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 25 deletions(-) diff --git a/vignettes/GGIRoutput.Rmd b/vignettes/GGIRoutput.Rmd index 96314d663..e10560667 100644 --- a/vignettes/GGIRoutput.Rmd +++ b/vignettes/GGIRoutput.Rmd @@ -56,10 +56,42 @@ Part 2 generates the following output: | nonwear_events_filtered | Total number of nonwear events filtered, only stored when using parameter `nonwearFiltermaxHours` | | calib_err | Calibration error (static estimate) Estimated based on all 'non-movement' periods in the measurement after applying the autocalibration. | | calib_status | Calibration status: Summary statement about the status of the calibration error minimisation | +| n hours ignored at start of meas (if data_masking_strategy=1, 3 or 5) | number of hours ignored at the start of the measurement (if data_masking_strategy = 1) or at the start of the `ndayswindow` (if data_masking_strategy = 3 or 5) A log of decision made in part2.R | +| n hours ignored at end of meas (if data_masking_strategy=1, 3 or 5) | number of hours ignored at the end of the measurement (if data_masking_strategy = 1) or at the end of the `ndayswindow` (if data_masking_strategy = 3 or 5). A log of decision made in part2.R | +| n days of measurement after which all data is ignored (if data_masking_strategy=1) | number of days of measurement after which all data is ignored (if data_masking_strategy = 1, 3 or 5) A log of decision made in part2.R | +| epoch size to which acceleration was averaged (seconds) | A log of decision made in part1.R | +| pdffilenumb | Indicator of in which pdf-file the plot was stored | +| pdfpagecount | Indicator of in which pdf-page the plot was stored | +| data_masking_strategy | A log of the decision made when calling g.impute: value=1 mean ignore specific hours; value=2 mean ignore all data before the first midnight and after the last midnight | + +### Letter codes to indicate aggregation type + +| (Part of) variable name | Description | +|--------------------------|----------------------------------------------| +| `AD_` | All days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over all the available days | +| `WE_` | Weekend days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over weekend days only | +| `WD_` | Week days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over week days only | +| `WWE_` | Weekend days (weighted average) The variable was calculated per day and then averaged over weekend days. Double weekend days are averaged. This is only relevant for experiments that last for more than seven days. | +| `WWD_` | Week days (weighted average) The variable was calculated per day and then averaged over week days. Double week days were averaged. This is only relevant for experiments that last for more than seven days) | + +### Distribution of acceleration + +| (Part of) variable name | Description | +|--------------------------|----------------------------------------------| | ENMO_fullRecordingMean | ENMO is the main summary measure of acceleration. The value presented is the average ENMO over all the available data normalised per 24-hour cycles (diurnal balanced), with invalid data imputed by the average at similar time points on different days of the week. In addition to ENMO it is possible to extract other acceleration metrics (i.e. BFEN, HFEN, HFENplus). We emphasize that it is calculated over the full recording because the alternative is that a variable is only calculated overmeasurement days with sufficient valid hours of data. | | ENMO | (only available if set to true in part1.R) ENMO is the main summary measure of acceleration. The value presented is the average ENMO over all the available data normalised per 24 hour cycles, with invalid data imputed by the average at similar timepoints on different days of the week. In addition to ENMO it is possible to extract other acceleration metrics in part1.R (i.e. BFEN, HFEN, HFENplus) See also [van Hees PLoSONE April 2013](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0061691) for a detailed description and comparison of these techniques. | | pX_A_mg_0-24h_fullRecording | This variable represents the Xth percentile in the distribution of short epoch metric value A of the average day. The average day may not be ideal for describing the distribution. Therefore, the code also extracts the following variable. | | AD_pX_A_mg_0-24h | This variable represents the Xth percentile in the distribution of short epoch metric value A per day averaged across all days. | +| WWD_MVPA_E5S_T100_ENMO | Time spent in moderate-to-vigorous based on 5 second epoch size and an ENMO metric threshold of 100 | +| `WWE_MVPA_E5S_B1M80%_T100_ENMO` | Time spent in moderate-to-vigorous based on a bout criteria of at least 1 minute where 80% or more of the 5 second epochs are expected to meet the threshold criteria of of 100 mg based on acceleration metric ENMO (threshold is specified with parameter `mvpathreshold`) | +| `WE_[100, 150)_mg_0-24h_ENMO` | Time spent between (and including) 100 mg and 150 (excluding 150 itself) between 0 and 24 hours (the full day) using metric ENMO data exclusion data_masking_strategy (value=1, ignore specific hours; value=2, ignore all data before the first midnight and after the last midnight) | +| `_MVPA_E5S_B1M80_T100` | MVPA calculated based on 5 second epoch setting bout duration 1 Minute and inclusion criterion of more than 80 percent. | +| `_ENMO_mg` | ENMO or other metric was first calculated per day and then average according to AD, WD, WWE, WWD | + +### Circadian rhythm: MXLX, IV, and IS + +| (Part of) variable name | Description | +|--------------------------|----------------------------------------------| | L5_A_mg_0-24 | Average of metric A during the least active five\* hours in the day that is the lowest rolling average value of metric A. (\* window size is modifiable by argument `winhr`) | | M5_A_mg_0-24 | Average of metric A during the most active five\* hours in the day that is the lowest rolling average value of metric A. (\* window size is modifiable by argument `winhr`) | | L5hr_A_mg_0-24 | Starting time in hours and fractions of hours of L5_A_mg_0-24, where hours below 12 are incremented with 24 to create a continuous scale throughout the night (e.g. 36 = 6am) in line with numeric timeing of sleep variables in GGIR part 4 output. | @@ -72,23 +104,14 @@ Part 2 generates the following output: | IV | intra daily variability. In contrast to the original paper, we ignore the epoch transitions between the end of a day and the beginning of the next day for the numerator of the equation, this to make it a true measure of intradaily variability. Same note as for IS: The movement count that is derived for this was an attempt to follow the original approach. | | IVIS_windowsize_minutes | Sizes of the windows based on which IV and IS are calculated (note that this is modifiable) | | IVIS_epochsize_seconds | Argument has been deprecated | -| `AD_` | All days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over all the available days | -| `WE_` | Weekend days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over weekend days only | -| `WD_` | Week days (plain average of all available days, no weighting). The variable was calculated per day and then averaged over week days only | -| `WWE_` | Weekend days (weighted average) The variable was calculated per day and then averaged over weekend days. Double weekend days are averaged. This is only relevant for experiments that last for more than seven days. | -| `WWD_` | Week days (weighted average) The variable was calculated per day and then averaged over week days. Double week days were averaged. This is only relevant for experiments that last for more than seven days) | -| WWD_MVPA_E5S_T100_ENMO | Time spent in moderate-to-vigorous based on 5 second epoch size and an ENMO metric threshold of 100 | -| `WWE_MVPA_E5S_B1M80%_T100_ENMO` | Time spent in moderate-to-vigorous based on a bout criteria of at least 1 minute where 80% or more of the 5 second epochs are expected to meet the threshold criteria of of 100 mg based on acceleration metric ENMO (threshold is specified with parameter `mvpathreshold`) | -| `WE_[100, 150)_mg_0-24h_ENMO` | Time spent between (and including) 100 mg and 150 (excluding 150 itself) between 0 and 24 hours (the full day) using metric ENMO data exclusion data_masking_strategy (value=1, ignore specific hours; value=2, ignore all data before the first midnight and after the last midnight) | -| `_MVPA_E5S_B1M80_T100` | MVPA calculated based on 5 second epoch setting bout duration 1 Minute and inclusion criterion of more than 80 percent. | -| `_ENMO_mg` | ENMO or other metric was first calculated per day and then average according to AD, WD, WWE, WWD | -| data exclusion data_masking_strategy | A log of the decision made when calling g.impute: value=1 mean ignore specific hours; value=2 mean ignore all data before the first midnight and after the last midnight | -| n hours ignored at start of meas (if data_masking_strategy=1, 3 or 5) | number of hours ignored at the start of the measurement (if data_masking_strategy = 1) or at the start of the `ndayswindow` (if data_masking_strategy = 3 or 5) A log of decision made in part2.R | -| n hours ignored at end of meas (if data_masking_strategy=1, 3 or 5) | number of hours ignored at the end of the measurement (if data_masking_strategy = 1) or at the end of the `ndayswindow` (if data_masking_strategy = 3 or 5). A log of decision made in part2.R | -| n hours ignored at end of meas (if data_masking_strategy = 1, 3 or 5) | number of days of measurement after which all data is ignored (if data_masking_strategy = 1, 3 or 5) A log of decision made in part2.R | -| epoch size to which acceleration was averaged (seconds) | A log of decision made in part1.R | -| pdffilenumb | Indicator of in which pdf-file the plot was stored | -| pdfpagecount | Indicator of in which pdf-page the plot was stored | +| phi | Indicator of auto-correlation in acceleration time series over multiple days, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | +| SSP | Method for describing time series, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | +| ABI | ABI measures how the activity over the observed period is balanced, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | + +### Circadian rhythm: Cosinor + +| (Part of) variable name | Description | +|--------------------------|----------------------------------------------| | `cosinor_` | Cosinor analysis estimates such as mes, amp, acrophase, and acrotime, as documented in the [ActCR](https://CRAN.R-project.org/package=ActCR) package. | | `cosinorExt_` | Extended Cosinor analysis estimates such as minimum, amp, alpha, beta, acrotime, UpMesor, DownMesor, MESOR, and F_pseudo, as documented in the [ActCR](https://CRAN.R-project.org/package=ActCR) package. | | `cosinorIV` | Cosinor analysis compatible estimate of the Intradaily Variability (IV) | @@ -111,9 +134,6 @@ Part 2 generates the following output: | cosinorExt_ndays | (copied from ActCR documentation) Number of days modeled. | | cosinorExt_F_pseudo | (copied from ActCR documentation) Measure the improvement of the fit obtained by the non-linear estimation of the transformed cosine model | | cosinorExt_R2 | Measure of goodness of fit of the extended cosinor function to the log transformed acceleration signal. Higher values indicate better goodness of fit. | -| phi | Indicator of auto-correlation in acceleration time series over multiple days, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | -| SSP | Method for describing time series, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | -| ABI | ABI measures how the activity over the observed period is balanced, see [chapter 13](https://wadpac.github.io/GGIR/articles/chapter13_CircadianRhythm.html) for details. | ## Day level summary (csv) @@ -328,15 +348,16 @@ For example, the following files will be generated if the threshold configuratio | dur_spt_min | Duration of Sleep Period Time within this day window. | | dur_day_spt_min | Duration this day window, including both waking hours and SPT. | | sleep_efficiency_after_onset | sleep_efficiency_after_onset in part 5 is not the same as in part 4, but calculated as the percentage of sleep within the sleep period time window. The conventional approach is the approach used in part 4. | -| L5TIME | Timing of least active 5hrs, expressed as timestamp in the day | -| M5TIME | Timing of most active 5hrs | -| L5TIME_num, M5TIME_num | Timing of least/most active 5hrs, expressed as hours in the day. Note that L5/M5 timing variables are difficult to average across days because 23:00 and 1:00 would average to noon and not to midnight. So, caution is needed when interpreting person averages. | -| L5VALUE | Acceleration value for least active 5hrs | -| M5VALUE | Acceleration value for most active 5hrs | | `ig_` | All variables related to intensity gradient analysis | | `_gradient` | Gradient from intensity gradient analysis proposed by [Rowlands et al. 2018](https://journals.lww.com/acsm-msse/Fulltext/2018/06000/Beyond_Cut_%20Points__Accelerometer_Metrics_that.25.aspx) for the waking hours window (`_day_`) and for the full window (`_day_spt_`) | | `_intercept` | Intercept from intensity gradient analysis proposed by [Rowlands et al. 2018](https://journals.lww.com/acsm-msse/Fulltext/2018/06000/Beyond_Cut_%20Points__Accelerometer_Metrics_that.25.aspx) for the waking hours window (`_day_`) and for the full window (`_day_spt_`) | | `_rsquared` | r squared from intensity gradient analysis proposed by [Rowlands et al. 2018](https://journals.lww.com/acsm-msse/Fulltext/2018/06000/Beyond_Cut_%20Points__Accelerometer_Metrics_that.25.aspx) for the waking hours window (`_day_`) and for the full window (`_day_spt_`) | + + +### Fragmentation + +| (Term in) variable name | Description | +|--------------------------|----------------------------------------------| | `FRAG_` | All variables related to behavioural fragmentation analysis | | `TP_` | Transition probability| | PA2IN | Physical activity fragments followed by inactivity fragments| @@ -350,6 +371,14 @@ For example, the following files will be generated if the threshold configuratio | alpha | Power law exponent | | `x0.5` | Derived from power law exponent alpha, see [Chastin et al. 201 0](https://doi.org/10.1016/j.gaitpost.2009.09.002) | | `W0.5` | Derived from power law exponent alpha, see [Chastin et al. 201 0](https://doi.org/10.1016/j.gaitpost.2009.09.002) | + + +### Old napping behaviour variables (to be deprecated) + +These variables will be deprecated as napping, if detection is turned on, is now a behavioural category just like all other behaviours. + +| (Term in) variable name | Description | +|--------------------------|----------------------------------------------| | nap_count | Total number of naps, only calculated when argument do.sibreport = TRUE, currently optimised for 3.5-year olds. See function documentation for function `g.part5.classifyNaps` in the [GGIR function documentation (pdf)](https:/CRAN.R-project.org/package=GGIR/GGIR.pdf). | | nap_totalduration | Total nap duration, only calculated when argument do.sibreport = TRUE, currently optimised for 3.5-year old. See function documentation for function `g.part5.classifyNaps` in the [GGIR function documentation (pdf)](https:/CRAN.R-project.org/package=GGIR/GGIR.pdf). | | sibreport_n_items | Only created if `do.sibreport = TRUE`. Number of items in the sibreport | @@ -384,3 +413,16 @@ Most variables in the person level summary are derived from the day level summar | Nvaliddays_AL10F_WE | Number of valid weekend days with at least 10 fragments (5 inactivity or 5 inactive) | | `_wei` | weighted average of weekend and week days, using a 2/5 ratio, see above. | | `_pla` | plain average of all days, see above | + + +# GGIR Part 6 + +Part 6 only stores a person level summary (csv). Most column names overlap with part 5, but are now derived based on the for the full time series only, whereas part 5 only presents these variables per day window which is then aggregated at person level. + +| Variable name | Description | +|--------------------------|----------------------------------------------| +| L5TIME | Timing of least active 5hrs, expressed as timestamp in the day | +| M5TIME | Timing of most active 5hrs | +| L5TIME_num, M5TIME_num | Timing of least/most active 5hrs, expressed as hours in the day. Note that L5/M5 timing variables are difficult to average across days because 23:00 and 1:00 would average to noon and not to midnight. So, caution is needed when interpreting person averages. | +| L5VALUE | Acceleration value for least active 5hrs | +| M5VALUE | Acceleration value for most active 5hrs | From 72d4c2b540b99c24b6bb487d8830f1ca55705aec Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 14:56:52 +0100 Subject: [PATCH 3/8] add documentation for +invalid and for NotWorn #1217 --- man/GGIR.Rd | 10 +++++++--- vignettes/chapter9_SleepFundamentalsGuiders.Rmd | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/man/GGIR.Rd b/man/GGIR.Rd index ce8e91427..f3963b2d0 100644 --- a/man/GGIR.Rd +++ b/man/GGIR.Rd @@ -1227,16 +1227,20 @@ GGIR(mode = 1:5, If \code{TRUE}, invalid time segments are ignored (i.e., they cannot contribute to the guider). If \code{NA}, then invalid time segments are considered to be no movement segments and can contribute to the guider. + Further, the guider name in the output will be shown with "+invalid" + its end, e.g. "HDCZA+invalid", to reflect the \code{NA} setting. When HASPT.algo is "NotWorn", HASPT.ignore.invalid is automatically set to - NA. + NA. } \item{HASIB.algo}{ Character (default = "vanHees2015"). To indicate which algorithm should be used to define the sustained inactivity bouts (i.e., likely sleep). - Options: "vanHees2015", "Sadeh1994", "Galland2012".} - + Options: "vanHees2015", "Sadeh1994", "Galland2012", "NotWorn". See vignette + \href{https://wadpac.github.io/GGIR/articles/chapter8_SleepFundamentalsSibs.html}{chapter 8} + for details.} + \item{Sadeh_axis}{ Character (default = "Y"). To indicate which axis to use for the Sadeh1994 algorithm, and other algortihms diff --git a/vignettes/chapter9_SleepFundamentalsGuiders.Rmd b/vignettes/chapter9_SleepFundamentalsGuiders.Rmd index de9e2e9d9..e877301f3 100644 --- a/vignettes/chapter9_SleepFundamentalsGuiders.Rmd +++ b/vignettes/chapter9_SleepFundamentalsGuiders.Rmd @@ -176,4 +176,4 @@ Depending on study protocol we may want to interpret invalid data (typically non 2. If we want to guider to ignore all invalid segment despite our efforts to impute it, see `HASPT.ignore.invalid = TRUE`. This approach may be helpful for studies where the accelerometer is often not worn during the waking hour of the day. -3. If we want the guider to consider invalid segments as no movement period set parameter `HASPT.ignore.invalid = NA`. This approach may be helpful for studies where the accelerometer is often not worn during the night. +3. If we want the guider to consider invalid segments as no movement period set parameter `HASPT.ignore.invalid = NA`. This approach may be helpful for studies where the accelerometer is often not worn during the night. If this is used, the guider name in the output will be shown with "+invalid" at the end, e.g. "HDCZA+invalid", to reflect that the guider was enhanced. From b32d54019eeb4f4884a09c0590713a2b9dcf0c7d Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 15:03:24 +0100 Subject: [PATCH 4/8] clarify unit of timestamps in read.myacc.csv output --- man/read.myacc.csv.Rd | 5 +++-- vignettes/readmyacccsv.Rmd | 5 ++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/man/read.myacc.csv.Rd b/man/read.myacc.csv.Rd index 6daff06fb..043d33e1d 100644 --- a/man/read.myacc.csv.Rd +++ b/man/read.myacc.csv.Rd @@ -180,8 +180,9 @@ except rmc.file, rmc.nrow, and rmc.skip as input for function \link{GGIR} or \link{g.part1} and also specify argument rmc.noise, which is not part of this function but needed to tell GGIR what noise level to expect in the data. The rmc.noise is taken from the params_rawdata object if not explicitly specified by user. } \value{ - List with objects data holding the time series of acceleration, and - header if it was available in the orignal file. + List with objects data holding the time series of acceleration with among others + a column named "time" that holds the time expressed in seconds since 1-1-1970, and + header if a header was present in the input file. } \examples{ diff --git a/vignettes/readmyacccsv.Rmd b/vignettes/readmyacccsv.Rmd index 16f02cbc1..284d2d262 100644 --- a/vignettes/readmyacccsv.Rmd +++ b/vignettes/readmyacccsv.Rmd @@ -116,7 +116,7 @@ Before we can use this with GGIR, we first test read this file using the `read.m ```{R,eval=FALSE} library(GGIR) -read.myacc.csv(rmc.file = "C:/mystudy/mydata/datafile.csv", +data = read.myacc.csv(rmc.file = "C:/mystudy/mydata/datafile.csv", rmc.nrow = Inf, rmc.skip = 0, rmc.dec = ".", @@ -132,6 +132,9 @@ read.myacc.csv(rmc.file = "C:/mystudy/mydata/datafile.csv", rmc.sf = 100) ``` +The object data is a list with a data.frame name data and a header. +The time column in the data.frame represents timestamps expressed in seconds since 1-1-1970. + ## Example using the shell function If the `rmc.firstrow.acc` argument is defined within the `GGIR` function, then the data will be read through `read.myacc.csv`. GGIR needs the user to specify in which row starts the accelerometer data within the csv, so this argument must be always explicitly specified by the user. Thus, a call to the `GGIR` including the rmc arguments would look as follows (note that the `rmc.file`, `rmc.nrow`, and `rmc.skip` arguments will not be used by `GGIR` as these arguments are already defined by `datadir`, `strategy`, and [header](#header) arguments, respectively). From ae25f655b24b41762bc337564c160fa60832436c Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 15:14:02 +0100 Subject: [PATCH 5/8] Expand documentation on part5 time series object #1046 --- vignettes/chapter12_TimeUseAnalysis.Rmd | 32 ++++++++++++++----------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/vignettes/chapter12_TimeUseAnalysis.Rmd b/vignettes/chapter12_TimeUseAnalysis.Rmd index 8102b6628..df536c303 100644 --- a/vignettes/chapter12_TimeUseAnalysis.Rmd +++ b/vignettes/chapter12_TimeUseAnalysis.Rmd @@ -92,22 +92,26 @@ Note that the time series exported in GGIR part 5 only includes the acceleration - `save_ms5raw_format` is a character string to specify how data should be stored: either "csv" (default) or "RData". Only used if save_ms5rawlevels=TRUE. - `save_ms5raw_without_invalid` is Boolean to indicate whether to remove invalid days from the time series output files. Only used if save_ms5rawlevels=TRUE. -| Column name | Description | +| Column name | Description | |-------------------------|-----------------------------------------------| -| timenum | Time stamp in UTC time format (i.e., seconds since 1970-01-01). To convert timenum to time stamp format, you need to specify your desired time zone, e.g., `as.POSIXct(mdat$timenum, tz = "Europe/London")`. | -| ACC | Average acceleration metric selected by `acc.metric`, default = "ENMO". | -| SleepPeriodTime | Is 1 if SPT is detected, 0 if not. Note that this refers to the combined usage of guider and detected sustained inactivity bouts (rest periods). | -| invalidepoch | Is 1 if epoch was detect as invalid (e.g. non-wear), 0 if not. | -| guider | Number to indicate what guider type was used, where 1=sleeplog, 2=HDCZA, 3=swetwindow, 4=L512, 5=HorAngle, 6=NotWorn | -| window | Numeric indicator of the analysis window in the recording. If timewindow = "MM" then these correspond to calendar days, if timewindow = "WW" then these correspond to which wakingup-wakingup window in the recording, if timewindow = "OO" then these correspond to which sleeponset-sleeponset window in the recording. So, in a recording of one week you may find window numbers 1, 2, 3, 4, 5 and 6. | +| timenum | Time stamp in UTC time format (i.e., seconds since 1970-01-01). To convert timenum to time stamp format, you need to specify your desired time zone, e.g., `as.POSIXct(mdat$timenum, tz = "Europe/London")`. | +| ACC | Average acceleration metric selected by `acc.metric`, default = "ENMO". | +| SleepPeriodTime | Is 1 if SPT is detected, 0 if not. Note that this refers to the combined usage of guider and detected sustained inactivity bouts (rest periods). | +| invalidepoch | Is 1 if epoch was detect as invalid (e.g. non-wear), 0 if not. | +| guider | Number to indicate what guider type was used, where 1=sleeplog, 2=HDCZA, 3=swetwindow, 4=L512, 5=HorAngle, 6=NotWorn | +| window | Numeric indicator of the analysis window in the recording. If timewindow = "MM" then these correspond to calendar days, if timewindow = "WW" then these correspond to which wakingup-wakingup window in the recording, if timewindow = "OO" then these correspond to which sleeponset-sleeponset window in the recording. So, in a recording of one week you may find window numbers 1, 2, 3, 4, 5 and 6. | | class_id | The behavioural class codes are documented in the exported csv file meta/ms5outraw/behaviouralcodes.csv. Class codes above class 8 will be analysis specific, because it depends on the number time variants of the bouts used. For example, if you look at MVPA lasting 1-10, 10-20, 30-40 then all of them will have their own class_id. In behaviouralcodes.csv you will find a column with class_names which match the behavioural classes as reported in the part 5 report. | -| invalid_fullwindow | Percentage of the window (see above) that represents invalid data, included to ease filtering the timeseries based on whether windows are valid or not. | -| invalid_sleepperiod | Percentage of SPT within the current window that represents invalid data. | -| invalid_wakinghours | Percentage of waking hours within the current window that represents invalid data. | -| timestamp | Time stamp derived from converting the column timenum, only available if `save_ms5raw_format = TRUE`. | -| angle | anglez by default. If `sensor.location = "hip"` or `HASPT.algo = "HorAngle"` then angle represents the angle for the longitudinal axis as provided by argument longitudinal_axis or estimated if no angle was provided. If more angles were extracted in part 1 then these will be add with their letter appended. | -| lightpeak | If lux sensor data is available in the data file then it was summarised at an epoch length defined by the second value of parameter `windowsizes` (defaults to 900 seconds = 15 minutes), to add this value to the time series it is interpolated, so the original time resolution is not necessarily reflected in this column. | -| temperature | If temperature was available in the data file then it was summarised at an epoch length defined by the second value of parameter `windowsizes` (defaults to 900 seconds = 15 minutes), to add this value to the time series it is interpolated, so the original time resolution is not necessarily reflected in this column. | +| sibdetection | 1 if sustained inactivity bout was detect, 2 if nap was detected | +| lightpeak | If lux sensor data is available in the data file then it was summarised at an epoch length defined by the second value of parameter `windowsizes` (defaults to 900 seconds = 15 minutes), to add this value to the time series it is interpolated, so the original time resolution is not necessarily reflected in this column. | +| selfreported | Factor to indicator what behaviour was reported via sleep diary, if no behaviour was reported value is NA | +| angle | anglez by default. If `sensor.location = "hip"` or `HASPT.algo = "HorAngle"` then angle represents the angle for the longitudinal axis as provided by argument longitudinal_axis or estimated if no angle was provided. If more angles were extracted in part 1 then these will be add with their letter appended. | +| step_count | Only stored when external algortihm for step detection is used. | +| diaryImputationCode | Code stored in the advanced format sleeplog that will be shown in the visualisation. | +| temperature | If temperature was available in the data file then it was summarised at an epoch length defined by the second value of parameter `windowsizes` (defaults to 900 seconds = 15 minutes), to add this value to the time series it is interpolated, so the original time resolution is not necessarily reflected in this column. | +| invalid_fullwindow | Percentage of the window (see above) that represents invalid data, included to ease filtering the timeseries based on whether windows are valid or not. | +| invalid_sleepperiod | Percentage of SPT within the current window that represents invalid data. | +| invalid_wakinghours | Percentage of waking hours within the current window that represents invalid data. | +| timestamp | Time stamp derived from converting the column timenum, only available if `save_ms5raw_format = TRUE`. | ## Key arguments From d51e9572b3235131fcb865a54e3fdbdedf2efc4e Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 15:25:55 +0100 Subject: [PATCH 6/8] add suggestion to calculate volume of behaviour --- vignettes/chapter12_TimeUseAnalysis.Rmd | 3 +++ 1 file changed, 3 insertions(+) diff --git a/vignettes/chapter12_TimeUseAnalysis.Rmd b/vignettes/chapter12_TimeUseAnalysis.Rmd index df536c303..b0b850eda 100644 --- a/vignettes/chapter12_TimeUseAnalysis.Rmd +++ b/vignettes/chapter12_TimeUseAnalysis.Rmd @@ -63,6 +63,9 @@ GGIR provides the following metrics over the time windows calculated, i.e., full - Number of bouts: Number of bouts per behavioural class. - Fragmentation: The fragmentation metrics as discussed in the previous chapter. Here no distinction is made between bouted or unbouted behavour. Note that fragmentation classes sometimes group multiple intensity levels, e.g. the fragmentation of physical activity reflects the fragmentation of LIPA and MVPA combined relative to Inactive time. +On a side note - If you multiply Acceleration by Duration for a given class, and by that combine the information from both variables, you would arrive at a volume measure of behaviour. This is similar to the construct of calories over time. I think this would be a much richer way of describing the data as opposed to the conventional approach that only looks at either time spent per behavioural class or average acceleration in an entire day. + + ### Complementary variables If your primary interest is on sleep research then we recommend you to work with the GGIR part 4 reports. However, for those who want to look at interactions between behaviour and sleep, GGIR part 5 reports include sleep estimates as used for the part 5 analysis. Note that in part 5 the criteria for sleep estimate inclusion are different than for part 4. In part 5 we are happy with any estimate, even if the accelerometer was not worn during the night. From 7ff6c1c6376727ab9e351e8c445e3c10d66f3043 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 15:44:28 +0100 Subject: [PATCH 7/8] prepare new release --- DESCRIPTION | 4 ++-- NEWS.md | 2 +- man/GGIR-package.Rd | 4 ++-- vignettes/chapter12_TimeUseAnalysis.Rmd | 1 - 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index cd05e0c6a..c128d6b92 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: GGIR Type: Package Title: Raw Accelerometer Data Analysis -Version: 3.1-7 -Date: 2024-11-25 +Version: 3.1-8 +Date: 2024-12-11 Authors@R: c(person("Vincent T","van Hees",role=c("aut","cre"), email="v.vanhees@accelting.com"), person("Jairo H","Migueles",role="aut", diff --git a/NEWS.md b/NEWS.md index f1152c190..ef2b06643 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# CHANGES IN GGIR VERSION 3.1-? +# CHANGES IN GGIR VERSION 3.1-8 - Part 4: Parameter sib_must_fully_overlap_with_TimeInBed added to control whether sib should overlap fully with the start and/or end of time in bed to be considered sleep (default TRUE), this is consistent with functionality in the past. #1223 diff --git a/man/GGIR-package.Rd b/man/GGIR-package.Rd index 5b905a37b..d06765359 100755 --- a/man/GGIR-package.Rd +++ b/man/GGIR-package.Rd @@ -21,8 +21,8 @@ \tabular{ll}{ Package: \tab GGIR\cr Type: \tab Package\cr - Version: \tab 3.1-7\cr - Date: \tab 2024-11-25\cr + Version: \tab 3.1-8\cr + Date: \tab 2024-12-11\cr License: \tab Apache License (== 2.0)\cr Discussion group: \tab https://groups.google.com/forum/#!forum/rpackageggir\cr } diff --git a/vignettes/chapter12_TimeUseAnalysis.Rmd b/vignettes/chapter12_TimeUseAnalysis.Rmd index b0b850eda..37887e4a8 100644 --- a/vignettes/chapter12_TimeUseAnalysis.Rmd +++ b/vignettes/chapter12_TimeUseAnalysis.Rmd @@ -65,7 +65,6 @@ GGIR provides the following metrics over the time windows calculated, i.e., full On a side note - If you multiply Acceleration by Duration for a given class, and by that combine the information from both variables, you would arrive at a volume measure of behaviour. This is similar to the construct of calories over time. I think this would be a much richer way of describing the data as opposed to the conventional approach that only looks at either time spent per behavioural class or average acceleration in an entire day. - ### Complementary variables If your primary interest is on sleep research then we recommend you to work with the GGIR part 4 reports. However, for those who want to look at interactions between behaviour and sleep, GGIR part 5 reports include sleep estimates as used for the part 5 analysis. Note that in part 5 the criteria for sleep estimate inclusion are different than for part 4. In part 5 we are happy with any estimate, even if the accelerometer was not worn during the night. From af84a53832671dd7acb388eb2298c7a660a47b83 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Wed, 11 Dec 2024 16:20:08 +0100 Subject: [PATCH 8/8] rebuild vignette in preparation for GitHub only 3.1-8 release --- docs/404.html | 6 +- docs/CODE_OF_CONDUCT.html | 4 +- docs/CONTRIBUTING.html | 4 +- docs/LICENSE-text.html | 4 +- docs/RELEASE_CYCLE.html | 4 +- docs/articles/Cookbook.html | 6 +- docs/articles/CutPoints.html | 6 +- docs/articles/ExternalFunction.html | 6 +- docs/articles/GGIR.html | 6 +- docs/articles/GGIRParameters.html | 286 +- docs/articles/GGIRoutput.html | 491 +- docs/articles/HouseHoldCoanalysis.html | 6 +- docs/articles/TutorialDaySegmentAnalyses.html | 6 +- docs/articles/chapter0_Contributing.html | 6 +- docs/articles/chapter0_GetStarted.html | 6 +- docs/articles/chapter0_Installation.html | 6 +- docs/articles/chapter0_Support.html | 6 +- docs/articles/chapter10_SleepAnalysis.html | 14 +- .../chapter11_DescribingDataCutPoints.html | 6 +- docs/articles/chapter12_TimeUseAnalysis.html | 74 +- docs/articles/chapter13_CircadianRhythm.html | 6 +- .../chapter14_BehaviouralFragmentation.html | 6 +- docs/articles/chapter1_WhatIsGGIR.html | 6 +- docs/articles/chapter2_Pipeline.html | 6 +- docs/articles/chapter3_QualityAssessment.html | 6 +- docs/articles/chapter4_AccMetrics.html | 6 +- docs/articles/chapter5_StudyProtocol.html | 6 +- docs/articles/chapter6_DataImputation.html | 6 +- ...er7_DescribingDataWithoutKnowingSleep.html | 6 +- .../chapter8_SleepFundamentalsSibs.html | 6 +- .../chapter9_SleepFundamentalsGuiders.html | 23 +- docs/articles/chapterInProgress.html | 6 +- docs/articles/index.html | 4 +- docs/articles/readmyacccsv.html | 37 +- docs/authors.html | 8 +- docs/deps/data-deps.txt | 4 +- docs/deps/font-awesome-6.5.2/css/all.css | 8028 +++++++++++++++++ docs/deps/font-awesome-6.5.2/css/all.min.css | 9 + docs/deps/font-awesome-6.5.2/css/v4-shims.css | 2194 +++++ .../font-awesome-6.5.2/css/v4-shims.min.css | 6 + .../webfonts/fa-brands-400.ttf | Bin 0 -> 209128 bytes .../webfonts/fa-brands-400.woff2 | Bin 0 -> 117852 bytes .../webfonts/fa-regular-400.ttf | Bin 0 -> 67860 bytes .../webfonts/fa-regular-400.woff2 | Bin 0 -> 25392 bytes .../webfonts/fa-solid-900.ttf | Bin 0 -> 420332 bytes .../webfonts/fa-solid-900.woff2 | Bin 0 -> 156400 bytes .../webfonts/fa-v4compatibility.ttf | Bin 0 -> 10832 bytes .../webfonts/fa-v4compatibility.woff2 | Bin 0 -> 4792 bytes docs/index.html | 6 +- docs/news/index.html | 14 +- docs/pkgdown.yml | 2 +- docs/search.json | 2 +- docs/sitemap.xml | 2 + 53 files changed, 10959 insertions(+), 399 deletions(-) create mode 100644 docs/deps/font-awesome-6.5.2/css/all.css create mode 100644 docs/deps/font-awesome-6.5.2/css/all.min.css create mode 100644 docs/deps/font-awesome-6.5.2/css/v4-shims.css create mode 100644 docs/deps/font-awesome-6.5.2/css/v4-shims.min.css create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-brands-400.ttf create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-brands-400.woff2 create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-regular-400.ttf create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-regular-400.woff2 create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-solid-900.ttf create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-solid-900.woff2 create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-v4compatibility.ttf create mode 100644 docs/deps/font-awesome-6.5.2/webfonts/fa-v4compatibility.woff2 diff --git a/docs/404.html b/docs/404.html index 3d469ca59..0ca86fc83 100644 --- a/docs/404.html +++ b/docs/404.html @@ -8,8 +8,8 @@ Page not found (404) • GGIR - - + + @@ -21,7 +21,7 @@ GGIR - 3.1-7 + 3.1-8