There are four different “levels” of the hierarchy in Soil Taxonomy that are represented by letter codes:
In the SoilTaxonomy package the
level argument is used by some functions to specify output for a target level within the hierarchy. Other functions determine
level by comparison against known taxa or codes. This vignette covers the basics of how taxon letter code conversion to and from taxonomic names is implemented.
taxon_to_taxon_code converts a taxon name (Soil Order, Suborder, Great Group, or Subgroup) to a letter code that corresponds to the logical position of that taxon in the Keys to Soil Taxonomy.
Gelisols are the first Soil Order to key out and are given letter code “A”
taxon_to_taxon_code("gelisols") #> gelisols #> "A"
The number of letters in a taxon code corresponds to the
level of that taxon. Histels are the first Suborder to key out in the Gelisols key (A), so they are given two letter code “AA”
taxon_to_taxon_code("histels") #> histels #> "AA"
For each “step” in each key, the letter codes are “incremented” by one.
Glacistels are the second Great Group in the Histels key (AA), so they have the three letter code “AAB”.
taxon_to_taxon_code("glacistels") #> glacistels #> "AAB"
Typic subgroups, by convention, are the last subgroup to key out in a Great Group.
taxon_to_taxon_code("typic glacistels") #> typic glacistels #> "AABC"
Since Typic Glacistels have code
"AABC" we can infer that there are three taxa in the Glacistels key with codes
This follows for Great Groups with many more subgroups. In case a Great Group has more than 26 subgroups within it, a fifth lowercase letter code is used to “extend” the ability to increment the code beyond 26.
An example of where this is needed is in the Haploxerolls key where the Typic subgroup has code
taxon_to_taxon_code("typic haploxerolls") #> typic haploxerolls #> "IFFZh"
From this code we infer that the Haploxerolls key has \(26+8=34\) subgroups corresponding to the range from
We can use a vector of letter codes to do the inverse operation with
Above we determined the Glacistels Key contains three taxa with codes
"AABC". Let’s convert those codes to taxon names.
We can infer from the length of the four-letter codes that all of the above are subgroup-level taxa.
taxon_to_level confirms this.
taxon_to_level(c("Hemic Glacistels","Sapric Glacistels","Typic Glacistels")) #>  "subgroup" "subgroup" "subgroup"
taxon_to_level can also identify a fifth (lower-level) family tier (
level="family"). Soil family differentia are not handled in the Order to Subgroup keys. Family names are defined by concatenating comma-separated class names on to the subgroup. Classes used in family names are determined by specific keys and apply variably depending on the subgroup-level taxonomy.
For instance, the soil family
"Fine, mixed, semiactive, mesic Ultic Haploxeralfs" includes a particle-size class (
"fine"), a mineralogy class (
"mixed"), a cation exchange capacity (CEC) activity class (
"semiactive") and a temperature class (
taxon_to_level("Fine, mixed, semiactive, mesic Ultic Haploxeralfs") #>  "family"
A wrapper method around taxon letter code functionality is
Say that you have family-level taxon above and you want to determine the taxonomy at a higher (less detailed) level. You can determine what to remove (family and subgroup-level modifiers) to get the Great Group using
getTaxonAtLevel("Fine, mixed, semiactive, mesic Ultic Haploxeralfs", level = "greatgroup") #> Fine, mixed, semiactive, mesic Ultic Haploxeralfs #> "haploxeralfs"
If you request a more-detailed taxonomic level than what you start with, you will get an
For example, we request the subgroup from suborder (
"Folists") level taxon name which is undefined.
getTaxonAtLevel("Folists", level = "subgroup") #> Folists #> NA
Another wrapper method around taxon letter code functionality is
getParentTaxa. This function will enumerate the tiers above a particular taxon.
getParentTaxa("Fine, mixed, semiactive, mesic Ultic Haploxeralfs") #> $`Fine, mixed, semiactive, mesic Ultic Haploxeralfs` #> J JD JDG #> "Alfisols" "Xeralfs" "Haploxeralfs" #> JDGR #> "Ultic Haploxeralfs"
You can alternately specify
code argument instead of
getParentTaxa(code = "BAB") #> $BAB #> B BA #> "Histosols" "Folists"
And converting the internally used taxon codes to taxon names can be disabled with
convert = FALSE. This may be useful for certain applications.
For more general cases
decompose_taxon_code might be useful. This is a function used by many of the above methods that returns a nested list result containing the letter code hierarchy.
Another pair of functions that might be useful for comparing relative positions within Keys, or the number of “steps” that it takes to reach a particular taxon, is
preceding_taxon_codes returns a list of vectors containing all preceding codes.
For example, the
AA suborder key precedes
AB. And within the
preceding_taxon_codes("ABC") #> $ABC #>  "AA" "ABA" "ABB"
relative_taxon_code_position counts how many taxa key out before a taxon plus \(1\) (to get the taxon position).