TDOE#230: Refactor Student Disability Models.

[AngelicaLastra]

Warning

This PR results in breaking changes. Any implementation using the newest version of this package would be required to generate a xwalk_disability_designations csv seed (even if empty).
This PR also requires the companion edu_edfi_source PR#190 to be released before this PR can run cleanly.

Description & motivation

This PR is a subset of TN'S edu_wh PR #230, it introduces fct_student_disability, a new fact table that unifies student disabilities from two Ed-Fi sources: StudentEducationOrganizationAssociation.Disabilities (ed org level) and StudentSpecialEducationProgramAssociation.Disabilities (program level).

Main highlights:

• Two build intermediates models, bld_ef3__student__disabilities and bld_ef3__student__wide_disability_designations, handle stacking and designation pivoting for student disability models before the final fact model's further transformations.
• The fct_student_disability table covers two distinct grains in a single place. An is_program boolean flag, makes it easier to distinguish program-level from ed org-level rows without null-checking k_program.
• k_student_program is surfaced as a primary key for program rows and joins to program association fact tables, in anticipation of PR#249.
• Disability designation descriptors are pivoted into boolean indicator columns through a xwalk_disability_designations, using the same ea_pivot + accordion_columns pattern used elsewhere in the warehouse.

PR Merge Priority:

• Low
• Medium
• High

New files created:

Build models:

• bld_ef3__student__disabilities:

  • Stacks stg_ef3__stu_ed_org__disabilities (always included) and stg_ef3__stu_spec_ed__disabilities (gated on src:program:special_ed:enabled) using dbt_utils.union_relations.
  • Derives is_program and carries k_student_program forward for downstream use.
  • Generates the k_student_disability surrogate key here so the wide designation model can carry it forward and the final fact join reduces to a single join on that key.

• bld_ef3__student__wide_disability_designations:

  • Flattens v_designations using outer=true so disability records with no designations are preserved as all-false rows rather than being dropped.
  • Pivots the descriptor values into boolean columns via ea_pivot against xwalk_disability_designations. The pivot block is skipped entirely when the crosswalk is empty via the is_empty_model().

Warehouse model:

• fct_student_disability:

  • Joins bld_ef3__student__disabilities to dim_student and left joins to bld_ef3__student__wide_disability_designations for designation indicator columns.
  • The surrogate key k_student_disability is built from tenant_code, school_year, k_student, k_lea, k_school, k_program, program_enroll_begin_date, and disability_type.
  • Designation columns are pulled in via accordion_columns, allowing stadium implementations to extend them through xwalk_disability_designations without modifying this model.

• fct_student_disability.yml:

  • Full documentation including overview, primary key description, business rules (covering the dual grain and null behavior of k_program/k_student_program for ed org rows), and a join example. No enabled gate is set at the fact level since the build models already handle conditional sourcing, and ed org disabilities do not depend on src:program:special_ed:enabled.

Changes to existing files:

• _edfi_3__students.yml: Added docs for bld_ef3__student__disabilities and bld_ef3__student__wide_disability_designations with tags: ['special_ed']. Neither carries an enabled gate since the build models handle conditional sourcing internally.

Changes applied in review:

• Removed ed_org_id from all models. It is fully recoverable from k_lea and k_school, which are already included, consistent with the approach taken in PR#249.
• Added k_student_program to bld_ef3__student__disabilities and fct_student_disability.
• Added is_program (k_program is not null) to bld_ef3__student__disabilities.
• Added disability_type to the k_student_disability surrogate key. The original key was built from (tenant_code, school_year, k_student, k_lea, k_school, k_program, ed_org_id, program_enroll_begin_date), which would produce duplicate surrogate keys for students with multiple disabilities under the same program enrollment.
• Updated table aliases in fct_student_disability to use full CTE names rather than short aliases (sd, stu), matching the repo convention.
• Moved k_student_disability surrogate key generation into bld_ef3__student__disabilities so it flows through bld_ef3__student__wide_disability_designations. The original join in fct_student_disability needed a six-condition null-safe match across k_student, k_lea, k_school, k_program, tenant_code, school_year, and disability_type; it now joins on k_student_disability alone.
• Various formatting fixes: join --> inner join, missing space in --Ed Org Disabilities.

Tests and QC done:

• dbt compile clean against local edu_edfi_source development branch
• dbt run --select +fct_student_disability+ passes
• Row counts verified across ed org and program disability rows