g.part5_analyseSegment_ExtFunType: Analyse External Function Type Classifications in GGIR Part 5

Description

Calculates summary metrics for epoch-by-epoch categorical classifications generated by external functions with reporttype = "type" in GGIR Part 5.

For each classification type, the function calculates time spent in the type, time spent outside defined bouts (unbt), time spent in defined bouts, total time, mean acceleration, number of blocks, and number of bouts. Metrics are calculated separately for sleep period time (SPT) and daytime.

External function type classifications are represented internally as the number of seconds in each epoch assigned to each classification. Bout definitions are represented by the corresponding binary matrices generated during the type bout detection step.

Usage

g.part5_analyseSegment_ExtFunType(ts, sse, TOLEVELS, TLEVELS, Tnames, myfun,
                                    ws3new, dsummary, ds_names, si, fi)

Value

A list containing:

dsummary: The updated Part 5 summary matrix containing the external function type metrics.
ds_names: The updated vector of summary variable names.
fi: The updated output column index.

Arguments

ts: Data frame containing the Part 5 epoch-level time series, including acceleration, day/SPT indicators, and external function type information.
sse: Integer vector containing the indices of the epochs belonging to the current segment.
TOLEVELS: Named list with one matrix per external-function output column. Each matrix contains the seconds assigned to each classification level, with epochs in rows and levels in columns.
TLEVELS: Nested list keyed by external-function output column and classification level. Each leaf is a binary matrix containing one row per bout-duration definition and one column per epoch.
Tnames: Character vector containing the names corresponding to the type bout definitions in TLEVELS.
myfun: List defining the external function. The function uses the colnames element to identify the external classification variable.
ws3new: Numeric value specifying the epoch duration in seconds.
dsummary: Matrix containing the Part 5 summary results. The function adds the external function type metrics to this matrix.
ds_names: Character vector containing the names of the Part 5 summary variables. The function appends the names of the external function type metrics.
si: Integer identifying the current row of dsummary to which the results are written.
fi: Integer identifying the current output column position in dsummary and ds_names.

Author

Vincent T van Hees <[email protected]> Jairo H Migueles <[email protected]>

Details

For each external function type, metrics are calculated separately for SPT and daytime.

The following metrics are generated:

Time spent outside any defined bout (unbt).
Time spent in each defined bout-duration category.
Total time spent in the classification type.
Mean acceleration during epochs classified as the type.
Number of blocks, defined as contiguous periods in which the type is present.
Number of bouts for each defined bout-duration category.

A block is based on the original epoch-level type classification and is therefore independent of the bout-duration criteria. Bout counts and bout durations are based on the bout masks stored in TLEVELS.