wait_for_extract: Wait for extract to finish

In mnpopcenter/ipumsr: Read 'IPUMS' Extract Files

Wait for extract to finish

Description

Wait for an extract to finish by periodically checking its status via the IPUMS API and returning when the extract is ready to download. For an overview of ipumsr API functionality, see vignette("ipums-api", package = "ipumsr").

Usage

wait_for_extract(
  extract,
  initial_delay_seconds = 0,
  max_delay_seconds = 300,
  timeout_seconds = 10800,
  verbose = TRUE,
  api_key = Sys.getenv("IPUMS_API_KEY")
)

Arguments

extract	One of: An object of class ipums_extract The data collection and extract number formatted as a single string of the form "collection:number" The data collection and extract number formatted as a vector of the form c("collection", "number") The extract number does not need to be zero-padded (e.g., use "usa:1" or c("usa", "1"), not "usa:00001" or c("usa", "00001")). See Examples section below for examples of each form.
initial_delay_seconds	How many seconds to wait before first status check.
max_delay_seconds	Maximum seconds to wait between status checks. The function doubles the wait time after each check, but will cap the wait wait time at this maximum value (300 seconds, or 5 minutes, by default).
timeout_seconds	Maximum total number of seconds to continue waiting for the extract before throwing an error. Defaults to 10,800 seconds (three hours).
verbose	If TRUE, the default, messages will be printed at the beginning of each wait interval with the current wait time, each time the status of the extract is checked, and when the extract is ready to download. Setting this argument to FALSE will silence these messages.
api_key	API key associated with your user account. Defaults to the value of environment variable "IPUMS_API_KEY".

Value

An object of class ipums_extract containing the extract definition and the URLs from which to download extract files.

See Also

Other ipums_api: define_extract_from_json(), define_extract_micro(), download_extract(), extract_list_to_tbl(), extract_tbl_to_list(), get_extract_info(), get_last_extract_info(), get_recent_extracts_info, ipums_data_collections(), is_extract_ready(), revise_extract_micro(), save_extract_as_json(), submit_extract()

Examples

my_extract <- define_extract_micro("usa", "Example", "us2013a", "YEAR")

## Not run: 
submitted_extract <- submit_extract(my_extract)

# Wait for extract by supplying extract object:
downloadable_extract <- wait_for_extract(submitted_extract)

# By supplying the data collection and extract number, as a string:
downloadable_extract <- wait_for_extract("usa:1")
# Note that there is no space before or after the colon, and no zero-padding
# of the extract number.

# By supplying the data collection and extract number, as a vector:
downloadable_extract <- wait_for_extract(c("usa", "1"))

## End(Not run)

mnpopcenter/ipumsr documentation built on Sept. 30, 2022, 6:56 a.m.