
Expected values or observations at new sampling units
predict.magComp.RdConstructs posterior predictions at new units, including every fitted regression, group, spatial, and composition-factor term. See magCompPrediction for the returned quantities and the distinction between expected values and simulated observations.
Arguments
- object
A fitted
magCompobject.- newdata
A data frame with one row per prediction unit, containing the covariates, group labels, and coordinates required by the fitted model.
- type
Quantities to return; see magCompPrediction for supported choices. With
NULL, defaults depend on the fitted components.- target
Use
"expected"for conditional means based on posterior and new latent-effect draws, or"observation"to simulate observations from the fitted likelihood.- summary
Return means, aligned retained samples, or quantiles. Means and quantiles pool all retained draws across chains.
- area
Prediction exposure: a positive finite scalar, a numeric vector with one value per row, or the name of a column in
newdata. ForfixedAreaStems, exposure is the sampling area for each predicted count. If omitted, the area column named in the fitted design must be innewdata. ForpointBasalArea, supply exposure1 / BAF, or omitareaand supply the fitted design's BAF column innewdata. Training exposures are never silently reused. Exposure is required for count predictions or observation simulation when magnitude is fitted. For composition-only models, it is required only for conditional density; probabilities and conditional counts need no exposure.- probs
One or more probabilities strictly between zero and one, used for
summary = "quantile".- total_count
For composition-only models, a numeric vector with one nonnegative integer total per prediction row, or the name of its column in
newdata. Named vectors are matched to prediction unit IDs; unnamed vectors follow row order. Counts must not exceed R's integer limit. Required for conditional counts, conditional densities, or any observation target. Totals are treated as known and are not simulated. Not used when magnitude is fitted.- n_draws
Number of retained posterior draws to use per chain. The default
NULLuses all retained draws. A positive integer selects approximately evenly spaced draws from each chain and must not exceed the number available. Selection preserves matching parameters and latent effects, and does not change the fitted object.- keep_effects
Retain the parameter and latent-effect draws used for prediction, for extraction with
samples. Requiressummary = "samples". Defaults toFALSEto avoid storing additional arrays. Both expected and observation targets are supported.- ...
Must be empty. Unknown arguments are rejected.
Details
Prediction draws new latent effects conditional on each retained posterior
draw. Thus even target = "expected" can require random simulation.
With both components, target = "observation" additionally draws a
negative-binomial total and multinomial allocation. Magnitude-only models draw
only the total. Composition-only models instead allocate total_count
using a multinomial draw. Their expected category counts are
\(N_0 p_{0j}\), conditional on the supplied total \(N_0\); no magnitude
is estimated. Expected probabilities require neither totals nor areas. Use set.seed()
externally for reproducibility.
Use n_draws to reduce prediction time and memory while keeping all
fitting draws for parameter summaries and diagnostics. For example,
n_draws = 100 with three fitted chains generates 300 predictive draws.
Selection occurs before prediction and retains every requested location in
each draw, including joint spatial effects. Selection itself uses no random
numbers. Output metadata$sample_ids identifies the positions selected
within the original retained chains. Fewer draws increase Monte Carlo
variability, especially in interval endpoints.
With keep_effects = TRUE, samples(predictions, type = "effects")
extracts the stored new-unit effects, and type = "combined" adds their
matching regression coefficients and loading-times-score contributions.
These are the same draws used to construct the response predictions; extraction
does not simulate again. All fitted latent terms are generated and retained,
even when type requests only magnitude. standSummary() aggregates
response draws and does not carry these location-level effects into its output.
Observed iid groups reuse posterior effect draws. Each unseen group receives
one new Gaussian effect per term and posterior draw, shared by all rows in
that group. Magnitude terms use their sampled variances; composition factor
scores use unit variance. For space-time terms, a location includes the final time coordinate: an exact
location-time match reuses its fitted effect, while a revisit at a new time
receives a conditional draw. Prediction inherits the fitted covariance family
and st_scale for neighbor searches.
Known spatial locations reuse fitted effects, and
repeated new coordinates share one sampled spatial effect per term and draw.
Dense-GP prediction draws new effects jointly from their conditional Gaussian
distribution. NNGP prediction orders new locations by their first coordinate,
using subsequent coordinates to break ties, and uses neighbors among observed and earlier new locations in the same call.
There is no conditionally independent spatial option. The NNGP approximation
depends on the requested location set; separate calls omit cross-call links
and do not reproduce a single joint call. Supply the complete desired support
in one call when its joint uncertainty matters.
Both targets support fixedAreaStems and
pointBasalArea.
For point sampling, the expected total tally is
\(M_0^{BA}/\mathrm{BAF}_0\); multiplying simulated tallies by BAF gives
sampled basal-area estimates. Composition-only models condition on the supplied
tally total. For an observed location, prediction
reuses its stored spatial effect, but covariates and exposure still come from
newdata and area. Use fitted() to obtain results for all
original units with their original inputs.
standSummary aggregates stored density or magnitude samples
using explicitly supplied represented land areas. It preserves the selected
target. These weights serve a different purpose from the sampling exposures
used to generate counts here. Neither function determines areas from polygons.
Value
A magCompPrediction named list with requested quantity components
and metadata, even for one requested quantity. All quantities share
posterior draw and chain identities. See that help page for dimensions and
metadata fields.
See also
summary for summarizing stored draws;
fitted, standSummary,
magCompCV