Snap points to stream segment within the sub-catchment

Move points to the stream segment within the sub-catchment where the point is located.

Usage

snap_to_subc_segment(
  data,
  lon,
  lat,
  id,
  basin_id = NULL,
  subc_id = NULL,
  basin_layer,
  subc_layer,
  stream_layer,
  n_cores = 1,
  quiet = TRUE
)

Arguments

data

a data.frame or data.table that contains the columns regarding the longitude / latitude coordinates in WGS84.

lon

character. The name of the column with the longitude coordinates.

lat

character. The name of the column with the latitude coordinates.

id

character. The name of a column containing unique IDs for each row of "data" (e.g., occurrence or site IDs). The unique IDs need to be numeric and less than 10 characters long.

basin_id

character. The name of the column with the basin IDs. If NULL, the basin IDs will be extracted automatically. Optional. Default is NULL

subc_id

character. The name of the column with the sub-catchment IDs. If NULL, the sub-catchment IDs will be extracted automatically. Optional. Default is NULL.

basin_layer

character. Full path to the basin ID .tif layer.

subc_layer

character. Full path to the sub-catchment ID .tif layer.

stream_layer

character. Full path of the stream network .gpkg file.

n_cores

numeric. Number of cores used for parallelisation. Default is 1.

quiet

logical. If FALSE, the standard output will be printed. Default is TRUE.

Value

A data.table of the original and new coordinates, along with the sub-catchment ID.

Details

The function uses the network module of GRASS GIS (v.net), to connect a vector line map (stream network) with a point map (occurrence/sampling points). After masking the stream segment and the sub-catchment where the target point is located, the connect operation snaps the point to the stream segment using a distance threshold. This threshold is automatically calculated as the longest distance between two points within the sub-catchment. In this way the snapping will always take place. From the new location, the function extracts the new snapped coordinates.

References

https://grass.osgeo.org/grass82/manuals/v.net.html

See also

• snap_to_network() to snap the data points to the next stream segment within a given radius and/or a given flow accumulation threshold value.

• extract_ids() to extract basin and sub-catchment IDs.

Author

Jaime Garcia Marquez, Marlene Schürz

Examples

# Download test data into the temporary R folder
# or define a different directory
my_directory <- tempdir()
download_test_data(my_directory)

# Load occurrence data
species_occurence <- read.table(paste0(my_directory,
                            "/hydrography90m_test_data/spdata_1264942.txt"),
                              header = TRUE)
basin_rast <- paste0(my_directory,
                     "/hydrography90m_test_data/basin_1264942.tif")
subc_rast <- paste0(my_directory,
                    "/hydrography90m_test_data/subcatchment_1264942.tif")

# Define full path to the vector file of the stream network
stream_vect <- paste0(my_directory,
                      "/hydrography90m_test_data/order_vect_59.gpkg")

hydrography90m_ids <- extract_ids(data = species_occurence,
                                  lon = "longitude",
                                  lat = "latitude",
                                  id = "occurrence_id",
                                  subc_layer = subc_rast,
                                  basin_layer = basin_rast)

# Snap data points to the stream segment of the provided sub-catchment ID
snapped_coordinates <- snap_to_subc_segment(data = hydrography90m_ids,
                                            lon = "longitude",
                                            lat = "latitude",
                                            id = "occurrence_id",
                                            basin_id = "basin_id",
                                            subc_id = "subcatchment_id",
                                            basin_layer = basin_rast,
                                            subc_layer = subc_rast,
                                            stream_layer = stream_vect,
                                            n_cores = 2)
# Show head of output table
head(snapped_coordinates)

# OR
# Automatically extract the basin and sub-catchment IDs and
# snap the data points to the stream segment
snapped_coordinates <- snap_to_subc_segment(data = species_occurence,
                                            lon = "longitude",
                                            lat = "latitude",
                                            id = "occurrence_id",
                                            basin_layer = basin_rast,
                                            subc_layer = subc_rast,
                                            stream_layer = stream_vect,
                                            n_cores = 2)
# Show head of output table
head(snapped_coordinates)