Package {likingInitiative}

likingInitiative: the Liking Rating Database in R

Description

Subjective liking ratings from published decision-making studies.

Details

Data is read from versioned release files, so a pinned version returns the same rows however long from now, and analyses keep working when the web service does not. Downloads are cached in the session's temporary directory; call use_persistent_cache() to keep them between sessions instead.

Two things to get right:

• Cross-study comparisons must use normalized_rating. Response scales differ between studies (0-4, 1-100, 1-870, willingness-to-pay in dollars), so raw rating values are not comparable. normalized_rating is (rating - scale_min) / (scale_max - scale_min) and always lies in 0-1.

• Subject ids are unique only within a dataset. Subject "12" in two datasets is two different people; key on dataset_code and subject_id together.

Author(s)

Maintainer: Kianté Fernandez kiantefernan@gmail.com [copyright holder]

See Also

Useful links:

• https://liking-rating-frontend.onrender.com

• https://github.com/liking-initiative/likingInitiative-r

• Report bugs at https://github.com/liking-initiative/likingInitiative-r/issues

BibTeX for a dataset's source publication

Description

BibTeX for a dataset's source publication

Usage

bibtex(x, ...)

Arguments

Value

A character string holding a BibTeX entry.

Examples

bibtex(get_dataset("leeholyoak2021"))

Report on the local asset cache

Description

Shows where downloaded release files are kept, how much space they use, and which versions are present.

Usage

cache_info()

Value

A list, invisibly, with path, bytes and versions.

Examples

cache_info()

Citation text

Description

Please cite both the database and the study whose data you used.

Usage

cite(x, ...)

Arguments

Value

A character string.

Examples

cite()

Delete cached release files

Description

Delete cached release files

Usage

clear_cache(version = NULL)

Arguments

Value

Invisibly, the number of bytes freed.

Examples

clear_cache()

Download one or more datasets

Description

Reads a dataset's ratings from the release, with the metadata needed to interpret them.

Usage

get_dataset(dataset, version = "latest", timepoint = NULL)

Arguments

Details

Two datasets repeat their rating phase – leeholyoak2021 (phases 1-3) and leehare2023exp2 (phases 1-2). For those, subject_id and item_id together are not unique; include timepoint, or pass the timepoint argument to take a single phase.

Value

An object of class likingInitiative_dataset with elements data (a tibble), metadata, dataset_code and version. For several datasets, a named list of them.

Examples

d <- get_dataset("leeholyoak2021")
head(d$data)
d$metadata$rating_scale_max
cite(d)

One stimulus across every study that used it

Description

The cross-study view. Because the underlying studies use different response scales, compare on normalized_rating, not rating.

Usage

get_item(item, version = "latest")

Arguments

Details

Only the first rating phase of a repeated-phase dataset is included, so those studies do not carry extra weight in a cross-study comparison.

Value

An object of class likingInitiative_item with data, datasets and version.

Examples

k <- get_item("kitkat")
k$data

List the datasets in the database

Description

timepoints gives the rating phases a dataset holds. All but two datasets have a single phase; see get_dataset().

Usage

list_datasets(version = "latest")

Arguments

Value

A tibble with one row per dataset.

Examples

list_datasets()

List the stimuli in the database

Description

List the stimuli in the database

Usage

list_items(version = "latest")

Arguments

Value

A tibble with one row per item.

Examples

list_items()

List the publications in the database

Description

List the publications in the database

Usage

list_studies(version = "latest")

Arguments

Value

A tibble with one row per study.

Examples

list_studies()

The whole corpus in one call

Description

The whole corpus in one call

Usage

load_database(version = "latest")

Arguments

Value

A list of tibbles: ratings, studies, datasets, items. Held in memory after the first call.

Examples

db <- load_database()
nrow(db$ratings)

Resolving a release version and fetching its assets

Description

The package reads versioned release files rather than a live service, so a pinned version returns the same rows however long from now, and analyses keep working when the web service does not.

Details

Assets come from Zenodo, which needs no credentials and mints a permanent DOI per version. The package resolves the concept record – what Zenodo calls "all versions" – so latest follows new releases without the package itself needing an update.

Set the likingInitiative.release_dir option (or the LIKING_INITIATIVE_RELEASE_DIR environment variable) to a directory built by scripts/build_release.py to work against an unreleased build. The test suite uses this, so tests never touch the network.

Version, date and headline counts for the release in use

Description

Version, date and headline counts for the release in use

Usage

release_info(version = "latest")

Arguments

Value

A list describing the release.

Examples

release_info()

Keep downloaded files between sessions

Description

By default release files are cached inside the session's temporary directory, so nothing is written outside it and the cache goes away when R exits. Call this to cache in a directory that persists instead, so a later session reuses the files rather than downloading them again.

Usage

use_persistent_cache(dir = tools::R_user_dir("likingInitiative", "cache"))

Arguments

Details

The choice lasts for the session. Put likingInitiative::use_persistent_cache() in your .Rprofile to make it the default for every session, and use clear_cache() to remove what it has stored.

Value

The cache directory, invisibly.

Examples

# cache somewhere disposable for the rest of this session
use_persistent_cache(tempfile("likingInitiative-cache-"))