
Results from fitted values and prediction
magCompPrediction.RdThis help topic describes the named list with class magCompPrediction, containing requested
magnitude, proportion, density, and count
components, followed by metadata. Predictions made with
keep_effects = TRUE also store a latent component for use by
samples; its internal indexing is not part of the public interface. standSummary also returns
this class, with a selected stand density, total, or proportion component.
Selecting one type still returns a
list: for example, fitted(fit, type = "count")$count.
Details
The definitions below describe fitted() and predict() results.
See standSummary for the corresponding stand quantities and metadata.
Observed and new units each have two choices of target:
| Units | Conditional means | Simulated observations |
| Observed | fitted(target = "expected") | fitted(target = "observation") |
| New | predict(target = "expected") | predict(target = "observation") |
These calls also require the fitted object and, for prediction, newdata.
Defaults are target = "expected" and summary = "mean".
With both model components, type = NULL selects all four quantities.
Standalone models return the quantities described below.
For fixed-area stems, let \(M\) be overall stem density, \(p_j\) the probability of final category \(j\), and \(a\) the sampling area. For each retained posterior draw, expected quantities are constructed as follows. Observation quantities additionally draw \(N \sim \mathrm{NB}(aM, r_M)\) and then \(\mathbf{Y} \sim \mathrm{Multinomial}(N, \mathbf{p})\).
| Quantity | Expected | Observation |
magnitude | \(M\) | \(N/a\) |
proportion | \(p_j\) | \(Y_j/N\) |
density | \(M p_j\) | \(Y_j/a\) |
count | \(a M p_j\) | \(Y_j\) |
In a conditional two-category model, \(p_j\) is the product of the parent probability and its conditional child probability. Size \(r_M\) uses the fitted fixed value or its matching posterior draw when estimated.
Point-sampling basal-area models support both targets. Let \(M^{BA}\) be basal-area density and \(m\) the in-tree tally. Expected total tally is \(M^{BA}/\mathrm{BAF}\). The observation target draws $$m \sim \mathrm{NB}(M^{BA}/\mathrm{BAF}, r_M^{BA}),$$ using the fitted fixed size or its matching posterior draw, then allocates \(m\) among categories when composition is fitted.
Expected magnitude and category density are \(M^{BA}\) and \(M^{BA}p_j\); observation values are the sampled basal-area estimates \(\mathrm{BAF}\,m\) and \(\mathrm{BAF}\,Y_j\). Count is the expected or simulated in-tree tally, and proportion is \(p_j\) or \(Y_j/m\), respectively. The fixed-area expressions above therefore apply with magnitude interpreted as basal-area density and exposure \(a = 1/\mathrm{BAF}\); this exposure is not a physical plot area. BAF must be constant within each point but may vary between points. BAF and basal-area density use matching units, such as square feet per acre.
For summary = "mean", each component is a matrix with one row per
unit and one column per category, or one column named "total" for
magnitude. For summary = "samples", category quantities have dimensions
unit by category by retained sample, plus a final chain dimension for multiple
chains. Magnitude omits the category dimension. For summary = "quantile",
category quantities have dimensions unit by category by probability, and
magnitude is a unit by probability matrix. Singleton dimensions are preserved;
means and quantiles pool chains. Row and category labels identify the fitted
units or prediction rows and final response cells.
Use summary(result) on a result retained with
summary = "samples" to obtain a table of means, standard deviations,
and quantiles by unit, quantity, and category. See
summary for the returned columns.
This uses the stored draws and does not rerun prediction.
For magnitude-only models, the default quantities are magnitude and
count. Expected values are \(M\) and \(aM\); observation values
are \(N/a\) and \(N\), with a negative-binomial draw for \(N\).
The count array retains a category dimension of length one named "total".
density and proportion are unavailable because no composition
is fitted.
Composition-only models default to proportion. Expected probabilities
need neither area nor a supplied total. Conditional expected counts are
\(N p_j\); replicate counts follow \(\mathrm{Multinomial}(N,\mathbf p)\).
fitted() uses observed totals; predict() requires
total_count. Conditional densities divide these counts by exposure.
magnitude is unavailable. Expected probabilities remain defined at
zero totals, but observation proportions are NA; counts and densities
are zero. A supplied total is fixed across draws, not an estimate from a
separate abundance model. Nested composition retains the parent/child product.
These standalone-component rules apply to both sampling families. For point sampling, conditional densities multiply tally counts by BAF, and observation proportions are undefined when the tally is zero.
Metadata contains:
source,target,type,summary,familyThe source function, target, requested quantities, summary, and response family.
units,unit_ids,exposureMeasurement units by quantity, row identifiers, and the exposures used. Exposure can be
NULLfor predictions requiring none.componentsActive model components.
count_conditioningCount conditioning:
"observed_total","supplied_total", or"none". Composition-only CV identifies its assessment as conditional on observed totals.total_countConditioning totals by unit when used, otherwise
NULL.n_samples,n_chains,n_drawsRetained draws per chain, number of chains, and their product.
sample_ids,chain_ids,probsDraw positions within the original retained chain, chain labels, and requested probabilities for quantile summaries (otherwise
NULL). Draws are aligned across quantities; observation simulation does not add another draw dimension. Withpredict(n_draws = ...), positions identify the selected subset.proportion_conditioning"positive_total"for observation results, otherwise"none". Observation proportions are undefined for zero totals. Their means and quantiles use positive-total draws only. Samples retainNAentries at zero totals, and all-zero units haveNAproportion summaries.zero_total_probability,n_positive_drawsFor each unit, the empirical fraction of zero-total draws and number of positive-total draws across all chains. Returned for every observation result, including type subsets;
NULLfor expected results.
All outputs within one result use the same draws. A zero simulated total
gives zero magnitude, density, and count, and undefined (NA) proportions.
Relations between draw-level quantities need not hold after separately taking
means or quantiles. Expected-target intervals describe uncertainty in conditional
means; observation-target intervals also include variation from the likelihood.
See also
fitted,
predict;
the technical guide's Prediction and aggregation section in
magComp-package.