
Prepare data for magnitude-composition models
magCompData.RdBuilds 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)orc("parent", "child"). Use this instead ofcategoryfor 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