Where a study's data came from

qes_provenance() returns the record of which file a result was read from: the study, its DOI and dataset version, the Dataverse file id and name, the md5 checksum expected and observed, the file's UNF and size, whether the file is the one qesR pins, where and when it was retrieved, its licence, where its labels came from, the reader and the versions of haven and of the qesR catalog. Printing it gives one paragraph per file, ready for a replication log or a methods section.

Usage

qes_provenance(x, level = c("study", "cell", "spec", "pooled"))

Arguments

x: A data frame returned by get_qes() (or get_preview()), the result of qes_download(), or a character vector of study codes (see qes_studies()). For study codes, the record shows what get_qes() would read: nothing has been retrieved or checked yet, so md5_observed, md5_verified, retrieved_via, retrieved_at and label_source are NA.
level: "study" (default): one row per file. "cell", "spec" and "pooled" describe data harmonized by qes_harmonize() ("pooled" only when it has pooled variables); for other objects they are an error of class qesR_error_no_provenance.

Value

A data frame of class qes_provenance. For level = "study", one row per file, with the columns study, doi, dataset_version, file_id, file_name, format, md5_expected, md5_observed, md5_verified, unf, n_rows, n_cols, pinned, retrieved_via ("network", "session_cache", "disk_cache", "local_demo" for the shipped demo study, or "user_data" for a file qes_download() found already in place), retrieved_at (UTC), licence, label_source, label_file_id, name_map_applied, reader, haven_version, catalog_version and dict_version. Columns that do not apply (the reader of a document, say) are NA. For data read from frames given to qes_harmonize() in data, md5_verified is FALSE and retrieved_via is "user_data".

For level = "cell" (harmonized data), one row per study and target: study, wave, target, source_var, rule, map_id, grade, status (of the crosswalk row: stable, or review and draft for rows not yet signed off), instrument, weight_var (the wave's recommended weight), weight_status (reviewed, or needs_review when the weight is not reviewed yet and is NA in the data), weight_mean_raw (the mean of the raw weight over the wave's members), levels_not_offered (structural zeros, ;-separated; empty when every level was offered, NA for targets without levels), included (FALSE when no row was applied), excluded (why not: no_row, the study has no question for the target; not_reviewed, its row is not yet signed off and include_draft = FALSE; not_in_data, the variable is not in the demonstration data; below_grade, its grade is below min_grade; NA when included), n_valid, one count n_<reason> per NA reason (they sum with n_valid to the study's rows), n_outside_universe (for targets about an election: the wave's members who could not vote in it, eligible_voter FALSE; NA for other targets, and NA when eligibility is not available for any member of the wave, for example when its age rows are not signed off and include_draft = FALSE) and note.

For level = "pooled" (harmonized data with pooled variables such as vote_choice), one row per study, pooled variable and member: study, pooled, type (the value of <pooled>__type), member (the target), precedence (1 is tried first), wave and item (<study>:<wave>:<source variables>) of the member's cell, grade (its grade, capped for lossy transforms), used_in_layout (FALSE for a member of another wave than the one the respondent layout takes the study's values from), included (its cell was applied and its grade is at least min_grade), n_value (rows whose value comes from it), n_answer_na (rows it made NA with an answer such as don't know or did not vote) and n_fallthrough (rows NA because no member asked them, reported under this member).

For level = "spec", one row (one per qes_harmonize() call for results combined with rbind()): spec_version, spec_hash, spec_custom, qesR_version, qesR_sha (the commit of a GitHub installation, else NA), args (the arguments of the call, with a fingerprint of any data given in data) and created (UTC).

Details

Data returned by get_qes() (and files saved by qes_download()) carry this record in their attribute qes_provenance. R drops such attributes in some operations, notably merge(); qes_provenance() then raises an error of class qesR_error_no_provenance. Record the provenance before merging, or pass the study codes.

En français

qes_provenance() indique de quel fichier provient un résultat : l'étude, son DOI et la version du jeu de données, l'identifiant et le nom du fichier Dataverse, la somme md5 attendue et observée, l'UNF et la taille du fichier, s'il s'agit du fichier retenu par qesR, où et quand il a été obtenu, sa licence, la source des étiquettes, le lecteur et les versions de haven et du catalogue de qesR. L'affichage donne un paragraphe par fichier, dans la langue des messages. Avec des codes d'étude, la fonction montre ce que get_qes() lirait, sans rien télécharger. Un objet qui a perdu ses attributs (par exemple après merge()) produit une erreur de classe qesR_error_no_provenance.

Examples

demo <- get_qes("qes_demo", assign_global = FALSE, quiet = TRUE)
qes_provenance(demo)
#> qes_demo: file 0 (qes_demo.sav), synthetic data shipped with qesR. md5
#> e956e315800690cb0894c86ed85c8bea, verified. 60 rows, 11 columns. Retrieved on
#> 2026-10-06 05:10:07 UTC (local_demo). Read with haven::read_sav(user_na =
#> TRUE), haven 2.5.5. Licence: CC0 1.0. qesR catalog 2.4.1.
#> 
#> as.data.frame() gives every column.

prov <- as.data.frame(qes_provenance(demo))
prov[, c("study", "file_id", "md5_verified", "retrieved_via")]
#>      study file_id md5_verified retrieved_via
#> 1 qes_demo       0         TRUE    local_demo

# what get_qes() would read, before anything is downloaded
qes_provenance(c("qes2018", "qes2014"))
#> qes2018: file 425914 (Quebec Election Study 2018.dta) of the Dataverse
#> dataset https://doi.org/10.5683/SP3/NWTGWS, version 1.0. Expected md5
#> d24f5b0be727d688ad305b8eb61f0d30 (not yet checked). 3072 rows, 254 columns.
#> Licence: CC0 1.0. qesR catalog 2.4.1.
#> 
#> qes2014: file 425916 (Quebec Election Study 2014.sav) of the Dataverse
#> dataset https://doi.org/10.5683/SP3/64F7WR, version 1.0. Expected md5
#> 9549423b32526a2f11a3d954a87c6861 (not yet checked). 1517 rows, 140 columns.
#> Licence: CC0 1.0. qesR catalog 2.4.1.
#> 
#> as.data.frame() gives every column.

# merge() drops the record: keep it first
prov <- qes_provenance(demo)
merged <- merge(demo, data.frame(extra_column = 1))
try(qes_provenance(merged))
#> Error : `x` does not record which study it comes from (it may have lost its attributes, for example through merge()). Pass study codes instead.