Skip to contents

This 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:

UnitsConditional meansSimulated observations
Observedfitted(target = "expected")fitted(target = "observation")
Newpredict(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})\).

QuantityExpectedObservation
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, family

The source function, target, requested quantities, summary, and response family.

units, unit_ids, exposure

Measurement units by quantity, row identifiers, and the exposures used. Exposure can be NULL for predictions requiring none.

components

Active model components.

count_conditioning

Count conditioning: "observed_total", "supplied_total", or "none". Composition-only CV identifies its assessment as conditional on observed totals.

total_count

Conditioning totals by unit when used, otherwise NULL.

n_samples, n_chains, n_draws

Retained draws per chain, number of chains, and their product.

sample_ids, chain_ids, probs

Draw 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. With predict(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 retain NA entries at zero totals, and all-zero units have NA proportion summaries.

zero_total_probability, n_positive_draws

For 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; NULL for 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.