Describing a Model with Descriptors

Descriptors are sets of information that describe a model. The user can think of descriptors as a nested list of helpful information for finding and specifying models. For example, Brackett (1977) is a technical report that fits 24 cubic volume models for a wide variety of tree species, age classes, and size classes. Descriptors answer the question: how would a user navigate models stored in allometric in a way that is consistent with the publication? We will take a look at Brackett (1977) as a motivating example.

In Brackett (1977) some species, like Douglas-fir, have multiple models that are fit to specific geographic regions and age classes. Let’s take a look at the descriptors of one of those models

brackett_acer

## Model Call: 
## vsia = f(dsob, hst) 
##  
## vsia [ft3]: volume of the entire stem inside bark, including top and stump
## dsob [in]: diameter of the stem, outside bark at breast height
## hst [ft]: total height of the stem 
## 
## Parameter Estimates: 
## # A tibble: 1 × 3
##       a     b     c
##   <dbl> <dbl> <dbl>
## 1 -2.77  1.89  1.12
## 
## Model Descriptors: 
## # A tibble: 1 × 5
##   country region geographic_region age_class taxa  
##   <chr>   <chr>  <chr>             <chr>     <list>
## 1 US      US-WA  NA                NA        <Taxa>

The last section of the output specifies all descriptors for this model, including country, region, family, genus, species, geographic_region and age_class. These descriptors are enough for a user to identify the model within the publication.

In this case, the first five descriptors (country through species) are referred to as “search descriptors”, which are descriptors propagated to the allometric_models dataframe. Contributors are encouraged to defined these descriptors whenever possible. The remaining two descriptors are non-standard descriptors specific to this publication, and use verbage from the publication to assist users in finding the correct model. Contributors are free to name these descriptors in a way that makes sense for the publication.

Specifying Descriptors at Different Levels

allometric operates at three levels arranged in a hierarchy. There are publications, model sets within publications and models within model sets. For convenience, contributors can define descriptors at any level, with the understanding that all descriptors defined at that level apply uniformly to all models lower in the hierarchy.

For example, the source code for the Brackett model installation specifies country and region at the publication-level.

brackett_1977 <- Publication(
  citation = bracket_1977_citation,
  descriptors = list(
    country = "US",
    region = "US-WA"
  )
)

This means that all models in brackett_1977 are constructed with data only from the state of Washington in the United States. The FixedEffectsSet, MixedEffectsSet and their respective FixedEffectsModel and MixedEffectsModel classes all have a descriptors argument that can be used for specifying descriptors at these levels. Refer to the Installing a Model vignette for more examples at these levels.