Survey Metadata Container

Stores variable labels, value labels, question prefaces, notes, and transformation history for variables in a survey design object. Automatically populated from haven-style attributes when as_survey() or related constructors are called.

Usage

survey_metadata(
  variable_labels = list(),
  value_labels = list(),
  question_prefaces = list(),
  notes = list(),
  var_extra = list(),
  universe = list(),
  missing_codes = list(),
  sata = list(),
  higher_is = list(),
  reverse_coded = list(),
  transformations = list(),
  weighting_history = list(),
  dataset_metadata = list()
)

Arguments

variable_labels

A named list mapping variable names to character labels (e.g., list(age = "Age in years")).

value_labels

A named list mapping variable names to named vectors of value labels (e.g., list(sex = c(Male = 1L, Female = 2L))).

question_prefaces

A named list mapping variable names to shared question battery preface text.

notes

A named list mapping variable names to analyst notes.

var_extra

A named list mapping variable names to a pass-through extension payload — itself a named list, or NULL. surveycore never inspects, type-checks, or acts on the payload's values; it stores and returns them as-is. Use set_var_extra() and extract_var_extra() to access this property. Default list().

universe

A named list mapping variable names to universe descriptions (e.g., list(age = "Adults 18+")). Describes the population to which a variable applies.

missing_codes

A named list mapping variable names to atomic vectors of missing-value codes (e.g., list(age = c(Refused = 99L, DK = 98L))).

sata

A named list mapping variable names to TRUE for variables that are select-all-that-apply (SATA). Only variables explicitly marked as SATA appear in this list — absence means the variable is not SATA.

higher_is

A named list mapping variable names to "better" or "worse", indicating the direction of improvement for that variable. Absent keys mean the direction is unset. Use set_higher_is() and extract_higher_is() to access this property.

reverse_coded

A named list mapping variable names to TRUE for variables that are reverse-coded. Absent keys mean the variable is not reverse-coded. Use set_reverse_coded() and extract_reverse_coded() to access this property.

transformations

A named list tracking variable transformation history (populated automatically during operations).

weighting_history

A list recording weighting operations applied to the survey object (e.g., raking, trimming). Each entry is written by a surveywts function and contains the operation name, parameters, effective sample size before/after, and design effect. Always list() until a surveywts weighting function is applied. Reserved for Phase 2.5.

dataset_metadata

A named list of whole-dataset facts. The key vocabulary is closed — exactly six keys are valid, each with a declared type:

• survey_name — character(1), the full formal survey name.

• data_name — character(1), the display label for this dataset.

• vendor — character(1), the fielding vendor.

• field_start — Date of length 1, the first day in the field.

• field_end — Date of length 1, the last day in the field.

• field_period — character(1), the prose field period.

No value may be NA and no element may be NULL. Any other key is rejected. survey_name and data_name are independent: no function derives one from the other. Use set_dataset_metadata() to write keys and extract_dataset_metadata() to read them; the default is list(). Each key also has a convenience pair: set_survey_name(), set_data_name(), set_vendor(), set_field_dates(), set_field_period(), and the matching extract_survey_name(), extract_data_name(), extract_vendor(), extract_field_dates(), extract_field_period().

Value

A survey_metadata object.

See also

Other metadata: classify_question_type(), extract_data_name(), extract_dataset_metadata(), 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_weighting_history()

Examples

# Empty metadata (default)
m <- survey_metadata()
m@variable_labels
#> list()

# Pre-populated metadata
m <- survey_metadata(
  variable_labels = list(age = "Respondent age", income = "Annual income"),
  value_labels = list(sex = c(Male = 1L, Female = 2L))
)
m@variable_labels$age
#> [1] "Respondent age"
m@value_labels$sex
#>   Male Female 
#>      1      2 

# Dataset-level metadata (closed six-key vocabulary)
m <- survey_metadata(dataset_metadata = list(vendor = "Ipsos"))
m@dataset_metadata$vendor
#> [1] "Ipsos"