Taxon Letter Codes in Soil Taxonomy

library(SoilTaxonomy)

taxon_to_taxon_code()

taxon_to_taxon_code() converts a taxon name (Soil Order,Suborder, Great Group, or Subgroup) to a letter code that corresponds tothe logical position of that taxon in the Keys to Soil Taxonomy.

Gelisols are the first Soil Order to key out and are givenletter code “A”

taxon_to_taxon_code("gelisols")#> gelisols#>      "A"

The number of letters in a taxon code corresponds to thelevel of that taxon.Histels are the firstSuborder to key out in theGelisols 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” byone.

Glacistels are thesecond Great Group in theHistels key (AA), so they have the threeletter code “AAB”.

taxon_to_taxon_code("glacistels")#> glacistels#>      "AAB"

Typic subgroups, by convention, are the last subgroup to keyout in a Great Group.

taxon_to_taxon_code("typic glacistels")#> typic glacistels#>           "AABC"

SinceTypic Glacistels have code"AABC" we caninfer that there are three taxa in theGlacistels key withcodes"AABA","AABB" and"AABC"

This follows for Great Groups with many more subgroups. In case aGreat Group has more than 26 subgroups within it, a fifth lowercaseletter code is used to “extend” the ability to increment the code beyond26.

An example of where this is needed is in theHaploxerollskey where theTypic subgroup has code"IFFZh".

taxon_to_taxon_code("typic haploxerolls")#> typic haploxerolls#>            "IFFZh"

From this code we infer that theHaploxerolls key has$26+8=34$subgroups corresponding to the range fromIFFA toIFFZplusIFFZa toIFFZh.

taxon_code_to_taxon()

We can use a vector of letter codes to do the inverse operation withtaxon_code_to_taxon().

Above we determined theGlacistels Key contains three taxawith codes"AABA","AABB" and"AABC". Let’s convert those codes to taxon names.

taxon_code_to_taxon(c("AABA","AABB","AABC"))#>                AABA                AABB                AABC#>  "Hemic Glacistels" "Sapric Glacistels"  "Typic Glacistels"

taxon_to_level()

We can infer from the length of the four-letter codes that all of theabove are subgroup-level taxa.taxon_to_level() confirmsthis.

taxon_to_level(c("Hemic Glacistels","Sapric Glacistels","Typic Glacistels"))#> [1] "subgroup" "subgroup" "subgroup"

taxon_to_level() can also identify a fifth (lower-level)family tier (level="family"). Soil familydifferentiae are not handled in the Order to Subgroup keys. Family namesare defined by concatenating comma-separated class names on to thesubgroup. Classes used in family names are determined by specific keysand 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("mesic")

taxon_to_level("Fine, mixed, semiactive, mesic Ultic Haploxeralfs")#> [1] "family"

getTaxonAtLevel()

A wrapper method around taxon letter code functionality isgetTaxonAtLevel().

Say that you have family-level taxon above and you want to determinethe taxonomy at a higher (less detailed) level. You can determine whatto remove (family and subgroup-level modifiers) to get the Great GroupusinggetTaxonAtLevel(level="greatgroup")

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 startwith, you will get anNA result.

For example, we request the subgroup from suborder("Folists") level taxon name which is undefined.

getTaxonAtLevel("Folists", level="subgroup")#> Folists#>      NA

getParentTaxa()

Another wrapper method around taxon letter code functionality isgetParentTaxa(). This function will enumerate the tiersabove 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 specifycode argument instead oftaxon.

getParentTaxa(code="BAB")#> $BAB#>           B          BA#> "Histosols"   "Folists"

And converting the internally used taxon codes to taxon names can bedisabled withconvert = FALSE. This may be useful forcertain applications.

getParentTaxa(code=c("BAA","BAB"), convert=FALSE)#> $BAA#> [1] "B"  "BA"#>#> $BAB#> [1] "B"  "BA"

decompose_taxon_code()

For more general casesdecompose_taxon_code() might beuseful. This is a function used by many of the above methods thatreturns a nested list result containing the letter code hierarchy.

decompose_taxon_code(c("BAA","BAB"))#> $BAA#> $BAA[[1]]#> [1] "B"#>#> $BAA[[2]]#> [1] "BA"#>#> $BAA[[3]]#> [1] "BAA"#>#>#> $BAB#> $BAB[[1]]#> [1] "B"#>#> $BAB[[2]]#> [1] "BA"#>#> $BAB[[3]]#> [1] "BAB"

preceding_taxon_codes() andrelative_taxon_code_position()

Other functions useful for comparing relative positions within Keys,or the number of “steps” that it takes to reach a particular taxon, arepreceding_taxon_codes() andrelative_taxon_code_position().

preceding_taxon_codes() returns a list of vectorscontaining all preceding codes.

For example, theAA suborder key precedesAB. And within theAB keyABA andABB precedeABC.

preceding_taxon_codes("ABC")#> $ABC#> [1] "AA"  "ABA" "ABB"

relative_taxon_code_position() counts how many taxa keyout before a taxon plus$1$(to getthe taxon position).

relative_taxon_code_position(c("A","AA","AAA","AAAA","AB","AAB","ABA","ABC","B","BA","BAA","BAB","BBA","BBB","BBC"))#>    A   AA  AAA AAAA   AB  AAB  ABA  ABC    B   BA  BAA  BAB  BBA  BBB  BBC#>    1    1    1    1    2    2    2    4    2    2    2    3    3    4    5