Diagnose externally simulated responses

Reduce an already generated response-simulation matrix to the same compact diagnostic returned by influ_residuals(). No CPUE model is fitted, and no new responses are simulated.

Usage

as_influ_residuals(
  simulations,
  data,
  response,
  year,
  response_kind,
  conditioning,
  component = NULL,
  observation_id = NULL,
  probability = NULL,
  probability_conditioning = NULL,
  trial_counts = NULL,
  batch_size = 25L,
  seed = 1L,
  grid_size = 201L,
  level = 0.95,
  groups = NULL,
  calibration_bins = 10L,
  calibration_min_n = 20L,
  calibration_groups = NULL,
  residual_method = c("simulation_pit", "dharma"),
  retain_dharma = FALSE,
  dharma_max_mb = 256,
  integer_response = NULL,
  residual_tests = c("none", "standard", "full"),
  dharma_storage = c("auto", "disk", "memory")
)

Arguments

simulations: Numeric matrix with observations in rows and complete joint response simulations in columns (at least 20). Row names are required and must exactly match the observation IDs in data, in the same order. No transposition, sorting, recycling, or omission is performed. Optional column names must be unique, non-empty simulation identifiers.
data: Data frame containing the matching observations, time labels, and any requested grouping or calibration columns. Exactly one row per simulation row is required; supply only the rows actually simulated.
response: Name of the numeric observed-response column in data. For Bernoulli/binomial inputs, supply integer success counts, not proportions.
year: Name of the time column in data. This is required because no fitted formula or native time metadata is available for automatic detection.
response_kind: Explicit response interpretation: "distribution" for general counts or continuous responses, "positive_continuous" for strictly positive continuous responses, "combined" for a non-negative combined hurdle/delta/zero-inflated response, "bernoulli" for one-trial successes, or "grouped_binomial" for known multi-trial successes. This is not inferred from observed zeros, ones, or the supplied simulations.
conditioning: Required non-empty description of how the response simulations were generated, including parameter uncertainty and treatment of random, spatial, and spatiotemporal effects. This is a user declaration, not something that influ2 can verify from a matrix.
component: NULL (default) means "combined" when response_kind is "combined", and "single" otherwise. Explicit "encounter" requires Bernoulli inputs. Explicit "positive" requires strictly positive inputs with kind "distribution" or "positive_continuous". These labels declare what was supplied; they never extract, transform, or filter components.
observation_id: Optional name of a unique, non-missing ID column in data; otherwise use its row names. IDs are compared as character strings.
probability: Name of the fitted success-probability column in data, required for Bernoulli/binomial calibration, and disallowed otherwise. Supply original fitted probabilities, not row means of the response simulations. For posterior predictions, average expected probabilities over the same posterior draw IDs used for the response simulations.
probability_conditioning: Required description of the conditioning used for probability, when supplied. Fixed probability bins may use different conditioning from response simulations (e.g. fitted versus resimulated random effects); record that difference explicitly.
trial_counts: Name of a positive-integer trial-count column in data. Required for "grouped_binomial", where at least one row must have more than one trial. Bernoulli defaults to one trial per row. Never use arbitrary fitting or area weights as trial counts.
batch_size: Maximum number of supplied simulation columns processed in each batch. No additional responses are generated.
seed: Integer random seed. The caller's random-number state is restored. DHARMa tie randomisation uses a separate deterministic seed: add 104729 to seed, then take the remainder modulo .Machine$integer.max. This is recorded in metadata$dharma_seed and avoids reusing the beginning of the simulation/draw-selection RNG stream.
grid_size: Approximate number of ECDF grid points, at least 20.
level: Pointwise predictive interval coverage for ECDFs, and nominal independent-uniform reference coverage for the Q-Q panel.
groups: Optional names of original-data grouping columns to retain for plot_grouped_residuals(). Specify these independently of the response. Only these columns, not the complete model data, are stored.
calibration_bins: Requested number of roughly equal-observation-count probability bins. Defaults to 10; ties are never split. Near ties within 1e-8 are kept together, and under-supported bins are merged.
calibration_min_n: Minimum observation count per probability bin, default 20. Smaller datasets remain a single flagged sparse bin. Scientific groups below this size remain visible but have no predictive envelope.
calibration_groups: Optional character vector of columns in data defining a joint scientific grouping, e.g. c("year", "target"). These columns must not be defined from the outcome.
residual_method: "simulation_pit" (default) preserves influ2's compact finite-simulation ranks. "dharma" delegates the residual calculation to optional DHARMa >= 0.4.7, using getQuantile(method = "PIT") on the same native response simulations and conditioning. It does not call simulateResiduals() or adopt DHARMa's model-specific defaults.
retain_dharma: Keep the genuine DHARMa object in result$dharma, including its full response matrix, for DHARMa plotting, aggregation, and tests. Default FALSE returns compact summaries without a native object. Requires residual_method = "dharma". No fitted model is retained.
dharma_max_mb: Response-workspace budget in MiB, default 256. Disk storage bounds estimated simulation-batch and quantile-slab workspace, reducing the effective batch size if needed. It fails if even one column or slab cannot fit. Memory storage guards the full matrix alone and warns at 100 MiB. Neither is a process-wide peak-memory bound: native backends, ECDF/calibration summaries, and auxiliary qgam fits use additional memory.
integer_response: For residual_method = "dharma", declare whether the supplied response distribution is integer-valued. Required for general response kinds; defaults to TRUE for Bernoulli/grouped binomial. This is distribution metadata, not inferred from realised observed values. DHARMa's PIT calculation randomises atoms in both discrete and mixed distributions.
residual_tests: Optional DHARMa-reference checks: "none" (default) leaves the existing result unchanged; "standard" calculates uniformity, simulation-based response dispersion, and supported year-level categorical checks. "full" also calculates auxiliary quantile regressions and an outlier test (bootstrap for integer responses, with extra calculation cost). Requires residual_method = "dharma". Uniformity, year, and quantile tests call native DHARMa vector interfaces. Disk dispersion and outlier tests use explicitly labelled bounded-memory equivalents of its non-refitted reference algorithms. Memory storage calls all tests on the genuine native object. Tests run once, retaining compact statistics only. They are exploratory, not fitted-model-calibrated acceptance tests, and do not refit the CPUE model, run MCMC, or use Pearson dispersion. Year KS p-values are Holm- adjusted across supported years; the other checks are not jointly adjusted.
dharma_storage: "auto" (default) uses a temporary disk cache for compact DHARMa results, or "memory" when retain_dharma = TRUE. Explicit "disk" processes observation slabs without assembling a full response matrix in RAM; "memory" uses createDHARMa(). Disk storage cannot retain a native DHARMa object. Simulations are generated once; temporary files are removed on success or error. Only used with DHARMa.

Value

An influ_residuals object, using the same plotting and grouped residual helpers as fitted-model results. Metadata identifies external input, explicit alignment, response component, and declared conditioning.

Details

Each column must be a whole response vector from the intended predictive distribution, not fitted means, parameter draws, or PIT values. Existing within-column dependence is preserved. The predictive mean and response ECDF are calculated from these same supplied simulations. No separate fitted-mean argument can introduce a different prediction target.

Validate native output order before assigning row names. For example, brms posterior predictions normally need transposition to put observations in rows; do not guess orientation from a square matrix. The caller is responsible for the provenance of the IDs and declared response structure. Matrix alignment checks cannot detect incorrectly assigned identifiers.

A combined-response diagnostic is not a positive-component diagnostic. For the latter, generate positive-component simulations at the matching observed-positive rows. Do not remove zeros separately within simulation columns or relabel a combined matrix as a component calculation. No conversion of censored, multivariate, weighted, or other special response encodings is provided; resolve the predictive target before using this API.

The default shared engine randomises ties and applies qnorm(pit) exactly as for fitted models. DHARMa uses its own PIT calculation and the endpoint display convention documented in influ_residuals(). The caller's random-number state is restored, including on error. Reusing the same matrix, seed, batch size, and RNG kind reproduces the result. A native adapter can consume random numbers when preparing simulations (e.g. selecting posterior draws), so an identical seed alone does not guarantee identical ranks between the two entry points.

This initial interface accepts an in-memory matrix, not a generator or on-disk stream. It is processed in observation-by-batch blocks; the returned object retains neither the matrix nor a closure capturing it. The caller's original matrix still occupies memory until they release it. Temporary ECDF/calibration storage and the first-batch ECDF grid follow the existing influ_residuals() calculation. Changing batch size can change that grid, but not the ranks or sequentially calculated predictive means for fixed supplied simulations. With residual_method = "dharma", compact output defaults to a temporary disk cache instead of an additional full matrix. This does not release the caller's original in-memory input. Set retain_dharma = TRUE only when DHARMa's original object is needed.

These remain exploratory predictive checks. Fitted-data ranks are not automatically uniform or calibrated for parameter estimation, posterior data reuse, or latent dependence. This constructor does not implement LOO-PIT, OSA, or validate a model-specific simulation scheme.

Examples

d <- data.frame(year = rep(2010:2012, each = 10),
  cpue = rep(c(0, 1, 2, 3, 4), 6))
# A small supplied-simulation example, not a fitted CPUE model.
set.seed(42)
sims <- matrix(rpois(nrow(d) * 30, lambda = 2), nrow = nrow(d),
  dimnames = list(rownames(d), NULL))
checks <- as_influ_residuals(sims, d, response = "cpue", year = "year",
  response_kind = "distribution",
  conditioning = "Independent Poisson responses at a fixed mean of 2")
checks
#> Simulation-based residual diagnostics (external)
#> 30 observations; 30 simulations
#> Time: year [ explicit external column ]
#> Independent Poisson responses at a fixed mean of 2
#> Exploratory ranks; not a calibrated goodness-of-fit test

Usage

Arguments

Value

Details

See also

Examples