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
)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; seeirw_conj_long), or"rank"(rankings; seeirw_rank_compress).- dedup
Logical, optional. If TRUE, deduplicates responses based on timing variables. Defaults to FALSE. If a
datecolumn is present, no deduplication is performed. If only awavecolumn is present, one random response is retained per (id, item) group within each wave. If neitherdatenorwaveis 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.
- 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.
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)
# Deduplicated
irw_fetch("pks_probability", dedup = TRUE)
# Simulation data
irw_fetch("gilbert_meta_3", source = "sim")
# Competition data
irw_fetch("collegefb_2021and2022", source = "comp")
# }
}