
Summarize predictive densities for stands, strata, or forests
standSummary.RdAggregates existing density draws using represented land areas. No new predictions are generated: the supplied expected or observation target and posterior draw alignment are preserved.
Arguments
- object
A
magCompPredictionresult fromfitted()orpredict(), retained withsummary = "samples"and containingdensityormagnitude. Both sampling families are supported.- data
A data frame or tibble with one row for each prediction location's contribution to a stand or other group. A cell crossing stand boundaries has a separate row and represented area for each stand. Rows may be in any order and may select a subset of prediction locations.
- unit
The column in
datacontaining prediction location IDs, supplied as a bare name or quoted column name. IDs must match the units stored inobject; the column name can differ from the original ID column.- group
The column in
dataidentifying stands or other groups, supplied as a bare name or quoted column name. Omission orNULLaggregates all rows into one group named"all". Groups appear in order of first occurrence.- represented_area
The column in
datacontaining positive finite land areas, supplied as a bare name or quoted column name. For cells crossing stand boundaries, use the cell's area within that row's stand. Use units consistent with the density, such as hectares for trees per hectare.- type
One stand quantity: area-weighted density (the default), total, or category proportion. Proportions require category density samples.
- summary
Return posterior means, aligned retained samples, or quantiles. Means and quantiles pool retained draws across chains.
- probs
Probabilities strictly between zero and one, used for
summary = "quantile".- ...
Must be empty. Unknown arguments are rejected.
Details
For each category and draw, total is the sum of density times represented area. Density is that total divided by the group's summed area. Proportions divide category totals by their sum across categories. They describe pooled stand composition, not an area-weighted average of local proportions.
Full models supply category density draws. Magnitude-only models supply
magnitude, giving overall density or total under a single category named
"total". When both quantities are present, category density is used.
Composition-only models can supply conditional category densities:
fitted() uses observed totals and predict() requires
total_count, with plot area or BAF supplied for the density conversion.
Those totals remain fixed across draws, and the conditioning is recorded in
metadata. Proportions alone lack the abundance information needed for pooled
stand composition and cannot be aggregated by this function.
For fixed-area sampling, stand densities are stems per unit area and totals
are stems. For point sampling, densities are basal area per unit area and
totals are basal area. Point-sampling fitted() and predict()
already multiply category tallies by BAF; standSummary() does not apply
BAF again. Point-sampling proportions describe basal-area composition.
Represented areas within a group define its summary area. For a cell grid,
intersect the cells with the target polygons and supply the intersection areas.
Each cell's same density draw contributes to every group it overlaps, treating
that density as constant within the cell. Multiple rows for the same location
and group add their represented areas, as for disconnected intersection pieces;
include each piece once. Omitting group pools all supplied areas.
For grid points, equal weights can be a stand's polygon area divided by its
number of points. These are aggregation weights, distinct from plot areas or
reciprocal BAF used to generate counts. No areas are inferred from polygons,
grid spacing, or sampling exposure. Fitted locations also require explicit
represented areas; sampled plots do not automatically represent a whole stand.
The same calculation applies to predictions from regression, stratum and spatial models. Their effects are already included in the supplied draws. Supply all locations for the desired support in one prediction call when joint spatial uncertainty matters. Aggregation preserves dependence already in those draws but cannot reconstruct dependence omitted by separate calls. When model relationships differ by stratum, prediction units must represent the appropriate stratum; aggregation weights do not change the fitted effects.
Internally, a sparse group-by-location area matrix multiplies the density samples, preserving category, draw and chain alignment without constructing a long table of draws. Density divides each group's totals by its summed area.
Totals and densities retain zero-valued draws. Proportions are NA for
zero-total draws; their means and quantiles condition on a positive total.
If no positive draws remain, proportion summaries are NA. Metadata
records the zero-total fraction and number of positive draws by stand.
Value
A magCompPrediction named list containing the selected
density, total, or proportion component and metadata.
Means are stand-by-category matrices, samples are stand-by-category-by-draw
arrays with the input chain dimension retained, and quantiles are
stand-by-category-by-probability arrays. Magnitude inputs use a category
named "total". Stand and category labels identify the rows and columns.
Use summary(result) on retained stand samples for a table of means,
standard deviations, quantiles, and contributing draw counts.
Metadata records the original target, family, units, count conditioning,
draw and chain identities, stand IDs in unit_ids, and summed
represented_area by stand. prediction_source identifies
fitted or predict. The aggregation list retains the
original prediction IDs, sampling exposures, and any conditioning totals.
Its data element records the supplied mapping with columns unit,
group, and represented_area; these are location contributions,
not stand totals.
See also
fitted,
predict,
summary;
the technical guide's Prediction and aggregation section in
magComp-package.
Examples
if (FALSE) { # \dontrun{
# Plot areas determine counts; intersection areas weight densities.
pred <- predict(fit, grid, area = "plot_area", target = "observation",
type = "density", summary = "samples")
stands <- standSummary(pred, data = cell_stand_areas,
unit = prediction_id, group = stand_id,
represented_area = area_ha, summary = "samples")
summary(stands)
stands$density
# One row per cell is sufficient for a forest summary.
standSummary(pred, data = grid, unit = prediction_id,
represented_area = cell_area_ha, summary = "quantile")
# The same interface handles basal-area densities from point sampling.
point_pred <- predict(point_fit, grid, target = "observation",
type = "density", summary = "samples")
standSummary(point_pred, data = grid, unit = prediction_id,
group = stand_id, represented_area = expansion_area_acres,
type = "total")$total
} # }