Title:	Access the Open Experience Sampling Method Database
Version:	0.1.0
Description:	Provides programmatic access to the Open Experience Sampling Method ('openESM') database (https://openesmdata.org), a collection of harmonized experience sampling datasets. The package enables researchers to discover, download, and work with the datasets while ensuring proper citation and license compliance.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	cli (≥ 3.6.0), fs, httr2, jsonlite, readr, purrr, dplyr, tibble, zen4R
Depends:	R (≥ 4.1.0)
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
URL:	https://github.com/openesm-project/openesm-r
BugReports:	https://github.com/openesm-project/openesm-r/issues
NeedsCompilation:	no
Packaged:	2025-10-25 06:24:36 UTC; Bjoern
Author:	Björn S. Siepe [aut, cre, cph], Matthias Kloft [aut]
Maintainer:	Björn S. Siepe <bjoernsiepe@gmail.com>
Repository:	CRAN
Date/Publication:	2025-10-29 20:00:07 UTC

openesm: Access the Open Experience Sampling Method Database

Description

Provides programmatic access to the Open Experience Sampling Method ('openESM') database (https://openesmdata.org), a collection of harmonized experience sampling datasets. The package enables researchers to discover, download, and work with the datasets while ensuring proper citation and license compliance.

Author(s)

Maintainer: Björn S. Siepe bjoernsiepe@gmail.com (ORCID) [copyright holder]

Authors:

• Matthias Kloft kloft.dev@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/openesm-project/openesm-r

• Report bugs at https://github.com/openesm-project/openesm-r/issues

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

Value

Citation information for the dataset(s)

Examples

# Get citation for a dataset
dataset <- get_dataset("0001")
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

Value

Character string with citation information, returned invisibly.

Examples

dataset <- get_dataset("0001")
cite(dataset)

Clear the openesm cache

Description

Removes all cached openesm data from your local machine.

Usage

clear_cache(force = FALSE)

Arguments

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

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)

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

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

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

# Get list of all available datasets
datasets <- list_datasets()

# Force fresh download of index
fresh_list <- list_datasets(cache_hours = 0)

# Use specific metadata version
datasets_v1 <- list_datasets(metadata_version = "1.0.0")

# Use dataset 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

Value

Additional notes and information about the dataset(s)

Examples

# Get notes for a dataset
dataset <- get_dataset("0001")
notes(dataset)

Get additional notes for dataset

Description

Get additional notes for dataset

Usage

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

Arguments

Value

Character vector with dataset notes, returned invisibly.

Examples

dataset <- get_dataset("0001")
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

Value

Invisibly returns the original object.

Examples

dataset <- get_dataset("0001")
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

Value

Invisibly returns the original object.

Examples

datasets <- get_dataset(c("0001", "0002"))
print(datasets)