# Rglottography - Getting started

This vignette introduces the basic functionality of the `Rglottography` package. An advanced vignette on creating language maps with `Rglottography` and third-party packages is provided in `mapping_languages.Rmd`.

## Introduction

Glottography is a collection of datasets that describe the spatial extent of speaker areas, that is, the geographic regions in which particular languages are spoken. The `Rglottography` package provides functions for working with these data, including downloading geospatial datasets and converting them to `sf` format. Data are sourced from either the Glottography organization on GitHub or the Glottography community on Zenodo.

Each Glottography dataset includes three geospatial representations of the speaker areas:

- `features`: speaker areas as depicted in the original source publication.

- `languages`: speaker areas aggregated at the Glottolog language level.

- `families`: speaker areas aggregated at the Glottolog family level.

Additionally, the `sources` object contains complete bibliographic references for all datasets in BibTeX format.

## Listing Datasets

Users can list all available Glottography datasets and view their version, creation date, and installation status on the local machine. Setting `online = TRUE` checks the Glottography community on Zenodo for updates before listing available datasets.

    available_datasets <- list_datasets(online = FALSE)

## Installing datasets

Users can install individual Glottography datasets (e.g. `matsumae2021exploring`), all available datasets (`"all"`), or only those datasets that are missing from their local machine (`"missing"`). Installation examples are shown for illustration only and are not run during package checks.

    install_datasets(datasets = "asher2007world")

## Load Glottography data

Users can load installed Glottography datasets into the current R session as a single collection. The `datasets` argument accepts either a character vector specifying the names of datasets to load or one of the special values `"installed"`, which loads all datasets already installed locally, or `"all"`, which loads all available datasets and installs any missing datasets if necessary. By default, the returned Glottography collection includes all available levels (`features`, `languages`, and `families`), but users can restrict which levels are loaded.

    collection <- load_datasets(datasets = "installed", level = "all")

    features <- collection$features
    languages <- collection$languages
    families <- collection$families
    sources <- collection$sources

## Collecting Sources

`Rglottography` makes it straightforward to extract the scientific references for all language polygons used, for example, in a map. For any Glottography object — a complete collection, `features`, `languages`, `families`, or any subset thereof — users can collect the bibliographic references in BibTeX format, print them, or write them to a file.

    sources <- collect_sources(languages)
    writeLines(sources)

## References and Further Reading

- Primary Citation: Ranacher 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

- Getting started: An introduction to the package’s basic functionality is available in `vignette("getting_started", package = "Rglottography")`.

- Documentation: Consult the package documentation for each function for detailed usage information (e.g., `?load_datasets` or `?Rglottography`).