A tool to quantify the area and ecological value impacted by a Harmful Alteration, Disruption, or Destruction (HADD) of fish habitat, in a metric that is comparable across projects.
The metric combines physical area, habitat quality (suitability), severity of harm, and duration into a standardized unit of habitat-unit-years (HU·yr) — on the Habitat Evaluation Procedures (HEP) / Habitat Equivalency Analysis (HEA) basis — anchored to a locked library of quality lookups, severity tiers, and duration conventions drawn from agency and peer-reviewed sources. The same library version is used across projects, so two HADD assessments produced by the tool are directly comparable.
- Regulator: Fisheries and Oceans Canada (DFO), under the Fish and Fish Habitat Protection Policy (2019) and the Authorizations Concerning Fish and Fish Habitat Protection Regulations.
- Habitat: Freshwater lotic (streams and rivers).
- Lifecycle stage: Pre-project prediction, offset-requirement calculation, and post-construction verification — same metric carried through.
- Sides of the ledger: Both loss (HADD) and gain (offset uplift) computed in the same tool, producing a net-effect balance sheet.
Excel workbook (user-facing) backed by R helper scripts:
- R side (authoritative): GIS preprocessing with
sf, the calculation engine, validation, and report generation. - Excel workbook (transparent UI): Per-reach inputs, version-stamped coefficient sheet, selectable quality-scoring method, calculation sheet that mirrors R, and a DFO-submission-ready summary/balance sheet.
HADD impact (habitat-unit-years) = Σ_reach ( Area × Quality × Severity × Duration )
where
- Area — m² of impacted habitat (from GIS or tabular entry)
- Quality — 0–1 habitat-suitability score from one of three supported methods: BC FHAP, categorical tiers, or composite HSI;
Area × Qualityis a habitat unit (HEP basis) - Severity — multiplier: Destruction = 1.0; Alteration and Disruption assigned per documented rubric
- Duration — service-years credited over the analysis horizon, including proportional partial-year impacts
Offset lift uses the same equation with positive sign; net balance is gain minus loss.
hadd-quantify/
├── R/ # Calculation engine and helpers
├── data/ # Locked, versioned coefficient and lookup tables (RDS/CSV)
├── data-raw/ # Source spreadsheets and scripts that build /data
├── inst/extdata/ # Excel workbook template and example inputs
├── tests/testthat/ # Unit and synthetic-case tests
├── vignettes/ # Worked example — synthetic project, GIS to verified workbook
├── docs/ # Methods document, user guide, milestone schedule
├── man/ # Generated function docs
├── DESCRIPTION
├── PLAN.md
├── MILESTONES.md
└── README.md
Phase: Implementation. M1 (methods), M2 (coefficient library, locked v1.0), M3 (calculation engine), M4 (Excel workbook), M5 (validation & sensitivity), and M6 (documentation & internal pilot) are complete with regression coverage; M7 (release) remains pending. See MILESTONES.md for the schedule, PLAN.md for the full development plan, and docs/HADD_Build_Tracker.html (backed by docs/hadd-tracker-state.json) for per-task status.
| Document | Covers |
|---|---|
docs/methods.md |
Methods Document v1.0 — the standardization rationale that travels with a DFO submission |
docs/user-guide.md |
Operator workflow: inputs, quality method, workbook, verification, interpretation |
vignettes/worked-example.Rmd |
The same workflow as runnable, oracle-checked code |
docs/sensitivity-report.md |
M5 defensibility and sensitivity findings |
docs/pilot-report.md |
Internal pilot run and lessons learned |
docs/methods-edge-cases.md |
Worked boundary cases |
The .docx deliverables are generated artifacts kept out of git; regenerate with pandoc <file>.md -o <file>.docx --resource-path=docs.
Rscript -e pkgload::load_all('.') -e testthat::test_local()
R CMD build .
R CMD check --no-manual haddquantify_0.0.0.9001.tar.gzThe CI workflow mirrors the package check across macOS, Windows, and Ubuntu via .github/workflows/R-CMD-check.yaml. On Windows shells that export unsupported C.UTF-8 locale variables, run the check with LC_ALL=C and LC_CTYPE=C.
inst/extdata/synthetic_project/ contains a compact acceptance-test dataset shaped like real project inputs: impact reaches, offsets, WKT spatial layers, remote-sensing reference samples, classifier quality probabilities, metadata, and expected engine outputs. Rebuild it with:
Rscript data-raw/build_synthetic_project.RThe package ships a static review console for the synthetic fixture and CSV-based scenario checks:
hq_launch_ui()Use hq_launch_ui(open = FALSE) to return the packaged HTML path without opening a browser.
Internal consulting tool. Single-author repo at this stage.
Proprietary — internal consulting use only; all rights reserved (see LICENSE). No license for
redistribution, publication, or external distribution is granted at this time. A formal license
will be determined before any external release.