Load a locally installed table of allometric models

Source: R/load.R

This function loads all locally installed allometric models if they are downloaded and installed, if not run the install_models function. The result is of class model_tbl, which behaves very much like a tibble::tbl_df or a data.frame.

load_models()

Value

A model_tbl containing the locally installed models.

Details

Printing the head of allometric_models, we can see the structure of the data

allometric_models <- load_models()
#> Warning in readRDS(rds_path): strings not representable in native encoding will be translated to UTF-8
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'M<e1>laga' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>ceres' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
#> Warning in readRDS(rds_path): input string 'C<e1>diz' cannot be translated to UTF-8, is it valid in 'UTF-8'?
head(allometric_models)
#> # A tibble: 6 x 10
#>   id       model_type  country   region    taxa   pub_id       model      family_name covt_name pub_year
#>   <chr>    <chr>       <list>    <list>    <list> <chr>        <list>     <list>      <list>       <dbl>
#> 1 76ccc16a site index  <chr [1]> <chr [2]> <Taxa> barnes_1962  <FxdEffcM> <chr [1]>   <chr [2]>     1962
#> 2 cc2078aa site index  <chr [1]> <chr [2]> <Taxa> barrett_1978 <FxdEffcM> <chr [1]>   <chr [2]>     1978
#> 3 3955ab4f stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 4 48b4aecf stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 5 2fa084c2 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 6 7a585d5e stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006

The columns are:

  • id - A unique ID for the model.

  • model_type - The type of model (e.g., stem volume, site index, etc.)

  • country - The country or countries from which the model data is from.

  • region - The region or regions (e.g., state, province, etc.) from which the model data is from.

  • taxa - The taxonomic specification of the trees that are modeled.

  • model - The model object itself.

  • pub_id - A unique ID representing the publication.

  • family_name - The names of the contributing authors.

  • covt_name - The names of the covariates used in the model.

  • pub_year - The publication year.

Models can be searched by their attributes. Note that some of the columns are list columns, which contain lists as their elements. Filtering on data in these columns requires the use of purrr::map_lgl which is used to determine truthiness of expressions for each element in a list column. While this may seem complicated, we believe the nested data structures are more descriptive and concise for storing the models, and users will quickly find that searching models in this way can be very powerful.

Finding Contributing Authors

Using purr::map_lgl to filter the family_name column, we are able to find publications that contain specific authors of interst. For example, we may want models only authored by "Hann". This is elementary to do in allometric:

hann_models <- dplyr::filter(
 allometric_models,
 purrr::map_lgl(family_name, ~ 'Hann' %in% .)
)

head(hann_models)
#> # A tibble: 6 x 10
#>   id       model_type  country   region    taxa   pub_id    model      family_name covt_name pub_year
#>   <chr>    <chr>       <list>    <list>    <list> <chr>     <list>     <list>      <list>       <dbl>
#> 1 8970949f stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 2 0d53539a stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 3 0d109f2c stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 4 86dcc7ff stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 5 037a7989 stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 6 02614f74 stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
nrow(hann_models)
#> [1] 87

Picking apart the above code block, we see that we are using the standard dplyr::filter function on the allometric_models dataframe. The second argument is a call using purrr:map_lgl, which will map over each list (contained as elements in the family_names column). The second argument to this function, ~ 'Hann' %in% . is itself a function that checks if 'Hann' is in the current list. Imagine we are marching down each row of allometric_models, . represents the element of family_names we are considering, which is itself a list of author names.

Finding First Authors

Maybe we are only interested in models where 'Hann' is the first author. Using a simple modification we can easily do this.

hann_first_author_models <- dplyr::filter(
  allometric_models,
  purrr::map_lgl(family_name, ~ 'Hann' == .[[1]])
)

head(hann_first_author_models)
#> # A tibble: 6 x 10
#>   id       model_type  country   region    taxa   pub_id    model      family_name covt_name pub_year
#>   <chr>    <chr>       <list>    <list>    <list> <chr>     <list>     <list>      <list>       <dbl>
#> 1 8970949f stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 2 0d53539a stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 3 0d109f2c stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 4 86dcc7ff stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 5 037a7989 stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
#> 6 02614f74 stem volume <chr [1]> <chr [2]> <Taxa> hann_1978 <FxdEffcM> <chr [2]>   <chr [2]>     1978
nrow(hann_first_author_models)
#> [1] 50

We can see that 'Hann' is the first author for 50 models in this package.

Finding Models for a Given Species

One of the most common things people need is a model for a particular species. For this, we must interact with the taxa column. For example, to find models for the Pinus genus we can use

pinus_models <- dplyr::filter(
 allometric_models,
 purrr::map_lgl(taxa, ~ "Pinus" %in% .)
)

head(pinus_models)
#> # A tibble: 6 x 10
#>   id       model_type  country   region    taxa   pub_id       model      family_name covt_name pub_year
#>   <chr>    <chr>       <list>    <list>    <list> <chr>        <list>     <list>      <list>       <dbl>
#> 1 cc2078aa site index  <chr [1]> <chr [2]> <Taxa> barrett_1978 <FxdEffcM> <chr [1]>   <chr [2]>     1978
#> 2 502152d1 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 3 3fb70119 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 4 925de182 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 5 910dddb1 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
#> 6 5b3e21e7 stem height <chr [1]> <chr [3]> <Taxa> barrett_2006 <FxdEffcM> <chr [1]>   <chr [1]>     2006
nrow(pinus_models)
#> [1] 352

Users can also search with a specific taxon, which allows a full specification from family to species. For example, if we want models that apply to Ponderosa pine, first declare the necessary taxon, then use it to filter as before

ponderosa_taxon <- Taxon(
 family = "Pinaceae", genus = "Pinus", species = "ponderosa"
)

ponderosa_models <- dplyr::filter(
 allometric_models,
 purrr::map_lgl(taxa, ~ ponderosa_taxon %in% .)
)

nrow(ponderosa_models)
#> [1] 57

Finding a Model with Specific Data Requirements

We can even check for models that contain certain types of data requirements. For example, the following block finds diameter-height models, specifically models that use diameter outside bark at breast height as the only covariate. The utility here is obvious, since many inventories are vastly limited by their available tree measurements.

dia_ht_models <- dplyr::filter(
    allometric_models,
    model_type == 'stem height',
    purrr::map_lgl(covt_name, ~ length(.)==1 & .[[1]] == 'dsob'),
)

nrow(dia_ht_models)
#> [1] 285

Breaking this down, we have the first condition model_type=='stem_height' selecting only models concerned with stem heights as a response variable. The second line maps over each element of the covt_name column, which is a character vector. The . represents a given character vector for that row. First, we ensure that the vector is only one element in size using length(.)==1, then we ensure that the first (and only) element of this vector is equal to 'dsob', (diameter outside bark at breast height). In this case, 285 are available in the package.

Finding a Model for a Region

By now the user should be sensing a pattern. We can apply the exact same logic as the Finding Contributing Authors section to find all models developed using data from US-OR

us_or_models <- dplyr::filter(
    allometric_models,
    purrr::map_lgl(region, ~ "US-OR" %in% .),
)

nrow(us_or_models)
#> [1] 537

We can see that 537 allometric models are defined for the state of Oregon, US.