get_dataset: Download ESM dataset(s) from openESM repository

In openesm: Access the Open Experience Sampling Method Database

Download ESM dataset(s) from openESM repository

Description

Downloads one or more Experience Sampling Method (ESM) datasets from the openESM repository hosted on Zenodo. Returns an S3 object containing the dataset and associated metadata.

Usage

get_dataset(
  dataset_id,
  version = "latest",
  cache = TRUE,
  path = NULL,
  force_download = FALSE,
  sandbox = FALSE,
  quiet = FALSE,
  max_attempts = 15,
  ...
)

Arguments

dataset_id	Character string or vector of dataset IDs. Use list_datasets() to see available datasets.
version	Character string specifying the dataset version. Default is "latest" which downloads the most recent version.
cache	Logical. If TRUE (default), uses cached version if available and not expired.
path	Character string specifying custom download path. If NULL (default), files are cached in the user's cache directory.
force_download	Logical. If TRUE, forces re-download even if cached version exists. Default is FALSE.
sandbox	Logical. If TRUE, uses Zenodo sandbox environment for testing. Default is FALSE.
quiet	Logical. If TRUE, suppresses informational messages. Default is FALSE.
max_attempts	Integer, maximum number of retry attempts for Zenodo API calls. Default is 15.
...	Additional arguments passed to list_datasets(). This includes metadata_version to specify the metadata catalog version.

Details

This function downloads ESM datasets from Zenodo using DOIs stored in the openESM metadata repository. Datasets are cached locally to avoid repeated downloads. Use force_download = TRUE to refresh cached data.

The function handles both individual datasets and batch downloads. When downloading multiple datasets, progress is shown for each download.

Value

For single dataset: An S3 object of class openesm_dataset containing:

• data: A tibble with the ESM data

• metadata: List with dataset metadata

• dataset_id: Character string with dataset identifier

• dataset_version: Character string with dataset version number

• metadata_version: Character string with metadata catalog version

For multiple datasets: An S3 object of class openesm_dataset_list containing a named list of openesm_dataset objects.

See Also

list_datasets() for available datasets, cite() for citation information

Examples

# List available datasets first
available <- list_datasets()
head(available)

# Download a single dataset
dataset <- get_dataset("0001")

# Access the data
head(dataset$data)

# View metadata and provenance information
dataset$metadata
dataset$dataset_version  # Dataset version
dataset$metadata_version # Metadata catalog version

# Download multiple datasets
datasets <- get_dataset(c("0001", "0002"))

# Access individual datasets from the list
datasets[["0001"]]$data

# Use specific metadata catalog version
dataset_v1 <- get_dataset("0001", metadata_version = "1.0.0")

# Force re-download to get latest version
dataset_fresh <- get_dataset("0001", force_download = TRUE)

openesm documentation built on Dec. 3, 2025, 5:08 p.m.