Package 'Rglottography'

Title: Programmatic Access to Glottography Speaker Area Polygons
Description: Provides programmatic access to Glottography, an online repository of geospatial speaker-area polygons for the world's languages. The package allows users to list available datasets, download and install them, and load speaker-area polygons as standard spatial 'sf' objects in R. Data are sourced from either the Glottography organization on GitHub <https://github.com/Glottography> or the Glottography community on Zenodo <https://zenodo.org/communities/glottography>. Based on Ranacher et al. (2026) <doi:10.5334/johd.459>.
Authors: Peter Ranacher [aut, cre]
Maintainer: Peter Ranacher <[email protected]>
License: MIT + file LICENSE
Version: 1.2.0
Built: 2026-05-25 10:32:04 UTC
Source: https://github.com/glottography/rglottography

Help Index

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

glottography

A Glottography object of class glottography_features, glottography_languages, or glottography_families; a data.frame derived from a Glottography object (containing a dataset column); or a glottography_collection. For non-collection inputs, the function identifies the associated datasets and retrieves their sources from the local registry.

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

datasets

Character vector specifying the datasets to install, or one of the following special values:

  • "all": install all available datasets.

  • "outdated": install all datasets for which an update is available (new version or updated timestamp).

  • "missing": install all datasets that are not yet installed.

update

Character string indicating when selected datasets should be installed. One of:

  • "outdated": install only if an update is available on Zenodo.

  • "missing": install only if the dataset is not present locally.

  • "always": install regardless of local status.

This argument is ignored when datasets is "all", "outdated", or "missing".

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

online

Logical. Should the function attempt to sync the registry with the online version? Defaults to TRUE.

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

datasets

Character vector specifying the names of datasets to load, or one of the following special values:

  • "installed": all datasets already installed locally.

  • "all": all datasets (attempts to install any missing datasets).

level

Character vector specifying the level(s) of aggregation to load:

  • "features": speaker areas according to the original source classification.

  • "languages": speaker areas aggregated at the Glottolog language level.

  • "families": speaker areas aggregated at the Glottolog family level.

  • "all": all levels.

Only valid levels will be selected.
install_missing

Logical. If TRUE, allows automatic downloading and installation of missing datasets.
sync_registry

Logical. If TRUE, synchronises the local registry with Zenodo before loading datasets.

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.

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

Author(s)

Maintainer: Peter Ranacher [email protected]

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:

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

path

Character string specifying the path to the new cache directory.
copy_existing

Logical; if TRUE, copies existing cache files from the current to the new cache directory. Defaults to TRUE.
remove_old

Logical; if TRUE, deletes cache files from old cache. Defaults to FALSE.

Value

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