
Cross-validation at held-out sampling units
magCompCV.RdFits 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:
fixedAreaStemsorpointBasalArea. Both support expected and observation targets.- magnitude
Magnitude formula, or
NULLto fit composition only.- composition
Composition model formula or
magCompCompositionspecification passed tomagComp, orNULLto 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_idis not supplied. Usen_fold = data$n_unitfor 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. DefaultNULLselects the same quantities aspredict. 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 matchpredict.- 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.5requests only the median. Also used for plot intervals when samples were retained.- keep_fits
Logical; if
TRUE, retain each fold's fittedmagCompobject.- x
A
magCompCVobject.- 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:
predictionsA list named by fold label, each entry a standard
magCompPredictionresult with the requested quantities, summary, row labels, and prediction metadata. A single requested type still returns that named result.observedA 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'smetadata$unit_ids.totalsA list named by fold label, each containing within-unit category sums for requested
countanddensityquantities. 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_idFold assignments named by original sampling unit.
fitsFold models named by fold label, or
NULLunlesskeep_fits = TRUE.call,target,type,summary,probsThe 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