define_variable: Define a hymetDP variable

In kzollove/hymetDP: Tools to Create, Use, and Convert hymetDP data

Define a hymetDP variable

Description

Define a hymetDP variable

Usage

define_variable(
  L0_flat,
  local_variable_column = "variable_name",
  local_variable = NULL,
  variable_name = local_variable,
  variable_units = NULL,
  sample_medium = "Unknown",
  value_type = "Unknown",
  is_regular = FALSE,
  time_support = 0,
  time_units = "hour",
  data_type = "Unknown",
  general_category = "Unknown",
  no_data = -9999
)

Arguments

L0_flat	(tbl_df, tbl, data.frame) The fully joined source L0 dataset, in "flat" format (see details).
local_variable_column	(character) Column in L0_flat table containing the L0 variable name.
local_variable	(character) Reference to a value in the local_variable_column from the L0_flat table to which the new hymetDP variable refers.
variable_name	(character) The CUAHSI ODM Controlled Vocabulary name for the variable that was measured, observed, modeled, etc. Defaults to the local_variable value.
variable_units	(character) The CUAHSI ODM Controlled Vocabulary name of units of the data values associated with a variable. Defaults to a column unit from the L0_flat table if left unspecified.
sample_medium	(character) The CUAHSI ODM Controlled Vocabulary name of the medium in which the sample or observation was taken or made.
value_type	(character) The CUAHSI ODM Controlled Vocabulary value that indicates how the data value was generated.
is_regular	(boolean) Value indicates whether the data values are from a regularly sampled time series. Choose TRUE or FALSE.
time_support	(numeric) Numerical value that indicates the time support (or temporal footprint) of the data values. 0 is used to indicate data values that are instantaneous. Other values indicate the time over which the data values are implicitly or explicitly averaged or aggregated. Goes along with time_units if is_regular == TRUE.
time_units	(character) The CUAHSI ODM Controlled Vocabulary name of units of the time support. If time_support == 0, indicating an instantaneous observation, a unit needs to still be given for completeness, although it is arbitrary.
data_type	(character) The CUAHSI ODM Controlled Vocabulary value that indicates how the value applies over a time interval.
general_category	(character) The CUAHSI ODM Controlled Vocabulary value for general category of the data (i.e. Hydrology).
no_data	(numeric) Numeric value used to encode when a data value is not available for this variable. DataValues will be reformatted to match this value.

Details

This function appends columns to the L0_flat table and returns the augmented table.

"flat" format refers to the fully joined source L0 dataset in "wide" form with the exception of the core observation variables, which are in "long" form (i.e. using the variable_name, value, unit columns of the observation table). This "flat" format is the "widest" an L1 hymetDP dataset can be consistently spread due to the frequent occurrence of L0 source datasets with > 1 core observation variable.

Value

(tbl_df, tbl, data.frame) An augmented version of the original flat table, with all of the original columns plus one for each of the specified variable values (i.e. variable_name, variable_units, etc.), plus the VariableCode column, with an auto-generated integer value that will become the primary key of the Variables table. Columns are only added the first time the function is run. Subsequent runs append values to the existing columns.

Examples

flat <- hymet_L0_flat[1:8]

flat <- hymetDP::define_variable(
  L0_flat = flat,
  local_variable_column = "variable_name",
  local_variable = "DSCHRGE_RATE",
  variable_name = "Discharge",
  variable_units = "liters per second",
  sample_medium = "Surface water",
  value_type = "Derived Value",
  is_regular = TRUE,
  time_support = 15,
  time_units = "minute",
  data_type = "Continuous",
  general_category = "Hydrology",
  no_data = -9999)

kzollove/hymetDP documentation built on Nov. 22, 2022, 10:41 p.m.