nfd: Natural Flow Data (nfd)

In BoulderCodeHub/CRSSIO: Package to Manage the Input and Output of CRSS Data

Natural Flow Data (nfd)

Description

nfd() creates an object to store natural flow data from the specified data. Conceptually, the nfd object is a 5-dimensional array, where the first three dimensions represent time (months or years), traces, and sites. The next two dimensions are the "flow space" (intervening or total flow), and then the time time step. This allows for the storage of all natural flow data used in CRSS and Colorado River modeling in one object, or to limit it and only store the site or flow space of interest.

crss_nf() is the constructor to create crss_nf obects. This class is an extension of nfd, however it imposes a strict number and naming convention to the sites. Where nfd objects can have an arbitrary number of sites, and they do not have to be named, crss_nf objects must have 29 sites, the names must match the expected site names for CRSS gages nf_gage_abbrv(), and the data must include monthly intervening data. (Annual and/or monthly total can also be included, but they do not have to be.)

Usage

nfd(
  data = NA,
  n_months = NA,
  n_trace = 1,
  n_sites = NA,
  flow_space = c("total", "intervening", "both"),
  time_step = c("annual", "monthly", "both"),
  start_yearmon = NA,
  year = c("cy", "wy"),
  site_names = NA
)

as_nfd(x, ...)

is_nfd(x)

crss_nf(
  data = NA,
  n_months = NA,
  n_trace = 1,
  flow_space = c("intervening", "both"),
  time_step = c("monthly", "both"),
  start_yearmon = NA,
  year = c("cy", "wy")
)

as_crss_nf(x, ...)

is_crss_nf(x)

Arguments

data	If NA or of length 1, creates an object with dimensions based on n_months, n_trace, flow_space, and time_step. Otherwise, creates an object based on the provided data. Data should be a matrix, array, or ⁠[xts]⁠ object.
n_months	The number of months. Scalar numeric.
n_trace	The number of traces. Scalar numeric.
n_sites	The number of sites. Scalar numeric. When NA, the number of sites will be solved for from the data shape.
flow_space	Data are intervening or total flow (or both). If both, then will store/create total and intervening flow data.
time_step	Data are annual or monthly (or both). If both, then will store/create annual and monthly data.
start_yearmon	Start year and month of data. If NA, then assumes the data begins in January of the current year. Should be a zoo::yearmon object or coercable to one. Scalar character.
year	Data are calendar year ("cy") or water year ("wy"). This has implications for the timestep the annual data are stored in (December for cy and September for wy) as well as how summation functions will be applied to monthly data.
site_names	The names of the sites. If specified, must be the same length as the number of sites (n_sites).
x	An R object.
...	Other parameters passed to crss_nf().

Details

If data is a scalar, then n_months and n_trace are used to determine the number of traces and time steps. Otherwise, those values are assumed from the dimensions of the data and the data class. See Data Types section for a description of how different data types are handled.

For initializing blank annual data - the number of years is computed as the number of full years with a minimum of 1 year of data: n_years = max(floor(n_months / 12), 1). The timestep will begin in December of the year as specified in start_yearmon if year is calendar year, or September if the the year is water year.

The data are assumed to always exist for all sites first, and then the number of timesteps or traces are determined after that.

When creating crss_nf objects, arrays, matrices, and xts objects must have the site dimension named and those names must match the expected natural flow site names nf_gage_abbrv().

Value

nfd() and as_nfd() return an object of class nfd.

is_nfd() returns TRUE if class inherits from nfd.

crss_nf() and as_crss_nf() return an object of class crss_nf.

is_crss_nf() returns TRUE if class inherits from crss_nf.

Data Types

This section describes how different data types for the specified data/x are treated when creating an nfd object.

Array: Arrays should be an m x t x s array, where m is the number of months (or years), t is the number of traces, and s is the number of sites. Array can also be an m x t x s x 2 array, where x[,,,1] is total flow and x[,,,2] is intervening flow. If there are rownames, then they must be in "yyyy-mm" format, otherwise an error will post. Rownames are not required, and if they are not provided will be set starting with the specified start_yearmon or assuming a starting date of January of the current year. Colnames are not required or used. The names of the 3rd dimension represent the site names, and will be used if provided, otherwise the site names remain NULL.

Matrix: Matrices are assumed to be structured as m x s, where m is the number of months or years and s is the number of sites for a single trace. The user needs to specify the time_step and flow_space, although they are assumed to be annual total if not specified. If start_yearmon is not specified, it is assumed to be January of the current year. The colnames of the matrix are used for the site names, if provided, otherwise they remain NULL.

xts: xts objects work the same way as matrices, except that start_yearmon is determined form the xts object.

data.frame: data.frames can be converted to nfd objects only if the variables ( i.e., column names) match specific variable names. In a "long" format, the data.frame must have month, year, site, trace, and value variables. In a "wide" format, the data.frame must have month, year, and at least one other column. In the wide format, the other column names are assumed to be site names, and there is assumed to be only 1 trace of data. When using as_nfd() the different components of an nfd object are guessed based on the data format. using nfd() uses the defaults if not specified, but will produce warnings and errors if the data seem to reflect different components. For example if the data are annual and the year argument is specified as "wy", then warnings will post if the month variable contains values that are different than September.

list: lists are treated the same way as data.frames. An error will post if the list cannot first be converted to a data.frame.

All other data types will result in an error.

BoulderCodeHub/CRSSIO documentation built on July 2, 2023, 5:15 p.m.