Enhance NotWorn algorithm to work with both count and raw data

[vincentvanhees]

NotWorn algorithms

Fixes #1089 by:

• Revising the "NotWorn" algorithm in both HASIB and HASPT and tested this with both raw- and count-acc data.
• Addressing minor issues encountered in the process such as that ActiGraph count columns are sometimes stored as character which should be numeric.
• In part 4 renamed internal object's column name from "dur" to "overlapGuider" because that is what it represents: 1 if it overlaps, 0 if not.
• In part 4 and when using "NotWorn" as guider than sib is automatically aligned to the guider to ensure the entire night is treated as sleep, also specific 24 shift hour mistakes in numeric timing of sleep in this scenario are accounted for.
• While testing this I also encountered issues with the plot5 function (visualreport) in that it did not correctly use includenightcrit and could not handle missing nights, which I addressed.
• I have now updated the documentation for HASPT.algo and created a cookbook vignette with a paragraph about dealing with study protocols where the accelerometer is not worn. In summary this is best used as shown below:

HASPT.algo = "NotWorn",
HASIB.algo = "NotWorn",
do.imp = FALSE, # Do not impute nonwear because sensor was never worn 24/7
HASPT.ignore.invalid = NA, # Treat nonwear as potential part of guider window
ignorenonwear = FALSE, # Consider nonwear as potential sleep
relyonguider = TRUE, # has minor influence
includenightcrit = 8,
includedaycrit = 8

and fixes #1160

Checklist before merging:

• Existing tests still work (check by running the test suite, e.g. from RStudio).
• Added tests (if you added functionality) or fixed existing test (if you fixed a bug).
• Clean code has been attempted, e.g. intuitive object names and no code redundancy.
• Documentation updated:
  • Function documentation
  • Chapter vignettes for GitHub IO
  • Vignettes for CRAN
• Corresponding issue tagged in PR message. If no issue exist, please create an issue and tag it.
• Updated release notes in inst/NEWS.Rd with a user-readable summary. Please, include references to relevant issues or PR discussions.
• Added your name to the contributors lists in the DESCRIPTION file, if you think you made a significant contribution.
• GGIR parameters were added/removed. If yes, please also complete checklist below.

If NEW GGIR parameter(s) were added then these NEW parameter(s) are :

• documented in man/GGIR.Rd
• included with a default in R/load_params.R
• included with value class check in R/check_params.R
• included in table of vignettes/GGIRParameters.Rmd with references to the GGIR parts the parameter is used in.
• mentioned in NEWS.Rd as NEW parameter

If GGIR parameter(s) were deprecated these parameter(s) are:

• documented as deprecated in man/GGIR.Rd
• removed from R/load_params.R
• removed from R/check_params.R
• removed from table in vignettes/GGIRParameters.Rmd
• mentioned as deprecated parameter in NEWS.Rd
• added to the list in R/extract_params.R with deprecated parameters such that these do not produce warnings when found in old config.csv files.

[vincentvanhees]

@jhmigueles just a heads up that I will ask a group I am helping to check that this works as expected in their data. But I thought you may like to be aware that I have prepared this update as it should hopefully make it easier to use GGIR in studies where the accelerometer was intentionally not worn during the night.

Update: That group has now indicated to me that these updates work well for them.

[jhmigueles]

It works as expected. As we discussed, for the future it would be good handling those nights in which participants ignore the protocol and wear the devices even if they were instructed not to.

[vincentvanhees]

It works as expected. As we discussed, for the future it would be good handling those nights in which participants ignore the protocol and wear the devices even if they were instructed not to.

I have looked at this and have now added the option to specify HASPT.algo as a vector of two. If the first element is "NotWorn" and the second element is either "HDCZA" for wrist or "HorAngle" for hip then this second guider will be used if the sensor is worn for more than 75% of the day (update: this should be night of course). Next, HASIB.algo should be set to what seems most feasible for the wear location, e.g. "vanHees2015". Other than that all stays the same. To document this I updated the CookBook paragraph for this scenario, which is references in GGIR.Rd and parameters vignette.

I ran this on test data and it seems to be working well. Given that this will not affect normal use of GGIR because it only is activated when HASPT.algo has length 2 I think this can now be safely merged. If more enhancements are needed they can be done for the next release.