Download a correspondence (mapping) table between two classifications

Source: R/retrieveCorrespondenceTable.R

Downloads a correspondence table, a mapping of codes, from one statistical classification (A) to another (B) from an online service (CELLAR or FAO), and returns it as a plain data frame. The function has no side effects (it does not read or write files).

A correspondence table tells you which codes in classification A relate to which codes in classification B (e.g., NACE2 → CPA21).

retrieveCorrespondenceTable(
  endpoint,
  prefix,
  ID_table,
  language = "en",
  showQuery = FALSE
)

Arguments

endpoint

Character. The online service to query. Case-insensitive. Supported values are those returned by the internal endpoint registry (e.g., "CELLAR", "FAO").

prefix

Character. Catalogue prefix where the correspondence is published (e.g., "nace2", "cpa21", "cn2022"). Use correspondenceTableList() to discover valid values.

ID_table

Character. Identifier of the correspondence, typically of the form "A_B" such as "NACE2_CPA21" or "CN2022_NACE2". Discover identifiers via correspondenceTableList().

language

Character. Preferred label language as a BCP‑47 code. Defaults to "en" (English). Examples: "fr", "de".

showQuery

Logical. If TRUE, returns a list with the SPARQL query and the result data frame; otherwise (default) returns just the data frame.

Value

A data.frame where each row represents one mapping from the source classification (A) to the target classification (B).

Columns (when available):

  • CorrespondenceID: Requested identifier (e.g., "NACE2_CPA21").

  • Prefix: Catalogue prefix (constant per table).

  • A: Source code (A parsed from ID_table).

  • B: Target code (B parsed from ID_table).

  • Label_A, Label_B: Human‑readable labels in language.

  • Include_A, Exclude_A, Include_B, Exclude_B: Notes, if available.

  • Comment: Free‑text comment on the mapping, if any.

  • URL: URI of the mapping association.

Attributes attached for traceability:

  • endpoint, endpoint_url, prefix, ID_table

  • A, B, language, normalized_codes, anchor_mode, anchor

Details

When to use this. Use retrieveCorrespondenceTable() when you know (or have discovered) the prefix and ID_table of a correspondence and want the mapping rows as a standard data frame.

How it works (short).

  1. Validates the selected service (endpoint).

  2. Optionally resolves a stable anchor via correspondenceTableList().

  3. Builds a SPARQL query returning source/target codes, labels, notes, and link URI.

  4. Issues an HTTP request and parses the response into a data frame.

Notes

  • The function focuses on retrieval. Any code normalization is left to downstream steps.

Examples

if (FALSE) { # \dontrun{
# 1) Discover available correspondences at CELLAR
ct <- correspondenceTableList(endpoint = "CELLAR")
subset(ct, grepl("NACE2", ID) & grepl("CPA21", ID))

# 2) Retrieve one correspondence (English labels)
x <- retrieveCorrespondenceTable(
  endpoint = "CELLAR",
  prefix   = "nace2",
  ID_table = "NACE2_CPA21",
  language = "en"
)
head(x)

# 3) Save to CSV explicitly if needed (no automatic writing)
# utils::write.csv(x, "NACE2_CPA21.csv", row.names = FALSE)

# 4) Inspect the generated SPARQL query
dbg <- retrieveCorrespondenceTable(
  endpoint = "FAO",
  prefix   = "cpa21",
  ID_table = "NACE2_CPA21",
  showQuery = TRUE
)
message(substr(dbg$SPARQL.query, 1, 400), "...")
} # }