Skip to contents

Calculate and retain one-step-ahead residuals

Source: R/osa.R
add_osa_residuals.Rd

Calculate observation diagnostics at fitted parameter values and return a fit containing the results. Use the returned object in vis_tam() or residuals(). No model is refitted, and the supplied fit is not modified.

Usage

add_osa_residuals(fit, method = "oneStepGaussianOffMode", ...)

Arguments

fit

A fitted tam_fit.

method

One algorithm supported by RTMB::oneStepPredict(): "oneStepGaussianOffMode" (default), "oneStepGaussian", "oneStepGeneric", "fullGaussian", or "cdf".

...

Named computation controls for RTMB::oneStepPredict(), such as trace, parallel, subset, conditional, or splineApprox. subset and conditional index included log observations in likelihood order. Their unrequested rows retain missing residuals.

Value

A tam_fit with osa_res and osa_method columns in $obs_pred, and calculation metadata in $osa and the observation-table attributes.

Details

The algorithms use different predictive approximations and can differ numerically. oneStepGeneric uses numerical integration and can be expensive. The existing off-mode Gaussian calculation remains the default. Log observations have a continuous Gaussian likelihood, so discrete = FALSE is supplied unless explicitly overridden. Method-dependent upstream defaults, including reverse, are retained. When SAM is also loaded, parallel OSA calculations use the existing sequential safeguard.

Temporary RTMB objectives protect the fitted parameters, uncertainty and objective state. Only OSA columns and metadata are added to a copy of the existing observation tables; row order, confidence intervals, units and custom columns are preserved. Metadata in fit$osa records the method, requested and effective settings, and observation coverage. Failed requested calculations remain missing and are recorded separately from unrequested observations. A calculation error returns no partially updated fit.

See also

residuals.tam_fit(), tidy_obs_pred()

Examples

if (FALSE) { # \dontrun{
fit_osa <- add_osa_residuals(fit, method = "oneStepGeneric", trace = FALSE)
residuals(fit_osa, type = "osa")
vis_tam(fit_osa)
} # }