Skip to contents

Builds sampling-unit summaries, count matrices, allocation-block summaries, coordinate matrices, design metadata, fixed-area exposure summaries, and expanded tree-list attributes used by magComp(). A one-category response creates one marginal allocation block. A two-category response creates a leading marginal block and a conditional child block. Category ordering metadata controls whether RW1/RW2 smoothing can be used for an allocation block. Coordinates must be constant within each sampling unit. When a model is prepared, the same check is applied to its predictors and grouping columns. Tree-level responses and attributes may vary within a unit.

Usage

magCompData(data, unit, category = NULL, categories = NULL,
            coords = NULL, tree_factor = NULL, tree_count = NULL,
            design = NULL, attributes = NULL, ordered = NULL)

fixedArea(area = NULL)

pointSampling(baf = NULL)

Arguments

data

Data frame with one row per observed tree or one row per category tally.

unit

Sampling-unit identifier column, supplied as a bare name or a string.

category

Optional single category column. Omit categories for total-count magnitude-only data.

categories

Optional one- or two-column category specification, supplied as c(parent, child) or c("parent", "child"). Use this instead of category for two-way composition tables.

coords

Optional coordinate columns, usually supplied as c(x,y).

tree_factor

Optional tree expansion factor column retained for expanded attribute summaries and future weighted-response families. Current point-sampling basal-area fits use pointSampling(baf = ...) rather than a tree-factor likelihood.

tree_count

Optional integer tally-count column. When supplied, category count matrices are built from this column rather than assuming one observed tree per row. Zero-count rows can be used to retain sampling units with no observed trees in the modeled categories.

design

Sampling design helper, e.g., fixedArea(area).

attributes

Optional tree-level attributes to expand by tree_factor. These summaries are stored with the prepared data for diagnostics and future continuous-response families.

ordered

Optional logical vector indicating which category columns are ordered. Names should match category column names. Ordered factor columns are also detected automatically. An ordered category must be a factor with levels in the intended order, or numeric (sorted numerically). Character labels require explicit factor levels to avoid accidental alphabetical ordering.

area

Fixed plot area, supplied as a scalar, a vector named by sampling-unit ID, or a column name constant within each unit. Non-scalar vectors must be named; values are matched by unit ID rather than position.

baf

Basal area factor, supplied as a scalar, a vector named by sampling-unit ID, or a column name constant within each unit. Non-scalar vectors must be named; values are matched by unit ID rather than position.

Details

Category columns can describe any categorical response dimensions; species and diameter classes are examples. With two columns, their order in categories determines the parent and child. Either can be ordered or unordered. Supply any desired classes as category values before preparing the data; the constructor does not create classes from continuous measurements.

Without category columns, counts are summed by sampling unit into one column named "total". Supply tree_count for tallied totals or use one row per tree. Fit these data using composition = NULL. Composition-only data still require integer category counts but can omit design; provide area or BAF information if conditional density outputs are needed later.

Column specifications accept bare names or strings. Sampling units retain their order of first appearance. Factor levels determine category order; otherwise numeric categories are sorted numerically and character categories alphabetically. Use explicit factor levels when a particular category order is needed, and ordered factors for categories to be smoothed. Unobserved category cells have zero counts; unused factor levels are retained.

To retain an empty sampling unit, provide a row with tree_count = 0 and valid category labels, covariates, and design information. Without a tally column, every row counts as one tree.

A fixed-area count model requires one common sampling area across all categories within each unit. Nested subplots with different areas for different categories must first be put on a common sampling support. Tree expansion factors do not convert those unequal-area counts into a valid common-area likelihood.

Tree-level attributes are stored as sums of tree_factor * attribute by unit and category. They are not responses in the implemented count models. Basal-area fits use in-tree tallies with a pointSampling() design and the pointBasalArea() family.

Value

The data constructor returns a magCompData object. Both design helpers return sampling-design objects.

Examples

rows <- data.frame(plot = c("p1", "p1", "p2"),
                   dbh_class = c("small", "large", "small"),
                   count = c(5, 2, 0), area = c(0.05, 0.05, 0.08))
rows$dbh_class <- ordered(rows$dbh_class, levels = c("small", "large"))
dat <- magCompData(rows, unit = plot, category = dbh_class,
                   tree_count = count, design = fixedArea(area))
dat$counts