Skip to content

Commit

Permalink
Merge pull request #1241 from wadpac/prepare_318_release
Browse files Browse the repository at this point in the history 
Prepare 3.1-8 release
  • Loading branch information
@vincentvanhees
vincentvanhees authored Dec 11, 2024
2 parents ca82700 + 7ff6c1c commit 2161e70
Show file tree
Hide file tree
Showing 9 changed files with 114 additions and 58 deletions.
4 changes: 2 additions & 2 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
@@ -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="[email protected]"),
person("Jairo H","Migueles",role="aut",
Expand Down
2 changes: 1 addition & 1 deletion NEWS.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 2 additions & 2 deletions man/GGIR-package.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down
10 changes: 7 additions & 3 deletions man/GGIR.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions man/read.myacc.csv.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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{

Expand Down
92 changes: 67 additions & 25 deletions vignettes/GGIRoutput.Rmd
View file

Large diffs are not rendered by default.

34 changes: 20 additions & 14 deletions vignettes/chapter12_TimeUseAnalysis.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,8 @@ 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.
Expand Down Expand Up @@ -92,22 +94,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

Expand Down
2 changes: 1 addition & 1 deletion vignettes/chapter9_SleepFundamentalsGuiders.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading

0 comments on commit 2161e70

Please sign in to comment.