SSmonoexponential: Self-starting monoexponential model

In mnirs: Muscle Near-Infrared Spectroscopy Processing and Analysis

Self-starting monoexponential model

Description

Creates initial coefficient estimates for a selfStart wrapper around monoexponential(), for use with stats::nls(). Supports both the 3-parameter (A, B, tau) and 4-parameter (A, B, tau, TD) forms; arity is inferred from the formula passed to stats::nls().

Usage

SSmonoexponential(t, A, B, tau, 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.
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

• 3-parameter: x ~ SSmonoexponential(t, A, B, tau)

• 4-parameter: x ~ SSmonoexponential(t, A, B, tau, TD)

The 3-parameter form is recommended for small samples or when no obvious time delay is expected, as it converges more reliably. stats::nls() reads the free parameters from the formula right-hand side, so omitting TD incurs no degrees-of-freedom penalty.

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

The model function returns the analytic gradient 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 ~ SSmonoexponential(t, A = 0, B, tau) fixes the baseline at A = 0. 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

monoexponential(), analyse_kinetics(), stats::nls(), stats::selfStart(), stats::SSasymp()

Examples

## create an exponential curve with random noise
set.seed(13)
t <- 1:60
x <- monoexponential(t, A = 10, B = 100, tau = 8, TD = 15) +
    rnorm(length(t), 0, 3)
data <- data.frame(t, x)

## 4-parameter fit
model4 <- nls(x ~ SSmonoexponential(t, A, B, tau, TD), data = data)
summary(model4)

## 3-parameter fit on the same data
model3 <- nls(x ~ SSmonoexponential(t, A, B, tau), data = data)
summary(model3)

## fix the baseline `A` at a known value
model_fixed <- nls(x ~ SSmonoexponential(t, A = 10, B, tau, TD), data = data)
summary(model_fixed)

y4 <- predict(model4, data)
y3 <- predict(model3, data)


    if (requireNamespace("ggplot2", quietly = TRUE)) {
        ggplot2::ggplot(data, ggplot2::aes(t, x)) +
            theme_mnirs() +
            ggplot2::geom_point() +
            ggplot2::geom_line(ggplot2::aes(y = y4, colour = "4-param")) +
            ggplot2::geom_line(ggplot2::aes(y = y3, colour = "3-param"))
    }

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