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

Description Usage Arguments Details Value 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 = NULL, x.cut = TRUE, x.cut.vl = 6000,
  compute.template.idx = FALSE)

`x`	A numeric vector. A time-series to segment pattern occurrences 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 pattern duration times 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 pattern templates below which the algorithm does not identify a pattern occurrence. 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 locations of pattern occurrence beginning and end 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 pattern occurrence beginning and end points 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. The `future` package is used to execute code asynchronously. Default is `FALSE`.
`run.parallel.cores`	An integer scalar. The number of cores to use for parallel execution. Default is `NULL`. If not specified, the number of cores is set to a number of cores available minus 1.
`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 was designed with the aim of performing fast, accurate walking strides segmentation from high-density data collected from wearable accelerometer worn during continuous walking activity.

ADEPT identifies pattern occurrences from a time-series x via maximizing similarity (correlation, covariance etc.) between a time-series x and pattern templates.

Pattern template is scaled to various scale parameters to allow for a potentially better match with pattern occurrences that may change its duration over time. pattern.dur.seq argument defines a grid of a pattern duration to be used in segmentation. Note: the more dense grid may potentially increase segmentation accuracy but may also increase method execution time.
Multiple pattern templates are allowed simultaneously to allow for potentially better match with pattern occurrences that may change its shape over time.

In practice, a pre-defined pattern template may be derived as an empirical pattern, that is, a data-derived vector representing a pattern of interest.

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

tau_i - index of a time-series x where identified pattern occurrence starts,
T_i - duration of identified pattern occurrence, expressed in a time-series x vector length,
sim_i - value of similarity statistic between an identified pattern occurrence and corresponding window of a time-series used in similarity matrix computation; note: this value corresponds to similarity statistic between preliminarily identified pattern occurrence and corresponding window of a time-series used in similarity matrix computation; specifically: if the fine-tune procedure is employed, the similarity value between the final pattern occurrence location and corresponding window of time-series x signal may differ from the value in this table,
template_i - if compute.template.idx equals TRUE: index of pattern template that yielded a similarity matrix value corresponding to an identified pattern occurrence; if compute.template.idx equals FALSE: NA.

## Example 1:
## - no noise in time-series x generation,
## - all pattern occurrences of the same length (101) n time-series x generation.
## Generate signal and template.
x0 <- cos(seq(0, 2 * pi * 10, length.out = 1001))
x  <- x0
template <- x0[1:101]
## Include true pattern occurrence length 101
## (and some redundat for the sake of example).
pattern.dur.seq <- c(90, 100, 101, 102, 110)
## Use segmentPattern function to identify beginnings tau_i and duration T_i
## of pattern occurrences within a signal x.
out <- segmentPattern(x = x,
                      x.fs = 1,
                      template = template,
                      pattern.dur.seq = pattern.dur.seq,
                      similarity.measure = "cor")
out

## Example 2:
## - no noise in time-series x generation,
## - use pattern occurrences of different length in time-series x generation.
## Generate signal and template.
set.seed(1)
## Grid of different true pattern occurrence durations.
s.grid <- sample(60:120, size = 10)
x_block <- cos(seq(0, 2 * pi, length.out = 200))
## Generate signal x that consists of "glued" pattern occurrences of different length
x <- numeric()
for (ss in s.grid){
  x_block_interpolated <- approx(seq(0, 1, length.out = 200),
                                 x_block,
                                 xout = seq(0, 1, length.out = ss))$y
  if (length(x)>0){
    x <- x[-length(x)]
  }
  x <- c(x, x_block_interpolated)
}
## Pattern template used in algorithm
template <- x_block
## Assume dense grid of pattern occurrence duration.
pattern.dur.seq <- 60:120
## Use segmentPattern function to identify beginnings tau_i and duration T_i.
out <- segmentPattern(x = x,
                      x.fs = 1,
                      template = template,
                      pattern.dur.seq = pattern.dur.seq,
                      similarity.measure = "cor")
out

## Example 3(a):
## - add noise in time-series x generation,
## - use pattern occurrences of different length in time-series x generation.
## Generate signal and template
s.grid <- sample(60:120, size = 10)
x_block <- cos(seq(0, 2 * pi, length.out = 200))
set.seed(1)
x <- numeric()
for (ss in s.grid){
  x_block_interpolated <- approx(seq(0, 1, length.out = 200),
                                 x_block,
                                 xout = seq(0, 1, length.out = ss))$y
  if (length(x)>0){
    x <- x[-length(x)]
  }
  x <- c(x, x_block_interpolated)
}
x <- x + rnorm(length(x), sd = 0.3)
pattern.dur.seq <- seq(50, 150, by = 5)
## Pattern template used in algorithm
template <- x_block
## Use segmentPattern function to identify beginnings tau_i and duration T_i:
## - use fine-tune "maxima" procedure.
out <- segmentPattern(x = x,
                      x.fs = 1,
                      template = template,
                      pattern.dur.seq = pattern.dur.seq,
                      similarity.measure = "cor",
                      finetune = "maxima",
                      finetune.maxima.ma.W = 30,
                      finetune.maxima.nbh.W = 120)
out
## Example 3(b):
## Use segmentPattern function to identify beginnings tau_i and duration T_i:
## - use time-series x smooting for ADEPT similarity matrix computation,
## - use fine-tune "maxima" procedure.
out <- segmentPattern(x = x,
                      x.fs = 1,
                      template = template,
                      pattern.dur.seq = pattern.dur.seq,
                      similarity.measure = "cor",
                      x.adept.ma.W = 30,
                      finetune = "maxima",
                      finetune.maxima.ma.W = 30,
                      finetune.maxima.nbh.W = 120)
out