ipums_extract-class {ipumsr}

ipums_extract class

Description

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 form c("{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. With collection, 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 appropriate define_extract_*() function. These functions take the form ⁠define_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 with define_extract_from_json().