Create variable and sample specifications for IPUMS microdata extract requests
Source:R/api_define_extract.R
var_spec.Rd
Provide specifications for individual variables when defining an IPUMS microdata extract request.
Currently, no additional specifications are available for IPUMS samples.
Learn more about microdata extract definitions in
vignette("ipums-api-micro")
.
Usage
var_spec(
name,
case_selections = NULL,
case_selection_type = NULL,
attached_characteristics = NULL,
data_quality_flags = NULL,
preselected = NULL
)
samp_spec(name)
Arguments
- name
Name of the sample or variable.
- case_selections
A character vector of values of the given variable that should be used to select cases. Values should be specified exactly as they appear in the "CODES" tab for the given variable in the web-based extract builder, including zero-padding (e.g. see the "CODES" tab for IPUMS CPS variable EDUC).
- case_selection_type
One of
"general"
or"detailed"
indicating whether the values incase_selections
should be matched against the general or detailed codes for the given variable. Only some variables have detailed codes. See IPUMS USA variable RACE for an example of a variable with general and detailed codes.Defaults to
"general"
if anycase_selections
are specified.- attached_characteristics
Whose characteristics should be attached, if any? Accepted values are
"mother"
,"father"
,"spouse"
,"head"
, or a combination. Specifying attached characteristics will add variables to your extract that contain the values for the given variable for the specified household members (e.g. variable "AGE_MOM" will be added if"mother"
is specified for the variable"AGE"
).- data_quality_flags
Logical indicating whether to include data quality flags for the given variable. By default, data quality flags are not included.
- preselected
Logical indicating whether the variable is preselected. This is not needed for external use.
Examples
var1 <- var_spec(
"SCHOOL",
case_selections = c("1", "2"),
data_quality_flags = TRUE
)
var2 <- var_spec(
"RACE",
case_selections = c("140", "150"),
case_selection_type = "detailed",
attached_characteristics = c("mother", "spouse")
)
# Use variable specifications in a microdata extract definition:
extract <- define_extract_usa(
description = "Example extract",
samples = "us2017b",
variables = list(var1, var2)
)
extract$variables$SCHOOL
#> $name
#> [1] "SCHOOL"
#>
#> $case_selections
#> [1] "1" "2"
#>
#> $data_quality_flags
#> [1] TRUE
#>
#> $case_selection_type
#> [1] "general"
#>
#> attr(,"class")
#> [1] "var_spec" "ipums_spec" "list"
extract$variables$RACE
#> $name
#> [1] "RACE"
#>
#> $case_selections
#> [1] "140" "150"
#>
#> $attached_characteristics
#> [1] "mother" "spouse"
#>
#> $case_selection_type
#> [1] "detailed"
#>
#> attr(,"class")
#> [1] "var_spec" "ipums_spec" "list"