Calculate a sequence of refitted year-effect contrasts

influ_steps() calculates and stores the indices needed for plot_step(). These are focus/year-effect contrasts, not area-integrated abundance indices. Adding a spatial process changes the estimated year effects by refitting the model; its field is not added to the plotted index.

Usage

influ_steps(
  fits,
  year = NULL,
  steps = NULL,
  refit = FALSE,
  labels = NULL,
  component = NULL,
  probs = c(0.025, 0.975),
  keep_fits = FALSE,
  refit_args = list(),
  year_term = NULL,
  ...
)

# S3 method for class 'influ_steps'
print(x, ...)

# S3 method for class 'influ_steps'
summary(object, ...)

Arguments

fits: One supported fitted model, an influ_diag, or an ordered list of fitted models or diagnostics. An existing influ_steps is also accepted.
year: Focus-variable name, inferred from the first input when omitted.
steps: For refitting, an ordered, uniquely named list of cumulative formulas or lists of model-update arguments. Each specification updates the original model. Use formula in an argument list for its formula change. If omitted, ordinary single-component models start with the focus term and progressively add the remaining formula terms. Offsets are retained. Spatial models require explicit steps so field changes are deliberate.
refit: Explicitly allow new model fitting. Defaults to FALSE.
labels: Unique step labels. Defaults to list names or generated labels.
component: Index component. Must be supplied if more than one is available, for example "positive" or "unconditional_mean" in a hurdle model. Even a combined-component index remains a focus-effect contrast, not the full expected response integrated over space.
probs: Interval probabilities for newly calculated diagnostics. Existing diagnostics retain their original intervals.
keep_fits: Retain fitted models in the result? Defaults to FALSE to keep the returned object small. Save expensive fits separately if needed.
refit_args: Named arguments passed to the model update at every step, with original fitting rows and offsets locked. For lme4 negative-binomial fits, explicitly supply list(reestimate_nb = TRUE) to use glmer.nb at each stage, or FALSE to keep the original size parameter. The saved native call cannot distinguish originally estimated from user-fixed size. Automatic lme4 sequences retain all random terms while adding fixed terms; changes to random structure require explicit step formulas, each with a random term. such as brms sampling controls. Stage-specific arguments take precedence. Execution-only controls (seed, cores, refresh, silent, and verbose) do not by themselves force an otherwise unchanged original fit to rerun.
year_term: For joint sdmTMB models, the annual predictor in each component, e.g. c(occurrence = "year_scaled", positive = "year_factor"). Defaults to year in both. Each predictor must be constant within each plotted year and enter its formula as an additive fixed term.
...: Arguments passed to influ() for fitted-model inputs, such as uncertainty = "none", weights, or reference_data. All steps use the same calculation arguments. Not used for model-fitting controls.
x, object: An `influ_steps` object.

Value

An influ_steps object with compact indices and steps tables, focus, calculation metadata, and optional fits.

Details

Plotting a stored result never refits models. plot_step(model, refit = TRUE) is an explicit shortcut that calculates a sequence and immediately plots it. Automatic refitting is restricted to supported formula structures. Supply explicit steps or already-fitted models when a structure cannot be updated safely. Refits use the original analysis rows and report convergence problems. Native update() methods are used where available. tinyVAST has no such method, so its refits reconstruct the recorded fitting call with the locked data, stored spatial domain, and requested process settings. Joint sdmTMB refits likewise reconstruct the saved call, because its native update method does not update paired formulas. Supply explicit stages such as list(Baseline = list(formula = list(~ year, ~ year), spatial = "off", spatiotemporal = "off"), Full = list(formula = model$formula)). Supported joint step indices are standard delta-Gamma and delta-lognormal with logit/log links. Choose component = "occurrence", "positive", or "unconditional_mean". The last combines both annual terms using their joint covariance; it is not an area-integrated index. Positive-component contrasts are ratios; occurrence contrasts are probability differences at the fixed-effect reference. Non-year covariates use each fit's common observed/reference design, not individual fitted random-effect modes. Positive-component effort offsets are preserved in refitting and cancel from log-link annual ratios. Field modes are not added to these fixed-year contrasts. This narrower calculation does not enable the full offset-dependent influence decomposition.

Each curve uses the centring and uncertainty supplied by influ(). No extra plug-in rescaling is applied. With the same data and focus reference, all steps use the same contrast definition. A change between steps depends on the chosen order and is not a causal measure of variable importance. Intervals describe each fitted model, not uncertainty in differences between independently fitted models.

Supplied fits are checked for matching fitted response and focus rows where those are recoverable. Precomputed diagnostics only permit checks of retained response, focus-composition, reference, and index summaries; identical raw data cannot be established from those summaries alone. Refitted stages receive backend convergence checks. A stage marked supplied records an existing input, not independent confirmation of its convergence; check that fit before including it. Compact posterior fixtures may not retain convergence records.

Examples

data(lobsters_per_pot)
model <- glm(lobsters ~ year + month, family = poisson(),
             data = lobsters_per_pot)
steps <- influ_steps(model, year = "year", refit = TRUE)
steps
#> <influ_steps>
#>   Estimand: year-effect contrasts (not spatial abundance)
#>   Focus: year
#>   Steps: 2
#>   Refitted: 1
#>  step_id     label backend          status
#>        1 Year only     glm        refitted
#>        2 Add month     glm reused original
plot_step(steps)