pacha (version 0.1.1)

pacha_configure: Configure the pacha data module

Description

Gets or updates the configuration shared by every public accessor in this module. The accessors are source-agnostic: they query any ChecklistBank-compatible web API, or read any compatible local Catalogue of Life Data Package (ColDP) archive, provided the source exposes name usages and, where relevant, vernacular names, taxon properties, and distributions. The defaults set here -- the ChecklistBank web API as the active source, dataset "313479" (the Ecuadorian checklist of plants susceptible to sustainable use), and coldp_country = "EC" -- identify the dataset used in this file's \dontrun examples; any other ChecklistBank dataset or compatible ColDP archive can be configured in its place without modifying the module itself.

Usage

pacha_configure(
  dataset = NULL,
  base_url = NULL,
  source_name = NULL,
  language = NULL,
  fetcher,
  use_exclude_pattern = NULL,
  labels = NULL,
  source = NULL,
  coldp_zip_file = NULL,
  coldp_country = NULL,
  timeout = NULL
)

Value

A named configuration list, returned visibly when called with no arguments, and invisibly after an update.

Arguments

dataset

Character scalar. ChecklistBank dataset identifier used by the default API adapter.

base_url

Character scalar. HTTP(S) base URL of the ChecklistBank API.

source_name

Character scalar identifying the web source in connection warnings.

language

Character scalar. A language-dictionary file stem or one of its aliases. Controls labels and presentation, not the source data.

fetcher

Optional custom web adapter. Pass NULL explicitly to restore the built-in ChecklistBank adapter; omit this argument to leave the current adapter unchanged.

use_exclude_pattern

Character scalar regular expression identifying taxon-property names that must not be treated as sustainable-use classes.

labels

Optional named list of named character vectors overriding the default labels by language.

source

Default source: "api"/"web" or "coldp"/"local".

coldp_zip_file

Path to a local ColDP ZIP archive. It must contain NameUsage.tsv; VernacularName.tsv, TaxonProperty.tsv, and Distribution.tsv are read when present. NULL leaves the configured path unchanged. The pacha_COLDP_ZIP environment variable is used lazily when no path is set.

coldp_country

ISO country code used to select country-specific records from the local ColDP archive: vernacular names in VernacularName.tsv, and the preferred distribution row in Distribution.tsv for establishment and threat status. Defaults to "EC".

timeout

Positive numeric HTTP timeout, in seconds, for web requests.

Details

fetcher preserves the existing extension contract for the web source. It receives (species, config) and must return a list with optional common_names, sustainable_uses, indexation_urls, establishment, threat_status, transport_error, and transport_messages elements. A custom fetcher applies only when source = "api"; source = "coldp" always reads the archive. For example:

my_fetcher <- function(species, config) {
  list(
    common_names = list(es = c("nombre comun")),
    sustainable_uses = list(Medicinal = c("uso medicinal registrado")),
    indexation_urls = c(source = "https://example.org/taxon/123"),
    establishment = "native",
    threat_status = "LC",
    transport_error = FALSE,
    transport_messages = character()
  )
}
pacha_configure(fetcher = my_fetcher)

Examples

if (FALSE) {
pacha_configure()
pacha_configure(source = "coldp", coldp_zip_file = "C:/data/ColDP.zip")
pacha_configure(source = "api", dataset = "313479", language = "es")
}