The ipums_extract
class provides a data structure for storing the
extract definition and status of an IPUMS data extract request. Both
submitted and unsubmitted extract requests are stored in ipums_extract
objects.
ipums_extract
objects are further divided into microdata
and aggregate data classes, and will also include
a collection-specific extract subclass to accommodate differences in
extract options and content across collections.
Currently supported collections are:
IPUMS microdata (
"micro_extract"
)IPUMS USA (
"usa_extract"
)IPUMS CPS (
"cps_extract"
)IPUMS International (
"ipumsi_extract"
)
IPUMS aggregate data (
"agg_extract"
)IPUMS NHGIS (
"nhgis_extract"
)
Learn more about the IPUMS API in vignette("ipums-api")
.
Properties
Objects of class ipums_extract
have:
A
class
attribute of the formc("{collection}_extract", "{collection_type}_extract", "ipums_extract")
. For instance,c("cps_extract", "micro_extract", "ipums_extract")
.A base type of
"list"
.A
names
attribute that is a character vector the same length as the underlying list.
All ipums_extract
objects will include several core fields identifying
the extract and its status:
collection
: the collection for the extract request.description
: the description of the extract request.submitted
: logical indicating whether the extract request has been submitted to the IPUMS API for processing.download_links
: links to the downloadable data, if the extract request was completed at the time it was last checked.number
: the number of the extract request. Withcollection
, this uniquely identifies an extract request for a given user.status
: status of the extract request at the time it was last checked. One of"unsubmitted"
,"queued"
,"started"
,"produced"
,"canceled"
,"failed"
, or"completed"
.
Creating an extract
Create an
ipums_extract
object from scratch with the appropriatedefine_extract_*()
function. These functions take the formdefine_extract_{collection}
.Use
get_extract_info()
to get the latest status of a submitted extract request.Use
get_extract_history()
to obtain the extract definitions of previously-submitted extract requests.
Submitting an extract
Use
submit_extract()
to submit an extract request for processing through the IPUMS API.Use
wait_for_extract()
to periodically check the status of a submitted extract request until it is ready to download.Use
is_extract_ready()
to manually check whether a submitted extract request is ready to download.
Downloading an extract
Download the data contained in a completed extract with
download_extract()
.
Saving an extract
Save an extract to a JSON-formatted file with
save_extract_as_json()
.Create an
ipums_extract
object from a saved JSON-formatted definition withdefine_extract_from_json()
.