R/rescale_catchments.R
rescale_catchment_characteristics.RdGiven 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
)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."
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.
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.
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`.
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.
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.
# \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)
#> # A tibble: 1 × 6
#> id areasqkm_sum lengthkm_sum CAT_IMPV11_area_wtd percent_nodata_CAT_BA…¹
#> <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 10012268 12.9 6.30 0 0
#> # ℹ abbreviated name: ¹percent_nodata_CAT_BASIN_AREA_area_wtd
#> # ℹ 1 more variable: CAT_BASIN_AREA_sum <dbl>
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_MIN_area_wtd,
#> # ²percent_nodata_CAT_ELEV_MAX_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_EWT_area_wtd <dbl>,
#> # percent_nodata_CAT_TWI_area_wtd <dbl>,
#> # percent_nodata_CAT_BASIN_AREA_area_wtd <dbl>, CAT_BASIN_AREA_sum <dbl>
# }