Package {pacha}

Title:	Reproducible Reporting for ChecklistBank Ethnobotanical Data
Version:	0.1.1
Description:	Provides programmatic access to the 'Listado de plantas de uso y aprovechamiento sostenible en Ecuador' <doi:10.48580/dgvrn>. Acts as a client for the 'ChecklistBank' API and for processing 'ColDP' (Catalogue of Life Data Package) files. Supports data retrieval for ethnobotanical records and includes built-in Markdown report generation for reproducible workflows.
License:	GPL (≥ 3)
Language:	en-US
URL:	https://github.com/envinatu/pacha
BugReports:	https://github.com/envinatu/pacha/issues
Imports:	httr2, stats, tools, utils, yaml
Suggests:	knitr, quarto, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
Config/roxygen2/version:	8.1.0
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-09-14 17:26:51 UTC; PC
Author:	Marcelo F. Amores-Palma [aut, cre, cph]
Maintainer:	Marcelo F. Amores-Palma <contacto.envinatu@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-24 14:00:02 UTC

Plain-text and Markdown accessors

Description

The package functions generally follow a dual-interface design: plain-text variants (⁠*_pacha()⁠) for interactive exploration, and Markdown variants (⁠*_pacha_md()⁠) for document rendering. Both share the same underlying source logic, differing only in formatting and error handling. Specific function availability is detailed in their respective documentation pages.

Plain-text accessors (⁠*_pacha()⁠)

Designed for interactive lookups and inline queries about a single taxon. They prioritize explicit feedback:

• Return a localized message when data is missing.

• Raise an R warning() and return a connection message on network failure.

• Warn when ColDP taxon resolution requires disambiguation.

• Print output directly to the console via cat() (returning invisibly) to preserve multi-line formatting (except indexation_urls_pacha()).

Markdown accessors (⁠*_pacha_md()⁠)

Designed for assembling multi-component or multi-taxon Markdown reports. They prioritize clean document compilation:

• Suppress all R warning()s, including connection and disambiguation issues.

• Return an empty string ("") invisibly when data is unavailable, preventing broken layouts or redundant headers in the compiled document.

Choosing between them

Use ⁠*_pacha()⁠ when inspecting an individual taxon interactively. Use ⁠*_pacha_md()⁠ when generating dynamic reports (e.g., Quarto or R Markdown), where unavailable data should omit silently rather than disrupt document rendering.

Retrieve common names

Description

Retrieves vernacular names for a scientific name from the currently configured source. The API source queries the configured ChecklistBank dataset; the local source reads VernacularName.tsv from the configured ColDP archive and, when a country column is present, keeps only the entries matching coldp_country. Names are grouped by language in the returned value. The examples below use the Ecuadorian checklist dataset configured by default, but the same calls work against any compatible ChecklistBank dataset or ColDP archive.

Usage

common_names_pacha(species, language = NULL, source = NULL, refresh = FALSE)

common_names_pacha_md(species, language = NULL, source = NULL, refresh = FALSE)

Arguments

Value

common_names_pacha() prints and invisibly returns a single character string of names grouped by language, or the localized no-data/connection message. common_names_pacha_md() returns, invisibly, the emitted Markdown string, or "" when no names are available.

See Also

accessors-pacha for how plain-text and Markdown accessors work.

Examples

## Not run: 
common_names_pacha("Bidens andicola")
common_names_pacha("Bidens andicola", source = "coldp")

## End(Not run)
## Not run: 
common_names_pacha_md("Bidens andicola")

## End(Not run)

Compare the web API and local ColDP source

Description

Validates and compares the data returned by both sources for one species. The comparison always queries the API and the local ColDP archive, regardless of the configured default source. It normalizes case, accents, punctuation, and whitespace before assessing agreement, while retaining the original source values in the printed result and returned report. Sustainable uses are compared as category :: value pairs, so a value moved between categories is reported as a discrepancy rather than overlooked.

Usage

compare_pacha(
  species,
  component = "all",
  language = NULL,
  refresh = FALSE,
  print = TRUE
)

Arguments

Details

The function prints a concise, component-by-component result by default and returns the full machine-readable report invisibly. Status values are "identical", "partial_overlap", "discrepant", "one_source_missing", "both_missing", "api_unavailable", and "coldp_unavailable". With component = "all", it compares common names, sustainable uses, indexation URLs, establishment status, and threat status.

Value

Invisibly, a list with species, language, components, summary, details, api_record, coldp_record, and compared_at. summary is a data frame with one row per selected component and its agreement status.

Examples

## Not run: 
compare_pacha("Bidens andicola")
compare_pacha("Bidens andicola", component = "sustainable_uses")
compare_pacha("Bidens andicola", component = c("origin", "threat"))
compare_pacha("Bidens andicola", component = c("names", "urls"), print = FALSE)

## End(Not run)

Retrieve establishment status

Description

Retrieves the documented establishment means of a taxon – native, introduced, cultivated, naturalized, and so on. The API source reads the ChecklistBank taxon-distribution endpoint. The local source reads Distribution.tsv and prefers the entry matching the configured coldp_country; when several equally relevant records remain, it selects the lowest ColDP identifier and reports this through a warning raised by the plain-text accessor.

Usage

establishment_pacha(species, language = NULL, source = NULL, refresh = FALSE)

establishment_pacha_md(
  species,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

Arguments

Details

Values are translated through the selected language dictionary's establishment mapping. Values absent from that mapping are returned in sentence case rather than rejected, so datasets using additional establishment categories remain usable.

Value

establishment_pacha() prints and invisibly returns a translated establishment category, or the localized no-data/connection message. establishment_pacha_md() returns, invisibly, the emitted Markdown string, or "" when the source has no establishment record.

See Also

accessors-pacha for a detailed description of plain-text and Markdown accessors.

Examples

## Not run: 
establishment_pacha("Bidens andicola")
establishment_pacha("Bidens andicola", source = "coldp", language = "en")

## End(Not run)
## Not run: 
establishment_pacha_md("Bidens andicola", language = "en")

## End(Not run)

Retrieve indexation URLs

Description

Retrieves URLs associated with the resolved taxon. For the web source, the result includes any URLs returned by ChecklistBank plus its canonical taxon page. For the local source, URLs are extracted from NameUsage.tsv; IPNI links are normalized to their canonical ⁠https://www.ipni.org/n/...⁠ form.

Usage

indexation_urls_pacha(species, language = NULL, source = NULL, refresh = FALSE)

indexation_urls_pacha_md(
  species,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

Arguments

Value

indexation_urls_pacha() returns, visibly, a named character vector of URLs, or the localized no-data/connection message. indexation_urls_pacha_md() returns, invisibly, the emitted Markdown string, or "" when no URLs are available.

See Also

accessors-pacha for a detailed description of plain-text and Markdown accessors.

Examples

## Not run: 
indexation_urls_pacha("Bidens andicola")
indexation_urls_pacha("Bidens andicola", source = "coldp")

## End(Not run)
## Not run: 
indexation_urls_pacha_md("Bidens andicola")

## End(Not run)

Report whether a species is listed in the configured dataset

Description

Resolves a scientific name against the currently configured source (api or coldp) and reports, as a plain-text console message, whether the species is listed in the working dataset. The message is taken from the active language configuration and can be customized through the package configuration; if the required messages are unavailable for the selected language, the function raises an error. The language argument is resolved in the same way as for the other accessors in this module, accepting either a language alias or a language code. As with those accessors, a taxonomic match resolved from the local ColDP archive that required disambiguation raises one or more additional warning()s.

Usage

is_listed_pacha(
  species,
  language = NULL,
  source = NULL,
  refresh = FALSE,
  detailed = FALSE
)

Arguments

Value

Invisibly, the printed plain-text statement: the species name, the localized listed/not-listed statement, and, when detailed = TRUE and the species is listed, its sustainable uses.

Examples

## Not run: 
is_listed_pacha("Bidens andicola")
is_listed_pacha("Bidens andicola", detailed = TRUE)
is_listed_pacha("Bidens andicola", language = "en", source = "coldp")

## End(Not run)

Clear cached source records

Description

Removes cached records for both sources. With species = NULL, also discards the cached ColDP tables, so subsequent local queries reread the ZIP archive. Supplying a species removes only that species from the API and ColDP record caches.

Usage

pacha_clear_cache(species = NULL)

Arguments

Value

Invisibly, NULL.

Examples

pacha_clear_cache()
pacha_clear_cache("Bidens andicola")

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
)

Arguments

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)

Value

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

Examples

## Not run: 
pacha_configure()
pacha_configure(source = "coldp", coldp_zip_file = "C:/data/ColDP.zip")
pacha_configure(source = "api", dataset = "313479", language = "es")

## End(Not run)

Generate a per-species Markdown report

Description

Concatenates the Markdown output of pacha_sc_full_name_md(), common_names_pacha_md(), and sustainable_uses_pacha_md() into a single Markdown-formatted string, with one block per species in species, suitable for a results = "asis" knitr chunk in an automated report.

Usage

pacha_report(
  species,
  language = NULL,
  source = NULL,
  use = NULL,
  refresh = FALSE,
  print = TRUE
)

Arguments

Details

The heading for each species always comes from pacha_sc_full_name_md(), which takes no argument beyond species and resolves against its own dataset and cache, independently of language and source; see ?pacha_sc_full_name_md. language and source are forwarded to both common_names_pacha_md() and sustainable_uses_pacha_md(); use is forwarded only to sustainable_uses_pacha_md(); refresh is forwarded to both common_names_pacha_md() and sustainable_uses_pacha_md(), but not to pacha_sc_full_name_md(), as scientific names rely on a separate cache unaffected by this parameter.

Each component is produced by capturing, not re-implementing, the output of the corresponding ⁠_md⁠ accessor: its internal cat() call is suppressed and its invisible return value is reused directly, so the combined report is emitted exactly once regardless of the number of species or components involved. As documented for the underlying accessors, a component with no data for a given species contributes nothing to that species' block: there is no "no data" placeholder or empty heading, since each ⁠_md⁠ function returns "" in that case. pacha_sc_full_name_md() has no such empty case: it always renders a heading, falling back to the requested name verbatim when resolution fails.

A structurally invalid element of species (missing, or lacking at least a genus and a specific epithet) raises an error via the same validation used by the underlying accessors; species preceding the invalid one in the vector are not processed once that error is raised.

Value

A character scalar with the combined Markdown for every element of species, one block per species separated by a blank line. Returned invisibly when print = TRUE, visibly when print = FALSE.

Examples

## Not run: 
# Inside a knitr chunk with `results = "asis"`:
pacha_report("Bidens andicola")
pacha_report(c("Bidens andicola", "Bomarea multiflora"), language = "en")
pacha_report("Bidens andicola", source = "coldp", use = "medicinal")

## End(Not run)

Full scientific name of a species

Description

Resolves species against ChecklistBank's Catalogue of Life dataset ("3LXR") via match/nameusage, falling back to nameusage/search (limit = 100) when no direct match is returned. Among search candidates the best match is chosen by preference: an exact case-insensitive name match with status "accepted"; else any exact name match; else the first "accepted" candidate; else the first candidate returned. pacha_sc_full_name returns the name as plain text; pacha_sc_full_name_md renders it as a Markdown heading (see "Functions"). This resolution always uses dataset "3LXR" and ignores pacha_configure().

Usage

pacha_sc_full_name(species)

pacha_sc_full_name_md(species)

Arguments

Details

Results are cached in memory per lower-cased, whitespace-normalised species string, shared by both functions, so repeat lookups skip the HTTP call.

Failures never raise an error: network/HTTP errors, timeouts, malformed JSON, no match, or a missing httr2 dependency all fall back to species verbatim with no authorship – the same output produced for a name that resolved but has no authorship of its own. stop() is only reached for a structurally invalid species.

Value

Character scalar: "Genus species Authorship" if authorship resolved, otherwise "Genus species" (or the original species if resolution failed). See "Functions" for the Markdown variant.

Functions

• pacha_sc_full_name_md(): Same resolution, rendered as a Markdown heading with the name italicised and the authorship appended as plain text (e.g. "## *Bidens andicola* Kunth"). Markdown-sensitive characters in both parts are backslash-escaped to keep the output well-formed. Printed via cat() and returned invisibly.

Examples

## Not run: 
pacha_sc_full_name("Bidens andicola")
pacha_sc_full_name_md("Bidens andicola")

## End(Not run)

Retrieve the source database citation

Description

Retrieves how the configured data source itself should be cited, as distinct from any per-species bibliographic reference. For the API source, this is the citation field of the configured ChecklistBank dataset (GET /dataset/{key}), resolved once and cached, since it does not vary by species. For the local source, this is the citation entry of metadata.yaml inside the configured ColDP archive. Either source may return the citation as CSL HTML (e.g. wrapped in ⁠<div class="csl-entry">⁠, with ⁠<span style="font-style: italic">⁠ and HTML entities); this function strips all markup and decodes entities, returning clean, unformatted text.

Usage

reference_pacha(
  species = NULL,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

Arguments

Value

A single character string with the plain-text source citation, or the localized no-data/connection message.

Examples

## Not run: 
reference_pacha()
reference_pacha(source = "coldp")

## End(Not run)

Retrieve sustainable-use records

Description

Retrieves sustainable-use categories and values from the configured source: the ChecklistBank taxon-property endpoint for the API source, or TaxonProperty.tsv for the local source. In either case, categories matching use_exclude_pattern are dropped. This keeps the function usable with any compatible property-based dataset, while remaining well suited to the Ecuadorian sustainable-use dataset used in the examples below.

Usage

sustainable_uses_pacha(
  species,
  use = NULL,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

sustainable_uses_pacha_md(
  species,
  use = NULL,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

Arguments

Value

sustainable_uses_pacha() prints and invisibly returns a ⁠Category:⁠ heading followed by one indented use per line, for every matching category, or the localized no-data/connection message. sustainable_uses_pacha_md() returns, invisibly, the emitted Markdown string, or "" when no matching sustainable-use data are available.

See Also

accessors-pacha for a detailed description of plain-text and Markdown accessors.

Examples

## Not run: 
sustainable_uses_pacha("Bidens andicola")
sustainable_uses_pacha("Bidens andicola", use = "medicinal", source = "coldp")

## End(Not run)
## Not run: 
sustainable_uses_pacha_md("Bidens andicola", use = "medicinal")

## End(Not run)

Retrieve conservation threat status

Description

Retrieves the conservation-status value documented for a taxon. The API source reads the ChecklistBank taxon-distribution endpoint; the local source reads Distribution.tsv using the same country-aware, deterministic selection rule as establishment_pacha(). Typical values are IUCN categories such as EX, EW, CR, EN, VU, NT, LC, DD, and NE, though the function accepts any status recorded in the underlying dataset.

Usage

threat_status_pacha(species, language = NULL, source = NULL, refresh = FALSE)

threat_status_pacha_md(
  species,
  language = NULL,
  source = NULL,
  refresh = FALSE
)

Arguments

Details

Values are translated through the selected language dictionary's threat mapping. Unmapped source values are returned in sentence case rather than rejected, so alternative assessment schemes remain usable.

Value

threat_status_pacha() prints and invisibly returns a translated conservation-status category, or the localized no-data/connection message. threat_status_pacha_md() returns, invisibly, the emitted Markdown string, or "" when the source has no threat-status record.

See Also

accessors-pacha for a detailed description of plain-text and Markdown accessors.

Examples

## Not run: 
threat_status_pacha("Bidens andicola")
threat_status_pacha("Bidens andicola", source = "coldp", language = "en")

## End(Not run)
## Not run: 
threat_status_pacha_md("Bidens andicola", language = "en")

## End(Not run)