analyze_bouts: Analyze bouts of various physical behaviors

In paulhibbing/PBpatterns: Analyze Patterns of Physical Behavior

Analyze bouts of various physical behaviors

Description

analyze_bouts is a universal function that serves as a wrapper for several bout classifying methods (included below in the usage section).

Usage

analyze_bouts(
  x,
  target,
  method = c("rle_standard", "CRIB", "Troiano_MVPA", "Ostendorf_MVPA", "SB_summary",
    "MVPA_summary"),
  ...
)

crib_bouts(
  x,
  target,
  target_buffer_mins,
  longest_allowable_interruption_mins = Inf,
  required_percent = 100,
  max_n_interruptions = Inf,
  minimum_bout_duration_minutes = 0,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

ostendorf_mvpa_bouts(
  x,
  target,
  required_percent = 80,
  termination_min = 3,
  minimum_bout_duration_minutes = 10,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

sb_summary_bouts(
  x,
  target,
  minimum_bout_duration_minutes = 0,
  probs = c(0.1, 0.2, 0.25, seq(0.3, 0.7, 0.1), 0.75, 0.8, 0.9),
  patterns = TRUE,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

mvpa_summary_bouts(
  x,
  target,
  minimum_bout_duration_minutes = 0,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

rle_standard_bouts(
  x,
  target,
  minimum_bout_duration_minutes = 0,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

troiano_mvpa_bouts(
  x,
  target,
  activation_window_min = 10,
  activation_min = 8,
  termination_min = 3,
  minimum_bout_duration_minutes = 10,
  epoch_length_sec,
  is_wear = TRUE,
  valid_indices = NULL
)

Arguments

x	factor. Epoch-by-epoch behavior classifications, e.g., SB, LPA, and MVPA
target	the level of x for which to examine bouts
method	character. The bout classifying method to use. See details.
...	arguments passed to the method function being wrapped (see usage section, above)
target_buffer_mins	numeric (CRIB). Maximum separation (in minutes) between runs of target, beyond which they will not be clustered together
longest_allowable_interruption_mins	numeric (CRIB). The maximum length (in minutes) for any single interruption in a valid bout
required_percent	numeric (1-100; CRIB and Ostendorf_MVPA). The minimum percentage of the full bout period that must be spent engaging in the target behavior. Stated differently, this threshold stipulates that interruptions can compose no more than 100-required_percent of the bout
max_n_interruptions	numeric (CRIB). The maximum number of interruption events that are allowed before a bout will be considered invalid
minimum_bout_duration_minutes	[optional argument available for all methods] a numeric filtering criterion. Bouts will be discarded if the length (in epochs) is less than this amount
epoch_length_sec	[REQUIRED argument for all methods] a numeric scalar giving the epoch length of x, in seconds
is_wear	[optional argument available for all methods] a logical scalar (or vector, as long as its length equals the length of x), indicating whether each epoch corresponds to wear time. For length 1, the provided value is assigned for all epochs. Thus, the default value of TRUE reflects assumption that all epochs are wear epochs
valid_indices	[optional argument available for all methods] a numeric/integer/logical vector specifying which elements of x occurred on a valid day. The default (NULL) assumes all elements are valid
termination_min	numeric (Troiano_MVPA and Ostendorf_MVPA). Number of consecutive non-target minutes required to terminate a bout
probs	quantile values to return (SB_summary)
patterns	logical (SB_summary). Append the output with extra sedentary pattern variables?
activation_window_min	numeric (Troiano_MVPA). Size of window (in minutes) to use when searching for a bout activation
activation_min	numeric (Troiano_MVPA). Number of minutes in activation_window that must equal target for an activation to be detected

Details

Currently, the following methods are supported: "rle_standard", "CRIB", "Troiano_MVPA", "Ostendorf_MVPA", "SB_summary", and "MVPA_summary". More can easily be added over time, including more *_summary methods or others that are designed for specific behaviors or activity monitors.

CRIB

For help understanding output when method == "CRIB", see CRIB_output

*_summary

These functions return a one-row data frame with bout summary information, rather than a data frame with one row for each individual bout

See Also

Troiano et al. (2008) Ostendorf et al. (2018) expand_bouts plot.bouts

Examples

data(example_data, package = "PBpatterns")

x <- cut(
  example_data$PAXINTEN,
  c(-Inf, 101, 760, Inf),
  c("SB", "LPA", "MVPA"),
  right = FALSE
)

analyze_bouts(x, "MVPA", "rle_standard", epoch_length_sec = 60)[1:6, ]

analyze_bouts(x, "MVPA", "CRIB", 20, 5, 50, 3, 10, 60)

analyze_bouts(x, "MVPA", "Troiano_MVPA", epoch_length_sec = 60)
analyze_bouts(x, "MVPA", "Ostendorf_MVPA", epoch_length_sec = 60)

analyze_bouts(x, "SB", "SB_summary", is_wear = TRUE, epoch_length_sec = 60)

analyze_bouts(x, "MVPA", "MVPA_summary", is_wear = TRUE, epoch_length_sec = 60)

paulhibbing/PBpatterns documentation built on Feb. 17, 2024, 5:34 a.m.