Vignette: PARS Peace mapping_code — link/bcfp parity + Arctic grayling showcase (Peace 2025 appendix prep) #215

Problem

link has no vignette. We want one for the PARS (Parsnip) WSG in the FWCP Peace region that rehearses a habitat mapping_code analysis end-to-end, so we can transfer the showcase into the Fish Passage Peace 2025 report appendix. This is the same vignette-then-appendix path flooded followed (its pars-floodplain.Rmd became 0830-appendix-floodplain.Rmd in the Peace report), templated in fish_passage_template_reporting#178.

The vignette does two things:

1. Parity — link's bcfishpass config reproduces bcfishpass's per-segment mapping_code methodology for PARS. PARS sits inside the 99.66% median match across the 50 study-area WSGs (link#175). Tunnel-free comparison against the local fresh.streams_vw_bcfp snapshot via lnk_compare_mapping_code / lnk_compare_rollup / lnk_parity_annotate.
2. Arctic grayling showcase — link's default config models Arctic grayling (GR), a species bcfishpass does not model. This is the net-new, project-specific extension and the first concrete output of the framework for FWCP Peace (see fish_passage_template_reporting#192).

Positioning (load-bearing)

Framing follows fish_passage_template_reporting#192: this complements and extends the canonical smnorris freshwater stack (fwapg, bcfishpass, bcfishobs) — it does not supersede it. Lead with what is net-new (project-specific parameterization, the grayling model); frame upstream as foundational/canonical and link as the downstream project layer. Simon Norris credited inline, lightly.

Leverage (don't reinvent)

• flooded vignettes/pars-floodplain.Rmd — bookdown::html_vignette2 front-matter, narrative arc, sourced parameter table via xciter::xct_keys_to_inline_table_col, terra hillshade + sf overlay maps, inline bcfp credit.
• flooded data-raw/wsg_vignette_data.R — data-gen -> inst/vignette-data/*.gpkg caching. Not the .Rmd.orig pre-knit pattern (breaks bookdown figure numbering).
• flooded#35 — WSG-scale vignette composition + output-path convention.
• fish_passage_template_reporting#178 — how the analysis lands as a templated report chapter.
• fish_passage_template_reporting#192 — tone/positioning + grayling-first framing.
• fish_passage_peace_2025_reporting/0830-appendix-floodplain.Rmd — the report-appendix target shape.
• existing link fns: lnk_compare_mapping_code, lnk_compare_rollup, lnk_mapping_code, lnk_parity_annotate, lnk_stamp, lnk_pipeline_run(mapping_code = TRUE).

Proposed vignette (vignettes/pars-mapping-code.Rmd)

1. Orienting paragraph — PARS in the Peace; what mapping_code is (per-segment access x habitat).
2. Modelling parameters — lnk_stamp() / config param table, citations inline (xciter).
3. Cached inputs — load system.file("vignette-data/pars.gpkg", package = "link") + rollup .rds; GitHub raw download links.
4. Reproducing bcfishpass (parity) — per-species PARS match% vs the fresh.streams_vw_bcfp snapshot. Frames link as faithful reproduction of the canonical methodology.
5. Arctic grayling — a link extension — GR mapping_code map for PARS; explicit that bcfp doesn't model GR.
6. Maps — terra hillshade + sf stream overlay (full-WSG + detail), flooded symbology.
7. From vignette to report — short forward-looking paragraph naming the Peace 2025 appendix as the landing spot.
8. References.

Infra to add (link has none today)

• DESCRIPTION Suggests: bookdown, knitr, rmarkdown, xciter, terra; VignetteBuilder: knitr.
• vignettes/ + vignettes/references.bib.
• data-raw/pars_vignette_data.R — runs the PARS compare once, caches inst/vignette-data/pars.gpkg + parity .rds.
• _pkgdown.yml — add articles: (pkgdown action already exists).

Dependencies / relations

• link-authored bcfp-style rules for KO, RB, GR in bcfishpass config (for link-vs-link comparison on the full species set) #212 (KO/RB/GR rows in the bcfp config) — required only for the link-vs-link full-species Comparison B. The grayling showcase here uses the default config and is independent of link-authored bcfp-style rules for KO, RB, GR in bcfishpass config (for link-vs-link comparison on the full species set) #212. The vignette will note this so the two aren't conflated.
• Relates: Promote with_mapping_code flag to stand-alone lnk_compare_mapping_code() export #175 (parity baseline), NewGraphEnvironment/fish_passage_template_reporting#192, NewGraphEnvironment/fish_passage_template_reporting#178, WSG-scale floodplain pipeline: multi-AOI iteration + memory + intermediate storage flooded#35, pkgdown site and vignette flooded#17.

Acceptance

• Vignette infra scaffolded (Suggests, vignettes/, _pkgdown.yml articles, references.bib).
• data-raw/pars_vignette_data.R generates + caches PARS gpkg + parity rollup .rds.
• vignettes/pars-mapping-code.Rmd renders via pkgdown::build_site(new_process = FALSE); figures numbered, cross-refs + examples run.
• Parity table reproduces PARS numbers from the Promote with_mapping_code flag to stand-alone lnk_compare_mapping_code() export #175 baseline.
• GR map renders from default-config output.
• Positioning consistent with lnk_pipeline_run: mapping_code phase hardcodes bcfp 8 species → fails on non-bcfp bundles #192 (extends, not supersedes); upstream framed as canonical.

Out of scope

• link-authored bcfp-style rules for KO, RB, GR in bcfishpass config (for link-vs-link comparison on the full species set) #212's bcfp-config GR rows / link-vs-link Comparison B (separate; showcase uses default config).
• The report-side chapter itself (lives in the Peace report / template Cypher integration tests for autonomous wrapper (1-cypher -> 3-cypher tiers) #178, lnk_pipeline_run: mapping_code phase hardcodes bcfp 8 species → fails on non-bcfp bundles #192).
• bcfishobs calibration loop (template lnk_pipeline_run: mapping_code phase hardcodes bcfp 8 species → fails on non-bcfp bundles #192 Phase C).

🤖 Generated with Claude Code