segmentPattern: Pattern Segmentation From a Time-series via ADEPT
In adept: Adaptive Empirical Pattern Transformation

Description Usage Arguments Details Value References Examples

View source: R/segmentPattern.R

Segment pattern from a time-series x via Adaptive Empirical Pattern Transformation (ADEPT).

segmentPattern(
  x,
  x.fs,
  template,
  pattern.dur.seq,
  similarity.measure = "cov",
  similarity.measure.thresh = 0,
  x.adept.ma.W = NULL,
  finetune = NULL,
  finetune.maxima.ma.W = NULL,
  finetune.maxima.nbh.W = NULL,
  run.parallel = FALSE,
  run.parallel.cores = 1L,
  x.cut = TRUE,
  x.cut.vl = 6000,
  compute.template.idx = FALSE
)

`x`	A numeric vector. A time-series to segment pattern from.
`x.fs`	A numeric scalar. Frequency at which a time-series `x` is collected, expressed in a number of observations per second.
`template`	A list of numeric vectors, or a numeric vector. Each vector represents a distinct pattern template used in segmentation.
`pattern.dur.seq`	A numeric vector. A grid of potential pattern durations used in segmentation. Expressed in seconds. See: Details.
`similarity.measure`	A character scalar. Statistic used to compute similarity between a time-series `x` and pattern templates. Currently supported values: `"cov"` - covariance, `"cor"` - correlation, Default is `"cov"`.
`similarity.measure.thresh`	A numeric scalar. Threshold of minimal similarity value between a time-series `x` and a template below which the algorithm does not identify a pattern occurrence from `x`. Default is `0`.
`x.adept.ma.W`	A numeric scalar. A length of a window used in moving average smoothing of a time-series `x` for similarity matrix computation. Expressed in seconds. Default is `NULL` (no smoothing applied).
`finetune`	A character scalar. A type of fine-tuning procedure employed in segmentation. Defaults to `NULL` (no fine-tuning procedure employed). Currently supported values: `"maxima"` - tunes preliminarily identified beginning and end of a pattern so as they correspond to local maxima of time-series `x` (or smoothed version of `x`) found within neighbourhoods of preliminary locations.
`finetune.maxima.ma.W`	A numeric scalar. A length of a window used in moving average smoothing of a time-series `x` in `"maxima"` fine-tuning procedure. Expressed in seconds. Default is `NULL` (no smoothing applied).
`finetune.maxima.nbh.W`	A numeric scalar. A length of the two neighborhoods centered at preliminarily identified beginning and end of a pattern within which we search for local maxima of `x` (or smoothed version of `x`) in `"maxima"` fine-tuning procedure. Expressed in seconds. Default is `NULL`. Note: if the length provided corresponds to an even number of `x` vector indices, it will be rounded down so as the corresponding number of vector indices is its closest odd number.
`run.parallel`	A logical scalar. Whether or not to use parallel execution in the algorithm with `parallel` package. Default is `FALSE`. DOES NOT WORK ON WINDOWS.
`run.parallel.cores`	An integer scalar. The number of cores to use for parallel execution. Defaults to 1L (no parallel). DOES NOT WORK ON WINDOWS.
`x.cut`	A logical scalar. Whether or not to use time optimization procedure in which a time-series `x` is cut into parts and segmentation is performed for each part of `x` separately. Recommended for a time-series `x` of vector length above 30,000. Default is `TRUE`.
`x.cut.vl`	An integer scalar. Defines a vector length of parts that `x` vector is cut into during the execution time optimization procedure. Default is `6000` (recommended).
`compute.template.idx`	A logical scalar. Whether or not to compute and return information about which of the provided pattern templates yielded a similarity matrix value that corresponds to an identified pattern occurrence. Setting to `TRUE` may increase computation time. Default is `FALSE`.

Function implements Adaptive Empirical Pattern Transformation (ADEPT) method for pattern segmentation from a time-series x. ADEPT is optimized to perform fast, accurate walking strides segmentation from high-density data collected with a wearable accelerometer during walking.

ADEPT identifies patterns in a time-series x via maximization of chosen similarity statistic (correlation, covariance, etc.) between a time-series x and a pattern template(s). It accounts for variability in both (1) pattern duration and (2) pattern shape.

A data.frame with segmentation results. Each row describes one identified pattern occurrence:

tau_i - index of x where pattern starts,
T_i - pattern duration, expressed in x vector length,
sim_i - similarity between a pattern and x; note: if "maxima" fine-tune and/or x smoothing is employed, the similarity value between the final segmented pattern and a template may differ from the value in this table,
template_i - if compute.template.idx equals TRUE: index of a template best matched to x; if compute.template.idx equals FALSE: NA.

Karas, M., Straczkiewicz, M., Fadel, W., Harezlak, J., Crainiceanu, C.M., Urbanek, J.K. (2019). Adaptive empirical pattern transformation (ADEPT) with application to walking stride segmentation. Biostatistics. https://doi.org/10.1093/biostatistics/kxz033

## Example 1: Simulate a time-series `x`. Assume that
## - `x` is collected at a frequency of 100 Hz,
## - there is one shape of pattern present within `x`,
## - each pattern lasts 1 second,
## - there is no noise in the collected data.
true.pattern <- cos(seq(0, 2 * pi, length.out = 100))
x <- c(true.pattern[1], replicate(10, true.pattern[-1]))
## Segment pattern from x.
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = true.pattern,
  pattern.dur.seq = c(0.9, 0.95, 1.03, 1.1),
  similarity.measure = "cor",
  compute.template.idx = TRUE)
out
## Segment pattern from x. Now assume a grid of potential pattern duratios
## contains true pattern duration
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = true.pattern,
  pattern.dur.seq = c(0.9, 0.95, 1, 1.03, 1.1),
  similarity.measure = "cor",
  compute.template.idx = TRUE)
out

## Example 2: Simulate a time-series `x`. Assume that
## - `x` is collected at a frequency of 100 Hz,
## - there are two shapes of pattern present within `x`,
## - patterns have various duration,
## - there is no noise in the collected data.
true.pattern.1 <- cos(seq(0, 2 * pi, length.out = 200))
true.pattern.2 <- true.pattern.1
true.pattern.2[70:130] <- 2 * true.pattern.2[min(70:130)] + abs(true.pattern.2[70:130])
x <- numeric()
for (vl in seq(70, 130, by = 10)){
  true.pattern.1.s <- approx(
    seq(0, 1, length.out = 200),
    true.pattern.1, xout = seq(0, 1, length.out = vl))$y
  true.pattern.2.s <- approx(
    seq(0, 1, length.out = 200),
    true.pattern.2, xout = seq(0, 1, length.out = vl))$y
  x <- c(x, true.pattern.1.s[-1], true.pattern.2.s[-1])
  if (vl == 70) x <- c(true.pattern.1.s[1], x)
}
## Segment pattern from x. Use a `template` object consisting of both
## true patterns used in `x` simulation.
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = list(true.pattern.1, true.pattern.2),
  pattern.dur.seq = 60:130 * 0.01,
  similarity.measure = "cor",
  compute.template.idx = TRUE)
out

## Example 3: Simulate a time-series `x`. Assume that
## - `x` is collected at a frequency of 100 Hz,
## - there are two shapes of a pattern present within `x`,
## - patterns have various duration,
## - there is noise in the collected data.
set.seed(1)
x <- x + rnorm(length(x), sd = 0.5)
## Segment pattern from x.
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = list(true.pattern.1, true.pattern.2),
  pattern.dur.seq =  60:130 * 0.01,
  similarity.measure = "cor",
  compute.template.idx = TRUE)
out
## Segment pattern from x. Use `x.adept.ma.W` to define a length of a smoothing
## window to smooth `x` for similarity matrix computation.
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = list(true.pattern.1, true.pattern.2),
  pattern.dur.seq =  60:130 * 0.01,
  similarity.measure = "cor",
  x.adept.ma.W = 0.1,
  compute.template.idx = TRUE)
out
## Segment pattern from x. Use `x.adept.ma.W` to define a length of a smoothing
## window to smooth `x` for similarity matrix computation. Employ a fine-tuning
## procedure for stride identification.
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = list(true.pattern.1, true.pattern.2),
  pattern.dur.seq =  60:130 * 0.01,
  similarity.measure = "cor",
  x.adept.ma.W = 0.1,
  finetune = "maxima",
  finetune.maxima.nbh.W = 0.3,
  compute.template.idx = TRUE)
out
## Segment pattern from x. Employ a fine-tuning procedure for stride
## identification. Smooth `x` for both similarity matrix computation
## (set `x.adept.ma.W = 0.1`) and for  fine-tune peak detection procedure
## (set `finetune.maxima.nbh.W = 0.3`).
out <- segmentPattern(
  x = x,
  x.fs = 100,
  template = list(true.pattern.1, true.pattern.2),
  pattern.dur.seq =  60:130 * 0.01,
  similarity.measure = "cor",
  x.adept.ma.W = 0.1,
  finetune = "maxima",
  finetune.maxima.nbh.W = 0.3,
  compute.template.idx = TRUE)
out