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_{SITE_ID}_BASE-BADM_{VERSION}.zip), which contains a BASE data
file (e.g., AMF_{SITE_ID}_BASE_{RESOLUTION}_{VERSION}.csv,
RESOLUTION = HH (half-hourly) or HR (hourly)) and a BADM data file (e.g.,
AMF_{SITE_ID}_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.