# Family-level Taxonomic Classes

    library(SoilTaxonomy)

## `parse_family()`

The function `parse_family()` provides a way to separate lower taxonomic levels (“family-level classes”) from the higher taxonomic levels (Order, Suborder, Great Group, and Subgroup) in a soil taxon name.

The user provides a vector of family names, and the result is a `data.frame` containing:

- `family` (input)
- `subgroup` (taxonomic subgroup)
- `subgroup_code` (four or five letter code for subgroup)
- `class_string` (comma-separated family-level class string in taxon name)
- `classes_split` (list column containing `class_string`; split using `","` as delimiter)

    parse_family("fine-loamy, mixed, semiactive, mesic ultic haploxeralfs")
    #>                                                    family
    #> 1 fine-loamy, mixed, semiactive, mesic ultic haploxeralfs
    #>                                                 taxclname          taxonname
    #> 1 fine-loamy, mixed, semiactive, mesic ultic haploxeralfs ultic haploxeralfs
    #>   subgroup_code code                         class_string classes_split
    #> 1          JDGR JDGR fine-loamy, mixed, semiactive, mesic  fine-loa....
    #>   taxpartsize taxpartsizemod taxminalogy taxceactcl taxreaction taxtempcl
    #> 1  fine-loamy             NA       mixed semiactive          NA     mesic
    #>   taxfamhahatmatcl taxfamother          taxsubgrp  taxgrtgroup taxsuborder
    #> 1               NA        <NA> Ultic Haploxeralfs Haploxeralfs     Xeralfs
    #>   taxorder
    #> 1 Alfisols

## `ST_family_classes`

The `ST_family_classes` data set provides information on the lower taxonomic class names and the Keys used to determine what, if any, class to use for a particular soil.

This data set is a `data.frame` with the following columns:

- `classname` (class name used in Soil Taxonomy family name)
- `group` (simplified grouping of related classes/keys/criteria)
- `name` (name of relevant section from Keys to Soil Taxonomy)
- `chapter` (chapter number from Keys to Soil Taxonomy)
- `page` ([first] page number from Keys to Soil Taxonomy)
- `description` (narrative description of section; may not be present)
- `criteria` (criteria listed under “Required Characteristics”; may not be present)

    data("ST_family_classes")
    head(ST_family_classes)
    #>   DomainID   classname          group               name chapter page
    #> 1      126 glauconitic Mineral Family Mineralogy Classes      17  325
    #> 2      126     allitic Mineral Family Mineralogy Classes      17  325
    #> 3      126    amorphic Mineral Family Mineralogy Classes      17  325
    #> 4      126  carbonatic Mineral Family Mineralogy Classes      17  325
    #> 5      126      gypsic Mineral Family Mineralogy Classes      17  325
    #> 6      126 halloysitic Mineral Family Mineralogy Classes      17  325
    #>                                                                                                                                                                                                                                                                                                                                                   description
    #> 1 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 2 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 3 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 4 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 5 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 6 The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #>   criteria
    #> 1
    #> 2
    #> 3
    #> 4
    #> 5
    #> 6

Here we determine the family-level classes for a single taxonomic family and match them to the class descriptions stored in `ST_family_classes` using `get_ST_family_classes()`. We set `parse_family(..., column_metadata=FALSE)` to not parse family components into corresponding NASIS domains (requires soilDB).

    f <- "fine-loamy, mixed, semiactive, mesic ultic haploxeralfs"
    family_classes <- parse_family(f, column_metadata = FALSE)$classes_split[[1]]

    get_ST_family_classes(classname = family_classes)
    #>     DomainID  classname          group
    #> 98       127 fine-loamy Mineral Family
    #> 20       126      mixed Mineral Family
    #> 179      520 semiactive Mineral Family
    #> 160      185      mesic Mineral Family
    #>                                                                 name chapter
    #> 98  Key to the Particle-Size and Substitute Classes of Mineral Soils      17
    #> 20                                                Mineralogy Classes      17
    #> 179                                 Cation-Exchange Activity Classes      17
    #> 160                                         Soil Temperature Classes      17
    #>     page
    #> 98   319
    #> 20   325
    #> 179  327
    #> 160  329
    #>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   description
    #> 98  This key, like other keys in this taxonomy, is designed in such a way that the reader makes the correct classification by going through the key systematically, starting at the beginning and eliminating one by one all classes that include criteria that do not fit the soil or layer in question. The class or substitute name for each layer within the control section must be determined from the key. If any two layers meet the criteria for strongly contrasting particle-size classes (listed below), the soil is named for that strongly contrasting class. If more than one pair meets the criteria for strongly contrasting classes, the soil is also in an aniso class named for the pair of adjacent classes that contrast most strongly. If the soil has none of the strongly contrasting classes, the weighted average soil materials within the particle-size control section generally determine the class. Exceptions are soils that are not strongly contrasting and that have a substitute class name for one or more parts of the control section. In these soils the class or substitute name of the thickest (cumulative) part within the control section is used to determine the family name.
    #> 20                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                The mineralogy of soils is known to be useful in making predictions about soil behavior and responses to management. Some mineralogy classes occur or are important only in certain taxa or particle-size classes, and others are important in all particle-size classes. A mineralogy class is assigned to all mineral soils, except for Quartzipsamments.
    #> 179                                                                                                                                                       The cation-exchange activity classes help in making interpretations about the nutrient-holding capacity of soils and their suites of colloids. The cation-exchange capacity is determined by NH4 OAc at pH 7 on the fine-earth fraction. The CEC of the organic matter, sand, silt, and clay is included in the determination. The criteria for the classes use ratios of CEC to the percent, by weight, of silicate clay, calculated by weighted average in the control section. In the following classes "clay" excludes clay-size carbonates. Percent carbonate clay must be subtracted from percent total clay before calculating the CEC to clay ratio. If the ratio of percent water retained at 1500 kPa tension to the percentage of measured clay is 0.25 or less or 0.6 or more in half or more of the particle-size control section (or in a part of contrasting families), then the percentage of clay is estimated by the following formula: Clay % = 2.5(% water retained at 1500 kPa tension - % organic carbon). See appendix for more information.
    #> 160                                                                                                                                                                                                                                                          Soil temperature classes, as named and defined here, are used as part of the family name in both mineral and organic soils. Temperature class names are used as part of the family name unless the criteria for a higher taxon carry the same limitation. Thus, frigid is implied in all cryic suborders, great groups, and subgroups and would be redundant if used in the names of families within these classes. The Celsius (centigrade) scale is the standard. It is assumed that the temperature is that of a soil that is not being irrigated. Control Section for Soil Temperature The control section for soil temperature is either at a depth of 50 cm below the soil surface or at the upper boundary of a root-limiting layer, whichever is shallower. The soil temperature classes, defined in terms of the mean annual soil temperature and the difference between mean summer and mean winter temperatures, are determined by the following key.
    #>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           criteria
    #> 98  A. Mineral soils that have, in the thickest part of the control section (if the control section is not in one of the strongly contrasting particle-size classes listed below), or in a part of the control section that qualifies as an element in one of the strongly contrasting particle-size classes listed below, or throughout the control section, a fine-earth component (including associated medium and finer pores) of less than 10 percent of the total volume and that meet one of the following sets of substitute class criteria:\n1. Have, in the whole soil, more than 60 percent (by weight) volcanic ash, cinders, lapilli, pumice, and pumicelike [see footnote] fragments and, in the fraction 2 mm or larger in diameter, two-thirds or more (by volume) pumice and/or pumicelike fragments.\nPumiceous or 2. Have, in the whole soil, more than 60 percent (by weight) volcanic ash, cinders, lapilli, pumice, and pumicelike fragments and, in the fraction 2 mm or larger in diameter, less than two-thirds (by volume) pumice and/or pumicelike fragments.\nCindery or 3. Other soils that have a fine-earth component of less than 10 percent (including associated medium and finer pores) of the total volume.\nFragmental or B. Other mineral soils that have a fine-earth component of 10 percent or more (including associated medium and finer pores) of the total volume and meet, in the thickest portion of the control section (if the control section is not in one of the strongly contrasting particle-size classes listed below), or in a portion of the control section that qualifies as a part in one of the strongly contrasting particle-size classes listed below, or throughout the control section, one of the following sets of substitute class criteria:\n1. They:\na. Have andic soil properties and have a water content at 1500 kPa tension of less than 30 percent on undried samples and less than 12 percent on dried samples; or\nb. Do not have andic soil properties, have 30 percent or more of the fine-earth fraction in the 0.02 to 2.0 mm fraction, and have a volcanic glass content (by grain count) of 30 percent or more in the 0.02 to 2.0 mm fraction; and\nc. Have one of the following; (1) A total of 35 percent or more (by volume) rock and pararock fragments, of which two-thirds or more (by volume) is pumice or pumicelike fragments.\nAshy-pumiceous or (2) 35 percent or more (by volume) rock fragments.\nAshy-skeletal or (3) Less than 35 percent (by volume) rock fragments.\nAshy or 2. They have a fine-earth fraction that has andic soil properties and that has a water content at 1500 kPa tension of less than 100 percent on undried samples; and\na. Have a total of 35 percent or more (by volume) rock and pararock fragments, of which two-thirds or more (by volume) is pumice or pumicelike fragments.\nMedial-pumiceous or b. Have 35 percent or more (by volume) rock fragments.\nMedial-skeletal or c. Have less than 35 percent (by volume) rock fragments.\nMedial or 3. They have a fine-earth fraction that has andic soil properties and that has a water content at 1500 kPa tension of 100 percent or more on undried samples; and\na. Have a total of 35 percent or more (by volume) rock and pararock fragments, of which two-thirds or more (by volume) is pumice or pumicelike fragments.\nHydrous-pumiceous or b. Have 35 percent or more (by volume) rock fragments.\nHydrous-skeletal or  [see footnote] Pumicelikevesicular pyroclastic materials other than pumice that have an apparent specific gravity (including vesicles) of less than 1.0 g/cm3 .\nc. Have less than 35 percent (by volume) rock fragments.\nHydrous or 4. They have, in the fraction less than 20 mm in diameter, 40 percent of more (by weight) gypsum and one of the following:\na. A total of 35 percent or more (by volume) rock fragments.\nGypseous-skeletal or b. Less than 35 percent (by volume) rock fragments and 50 percent or more (by weight) particles with diameters of 0.1 to 2.0 mm.\nCoarse-gypseous or c. Less than 35 percent (by volume) rock fragments.\nFine-gypseous or Note: In the following classes, "clay" excludes clay-size carbonates. Carbonates of clay size are treated as silt. If the ratio of percent water retained at 1500 kPa tension to the percentage of measured clay is 0.25 or less or 0.6 or more in half or more of the particle-size control section or part of the particle-size control section in strongly contrasting classes, then the percentage of clay is estimated by the following formula:\nClay % = 2.5(% water retained at 1500 kPa tension - % organic carbon). See appendix for more information.\nC. Other mineral soils that, in the thickest part of the control section (if part of the control section has a substitute for particle-size class and is not in one of the strongly contrasting particle-size classes listed below), or in a part of the control section that qualifies as an element in one of the strongly contrasting particle-size classes listed below, or throughout the control section, meet one of the following sets of particle-size class criteria:\n1. Have a total content of rock fragments, plus any artifacts 2 mm or larger in diameter which are both cohesive and persistent, of 35 percent or more (by volume) and a texture class of coarse sand, sand, fine sand, loamy coarse sand, loamy sand, or loamy fine sand in the fine-earth fraction.\nSandy-skeletal or 2. Have a total content of rock fragments, plus any artifacts 2 mm or larger in diameter which are both cohesive and persistent, of 35 percent or more (by volume) and less than 35 percent (by weight) clay.\nLoamy-skeletal or 3. Have a total content of rock fragments, plus any artifacts 2 mm or larger in diameter which are both cohesive and persistent, of 35 percent or more (by volume).\nClayey-skeletal or 4. Have a texture class of coarse sand, sand, fine sand, loamy coarse sand, loamy sand, or loamy fine sand in the fine-earth fraction.\nSandy or 5. Have a texture class of loamy very fine sand, very fine sand, or finer, including less than 35 percent (by weight) clay in the fine-earth fraction (excluding Vertisols), and are in a shallow family (defined below) or in a Lithic, Arenic, or Grossarenic subgroup, or the layer is a part in a strongly contrasting particle-size class (listed below).\nLoamy or 6. Have, in the fraction less than 75 mm in diameter, 15 percent or more (by weight) particles with diameters of 0.1 to 75 mm (fine sand or coarser, including gravel and artifacts 2 to 75 mm in diameter which are both cohesive and persistent) and, in the fine-earth fraction, less than 18 percent (by weight) clay.\nCoarse-loamy or 7. Have, in the fraction less than 75 mm in diameter, 15 percent or more (by weight) particles with diameters of 0.1 to 75 mm (fine sand or coarser, including gravel and artifacts 2 to 75 mm in diameter which are both cohesive and persistent) and, in the fine-earth fraction, 18 to less than 35 percent (by weight) clay (Vertisols are excluded).\nFine-loamy or 8. Have, in the fraction less than 75 mm in diameter, less than 15 percent (by weight) particles with diameters of 0.1 to 75 mm (fine sand or coarser, including gravel and artifacts 2 to 75 mm in diameter which are both cohesive and persistent) and, in the fine-earth fraction, less than 18 percent (by weight) clay.\nCoarse-silty or 9. Have, in the fraction less than 75 mm in diameter, less than 15 percent (by weight) particles with diameters of 0.1 to 75 mm (fine sand or coarser, including gravel and artifacts 2 to 75 mm in diameter which are both cohesive and persistent) and, in the fine-earth fraction, 18 to less than 35 percent (by weight) clay (Vertisols are excluded).\nFine-silty or 10. Have 35 percent or more (by weight) clay (more than 30 percent in Vertisols) and are in a shallow family (defined below) or in a Lithic, Arenic, or Grossarenic subgroup, or the layer is a part in a strongly contrasting particle-size class (listed below).\nClayey or 11. Have (by weighted average) less than 60 percent (by weight) clay in the fine-earth fraction.\nFine or 12. Have 60 percent or more (by weight) clay.\nVery-fine
    #> 20
    #> 179
    #> 160