ms_delineate_watershed: Delineate a watershed from a stream location.

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

Delineate a watershed from a stream location.

Description

From any geographic location, this function (iteratively) attempts to delineate a watershed, i.e. the land area that contributes overland flow to that location. You will need to install whitebox binaries via whitebox::install_whitebox() before it will work. Delineation can be guided by user knowledge of local geography, or it can be fully agnostic. Any specifications not explicitly passed are given reasonable defaults. Candidate delineations are made available for viewing and the user is asked to pick one, or try again by interactively providing different specifications. This function is intended to be used interactively in Rstudio. If you'd like to use it in some other fashion, let us know. See details.

Usage

ms_delineate_watershed(
  lat,
  long,
  crs = 4326,
  write_dir,
  write_name,
  spec_buffer_radius_m = NULL,
  spec_snap_distance_m = NULL,
  spec_snap_method = NULL,
  spec_dem_resolution = NULL,
  spec_flat_increment = NULL,
  spec_breach_method = "basic",
  spec_burn_streams = FALSE,
  verbose = TRUE,
  confirm = TRUE,
  responses_from_file = NULL
)

Arguments

lat	numeric. Represents the latitude of the pour point in decimal degrees (negative indicates southern hemisphere).
long	numeric. Represents the longitude of the pour point in decimal degrees (negative indicates west of prime meridian).
crs	numeric. Represents the coordinate reference system of your starting coordinates. EPSG codes work here (e.g. the default is 4326 for WGS 84).
write_dir	character string. The directory in which to write output shapefile.
write_name	character string. the basename of the shapefile components to be written. e.g. write_name = 'foo' would produce foo.shp, foo.shx, foo.prj, foo.dbf.
verbose	logical. Determines the amount of informative messaging during run.
confirm	logical. Ignored unless all delineation parameters (the ones that start with "spec_") are supplied. If TRUE, you will be asked to visually confirm the delineation before it is written to write_dir.
responses_from_file	character. Path to a file containing responses to ms_delineate_watershed internal prompts–one per line. The file must end with a newline, and it will be emptied, line-by-line from the top, during operation. This is used for testing and is unlikely to be useful to end-users, but who knows?
spec_buffer_radius_m:	optional integer. the radius, in meters, of the buffer circle around the site location. A DEM will be acquired that covers at least the full area of the buffer, so basically a square of DEM in which that circle is inscribed. Must be between 1000 and 100,000 meters, though your watershed may be larger (in which case the buffer will be incremented automatically. This is set initially to 1000 meters if NULL.
spec_snap_distance_m:	optional integer [0,200]. the radius, in meters, of a circle around the recorded site location. A pour point will be identified within this circle. method depends on snap_method. Several reasonable values chosen if NULL.
spec_snap_method:	optional character. either "standard", which snaps the site location to the cell within snap_dist that has the highest flow value, or "jenson", which snaps to the nearest cell identified as part of a flow path. Because we use a flow accumulation raster in place of a streams raster, this isn't all that different from "standard," but it can be a helpful way to "jiggle" the snapping algorithm if it's struggling to find your stream. Both methods will be attempted if NULL. Note that neither snap method will work as desired if your pour point is in an estuary (delineation will proceed into the ocean).
spec_dem_resolution:	optional integer [1,14]. the granularity of the DEM that is used for delineation. this argument is passed directly to the z parameter of elevatr::get_elev_raster(). 1 is low resolution; 14 is high. 8-9 is generally good for large watersheds and 12-13 for small ones. If NULL, initial dem_resolution will be set to 9.
spec_flat_increment:	optional float. Passed to whitebox::wbt_breach_depressions_least_cost() or whitebox::wbt_breach_depressions(), depending on the value of breach_method (see next). Think of this as an arbitrary tuning parameter, to be adjusted only if your watershed won't delineate and you've tried everything else.
spec_breach_method:	optional string. Either 'basic', which invokes whitebox::wbt_breach_depressions(), or 'lc', which invokes whitebox::wbt_breach_depressions_least_cost(). NOTE: at present, wbt_breach_depressions is used regardless of the argument to this parameter, as the least cost algorithm in whitebox is non-deterministic.
spec_burn_streams:	logical. if TRUE, both whitebox::wbt_burn_streams_at_roads() and whitebox::wbt_fill_burn() are called on the DEM, using road and stream layers from OpenStreetMap. This allows delineation to proceed through bridges, dams, and other would-be obstacles.

Details

Output files are unprojected (WGS 84), though processing is done on projected data. A projection is chosen automatically by choose_projection(), based on pour point location. Note that this has nothing to do with the crs parameter, which only allows you to specify the coordinate reference system of your input coordinates. Also note that for watersheds that span several latitudes or longitudes, calculated watershed areas might be inaccurate.

For the fully agnostic delineation procedure, here are the steps:

1. A reasonable projection is chosen via choose_projection().

2. A digital elevation model is retrieved via elevatr::get_elev_raster(). This initial DEM is 4 km^2 and is centered on the given location.

3. Single-cell pits in the DEM are filled using whitebox::wbt_fill_single_cell_pits(). and larger depressions are breached using whitebox::wbt_breach_depressions(). These preprocessing steps ensure that the DEM is traversable by the delineator. If you'd like to see a "fill depressions" option, please open a GitHub issue.

4. If specified, streamline and roadway files are retrieved via osmdata, and streamlines are burned into the DEM at stream-road intersections. In most cases, this allows delineation to proceed through bridges and culverts where it would otherwise stop.

5. Flow direction and accumulation are computed via whitebox::wbt_d8_pointer() and whitebox::wbt_d8_flow_accumulation().

6. The specified site location is snapped to a nearby stream line in multiple ways, in the hopes that at least one snap will land on the intended stream. This matters when e.g. a tributary is being delineated near its confluence with a mainstem. Snapping methods include whitebox::wbt_snap_pour_points() and whitebox::wbt_jenson_snap_pour_points().

7. All unique snap locations are delineated via whitebox::wbt_watershed(). If at any point the computed watershed meets the edge of the DEM, a larger DEM is retrieved, and the delineator tries again.

8. All candidate watersheds are presented for inspection. Either one is selected, or the procedure starts over with a new set of user-given and/or default specifications.

9. The delineated watershed is saved as a shapefile. Watershed area and the successful set of specifications are returned.

Value

Writes a shapefile to write_dir. Also returns a list containing the following components:

• watershed_area_ha: the area of the delineated watershed in hectares

• specs: a list of specifications of the successful delineation

  • buffer_radius_m: the width (meters) around the site location that was used when requesting a DEM (digital elevation model).

  • snap_distance_m: the search radius (meters) around the supplied lat/long that was used to snap a pour point.

  • snap_method: either "standard", which snaps the pour point to the cell within snap_distance_m with highest flow accumulation, or "jenson", which snaps to the nearest flow line.

  • dem_resolution: passed to elevatr::get_elev_raster() (z parameter).

  • flat_increment: see whitebox::wbt_breach_depressions() or whitebox::wbt_breach_depressions_least_cost().

  • breach_method: Either 'basic', indicating that whitebox::wbt_breach_depressions() was used to condition the DEM, or 'lc', indicating that whitebox::wbt_breach_depressions_least_cost() was used (which less readily alters the DEM).

  • burn_streams: TRUE or FALSE, indicating whether whitebox::wbt_burn_streams_at_roads() and whitebox::wbt_fill_burn() were used to condition the DEM.

Author(s)

Mike Vlah, [e-mail]

Spencer Rhea

Wes Slaughter

See Also

ms_scale_flux_by_area(), ms_undo_scale_flux_by_area()

Examples

#here's the agnostic approach, if you're delineating this site for the first time.
out <- ms_delineate_watershed(
    lat = 44.21013,
    long = -122.2571,
    crs = 4326,
    write_dir = '/your/path',
    write_name = 'example_site'
)

#or maybe you know the watershed is on the order of 10,000 km^2 and that.
#there are large highway bridges over some reaches.
out <- ms_delineate_watershed(
    lat = 44.21013,
    long = -122.2571,
    crs = 4326,
    write_dir = '/your/path',
    write_name = 'example_site',
    spec_buffer_radius_m = 10000,
    spec_burn_streams = TRUE,
)

#or maybe you've delineated this site before and you know which specs were successful.
out <- ms_delineate_watershed(
    lat = 44.21013,
    long = -122.2571,
    crs = 4326,
    write_dir = '/your/path',
    write_name = 'example_site',
    spec_buffer_radius_m = 1000,
    spec_snap_distance_m = 150,
    spec_snap_method = 'standard',
    spec_dem_resolution = 10,
    spec_flat_increment = 0.01,
    spec_breach_method = 'basic',
    spec_burn_streams = FALSE,
    verbose = FALSE,
    confirm = FALSE
)

MacroSHEDS/macrosheds documentation built on Oct. 30, 2024, 11:15 a.m.