peak_slope: Peak linear slope

In mnirs: Muscle Near-Infrared Spectroscopy Processing and Analysis

Peak linear slope

Description

Identify the maximum positive or negative local linear slope of a numeric vector using rolling least-squares regression, and return the regression parameters of the peak window. Vector-level companion to analyse_kinetics() with method = "peak_slope".

Usage

peak_slope(
  x,
  t = seq_along(x),
  width = NULL,
  span = NULL,
  align = c("centre", "left", "right"),
  direction = c("auto", "positive", "negative"),
  partial = FALSE,
  na.rm = FALSE,
  verbose = TRUE,
  ...
)

Arguments

x	A numeric vector of the response variable.
t	An optional numeric vector of the predictor variable (e.g. time). Default is seq_along(x).
width	An integer defining the local window in number of samples around idx in which to perform the operation, according to align.
span	A numeric value defining the local window time span around idx in which to perform the operation, according to align. In units of time_channel or t.
align	Window alignment as "centre"/"center" (the default), "left", or "right". Where "left" is forward looking, and "right" is backward looking from the current sample.
direction	A character string specifying the response direction "positive", or "negative", or detect with "auto" (default). See Details.
partial	Logical; default is FALSE, only returns values where a full window of valid (non-NA) samples are available. If TRUE, ignores NA and processes available valid samples (see Details).
na.rm	Logical; default is FALSE, propagates any NAs to the returned vector. If TRUE, ignores NAs and processes available valid samples within the local window. May return errors or warnings. (see Details).
verbose	Logical. TRUE (default) will display, and FALSE will silence warnings and information messages helpful for troubleshooting. Global default can be set via options(mnirs.verbose = FALSE).
...	Additional arguments.

Details

A semi-parametric approach to estimate the steepest local rate of change of a signal. In NIRS signals this can be interpreted as the moment of greatest mismatch between oxygen delivery and extraction. Rolling slopes are computed by rolling_slope(), and the peak window is refit with stats::lm() to return the regression parameters.

Rolling window

The local window is defined by either width (number of samples) or span (time span in units of t); one of either width or span must be specified.

• width with align = "centre" spans ⁠[idx - floor((width - 1) / 2), idx + floor(width / 2)]⁠. Even width values bias alignment to "left", placing the unequal sample forward of idx.

• span with align = "centre" spans ⁠[t - span / 2, t + span / 2]⁠.

Direction

direction is detected automatically by default as either "positive" (upward) or "negative" (downward) response, from the dominant excursion of x above or below its initial baseline (the median of the earliest samples). When tied, the greater absolute rolling slope decides. The greatest local slope in that direction is returned, and direction can be overwritten manually.

Partial windows

partial = FALSE (the default) requires the complete number of samples specified by width or span, and returns NA for any window with fewer samples. partial = TRUE allows computation with as few as 2 valid samples. These windows, such as at edge conditions, are more sensitive to noise and should be used with caution.

Missing values

na.rm = FALSE (the default) propagates any NA in a window to the returned slope. na.rm = TRUE ignores NAs and computes the slope from the remaining valid samples.

Value

A named list containing:

slope	The peak slope value in units of x / t.
intercept	The y-intercept of the peak local regression line.
y	The predicted value of x at the peak slope index.
t	The value of t at the peak slope index.
idx	The integer index of the peak slope window.
fitted	A numeric vector of predicted values spanning the peak slope window.
window_idx	An integer vector of indices spanning the peak slope window.
model	The lm object fit to the peak slope window.

See Also

analyse_kinetics(), rolling_slope(), response_time(), monoexponential()

Examples

x <- c(1, 3, 2, 5, 8, 7, 9, 12, 11, 15, 14, 17, 18)

## peak positive slope over a 5-sample window
peak_slope(x, width = 5)

## peak negative slope of the reversed signal
peak_slope(rev(x), width = 5)

mnirs documentation built on Sept. 13, 2026, 1:06 a.m.