flora_get_descriptions

Extract species descriptions from Flora e Funga do Brasil pages

floraR::flora_get_descriptions()

Description

Reads the printable versions of Flora e Funga do Brasil (FFB) taxon pages for a set of species and extracts the text of their description sections. The function attempts to recover two kinds of descriptions from each page: controlled descriptions (“Descricao com campos controlados”) and free descriptions (“Descricao livre”).

Details

For each taxon, the function:

builds a printable page URL from the references column;
loads the page in a headless Chrome browser (via chromote) and reads its text;
searches for the controlled-description section;
searches for the free-description section;
stores extracted text in named lists using the scientific name.

Failed extractions are returned together with the extracted descriptions.

The function assumes that the printable FFB page contains recognizable section headers in Portuguese and/or English, such as:

"Descricao com campos controlados|Description with controlled"
"Descricao livre|Free description"
"Comentarios|Commentaries"
"Vouchers"
"Origem|Origin"
"Bibliografia Referencia|Reference"

The text is read directly from the rendered page rather than from a PDF of it, so no line can be cut off at a page margin (a PDF of the page clipped the right end of every line, silently losing words), and a description is read in full however long it is. Each section ends at the next section header found at the start of a line; if no closing header is found, the taxon is recorded as a failure rather than stopping the whole run. The language tag lines (“EN”/“PT”) are dropped.

A Chrome or Chromium browser must be installed, as for chromote; one browser session is opened for the whole run and closed at the end.

Arguments

Argument	Description
taxa	A data frame containing the taxa to process. It must include at least the columns `genus`, `specificEpithet`, and `references`. Each row is treated as one taxon page to download and parse.
delay	Numeric. Seconds to wait after each page has loaded before its text is read, to let the page finish rendering. Default is `10`.
verbose	Logical. If `TRUE` (default), prints informative progress messages during parsing. If `FALSE`, runs quietly.

Value

A named list with two elements:

descriptions_controlled: A named list of controlled descriptions. If any failures occur, this element becomes a list of length two: extracted descriptions and a character vector of failed taxon names.
descriptions_free: A named list of free descriptions. If any failures occur, this element becomes a list of length two: extracted descriptions and a character vector of failed taxon names.

Examples

taxa <- flora_records(taxon = "Luetzelburgia",
                      taxonRank = "ESPECIE",
                      taxonomicStatus = "NOME_ACEITO")

descriptions <- flora_get_descriptions(taxa, delay = 10)

--- title: 'flora_get_descriptions' description: 'Extract species descriptions from Flora e Funga do Brasil pages' toc: true toc-depth: 3 --- ```{r} #| eval: false floraR::flora_get_descriptions() ``` ### Description Reads the printable versions of Flora e Funga do Brasil (FFB) taxon pages for a set of species and extracts the text of their description sections. The function attempts to recover two kinds of descriptions from each page: controlled descriptions ("Descricao com campos controlados") and free descriptions ("Descricao livre"). ### Details For each taxon, the function: 1. builds a printable page URL from the `references` column; 2. loads the page in a headless Chrome browser (via chromote) and reads its text; 3. searches for the controlled-description section; 4. searches for the free-description section; 5. stores extracted text in named lists using the scientific name. Failed extractions are returned together with the extracted descriptions. The function assumes that the printable FFB page contains recognizable section headers in Portuguese and/or English, such as: - `"Descricao com campos controlados|Description with controlled"` - `"Descricao livre|Free description"` - `"Comentarios|Commentaries"` - `"Vouchers"` - `"Origem|Origin"` - `"Bibliografia Referencia|Reference"` The text is read directly from the rendered page rather than from a PDF of it, so no line can be cut off at a page margin (a PDF of the page clipped the right end of every line, silently losing words), and a description is read in full however long it is. Each section ends at the next section header found at the start of a line; if no closing header is found, the taxon is recorded as a failure rather than stopping the whole run. The language tag lines ("EN"/"PT") are dropped. A Chrome or Chromium browser must be installed, as for chromote; one browser session is opened for the whole run and closed at the end. ### Arguments | Argument | Description | |---|---| | taxa | A data frame containing the taxa to process. It must include at least the columns `genus`, `specificEpithet`, and `references`. Each row is treated as one taxon page to download and parse. | | delay | Numeric. Seconds to wait after each page has loaded before its text is read, to let the page finish rendering. Default is `10`. | | verbose | Logical. If `TRUE` (default), prints informative progress messages during parsing. If `FALSE`, runs quietly. | ### Value A named list with two elements: - `descriptions_controlled`: A named list of controlled descriptions. If any failures occur, this element becomes a list of length two: extracted descriptions and a character vector of failed taxon names. - `descriptions_free`: A named list of free descriptions. If any failures occur, this element becomes a list of length two: extracted descriptions and a character vector of failed taxon names. ### Examples ```r taxa <- flora_records(taxon = "Luetzelburgia", taxonRank = "ESPECIE", taxonomicStatus = "NOME_ACEITO") descriptions <- flora_get_descriptions(taxa, delay = 10) ```