Set the Field Dates

Sets the field_start and field_end dataset-level metadata keys — the first and last day in the field — on a survey design object or a data frame.

Usage

set_field_dates(x, field_start, field_end)

Arguments

x

A survey design object or data.frame.

field_start

Date(1), an ISO 8601 character(1), or NULL to delete the key. Omit the argument to leave the stored value unchanged.

field_end

Date(1), an ISO 8601 character(1), or NULL to delete the key. Omit the argument to leave the stored value unchanged.

Value

The modified object, invisibly.

Details

A convenience wrapper for set_dataset_metadata() that forwards only the arguments the call supplies. The three states of each argument are distinct:

not supplied

The stored key is left unchanged.

NULL

The stored key is deleted.

a value

The key is set, after validation and coercion.

A value is either a Date scalar or an ISO 8601 string ("YYYY-MM-DD"), which is stored as a Date. A looser string such as "2026/02/10" or "2026-2-1" is rejected, and the error names this function's own argument.

field_start must not be after field_end. The comparison uses the effective value of each key: the new value when the call supplies one, no value when the call supplies NULL, and the stored value when the call does not mention the key. So one call can repair a reversed stored pair by deleting one date and setting the other, and deleting both always succeeds.

This function never touches field_period — the prose period has its own setter, set_field_period().

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_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

df <- data.frame(id = 1:5, y = c(2, 4, 3, 5, 1), w = rep(1, 5))
df <- set_field_dates(df, "2026-02-10", "2026-03-04")
extract_field_dates(df)
#> $field_start
#> [1] "2026-02-10"
#> 
#> $field_end
#> [1] "2026-03-04"
#> 

# Supplying one argument leaves the other key unchanged.
df <- set_field_dates(df, field_end = "2026-03-10")
extract_field_dates(df)
#> $field_start
#> [1] "2026-02-10"
#> 
#> $field_end
#> [1] "2026-03-10"
#> 

# NULL deletes a key.
df <- set_field_dates(df, field_start = NULL)
extract_field_dates(df)
#> $field_start
#> [1] NA
#> 
#> $field_end
#> [1] "2026-03-10"
#> 

d <- as_survey(df, weights = w)
d <- set_field_dates(d, field_start = as.Date("2026-02-11"))
extract_field_dates(d)
#> $field_start
#> [1] "2026-02-11"
#> 
#> $field_end
#> [1] "2026-03-10"
#>