Skip to contents

Aggregates existing density draws using represented land areas. No new predictions are generated: the supplied expected or observation target and posterior draw alignment are preserved.

Usage

standSummary(object, ...)

# S3 method for class 'magCompPrediction'
standSummary(object, data, unit, group = NULL, represented_area,
                            type = c("density", "total", "proportion"),
                            summary = c("mean", "samples", "quantile"),
                            probs = c(0.025, 0.5, 0.975), ...)

Arguments

object

A magCompPrediction result from fitted() or predict(), retained with summary = "samples" and containing density or magnitude. 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 data containing prediction location IDs, supplied as a bare name or quoted column name. IDs must match the units stored in object; the column name can differ from the original ID column.

group

The column in data identifying stands or other groups, supplied as a bare name or quoted column name. Omission or NULL aggregates all rows into one group named "all". Groups appear in order of first occurrence.

represented_area

The column in data containing 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

} # }