| Title: | 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. |
| Authors: | Björn S. Siepe [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-9558-4648>), Matthias Kloft [aut] (ORCID: <https://orcid.org/0000-0003-1845-6957>) |
| Maintainer: | Björn S. Siepe <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-06-05 06:14:45 UTC |
| Source: | https://github.com/openesm-project/openesm-r |
Shows the location and total size of the local file cache.
cache_info()cache_info()
Invisibly returns NULL.
# view cache information cache_info()# view cache information cache_info()
Citation information for openESM datasets
cite(x, ...)cite(x, ...)
x |
An object of class |
... |
Additional arguments passed to methods |
Citation information for the dataset(s)
# Get citation for a dataset dataset <- get_dataset("0001") cite(dataset)# Get citation for a dataset dataset <- get_dataset("0001") cite(dataset)
Get citation information for dataset
## S3 method for class 'openesm_dataset' cite(x, format = "bibtex", ...)## S3 method for class 'openesm_dataset' cite(x, format = "bibtex", ...)
x |
An object of class |
format |
Character string specifying citation format. Currently only "bibtex" is supported. |
... |
Additional arguments (currently unused). |
Character string with citation information, returned invisibly.
# 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)# 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)
Removes all cached openesm data from your local machine.
clear_cache(force = FALSE)clear_cache(force = FALSE)
force |
Logical. If |
Invisibly returns NULL.
# clear cache with confirmation prompt if(interactive()) { clear_cache() } # force clear without confirmation clear_cache(force = TRUE)# clear cache with confirmation prompt if(interactive()) { clear_cache() } # force clear without confirmation clear_cache(force = TRUE)
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.
get_dataset( dataset_id, version = "latest", cache = TRUE, path = NULL, force_download = FALSE, sandbox = FALSE, quiet = FALSE, max_attempts = 15, ... )get_dataset( dataset_id, version = "latest", cache = TRUE, path = NULL, force_download = FALSE, sandbox = FALSE, quiet = FALSE, max_attempts = 15, ... )
dataset_id |
Character string or vector of dataset IDs. Use
|
version |
Character string specifying the dataset version. Default is "latest" which downloads the most recent version. |
cache |
Logical. If |
path |
Character string specifying custom download path. If |
force_download |
Logical. If |
sandbox |
Logical. If |
quiet |
Logical. If |
max_attempts |
Integer, maximum number of retry attempts for Zenodo API calls. Default is 15. |
... |
Additional arguments passed to |
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.
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.
list_datasets() for available datasets,
cite() for citation information
# 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 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)
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().
list_datasets(cache_hours = 24, metadata_version = "latest", max_attempts = 15)list_datasets(cache_hours = 24, metadata_version = "latest", max_attempts = 15)
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. |
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().
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
get_dataset() to download specific datasets
# List 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])# List 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
notes(x, ...)notes(x, ...)
x |
An object of class |
... |
Additional arguments passed to methods |
Additional notes and information about the dataset(s)
# Get notes for a dataset dataset <- get_dataset("0001") notes(dataset)# Get notes for a dataset dataset <- get_dataset("0001") notes(dataset)
Get additional notes for dataset
## S3 method for class 'openesm_dataset' notes(x, ...)## S3 method for class 'openesm_dataset' notes(x, ...)
x |
An object of class |
... |
Additional arguments (currently unused). |
Character vector with dataset notes, returned invisibly.
dataset <- structure( list( dataset_id = "0001", metadata = list( additional_comments = "Note about timing; Note about exclusions" ) ), class = "openesm_dataset" ) notes(dataset)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
## S3 method for class 'openesm_dataset' print(x, ...)## S3 method for class 'openesm_dataset' print(x, ...)
x |
An object of class |
... |
Additional arguments (currently unused). |
Invisibly returns the original object.
dataset <- get_dataset("0001") print(dataset)dataset <- get_dataset("0001") print(dataset)
Print method for a list of openesm_dataset objects
## S3 method for class 'openesm_dataset_list' print(x, ...)## S3 method for class 'openesm_dataset_list' print(x, ...)
x |
An object of class |
... |
Additional arguments (currently unused). |
Invisibly returns the original object.
datasets <- get_dataset(c("0001", "0002")) print(datasets)datasets <- get_dataset(c("0001", "0002")) print(datasets)