Find species and state records missing from FFB

Here we present a practical guide to the mycobank_gap(), spfungorum_gap(), and funga_distribution_gap() functions of the fungaR package. Together, they support taxonomic experts curating and expanding Flora e Funga do Brasil (FFB)’s fungal coverage, by cross-checking global mycological and biodiversity repositories and flagging candidates worth a manual review.

Looking for MycoBank or Index Fungorum information on a taxon you already have in mind, rather than a comparison against FFB? See Retrieve records for a Brazilian taxon for mycobank_records()/spfungorum_records() instead.

All three functions write their results in three complementary forms: the returned data.frame, a downloadable .xlsx spreadsheet, and — by default (html_report = TRUE) — a self-contained HTML report with KPI counts, breakdown tables, and the full candidate/record table as a sortable, filterable DT widget with one-click copy/CSV/Excel download buttons, opened automatically in your browser in interactive sessions (open_report = interactive()).

mycobank_gap(): find MycoBank species with Brazil evidence missing from FFB

Given a genus or order, mycobank_gap() cross-checks MycoBank’s global name database against the current FFB checklist. This is not a general diff of the two databases: by default, only species-level MycoBank names that MycoBank’s own locality data already places in Brazil — but that are still missing from FFB — are returned, so taxonomic experts get a shortlist of genuinely plausible new national records rather than every unrelated MycoBank name in the genus/order.

MycoBank has no public search API suited to bulk automation, so rather than scraping its live, JavaScript-driven search interface, the function downloads and caches MycoBank’s own bulk name export (MBList.zip, refreshed regularly by MycoBank), then filters it down to the requested genus or order using MycoBank’s Classification column. Names are compared against FFB by their currently accepted MycoBank name (not the raw name itself), so an obscure historical synonym of a species FFB already lists under a different name is not flagged as missing.

Determining Brazil evidence requires visiting each missing candidate’s own MycoBank name page (check_locality = TRUE, the default, via chromote, a headless-Chrome driver — MycoBank’s name pages are a JavaScript app with no static HTML fallback) to read the type specimen’s reported “Location details”, along with several other fields only available on that individual page: substrate/host, etymology, name type (e.g. Basionym/Combination), the type specimen voucher itself, its collector, and the original-publication (protolog) citation — beyond what MycoBank’s bulk export alone provides. When require_brazil_evidence = TRUE (the default), the result is then filtered down to only the candidates whose 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. This intentionally does not cross-check GBIF/speciesLink here — see funga_distribution_gap() below for that.

A candidate counts as “already in FFB” if either its raw MycoBank name or its MycoBank currently accepted name matches an FFB species — not the current name alone — because MycoBank and FFB sometimes disagree on which genus a name currently belongs to.

Arguments

Argument Description
taxon Character. A single genus or order name (e.g. "Trichoderma" or "Xylariales").
rank "genus" (default) or "order".
check_locality If TRUE (default), each candidate’s own MycoBank name page is visited to read its reported locality/substrate. Requires the chromote package and a local Chrome/Chromium install; skipped with a message if unavailable.
require_brazil_evidence If TRUE (default), the returned table is filtered to only candidates whose MycoBank locality mentions Brazil. Set FALSE to return every missing name regardless of locality. Only meaningful when check_locality = TRUE.
max_check Safety cap on how many candidates are sent through the (one-page-load-per-name) locality check. Default 200.
version FFB dataset version to compare against. Defaults to "latest".
mycobank_dir Local directory used to cache the downloaded MycoBank export (~140MB). Defaults to "mycobank_download".
save If TRUE (default), saves the result as an .xlsx spreadsheet.
html_report If TRUE (default), also writes the interactive HTML report described above.

Value

A data frame, one row per MycoBank species-level name missing from FFB and, by default, with a Brazilian MycoBank locality, with its MycoBank number, author, year, name status, classification, current name, full synonymy text, original MycoBank URL (rendered as a clickable link in the HTML report), and — when check_locality = TRUE — several fields scraped from the name’s own MycoBank page: MycoBank_Locality, MycoBank_Substrate, MycoBank_Etymology, MycoBank_Name_Type, MycoBank_Type_Specimen, MycoBank_Collector, MycoBank_Protolog, and a MycoBank_Brazil_Evidence flag — ready for a taxonomist’s manual review.

Example

library(fungaR)

# MycoBank species in genus Trichoderma with a Brazilian MycoBank locality
# 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 per-candidate locality check (no Brazil filtering possible)
gap_fast <- mycobank_gap(taxon = "Trichoderma", rank = "genus",
                         check_locality = FALSE)

spfungorum_gap(): find Index Fungorum species with Brazil evidence missing from FFB

Given a genus, spfungorum_gap() cross-checks Species Fungorum (Index Fungorum, Kew) against the current FFB checklist — the same “not a general diff” philosophy as mycobank_gap(), but sourced from Index Fungorum’s own reported locality instead of MycoBank’s.

Unlike MycoBank, Index Fungorum publishes a public, documented web service (fungus.asmx, a plain HTTP GET/XML API — no SOAP client or headless browser needed) that already returns every matching name’s own reported locality and host in a single request per genus. Index Fungorum’s LOCATION field very often names a Brazilian state directly (e.g. "Pernambuco") rather than the country itself, so the Brazil-evidence check covers the country name and every Brazilian state (matched as whole words, so e.g. “Paraguay” is never mistaken for the state “Pará”), not just the literal word “Brazil”. As with mycobank_gap(), a candidate counts as “already in FFB” if either its raw Index Fungorum name or its currently accepted name matches an FFB species.

By default (fetch_details = TRUE), each missing candidate’s own Species Fungorum page is also visited — a fast, plain HTTP request, no headless browser needed — to read the journal it was published in, the full formatted citation, the basionym/typification details, and the Index Fungorum LSID, and to correct Current_name with the freshly-scraped value whenever the bulk search response’s own (occasionally stale) field differs.

Arguments

Argument Description
taxon Character. A single genus name (e.g. "Phellinotus"). Index Fungorum’s web service has no operation for searching by higher classification, so order-level searches are not supported.
require_brazil_evidence If TRUE (default), the returned table is filtered to only candidates whose Index Fungorum location mentions Brazil. Set FALSE to return every missing name regardless of locality.
fetch_details If TRUE (default), visits each missing candidate’s own Species Fungorum page for its journal, full citation, basionym/typification details, and LSID, and to refresh Current_name. Set FALSE to skip this and use only the bulk search response’s own fields.
max_number Maximum number of matching names requested from the web service in a single call. Default 1000, generous for any genus.
version FFB dataset version to compare against. Defaults to "latest".
save If TRUE (default), saves the result as an .xlsx spreadsheet.
html_report If TRUE (default), also writes the interactive HTML report described above.

Value

A data frame, one row per Index Fungorum species-level name missing from FFB and, by default, with a Brazilian reported locality, with its Fungorum number, author, specific epithet, year, name status, current name, volume/part/page, publishing authors, original Species Fungorum URL (rendered as a clickable link in the HTML report), Fungorum_Location, Fungorum_Host, a Fungorum_Brazil_Evidence flag, and — when fetch_details = TRUE — Fungorum_Journal, Fungorum_Citation, Fungorum_Basionym, Fungorum_Current_Name_Citation, and Fungorum_LSID.

Example

library(fungaR)

# Index Fungorum species in genus Phellinotus with a Brazilian reported
# locality that are still missing from FFB
gap <- spfungorum_gap(taxon = "Phellinotus")

# Every Index Fungorum name missing from FFB regardless of locality, for manual review
gap_all <- spfungorum_gap(taxon = "Phellinotus", require_brazil_evidence = FALSE)

# Faster, without the per-candidate page visit
gap_fast <- spfungorum_gap(taxon = "Phellinotus", fetch_details = FALSE)

funga_distribution_gap(): find candidate new state and phytogeographic domain records

Given a fungal genus or species, funga_distribution_gap() checks GBIF and, optionally, speciesLink and the Reflora Virtual Herbarium (via the refloraR package) for specimen evidence in Brazilian states that are not currently listed in FFB’s official distribution for that taxon — flagging candidate new state records.

By default (domains = TRUE), it goes a step further: georeferenced records are also placed in Brazil’s six phytogeographic domains (Amazônia, Caatinga, Cerrado, Mata Atlântica, Pampa, Pantanal) using IBGE’s biome map bundled with the package, flagging candidate new domain records the same way — e.g. a species FFB lists only for the Caatinga, but with GBIF coordinates falling in the Cerrado. This requires the sf package.

Its HTML report goes further still than the state- and domain-level tables: it plots the georeferenced records on an interactive map over the phytogeographic domains (colored by candidate status, via the leaflet package), and lists the actual individual occurrence records (not aggregated) behind each new-state and new-domain candidate, each linking directly to that record’s own page on GBIF or Reflora — exactly the evidence a taxonomist needs to verify the candidate.

Arguments

Argument Description
taxon Character. A single genus or species name (e.g. "Trichoderma harzianum").
state Optional character vector restricting the check to specific states. NULL (default) checks all states with any evidence.
sources Which sources to query: any of "gbif", "speciesLink", "reflora". Defaults to "gbif" alone, the fastest.
specieslink_key speciesLink API key, used when "speciesLink" is among sources. Defaults to the SPECIESLINK_KEY environment variable.
domains If TRUE (default), also places georeferenced records in the phytogeographic domains and flags candidate new domain records. Requires sf.
max_coordinates Maximum number of georeferenced GBIF records read for the domain analysis. Defaults to 5000.
version FFB dataset version to compare against. Defaults to "latest".
save If TRUE (default), saves the result as an .xlsx spreadsheet, one sheet per table.
html_report If TRUE (default), also writes the interactive HTML report, including the domain map and the individual-records tables.

Value

A list of three data frames:

  • states — one row per Brazilian state with any occurrence evidence, flagging New_state_record_candidate = TRUE whenever a state has external evidence but is not in FFB’s official distribution.
  • domains — one row per phytogeographic domain with any evidence, flagging New_domain_record_candidate = TRUE the same way. Empty when domains = FALSE.
  • records — one row per georeferenced record, with its coordinates, assigned state and domain, and the logical New_state_record_candidate/New_domain_record_candidate columns. Empty when domains = FALSE.

Example

library(fungaR)

gap <- funga_distribution_gap(taxon = "Trichoderma harzianum")

# Candidate new state records
gap$states

# Candidate new phytogeographic domain records, and the records behind them
gap$domains
gap$records[gap$records$New_domain_record_candidate, ]

# Restrict the check to two states, using only GBIF
gap_ba_pe <- funga_distribution_gap(taxon = "Trichoderma harzianum",
                                    state = c("Bahia", "Pernambuco"),
                                    sources = "gbif")

Additional Tips

  • funga_distribution_gap() only queries GBIF by default; add "speciesLink" to sources (with a free specieslink_key) and/or "reflora" for additional evidence.
  • Install the refloraR package to include Reflora specimen evidence in funga_distribution_gap(); without it, that source is skipped with a message.
  • Install the sf package to include the phytogeographic domain analysis in funga_distribution_gap() (domains = TRUE, the default); without it, that step is skipped with a message and domains/records come back empty. Install leaflet as well to see the interactive domain map in the HTML report.
  • Install the chromote package (and have a local Chrome/Chromium install) to include the MycoBank locality check in mycobank_gap(); without it, that step (and the Brazil-evidence filtering that depends on it) is skipped with a message, and every missing name is returned unfiltered. spfungorum_gap() needs no such extra dependency.
  • Combine with funga_get_children_taxa() to build the candidate genus list you want to check against MycoBank or Index Fungorum.
  • mycobank_gap(), for larger genera or orders, can take a while when the per-candidate locality checks are enabled — start with check_locality = FALSE to size up how many candidates exist before running the full Brazil-evidence check. spfungorum_gap()’s Brazil-evidence filtering is always a single request regardless of genus size, but fetch_details = TRUE (the default) adds one fast plain-HTTP request per missing candidate for the journal/citation/basionym/LSID fields — set fetch_details = FALSE to skip that for very large result sets.

See Also