Skip to contents

Fits a magComp model repeatedly while holding out complete sampling units, retaining the original category levels. Each fold predicts all held-out units together through predict, using their covariates, group labels, coordinates, and original sampling exposures. Prediction options have the same defaults and meanings as predict().

Usage

magCompCV(data, family = fixedAreaStems(), magnitude = ~1,
  composition = ~1, smooth = magCompSmooth(), priors = magCompPriors(),
  starting = list(), control = magCompControl(), tuning = list(), n_fold = 10,
  fold_id = NULL,
  type = NULL,
  target = c("expected", "observation"),
  summary = c("mean", "samples", "quantile"),
  probs = c(0.025, 0.5, 0.975), keep_fits = FALSE)

# S3 method for class 'magCompCV'
plot(x, type = x$type[1L],
  level = c("cell", "total"), file = NULL, main = NULL, ...)

Arguments

data

A data object returned by magCompData.

family

A model family: fixedAreaStems or pointBasalArea. Both support expected and observation targets.

magnitude

Magnitude formula, or NULL to fit composition only.

composition

Composition model formula or magCompComposition specification passed to magComp, or NULL to fit magnitude only.

smooth

Composition smoothing specification.

priors

Prior specification.

starting

Partial or complete starting values specified for the full data. Supplied magnitude effects and composition scores are matched to the full-data template and subset to each training fold's groups or locations. Unspecified starts are computed using only that fold's training data. Supplied loadings must satisfy each fold's anchor constraints; use explicit anchors when reusing full-data loading starts.

control

MCMC control passed to each fold fit. Sampling is enabled.

tuning

Covariance proposal settings passed to each fold fit; see magCompCovModels.

n_fold

Number of folds when fold_id is not supplied. Use n_fold = data$n_unit for leave-one-out cross-validation.

fold_id

Optional vector of fold labels named by sampling unit, identifying at least two folds.

type

A nonempty, unique subset of "magnitude", "proportion", "density", and "count", restricted to the quantities supported by the fitted components. Default NULL selects the same quantities as predict. For plotting, select one returned quantity; the first requested quantity is the default.

target

"expected" returns expected quantities; "observation" simulates observations using the fitted likelihood. Meanings and defaults match predict.

summary

Return means, aligned retained samples, or quantiles, with the same dimensions and behavior as predict.

probs

One or more probabilities strictly between zero and one, used for summary = "quantile". For example, probs = 0.5 requests only the median. Also used for plot intervals when samples were retained.

keep_fits

Logical; if TRUE, retain each fold's fitted magComp object.

x

A magCompCV object.

level

Plot category values ("cell") or within-unit totals across categories ("total"). Magnitude already represents overall density and has the same plot at either level. Proportions support only "cell". Composition-only CV has no total-level plot because unit totals are conditioned on.

file

Optional PNG output path.

main

Optional plot title.

...

Additional graphical arguments passed to plot().

Details

Standalone components are supported. Magnitude-only CV compares total counts or overall densities. Composition-only CV predicts category probabilities; conditional expected counts and simulated allocations use held-out observed totals. These assess allocation given the total, not abundance prediction. The result's count_conditioning is "observed_total" in this case, otherwise "none". Conditional count/density totals and total-level plots are omitted because totals are fixed by construction. Composition-only probability or count predictions need no areas; conditional densities do.

Folds are fitted sequentially. control$n_cores parallelizes chains within a fit, not folds. With no supplied fold_id, units are randomly assigned to approximately equal-sized folds.

Each fold uses one joint prediction call, including every fitted model term. All requested quantities and within-unit totals use the same draws. Totals are summed across categories before taking means or quantiles. Fold identities are retained: posterior draws from separately fitted folds do not constitute joint draws across all held-out units.

Observed counterparts are category counts, category counts divided by exposure (density), total count divided by exposure (magnitude), and category count fractions (proportion). Observed proportions are NA for zero observed totals. For fixed-area stems, exposure is plot area; for point basal area it is \(1/\mathrm{BAF}\). CV supplies each held-out unit's original exposure; there is no user-supplied replacement area or newdata argument.

The definitions and zero-total handling in magCompPrediction apply to all returned predictions.

Expected-target intervals describe uncertainty in expected quantities. Observation-target intervals also include observation variation. CV returns predictions and observed values; it does not calculate predictive scores or coverage statistics.

Plots use means for mean or sample results, and the requested quantile nearest 0.5 for quantile results, with the selected statistic labeled on the axis. Intervals use the smallest and largest requested probabilities when at least two are supplied. Mean-only results have no interval bars. Undefined observed or predicted proportions do not produce plotted pairs.

Serial workflows can be reproduced with external set.seed(). Parallel fitting uses chain_seeds in magCompControl().

Value

An object of class magCompCV, containing:

predictions

A list named by fold label, each entry a standard magCompPrediction result with the requested quantities, summary, row labels, and prediction metadata. A single requested type still returns that named result.

observed

A list named by requested type, with matrices in the original sampling-unit order. Category quantities have one column per category; magnitude has one column named "total". Match prediction rows using each fold result's metadata$unit_ids.

totals

A list named by fold label, each containing within-unit category sums for requested count and density quantities. Each total uses magnitude-style dimensions: unit by sample (and chain) for samples, unit by one column for means, or unit by probability for quantiles. Magnitude is already overall density; no total proportion is returned. Entries are empty lists for composition-only models or if neither count nor density is requested.

count_conditioning

"observed_total" for composition-only assessment, otherwise "none".

fold_id

Fold assignments named by original sampling unit.

fits

Fold models named by fold label, or NULL unless keep_fits = TRUE.

call, target, type, summary, probs

The call and selected prediction options.

Examples

rows <- expand.grid(plot = paste0("p", 1:6), cls = c("small", "large"))
rows$count <- rep(c(1, 3, 2, 4, 2, 1), 2)
rows$area <- rep(seq(0.05, 0.1, length.out = 6), 2)
dat <- magCompData(rows, unit = plot, category = cls, tree_count = count,
                   design = fixedArea(area))
set.seed(42)
cv <- magCompCV(dat, n_fold = 2, target = "observation", type = "count",
                summary = "samples",
                control = magCompControl(n_samples = 6, n_burn = 2,
                                          verbose = FALSE))
cv$predictions[["1"]]$count
cv$observed$count
cv$totals[["1"]]$count