Extract Dataset-Level Metadata

Returns whole-dataset metadata — the survey name, the display name, the fielding vendor, and the field dates — from a survey design object or a data frame.

Usage

extract_dataset_metadata(x, ..., key = NULL, format = "list", fill = NULL)

Arguments

x

A survey design object or data.frame.

...

Keys to return, as bare names (vendor) or strings ("vendor"). Supports !!! splicing of a character vector of names. Matching is by plain name and is not tidy-select: a key is not a column, so selection helpers such as all_of() are rejected. Repeated requests are deduplicated, keeping the first position. If empty, returns every key that is set.

key

character vector of key names, or NULL (default). A programmatic alternative to ...; supplying both is an error. Must be supplied by name, because it follows ....

format

character(1). Output shape: "list" (default) or "data_frame". Must be supplied by name, because it follows ....

fill

NULL (default), NA, or NA_character_. Has two effects. For keys named in ... or key that are not set: NULL omits them, while NA and NA_character_ include them with a missing value. With an empty request, a non-NULL fill returns the full six-key schema with every absent key filled — the codebook idiom. Must be supplied by name, because it follows ....

Value

• "list" (default): named list of the stored values, in request order, or canonical key order for an empty request. Date keys are Date(1). A filled absent key is type-matched: as.Date(NA) for field_start and field_end, NA_character_ for the four character keys. Empty result: list().

• "data_frame": tibble with columns key and value, both character. A Date renders through format() as YYYY-MM-DD, and a filled absent key is always NA_character_ regardless of its type. Empty result: zero-row tibble with both columns.

Details

The key vocabulary is closed. Exactly six keys are valid, and this is their canonical order:

survey_name

character(1). Full formal survey name.

data_name

character(1). Display label for this dataset.

vendor

character(1). Fielding vendor.

field_start

Date(1). First day in the field.

field_end

Date(1). Last day in the field.

field_period

character(1). Prose field period, for display.

survey_name and data_name are independent. This function never reads one to compute the other, and it never composes a label from the field dates.

On a survey design object the stored metadata is the single source of truth; attributes on the underlying data frame are not consulted. On a data frame the six attribute names above are read directly, plus the pre-1.2.0 name dates, which is read as field_period when no field_period attribute is present. Any other attribute is ignored. An attribute whose value fails the type rules above is dropped silently — this function never warns.

A design object restored from a file written by surveycore 1.1.0 or earlier reports no dataset metadata rather than failing.

extract_metadata() is deliberately separate: it reports per-variable fields only, and a dataset-level key is not a variable.

Each key also has a convenience extractor that returns one scalar: extract_survey_name(), extract_data_name(), extract_vendor(), extract_field_dates(), and extract_field_period().

See also

Other metadata: classify_question_type(), extract_data_name(), extract_field_dates(), extract_field_period(), extract_higher_is(), extract_metadata(), extract_missing_codes(), extract_question_preface(), extract_reverse_coded(), extract_sata(), extract_survey_name(), extract_universe(), extract_val_labels(), extract_var_extra(), extract_var_label(), extract_var_note(), extract_vendor(), infer_question_prefaces(), set_data_name(), set_dataset_metadata(), set_field_dates(), set_field_period(), set_higher_is(), set_missing_codes(), set_question_preface(), set_reverse_coded(), set_sata(), set_survey_name(), set_universe(), set_val_labels(), set_var_extra(), set_var_label(), set_var_note(), set_vendor(), survey_metadata(), survey_weighting_history()

Examples

# On a data frame, dataset metadata lives in whole-object attributes.
df <- data.frame(id = 1:5, y = c(2, 4, 3, 5, 1), w = rep(1, 5))
attr(df, "survey_name") <- "Example Attitudes Survey 2026"
attr(df, "vendor") <- "Ipsos KnowledgePanel"
attr(df, "field_start") <- as.Date("2026-02-10")
attr(df, "field_end") <- as.Date("2026-03-04")

extract_dataset_metadata(df)
#> $survey_name
#> [1] "Example Attitudes Survey 2026"
#> 
#> $vendor
#> [1] "Ipsos KnowledgePanel"
#> 
#> $field_start
#> [1] "2026-02-10"
#> 
#> $field_end
#> [1] "2026-03-04"
#> 
extract_dataset_metadata(df, vendor)
#> $vendor
#> [1] "Ipsos KnowledgePanel"
#> 
extract_dataset_metadata(df, key = c("field_start", "field_end"))
#> $field_start
#> [1] "2026-02-10"
#> 
#> $field_end
#> [1] "2026-03-04"
#> 
extract_dataset_metadata(df, format = "data_frame")
#> # A tibble: 4 × 2
#>   key         value                        
#>   <chr>       <chr>                        
#> 1 survey_name Example Attitudes Survey 2026
#> 2 vendor      Ipsos KnowledgePanel         
#> 3 field_start 2026-02-10                   
#> 4 field_end   2026-03-04                   

# An unset key is omitted by default, or filled on request.
extract_dataset_metadata(df, data_name)
#> list()
extract_dataset_metadata(df, data_name, fill = NA)
#> $data_name
#> [1] NA
#> 

# A non-NULL fill plus an empty request gives the whole six-key schema.
extract_dataset_metadata(df, fill = NA, format = "data_frame")
#> # A tibble: 6 × 2
#>   key          value                        
#>   <chr>        <chr>                        
#> 1 survey_name  Example Attitudes Survey 2026
#> 2 data_name    NA                           
#> 3 vendor       Ipsos KnowledgePanel         
#> 4 field_start  2026-02-10                   
#> 5 field_end    2026-03-04                   
#> 6 field_period NA