Skip to contents

cronus

Source: vignettes/cronus.Rmd
cronus.Rmd

Overview

This vignette contains general information on the package. It is intended to give the user a general picture of the package features, presenting the database structure and the code architecture in a clear and concise way.

Database structure

The database takes the form of a 5-level structured directory. For a specific region, data can belong to one of three sectors: agricultural, environmental or satellite. Data are made available by a provider, usually an organization or a lab, which organizes the data in one or more products. Each product contains several variables of interest. You can see the materials covered in the package by calling the function print_tree().

  1. Parent Directory
  2. Region, (e.g. nebraska)
  3. Sector, (e.g. agricultural)
  4. Provider, (e.g. nass)
  5. Product, (e.g. cropmaps)
  6. Variable, (e.g. cdl)

For more information on the nature of the available data products, check ?cronus::'Database-class' or read vignette("Data").

Code architecture

The package is built using the S4 class system, offering simplicity to new R users as well as ease of development to the project core team. Functions require a single object that holds all the necessary information concerning the data of interest:

  1. region, an object of class Region indicating the region of interest,
  2. date, an object of class Date indicating the time of interest and
  3. dir, an object of class character indicating the parent directory of the database.

Now, it is straightforward to create any data object:

region <- Region(name = "nebraska", type = "us state", div = c(country = "United States", state = "Nebraska"))
date <- as.Date("2020-07-15")
dir <- getwd()

w <- new("Quickstats", region = region, date = date, dir = dir)
x <- new("Cropmaps", region = region, date = date, dir = dir)
y <- new("Daymet", region = region, date = date, dir = dir)
z <- new("Mod09ga", region = region, date = date, dir = dir)

The package functions, such as download() are generic S4 functions, meaning that depending on the class of the object provided by the user, they can have a different behavior. Therefore, the user only needs to provide the product object along with the variables of interest and the function will do the rest:

?cronus::download
download(w, "progress")
download(x, "cdl")
download(y, c("tmin", "tmax"))
download(z)

Functions that download or process data automatically store them in the database. This means that the user will never have to deal with directories explicitly.

Note: All functions that may require more than a few seconds are equipped with a progress bar indicating the percentage completed, as well as the estimated time remaining.

You are now ready to read vignette("Examples").

Additional Features

Database path

In order to avoid specifying the database directory in every single function call, a variable named path_demeter can be added to the environment variables, stored in the user .Renviron file. This allows the user to specify only once the database directory, which will load in the beginning of every R session. Function set_path_demeter() can be used to specify or change the path.

Safety and Keyrings

Many organizations require credentials in order to allow data download. Currently, the user needs to have an credentials for the following services:

  • USDA: Provides access to NASS Quickstats data.
  • USGS: Provides access to Modis Images. USGS is the sole science agency for the Department of the Interior of United States.
  • EarthData: A repository of NASA’s earth observation data-sets.
  • SciHub: A web service giving access to Copernicus’ scientific data hub.

In order to safely store API keys and passwords, the R package keyring is used. You can always store your credentials in another safe place, just make sure they are not made publicly available by mistake. A keyring is an account that can hold keys (credentials) for various services. Once a keyring is created, the user can start adding keys to it. The following example shows how to create a keyring and store credentials.

 ringname <- "my_ringname"
 password <- "my_password"

 create_keyring(ringname, password)

 log_in(ringname, password)

 add_key(ringname = ringname,
         provider = "usgs",
         username = "usgs_username",
         password = "usgs_password")

 get_username(ringname, "usgs")
 get_password(ringname, "usgs")

 log_out(ringname)

Functions that require credentials can automatically get them if the user is logged in. Users are reminded to log out for safety reasons.