---
title: "Family-level Taxonomic Classes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Family-level Taxonomy}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  eval = SoilTaxonomy:::.soilDB_metadata_available(min_version = "2.0.0"),
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
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)

```{r}
parse_family("fine-loamy, mixed, semiactive, mesic ultic haploxeralfs")
```

## `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)

```{r}
data("ST_family_classes")
head(ST_family_classes)
```

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).

```{r}
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)
```