mycobank_gap

Find fungal species with MycoBank Brazil evidence that are missing from FFB

fungaR::mycobank_gap()

Description

Given a fungal genus or order, cross-checks MycoBank’s global nomenclatural database against the Flora e Funga do Brasil (FFB) checklist to find species-level names that MycoBank itself already associates with a Brazilian locality but that are not currently registered in FFB. This is not a general diff of the two databases: a MycoBank name missing from FFB is only returned when MycoBank’s own type/specimen locality data indicates it occurs in Brazil, so taxonomic experts get a shortlist of genuinely plausible new national records rather than every unrelated MycoBank name in the genus/order.

Details

MycoBank does not offer a public search API suited to bulk automation, but it does publish a full, regularly-updated bulk export of every name in its database (https://www.mycobank.org/images/MBList.zip). This function downloads and caches that export locally (the same way funga_download caches the FFB dataset), then filters it down to the requested genus or order using MycoBank’s own Classification column.

The bulk export itself carries no locality information, so determining Brazil evidence requires visiting each missing candidate’s individual MycoBank name page (its MycoBank_URL) to read the “Location details” (and “Host/Substrate”) reported for its type specimen. MycoBank’s name pages are a JavaScript single-page application with no static HTML fallback, so this step (check_locality = TRUE, the default) requires the chromote package (and a local Chrome/Chromium installation) to drive a headless browser. When require_brazil_evidence = TRUE (the default), the returned table is filtered down to only the candidates whose MycoBank locality mentions Brazil; set it to FALSE to instead get every MycoBank name missing from FFB regardless of locality (with the evidence columns alongside, for manual review). Brazil-evidence filtering has no effect if check_locality = FALSE, since no locality data is available to filter on; a message explains this when it happens.

The FFB side of the comparison reuses funga_get_children_taxa to list every species (accepted and synonym) currently registered in FFB for the requested genus/order.

Arguments

Argument	Description
taxon	Character. A single fungal genus or order name (e.g. `"Trichoderma"` or `"Xylariales"`).
rank	Character. Whether `taxon` is a `"genus"` (default) or an `"order"`.
check_locality	Logical. If `TRUE` (default), each MycoBank name missing from FFB has its own MycoBank name page visited (via chromote) to read the type specimen’s reported locality and host/substrate, determining which candidates MycoBank itself already associates with Brazil. Set to `FALSE` to skip this (much faster, but without locality evidence, and `require_brazil_evidence` has no effect).
require_brazil_evidence	Logical. If `TRUE` (default), the returned table is filtered to only the candidates whose MycoBank locality mentions Brazil - i.e. names MycoBank itself indicates occur in Brazil but that FFB is still missing. Set to `FALSE` to instead return every MycoBank species-level name missing from FFB regardless of locality (with `MycoBank_Brazil_Evidence` alongside for manual review). Only meaningful when `check_locality = TRUE`.
max_check	Numeric. Safety cap on how many missing candidates are sent through the (comparatively slow, one-page-load-per-name) locality check when `check_locality = TRUE`. Defaults to `200`; if more candidates are found, only the first `max_check` (alphabetically) are checked and a warning is issued. Ignored when `check_locality = FALSE`.
version	Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `funga_get_children_taxa`.
mycobank_dir	Character. Local directory used to cache the downloaded MycoBank bulk export. Defaults to `"mycobank_download"`. Reused on subsequent calls to avoid re-downloading the (~140MB) file.
verbose	Logical. If `TRUE` (default), prints progress messages.
save	Logical. If `TRUE` (default), the result is saved to disk as an `.xlsx` spreadsheet.
dir	Character. Directory where the spreadsheet is saved when `save = TRUE`. Defaults to `"mycobank_gap"`.
filename	Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"mycobank_gap_<taxon>"`.
html_report	Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts, a families-affected breakdown, and the full candidate table as a sortable, filterable DT widget with buttons to copy or download it as CSV/Excel. Requires the rmarkdown, DT, and htmltools packages; if any is missing, the report is skipped with a message (the `.xlsx` spreadsheet is unaffected).
open_report	Logical. If `TRUE` (default in interactive sessions), opens the rendered HTML report in the default browser.

Value

A data.frame, one row per MycoBank species-level name found in the requested genus/order that is absent from the current FFB checklist and, by default, whose MycoBank locality data indicates it occurs in Brazil, with columns:

MycoBank_NumberMycoBank’s numeric identifier for the name. Taxon_nameThe binomial as registered in MycoBank. AuthorsFull author citation. YearYear of effective publication. Name_statusMycoBank’s nomenclatural status (e.g. "Legitimate"). ClassificationFull MycoBank classification string (Kingdom to genus). Current_nameMycoBank’s currently accepted name for this entry, when different (i.e. when Taxon_name is itself a synonym). SynonymyMycoBank’s full synonymy text (current name and/or basionym, each with its complete author/journal/year citation), from the bulk export. MycoBank_URLDirect link to the name’s MycoBank page. MycoBank_Locality, MycoBank_SubstrateType specimen locality and host/substrate as reported on the name’s own MycoBank page (only when check_locality = TRUE). MycoBank_EtymologyThe name’s etymology, as reported on its own MycoBank page (only when check_locality = TRUE). MycoBank_Name_TypeMycoBank’s nomenclatural name type for this entry (e.g. "Basionym", "Combination"; only when check_locality = TRUE). MycoBank_Type_SpecimenThe type specimen voucher (e.g. "URM 80362 holotype"; only when check_locality = TRUE). MycoBank_CollectorThe type specimen’s collector, as reported on the name’s own MycoBank page (only when check_locality = TRUE). MycoBank_ProtologThe original-publication (protolog) citation, as reported on the name’s own MycoBank page (only when check_locality = TRUE). MycoBank_Brazil_EvidenceLogical; TRUE when MycoBank_Locality mentions Brazil (only when check_locality = TRUE). In_FFBAlways FALSE (kept for clarity when combining with other tables).

Examples

# Species-level MycoBank names for genus Trichoderma that MycoBank's own
# locality data places in Brazil but that are still missing from FFB
gap <- mycobank_gap(taxon = "Trichoderma", rank = "genus")

# Every MycoBank name missing from FFB regardless of locality, for manual review
gap_all <- mycobank_gap(taxon = "Trichoderma", rank = "genus",
                              require_brazil_evidence = FALSE)

# Faster, without the locality check (no Brazil-evidence filtering possible)
gap_fast <- mycobank_gap(taxon = "Trichoderma", rank = "genus",
                               check_locality = FALSE)

--- title: 'mycobank_gap' description: 'Find fungal species with MycoBank Brazil evidence that are missing from FFB' toc: true toc-depth: 3 --- ```{r} #| eval: false fungaR::mycobank_gap() ``` ### Description Given a fungal genus or order, cross-checks [MycoBank](https://www.mycobank.org)'s global nomenclatural database against the Flora e Funga do Brasil (FFB) checklist to find species-level names that MycoBank itself already associates with a Brazilian locality but that are not currently registered in FFB. This is not a general diff of the two databases: a MycoBank name missing from FFB is only returned when MycoBank's own type/specimen locality data indicates it occurs in Brazil, so taxonomic experts get a shortlist of genuinely plausible new national records rather than every unrelated MycoBank name in the genus/order. ### Details MycoBank does not offer a public search API suited to bulk automation, but it does publish a full, regularly-updated bulk export of every name in its database (https://www.mycobank.org/images/MBList.zip). This function downloads and caches that export locally (the same way `funga_download` caches the FFB dataset), then filters it down to the requested genus or order using MycoBank's own `Classification` column. The bulk export itself carries no locality information, so determining Brazil evidence requires visiting each missing candidate's individual MycoBank name page (its `MycoBank_URL`) to read the "Location details" (and "Host/Substrate") reported for its type specimen. MycoBank's name pages are a JavaScript single-page application with no static HTML fallback, so this step (`check_locality = TRUE`, the default) requires the chromote package (and a local Chrome/Chromium installation) to drive a headless browser. When `require_brazil_evidence = TRUE` (the default), the returned table is filtered down to only the candidates whose MycoBank locality mentions Brazil; set it to `FALSE` to instead get every MycoBank name missing from FFB regardless of locality (with the evidence columns alongside, for manual review). Brazil-evidence filtering has no effect if `check_locality = FALSE`, since no locality data is available to filter on; a message explains this when it happens. The FFB side of the comparison reuses `funga_get_children_taxa` to list every species (accepted and synonym) currently registered in FFB for the requested genus/order. ### Arguments | Argument | Description | |---|---| | taxon | Character. A single fungal genus or order name (e.g. `"Trichoderma"` or `"Xylariales"`). | | rank | Character. Whether `taxon` is a `"genus"` (default) or an `"order"`. | | check_locality | Logical. If `TRUE` (default), each MycoBank name missing from FFB has its own MycoBank name page visited (via chromote) to read the type specimen's reported locality and host/substrate, determining which candidates MycoBank itself already associates with Brazil. Set to `FALSE` to skip this (much faster, but without locality evidence, and `require_brazil_evidence` has no effect). | | require_brazil_evidence | Logical. If `TRUE` (default), the returned table is filtered to only the candidates whose MycoBank locality mentions Brazil - i.e. names MycoBank itself indicates occur in Brazil but that FFB is still missing. Set to `FALSE` to instead return every MycoBank species-level name missing from FFB regardless of locality (with `MycoBank_Brazil_Evidence` alongside for manual review). Only meaningful when `check_locality = TRUE`. | | max_check | Numeric. Safety cap on how many missing candidates are sent through the (comparatively slow, one-page-load-per-name) locality check when `check_locality = TRUE`. Defaults to `200`; if more candidates are found, only the first `max_check` (alphabetically) are checked and a warning is issued. Ignored when `check_locality = FALSE`. | | version | Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `funga_get_children_taxa`. | | mycobank_dir | Character. Local directory used to cache the downloaded MycoBank bulk export. Defaults to `"mycobank_download"`. Reused on subsequent calls to avoid re-downloading the (~140MB) file. | | verbose | Logical. If `TRUE` (default), prints progress messages. | | save | Logical. If `TRUE` (default), the result is saved to disk as an `.xlsx` spreadsheet. | | dir | Character. Directory where the spreadsheet is saved when `save = TRUE`. Defaults to `"mycobank_gap"`. | | filename | Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"mycobank_gap_<taxon>"`. | | html_report | Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts, a families-affected breakdown, and the full candidate table as a sortable, filterable DT widget with buttons to copy or download it as CSV/Excel. Requires the rmarkdown, DT, and htmltools packages; if any is missing, the report is skipped with a message (the `.xlsx` spreadsheet is unaffected). | | open_report | Logical. If `TRUE` (default in interactive sessions), opens the rendered HTML report in the default browser. | ### Value A `data.frame`, one row per MycoBank species-level name found in the requested genus/order that is absent from the current FFB checklist and, by default, whose MycoBank locality data indicates it occurs in Brazil, with columns: MycoBank_NumberMycoBank's numeric identifier for the name. Taxon_nameThe binomial as registered in MycoBank. AuthorsFull author citation. YearYear of effective publication. Name_statusMycoBank's nomenclatural status (e.g. `"Legitimate"`). ClassificationFull MycoBank classification string (Kingdom to genus). Current_nameMycoBank's currently accepted name for this entry, when different (i.e. when `Taxon_name` is itself a synonym). SynonymyMycoBank's full synonymy text (current name and/or basionym, each with its complete author/journal/year citation), from the bulk export. MycoBank_URLDirect link to the name's MycoBank page. MycoBank_Locality, MycoBank_SubstrateType specimen locality and host/substrate as reported on the name's own MycoBank page (only when `check_locality = TRUE`). MycoBank_EtymologyThe name's etymology, as reported on its own MycoBank page (only when `check_locality = TRUE`). MycoBank_Name_TypeMycoBank's nomenclatural name type for this entry (e.g. `"Basionym"`, `"Combination"`; only when `check_locality = TRUE`). MycoBank_Type_SpecimenThe type specimen voucher (e.g. `"URM 80362 holotype"`; only when `check_locality = TRUE`). MycoBank_CollectorThe type specimen's collector, as reported on the name's own MycoBank page (only when `check_locality = TRUE`). MycoBank_ProtologThe original-publication (protolog) citation, as reported on the name's own MycoBank page (only when `check_locality = TRUE`). MycoBank_Brazil_EvidenceLogical; `TRUE` when `MycoBank_Locality` mentions Brazil (only when `check_locality = TRUE`). In_FFBAlways `FALSE` (kept for clarity when combining with other tables). ### Examples ```r # Species-level MycoBank names for genus Trichoderma that MycoBank's own # locality data places in Brazil but that are still missing from FFB gap <- mycobank_gap(taxon = "Trichoderma", rank = "genus") # Every MycoBank name missing from FFB regardless of locality, for manual review gap_all <- mycobank_gap(taxon = "Trichoderma", rank = "genus", require_brazil_evidence = FALSE) # Faster, without the locality check (no Brazil-evidence filtering possible) gap_fast <- mycobank_gap(taxon = "Trichoderma", rank = "genus", check_locality = FALSE) ```