Skip to contents

Find Features on a Stream Network

Source: R/frs_feature_find.R
frs_feature_find.Rd

Locate features from a database table or sf object on the stream network. Produces a table with blue_line_key, downstream_route_measure, label, and source columns, suitable for frs_break_apply(), frs_feature_index(), or as a break source in frs_habitat().

Usage

frs_feature_find(
  conn,
  table,
  to = "working.features",
  points_table = NULL,
  points = NULL,
  where = NULL,
  col_blk = "blue_line_key",
  col_measure = "downstream_route_measure",
  col_id = NULL,
  label = NULL,
  label_col = NULL,
  label_map = NULL,
  overwrite = TRUE,
  append = FALSE
)

Arguments

conn

A DBI::DBIConnection object.

table

Character. Working streams table (for BLK scoping).

to

Character. Destination table name. Default "working.features".

points_table

Character or NULL. Schema-qualified table with network-referenced features.

points

An sf object or NULL. User-provided points to snap to the network via frs_point_snap() (default 100 m tolerance; points farther than that are dropped with a message). col_id, label, label_col (a column of points) and label_map apply as for points_table. For other snap options, snap first with frs_point_snap() and pass the result as points_table.

where

Character or NULL. SQL predicate to filter points_table.

col_blk

Character. Column name for stream identifier in points_table. Default "blue_line_key".

col_measure

Character. Column name for route measure in points_table. Default "downstream_route_measure".

col_id

Character or NULL. Column name for feature ID. When provided, included in output as text column feature_id for joining back to source.

label

Character or NULL. Static label for all features.

label_col

Character or NULL. Column name to read labels from.

label_map

Named character vector or NULL. Maps label_col values to output labels. Values are compared as text; for a logical / boolean column use keys "TRUE" / "FALSE" (or "t" / "f").

overwrite

Logical. Drop to before creating. Default TRUE.

append

Logical. INSERT INTO existing to table. Default FALSE.

Value

conn invisibly, for pipe chaining.

Details

Unlike frs_break_find() which is specific to gradient threshold detection, this function handles any point features on the network: crossings, fish observations, water quality stations, flow gauges, territory boundaries, etc.

See also

Other habitat: frs_aggregate(), frs_break(), frs_break_apply(), frs_break_find(), frs_break_validate(), frs_categorize(), frs_channel_width(), frs_classify(), frs_cluster(), frs_col_generate(), frs_col_join(), frs_extract(), frs_feature_index(), frs_habitat(), frs_habitat_access(), frs_habitat_classify(), frs_habitat_overlay(), frs_habitat_partition(), frs_habitat_predicates(), frs_habitat_species(), frs_near_river(), frs_network_segment()

Examples

if (FALSE) { # \dontrun{
conn <- frs_db_conn()

# Crossings with severity labels
frs_feature_find(conn, "working.streams",
  points_table = "working.crossings",
  col_id = "aggregated_crossings_id",
  label_col = "barrier_status",
  label_map = c("BARRIER" = "blocked", "POTENTIAL" = "potential"),
  to = "working.features_crossings")

# Fish observations
frs_feature_find(conn, "working.streams",
  points_table = "bcfishobs.fiss_fish_obsrvtn_events_vw",
  col_id = "fish_observation_point_id",
  label_col = "species_code",
  to = "working.features_fish_obs")

# Use as break source in habitat pipeline
frs_habitat(conn, "BULK", break_sources = list(
  list(table = "working.features_crossings",
       label_col = "label")))

DBI::dbDisconnect(conn)
} # }