Embedding of external functions

[vincentvanhees]

The plan is to allow for specification of an external function to be applied to the raw accelerometer data, and to integrate the output of that function in the GGIR output. For example, an external algorithm for sleep detection, step detection, cycling detection, etc. The advantages include:

• Avoids embedding all these algorithms in GGIR itself.
• Gives freedom to developer to develope their code and models independent of GGIR.
• Open to dependencies in other programming languages, e.g. Matlab or Python.
• Allows for new features to be developed as external function first, and if they are well tested we can include them eventually as a GGIR function if external developers agrees.

Plan for now:

• [x] Create development branch.
• [x] Add function object as extra argument to g.shell.GGIR, g.part1, g.getmeta.
• [x] Make g.getmeta apply this function argument to blocks of raw accelerometer data.
• [x] Define clear API requirements for this function
• [x] Adapt function such that it can include a loaded model, by which we do not have to load the model with every new block of data. So, rather than providing a function, we expect the user to provide a function and a separately loaded model, which is then fed into the function by GGIR.
• [x] Include functionality to resample the input data if external function requires this.
• [x] Include functionality to resample the output data if external function does not do this.
• [x] Make getmeta truncate the data if necessary to be convenient for external function, e.g. integer number of window sizes.
• [x] Tidy up g.getmeta by moving all the new code to a separate function + write unit tests.
• [x] Update specific documention about myfun object (g.getmeta, g.part1, g.shell.GGIR)
• [x] Make g.getmeta add the external function output to the part1 milestone data.
• [x] Integrate external function produced variable names, such that features can be used in parts 2, 3, 4 and 5
• [x] Add examples of how to use this with Python code (reticulate package).
• [x] Create vignette with overview of examples of R function (count calculation) and Python function (dominant frequency calculation).
• [x] Address failing OSx-specific travis build, related to using python in Rmarkdown.
• [x] Add option to pass (numeric) timestamps to external function together with data object.
• [x] Add quality checks on myfun object, and on output. Maybe worth defining an explicit class for it.
• [x] Enable interpolation, e.g. 30 second classification to 5 second output
• [x] Embed output in part2 report (events)
• [x] Expand vignette tutorial with more information about output, update date.
• [x] Put example vignette pdf in repo

Embed sleep/nonwear classification output LRAP project in part 2 and 4 reports:

• [x] Embed output in part 4 report (sleep): Write part 3 function that extracts sleep from part 1 and formats it in a way that part 4 can handle.
• [ ] Fuse non-wear with conventional non-wear in part 2. If shorter than 1 hour rely on new classification, otherwise use old one.

[vincentvanhees]

Current thoughts on S3 class object for the input data:

rawacc <- list(acc = data.frame(accx=x, accy=y, accz=z),
    original_sample_rate = 100,
    current_sample_rate = 50,
    unit="g")
class(rawacc) <- "rawacc"

• Object has no timestamps, because I assuming that algorithms do not need timestamps.
• I am including both the original and the current sample rate of the data, because algorithms may be sample rate specific which requires resampling. However, to preserve knowledge about the original sample rate we also store this information.
• Unit, because algorithms may be measurement unit specific.

[vincentvanhees]

An alternative approach could be to define a class around the external function, rather than around the data.

mytool = list(FUN, model_coefficients = c(), expected_sample_rate=50, expected_unit="g", minlength = 5, outputres = 5) class(mytool) = "externalTool"

Which makes it clear for the external function developer what to provide.

Object components:

• FUN, the function, which could be a function object (e.g. Python function with R reticulate package).
• (optional) _modelcoefficients: loaded model coefficients, to avoid having to load these for every block of data. This may especially be valuable when working with larger models.
• minlength: the minimum expected data length. Based on this GGIR will provide an multitude of these windows to the external function.
• outputres: is the resolution in seconds of the external function output

[m-patterson]

Hi Vincent, thanks for all the work and documentation on this. I'm a bit stuck in the 'applyExtFunction.R' script, as there is a call to a 'resample' function. Does this function come from library, or should it be included in the .R files with GGIR? IT doesn't seem to be in the _issue241ExtrnlFuncEmbedding branch?

IT is inside the resampleAcc function, which is defined inside applyExtFunction.R:

'Resample' seems to be getting called somehow, as this is the error that I am stuck at:

[vincentvanhees]

Hi Matt, resample is a c++ function from the src directory, which needs to be compiled with (only if you are working with the code in development mode):

library("Rcpp")
pathR = "/home/GGIR"
sourceCpp(paste0(pathR,"/src/numUnpack.cpp"))
sourceCpp(paste0(pathR,"/src/resample.cpp"))

I am currently trying to fix some issues in this part of the code. so please hold on. I am hopeful that I can commit my changes in the upcoming hour or so. This relates robustness to incorret use of myfun$timestamp value.

[m-patterson]

sounds good, thanks!

[vincentvanhees]

I am done for the day, the above commit was what I wanted to do. To check I did not break anything I run the counts example and the dominant frequency example from the vignette and they still seem to work.

[m-patterson]

Thanks for those updates Vincent, it seems to be working well now. For, the step count algorithm, the user will want to have the number of steps taken each day as well as the total number of steps taken over the entire recording? Do you think you will set this up to auto generate in the output, or will there be some sort of myfun setting to indicate how the final output should be shown?

Great work on this tool, it is a very powerful way to quickly apply different algorithms to long term activity recordings!

[vincentvanhees]

Thanks Matt for letting me know. Yes, I think some input will be needed to make it generically useful.

Possible types of features:

• event count (e.g. steps, falls, ...)
• labels (e.g. activity types)
• scalar (e.g. likelihood that someone fell, energy expenditure estimate, ...)
• multivariate scalars (e.g. some scalar calculated per accelerometer axis, frequency spectrum, ...)

Possible types of aggregating per day and per recording:

• average
• sum

Possible desired ways of reporting:

• Part 2
• Use as alternative sleep detection in parts 3 and 4
• Part 5

Next, the myfun object may then need to carry a choice for each of these three categories. For example, to be named: outputtype = "eventcount", how2aggregate4report = "sum", and GGIRreport = 2. Can you think of any additional types or decisions that need to be accounted for to be future proof?

[m-patterson]

I think that is a pretty thorough list of how algorithm creators will want to categorize outputs.

There might be a need to only include results from either day or night or else to separate day results and night results. Maybe this would take more time to implement, so could be something to do down the road. For the steps algorithm I don't need it.

[vincentvanhees]

Can you send me an example milestone file with the step count in it? I could use that to develop the automated incorporation of total steps per day in the csv report.

[vincentvanhees]

Closing this issue as it seems to be working for a variety of use cases.

Most recent addition is the use of an external function for sleep detection and embedding in all sleep and part 5 reports. I have added a pdf copy of the tutorial to the repo https://github.com/wadpac/GGIR/tree/GGIR2.0/pdf_vignettes_for_github_only

Inclusion in new release: I merged all progress with branch GGIR2.0, which I aim to merge with the master branch in the upcoming weeks and that will be release 2.0-0 (GitHub only). Next, I will encourage the GGIR e-mail list (google group) to start testing it, followed by 2.1-0 a couple of weeks later on GitHUb and on CRAN.

New ideas for improvement can be collected in a new issue, for now I think it is good enough.