fit_mm: Fit a Variance-Aware Michaelis-Menten Model

In inferMM: Variance-Aware Michaelis-Menten Estimation and Inference

Fit a Variance-Aware Michaelis-Menten Model

Description

Estimate Michaelis-Menten parameters under a constant or concentration-dependent working variance specification.

Usage

fit_mm(x, y,
  variance = c("log", "sqrt", "cuberoot", "constant", "power", "auto"),
  power = NULL, power_selection = c("quasi_aic", "quasi_bic"),
  power_grid = default_power_grid(), interval_level = 0.95,
  km_bounds = NULL, allow_zero_substrate = TRUE)

## S3 method for class 'fit_mm'
coef(object, ...)

## S3 method for class 'fit_mm'
vcov(object, ...)

## S3 method for class 'fit_mm'
confint(object, parm = c("Vmax", "Km"),
  level = object$interval_level, method = c("wald", "bootstrap"),
  B = 399L, bootstrap_type = c("wild", "pairs"),
  bootstrap_ci = c("studentized", "basic", "percentile"),
  wild_weights = c("mammen", "rademacher"), seed = NULL, ...)

## S3 method for class 'fit_mm'
print(x, digits = max(3L, getOption("digits") - 2L), ...)

## S3 method for class 'fit_mm'
summary(object, level = object$interval_level,
  method = c("wald", "bootstrap"), B = 399L,
  bootstrap_type = c("wild", "pairs"),
  bootstrap_ci = c("studentized", "basic", "percentile"),
  wild_weights = c("mammen", "rademacher"), seed = NULL, ...)

## S3 method for class 'summary.fit_mm'
print(x,
  digits = max(3L, getOption("digits") - 2L), ...)

## S3 method for class 'fit_mm'
predict(object, newdata = NULL, se.fit = FALSE,
  interval = c("none", "confidence", "prediction"),
  level = object$interval_level, ...)

## S3 method for class 'fit_mm'
plot(x, interval = TRUE,
  interval_type = c("prediction", "confidence"),
  level = x$interval_level, n_points = 200,
  xlab = "Substrate concentration", ylab = "Reaction velocity",
  main = NULL, pch = 19, col.points = "#1f78b4",
  col.line = "#222222",
  col.band = grDevices::adjustcolor("#9ecae1", alpha.f = 0.45), ...)

Arguments

x	Numeric vector of substrate concentrations. For the plot method, a fitted object of class "fit_mm".
y	Numeric vector of observed reaction velocities.
variance	A built-in working variance model name or a fixed, vectorized function of concentration returning strictly positive values. Use variance_function to attach a label to a custom function. Use "power" with a fixed exponent or "auto" to compare log(S + 1) against a grid of power functions.
power	Optional exponent used when variance = "power".
power_selection	Criterion used when variance = "auto": "quasi_aic" or "quasi_bic".
power_grid	Candidate exponents considered when variance = "auto".
interval_level	Confidence level used for interval estimation.
km_bounds	Numeric vector of length two giving the search bounds for K_m.
allow_zero_substrate	Logical; if FALSE, substrate concentrations must be strictly positive.
object	A fitted "fit_mm" object.
parm	Parameter names for confint().
level	Confidence level for intervals.
method	Interval construction method: "wald" or "bootstrap".
B	Number of bootstrap resamples when method = "bootstrap".
bootstrap_type	Bootstrap scheme: "wild" or "pairs".
bootstrap_ci	Bootstrap interval calibration used when method = "bootstrap": "studentized", "basic", or "percentile".
wild_weights	Wild-bootstrap multipliers used when bootstrap_type = "wild": "mammen" or "rademacher".
seed	Deprecated and ignored. Call set.seed() before bootstrap-based summaries or intervals if reproducibility is needed.
digits	Number of printed digits.
newdata	Optional numeric vector of new substrate concentrations.
se.fit	Logical; if TRUE, return standard errors for mean predictions.
interval	Prediction type: none, confidence, or prediction.
interval_type	For the plot method, draw either a prediction or confidence band when interval = TRUE.
n_points	Number of grid points used for plotting the fitted curve.
xlab, ylab, main, pch, col.points, col.line, col.band	Graphical parameters for the plot method.
...	Additional arguments passed to S3 methods.

Details

Built-in working variance models are "constant", "log", "sqrt", "cuberoot", "power", and "auto". All single-curve fits use the Michaelis-Menten profile-score estimator from the companion methodology work, with the constant-variance case treated as the special case h(S) \equiv 1. Confidence intervals can be computed either from the default asymptotic Wald approximation or from a bootstrap refitting scheme. The bootstrap option supports percentile, basic, and studentized calibration, together with wild or pairs resampling. The default printed summaries suppress interval output when the fitted curve has fewer than 20 observations or fewer than 6 distinct substrate concentrations; in that setting, confint() remains available as an explicit sensitivity analysis tool and issues a warning. The automatic option compares log(S + 1) with a user-supplied grid of S^p working variance functions and keeps the best fit according to quasi-AIC or quasi-BIC.

The profile search examines sign-changing brackets on a 400-point log grid and verifies the mean score equations after solving. The diagnostic projects the K_m score direction off the eliminated V_{\max} direction and standardizes its residual inner product by both weighted norms; the V_{\max} equation is also checked. The maximum absolute standardized score must not exceed 10^{-7}. If no bracketed root is verified, minimization of the squared standardized profile score supplies additional candidates, not automatically accepted estimates. Among detected positive interior roots passing these checks, the smallest weighted residual sum of squares determines the fitted root. A finite grid does not guarantee finding every root or a global minimum.

Candidates within 10^{-6} of either log search bound are rejected, as are non-positive or non-finite parameters and numerically zero residual variance. The mean information is scaled by its gradient-column magnitudes; a reciprocal condition number below 10^{-12} stops covariance calculation. No ridge term is added to obtain the single-curve Wald covariance. These checks do not guarantee identifiability or accurate finite-sample coverage.

Profile validation errors have class inferMM_profile_error, also inheriting from inferMM_convergence_error. They identify the failure stage, reason, search bounds, score norm, tolerance and candidate count, with information conditioning where relevant. No fit or confidence intervals are returned on these errors. Use tryCatch() to inspect the condition. Automatic variance selection records unsuccessful candidates in variance_candidate_table using success = 0 and an error_message; they cannot be selected. If every candidate fails, selection stops. Screening and grouped workflows likewise record failures without reporting estimates or intervals for those curves. The profile pilot of fit_mm_moments uses the same root-validation checks; the later joint higher-moment solve has its own diagnostics. These new single-curve checks do not replace the separate clustered solver.

A custom function specifies h(S) in \operatorname{Var}(Y\mid S)=\gamma h(S); see variance_function for its input/output contract. Only K_m requires numerical search, followed by closed-form updates for V_{\max} and \gamma. The stored variance_fun is reused for new-data prediction and wild or pairs bootstrap refitting. Custom shapes are normalized internally for numerical scaling, without clipping; the reported scale is \gamma for the original supplied shape. Multiplying the shape by a positive constant changes \gamma inversely, not the fitted variance. Extremely ill-scaled shapes can still produce numerical errors.

Custom shape parameters are not estimated. Wald covariance and working-Gaussian prediction bands condition on the fixed supplied shape. Quasi-AIC and quasi-BIC count three fitted parameters (V_{\max}, K_m, \gamma); they do not account for coefficients fitted externally inside a custom function or for variance-model selection uncertainty. Free parameters, shapes depending on the fitted mean parameters, and data-adaptive variance-function estimation are outside this interface. The feature does not implement conditional third/fourth moment estimation or imply an efficiency gain over identically weighted nonlinear least squares. Prediction bands retain the existing working-normal approximation rather than estimating skewed predictive quantiles.

Value

The main fitting function returns an object of class "fit_mm". Its convergence component records the standardized score norm, tolerance, search method, candidate roots, and scaled information condition. predict() returns either a numeric vector or a data frame containing prediction intervals.

Examples

one_curve <- subset(sdl_demo, enzyme == "1111")

fit <- fit_mm(
  x = one_curve$s_uM,
  y = one_curve$v_uM_per_min,
  variance = "sqrt"
)

fit_power <- fit_mm(
  x = one_curve$s_uM,
  y = one_curve$v_uM_per_min,
  variance = "power",
  power = 0.4
)

fit_auto <- fit_mm(
  x = one_curve$s_uM,
  y = one_curve$v_uM_per_min,
  variance = "auto",
  power_selection = "quasi_aic"
)

coef(fit)
confint(fit)
set.seed(1)
confint(
  fit,
  method = "bootstrap",
  B = 99,
  bootstrap_ci = "studentized",
  wild_weights = "mammen"
)
head(predict(fit, newdata = seq(0, 80, length.out = 6), interval = "prediction"))

h <- variance_function(function(S) 1 + S / 20,
                       label = "Var = gamma (1 + S/20)")
fit_custom <- fit_mm(one_curve$s_uM, one_curve$v_uM_per_min, variance = h)
summary(fit_custom)
confint(fit_custom)
head(predict(fit_custom, newdata = c(0, 10, 40), interval = "prediction"))


plot(fit)
report_mm(fit, interval_type = "confidence")

inferMM documentation built on Oct. 30, 2026, 9:06 a.m.