build(stage1): create primary outcome review package

2026-09-20 08:58:52 +12:00
parent c8dee9b8e8
commit f7e0dbbc22
11 changed files with 1209 additions and 7 deletions
@@ -1055,3 +1055,61 @@ Remove the override and tolerate the harmless warning, or use an actual readable
 - **Notes**: The override is removed; no index changes occurred in the failed attempt.

 ---
+## [ERR-20260920-024] parquet-field-name-assumption
+
+**Logged**: 2026-09-20
+**Priority**: low
+**Status**: resolved
+**Area**: data
+
+### Summary
+A diagnostic PyArrow read requested a non-existent `survey_year` field from the NSDUH full Parquet.
+
+### Error
+The full NSDUH schema uses `YEAR`, not `survey_year`.
+
+### Context
+The field name was inferred from the YRBS convention instead of checked against the NSDUH schema. No data were modified.
+
+### Suggested Fix
+Inspect the authoritative schema before column projection and use the source-specific `YEAR` field; DuckDB then verified the intended annual counts.
+
+### Metadata
+- Reproducible: yes
+- Related Files: `Dataset/可直接分析数据包_NSDUH_YRBS/NSDUH/nsduh_2021_2024_full.parquet`
+- Pattern-Key: schema.field-name-assumption
+
+### Resolution
+- **Resolved**: 2026-09-20
+- **Notes**: Re-ran the count query against `YEAR` and obtained annual distributions for `YUSUITHK` and `YUSUIPLN`.
+
+---
+## [ERR-20260920-025] yrbs-attempt-response-shape
+
+**Logged**: 2026-09-20
+**Priority**: medium
+**Status**: resolved
+**Area**: data
+
+### Summary
+The first Gate-1 package build assumed all YRBS primary outcomes were binary and stopped on attempt response code 3.
+
+### Error
+`ValueError: Unsupported response code: survey='YRBS' construct='suicide_attempt' code='3' label='2 or 3 times'`
+
+### Context
+Annual source audits correctly retained five attempt-frequency categories, but the canonical response function handled the ordinal mapping only for GSHS. The fail-closed check prevented output files from being written.
+
+### Suggested Fix
+Apply the shared five-level frequency mapping to both GSHS and YRBS attempt items and rerun all package validations.
+
+### Metadata
+- Reproducible: yes
+- Related Files: `research/stage1/build_primary_outcome_package.py`, `research/stage1/yrbs_primary_outcome_source_audit.json`
+- Pattern-Key: response-dictionary.shape-assumption
+
+### Resolution
+- **Resolved**: 2026-09-20
+- **Notes**: Canonical attempt categories are now `zero`, `one`, `two_or_three`, `four_or_five`, and `six_or_more` in both surveys.
+
+---