Multi-class gradient barrier detection in single pass (match bcfishpass v0.5.0)

[NewGraphEnvironment]

Problem

fresh 0.12.5 runs frs_break_find separately for each gradient threshold (15%, 20%, 25%, 30%). Each run does its own vertex sampling and island detection with a boolean above/below grouping. This misses class transitions WITHIN a steep section — a section going 12%→18%→25% is one island at threshold=15%, so only one barrier is placed at the downstream entry. The 25% transition point is lost.

bcfishpass v0.5.0 gradient_barriers_load.sql does one pass, tags every vertex with its gradient class (5, 7, 10, 12, 15, 20, 25, 30), and creates separate islands per class. Class transitions within a steep section produce separate barriers. This is biologically correct — the point where gradient jumps from 15% to 25% matters because CH is blocked at 15% but BT passes through to 25%.

Result: bcfishpass generates 7,136 gradient_15 barriers for ADMS. fresh generates 5,571 (found) / 4,229 (in breaks). The missing barriers are at class transitions within steep sections.

Impact

Different barrier counts → different break points → different segments → different channel width coverage on accessible segments → -23% CH spawning gap vs bcfishpass v0.5.0 (link 0.0.0.9000 ADMS comparison).

Proposed Solution

Change frs_break_find to use bcfishpass's multi-class approach:

1. One pass: sample gradient at every FWA vertex over 100m upstream window (same as now)
2. Tag classes: assign each vertex to a gradient class (5, 7, 10, 12, 15, 20, 25, 30) instead of boolean above/below
3. Island detection per class: group consecutive same-class vertices, place one barrier at the downstream entry of each class island
4. Output: all barriers in one table with a gradient_class column

frs_habitat() then filters by species access threshold — BT uses 25+30, CH/CO/SK use 15+20+25+30.

The breaks_gradient parameter on frs_habitat() becomes the list of classes to generate (default all 8), not the list of thresholds to run separately.

Key SQL difference

Current fresh (boolean):

lag(above) OVER (...) IS DISTINCT FROM above AS step

bcfishpass (class-based):

lag(grade_class) OVER (...) <> grade_class AS step

Additional bcfishpass filter to match

bcfishpass line 22: AND blue_line_key = watershed_key — only samples main flow lines, excludes 382 of 11,520 ADMS segments (secondary/side channels). Minor impact but should be a parameter for exact matching.

Versions

• fresh: 0.12.5
• bcfishpass: v0.5.0
• link: 0.0.0.9000
• fwapg: Docker local (FWA 20240830)

Relates to NewGraphEnvironment/link#16
Relates to #124

[NewGraphEnvironment]

Implementation reference

bcfishpass source SQL

Full gradient_barriers_load.sql from bcfishpass v0.5.0 — this is the target to match:

WITH grade100m AS (
  SELECT
    sv.blue_line_key,
    ROUND(sv.downstream_route_measure::numeric, 2) as downstream_route_measure,
    ROUND(((ST_Z((ST_Dump((ST_LocateAlong(
      s2.geom, sv.downstream_route_measure + 100
    )))).geom) - sv.elevation) / 100)::numeric, 4) as gradient
  FROM (
    SELECT
      blue_line_key, edge_type,
      ((ST_LineLocatePoint(geom, ST_PointN(geom, generate_series(1, ST_NPoints(geom) - 1)))
        * length_metre) + downstream_route_measure) as downstream_route_measure,
      ST_Z(ST_PointN(geom, generate_series(1, ST_NPoints(geom) - 1))) AS elevation
    FROM whse_basemapping.fwa_stream_networks_sp s
    WHERE watershed_group_code = :'wsg'
      AND blue_line_key = watershed_key
      AND edge_type != 6010
  ) as sv
  INNER JOIN whse_basemapping.fwa_stream_networks_sp s2
    ON sv.blue_line_key = s2.blue_line_key
    AND sv.downstream_route_measure + 100 >= s2.downstream_route_measure
    AND sv.downstream_route_measure + 100 < s2.upstream_route_measure
  WHERE sv.edge_type IN (1000,1050,1100,1150,1250,1350,1410,2000,2300)
    AND s2.edge_type != 6010
),

gradeclass AS (
  SELECT blue_line_key, downstream_route_measure,
    CASE
      WHEN gradient >= .05 AND gradient < .07 THEN 5
      WHEN gradient >= .07 AND gradient < .10 THEN 7
      WHEN gradient >= .10 AND gradient < .12 THEN 10
      WHEN gradient >= .12 AND gradient < .15 THEN 12
      WHEN gradient >= .15 AND gradient < .20 THEN 15
      WHEN gradient >= .20 AND gradient < .25 THEN 20
      WHEN gradient >= .25 AND gradient < .30 THEN 25
      WHEN gradient >= .30 THEN 30
      ELSE 0
    END as grade_class
  FROM grade100m
),

islands AS (
  SELECT blue_line_key,
    min(downstream_route_measure) AS downstream_route_measure,
    grade_class as gradient_class
  FROM (
    SELECT blue_line_key, downstream_route_measure, grade_class,
      count(step OR NULL) OVER (ORDER BY blue_line_key, downstream_route_measure) AS grp
    FROM (
      SELECT blue_line_key, downstream_route_measure, grade_class,
        lag(grade_class, 1, grade_class) OVER (
          ORDER BY blue_line_key, downstream_route_measure
        ) <> grade_class AS step
      FROM gradeclass
    ) sub1
    WHERE grade_class != 0
  ) sub2
  GROUP BY blue_line_key, grade_class, grp
)

SELECT blue_line_key, downstream_route_measure,
  max(gradient_class) as gradient_class
FROM islands
GROUP BY blue_line_key, downstream_route_measure

What changes in fresh

1. frs_break_find (.frs_break_find_attribute) — replace boolean above/below with multi-class grading in one pass
2. Output table gets a gradient_class column (integer: 5,7,10,12,15,20,25,30)
3. frs_habitat filters barriers by species access threshold from params_fresh$access_gradient_max
4. breaks_gradient parameter meaning changes: list of classes to generate (default c(5,7,10,12,15,20,25,30) — all 8), not separate thresholds to run individually
5. Add gradient_blk_filter parameter (default TRUE): when TRUE, only sample blue_line_key = watershed_key (matches bcfishpass). When FALSE, sample all streams.

Verification

Run ADMS comparison (link 0.0.0.9000 compare_adms.R) after this change. Check:

-- Barrier counts should match bcfishpass
SELECT gradient_class, count(*) FROM fresh.gradient_barriers
WHERE watershed_group_code = 'ADMS'
GROUP BY gradient_class ORDER BY gradient_class

-- bcfishpass reference:
-- 5: 4983, 7: 5732, 10: 5674, 12: 6230, 15: 7136, 20: 7452, 25: 7402, 30: 5451

If barrier counts match, segments match, and the CH/CO gap should close from -23% toward 0%.