SSNbler (version 1.1.0)

sites_to_lsn: Incorporate sites into a Landscape Network

Description

Incorporates an sf object containing features with POINT geometry into a landscape network (LSN), which is a topological data model of streams/rivers represented as a directional graph embedded in 2-D geographic space. Point locations are 'snapped' to the closest edge location and new information is generated describing the geographic and topological location relative to other features in the LSN.

Usage

sites_to_lsn(
  sites,
  edges,
  snap_tolerance,
  save_local = TRUE,
  lsn_path = NULL,
  file_name = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Value

An sf object with POINT geometry containing the features from sites that were found within the snap_tolerance distance to the closest edge. In addition to the original columns in sites, three new columns are added: rid, ratio, and snapdist (see Details). If save_local = TRUE, the sf object is also saved to lsn_path.

Arguments

sites

An sf object with POINT geometry, typically representing observed data or prediction locations.

edges

An sf object with LINESTRING geometry created using lines_to_lsn.

snap_tolerance

Numeric distance in map units >= 0. Sites that are <= this distance from an edge feature will snapped to the closest location on the edge. When the distance between the site and all edges is > snap_tolerance, the point feature is not snapped or included in the lsn_path.

save_local

Logical indicating whether the outputs should be saved to a local directory in GeoPackage format. Defaults to TRUE.

lsn_path

Pathname to the LSN. This is typically a directory created by lines_to_lsn. Required if save_local = TRUE.

file_name

Filename for output sites, which are saved to lsn_path in GeoPackage format (must include the .gpkg extension). Required if save_local = TRUE.

overwrite

Logical indicating whether the outputs saved to lsn_path should overwrite existing files if they exist. Defaults to FALSE.

verbose

Logical indicating whether progress messages should be printed to the console. Defaults to TRUE

Details

The sites_to_lsn function is used to incorporate observed and prediction sites into the LSN. The output is an sf object with POINT geometry, which contains only the point features from sites that were found less than the snap_tolerance distance from the closest edge feature. When a sites point feature meets these requirements, it is moved (i.e. snapped) to the closest location on an edge feature. Three new columns are also added: rid, ratio, and snapdist. The rid column contains the rid for the edge the site has been snapped to. The second column, ratio, represents the proportional length of the edge found between the downstream end node for the edge and the updated/snapped site location. The snapdist is the distance in map units that the site was moved. If the distance between a point feature and the closest edge is greater than or equal to the snap_tolerance, the feature is not included in the output.

The snap_tolerance must always be \(\ge 0\) and must be large enough to snap all of the point features to the edges. Using snap_tolerance = 0 is not recommended, even when the sites features intersect the edge features. Instead, a very small snap_tolerance value is recommended to ensure that differences in the precision of the x and y coordinates and the line location do not result in unsnapped point features.

Note that the sites and edges must have the same projection.

Examples

# Get temporary directory, where the example LSN will be stored
# locally.
temp_dir <- tempdir()
# Build the LSN. When working with your own data, lsn_path will be
# a local folder of your choice rather than a temporary directory.
edges<- lines_to_lsn(
   streams = MF_streams,
   lsn_path = temp_dir,
   snap_tolerance = 1,
   check_topology = FALSE,
   overwrite = TRUE,
   verbose = FALSE
)

# # Incorporate observed sites, MF_obs, into LSN
obs<- sites_to_lsn(
   sites = MF_obs,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 100,
   overwrite = TRUE,
   verbose = FALSE
)
# Notice that 3 new columns have been added to obs
names(obs)

# Incorporate prediction dataset, MF_preds, into LSN
preds<- sites_to_lsn(sites = MF_preds,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 1,
   overwrite = TRUE,
   verbose = FALSE
)