9 Patterns and Templates

9.1 How to use pattern cards

Treat each card as a do-this-exactly runbook for a common scenario.

Each card tells you:

  • when to use it,
  • which layers it produces,
  • which inputs are hard-coded or conditional,
  • which intermediate artifacts must be reviewed,
  • what to escalate.

9.2 Pattern Card 1 — Fraser Sockeye (dual stream layers + targeted gap fills)

9.2.1 Use when

  • Species is Fraser Sockeye
  • You need CU outputs plus pop/context outputs aligned with current production practice
  • You expect CU-specific gap-fill logic and decoder-heavy matching

9.2.2 Repo and script

  • Repo: FRSK-WSPDataPrep
  • Script: CODE/Prep4_CleanedFlatFile_Fraser_Sk_KDEdits2024.R

9.2.3 Key output layers

  • cu_trend
  • cu_abundance
  • pop_representation

9.2.4 Required inputs

  • DATA_IN/SKAll (Nov YYYY).csv
  • DATA_IN/Fraser Sockeye SR Data_YYYY.csv
  • DATA_IN/Sockeye_Fraser_CU_Streams.csv
  • DATA_IN/Sockeye_Fraser_SR_Streams.csv
  • DATA_IN/Sockeye_Fraser_Expansion_Years.csv
  • DATA_LOOKUP_FILES/MOD_MAIN_CU_LOOKUP_FOR_SOS.csv
  • DATA_LOOKUP_FILES/Site_Info_GeneratedDecoder_Fraser_Sk.csv

9.2.5 Important notes before run

  • Check whether the script expects literal file names.
  • Keep trend-layer and abundance-layer stream lists distinct.
  • Open the exception register before running; you will probably need it.

9.2.6 Run

cd FRSK-WSPDataPrep
Rscript CODE/Prep4_CleanedFlatFile_Fraser_Sk_KDEdits2024.R

9.2.7 Review these artifacts before release

  • DATA_TRACKING/FraserSockeye_MatchingCheck.csv
  • DATA_TRACKING/Sites not in CUs.csv
  • CU-specific prep files in DATA_TRACKING/FraserSockeyePrep/
  • any manual suppression or gap-fill notes recorded in the run log

9.2.8 Escalate if

  • decoder joins break because stream names changed,
  • a high-priority CU changes method family,
  • the abundance and trend layers can no longer be explained cleanly.

9.3 Pattern Card 2 — Interior Fraser Coho (WSP-only CU layer + all-stream pop layer)

9.3.1 Use when

  • Species is Interior Fraser Coho
  • You need CU outputs, pop outputs, and brood-year / decomposition support

9.3.2 Repo and scripts

  • Repo: FRCo-WSPDataPrep
  • Scripts:
    • CODE/SUB_Data extraction and clean up (Coho for now)_2023.R
    • CODE/Prep5_CleanedFlatFile_Fraser_Coho.R

9.3.3 Key output layers

  • cu_trend
  • cu_abundance
  • pop_representation

9.3.4 Required inputs

  • latest DATA_IN/IFC Data 1975-<year> ... for Salmon Scanner.csv
  • DATA_IN/FRSK_CU_Info_masterUpdate.csv
  • DATA_IN/Fraser Coho POPID Lookup...csv
  • DATA_LOOKUP_FILES/MOD_MAIN_CU_LOOKUP_FOR_SOS.csv
  • DATA_IN/IFC Infill exceptions.csv only if the active path actually uses it

9.3.5 Important notes before run

  • Document whether the CU layer is WSP-only and the pop layer is all-stream.
  • Confirm how Final.Estimate.Type == "NO" is treated.
  • Treat decomposition tables as QC evidence, not as optional extras.

9.3.6 Run

cd FRCo-WSPDataPrep
Rscript CODE/Prep5_CleanedFlatFile_Fraser_Coho.R

9.3.7 Review these artifacts before release

  • DATA_PROCESSING/Calc.Nat Table for <CU>.csv
  • DATA_PROCESSING/All IFC CUs BY Table_EC.max=NA_infill=FALSE.csv
  • any Check.Natural.Returns outputs or equivalent summaries

9.3.8 Escalate if

  • tributary names stop matching the POPID crosswalk,
  • natural versus hatchery components shift sharply without explanation,
  • the pop layer stops being intentionally broader than the CU layer.

9.4 Pattern Card 3 — Lower Fraser Chum (major-system CU layer with expected CU/pop non-equality)

9.4.1 Use when

  • Species is Lower Fraser Chum
  • You need the production CU layer and pop representation built from major systems and Harrison logic

9.4.2 Repo and script

  • Repo: FRCm-WSPDataPrep
  • Script: CODE/Prep7_Create Fraser Chum2.R

9.4.3 Required inputs

  • DATA_IN/FR Chum Major Systems.csv
  • DATA_IN/Harrison Chum Escapement Summary.csv
  • DATA_IN/Chum extensive pivot.csv
  • DATA_IN/FR Chum POPID Crosswalk.csv

9.4.4 Important notes before run

  • Do not expect CU totals to equal the sum of pop rows.
  • Review any row-name / unnamed-column CSV behaviour before downstream use.
  • Log the Harrison and Squawkum handling explicitly.

9.4.5 Run

cd FRCm-WSPDataPrep
Rscript "CODE/Prep7_Create Fraser Chum2.R"

9.4.6 Review these artifacts before release

  • final CU and pop files,
  • any comparison showing Harrison decomposition,
  • run-log note explaining expected CU/pop non-equality.

9.4.7 Escalate if

  • the non-equality pattern cannot be explained,
  • unnamed first columns break downstream import,
  • year truncation changes relative to the prior release.

9.5 Pattern Card 4 — Fraser Pink (official CU series + historical context layer)

9.5.1 Use when

  • Species is Fraser Pink
  • You need the official CU series plus the historical NuSEDS-based pop/context layer

9.5.2 Repo and script

  • Repo: FRPink-WSPDataPrep
  • Script: CODE/Prep6_Create Fraser Pink_2.R

9.5.3 Required inputs

  • DATA_IN/Fraser Pink esc_rec CU.csv
  • DATA_IN/FR_Pink_Conservation_Unit_Data_NUSEDs_June 2023.csv

9.5.4 Important notes before run

  • Keep the official CU series authoritative across the whole time series.
  • Treat the historical NuSEDS layer as context, not as a replacement CU series.
  • Review the Fraser aggregate pop row separately from ordinary pop rows.

9.5.5 Run

cd FRPink-WSPDataPrep
Rscript "CODE/Prep6_Create Fraser Pink_2.R"

9.5.6 Review these artifacts before release

  • final CU and pop files,
  • a year-transition check around the pre-1993 historical layer,
  • confirmation that the Fraser aggregate row retains expected NA trend fields.

9.5.7 Escalate if

  • the official CU series appears to be overwritten by stream sums,
  • the historical transition years cannot be explained,
  • the Fraser aggregate row loses its special semantics.

9.6 Pattern Card 5 — CU/WSP bundle handoff

9.6.1 Use when

  • final CU outputs passed release QC,
  • you need a stable handoff for metrics, packaging, or another consumer.

9.6.2 Required inputs

  • cu_timeseries.csv
  • wsp_metric_specs.csv
  • optional wsp_cyclic_benchmarks.csv
  • optional cu_metadata.csv
  • sidecars: run-log.md, decision-log.md, qc-summary.md, metadata_notes.md

9.6.3 Minimum QC before handoff

  • CU/spec alignment checked,
  • intentional NA patterns documented,
  • exception register reviewed,
  • intermediate QC artifacts linked from the summary.

9.6.4 Handoff outputs

  • status-ready bundle,
  • optional Salmon Data Package,
  • optional derived consumer bridge.