SSexponential_drift: Self-starting exponential-drift model

In mnirs: Muscle Near-Infrared Spectroscopy Processing and Analysis

Self-starting exponential-drift model

Description

Creates initial coefficient estimates for a selfStart wrapper around exponential_drift(), for use with stats::nls(). Supports both the 5-parameter (A, B, tau, slope_B, drift_fraction) and 6-parameter forms adding a time delay TD; arity is inferred from the formula passed to stats::nls().

Usage

SSexponential_drift(t, A, B, tau, slope_B, drift_fraction, TD)

Arguments

t	A numeric vector of the predictor variable (time).
A	A numeric parameter for the starting baseline of the response variable.
B	A numeric parameter for the ending asymptote of the response variable.
tau	A numeric parameter for the time constant (\tau) of the exponential response, in units of the predictor variable t.
slope_B	A numeric parameter for the linear drift rate dx/dt of the secondary phase, in response units per unit of the predictor variable t.
drift_fraction	A numeric fraction of the primary amplitude B - A in ⁠(0.5, 1)⁠ at which the linear drift begins, where the primary response reaches A + drift_fraction * (B - A).
TD	A numeric parameter for the time delay before the onset of the exponential response, in units of the predictor variable t. If NULL (default), a 3-parameter model without time delay is used.

Details

Model formulas

• 5-parameter: x ~ SSexponential_drift(t, A, B, tau, slope_B, drift_fraction)

• 6-parameter: x ~ SSexponential_drift(t, A, B, tau, slope_B, drift_fraction, TD)

The hinge at the drift onset TD - tau * log(1 - drift_fraction) is not differentiable, so algorithm = "port" with tau (and TD) bounded non-negative and control = nls.control(warnOnly = TRUE) is recommended.

Starting estimates are profiled on a coarse grid of tau (and TD) with A, B, and slope_B solved by least squares at each grid point, keeping the residual-minimising start.

The model function returns the analytic gradient (one-sided at the hinge) for the free parameters as a "gradient" attribute, so stats::nls() does not resort to stats::numericDeriv(). stats::predict() on a fitted model carries the attribute; drop it with as.vector().

Fixing parameters

Any parameter may be held constant by writing a value in place of its name in the formula, e.g. x ~ SSexponential_drift(t, A, B, tau, slope_B, drift_fraction = 0.95) holds the drift onset at 95% of the amplitude (TD + 3 * tau). Fixed parameters are excluded from estimation and are not returned by stats::coef().

Value

A numeric vector of predicted values the same length as the predictor variable t.

See Also

exponential_drift(), analyse_kinetics(), stats::nls(), stats::selfStart(), SSmonoexponential(), SSbiexponential()

Examples

## create an exponential curve with late linear drift and random noise
set.seed(13)
t <- 1:180
x <- exponential_drift(
    t, A = 10, B = 100, tau = 12,
    slope_B = -0.5, drift_fraction = 0.98, TD = 15
) + rnorm(length(t), 0, 2)
data <- data.frame(t, x)

## 6-parameter fit with the drift onset held at 98% of the amplitude
model <- nls(
    x ~ SSexponential_drift(
        t, A, B, tau, slope_B, drift_fraction = 0.98, TD
    ),
    data = data,
    algorithm = "port",
    lower = c(-Inf, -Inf, 0, -Inf, 0),
    control = nls.control(warnOnly = TRUE)
)
summary(model)

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