Rescale Catchment Characteristics

Source: R/rescale_catchments.R

Given catchment characteristics to retrieve or process will aggregate and / or split the characteristics according to a lookup table.

rescale_catchment_characteristics(
  vars,
  lookup_table,
  refactored_areas = NULL,
  catchment_characteristics = NULL,
  catchment_areas = NULL,
  source = "usgs",
  aoi = "cat"
)

Arguments

vars

data.frame containing `characteristic_id` retrieved from get_characteristics_metadata and `summary_statistic` indicating which summary statistic should be applied to rescale each characteristic. Accepted values are "sum," "length_weighted_mean," "area_weighted_mean," "min," and "max."

lookup_table

data.frame containing `id` numeric vector of identifiers at the desired scale; "comid" is a numeric vector of NHDPlusV2 identifiers; "member_comid" contains formatted NHDPlusV2 COMIDs indicating that the catchments in question need to be split. If catchments have not been split, the columns "comid" and "member_comid" should be identical.

refactored_areas

data.frame containing columns "featureid" and "areasqkm." Used to retrieve adjusted catchment areas in the case of split catchments. If not provided, either no split catchments can be considered or the `catchment_areas` parameter is required.

catchment_characteristics

data.frame containing columns "characteristic_id", "comid", "characteristic_value", and "percent_nodata". If not provided, it will be retrieved from get_catchment_characteristics using the characteristic ids from `vars` and the comids from `lookup_table`.

catchment_areas

data.frame containing columns "comid", "areasqkm", "split_catchment_areasqkm", and "split_area_prop". If not provided, it will be retrieved from `refactored_areas` and/or get_vaa.

source

character "usgs" (default) or "streamcat". Passed through to get_catchment_characteristics when catchment_characteristics is not provided.

aoi

character area of interest, passed through to get_catchment_characteristics when catchment_characteristics is not provided. See get_catchment_characteristics for details.

Value

data.frame with one row per unique `id` in `lookup_table`. Always contains `id`, `areasqkm_sum` (total catchment area contributing to that `id`), and `lengthkm_sum` (total flowline length). Each characteristic named in `vars` adds a column called `<characteristic_id>_<statistic>`, where the statistic suffix is one of "area_wtd", "length_wtd", "sum", "min", or "max" following the `summary_statistic` requested for it – for example `CAT_IMPV11_area_wtd` or `CAT_BASIN_AREA_sum`. Where the source reports a no-data fraction, a matching `percent_nodata_<characteristic_id>_area_wtd` column is included. Returns `NULL` if `catchment_characteristics` was not supplied and could not be retrieved from the web service.

Details

NOTE: Since this algorithm works on catchment characteristics that are spatial averages, when splitting, the average condition is apportioned evenly to each split. In some cases, such as with land cover or elevation, this may not be appropriate and source data should be used to derive new characteristics. In addition, this function handles catchment areas for split catchments but makes no adjustments for the length of flowlines in those catchments. Therefore, requests for length-weighted mean values may not be appropriate when working with split catchments.

Examples

# \donttest{
vars <- data.frame(characteristic_id = c("CAT_IMPV11","CAT_BASIN_AREA"),
                   summary_statistic = c("area_weighted_mean","sum"))
lookup_table <- data.frame(id = rep(10012268, 2),
                           comid = c(4146596, 4147382),
                           member_comid = c(4146596, 4147382))
rescale_catchment_characteristics(vars, lookup_table)
#> Warning: Variable(s) CAT_IMPV11 not found in metadata.
#> NULL

vars <- data.frame(characteristic_id = c("CAT_ELEV_MIN","CAT_ELEV_MAX"),
                   summary_statistic = c("min","max"))
lookup_table <- data.frame(id = rep(10012268, 2),
                           comid = c(4146596, 4147382),
                           member_comid = c(4146596, 4147382))
rescale_catchment_characteristics(vars, lookup_table)
#> # A tibble: 1 × 7
#>       id areasqkm_sum lengthkm_sum percent_nodata_CAT_E…¹ percent_nodata_CAT_E…²
#>    <dbl>        <dbl>        <dbl>                  <dbl>                  <dbl>
#> 1 1.00e7         12.9         6.30                      0                      0
#> # ℹ abbreviated names: ¹​percent_nodata_CAT_ELEV_MAX_area_wtd,
#> #   ²​percent_nodata_CAT_ELEV_MIN_area_wtd
#> # ℹ 2 more variables: CAT_ELEV_MIN_min <dbl>, CAT_ELEV_MAX_max <dbl>

vars <- data.frame(characteristic_id = c("CAT_EWT","CAT_TWI", "CAT_BASIN_AREA"),
                   summary_statistic = c("area_weighted_mean", "area_weighted_mean","sum"))
lookup_table <- data.frame(id = c(10012268, 10012268, 10024047, 10024048),
                           comid = c(4146596, 4147382, 4147396, 4147396),
                           member_comid = c("4146596", "4147382", "4147396.1", "4147396.2"))
comid_areas <- data.frame(featureid = c("4146596", "4147382", "4147396.1", "4147396.2"),
                               areasqkm = c(0.9558, 11.9790, 6.513294, 1.439999))
rescale_catchment_characteristics(vars, lookup_table, refactored_areas = comid_areas)
#> # A tibble: 3 × 9
#>         id areasqkm_sum lengthkm_sum CAT_EWT_area_wtd CAT_TWI_area_wtd
#>      <dbl>        <dbl>        <dbl>            <dbl>            <dbl>
#> 1 10012268        12.9          6.30           -25.5              9.59
#> 2 10024047         6.51         4.31           -24.6              9.07
#> 3 10024048         1.44         4.31            -5.44             2.00
#> # ℹ 4 more variables: percent_nodata_CAT_BASIN_AREA_area_wtd <dbl>,
#> #   percent_nodata_CAT_EWT_area_wtd <dbl>,
#> #   percent_nodata_CAT_TWI_area_wtd <dbl>, CAT_BASIN_AREA_sum <dbl>

 # }