Get Catchment Characteristics

Downloads (subsets of) catchment characteristics from a cloud data store. See get_characteristics_metadata for available characteristics.

When source = "usgs" (the default), data is retrieved from: Wieczorek, M.E., Jackson, S.E., and Schwarz, G.E., 2018, Select Attributes for NHDPlus Version 2.1 Reach Catchments and Modified Network Routed Upstream Watersheds for the Conterminous United States (ver. 3.0, January 2021): U.S. Geological Survey data release, doi:10.5066/F7765D7V .

When source = "streamcat", data is retrieved from the EPA StreamCat dataset via the StreamCatTools package (must be installed separately). The aoi parameter controls the area of interest for StreamCat queries.

get_catchment_characteristics(
  varname,
  ids,
  reference_fabric = "nhdplusv2",
  source = "usgs",
  aoi = "cat"
)

Arguments

varname

character vector of desired variables. If repeated varnames are provided, they will be downloaded once but duplicated in the output. For source = "streamcat", use StreamCat metric names (see get_characteristics_metadata(source = "streamcat")).

ids

numeric vector of identifiers (comids) from the specified fabric

reference_fabric

(not used) will be used to allow future specification of alternate reference fabrics

source

character "usgs" (default) or "streamcat".

aoi

character area of interest for StreamCat queries. One of "cat" (local catchment, default), "ws" (total upstream watershed), "catrp100" (catchment riparian 100m buffer), "wsrp100" (watershed riparian 100m buffer), or "other" (for metrics like BankfullDepth, IWI, etc.). Ignored when source = "usgs" where the area of interest is encoded in the variable name prefix (e.g. CAT_, TOT_, ACC_).

Examples

# \donttest{
  get_catchment_characteristics("CAT_BFI", c(5329343, 5329427))
#> Warning: Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#> Warning: Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#> Warning: Potentially unsafe or invalid elements have been discarded from R metadata.
#> ℹ Type: "externalptr"
#> → If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.
#>    characteristic_id   comid characteristic_value percent_nodata
#>               <char>   <int>                <num>          <num>
#> 1:           CAT_BFI 5329343                27.76              0
#> 2:           CAT_BFI 5329427                24.49              0
# }