Learn R Programming
ipumsr (version 0.6.3)

ipums_extract-class: 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").

Arguments

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().