Skip to contents

Find Gradient Break Locations on a Stream Network

Source: R/frs_break.R
frs_break_find.Rd

Detect where stream gradient exceeds a threshold for a sustained distance (island detection). Produces break points at the entry of each steep section, suitable for frs_break_apply().

Usage

frs_break_find(
  conn,
  table,
  to = "working.breaks",
  attribute = NULL,
  threshold = NULL,
  interval = 100L,
  distance = 100L,
  min_length = 0L,
  classes = NULL,
  blk_filter = TRUE,
  overwrite = TRUE
)

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.

min_length

Integer. Minimum island length in metres to keep. Default 0 (keep all islands — a 30m waterfall at 20% gradient is a real barrier). Set to 100 to restore pre-0.12.2 behavior where short steep sections were filtered out.

classes

Named numeric vector or NULL. Gradient class lower bounds for multi-class detection (matching bcfishpass v0.5.0). Names are class labels (used in gradient_class column), values are lower gradient bounds. When provided, threshold is ignored and all classes are detected in one pass. Example: c("5" = 0.05, "7" = 0.07, "15" = 0.15, "25" = 0.25).

blk_filter

Logical. If TRUE (default), only sample main flow lines (blue_line_key = watershed_key). Matches bcfishpass. FALSE samples all edge types including side channels.

overwrite

Logical. If TRUE, drop to before creating. Default TRUE.

Value

conn invisibly, for pipe chaining.

Details

For locating point features on the network (crossings, falls, observations), use frs_feature_find() instead.

See also

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

Examples

# --- Where breaks occur (bundled data) ---
# Break points are locations where a stream attribute exceeds a threshold.
# Here: segments with gradient > 5% (potential barriers to fish passage).

d <- readRDS(system.file("extdata", "byman_ailport.rds", package = "fresh"))
streams <- d$streams

# Which segments exceed 5% gradient?
is_steep <- streams$gradient > 0.05
message(sum(is_steep, na.rm = TRUE), " of ", nrow(streams),
        " segments exceed 5% gradient")
#> 546 of 2167 segments exceed 5% gradient

# Plot: steep segments (red) are where breaks would be placed
plot(sf::st_geometry(streams), col = "grey80",
     main = "Break locations: gradient > 5%")
plot(sf::st_geometry(streams[which(is_steep), ]), col = "red", add = TRUE)
legend("topright", legend = c("below threshold", "above threshold (break)"),
       col = c("grey80", "red"), lwd = 2, cex = 0.8)


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

# Attribute mode: break where gradient exceeds 5%
conn |>
  frs_extract("bcfishpass.streams_vw", "working.streams", aoi = "BULK") |>
  frs_break_find("working.streams", attribute = "gradient", threshold = 0.05)

DBI::dbDisconnect(conn)
} # }