Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/education-data-source-pseo

education-data-source-pseo

Unverified

PSEO — Census data linking graduates to employment via LEHD wage records. Earnings percentiles at 1/5/10 years post-graduation by institution, degree, and CIP. Use for graduate earnings analysis. Coverage changes by release; Census V4.14.1 (2026Q2, posted 2026-08-25) lists 1,117 institution rows and partners in 37 states plus D.C. (plus online-only WGU).

PSEO Data Source Reference

Postsecondary Employment Outcomes (PSEO) — Census Bureau experimental statistics linking college graduates to employment outcomes via UI wage records (LEHD program). Covers earnings (25th/50th/75th percentile, measured 1, 5, and 10 years post-graduation) and employment flows by institution, degree level, and CIP field. Use when comparing graduate earnings across programs or institutions, analyzing industry entry patterns, or studying geographic migration of graduates. Coverage is partner-based and changes by release; Census V4.14.1 (2026Q2, posted 2026-08-25) contains 1,117 institution rows and partners in 37 states plus the District of Columbia (plus online-only WGU); the prior release V4.13.0 (2025Q4) listed 952 institutions and 32 states plus D.C.

Postsecondary Employment Outcomes (PSEO) is an experimental data product from the U.S. Census Bureau that links college graduate records to national employment data, providing earnings and employment outcomes by institution, degree level, and field of study.

CRITICAL: Value Encoding

This document describes Education Data Portal integer encodings, which differ from Census API string codes. The Portal converts categorical variables to integers for consistency.

ContextBaccalaureateAssociatesMastersCensus Division Pacific
Portal (integers)5379
Census API (strings)0503079

Key differences: Degree level uses simple integers (1-10), not Census string codes (01-08, 17, 18 per the LEHD public-use schema). CIP codes are 2-digit integers (11 for Computer Science), not strings like "11.01".

See ./references/variable-definitions.md for complete encoding tables.

What is PSEO?

  • Producer: U.S. Census Bureau, LEHD program (Longitudinal Employer-Household Dynamics)
  • Coverage: Partner-based and release-specific; V4.14.1 (2026Q2) contains 1,117 institution rows and partners in 37 states plus D.C., including Western Governors University (online-only); the prior release V4.13.0 (2025Q4) listed 952 institutions and 32 states plus D.C.
  • Content: Links university transcript data with national UI wage records to track graduate employment outcomes
  • Two data types: Graduate Earnings (percentile earnings) and Employment Flows (industry/geography)
  • Frequency: Updated periodically; cohorts span 3-year (Bachelor's) or 5-year (all others) windows; verify the latest institution, partner, and version files before reporting coverage
  • Primary identifiers: unitid (IPEDS Unit ID, integer), opeid (dtype differs by shard on the pinned mirror vintage, Portal v0.26.1: in pseo/colleges_pseo_2001 through _2018 an 8-character string with leading zeros, e.g. "00182600", occasionally with a letter, e.g. "0033290W" (both examples carry unitid -1 in the 2018 shard, so a unitid join drops them); in _2019 through _2021 an Int64 with the leading zeros dropped, e.g. 365800)
  • Privacy method: Differential privacy mechanisms protect individual data
  • Available through: Education Data Portal mirrors (restructured from Census Bureau LEHD format with integer encodings and lowercase variable names)

Reference File Structure

FilePurposeWhen to Read
lehd-methodology.mdHow LEHD produces tabulations, data matching processUnderstanding data creation
earnings-data.mdPercentile earnings, cohort definitions, labor attachmentAnalyzing graduate earnings
geographic-flows.mdWhere graduates work by Census DivisionStudying migration patterns
industry-flows.mdWhat industries graduates enter by NAICS sectorCareer pathway analysis
variable-definitions.mdAll variables, codes, and status flagsBuilding queries or interpreting values
state-coverage.mdParticipating states, coverage rates, data partnersUnderstanding limitations

Decision Trees

What type of outcome am I researching?

Graduate outcomes research?
├─ Earnings by program/institution
│   ├─ Median earnings → `p50_earnings` column, filter by `years_after_grad`
│   ├─ Earnings distribution → `p25_earnings`/`p50_earnings`/`p75_earnings`
│   └─ See ./references/earnings-data.md
├─ Where graduates work (geography)
│   ├─ Census Division of employment → `census_division` column
│   ├─ In-state vs out-of-state → `employed_instate_grads_count`
│   └─ See ./references/geographic-flows.md
├─ What industries graduates enter
│   ├─ NAICS sector employment → `industry` column (String)
│   └─ See ./references/industry-flows.md
└─ How many graduates are employed
    ├─ Employment counts → `employed_grads_count_f`
    ├─ Non-employed/marginal → `jobless_m_emp_grads_count`
    └─ See ./references/variable-definitions.md

What degree level am I researching?

Degree level?
├─ Certificate (<1 year) → degree_level=1
├─ Certificate (1-2 years) → degree_level=2
├─ Certificate (2-4 years) → degree_level=4
├─ Associate's → degree_level=3
├─ Bachelor's → degree_level=5 (default, 3-year cohorts)
├─ Post-Bacc Certificate → degree_level=6
├─ Master's → degree_level=7 (2-digit CIP only)
├─ Post-Masters Certificate → degree_level=8
├─ Doctoral-Research → degree_level=9 (2-digit CIP only)
└─ Doctoral-Professional Practice → degree_level=10

Note: Portal uses integers 1-10. Census Bureau source data uses string codes 01-08, 17 (Doctoral - Research/Scholarship) and 18 (Doctoral - Professional Practice) per the LEHD public-use schema -- these do not appear in Portal data.

Is my institution/state covered?

Checking data availability?
├─ Current participating partners/institutions → Check Census latest-release files
├─ Release-specific coverage context → ./references/state-coverage.md
├─ Portal-covered institution/cohort rows → Check the mirror data actually used
└─ Why data might be missing
    ├─ Institution not partnered
    ├─ Cell suppressed (count < 30)
    └─ Insufficient labor force attachment

Quick Reference: PSEO Variables

Earnings Variables

Portal VariableDescription
p25_earnings25th percentile earnings (2022 dollars)
p50_earningsMedian earnings (2022 dollars)
p75_earnings75th percentile earnings (2022 dollars)
years_after_gradYears post-graduation: 1, 5, or 10
employed_grads_count_eGraduate count with earnings data
total_grads_countTotal IPEDS-reported graduates

Flows Variables

Portal VariableDescription
employed_grads_count_fEmployed graduates count
employed_instate_grads_countEmployed in institution's state
jobless_m_emp_grads_countNon-employed or marginally employed
industry2-digit NAICS sector (String, e.g., "54", "31-33")
census_divisionCensus Division of employment (1-9, 99)

Note: Portal uses restructured schema with years_after_grad column instead of Census API's Y1_*/Y5_*/Y10_* naming. The industry column is String type because some NAICS sectors span ranges (e.g., "31-33" for Manufacturing, "44-45" for Retail Trade).

Key Identifiers

IDFormatLevelExampleNotes
unitidIntegerInstitution100751IPEDS Unit ID (University of Alabama)
opeidString (2001-2018 shards) / Int64 (2019-2021 shards)Institution"00105100" / 105100On the pinned mirror vintage: 8-character zero-padded OPEID in the String shards, which may be alphanumeric ("0033290W", Penn State World Campus); the Int64 shards drop leading zeros, so cast to string and zero-pad to 8 before concatenating shards or joining
fipsIntegerState48State of institution (Texas)
cipcode2-digit integerField of study11Computer Science; Portal uses integers, not "11.01"

Key Filters (Portal Integer Encoding)

ParameterDescriptionExample
degree_levelDegree type integer5 (Bachelor's)
pseo_cohortGraduation cohort"2016-2020" or "2019-2021" (string format, full year range)
years_after_gradYears post-graduation1, 5, or 10

Cohort Definitions

Degree LevelCohort YearsExample Cohorts
Bachelor's3-year"2001-2003", "2004-2006", "2007-2009", "2010-2012", "2013-2015", "2016-2018", "2019-2021"
All others5-year"2001-2005", "2006-2010", "2011-2015", "2016-2020"

Missing Data Codes

CodeMeaningWhen Used
-1Missing/not reportedPrimary missing data indicator; very common in earnings and flows columns
-3SuppressedPortal-wide suppression code; in PSEO earnings columns it was not observed (see note)
-2Not applicableItem doesn't apply to this entity (Portal convention)

Note: PSEO data has no null values in the parquet files. All missing/suppressed data uses negative integer codes. Filter with pl.col("p50_earnings") > 0 to get valid earnings, not .is_not_null(). Census suppresses earnings cells with protected counts below 30 (PSEO Technical Documentation), but in the Portal probe checked on 2026-10-19 (UT Austin, year 2016, 690 rows) every unavailable earnings value was -1 and no earnings column was ever -3; -3 appeared only in jobless_m_emp_grads_count on Census-division breakdown rows. Treat any negative earnings value as non-reportable, and do not count suppressed cells with == -3.

Data Access

Datasets for PSEO are available via the Education Data Portal mirror system. See datasets-reference.md for canonical paths, mirrors.yaml for mirror configuration, and fetch-patterns.md for fetch code patterns.

DatasetTypePathCodebook
Earnings and FlowsYearly (2001-2021)pseo/colleges_pseo_{year}pseo/codebook_colleges_pseo

Codebooks are .xls files co-located with data in all mirrors. Use get_codebook_url() from fetch-patterns.md to construct download URLs.

Truth Hierarchy: When interpreting variable values, apply this priority:

  1. Actual data file (what you observe in the parquet/CSV) -- this IS the truth
  2. Live codebook (.xls in mirror) -- authoritative documentation, may lag
  3. This skill documentation -- convenient summary, may drift from codebook

If this documentation contradicts the codebook, trust the codebook. If the codebook contradicts observed data, trust the data and investigate.

Fetching PSEO Data

import polars as pl

# PSEO is a yearly dataset -- fetch individual years
df = fetch_yearly_from_mirrors(
    path_template="pseo/colleges_pseo_{year}",
    years=[2018, 2019, 2020],
)
# opeid is String in the 2018 shard and Int64 in 2019-2021 (pinned mirror vintage);
# the relaxed concat leaves "00365800" next to "365800". Zero-pad to 8 before any join.
df = df.with_columns(pl.col("opeid").cast(pl.String).str.zfill(8))

# Or fetch a single year
df = fetch_from_mirrors("pseo/colleges_pseo_2020")
library(arrow)
library(dplyr)

# fetch_yearly_from_mirrors()/fetch_from_mirrors() are Python helpers; in R,
# build URLs from the mirror root in mirrors.yaml and read directly.
# Mirror failover: see `education-data-query/references/fetch-patterns.md` (R pattern).
config <- yaml::read_yaml("mirrors.yaml")
mirror <- config$mirrors[[1]]

# PSEO is a yearly dataset -- fetch individual years and bind
frames <- list()
# NOTE: illustrative only — mirror parquet files are Polars-written and may
# declare string_view columns, so a plain read can fail under R arrow
# ("cannot handle Array of type <utf8_view>"). Real fetch scripts must use the
# view-safe parquet read from `education-data-query/references/fetch-patterns.md`.
for (y in c(2018, 2019, 2020)) {
  url <- paste0(mirror$root_url, "/", mirror$vintage$hf_revision, "/", "pseo/colleges_pseo_", y, ".", mirror$format)
  # opeid is character in shards 2001-2018 and integer in 2019-2021 (pinned mirror
  # vintage); normalise to an 8-character zero-padded string so the shards bind and join.
  frames[[length(frames) + 1]] <- arrow::read_parquet(url) |>
    mutate(opeid = stringr::str_pad(as.character(opeid), width = 8, pad = "0"))
}
df <- bind_rows(frames)

# Or fetch a single year
url <- paste0(mirror$root_url, "/", mirror$vintage$hf_revision, "/", "pseo/colleges_pseo_2020", ".", mirror$format)
df <- arrow::read_parquet(url)

CRITICAL: Do not stack years without de-duplicating. The Portal repeats each pseo_cohort under every year in its span (verified 2026-10-19 on the live Portal API: UT Austin bachelor's cohort "2016-2018" has identical values under year 2016, 2017 and 2018; year 2018 from probe …_51614bb8.json). After a multi-year fetch, drop year and de-duplicate on all remaining columns (or keep one year per cohort) before aggregating.

Filtering

# Filter by institution
df.filter(pl.col("unitid") == 100751)  # University of Alabama

# Filter by field of study
df.filter(pl.col("cipcode") == 11)  # Computer Science

# Filter by cohort (note: full year range format)
df.filter(pl.col("pseo_cohort") == "2019-2021")

# Earnings rows only (exclude missing/suppressed)
df.filter(pl.col("p50_earnings") > 0)

# Filter by industry (String column, not integer)
df.filter(pl.col("industry") == "54")  # Professional Services
# Filter by institution
df |> filter(unitid == 100751)  # University of Alabama

# Filter by field of study
df |> filter(cipcode == 11)  # Computer Science

# Filter by cohort (note: full year range format)
df |> filter(pseo_cohort == "2019-2021")

# Earnings rows only (exclude missing/suppressed)
df |> filter(p50_earnings > 0)

# Filter by industry (String column, not integer)
df |> filter(industry == "54")  # Professional Services

Additional Access Methods (Census Bureau Source)

  1. PSEO Explorer: Interactive visualization tool at https://lehd.ces.census.gov/applications/pseo/
  2. Census bulk download: CSV/XLS files at https://lehd.ces.census.gov/data/pseo/
  3. Census API: https://api.census.gov/data/timeseries/pseo/earnings and .../flows (uses different variable naming and string codes; requires a Census API key; not used in this system)

Release-Specific Coverage Verification

PSEO participation changes between releases. Before reporting a state, partner, or institution count, inspect the current Census release metadata rather than carrying a fixed historical count forward:

  • Institutions: https://lehd.ces.census.gov/data/pseo/latest_release/all/pseo_all_institutions.csv
  • Partners: https://lehd.ces.census.gov/data/pseo/latest_release/all/pseo_all_partners.txt
  • Version: https://lehd.ces.census.gov/data/pseo/latest_release/all/version_pseo.txt

As verified on 2026-10-19, version V4.14.1 (2026Q2) lists 1,117 institution rows and partners in 37 states plus D.C.; the prior release V4.13.0 (2025Q4) listed 952 institutions and 32 states plus D.C. This release-specific roster does not establish a national percentage of all graduates. The Portal mirror remains a fixed 2001–2021 snapshot; distinguish its observed rows from the current Census release roster.

Common Pitfalls

PitfallIssueSolution
Using Census string codesPortal uses integers (e.g., 5 for Bachelor's), not Census strings ("05")Always check encoding; see variable-definitions.md
Ignoring suppressionCells with <30 graduates are suppressed; missing data looks like no program existsCheck total_grads_count to confirm cell exists; negative-coded earnings (observed as -1) may mean suppression
Cross-institution comparison without controlling degree/CIPInstitutions offer different program mixes; aggregate comparison is misleadingAlways filter to same degree_level and cipcode when comparing institutions
Treating PSEO as comprehensiveParticipation is voluntary and changes by release; no verified national graduate-coverage percentage is documented hereReport the release/version and partner roster used; acknowledge selection bias and do not generalize to all U.S. graduates
Ignoring labor attachmentGraduates need annual earnings above a full-time minimum-wage equivalent (35 h × 50 wk) AND at least 3 quarters of non-zero earnings to appear in earnings dataSome graduates are employed but excluded; note this limitation
Assuming one dtype for Portal opeidOn the pinned mirror vintage (Portal v0.26.1), PSEO shards 2001-2018 store opeid as an 8-character string ("00182600"; the 2018 shard has one alphanumeric value, "0033290W") and shards 2019-2021 as Int64 (365800); a multi-year concat fails or mixes forms, and an integer cast fails on lettersIn every shard, cast to string and zero-pad to 8 before concatenating or joining: Python pl.col("opeid").cast(pl.String).str.zfill(8), R stringr::str_pad(as.character(opeid), width = 8, pad = "0"); zero-pad other sources' OPEIDs the same way
Mixing cohort spansBachelor's uses 3-year cohorts; all others use 5-yearFilter by degree_level first, then verify cohort format matches
Assuming inflation comparabilityAll earnings are in 2022 CPI-U dollarsNo manual inflation adjustment needed; values are already real dollars (Portal snapshot; current Census PSEO releases since V4.13.0 are in 2023 dollars — do not mix sources without re-deflating)

PSEO vs Other Data Sources

FeaturePSEOCollege ScorecardState Systems
CoverageGraduates onlyFederally aided students (entry cohorts incl. non-completers in institution files; completers in field-of-study files)Graduates only
Geographic scopeNational (cross-state)NationalIn-state only
SampleAll graduates from partnersFederal aid recipientsAll graduates
Earnings detail25th/50th/75th percentilePercentiles (10th–90th per Census PSEO tech doc)Varies
Industry dataYes (NAICS sector)NoVaries
Geographic flowsYes (Census Division)NoNo
Privacy methodDifferential privacy (noise on earnings histograms and flows counts) plus suppression of earnings cells with protected count < 30Differential-privacy noise on earnings counts/medians plus PS suppressionVaries

Common Use Cases

Use CaseData NeededKey Considerations
Compare programs within institutionEarnings by CIPCODECheck cell counts for suppression
Compare institutions for same programEarnings by INSTITUTIONEnsure same degree level and CIP
Analyze brain drain/retentionFlows by division + in-stateOnly 9 Census Divisions
Career pathway analysisFlows by NAICS sector2-digit NAICS only
ROI by degree levelEarnings across DEGREE_LEVELDifferent cohort spans

Important Limitations

  1. Experimental status: Not official Census statistics; methodology may change
  2. Partial, changing coverage: Partner and institution participation varies by Census release; V4.14.1 (2026Q2) lists 1,117 institution rows and partners in 37 states plus D.C. (prior release V4.13.0: 952 institutions, 32 states plus D.C.), but no verified national graduate-coverage percentage is asserted here
  3. Selection bias: Participating states/institutions may differ systematically
  4. Employment coverage: Excludes self-employed, independent contractors, military, some federal
  5. Labor attachment requirement: Graduates need annual earnings above a full-time minimum-wage equivalent (35 h × 50 wk) AND at least 3 quarters of non-zero earnings
  6. Suppression: Earnings cells with fewer than 30 graduates (protected count) are suppressed; flows counts are noise-infused rather than suppressed by a fixed <30 rule
  7. Earnings inflation-adjusted: All earnings in 2022 dollars (CPI-U) in the Portal snapshot; current Census PSEO releases since V4.13.0 are in 2023 dollars

Related Data Sources

SourceRelationshipWhen to Use
education-data-source-scorecardAlternative earnings source (Title IV aid recipients; IRS/Treasury earnings)When PSEO coverage is insufficient or need non-graduate outcomes
education-data-source-ipedsInstitution characteristics, enrollment, graduation ratesContextualizing PSEO institutions; join on unitid
education-data-explorerParent discovery skillRouting questions to mirror dataset files
education-data-queryData fetchingDownloading parquet/CSV files

Topic Index

TopicReference File
LEHD program overview./references/lehd-methodology.md
Data matching process./references/lehd-methodology.md
Differential privacy./references/lehd-methodology.md
Percentile earnings./references/earnings-data.md
Labor force attachment./references/earnings-data.md
Cohort definitions./references/earnings-data.md
Census Division employment./references/geographic-flows.md
In-state employment./references/geographic-flows.md
NAICS sector employment./references/industry-flows.md
Industry code reference./references/industry-flows.md
Variable names and codes./references/variable-definitions.md
Status flags./references/variable-definitions.md
State participation./references/state-coverage.md
Coverage rates./references/state-coverage.md
Data partners./references/state-coverage.md
Mirror-based data downloadData Access section above
Bulk data downloadData Access section above
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall