Rglottography: Programmatic Access to the 'Glottography' Geolinguistic Data Platform

Description

Provides programmatic access to Glottography, an online repository of geospatial speaker-area polygons for the world's languages. This package allows users to list available datasets, download and install them, and load speaker-area polygons as standard spatial 'sf' objects in R.

Details

The package is the primary R interface for the Glottography data platform. It simplifies the workflow of obtaining georeferenced speaker areas linked to 'Glottolog' identifiers.

Key functions

• list_datasets: View available datasets.

• install_datasets: Download Glottography datasets from GitHub or Zenodo.

• load_datasets: Load Glottography datasets into the current R session.

• set_cache_dir: Manage where datasets are stored locally.

Author(s)

Maintainer: Peter Ranacher peter.ranacher@gmail.com

References

Ranacher, P., et al. (2026). "Glottography: an open-source geolinguistic data platform for mapping the world’s languages." Journal of Open Humanities Data. doi:10.5334/johd.459

See Also

Useful links:

• https://github.com/Glottography/Rglottography

• Report bugs at https://github.com/Glottography/Rglottography/issues

Collect sources referenced by a Glottography object

Description

Extracts and returns the unique source identifiers referenced by a Glottography object. If the input is a glottography_collection, sources are taken directly from the object. Otherwise, the function determines the associated datasets, reads them from the local registry, and collects all referenced sources.

Usage

collect_sources(glottography)

Arguments

Value

A character vector of unique source identifiers referenced by the input glottography object, in BibTeX format.

Install Glottography datasets

Description

Installs Glottography datasets by checking their status in the registry and downloading them from the Zenodo Glottography community.

Usage

install_datasets(datasets, update = c("missing", "outdated", "always"))

Arguments

Details

By default, datasets are cached in the directory returned by tools::R_user_dir("Rglottography", "data"). You can change the cache location using set_cache_dir(path).

Value

Invisibly returns the installed datasets, or NULL if none were installed.

List available Glottography datasets

Description

Lists all available Glottography datasets. The function reads the package’s registry file, which contains metadata for all datasets along information on local installation status.

Usage

list_datasets(online = TRUE)

Arguments

Details

If online = TRUE and an internet connection is available, the function attempts to sync the registry with the Glottography community on Zenodo by updating the local registry. Otherwise, it runs in offline mode and uses the local, unsynced registry.

Value

A data.frame containing metadata and status information for all Glottography datasets with the following columns:

• name: Dataset name. Serves as a unique identifier.

• installed: Logical; whether the dataset is installed locally.

• created: Creation date of the dataset on Zenodo.

• version: Latest available version online.

• version_local: Version currently installed locally, or NA if none.

• modified: Timestamp of the most recent online update.

• modified_local: Timestamp of the local version, or NA if none.

Load Glottography datasets

Description

Loads Glottography speaker area data and associated metadata from the Glottography collection into the current R session, optionally installing missing datasets.

Usage

load_datasets(
  datasets = "installed",
  level = c("all", "features", "languages", "families"),
  install_missing = FALSE,
  sync_registry = FALSE
)

Arguments

Details

If install_missing = TRUE, the function automatically installs any missing datasets before loading.

Value

A validated Glottography collection (S3 class glottography_collection) containing the following components (if requested):

• features: a glottography_features object; speaker areas according to the original source classification.

• languages: a glottography_languages object; speaker areas aggregated at the Glottolog language level.

• families: a glottography_families object; speaker areas aggregated at the Glottolog family level.

• sources: a glottography_sources object; list of bibliographic references in BibTeX format.

Components not requested are omitted.

Set cache directory for Rglottography

Description

Sets the cache directory used by Rglottography for storing datasets and the registry. Optionally, existing cache files from the current cache directory can be copied to the new location and removed from the old.

Usage

set_cache_dir(path, copy_existing = TRUE, remove_old = FALSE)

Arguments

Value

Invisibly returns the path to the new cache directory. Sets the option "Rglottography.cache_dir" for the current session.