docs/design/reference-scaffold/config/outcomes.yaml

# Per-outcome configuration. Adding an outcome = a new block here + a parser;
# no changes to the analysis engine. The pilot below is fully filled.
outcomes:
  - id: ela_math_g3
    label: "3rd Grade ELA + Math Proficiency"
    grade_band: ES
    sources: [test_results]

    # --- response variable -------------------------------------------------
    value:
      type: composite                       # mean of the components below
      components: [g3_ela_pct_l34, g3_math_pct_l34]   # percentages, 0..100
      denominator: g3_tested_n              # used for weights and sampling SE
    scale: percent                          # percent (0..100) | rate (0..1) | count
    desirable_direction: high               # high = good. (use "low" for absenteeism/bullying)

    # --- model -------------------------------------------------------------
    functional_form: identity               # identity | empirical_logit
    covariates: es_base                      # -> covariates.yaml
    admission_handling: covariate            # covariate | stratify | none
    prior_achievement: null                  # set a field to get a growth-style residual
    min_n: 15                                # below this, ineligible to be flagged

    # --- View 1: outliers --------------------------------------------------
    outlier:
      z_threshold: 2.0
      persistence: {window: 3, min_flags: 2}

    # --- View 2: trends ----------------------------------------------------
    comparability: ela_math_regimes          # -> comparability.yaml
    trend:
      min_years_within_regime: 3
      slope_threshold_z_per_yr: 0.15         # min |slope| in z-units/yr (material size)
      p_threshold: 0.05                      # two-sided t-test significance (df = n-2)

    # --- scope -------------------------------------------------------------
    non_comparable_school_types: [D75, D79, transfer]

    # --- correctness reconciliation (verify/reconcile.py) ------------------
    reconciliation:
      reference_metric_key: g3_composite_pct_l34
      tolerance_abs: 1.0                     # percentage points; nonzero allows for
                                             # cross-publisher rounding differences
      reference_sources: [manual_csv]        # add socrata / cached_file once configured
      sample:
        size: 25
        stratify_by: [borough, admission_bucket]
        always_include_flagged: true         # every flagged outlier is checked
        seed: 12345

    notes: >
      2023 NextGen standards reset; trends within-regime only. Composite sampling SE is
      approximated by treating the mean proficiency as a single proportion on g3_tested_n.