Skip to contents

Retrieves one or more tables from IRW and returns them as tibbles. By default this downloads every row of each table and counts against the Redivis export quota. Pass max_rows and/or columns to transfer a page rather than a table – both are pushed to Redivis, so the rest is never exported. If you only need the item or response value sets, or per-item counts and ranges, use irw_table_sets(), which answers with a server-side query. If the table includes a character resp column, the function attempts to coerce it into numeric. Strings like "NA", "", and NA are treated as missing values. A warning is issued only if other non-numeric values are encountered.

Usage

irw_fetch(
  name,
  source = "core",
  dedup = FALSE,
  max_rows = NULL,
  columns = NULL,
  sim = FALSE,
  comp = FALSE,
  nom = FALSE,
  resp = FALSE,
  cov_args = list()
)

Arguments

name

Character vector of one or more table names (IRW table IDs).

source

Character. The data family: "core" (default), "nom", "sim", "comp", "conj" (conjoint experiments; see irw_conj_long), or "rank" (rankings; see irw_rank_compress). "cov" is the covariance family: a published matrix from it is returned as published, and the name of a core table returns that table's item-by-item correlation or covariance matrix in the same layout, computed by irw_cov_compute() with cov_args; turn either into a square matrix with irw_cov2matrix().

dedup

Logical, optional. If TRUE, deduplicates responses based on timing variables. Defaults to FALSE. If a date column is present, no deduplication is performed. If only a wave column is present, one random response is retained per (id, item) group within each wave. If neither date nor wave is present, one random response is retained per (id, item) pair.

max_rows

Integer, optional. Stop after this many rows. Pushed to Redivis, so only those rows are exported and counted against the account's export quota – which is the point: 326 IRW tables are over a million rows, and a cap applied after the download has already cost the quota. A slice is never written to the disk cache, because it cannot stand in for the table; a cached whole table does serve a slice. The rows are the first max_rows in the table's stored order, not a random sample, and that order can track the outcome: the first 20,000 rows of narcissistic_personality_inventory all have resp = 1. Do not generalise from a slice to the table.

columns

Character vector, optional. Fetch only these columns, also pushed to Redivis. A column the table does not have is an error. Ignored for the download when dedup = TRUE (deduplication needs every column); the columns are then dropped after deduplicating.

sim

Deprecated. Use source = "sim" instead.

comp

Deprecated. Use source = "comp" instead.

nom

Deprecated. Use source = "nom" instead.

resp

Logical, optional. If TRUE, returns response matrix via irw_long2resp(). Defaults to FALSE.

cov_args

List, optional. With source = "cov", the arguments passed to irw_cov_compute(): method ("pearson", "spearman", "kendall", "polychoric", "tetrachoric", or a function of your own), type ("cor" or "cov"), use and max_items.

Value

If a single name is provided, returns a tibble. If multiple, returns a named list of tibbles (or error messages, if retrieval failed).

Details

Each table downloaded is also kept on disk (see irw_cache_dir()) and reused by later fetches, in this session or another, for as long as the table is unchanged on Redivis; the Python package shares the same copies. Switch this off with options(irw.cache = FALSE) or IRW_CACHE=0.

A table the IRW found through another collection, such as openESM, prints that collection's note and citation once per session per collection. Silence it with options(irw.source_note = FALSE) or IRW_SOURCE_NOTE=0.

See also

irw_table_sets() for value sets and summaries without a download; irw_cache_info() for the tables kept on disk.

Examples

if (FALSE) { # irw_has_credentials() || nzchar(Sys.getenv("IRW_RUN_EXAMPLES"))
# \donttest{
# Main IRW data
irw_fetch("environment_ltm")

# A look at a large table without exporting all of it
irw_fetch("neurips_2020", max_rows = 100)
irw_fetch("neurips_2020", columns = c("id", "item", "resp"), max_rows = 1000)

# An item correlation matrix, computed from the table
m <- irw_fetch("environment_ltm", source = "cov", cov_args = list(method = "polychoric"))
irw_cov2matrix(m)$matrix

# Deduplicated
irw_fetch("pks_probability", dedup = TRUE)

# Simulation data
irw_fetch("gilbert_meta_3", source = "sim")

# Competition data
irw_fetch("collegefb_2021and2022", source = "comp")
# }
}