Add new values to any fields of an IPUMS USA or CPS extract object. All fields are optional, and if omitted, will be unchanged. Supplying a value for fields that take a single value, such as description and data_format, will replace the existing value with the supplied value.

To remove existing values from an extract, see remove_from_extract().

For an overview of ipumsr microdata API functionality, see vignette("ipums-api", package = "ipumsr").

add_to_extract(extract, ...)

# S3 method for usa_extract
add_to_extract(
  extract,
  description = NULL,
  samples = NULL,
  variables = NULL,
  data_format = NULL,
  validate = TRUE,
  ...
)

# S3 method for cps_extract
add_to_extract(
  extract,
  description = NULL,
  samples = NULL,
  variables = NULL,
  data_format = NULL,
  validate = TRUE,
  ...
)

Arguments

extract

An ipums_extract object.

...

Further arguments passed to methods.

description

Description of the extract.

samples

Character vector of samples to add to the extract, if any. Use the USA sample ID values or the CPS sample ID values.

variables

Character vector of variables to add to the extract, if any.

data_format

The desired format of the extract data file (one of "fixed_width", "csv", "stata", "spss", or "sas9").

validate

Logical value indicating whether to check the modified extract structure for validity. Defaults to TRUE.

Value

A modified IPUMS USA or CPS extract object

Note

If the supplied extract definition comes from a previously submitted extract, this function will reset the definition to an unsubmitted state.

Examples

usa_extract <- define_extract_usa(
  description = "USA example",
  samples = "us2013a",
  variables = "YEAR"
)

revised_usa_extract <- add_to_extract(
  usa_extract,
  description = "Revised USA extract",
  samples = "us2014a"
)

revised_usa_extract
#> Unsubmitted IPUMS USA extract 
#> Description: Revised USA extract
#> Samples: (2 total) us2013a, us2014a
#> Variables: (1 total) YEAR


cps_extract <- define_extract_cps(
  description = "CPS example",
  samples = "cps2019_03s",
  variables = "YEAR"
)

revised_cps_extract <- add_to_extract(
  cps_extract,
  description = "Revised CPS extract",
  samples = "cps2020_03s"
)

revised_cps_extract
#> Unsubmitted IPUMS CPS extract 
#> Description: Revised CPS extract
#> Samples: (2 total) cps2019_03s, cps2020_03s
#> Variables: (1 total) YEAR