Break Stream Network at an Attribute Threshold

Convenience wrapper that calls frs_break_find(), optionally frs_break_validate(), then frs_break_apply() in sequence. To break at point features instead, locate them with frs_feature_find() and pass that table to frs_break_apply().

Usage

frs_break(
  conn,
  table,
  to = "working.breaks",
  attribute = NULL,
  threshold = NULL,
  interval = 100L,
  distance = 100L,
  overwrite = TRUE,
  evidence_table = NULL,
  where = NULL,
  count_threshold = 1L,
  segment_id = "linear_feature_id"
)

Arguments

conn: A DBI::DBIConnection object (from frs_db_conn()).
table: Character. Working schema table to find breaks on (from frs_extract()).
to: Character. Destination table for break points. Default "working.breaks".
attribute: Character. Column name for threshold-based breaks. Currently only "gradient" is supported.
threshold: Numeric. Threshold value — sustained sections where gradient exceeds this produce a break point at the entry.
interval: Integer. Not used (kept for compatibility). Default 100.
distance: Integer. Upstream window in metres for gradient computation at each vertex. Default 100.
overwrite: Logical. If TRUE, drop to before creating. Default TRUE.
evidence_table: Character or NULL. If provided, validate breaks against upstream evidence before applying. Passed to frs_break_validate().
where: Character or NULL. SQL predicate to filter evidence (e.g. "e.species_code IN ('CO','CH')"). Passed to frs_break_validate().
count_threshold: Integer. Minimum upstream evidence count to remove a break. Default 1.
segment_id: Character. Column name used as segment identifier. Passed to frs_break_apply(). Default "linear_feature_id".

Value

conn invisibly, for pipe chaining.

Examples

# --- Concept: what frs_break does (bundled data) ---
d <- readRDS(system.file("extdata", "byman_ailport.rds", package = "fresh"))
streams <- d$streams

# Steep segments are where breaks get placed
steep <- !is.na(streams$gradient) & streams$gradient > 0.08
plot(sf::st_geometry(streams), col = "grey80",
     main = "Gradient breaks (> 8%)")
plot(sf::st_geometry(streams[steep, ]), col = "red", add = TRUE)
legend("topright",
       legend = c("below threshold", "above (break here)"),
       col = c("grey80", "red"), lwd = 2, cex = 0.8)


if (FALSE) { # \dontrun{
# --- Live DB: copy-paste to see before/after ---
conn <- frs_db_conn()
aoi <- d$aoi  # Byman-Ailport sf polygon from bundled data

# 1. Extract FWA base streams (unsegmented) to working schema
conn |> frs_extract(
  from = "whse_basemapping.fwa_stream_networks_sp",
  to = "working.demo_streams",
  cols = c("linear_feature_id", "blue_line_key",
           "downstream_route_measure", "upstream_route_measure",
           "gradient", "geom"),
  aoi = aoi,
  overwrite = TRUE
)

# 2. Plot BEFORE — original segments
before <- frs_db_query(conn,
  "SELECT gradient, geom FROM working.demo_streams")
n_before <- nrow(before)
plot(before["gradient"], main = paste("Before:", n_before, "segments"))

# 3. Convert to generated columns — gradient auto-recomputes after break
conn |> frs_col_generate("working.demo_streams")

# 4. Break at gradient > 8%
conn |> frs_break("working.demo_streams",
  attribute = "gradient", threshold = 0.08)

# 5. Plot AFTER — more segments, gradient recomputed per sub-segment
after <- frs_db_query(conn,
  "SELECT gradient, geom FROM working.demo_streams")
n_after <- nrow(after)
plot(after["gradient"],
     main = paste("After:", n_after, "segments (+",
                  n_after - n_before, "from breaks)"))

# Clean up
DBI::dbExecute(conn, "DROP TABLE IF EXISTS working.demo_streams")
DBI::dbExecute(conn, "DROP TABLE IF EXISTS working.breaks")
DBI::dbDisconnect(conn)
} # }

Break Stream Network at an Attribute Threshold

Usage

Arguments

Value

See also

Examples