Tree Species Codings in ForestElementsR

1. Introduction

Unfortunately, the way how tree species are coded in forest data varies vastly among research institutions, forest administrations, and the likes. In order to make the package ForestElementsR broadly applicable, it requires a generic coding system that can cover any specific species coding system and allows to translate from one into the other. In contrast to what one might expect, this is not a trivial task, as most existing codings do include not only codes for single species, but also for species groups. These groups are rarely the same across different codings which causes certain issues to be covered by a useful generic coding system. Such a generic approach, in addition, requires to be open to include any desired additional species and specific codings.

2. Where to find things and what they are good for

Before I show how to actually work with species codings in ForestElementsR, I will talk about where to find all implemented codings in the package. For the code examples below to work, you will need to attach ForestElementsR itself, and the packages tibble, dplyr, and ggplot2 from the tidyverse which make handling and output more convenient.

library(ForestElementsR)
library(tibble)
library(dplyr)
library(ggplot2)

2.1 The species master table

The data.frame (actually, a tibble) species_master_table is the most important part of the generic species coding system. Any single species to be included in any specific coding must be absolutely listed here, as the species master table serves as the common reference for all implemented codings. Conversely, specific species codings do not need to comprise all species provided in the species master table. In order to view this table it is only necessary to type its name:

species_master_table
#> # A tibble: 96 × 6
#>    genus species_no deciduous_conifer name_sci               name_eng   name_ger
#>    <chr> <chr>      <chr>             <chr>                  <chr>      <chr>   
#>  1 abies 001        conif             Abies alba             silver fir Tanne   
#>  2 abies 002        conif             Abies grandis          Oregon fir Große K…
#>  3 abies 003        conif             Abies balsamea         balsam fir Balsamt…
#>  4 abies 004        conif             Abies concolor         white fir  Kolorad…
#>  5 abies 005        conif             Abies concolor lowiana Sierra wh… Sierra-…
#>  6 abies 006        conif             Abies amabilis         red fir    Purpurt…
#>  7 abies 007        conif             Abies firma            Momi fir   Momi-Ta…
#>  8 abies 008        conif             Abies homolepis        Nikko fir  Nikko-T…
#>  9 abies 009        conif             Abies nordmanniana     Nordmann … Nordman…
#> 10 abies 010        conif             Abies procera          noble fir  Edeltan…
#> # ℹ 86 more rows

# Also show the tail of the table
species_master_table |> tail(10)
#> # A tibble: 10 × 6
#>    genus  species_no deciduous_conifer name_sci           name_eng      name_ger
#>    <chr>  <chr>      <chr>             <chr>              <chr>         <chr>   
#>  1 sorbus 001        decid             Sorbus aucuparia   rowan         Vogelbe…
#>  2 sorbus 002        decid             Sorbus torminalis  wild service… Elsbeere
#>  3 sorbus 003        decid             Sorbus aria        common white… Mehlbee…
#>  4 sorbus 004        decid             Sorbus intermedia  Swedish whit… Schwedi…
#>  5 sorbus 005        decid             Sorbus domestica   sorb tree     Speierl…
#>  6 tilia  001        decid             Tilia cordata      small-leaved… Winterl…
#>  7 tilia  002        decid             Tilia platyphyllos large-leaved… Sommerl…
#>  8 ulmus  001        decid             Ulmus glabra       Scots elm     Bergulme
#>  9 ulmus  002        decid             Ulmus minor        field elm     Feldulme
#> 10 ulmus  003        decid             Ulmus laevis       European whi… Flatter…

In contrast to specific codings (see below) the species master table must contain single species only, i.e. each row represents a species, never a group of species. Currently, it comprises 96 tree species. Let us have a look at the table’s anatomy:

The key fields of the species master table are genus and species_no. Together, they must be unique. Both are of type character. genus represents a specie’s genus name, always in lower case letters, and species_no is always a three-digit number with leading zeroes. This approach was chosen because of a few advantages: While genus names are usually stable, species names may change more often. Therefore, the species inside a genus are identified with a number instead of a name. New species can be easily added without the danger of running out of numbers and being thus forced to break the coding concept. For convenience, the table also contains the column deciduous_conifer which allows only for the two values conif and decid. This column is not part of the actual species key, but it it is intended for filtering purposes, and for all relevant forest tree species, the distinction between both groups should be biologically correct or at least practical. The three remaining fields, name_sci, name_eng, and name_ger contain the scientific, colloquial English, and colloquial German names of all species.

2.2 Specific species codings

2.2.1 General setup

All specific species codings implemented in ForestElementsR are stored in the tibble species_codings:

species_codings
#> # A tibble: 6 × 2
#>   species_coding    code_table       
#>   <chr>             <list>           
#> 1 master            <tibble [96 × 7]>
#> 2 tum_wwk_short     <tibble [96 × 7]>
#> 3 tum_wwk_long      <tibble [45 × 7]>
#> 4 ger_nfi_2012      <tibble [96 × 7]>
#> 5 bavrn_state       <tibble [96 × 7]>
#> 6 bavrn_state_short <tibble [96 × 7]>

Each row in this tibble represents a specific coding; hereby the column species_coding provides the coding’s name, and the column code_table provides an own tibble that defines the coding and links it to the species master table. Currently, there are six codings implemented (master, tum_wwk_short, tum_wwk_long, ger_nfi_2012, bavrn_state, bavrn_state_short). We use the coding tum_wwk_short for explaining the implementation. This species coding is used for many purposes at the Chair of Forest Growth and Yield Science at the Technical University of Munich. It comprises a small set of the most important tree species in Central Europe only, while all other species are attributed to three larger container groups. In order to see the coding table, it could be accessed by usual indexing of the tibble species_coding, but it is more convenient to use the function fe_species_get_coding_table which needs to be called with the name of the desired coding:

fe_species_get_coding_table("tum_wwk_short")
#> # A tibble: 96 × 7
#>    species_id genus      species_no deciduous_conifer name_sci name_eng name_ger
#>    <chr>      <chr>      <chr>      <chr>             <chr>    <chr>    <chr>   
#>  1 1          picea      001        conif             Picea a… Norway … Fichte  
#>  2 2          abies      001        conif             Abies a… silver … Tanne   
#>  3 3          pinus      001        conif             Pinus s… Scots p… Kiefer  
#>  4 4          larix      001        conif             Larix d… Europea… Europäi…
#>  5 5          fagus      001        decid             Fagus s… Europea… Buche   
#>  6 6          quercus    001        decid             Quercus… peduncu… Eiche (…
#>  7 6          quercus    002        decid             Quercus… peduncu… Eiche (…
#>  8 7          pseudotsu… 001        conif             Pseudot… Douglas… Douglas…
#>  9 8          acer       001        decid             aliae d… other h… Sonstig…
#> 10 8          acer       002        decid             aliae d… other h… Sonstig…
#> # ℹ 86 more rows

Clearly, this table closely resembles the species master table, as they have in common the columns genus, species_no, deciduous_conifer, name_sci, name_eng, and name_ger. Most importantly, however, there is the additional column species_id. This column contains the actual coding, and it is always of type character, even if the coding is exlusively consisting of numbers. Such a coding table is not required to comprise all species available in the species master table, but it must not contain any species which is not included there. In other words, a coding table is not allowed to contain any combination of genus and species_no which is not contained in the species master table. The species names, however, may differ from those in the master table in order to allow e.g. for regional colloquial naming preferences or, more importantly, for naming species groups which, by definition, do not exist in the master table. Let’s have a view on the coding in compact form:

fe_species_get_coding_table("tum_wwk_short") |>
  select(species_id, name_eng) |> # English names only for clarity
  distinct()
#> # A tibble: 10 × 2
#>    species_id name_eng                       
#>    <chr>      <chr>                          
#>  1 1          Norway spruce                  
#>  2 2          silver fir                     
#>  3 3          Scots pine                     
#>  4 4          European larch                 
#>  5 5          European beech                 
#>  6 6          pedunculate/sessile oak (group)
#>  7 7          Douglas fir                    
#>  8 8          other hardwood                 
#>  9 9          soft deciduous wood            
#> 10 10         other conifers

As it is easily visible in this display, the coding distinguishes only ten species (groups). From the names, it can be already guessed which species_id’s refer to single species and which to groups, but we should use R to find this out unambiguously:

fe_species_get_coding_table("tum_wwk_short") |>
  group_by(species_id, name_eng) |>
  summarise(n_species = n()) |>
  arrange(as.numeric(species_id)) # not required, but output is nicely sorted
#> `summarise()` has grouped output by 'species_id'. You can override using the
#> `.groups` argument.
#> # A tibble: 10 × 3
#> # Groups:   species_id [10]
#>    species_id name_eng                        n_species
#>    <chr>      <chr>                               <int>
#>  1 1          Norway spruce                           1
#>  2 2          silver fir                              1
#>  3 3          Scots pine                              1
#>  4 4          European larch                          1
#>  5 5          European beech                          1
#>  6 6          pedunculate/sessile oak (group)         2
#>  7 7          Douglas fir                             1
#>  8 8          other hardwood                         41
#>  9 9          soft deciduous wood                    10
#> 10 10         other conifers                         37

Clearly, every species_id with n_species > 1 actually represents a group of tree species. Let us look at the smallest group (species_id 6), which comprises only two species:

fe_species_get_coding_table("tum_wwk_short") |>
  select(species_id, genus, species_no, name_eng) |>
  filter(species_id == "6")
#> # A tibble: 2 × 4
#>   species_id genus   species_no name_eng                       
#>   <chr>      <chr>   <chr>      <chr>                          
#> 1 6          quercus 001        pedunculate/sessile oak (group)
#> 2 6          quercus 002        pedunculate/sessile oak (group)

We see that the two species in this group are quercus 001 and quercus 002, but the colloquial species name in the coding table is the group name only. In order to find out the species names, we can obtain them from the species master table with the help of genus and species_no:

species_master_table |>
  filter(genus == "quercus" & species_no %in% c("001", "002")) |>
  select(-deciduous_conifer)
#> # A tibble: 2 × 5
#>   genus   species_no name_sci        name_eng        name_ger    
#>   <chr>   <chr>      <chr>           <chr>           <chr>       
#> 1 quercus 001        Quercus robur   pedunculate oak Stieleiche  
#> 2 quercus 002        Quercus petraea sessile oak     Traubeneiche

2.1.2 Implemented codings

Six species codings are currently implemented. While their documentation in the package and can be accessed with ?species_codings, I list them also here:

master: This is the original species coding used by the package ForestElementsR. It contains each species from the species_master_table and no species groups. This coding corresponds directly to the species_master_table. Its species_id’s are the master table’s columns genus and species_no combined into one character string, separated by an underscore.
tum_wwk_short: This is one of two codings in use at the Chair of Forest Growth and Yield Science at the Technical University of Munich. It defines only a small set of single species explicitly (the most important ones in Central Europe), while all other species are attributed to a few large container groups.
tum_wwk_long: This is one of two codings in use at the Chair of Forest Growth and Yield Science at the Technical University of Munich. It defines a larger set of single species than the tum_wwk_short coding. In its original version, this coding contains several species groups, but most of these groups are ambiguous as they include species for which also a single code is provided. These ambiguous groups were not included in this package.
bavrn_state: This species coding is the coding used by the Bavarian State Forest Service.
bavrn_state_short: This coding that combines the species of bavrn_state into larger groups. These groups are typically used by the Bavarian State Forest Service in aggregated evaluations.
ger_nfi_2012: The ger_nfi_2012 species coding is the species coding used by the German National Forest Inventory of 2012 (Riedel et al. 2017).

3. Usage

Species codes as implemented in this package are vectors with a few special properties. Most users of the package, will work with species codes as columns in a data.frame (or tibble), where they are provided in parallel with other columns (i.e. vectors) that contain other tree information, e.g. tree diameters, heights, or spatial coordinates. For the sake of clarity, however, we demonstrate most applications for isolated vectors of species codes.

3.1 Creating a species code vector

For each implemented species coding there exists a user friendly function for constructing a vector of species. The naming convention for this function is fe_species_coding_name, whereby coding_name is the name of the desired coding as in the column species_coding in the tibble species_codings (see above). Thus, e.g. for creating a vector of tum_wwk_short or ger_nfi_2012 codes, one would use the functions fe_species_tum_wwk_short or fe_species_ger_nfi_2012, respectively. As their input, these functions require a vector of codes either in numeric or character format:

spec_ids_1 <- fe_species_tum_wwk_short(c(1, 1, 1, 5, 5, 5, 5, 3, 3, 8, 9, 8))
spec_ids_2 <- fe_species_ger_nfi_2012(
  c(10, 10, 10, 100, 100, 100, 100, 20, 20, 190, 290, 190)
)

spec_ids_1
#> <fe_species_tum_wwk_short[12]>
#>  [1] 1 1 1 5 5 5 5 3 3 8 9 8
spec_ids_2
#> <fe_species_ger_nfi_2012[12]>
#>  [1] 10  10  10  100 100 100 100 20  20  190 290 190

If the input vector contains codes which are not supported by the chosen coding, the attempt terminates with an error:

fe_species_tum_wwk_short(c(1, 321, 1, 9999))
#> Error: Code(s) 321, 9999 is/are not supported by species coding 'tum_wwk_short'
fe_species_ger_nfi_2012(c("100", "290", "Peter", "Paul", "Mary"))
#> Error: Code(s) Peter, Paul, Mary is/are not supported by species coding 'ger_nfi_2012'

For each implemented coding there exists a function is_fe_species_coding_name for checking whether an object is a vector of species codes of the requested class:

spec_ids <- c(1:10)
is_fe_species_tum_wwk_short(spec_ids)
#> [1] FALSE
spec_ids <- fe_species_tum_wwk_short(c(1:10))
is_fe_species_tum_wwk_short(spec_ids)
#> [1] TRUE
is_fe_species_bavrn_state(spec_ids)
#> [1] FALSE

NA values are in principle allowed in species code vectors, there may be, however, objects (like fe_stand, covered in an own vignette) which enforce species code vectors without NAs.

3.2 Display options

By default, species code vectors are displayed “as they are”, i.e. what we see are the original codes as in the column species_id in the corresponding coding’s table (see above). Sometimes, e.g. for creating output for third parties, the actual species names are preferable. The most convenient way to achieve that is to set the option fe_spec_lang which can take the values sci, eng, ger, and code. Let’s create four species code vectors

spec_ids_1 <- fe_species_tum_wwk_short(c(1, 1, 5, 5, 5, 5, 3, 3))
spec_ids_2 <- fe_species_ger_nfi_2012(c(100, 100, 20, 20, 30, 110))
spec_ids_3 <- fe_species_bavrn_state(c(60, 60, 30, 30, 84, 86))
spec_ids_4 <- fe_species_master(c("abies_001", "tilia_002", "ulmus_001"))

The default display is:

#> <fe_species_tum_wwk_short[8]>
#> [1] 1 1 5 5 5 5 3 3
#> <fe_species_ger_nfi_2012[6]>
#> [1] 100 100 20  20  30  110
#> <fe_species_bavrn_state[6]>
#> [1] 60 60 30 30 84 86
#> <fe_species_master[3]>
#> [1] abies_001 tilia_002 ulmus_001

With the option fe_spec_lang set on “sci”, the scientific species names are displayed:

options(fe_spec_lang = "sci") # Display scientific species names

spec_ids_1
#> <fe_species_tum_wwk_short[8]>
#> [1] Picea abies      Picea abies      Fagus sylvatica  Fagus sylvatica 
#> [5] Fagus sylvatica  Fagus sylvatica  Pinus sylvestris Pinus sylvestris
spec_ids_2
#> <fe_species_ger_nfi_2012[6]>
#> [1] Fagus sylvatica  Fagus sylvatica  Pinus sylvestris Pinus sylvestris
#> [5] Abies alba       Quercus robur
spec_ids_3
#> <fe_species_bavrn_state[6]>
#> [1] Fagus sylvatica Fagus sylvatica Abies alba      Abies alba     
#> [5] Salix spec.     Alnus glutinosa
spec_ids_4
#> <fe_species_master[3]>
#> [1] Abies alba         Tilia platyphyllos Ulmus glabra

For printing the colloquial English species names, the option “eng” is the choice:

options(fe_spec_lang = "eng") # Display English species names

spec_ids_1
#> <fe_species_tum_wwk_short[8]>
#> [1] Norway spruce  Norway spruce  European beech European beech European beech
#> [6] European beech Scots pine     Scots pine
spec_ids_2
#> <fe_species_ger_nfi_2012[6]>
#> [1] European beech  European beech  Scots pine      Scots pine     
#> [5] silver fir      pedunculate oak
spec_ids_3
#> <fe_species_bavrn_state[6]>
#> [1] European beech European beech silver fir     silver fir     willow (group)
#> [6] Black alder
spec_ids_4
#> <fe_species_master[3]>
#> [1] silver fir        large-leaved lime Scots elm

In the same way, you can use options(fe_spec_lang = "ger") for having the German species names displayed. With options(fe_spec_lang = "code") or options(fe_spec_lang = NULL). If you do not want to work with such options, and want just a quick check of the species names corresponding to given codes, you could use the function format. It takes the species code vector to be displayed, and spec_lang, which can be “sci”, “eng”, “ger”, and “code” with exactly the same meanings as explained above. The output of format is never an fe_species coding object, but always a character vector (which is useful for some purposes):

format(spec_ids_1, spec_lang = "eng")
#> [1] "Norway spruce"  "Norway spruce"  "European beech" "European beech"
#> [5] "European beech" "European beech" "Scots pine"     "Scots pine"
format(spec_ids_2, spec_lang = "sci")
#> [1] "Fagus sylvatica"  "Fagus sylvatica"  "Pinus sylvestris" "Pinus sylvestris"
#> [5] "Abies alba"       "Quercus robur"
format(spec_ids_3, spec_lang = "code")
#> [1] "60" "60" "30" "30" "84" "86"
format(spec_ids_4, spec_lang = "ger")
#> [1] "Tanne"       "Sommerlinde" "Bergulme"

Note that the names for display are always taken from the specific coding’s table, not from the species master table. Be also aware that such species names are not the codes themselves. This means, you cannot generate a species code vector from a vector of species names:

spec_names <- c("Abies alba", "Picea abies")
fe_species_ger_nfi_2012(spec_names)
#> Error: Code(s) Abies alba, Picea abies is/are not supported by species coding 'ger_nfi_2012'

When assigning new values to elements of a species coding vector, the safest way to do so is to provide the new values as an instance of the same class. But with all other values, an attempt will be made to convert them into an instance of the goal class. If this is not possible, the assignment does not take place, and an error is thrown.

spec_vec <- fe_species_bavrn_state(c("10", "10", "10", "50", "50", "50"))
format(spec_vec, "eng")
#> [1] "Norway spruce" "Norway spruce" "Norway spruce" "Douglas fir"  
#> [5] "Douglas fir"   "Douglas fir"

# Safest way, same class on both sides of the '<-'
spec_vec[3] <- fe_species_bavrn_state("40")
is_fe_species_bavrn_state(spec_vec)
#> [1] TRUE
format(spec_vec, "eng")
#> [1] "Norway spruce"  "Norway spruce"  "European larch" "Douglas fir"   
#> [5] "Douglas fir"    "Douglas fir"

# Character vector is converted
spec_vec[3:4] <- c("40", "70")
is_fe_species_bavrn_state(spec_vec)
#> [1] TRUE
format(spec_vec, "eng")
#> [1] "Norway spruce"                   "Norway spruce"                  
#> [3] "European larch"                  "pedunculate/sessile oak (group)"
#> [5] "Douglas fir"                     "Douglas fir"

# Numerical vector is converted
spec_vec[3:4] <- c(60, 87)
is_fe_species_bavrn_state(spec_vec)
#> [1] TRUE
format(spec_vec, "eng")
#> [1] "Norway spruce"  "Norway spruce"  "European beech" "noble hardwood"
#> [5] "Douglas fir"    "Douglas fir"

# Species code not supported by goal coding - no assignment and error
spec_vec[1:2] <- c("3333", "12")
#> Error: Code(s) 3333 is/are not supported by species coding 'bavrn_state'
is_fe_species_bavrn_state(spec_vec)
#> [1] TRUE
format(spec_vec, "eng")
#> [1] "Norway spruce"  "Norway spruce"  "European beech" "noble hardwood"
#> [5] "Douglas fir"    "Douglas fir"

# Vectors of other species codings are converted, if possible
spec_vec[5:6] <- fe_species_tum_wwk_short(c("3", "3")) # "3" Scots pine in rhs
# coding
is_fe_species_bavrn_state(spec_vec)
#> [1] TRUE
format(spec_vec, "code") # "3" becomes "20" ...
#> [1] "10" "10" "60" "87" "20" "20"
format(spec_vec, "eng") # ... which is Scots pine in the goal coding
#> [1] "Norway spruce"  "Norway spruce"  "European beech" "noble hardwood"
#> [5] "Scots pine"     "Scots pine"

3.3 Species code conversions

For each implemented species coding there is a function as_fe_species_coding_name which tries to convert an object of any other given species coding implemented in ForestElementsR into an instance of the goal object. You can use it also for converting numeric or character vectors (as an alternative to fe_species_coding_name), but the interesting feature is the conversion between different codings:

spec_ids <- as_fe_species_tum_wwk_short(c("1", "3", "5"))
as_fe_species_ger_nfi_2012(spec_ids) |> format("eng")
#> [1] "Norway spruce"  "Scots pine"     "European beech"

When the initial species code vector contains codes which belong to the same species group in the goal coding, information is lost when doing the conversion. This is a backward ambiguous cast. In such a case, the conversion is executed, but a warning is issued.

spec_ids_1 <- as_fe_species_ger_nfi_2012(c("170", "150", "140"))
spec_ids_1 |> format("eng")
#> [1] "elm (spec.)"    "lime (spec.)"   "sycamore maple"

# Backward ambiguous cast (possibly, but with information loss)
spec_ids_2 <- as_fe_species_tum_wwk_short(spec_ids_1)
#> Warning: Cast loses information. Goal code(s) 8 correspond to 3 original
#> code(s).
spec_ids_2 |> format("eng")
#> [1] "other hardwood" "other hardwood" "other hardwood"

Conversions with no match in the goal coding terminate with an error:

spec_ids <- as_fe_species_bavrn_state(c("11", "11", "11"))
spec_ids |> format("eng")
#> [1] "Serbian spruce" "Serbian spruce" "Serbian spruce"

# No Serbian spruce in the tum_wwk_long coding
spec_ids |> as_fe_species_tum_wwk_long()
#> Error: Original code(s) 11 has/have no (complete) match in goal species coding.

Forward ambiguous casts occur when one code in the initial code vector has several matches in the goal coding. If this is the case, execution terminates, and an error is thrown:

# Each of these codes comprises many single species
spec_ids <- fe_species_tum_wwk_short(c("8", "9", "10"))
spec_ids |> format("eng")
#> [1] "other hardwood"      "soft deciduous wood" "other conifers"

# Conversion attempt terminates with error
spec_ids |> as_fe_species_ger_nfi_2012()
#> Error: Ambiguous cast attempt. Original code(s) 10, 8, 9 correspond(s) to 12, 23, 9 goal code(s).

# Similar
as_fe_species_master(fe_species_ger_nfi_2012("90"))
#> Error: Ambiguous cast attempt. Original code(s) 90 correspond(s) to 8 goal code(s).

Note that the operability of a species coding cast is checked for each single conversion attempt, because it does depend on the single species codes to be converted. I.e. some conversions between the same codings will work well while others fail:

# Conversion from tum_wwk_short to ger_nfi_2012 - works
spec_ids_1 <- fe_species_tum_wwk_short(c("1", "3", "5"))
spec_ids_1 |> format("eng")
#> [1] "Norway spruce"  "Scots pine"     "European beech"

spec_ids_2 <- as_fe_species_ger_nfi_2012(spec_ids_1)
spec_ids_2 |> format("eng")
#> [1] "Norway spruce"  "Scots pine"     "European beech"

# Conversion from tum_wwk_short to ger_nfi_2012 - fails
spec_ids_1 <- fe_species_tum_wwk_short(c("8", "9", "10"))
spec_ids_1 |> format("eng")
#> [1] "other hardwood"      "soft deciduous wood" "other conifers"

spec_ids_2 <- as_fe_species_ger_nfi_2012(spec_ids_1)
#> Error: Ambiguous cast attempt. Original code(s) 10, 8, 9 correspond(s) to 12, 23, 9 goal code(s).

In some cases one might want to extract the character vector of species codes out of an fe_species_coding_name vector. This is possible either with unclass or with vctrs::vec_data (the species codings are implemented based on the package vctrs).

spec_ids <- fe_species_ger_nfi_2012(c("10", "10", "100", "170"))
spec_ids
#> <fe_species_ger_nfi_2012[4]>
#> [1] 10  10  100 170

chars_1 <- unclass(spec_ids)
chars_1
#> [1] "10"  "10"  "100" "170"
chars_2 <- vctrs::vec_data(spec_ids)
chars_2
#> [1] "10"  "10"  "100" "170"

is_fe_species_ger_nfi_2012(chars_1)
#> [1] FALSE
is_fe_species_ger_nfi_2012(chars_2)
#> [1] FALSE

is.character(chars_1)
#> [1] TRUE
is.character(chars_2)
#> [1] TRUE

3.4 Practical examples

As mentioned above, species codes do typically not come as isolated vectors, but as columns in a data frame (tibble). We isolate one such data frame from the fe_stand object selection_forest_1_fe_stand which is among the example data that come with the package ForestElementsR:

dat <- selection_forest_1_fe_stand$trees |> select(
  tree_id, species_id, time_yr, dbh_cm, height_m
)
dat
#> # A tibble: 283 × 5
#>    tree_id species_id    time_yr dbh_cm height_m
#>    <chr>   <tm_wwk_shrt>   <dbl>  <dbl>    <dbl>
#>  1 1       1                2022    9.6      9.5
#>  2 2       1                2022    9.1      8.5
#>  3 3       1                2022   11       10.9
#>  4 4       1                2022   24.9     23  
#>  5 5       1                2022   20.9     19.4
#>  6 6       1                2022    8.2      8.3
#>  7 7       1                2022   22.6     19.8
#>  8 8       1                2022   18.8     19  
#>  9 9       1                2022   27.8     26.2
#> 10 10      1                2022   26.8     25.8
#> # ℹ 273 more rows

Here, each row represents one tree, the column species_id represents species codes, and the other columns represent additional key fields (tree_id, time_yr) and tree data (dbh_cm, height_m). When the package tidyverse or tibble is attached, the tibble is displayed as shown below, and the abbreviation tm_wwk_shrt indicates, that the coding is tum_wwk_short. As by standard only the first ten lines are shown, we see only the species code “1”. For finding out if there are more species, we could use the function summary:

dat |> summary()
#>    tree_id          species_id    time_yr         dbh_cm         height_m    
#>  Length:283         1:130      Min.   :2022   Min.   : 7.00   Min.   : 7.20  
#>  Class :character   2: 98      1st Qu.:2022   1st Qu.: 9.90   1st Qu.:11.65  
#>  Mode  :character   5: 42      Median :2022   Median :17.50   Median :19.40  
#>                     8: 13      Mean   :2022   Mean   :21.01   Mean   :19.83  
#>                                3rd Qu.:2022   3rd Qu.:28.05   3rd Qu.:26.95  
#>                                Max.   :2022   Max.   :73.40   Max.   :39.30

Very similar as in a summary for a factor the summary for the column species_id provides the row counts for each of the four coded species. In order to display species names instead of the codes, we have to set the option fe_spec_lang (see also above):

# Set option to display colloquial English species names, and store the
# previous setting in opt_prev
opt_prev <- getOption("fe_spec_lang")
options(fe_spec_lang = "eng")

# Display dat
dat
#> # A tibble: 283 × 5
#>    tree_id species_id    time_yr dbh_cm height_m
#>    <chr>   <tm_wwk_shrt>   <dbl>  <dbl>    <dbl>
#>  1 1       Norway spruce    2022    9.6      9.5
#>  2 2       Norway spruce    2022    9.1      8.5
#>  3 3       Norway spruce    2022   11       10.9
#>  4 4       Norway spruce    2022   24.9     23  
#>  5 5       Norway spruce    2022   20.9     19.4
#>  6 6       Norway spruce    2022    8.2      8.3
#>  7 7       Norway spruce    2022   22.6     19.8
#>  8 8       Norway spruce    2022   18.8     19  
#>  9 9       Norway spruce    2022   27.8     26.2
#> 10 10      Norway spruce    2022   26.8     25.8
#> # ℹ 273 more rows

# Display a summary of dat
dat |> summary()
#>    tree_id                   species_id     time_yr         dbh_cm     
#>  Length:283         European beech: 42   Min.   :2022   Min.   : 7.00  
#>  Class :character   Norway spruce :130   1st Qu.:2022   1st Qu.: 9.90  
#>  Mode  :character   other hardwood: 13   Median :2022   Median :17.50  
#>                     silver fir    : 98   Mean   :2022   Mean   :21.01  
#>                                          3rd Qu.:2022   3rd Qu.:28.05  
#>                                          Max.   :2022   Max.   :73.40  
#>     height_m    
#>  Min.   : 7.20  
#>  1st Qu.:11.65  
#>  Median :19.40  
#>  Mean   :19.83  
#>  3rd Qu.:26.95  
#>  Max.   :39.30

# Reset option to previous value
options(fe_spec_lang = opt_prev)

Let’s assume, we want to know the mean stem volume per species (group) and its standard deviation. In order to achieve that, we require each tree’s volume first. This can be done with the function v_gri which requires the three inputs species_id, dbh_cm, and height_m. The function v_gri is originally designed to work with the species coding tum_wwk_short (as available in the example data), but it can process any input for species_id that can be converted into the former.

opt_prev <- getOption("fe_spec_lang")
options(fe_spec_lang = "eng")

dat <- dat |>
  mutate(v_cbm = v_gri(species_id, dbh_cm, height_m))

# Note that the summary of species_id does not preserve the original order of
# the codes (species are alphabetically sorted, dependent on language setting)
dat |> summary()
#>    tree_id                   species_id     time_yr         dbh_cm     
#>  Length:283         European beech: 42   Min.   :2022   Min.   : 7.00  
#>  Class :character   Norway spruce :130   1st Qu.:2022   1st Qu.: 9.90  
#>  Mode  :character   other hardwood: 13   Median :2022   Median :17.50  
#>                     silver fir    : 98   Mean   :2022   Mean   :21.01  
#>                                          3rd Qu.:2022   3rd Qu.:28.05  
#>                                          Max.   :2022   Max.   :73.40  
#>     height_m         v_cbm        
#>  Min.   : 7.20   Min.   :0.00996  
#>  1st Qu.:11.65   1st Qu.:0.03441  
#>  Median :19.40   Median :0.23213  
#>  Mean   :19.83   Mean   :0.65723  
#>  3rd Qu.:26.95   3rd Qu.:0.83518  
#>  Max.   :39.30   Max.   :6.97478

options(fe_spec_lang = opt_prev)

The summary reveals a wide range of volumes which is plausible, given the range of dbh and height values. For obtaining the mean volumes per species (group), we can use the dplyr functions group_by and summarise which work also with our species codings. We see from the summary below that e.g. Abies alba has the smallest mean stem volume which comes, however, with the highest standard deviation.

# Set option for displaying scientific species names
opt_prev <- getOption("fe_spec_lang")
options(fe_spec_lang = "sci")

dat |>
  group_by(species_id) |>
  summarise(
    mean_stem_volume_cbm = mean(v_cbm),
    sd_stem_volume_cbm = sd(v_cbm)
  )
#> # A tibble: 4 × 3
#>   species_id      mean_stem_volume_cbm sd_stem_volume_cbm
#>   <tm_wwk_shrt>                  <dbl>              <dbl>
#> 1 Picea abies                    0.669              0.926
#> 2 Abies alba                     0.553              1.14 
#> 3 Fagus sylvatica                0.805              0.829
#> 4 aliae deciduae                 0.855              0.533
# In contrast to summary, summarise keeps the original order of the species
# codes, no matter the language setting

options(fe_spec_lang = opt_prev)

Note, that plotting functions do currently not work with the species codings. Use the format function for such purposes:

# Note: Using simply 'format(species_id)' below would use the current setting
# of the option fe_spec_lang
dat |>
  ggplot() +
  geom_point(aes(x = dbh_cm, y = v_cbm, col = format(species_id, "eng"))) +
  scale_color_discrete("Species") +
  scale_x_log10() +
  scale_y_log10()

Stem volume over diameter by species in log-log display

4. Informations for developers

Most prominently, in the context of species codes a developer of the package ForestElementsR will want to add a new species coding. A few things have to be done in order to make that work. We mention these work steps first, and detail on them below:

If the coding contains new species, add them to the species master table
Add new species to the fe_species_master coding
Add the new coding to the species_coding tibble
Copy the R-source file of an existing coding and adapt it (easy!)
Add a species coding cast function to your new coding to the R-source file of each other coding (easy!)
Document the new coding (easy!)
Add your new coding to the automated tests for species codings (not difficult)
Never touch the source file fe_species_helper_functions.R if you do not exactly know what you are doing.

Before we get into the details, note that all species codings inherit from the vctrs_vctr class which is provided by the package vctrs:

fe_species_bavrn_state("30") |> class()
#> [1] "fe_species_bavrn_state" "vctrs_vctr"
fe_species_ger_nfi_2012("20") |> class()
#> [1] "fe_species_ger_nfi_2012" "vctrs_vctr"
fe_species_tum_wwk_long("87") |> class()
#> [1] "fe_species_tum_wwk_long" "vctrs_vctr"
fe_species_tum_wwk_short("7") |> class()
#> [1] "fe_species_tum_wwk_short" "vctrs_vctr"
fe_species_master("abies_004") |> class()
#> [1] "fe_species_master" "vctrs_vctr"

While this does not allow for building species_coding super- and subclasses, which would be an obvious feature for a system of species codings, it has a very convenient way of supporting casts between different classes. As this is a key requirement of our implementation, we decided to design a vctrs based solution. But now, let’s talk about the above-mentioned steps in somewhat more detail.

4.1 Check for new species and add them to the species master table

If you plan to implement a new species coding, care fully check the species master table if there is any species in your coding which is not covered which is not listed in the master table, yet. If it is not, you can add it as a new row. Probably, the genus where your new species belongs to is already present. In this case simply give your entry the desired genus name (always lowercase!) and use for the species_no entry the greatest existing species number plus one (always three digit character string with leading zeroes). Fill the other field of the row with the correct species names and the deciduous_conifer information. In case, the required genus is not yet covered, introduce it to the table and give your entry the species_no ‘001’. Note that NA values are not allowed at all in the species master table.

However, you must by any means avoid to have the same species twice in the species master table. Maybe, the species is listed, but under a different name than that you are used to. In this case, remember, you can choose different names in your specific coding table, as long as the link to the correct entry in the species master table by genus and species_no is existing. If you feel a scientific name in the species master table is outdated or that colloquial names could be better chosen, please contact the maintainers of ForestElementsR before making any changes.

4.2 Add new species to the coding fe_species_master

By definition, the coding fe_species_master is the coding that mirrors the contents of the species master table. So, if you have added a new species to the master table, you must also add it to the coding. Inside the tibble species_codings, access the code_table for the species_coding master and add the species. See here for an explanation of the tibble species_codings and its substructures.

4.3 Add the new species coding to the tibble species_codings

First, give your new coding a name which is short, but informative enough. See our examples here. Add a new row to the tibble species_codings and insert the name you chose in the field species_coding. In the second field (code_table) insert a tibble with exactly the structure as explained in Section 2.2. In the column species_id you must provide your own codes (always character, even if they are numbers only). The link to the species master table must be guaranteed with the entries in genus and species_no. All your species must be listed in the master table, but your coding is not required to cover all species of the master table. The species names in your code table may differ from those in the master table; when displaying names, those of your code table are used. Note that no NA’s at all are allowed in your code table.

if you give the same species_id to several species in the code table, these species will be treated as a group. As species name in the code table, you must then use the same group name for all these species. Look into the existing codings for examples, e.g. the species_id’s 8, 9, and 10 in the coding tum_wwk_short.

4.4 Copy the R-source file of an existing coding and adapt it

Now, you must provide the functions in order to make your new coding workable. While this sounds difficult, it is actually really easy. Before we explain how to do that, be aware of the following naming convention:

The S3 class covering your species coding must be named “fe_species_” followed by the name of your coding.

In other words, if your new coding is named john_doe_coding (and that is also exactly what you called it in the tibble species codings), then your S3 class name must be fe_species_john_doe_coding.

First, copy the R source file of one of the implemented codings, and give it the name of your S3 class (in our example fe_species_john_doe_coding.R). Note, that the files with the existing implementation follow this naming convention. For this explanation, I assume you have copied and renamed the file fe_species_tum_wwk_short.R. You could now literally get an almost working implementation by automatic search for the term fe_species_tum_wwk_short and replace it with fe_species_john_doe_coding, however, if you must, do it function by function, not for the whole file in one go. Note, that you must also exchange the terms in the documentation above each function, not only in the R code itself. Important: you will also have to adjust the examples by using species codes which are actually covered by your coding. Otherwise, the examples will not work, and the package will not pass R CMD check.

From top to bottom of the file fe_species_tum_wwk_short.R, the functions to update are:

the constructor new_fe_species_tum_wwk_short
is_fe_species_tum_wwk_short
the formatter format.fe_species_tum_wwk_short
summary.fe_species_tum_wwk_short
vec_ptype_abbr.fe_species_tum_wwk_short; here you should also replace the provided abbreviation for the coding name by one of your own (this abbreviation is printed e.g. as type information below the column head if your coding is a column of a tibble)
validate_fe_species_tum_wwk_short
fe_species_tum_wwk_short, the function users should use for constructing an instance of a species coding object
vec_proxy_order.fe_species_tum_wwk_short; guarantees always the same order if species id’s are to be sorted. The order will not change, even if the option fe_spec_lang is changed
Now comes a block of species type casting functions. Their names are built like .e.g vec_cast.fe_species_tum_wwk_short.fe_species_ger_nfi_2012, which means vec_cast.fe_species_GOAL_CODING_NAME.fe_species_FROM_CODING_NAME. These functions are very short, and some of them use the coding names internally. If you are qualified to work on this R package, you understand immediately, what to adapt. In general, in the function names, you must replace tum_wwk_short as the goal coding with john_doe_coding, In addition, you must copy one of the functions which casts between two species codings, and adapt it so that it casts from tum_wwk_short to john_doe_coding, i.e. name it vec_cast.fe_species_john_doe_coding.fe_species_tum_wwk_short, and make the obvious adaptions in the function’s body.
as_fe_species_tum_wwk_short which is the actual functions users call for casts between codings

4.5 Add a species coding cast function to each other coding

In the previous step, you have placed a vec_cast function that casts other codings into your new coding in the implementation of the new coding. Now, you have to add such a function that casts from your coding into another coding to the implementation of each other coding. In other words, the implementation of fe_species_tum_wwk_short requires a function called vec_cast.fe_species_tum_wwk_short.fe_species_john_doe_coding, and the implementation of fe_species_ger_nfi_2012 requires a function vec_cast.fe_species_ger_nfi_2023.fe_species_john_doe_coding, and so on.

4.6 Document the new coding

Clearly, when implementing your new species coding by editing an existing source file, you must adapt the existing documentation you find there to the new requirements. However, you must not forget to add your coding to the general documentation of species codings of the package. You find this in the file data_species_codings.R which is Roxygen2 code. Add a short description and examples in the same style as you find it for the other codings.

4.7 Add your new coding to the automated tests for species codings

The package ForestElementsR comprises a suite of automated tests. You must add your now coding also there. You find the implementations of the tests in the subdirectory /tests/testhat/; the files you need are called test_species_coding_consistency, and test_species_coding_casts. See how the tests for the other codings are implemented, and follow these examples.

4.8 Never touch the source file fe_species_helper_functions.R

The functions in the source file fe_species_helper_functions.R were very carefully crafted, and they provide the common technical background for existing and future species codings implemented in the package ForestElementsR. If you fiddle around there without knowing 500% exactly what you are doing, you will almost certainly goof it up.

References

Riedel, T., P. Hennig, F. Kroiher, H. Polley, F. Schmitz, and Schwitzgebel F. 2017. Die Dritte Bundeswaldinventur (BWI 2012). Inventur- Und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.