R/ms_undo_scale_flux_by_area.R

In MacroSHEDS/macrosheds: Tools for interfacing with the MacroSheds dataset

#' Un-scale stream or precipitation chemical flux by watershed area
#'
#' MacroSheds chemical flux is scaled to watershed area by default (kg/ha/d).
#' This function converts chemical flux to kg/d. If You generated precipitation chemical
#' flux yourself with [ms_calc_watershed_precip()], it is in kd/d and this function is not needed.
#'
#' @author Spencer Rhea
#' @author Mike Vlah, \email{vlahm13@@gmail.com}
#' @author Wes Slaughter
#' @param d \code{data.frame}. A \code{data.frame} in MacroSheds format (see details),
#'    containing stream_flux_inst_scaled or precip_flux_inst_scaled data. A \code{data.frame} in
#'    MacroSheds format is generated by [ms_load_product()].
#' @return returns a \code{data.frame} in MacroSheds format with stream or precipitation chemical flux in kg/d.
#' @details MacroSheds reports all chemical flux on a per area basis (kg/ha/d) to
#'    facilitate comparison of watersheds of different sizes. Sometimes un-scaled
#'    fluxes are of interest. This function will convert the units of a native
#'    MacroSheds chemical flux dataset from kg/ha/d to kg/d. To download
#'    MacroSheds data, see [ms_download_core_data()].
#'
#'    MacroSheds format (only site_code and val columns required as inputs to this function):
#' | header value  | column_definition |
#' | ------------- | ----------------- |
#' | date          | Date in YYYY-mm-dd |
#' | site_code     | A unique identifier for each MacroSheds site, identical to primary source site code where possible. See [ms_load_sites()]. |
#' | grab_sample   | Boolean integer indicating whether the observation was obtained via grab sample or installed sensor. 1 = TRUE (grab sample), 0 = FALSE (installed sensor). |
#' | var           | Variable code. See [ms_load_variables()]. |
#' | val           | Data value. See [ms_load_variables()] for units. |
#' | ms_status     | Boolean integer. 0 = clean value. 1 = questionable value. See "Technical Validation" section of [the MacroSheds data paper](https://aslopubs.onlinelibrary.wiley.com/doi/full/10.1002/lol2.10325) for details. |
#' | ms_interp     | Boolean integer. 0 = measured or imputed by primary source. 1 = interpolated by MacroSheds. See "Temporal Imputation and Aggregation" section of [the MacroSheds data paper](https://aslopubs.onlinelibrary.wiley.com/doi/full/10.1002/lol2.10325) for details. |
#' | val_err       | The combined standard uncertainty associated with the corresponding data point, if estimable. See "Detection Limits and Propagation of Uncertainty" section of [the MacroSheds data paper](https://aslopubs.onlinelibrary.wiley.com/doi/full/10.1002/lol2.10325) for details. |
#' @export
#' @seealso [ms_scale_flux_by_area()]
#' @examples
#' ms_root <- 'data/macrosheds'
#' ms_download_core_data(macrosheds_root = ms_root,
#'                       domains = 'hbef')
#' d <- ms_load_product(macrosheds_root = ms_root,
#'                      prodname = 'stream_flux_inst_scaled',
#'                      domains = 'hbef',
#'                      filter_vars = 'NO3_N')
#'
#' d <- ms_undo_scale_flux_by_area(d)

ms_undo_scale_flux_by_area <- function(d){

    library("dplyr", quietly = TRUE)

    requireNamespace('macrosheds', quietly = TRUE)

    site_data <- macrosheds::ms_site_data

    sites <- unique(d$site_code)

    ws_areas <- site_data %>%
        dplyr::select(site_code, ws_area_ha) %>%
        filter(site_code %in% !!sites)

    d <- d %>%
        left_join(ws_areas,
                  by = 'site_code') %>%
        mutate(val = val * ws_area_ha) %>%
        dplyr::select(-any_of(c('ws_area_ha', 'val_err')))

    return(d)
}