ipums_extract-class: 'ipums_extract' class

ipums_extract-classR Documentation

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

    • IPUMS USA

    • IPUMS CPS

    • IPUMS International

    • IPUMS Time Use (ATUS, AHTUS, MTUS)

    • IPUMS Health Surveys (NHIS, MEPS)

  • IPUMS aggregate data

    • IPUMS NHGIS

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 or obtaining an extract

  • Create an ipums_extract object from scratch with the appropriate ⁠define_extract_*()⁠ function.

    • For microdata extracts, use define_extract_micro()

    • For NHGIS extracts, use define_extract_nhgis()

  • Use get_extract_info() to get the definition and latest status of a previously-submitted extract request.

  • Use get_extract_history() to get the definitions and latest status of multiple 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().


ipumsr documentation built on Sept. 12, 2024, 7:38 a.m.