Package 'openesm'

Display information about the openesm cache

Description

Shows the location and total size of the local file cache.

Usage

cache_info()

Value

Invisibly returns NULL.

Examples

# view cache information
cache_info()

---

Citation information for openESM datasets

Description

Citation information for openESM datasets

Usage

cite(x, ...)

Arguments

x	An object of class openesm_dataset.
...	Additional arguments passed to methods

Value

Citation information for the dataset(s)

Examples

dataset <- structure(
  list(
    dataset_id = "0001",
    metadata = list(
      reference_a = "@article{fried2022, author = {Fried}, year = {2022}}"
    )
  ),
  class = "openesm_dataset"
)
cite(dataset)

---

Get citation information for dataset

Description

Get citation information for dataset

Usage

## S3 method for class 'openesm_dataset'
cite(x, format = "bibtex", ...)

Arguments

x	An object of class openesm_dataset.
format	Character string specifying citation format. Currently only "bibtex" is supported.
...	Additional arguments (currently unused).

Value

Character string with citation information, returned invisibly.

Examples

# Minimal object to demonstrate the method (no API call)
dataset <- structure(
  list(
    dataset_id = "0001",
    metadata = list(
      reference_a = "@article{fried2022, author = {Fried}, year = {2022}}"
    )
  ),
  class = "openesm_dataset"
)
cite(dataset)

---

Clear the openesm cache

Description

Removes all cached openesm data from your local machine.

Usage

clear_cache(force = FALSE)

Arguments

force

Logical. If TRUE, will not ask for confirmation before deleting. Default is FALSE.

Value

Invisibly returns NULL.

Examples

# clear cache with confirmation prompt
if (interactive()) {
  clear_cache()
}

# force clear without confirmation
clear_cache(force = TRUE)

---

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.

Requires an active internet connection. Download time depends on Zenodo availability and dataset size.

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()

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

# Access the data and metadata
head(dataset$data)
dataset$metadata
dataset$dataset_version
dataset$metadata_version

# Download multiple datasets at once
datasets <- get_dataset(c("0001", "0002"))
datasets[["0001"]]$data

# Pin a specific metadata catalog version for reproducibility
dataset_v1 <- get_dataset("0001", metadata_version = "1.0.0")

# Force re-download even if a cached copy exists
dataset_fresh <- get_dataset("0001", force_download = TRUE)

---

List available ESM datasets from openESM repository

Description

Retrieves a list of available Experience Sampling Method (ESM) datasets from the openESM metadata repository. Returns a tibble with dataset information and metadata that can be used with get_dataset().

Usage

list_datasets(cache_hours = 24, metadata_version = "latest", max_attempts = 15)

Arguments

cache_hours	Numeric. Number of hours to consider the cached dataset index valid. Default is 24. Set to 0 to force fresh download.
metadata_version	Character string specifying the metadata catalog version. Default is "latest" which downloads the most recent version.
max_attempts	Integer, maximum number of retry attempts for Zenodo API calls. Default is 15.

Details

This function downloads and caches a master index of available datasets from the openESM metadata repository, which is hosted on Zenodo. The index is cached locally to avoid repeated downloads. Use cache_hours = 0 to force a fresh download of the index.

The returned tibble can be filtered and explored to identify datasets of interest before downloading with get_dataset().

Requires an active internet connection. Download time depends on Zenodo availability and the size of the metadata archive.

Value

A tibble with one row per dataset containing:

• dataset_id: Character string with unique dataset identifier

• first_author: Character string with first author's surname

• year: Numeric year of publication

• reference_a: Character string with primary reference

• reference_b: Character string with secondary reference (if available)

• paper_doi: Character string with publication DOI

• zenodo_doi: Character string with Zenodo dataset DOI

• license: Character string with dataset license

• link_to_data: Character string with direct data link

• link_to_codebook: Character string with codebook link

• link_to_code: Character string with analysis code link

• n_participants: Numeric number of participants

• n_time_points: Numeric number of time points

• n_beeps_per_day: Character string with beeps per day information

• passive_data_available: Character string indicating passive data availability

• cross_sectional_available: Character string indicating cross-sectional data availability

• topics: Character string with study topics

• implicit_missingness: Character string with missingness information

• raw_time_stamp: Character string with timestamp format information

• sampling_scheme: Character string with sampling scheme details

• participants: Character string with participant information

• coding_file: Character string with coding file information

• additional_comments: Character string with additional notes

• features: List column containing feature tibbles for each dataset

See Also

get_dataset() to download specific datasets

Examples

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

# Force a fresh download regardless of cache age
fresh_list <- list_datasets(cache_hours = 0)

# Pin a specific metadata catalog version
datasets_v1 <- list_datasets(metadata_version = "1.0.0")

# Use the returned IDs with get_dataset()
dataset <- get_dataset(datasets$dataset_id[1])

---

Additional notes for openESM datasets

Description

Additional notes for openESM datasets

Usage

notes(x, ...)

Arguments

x	An object of class openesm_dataset.
...	Additional arguments passed to methods

Value

Additional notes and information about the dataset(s)

Examples

dataset <- structure(
  list(
    dataset_id = "0001",
    metadata = list(
      additional_comments = "Note about timing; Note about exclusions"
    )
  ),
  class = "openesm_dataset"
)
notes(dataset)

---

Get additional notes for dataset

Description

Get additional notes for dataset

Usage

## S3 method for class 'openesm_dataset'
notes(x, ...)

Arguments

x	An object of class openesm_dataset.
...	Additional arguments (currently unused).

Value

Character vector with dataset notes, returned invisibly.

Examples

dataset <- structure(
  list(
    dataset_id = "0001",
    metadata = list(
      additional_comments = "Note about timing; Note about exclusions"
    )
  ),
  class = "openesm_dataset"
)
notes(dataset)

---

S3 Methods for openesm objects Print method for openesm_dataset

Description

S3 Methods for openesm objects Print method for openesm_dataset

Usage

## S3 method for class 'openesm_dataset'
print(x, ...)

Arguments

x	An object of class openesm_dataset.
...	Additional arguments (currently unused).

Value

Invisibly returns the original object.

Examples

dataset <- structure(
  list(
    dataset_id = "0001",
    dataset_version = "1.0.0",
    metadata_version = "1.3.0",
    metadata = list(
      first_author = "Fried",
      year = "2022",
      paper_doi = "10.1234/example",
      license = "CC-BY-4.0",
      n_participants = 100L,
      n_time_points = 70L
    )
  ),
  class = "openesm_dataset"
)
print(dataset)

---

Print method for a list of openesm_dataset objects

Description

Print method for a list of openesm_dataset objects

Usage

## S3 method for class 'openesm_dataset_list'
print(x, ...)

Arguments

x	An object of class openesm_dataset_list.
...	Additional arguments (currently unused).

Value

Invisibly returns the original object.

Examples

datasets <- structure(
  list(
    "0001" = structure(list(dataset_id = "0001"), class = "openesm_dataset"),
    "0002" = structure(list(dataset_id = "0002"), class = "openesm_dataset")
  ),
  class = c("openesm_dataset_list", "list")
)
print(datasets)

---