Skip to contents

Spikes

Source: R/spct.spikes.R
spikes.Rd

Function that returns a subset of an R object with observations corresponding to spikes. Spikes are values in spectra that are unusually high compared to neighbors. They are usually individual values or very short runs of similar "unusual" values.

Usage

spikes(
  x,
  height.threshold,
  z.threshold,
  k,
  spike.direction,
  na.rm,
  max.spike.width,
  ...
)

# Default S3 method
spikes(
  x,
  height.threshold = NA,
  z.threshold = NA,
  k = NA,
  spike.direction = NA,
  na.rm = FALSE,
  max.spike.width = NA,
  ...
)

# S3 method for class 'numeric'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...
)

# S3 method for class 'data.frame'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  y.var.name = NULL,
  var.name = y.var.name
)

# S3 method for class 'generic_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  var.name = NULL,
  ...
)

# S3 method for class 'source_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...
)

# S3 method for class 'response_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...
)

# S3 method for class 'filter_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  filter.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  ...
)

# S3 method for class 'reflector_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...
)

# S3 method for class 'solute_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...
)

# S3 method for class 'cps_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  var.name = "cps",
  ...
)

# S3 method for class 'raw_spct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  var.name = "counts",
  ...
)

# S3 method for class 'generic_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  var.name = NULL,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'source_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'response_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'filter_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  filter.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'reflector_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'solute_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'cps_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  var.name = "cps",
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'raw_mspct'
spikes(
  x,
  height.threshold = 10,
  z.threshold = 5,
  k = 20,
  spike.direction = "both",
  na.rm = FALSE,
  max.spike.width = NA,
  ...,
  var.name = "counts",
  .parallel = FALSE,
  .paropts = NULL
)

Arguments

x

numeric vector containing the data.

height.threshold

numeric The minimum height of spikes expressed relative to the median amplitude of the baseline local variation of x.

z.threshold

numeric Modified local \(Z\) values larger than z.threshold are detected as boundaries of spikes.

k

integer width of median window used for smoothing; must be odd

spike.direction

character Controls the direction of spikes to be detected. Accepted arguments are "up", "down", "both".

na.rm

logical indicating whether NA values should be stripped before searching for spikes.

max.spike.width

integer The width of the widest spike to be detected, NA puts no limit.

...

ignored

var.name, y.var.name

character Name of column where to look for spikes.

unit.out

character One of "energy" or "photon"

filter.qty

character One of "transmittance" or "absorbance"

.parallel

if TRUE, apply function in parallel, using parallel backend provided by foreach

.paropts

a list of additional options passed into the foreach function when parallel computation is enabled. This is important if (for example) your code relies on external data or packages: use the .export and .packages arguments to supply them so that all cluster nodes have the correct environment set up for computing.

Value

A subset of the object passed as argument to x with rows corresponding to spikes.

Spike detection

Spikes are detected based on a modified \(Z\) score calculated from the differenced spectrum. The \(Z\) threshold used should be adjusted to the characteristics of the input and desired sensitivity. The lower the threshold the more stringent the test becomes, with shorter spikes being detected.

The algorithms assume a consistent step size for the underlying independent variable, e.g., wavelength or time, and should not be applied if the data do not fulfil this assumption, at least approximately. As find_spkikes() operates on a single vector, checking this remains the responsibility of calling functions or methods such as spikes() and despike().

The algorithm uses running differences to detect abrupt changes in value, compared to an estimate of the baseline variation of the differences, approximating a baseline \(Z\) from MAD and a baseline value from the median differences. Currently, a single estimate of MAD is used but running medians, when possible, as baseline. This comparison detects running differences that are unusually large, in most cases signalling a transition between values near the baseline and far from it, in both directions.

Transitions into- and out of spikes are distinguished based on the median of the non-differenced values, as a descriptor of the data baseline. As for the median of the differences, a running median is used when possible.

This function thus detects the start and end of each spike, and distinguishes upward and downward spikes.

k is the width in number of observations of the window used for running median smoothing to extract the baseline. A value several times the width of the broader spike but narrow enough to track broader peaks needs to be manually set in most cases.

With na.rm = TRUE, NA values are omitted before searching for spikes and set to 0L in the returned vector.

If all spikes are guaranteed to be one observation-wide and either going up or down from the baseline, it is possible to detect them based purely on the z.threshold by passing height.threshold = NA and either spike.direction = "up" or spike.direction = "down", which ensures very fast computation.

Parameters of the algorithm need to be adjusted depending on the data, so inspection of returned values is needed together with adjustment by trial and error of suitable values for z.threshold, height.threshold, and k.

Parameter max.spike.width searches for too wide spikes in the output of the algorithms described above and ignores them. This is possibly redundant, but maintained for partial backwards compatibility.

See also

See find_spikes() for locating spikes in a vector, despike() for replacement of spikes by interpolation in spectra and and replace_bad_pixs() for replacing by interpolation missing or bad values in a vector.

Other peaks and valleys functions: find_peaks(), find_spikes(), get_peaks(), peaks(), replace_bad_pixs(), valleys(), wls_at_target()

Examples

spikes(sun.spct)
#> Object: source_spct [6 x 2]
#> Wavelength range 382-760 nm, step 1-329 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 6 × 2
#>   w.length s.e.irrad
#>      <dbl>     <dbl>
#> 1      382     0.323
#> 2      393     0.242
#> 3      394     0.298
#> 4      397     0.254
#> 5      431     0.414
#> 6      760     0.179