amerifluxr

An R programmatic interface for querying, downloading, and handling AmeriFlux data and metadata.

Installation

Stable release

To install the current stable release use a CRAN repository:

install.packages("amerifluxr")
library("amerifluxr")

Development release

To install the development releases of the package run the following commands:

if(!require(devtools)){install.packages("devtools")}
devtools::install_github("chuhousen/amerifluxr")
library("amerifluxr")

Vignettes are not rendered by default, if you want to include additional documentation please use:

if(!require(devtools)){install.packages("devtools")}
devtools::install_github("chuhousen/amerifluxr", build_vignettes = TRUE)
library("amerifluxr")

Use

Obtain an AmeriFlux site list

This function obtains the latest AmeriFlux site list and sites' general info through the AmeriFlux web service.

site <- amf_site_info()

Download all-site metadata

Access to AmeriFlux data requires creating an AmeriFlux account first. Register an account through the link.

The following downloads a single file containing all AmeriFlux sites' metadata (i.e., BADM data product) for sites under the CC-BY-4.0 data use policy. The downloaded file is a Excel file saved to tempdir() (e.g., AMF_{SITES}_BIF_{POLICY}_{VERSION}.xlsx, SITES = AA-Net (all registered sites) or AA-Flx (all sites with flux/met data available); POLICY = CCBY4 (shared under AmeriFlux CC-BY-4.0 data use policy) or LEGACY (shared under AmeriFlux Legacy data use policy)).

For details about BADM data files, see AmeriFlux web page.

floc1 <- amf_download_bif(user_id = "my_user",
                          user_email = "my_email@mail.com",
                          data_policy = "CCBY4.0",
                          agree_policy = TRUE,
                          intended_use = "synthesis",
                          intended_use_text = "obtain AmeriFlux sites' geolocation, IGBP, and climate classification",
                          out_dir = tempdir(),
                          verbose = TRUE,
                          site_w_data = TRUE)

The amf_download_bif() returns the full file path to the downloaded file, which can be used to read the file into R.

bif <- amf_read_bif(file = floc1)

Download single-site flux/met data

The following downloads AmeriFlux flux/met data (aka BASE data product) from a single site. For details about BASE data files, see AmeriFlux BASE data page.

The downloaded file is a zipped file saved in tempdir() (e.g., AMF_{SITEID}_BASE-BADM_{VERSION}.zip), which contains a BASE data file (e.g., AMF\{SITEID}_BASE_{RESOLUTION}_{VERSION}.csv, RESOLUTION = HH (half-hourly) or HR (hourly)) and a BADM data file (e.g., AMF\{SITEID}_BIF\{VERSION}.xlsx). The BADM data file is a site subset of the all-site BADM downloaded through amf_download_bif().

floc2 <- amf_download_base(user_id = "my_user",
                           user_email = "my_email@mail.com",
                           site_id = "US-CRT",
                           data_product = "BASE-BADM",
                           data_policy = "CCBY4.0",
                           agree_policy = TRUE,
                           intended_use = "remote_sensing",
                           intended_use_text = "validate the model of GPP estimation",
                           verbose = TRUE,
                           out_dir = tempdir())

The amf_download_base() returns the full file path to the downloaded file, which can be used to read the file into R.

base <- amf_read_base(file = floc2,
                      unzip = TRUE,
                      parse_timestamp = TRUE)

Download multiple-site flux/met data

The following downloads AmeriFlux flux/met data from multiple sites. The downloaded files are organized by sites, with one zipped file for each site, similar to single-site download.

amf_download_base(user_id = "my_user",
                  user_email = "my_email@mail.com",
                  site_id = c("US-CRT", "US-WPT", "US-Oho"),
                  data_product = "BASE-BADM",
                  data_policy = "CCBY4.0",
                  agree_policy = TRUE,
                  intended_use = "model",
                  intended_use_text = "Data-driven modeling, for training models and cross-validation",
                  verbose = TRUE,
                  out_dir = tempdir())

Additional functionalities

• Site Selection Vignette demonstrates examples to query a list of target sites based on sites' general information and availability of metadata and data.

• Data Import Vignette demonstrates examples to import data and metadata downloaded from AmeriFlux, and parse and clean data for further use.

Citation

Chu, Housen, and Hufkens, Koen. "amerifluxr v1.0.0." Computer software. May 10, 2021. https://github.com/chuhousen/amerifluxr. https://doi.org/10.11578/dc.20210730.2.

Acknowledgement

We thank the AmeriFlux site teams for sharing their data and metadata with the network. Funding for these flux sites is acknowledged in the site data DOI on AmeriFlux website. This package was supported in part by funding provided to the AmeriFlux Management Project by the U.S. Department of Energy’s Office of Science under Contract No. DE-AC0205CH11231. We also thank Adam Young, Minkyu Moon, Erica Orcutt, Manuel Helbig for testing the package and providing valuable feedback.