apiVersion: v3.1.0
kind: DataContract
id: education.graduation_rate_4_year_cohort
name: graduation_rate_4_year_cohort
version: 1.0.0
status: active
domain: education
tenant: georgia-public-data
description:
  purpose: Four-year high-school graduation rate for Georgia public schools, with official district and
    state rollups, by demographic subgroup (race/ethnicity, gender, disability status, English proficiency,
    economic status, and special populations). Reports the graduation rate, the number of graduates, and
    the cohort size. Published by GOSA for school years 2003-04 through 2023-24. 2011 onward is the federal
    four-year adjusted-cohort graduation rate (ACGR); 2004-2010 predate Georgia's ACGR adoption and use
    the state's earlier leaver-based methodology — the two halves are not trend-comparable (see limitations).
    This is the long historical 4-year series with demographic breakdowns; the sibling ccrpi_graduation_rate
    topic carries the GaDOE CCRPI release (2012 onward, 4- and 5-year rates with CCRPI target/flag context).
  usage: Star-schema fact table. Join the districts dimension on district_code; the schools dimension
    on district_code + school_code; the demographics dimension on demographic. Read directly with DuckDB
    over Parquet.
  limitations: 2004-2010 figures predate Georgia's adoption of the federal four-year adjusted-cohort methodology
    (ACGR, first reported 2011) and use the state's earlier leaver-based rate; the 2010->2011 state rate
    drop (~81% to ~67%) is a methodology break, not a real decline — do not trend across it. Suppressed
    cells are NULL (not zero) from 2010 onward, but 2004-2009 sources use literal ZEROS for suppressed
    cells — a zero rate/count in those years may be real or suppressed and cannot be distinguished; treat
    very small cohorts in 2004-2009 with caution. num_cohort is NULL for every row in 2012-2016 (the source
    publishes no denominator in those years). School rows do not always sum to the published district
    row (49 of ~3,850 district-years publish a district num_graduates below the visible school sum, source-published,
    e.g. 2016 Whitfield 709 vs 810) — use the official district/state rows for rollups rather than summing
    school rows. The race axis uses the combined asian_pacific_islander bucket — not comparable row-for-row
    with split-convention topics without aggregating those topics' asian + pacific_islander rows at query
    time. State rows have NULL district_code and school_code; district rows have NULL school_code.
tags:
- education
- governor's office of student achievement
- graduation_rate_4_year_cohort
servers:
- server: s3_gold
  type: s3
  location: s3://georgia-data-gold/education/graduation_rate_4_year_cohort/**/*.parquet
  format: parquet
- server: local_gold
  type: local
  path: data/gold/education/graduation_rate_4_year_cohort/**/*.parquet
  format: parquet
schema:
- name: graduation_rate_4_year_cohort
  logicalType: object
  physicalType: parquet
  physicalName: graduation_rate_4_year_cohort
  description: graduation_rate_4_year_cohort fact table, year-partitioned Parquet (split by detail level
    where present).
  dataGranularityDescription: One row per year, district_code, school_code, demographic (geography columns
    are NULL at higher aggregation levels).
  customProperties:
  - property: sub_topic
    value: gosa
  - property: detail_levels
    value:
    - schools
    - districts
    - states
  - property: default_detail
    value: schools
  - property: grain
    value:
    - year
    - district_code
    - school_code
    - demographic
  - property: key_metric
    value: graduation_rate
  - property: null_semantics
    value:
      suppressed_to_null: true
      zero_is_real: true
  - property: partition_columns
    value:
    - year
  - property: path_template
    value: education/graduation_rate_4_year_cohort/year={year}/{detail}.parquet
  - property: foreign_keys
    value:
    - column: district_code
      target_object: districts
      target_columns:
      - district_code
      attribute_columns:
      - district_name
      - district_census_id
      - district_type
      scope: domain
    - column: school_code
      target_object: schools
      target_columns:
      - district_code
      - school_code
      attribute_columns:
      - school_name
      scope: domain
    - column: demographic
      target_object: demographics
      target_columns:
      - demographic
      attribute_columns:
      - demographic_label
      - demographic_category
      scope: global
  - property: example_queries
    value:
    - description: Latest year (2024), schools detail
      query: SELECT * FROM graduation_rate_4_year_cohort WHERE year = 2024 LIMIT 100
    - description: District 601 in 2024
      query: SELECT * FROM graduation_rate_4_year_cohort WHERE district_code = '601' AND year = 2024 LIMIT
        100
  properties:
  - name: year
    logicalType: integer
    physicalType: int
    required: true
    description: Ending (spring) calendar year of the cohort's graduating school year (2024 = the 2023-24
      cohort). Parsed from the source's LONG_SCHOOL_YEAR and cross-checked against the filename for 2011-2024;
      from the filename for 2004-2010 (no year column in those eras).
    examples:
    - 2024
    customProperties:
    - property: column_role
      value: year
    - property: label
      value: Year
    primaryKey: true
    primaryKeyPosition: 1
  - name: district_code
    logicalType: string
    physicalType: string
    required: false
    description: 'GOSA district code (FK to districts dimension): 3-digit zero-padded county/city codes
      or 7-digit state-charter codes. Code 799 is the state-school virtual district (''State Schools''),
      published as a district-level aggregate in 2004-2010. NULL on state-level rows.'
    examples:
    - '601'
    relationships:
    - to: districts.district_code
    customProperties:
    - property: column_role
      value: fk_district
    - property: label
      value: District Code
    primaryKey: true
    primaryKeyPosition: 2
  - name: school_code
    logicalType: string
    physicalType: string
    required: false
    description: GOSA school code, zero-padded to 4 characters (composite FK to schools dimension with
      district_code; not globally unique on its own). NULL on district- and state-level rows.
    examples:
    - '0103'
    relationships:
    - to: schools.district_code
    - to: schools.school_code
    customProperties:
    - property: column_role
      value: fk_school
    - property: label
      value: School Code
    primaryKey: true
    primaryKeyPosition: 3
  - name: demographic
    logicalType: string
    physicalType: string
    required: true
    description: 'Demographic subgroup (FK to the global demographics dimension). Race buckets use the
      combined asian_pacific_islander key (pre-1997 OMB convention) in every year: 2011+ bronze publishes
      the explicit ''Asian/Pacific Islander'' label, and the bare ''Asian'' label of 2004-2010 is the
      same combined bucket — the six race-bucket counts sum exactly to the All Students totals at the
      state level in every year, so Pacific Islanders are folded in, never published separately. 2004-2017
      publish 15 subgroups; active_duty, foster_care, and homeless appear from 2018; english_learners
      is absent in 2021 only. ''all'' is the unfiltered total and overlaps every other value; subgroups
      are mutually exclusive only within their own category (race, gender, disability, economic, special
      population).'
    examples:
    - 'all'
    relationships:
    - to: demographics.demographic
    enum:
    - 'active_duty'
    - 'all'
    - 'asian_pacific_islander'
    - 'black'
    - 'economically_disadvantaged'
    - 'english_learners'
    - 'female'
    - 'foster_care'
    - 'hispanic'
    - 'homeless'
    - 'male'
    - 'migrant'
    - 'multiracial'
    - 'native_american'
    - 'not_economically_disadvantaged'
    - 'students_with_disabilities'
    - 'students_without_disabilities'
    - 'white'
    customProperties:
    - property: column_role
      value: fk_demographic
    - property: label
      value: Demographic
    - property: short_description
      value: Student subgroup the row reports (race/ethnicity, gender, disability, economic status, special
        population); 'all' is the total.
    - property: has_total
      value: true
    - property: total_value
      value: 'all'
    - property: key_metric_grain_contributor
      value: true
    primaryKey: true
    primaryKeyPosition: 4
  - name: num_graduates
    logicalType: integer
    physicalType: bigint
    required: false
    description: Number of students in the subgroup's cohort who graduated with a regular diploma within
      four years of first entering 9th grade (from 2011 the federal adjusted-cohort numerator; 2004-2010
      use the state's earlier leaver-based accounting). Published values are >= 10 from 2011 onward (GOSA's
      n=10 reporting threshold). 2004-2009 use literal zeros for suppressed cells — a zero in those years
      may be real or suppressed and the two cannot be distinguished in source. The three non-suppressed
      2010 migrant rows are internally inconsistent in bronze (num_graduates = num_cohort yet graduation_rate
      != 1.0; graduation_rate is the authoritative figure) and are preserved as published.
    examples:
    - 225
    customProperties:
    - property: column_role
      value: metric
    - property: label
      value: Number Graduates
    - property: unit
      value: count
    - property: null_meaning
      value: Suppressed by GOSA ('Too few Students' literals in 2010, blank cells 2011-2020, TFS literals
        2021-2024). 2004-2009 have no suppression NULLs — those sources publish literal zeros instead.
        Always co-suppressed with graduation_rate.
    - property: metric_component
      value: numerator
  - name: num_cohort
    logicalType: integer
    physicalType: bigint
    required: false
    description: Cohort size — the denominator of the graduation rate. From 2011 this is the federal adjusted
      four-year cohort (first-time 9th-graders four years prior, plus transfers in, minus transfers out);
      the 2004-2010 denominator is the source's 'Approximate Class Size' (pre-ACGR leaver-based methodology).
      NULL for ALL rows in 2012-2016 (the source does not publish TOTAL_COUNT in those years; consumers
      may estimate round(num_graduates / graduation_rate) at their own rounding risk). In 2023-2024 some
      rows — mostly school-level (295 school / 74 district in 2023, 271 / 68 in 2024) — publish num_cohort
      while num_graduates and graduation_rate are suppressed (partial suppression). Published values are
      >= 10 from 2011 onward. 2004-2009 zeros may be real or suppressed (see num_graduates).
    examples:
    - 240
    customProperties:
    - property: column_role
      value: metric
    - property: label
      value: Number Cohort
    - property: unit
      value: count
    - property: null_meaning
      value: 'Suppressed by GOSA, or unpublished: the source has no cohort denominator at all for 2012-2016.'
    - property: metric_component
      value: denominator
  - name: graduation_rate
    logicalType: number
    physicalType: double
    required: false
    description: 'Four-year graduation rate as a proportion (0-1 scale): num_graduates divided by num_cohort.
      From 2011 this is the federal adjusted-cohort rate (ACGR); 2004-2010 use Georgia''s earlier leaver-based
      methodology and are NOT trend-comparable with 2011+ (state rate breaks 0.808 -> 0.675 at the 2010->2011
      boundary). The source publishes 0-100 percentages (1-2 decimal places); divided by 100. Reconciles
      with num_graduates / num_cohort within 0.001 everywhere except the three documented 2010 migrant
      defect rows. Zeros in 2004-2009 may be real or suppressed (see num_graduates).'
    examples:
    - 0.9375
    customProperties:
    - property: column_role
      value: metric
    - property: label
      value: Graduation Rate
    - property: short_description
      value: Share of the four-year cohort that graduated, on a 0-1 scale; 2011+ is the federal ACGR,
        2004-2010 a non-comparable older method.
    - property: unit
      value: proportion
    - property: null_meaning
      value: Suppressed by GOSA ('Too few Students' literals in 2010, blank cells 2011-2020, TFS literals
        2021-2024). 2004-2009 have no suppression NULLs — those sources publish literal zeros instead.
        Always co-suppressed with num_graduates.
    - property: key_metric
      value: true
  quality:
  - type: sql
    name: non_empty
    description: The dataset has at least one row.
    dimension: completeness
    query: SELECT COUNT(*) FROM {object}
    mustBeGreaterThan: 0
  - type: sql
    name: demographic_in_allowed_values
    description: demographic is one of the 18 canonical codes.
    dimension: conformity
    query: SELECT COUNT(*) FROM {object} WHERE demographic IS NOT NULL AND demographic NOT IN ('active_duty',
      'all', 'asian_pacific_islander', 'black', 'economically_disadvantaged', 'english_learners', 'female',
      'foster_care', 'hispanic', 'homeless', 'male', 'migrant', 'multiracial', 'native_american', 'not_economically_disadvantaged',
      'students_with_disabilities', 'students_without_disabilities', 'white')
    mustBe: 0
  - type: sql
    name: num_graduates_non_negative
    description: num_graduates is a count (>= 0).
    dimension: accuracy
    query: SELECT COUNT(*) FROM {object} WHERE num_graduates IS NOT NULL AND num_graduates < 0
    mustBe: 0
  - type: sql
    name: num_cohort_non_negative
    description: num_cohort is a count (>= 0).
    dimension: accuracy
    query: SELECT COUNT(*) FROM {object} WHERE num_cohort IS NOT NULL AND num_cohort < 0
    mustBe: 0
  - type: sql
    name: graduation_rate_within_unit_interval
    description: graduation_rate is a bounded proportion on the [0, 1] scale.
    dimension: accuracy
    query: SELECT COUNT(*) FROM {object} WHERE graduation_rate IS NOT NULL AND (graduation_rate < 0 OR
      graduation_rate > 1)
    mustBe: 0
  - type: sql
    name: num_graduates_not_exceeding_num_cohort
    description: The four-year adjusted-cohort numerator (num_graduates) never exceeds its denominator
      (num_cohort) where both are present. Verified 0 violations across all bronze years 2004-2024.
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE num_graduates IS NOT NULL AND num_cohort IS NOT NULL AND
      num_graduates > num_cohort
    mustBe: 0
  - type: sql
    name: graduation_rate_reconciles_with_counts
    description: Where rate, count, and cohort are all present and the cohort is positive, the published
      rate equals num_graduates / num_cohort within 0.001 (the source rounds the percent to 1-2 decimals;
      measured max legitimate deviation 0.0005). Excludes the three documented 2010 migrant defect rows
      (year=2010 AND demographic='migrant'), the only violations in any year — see notes.
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE graduation_rate IS NOT NULL AND num_graduates IS NOT NULL
      AND num_cohort IS NOT NULL AND num_cohort > 0 AND NOT (year = 2010 AND demographic = 'migrant')
      AND ABS(graduation_rate - (CAST(num_graduates AS DOUBLE) / num_cohort)) > 0.001
    mustBe: 0
  - type: sql
    name: num_graduates_and_rate_co_suppressed
    description: 'GOSA suppresses num_graduates and graduation_rate together in every era: no row may
      have exactly one of the two missing (verified across all 21 bronze files). num_cohort is exempt
      — 2023-2024 publish it on partially suppressed rows and 2012-2016 omit it.'
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE (num_graduates IS NULL) <> (graduation_rate IS NULL)
    mustBe: 0
  - type: sql
    name: num_cohort_unpublished_2012_2016
    description: 'The source publishes no cohort denominator (TOTAL_COUNT) in 2012-2016, and the transform
      does not derive one from the rounded rate: num_cohort must be NULL on every row in those years.'
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE year BETWEEN 2012 AND 2016 AND num_cohort IS NOT NULL
    mustBe: 0
  - type: sql
    name: state_race_partition_sums_to_all
    description: 'At the state level the six mutually exclusive race buckets partition the graduating
      cohort: their num_graduates values sum exactly to the ''all'' total in every year (the §5b math
      test proving the combined Asian/Pacific Islander convention; verified 2004-2024). State race rows
      are never suppressed.'
    dimension: consistency
    query: SELECT COUNT(*) FROM (SELECT year FROM {object} WHERE district_code IS NULL AND school_code
      IS NULL GROUP BY year HAVING SUM(CASE WHEN demographic IN ('asian_pacific_islander', 'black', 'hispanic',
      'multiracial', 'native_american', 'white') THEN num_graduates ELSE 0 END) <> MAX(CASE WHEN demographic
      = 'all' THEN num_graduates END)) AS bad_years
    mustBe: 0
  - type: sql
    name: state_gender_partition_sums_to_all
    description: At the state level male + female num_graduates sums exactly to the 'all' total in every
      year (verified 2004-2024; state gender rows are never suppressed).
    dimension: consistency
    query: SELECT COUNT(*) FROM (SELECT year FROM {object} WHERE district_code IS NULL AND school_code
      IS NULL GROUP BY year HAVING SUM(CASE WHEN demographic IN ('male', 'female') THEN num_graduates
      ELSE 0 END) <> MAX(CASE WHEN demographic = 'all' THEN num_graduates END)) AS bad_years
    mustBe: 0
  - type: sql
    name: published_counts_meet_reporting_threshold_2011_on
    description: 'From 2011 onward every published num_graduates and num_cohort is >= 10 — GOSA''s n=10
      cell-size suppression threshold (verified per file). A smaller value means a suppression regression
      or column swap. 2004-2010 are exempt: the wide eras publish sub-threshold values (including suppression
      zeros).'
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE year >= 2011 AND ((num_graduates IS NOT NULL AND num_graduates
      < 10) OR (num_cohort IS NOT NULL AND num_cohort < 10))
    mustBe: 0
  - type: sql
    name: expanded_subgroups_absent_before_2018
    description: 'Active Duty, Foster, and Homeless first appear in the 2018 file: no active_duty / foster_care
      / homeless rows may exist before 2018.'
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE year < 2018 AND demographic IN ('active_duty', 'foster_care',
      'homeless')
    mustBe: 0
  - type: sql
    name: english_learners_absent_2021
    description: 'The 2021 file drops the Limited English Proficient subgroup (present in every other
      year 2004-2024): no english_learners rows may exist in 2021.'
    dimension: consistency
    query: SELECT COUNT(*) FROM {object} WHERE year = 2021 AND demographic = 'english_learners'
    mustBe: 0
customProperties:
- property: title
  value: Four-Year Cohort Graduation Rate
- property: summary
  value: Share of the four-year high school cohort that graduated, by school, district, and state and
    demographic subgroup, 2004-2024.
- property: source
  value: Governor's Office of Student Achievement (GOSA)
- property: source_url
  value: https://gosa.georgia.gov/dashboards-data-report-card/downloadable-data
- property: update_frequency
  value: annual
- property: year_range
  value: 2004-2024
- property: schema_hash
  value: d58fde7781dfaec406fb52e58bc8fafc339d6eaac0cb222f1d580e3a1010e568
- property: available_years
  value:
  - 2004
  - 2005
  - 2006
  - 2007
  - 2008
  - 2009
  - 2010
  - 2011
  - 2012
  - 2013
  - 2014
  - 2015
  - 2016
  - 2017
  - 2018
  - 2019
  - 2020
  - 2021
  - 2022
  - 2023
  - 2024
- property: year_gaps
  value: []
