flora_build_matrix

Build a character matrix from extracted descriptions

floraR::flora_build_matrix()

Description

Converts extracted Flora e Funga do Brasil description text into a matrix with taxa as rows, from either kind of description returned by flora_get_descriptions:

controlled descriptions (descriptions[[1]]) become a taxon-by-character-state matrix, one column per state;
free descriptions (descriptions[[2]]) become a taxon-by-organ matrix, one column per organ (e.g. Habit, Leaf, Panicle, Flower, Samara, Seed), each cell holding that organ’s description.

Details

If descriptions is the list returned by flora_get_descriptions() when some taxa failed - an unnamed list of the extracted descriptions and the failed taxon names - only the extracted descriptions are used. In both cases, NULL descriptions are removed before the matrix is built.

Controlled descriptions follow a fixed template, in which character categories are separated by periods, category names are separated from their values by colons, and multiple states are separated by semicolons (e.g. "Leaf: leaflet number 3 to 7; leaflet margin entire. Flower: ..."). The first description defines the matrix columns; a taxon whose description does not match that template is left empty.

Free descriptions are prose written one sentence (or more) per organ, each starting with the organ’s name (e.g. "Tree to 10 m; branchlets sericeous. Leaves 12-30 cm long, ... Panicles erect, ... Seeds 12-25 mm long."). The first sentence is the Habit; every later sentence is assigned to the organ named by its first word, singularised so that e.g. “Seeds” and “Seed” share one column. Columns are aligned by organ name across all taxa, so taxa that describe different organs or the same organs in another order still line up; an organ a taxon does not describe is NA. Sentences are split at a period followed by a capital letter, but not after a person’s initial (as in a cited specimen, “M. Nee 34997”) or a common abbreviation (“cf.”, “ca.”, “e.g.”, “var.”), and decimals (“1.5 m”) never split. As a safeguard, a sentence starting with a word that opens sentences in fewer than a third of the taxa is not treated as an organ, and is appended to the preceding organ’s text.

Arguments

Argument	Description
descriptions	A named list of description strings, usually one of the outputs from `flora_get_descriptions()`, such as `descriptions[[1]]` or `descriptions[[2]]`. If failures were returned together with descriptions, the function uses only the extracted-description component.
type	Character. Which kind of descriptions these are: `"auto"` (default) detects it from the text, or set `"controlled"` or `"free"` explicitly.

Value

A character matrix with taxa as rows: for controlled descriptions, one column per character state; for free descriptions, one column per organ.

Examples

taxa <- flora_records(taxon = "Luetzelburgia",
                      taxonRank = "ESPECIE",
                      taxonomicStatus = "NOME_ACEITO")
descriptions <- flora_get_descriptions(taxa, delay = 10)

# Taxon-by-character-state matrix from the controlled descriptions
mat_control <- flora_build_matrix(descriptions[[1]])

# Taxon-by-organ matrix from the free descriptions
mat_free <- flora_build_matrix(descriptions[[2]])

--- title: 'flora_build_matrix' description: 'Build a character matrix from extracted descriptions' toc: true toc-depth: 3 --- ```{r} #| eval: false floraR::flora_build_matrix() ``` ### Description Converts extracted Flora e Funga do Brasil description text into a matrix with taxa as rows, from either kind of description returned by `flora_get_descriptions`: - **controlled descriptions** (`descriptions[[1]]`) become a taxon-by-character-state matrix, one column per state; - **free descriptions** (`descriptions[[2]]`) become a taxon-by-organ matrix, one column per organ (e.g. Habit, Leaf, Panicle, Flower, Samara, Seed), each cell holding that organ's description. ### Details If `descriptions` is the list returned by `flora_get_descriptions()` when some taxa failed - an unnamed list of the extracted descriptions and the failed taxon names - only the extracted descriptions are used. In both cases, `NULL` descriptions are removed before the matrix is built. **Controlled descriptions** follow a fixed template, in which character categories are separated by periods, category names are separated from their values by colons, and multiple states are separated by semicolons (e.g. `"Leaf: leaflet number 3 to 7; leaflet margin entire. Flower: ..."`). The first description defines the matrix columns; a taxon whose description does not match that template is left empty. **Free descriptions** are prose written one sentence (or more) per organ, each starting with the organ's name (e.g. `"Tree to 10 m; branchlets sericeous. Leaves 12-30 cm long, ... Panicles erect, ... Seeds 12-25 mm long."`). The first sentence is the `Habit`; every later sentence is assigned to the organ named by its first word, singularised so that e.g. "Seeds" and "Seed" share one column. Columns are aligned by organ name across all taxa, so taxa that describe different organs or the same organs in another order still line up; an organ a taxon does not describe is `NA`. Sentences are split at a period followed by a capital letter, but not after a person's initial (as in a cited specimen, "M. Nee 34997") or a common abbreviation ("cf.", "ca.", "e.g.", "var."), and decimals ("1.5 m") never split. As a safeguard, a sentence starting with a word that opens sentences in fewer than a third of the taxa is not treated as an organ, and is appended to the preceding organ's text. ### Arguments | Argument | Description | |---|---| | descriptions | A named list of description strings, usually one of the outputs from `flora_get_descriptions()`, such as `descriptions[[1]]` or `descriptions[[2]]`. If failures were returned together with descriptions, the function uses only the extracted-description component. | | type | Character. Which kind of descriptions these are: `"auto"` (default) detects it from the text, or set `"controlled"` or `"free"` explicitly. | ### Value A character matrix with taxa as rows: for controlled descriptions, one column per character state; for free descriptions, one column per organ. ### Examples ```r taxa <- flora_records(taxon = "Luetzelburgia", taxonRank = "ESPECIE", taxonomicStatus = "NOME_ACEITO") descriptions <- flora_get_descriptions(taxa, delay = 10) # Taxon-by-character-state matrix from the controlled descriptions mat_control <- flora_build_matrix(descriptions[[1]]) # Taxon-by-organ matrix from the free descriptions mat_free <- flora_build_matrix(descriptions[[2]]) ```