get_dataset: 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,
  ...
)

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.

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.

Examples

Run this code

# \donttest{
# 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)


# \dontshow{
# cleanup
clear_cache(force = TRUE)
# }
# }