Construct EDGAR v8.1 air-pollutant or VOC-speciation archive URLs and download them using the shared validation, preview, and download helpers.
Usage
download_edgar(
species = c("BC", "CO", "NH3", "NMVOC", "NOx", "OC", "PM10", "PM2.5", "SO2"),
version = "8.1",
temp_res = NULL,
sector_yearly = NULL,
sector_monthly = NULL,
sector_voc = NULL,
format = "nc",
output = "emi",
year_range = NULL,
voc = NULL,
directory_to_save = NULL,
acknowledgement = FALSE,
download = TRUE,
remove_command = FALSE,
unzip = TRUE,
remove_zip = FALSE,
hash = FALSE,
show_progress = TRUE,
max_tries = 20,
rate_limit = 2
)Arguments
- species
character vector. Air pollutants to download for version
"8.1":"BC","CO","NH3","NMVOC","NOx","OC","PM10","PM2.5", or"SO2". Defaults to all listed species. Input is case-insensitive;"PM25"is also accepted. Ignored for VOC speciation, which usesvocinstead.- version
character(1).
"8.1"(default) for air pollutants or"8.1_voc"for VOC speciation.- temp_res
character(1) or NULL. Required for version
"8.1":"yearly","monthly", or"timeseries". Timeseries archives can contain tabular data; see Details for processing limitations. For version"8.1_voc", this does not affect URL selection; if supplied, it is retained in the local archive-name prefix instead of"voc".- sector_yearly
character vector or NULL. Yearly sectors:
"AGS","AWB","CHE","ENE","IND","MNM","NMM","PRU_SOL","RCO","REF_TRF","SWD_INC","SWD_LDF","TNR_Aviation_CDS","TNR_Aviation_CRS","TNR_Aviation_LTO","TNR_Aviation_SPS","TNR_Other","TNR_Ship","TRO","WWT", or"TOTALS".NULLselects totals. Used only for yearly version"8.1"data.- sector_monthly
character vector or NULL. Monthly sectors:
"AGRICULTURE","BUILDINGS","FUEL_EXPLOITATION","IND_COMBUSTION","IND_PROCESSES","POWER_INDUSTRY","TRANSPORT", or"WASTE".NULLselects full-species archives. Used only for monthly version"8.1"data.- sector_voc
character vector or NULL. VOC sectors, using the same choices as
sector_monthly.NULLselects full VOC-group archives. Used only for version"8.1_voc".- format
character(1).
"nc"(default) or"txt". Flux output and monthly version"8.1"data require"nc". Selects an archive template where supported; it does not convert the downloaded files.- output
character(1).
"emi"(default) for emissions or"flx"for fluxes. Full-species monthly, timeseries, and full VOC-group archives use fixed provider filenames that do not vary withoutputorformat.- year_range
integer(1 or more) or NULL. One year, two endpoints, or a non-empty vector of years. Every year from the minimum through the maximum is selected, including gaps:
c(2018, 2023)andc(2018, 2020, 2023)both select2018:2023. Years must be non-missing integer values. For yearly version"8.1"data or sector-specific VOC data,NULL(default) selects bundled archives instead of individual yearly archives. Monthly, timeseries, and full VOC-group archives always contain the provider's bundled years;year_rangeis validated when supplied but does not change their URLs or subset their contents.- voc
integer vector, character vector, or NULL. VOC group numbers from 1 to 25, required for version
"8.1_voc". Numeric strings such as"1"are accepted. Ignored for version"8.1".- directory_to_save
character(1). Non-empty parent directory. Archives are saved in
zip_files/and extracted intodata_files/.- acknowledgement
logical(1). Must be
TRUEto proceed. Archives and extracted data can require substantial storage.- download
logical(1). Deprecated.
FALSEwarns and returns a preview after directory creation, without making network requests. Default isTRUE.- remove_command
logical(1). Deprecated and ignored;
TRUEwarns. Default isFALSE.- unzip
logical(1). Extract downloaded or existing archives into
data_files/. Default isTRUE. WhenFALSE, archives remain inzip_files/without extraction.- remove_zip
logical(1). Remove archives and their parent
zip_files/directory recursively after the extraction loop finishes, including any other files in that directory. Requiresunzip = TRUE. Default isFALSE.- hash
logical(1). Return the combined MD5 hash of all files recursively under
data_files/, including previously extracted files. Withunzip = FALSE, this still hashesdata_files/, not the archives. Default isFALSE; ignored whendownload = FALSE.- show_progress
logical(1). Show per-file download progress. Default is
TRUE; summary messages may still be printed whenFALSE.- max_tries
integer(1). Maximum attempts per file request, including the initial attempt. Must be at least 1. Default is 20.
- rate_limit
numeric(1). Non-negative request-throttling interval in seconds, passed to
download_run_method(). Default is 2.
Value
With
download = FALSE, an invisible list containingurls,destfiles, andn_files, the number of planned archive downloads.With
download = TRUEandhash = FALSE, the invisible summary fromdownload_run_method()withsuccess,failed, andskippedcounts. It always containsfailed_urlsandfailed_filescharacter vectors, bothcharacter(0)when no downloads failed, including when every file was skipped. These counts describe archives, not extracted files.With
download = TRUEandhash = TRUE, a visible character(1) combined MD5 hash of all files underdata_files/, including existing files.
Details
Scalar selectors version, format, and output use base::match.arg(),
allowing unambiguous partial matches. This also applies to temp_res for
version "8.1"; for VOC speciation, a supplied temp_res is used as-is
in the local archive-name prefix. Sector names require exact,
case-sensitive matches. Only the sector argument for the selected version
and temporal resolution is used; timeseries downloads use no sector argument.
URL construction retains the v8.1 FT2022 archive templates, including
the PM2.5 folder/filename conventions and the SO2 _v2 suffix on full
monthly and timeseries archives. Monthly full-species filenames cover
2000–2022; timeseries and full VOC-group filenames cover 1970–2022.
Available remote files are not discovered by querying directory listings.
Year validation checks the input range, not whether EDGAR provides an
archive for each requested year or combination of arguments.
Timeseries archives are not necessarily raster products. For example,
the NOx timeseries archive contains an Excel workbook (.xlsx) and a
readme, even when format = "nc". process_edgar() currently accepts
raster files only, so this workbook cannot be passed through the
process_edgar() and calculate_edgar() workflow.
Local archive names retain the edgar_<temp_res>_ prefix, or edgar_voc_
when VOC speciation is requested with temp_res = NULL. Preview results
include all constructed URLs and destination paths, including existing
files. A preview creates the output directories but makes no network
requests and does not verify remote availability. No shell-command file
is created.
download_run_method() skips existing non-empty destination files and
records individual download failures in its summary. File downloads use
the shared default timeout.
Extraction and cleanup occur before returning, and extraction errors can
prevent a normal return. Summary counts describe downloads, not extraction.
Examples
if (FALSE) { # \dontrun{
download_edgar(
species = "CO",
temp_res = "yearly",
sector_yearly = "ENE",
year_range = c(2021, 2022),
directory_to_save = file.path(tempdir(), "edgar"),
acknowledgement = TRUE,
download = FALSE
)
download_edgar(
version = "8.1_voc",
voc = 1:3,
sector_voc = "AGRICULTURE",
year_range = 2021,
directory_to_save = file.path(tempdir(), "edgar_voc"),
acknowledgement = TRUE,
download = FALSE
)
} # }