influ2

influ2 calculates and visualises how explanatory variables, random effects, and spatial fields influence standardised fisheries CPUE indices.

The package uses one model-neutral S3 interface:

diagnostic <- influ(model, focus = "year")
diagnostic
summary(diagnostic)
plot(diagnostic, type = "influence")
plot(diagnostic, type = "cdi", term = "vessel")

Initial adapters are available for:

• stats::glm();
• mgcv::gam();
• brms::brm();
• glmmTMB::glmmTMB();
• lme4::lmer(), lme4::glmer(), and lme4::glmer.nb();
• sdmTMB::sdmTMB(); and
• tinyVAST::tinyVAST().

The result is a compact influ_diag object with consistent tables and plots across backends. brms posterior coefficients are projected directly into focus-by-term diagnostics, avoiding observation-by-draw-by-term arrays.

Compare saved diagnostics from different model runs in one overlaid CDI:

plot_cdi(list(Full = diagnostic_full, Recent = diagnostic_recent),
  term = "month", years = "union")

Coefficient estimates, composition bubbles, and influence lines use the same model colours. A common year axis leaves unavailable years blank; plotting does not silently recalculate each model's centring reference.

# Full posterior calculation, compact stored summaries.
diagnostic <- influ(brms_fit, focus = "year", retain = "summary")

# Retain only draws of the derived diagnostics.
diagnostic <- influ(
  brms_fit,
  focus = "year",
  retain = "derived_draws"
)

# Fast posterior-mean preview.
preview <- influ(brms_fit, focus = "year", uncertainty = "none")

Supported base families in the first implementation are Gaussian, binomial, Poisson, negative binomial, lognormal, Gamma, and Tweedie. Hurdle/delta and zero-inflated components are kept explicit.

Year-effect indices from influ() require an unambiguous focus effect. Offset/exposure diagnostics currently support single-component log-link ratios and identity-link contrasts, not combined or nonlinear-probability outputs. Lognormal support follows each backend's parameterisation; see the main vignette for the supported location, scale, and link combinations.

For an assessment-ready expected-response table, use cpue_index() with an explicit common reference profile or population. Both "standardised" and "standardized" are accepted. GLM, GAM, glmmTMB, lme4, complete brms, sdmTMB, and univariate tinyVAST fits are supported for response standardisation. integrate_index() separately calculates area-weighted totals for these same seven backends, whether or not the fitted model includes spatial effects.

index <- cpue_index(model, year = "year", reference_data = reference_profile)
as.data.frame(index)  # Year, Mean, Median, SD, CV, Qlower, Qupper, and metadata.
plot_index(index)
geo_mean(c(1, 4, 16))

total <- integrate_index(model, reference_data = prediction_grid,
  area = "area_km2", year = "year",
  area_units = "km^2", response_units = "kg/km^2", units = "kg")
plot_index(total)

These response indices are distinct from the year-effect contrasts used in the step plots. See the CPUE indices article for reference choices, compact uncertainty, and comparison examples. Area integration requires a stated domain and compatible response/area units; integrating CPUE does not automatically turn it into absolute biomass.

For GAM, sdmTMB, and univariate tinyVAST fits, index_domain() reports sampling coverage, native link contributions, restricted-domain indices, and masked term-omission comparisons without refitting:

domain <- index_domain(model, reference_data = prediction_grid, year = "year",
  sampled = list(coords = c("X", "Y"), distance = 5))
plot(domain)

The sampling rule is explicit, and missing responses or zero likelihood weights do not count as observations. GAM spatial/spatiotemporal smooths are grouped only by declared native labels. Shared joint draws preserve dependence across years and counterfactuals, with blocked prediction and compact retained results. See the spatial article for executed examples and interpretation limits.

For a separate view of multiplicative differences, calculate and plot index ratios from stored estimates:

ratios <- index_ratio(list(Full = index_full, Recent = index_recent),
  reference = "Full")
plot_index_ratio(ratios)

Ratios use matching years and retain gaps. Their point estimates are not between-model confidence intervals. The Comparing influence and indices article demonstrates unequal year ranges and separate ratio diagnostics.

Residual diagnostics

Residual overviews also adapt to the response: Bernoulli encounter models use fixed-bin probability calibration, while positive and combined responses retain the observed-versus-simulated CDF. No model is refitted by these calls.

checks <- influ_residuals(model, year = "year")
plot(checks)                          # Automatic fourth panel.
plot(checks, type = "distribution")  # Explicit original CDF.

DHARMa is an optional residual engine using the same native simulations and conditioning choices:

checks <- influ_residuals(model, residual_method = "dharma")
plot(checks)

This leaves the default compact engine unchanged. Compact DHARMa calculations now use a temporary disk cache and bounded observation blocks by default, rather than holding the full response-simulation matrix in RAM. Native DHARMa calculates the PIT values and vector-based tests; dispersion and outlier checks use explicitly labelled bounded-memory equivalents. Use retain_dharma = TRUE only when its genuine full-memory object is needed for DHARMa's own tools. Disk storage and extra I/O replace the matrix's RAM cost, not all backend or diagnostic memory. Conditioning and false-positive calibration are unchanged. See the DHARMa example for memory limits, endpoint handling, and interpretation.

For native fitting evidence and a term-by-term residual report:

report <- check_cpue(model, data = original_data)
report
summary(report)$terms
plot(report)  # Stored model statistics and exploratory DHARMa tests.

# Quick fitting report; no response simulation.
check_cpue(model, simulate = FALSE)

The checker supports the same seven backends. Unavailable tests are explicitly unassessed, and there is no overall model-pass flag. Numeric and categorical term screens are exploratory raw-predictor checks, not coefficient significance or automatic term selection. Supplying residuals = checks reuses a native residual result from the same fitted model without further simulation.

See Residual diagnostics for predictive-envelope interpretation and grouped checks that can reveal missing structure even when pooled encounter calibration looks good.

Constrained model search

Use one buildmer-style interface with native GLM, GAM, glmmTMB, lme4, brms, sdmTMB, and tinyVAST refitting. Year, offsets, fitted rows, and essential processes stay protected. The default is a preflight report, not a refit:

search_cpue(model, year = "year")
search <- search_cpue(model, year = "year", direction = "backward",
  criterion = "BIC", refit = TRUE, max_models = 30)
search$candidates
plot(search)
best <- selected_model(search)

Failed fits and stopping reasons remain visible; each specification is evaluated once. The recommendation is the best eligible evaluated model, not a guaranteed global optimum. Use check_cpue(best) separately: residual p-values are not term-selection rules, and selected-model uncertainty does not include selection uncertainty. See the Model search article for constraints, optional random terms, component handling, and memory limits.

Installation

pak::pak("quantifish/influ2")

See vignette("influ2") for the framework, memory strategy, and model examples. The separate vignette("bentley-validation") documents and plots the frozen agreement check against the original Bentley implementation.