DAAF-Contribution-Community/daaf / .claude/skills/education-data-source-pseo
education-data-source-pseo
UnverifiedPSEO — 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.
Context Baccalaureate Associates Masters Census Division Pacific Portal (integers) 5379Census API (strings) 0503079Key differences: Degree level uses simple integers (1-10), not Census string codes (
01-08,17,18per the LEHD public-use schema). CIP codes are 2-digit integers (11 for Computer Science), not strings like "11.01".See
./references/variable-definitions.mdfor 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: inpseo/colleges_pseo_2001through_2018an 8-character string with leading zeros, e.g."00182600", occasionally with a letter, e.g."0033290W"(both examples carryunitid-1 in the 2018 shard, so a unitid join drops them); in_2019through_2021an 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
| File | Purpose | When to Read |
|---|---|---|
lehd-methodology.md | How LEHD produces tabulations, data matching process | Understanding data creation |
earnings-data.md | Percentile earnings, cohort definitions, labor attachment | Analyzing graduate earnings |
geographic-flows.md | Where graduates work by Census Division | Studying migration patterns |
industry-flows.md | What industries graduates enter by NAICS sector | Career pathway analysis |
variable-definitions.md | All variables, codes, and status flags | Building queries or interpreting values |
state-coverage.md | Participating states, coverage rates, data partners | Understanding 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) and18(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 Variable | Description |
|---|---|
p25_earnings | 25th percentile earnings (2022 dollars) |
p50_earnings | Median earnings (2022 dollars) |
p75_earnings | 75th percentile earnings (2022 dollars) |
years_after_grad | Years post-graduation: 1, 5, or 10 |
employed_grads_count_e | Graduate count with earnings data |
total_grads_count | Total IPEDS-reported graduates |
Flows Variables
| Portal Variable | Description |
|---|---|
employed_grads_count_f | Employed graduates count |
employed_instate_grads_count | Employed in institution's state |
jobless_m_emp_grads_count | Non-employed or marginally employed |
industry | 2-digit NAICS sector (String, e.g., "54", "31-33") |
census_division | Census Division of employment (1-9, 99) |
Note: Portal uses restructured schema with
years_after_gradcolumn instead of Census API'sY1_*/Y5_*/Y10_*naming. Theindustrycolumn is String type because some NAICS sectors span ranges (e.g.,"31-33"for Manufacturing,"44-45"for Retail Trade).
Key Identifiers
| ID | Format | Level | Example | Notes |
|---|---|---|---|---|
unitid | Integer | Institution | 100751 | IPEDS Unit ID (University of Alabama) |
opeid | String (2001-2018 shards) / Int64 (2019-2021 shards) | Institution | "00105100" / 105100 | On 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 |
fips | Integer | State | 48 | State of institution (Texas) |
cipcode | 2-digit integer | Field of study | 11 | Computer Science; Portal uses integers, not "11.01" |
Key Filters (Portal Integer Encoding)
| Parameter | Description | Example |
|---|---|---|
degree_level | Degree type integer | 5 (Bachelor's) |
pseo_cohort | Graduation cohort | "2016-2020" or "2019-2021" (string format, full year range) |
years_after_grad | Years post-graduation | 1, 5, or 10 |
Cohort Definitions
| Degree Level | Cohort Years | Example Cohorts |
|---|---|---|
| Bachelor's | 3-year | "2001-2003", "2004-2006", "2007-2009", "2010-2012", "2013-2015", "2016-2018", "2019-2021" |
| All others | 5-year | "2001-2005", "2006-2010", "2011-2015", "2016-2020" |
Missing Data Codes
| Code | Meaning | When Used |
|---|---|---|
-1 | Missing/not reported | Primary missing data indicator; very common in earnings and flows columns |
-3 | Suppressed | Portal-wide suppression code; in PSEO earnings columns it was not observed (see note) |
-2 | Not applicable | Item 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") > 0to 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,year2016, 690 rows) every unavailable earnings value was-1and no earnings column was ever-3;-3appeared only injobless_m_emp_grads_counton 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.
| Dataset | Type | Path | Codebook |
|---|---|---|---|
| Earnings and Flows | Yearly (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:
- Actual data file (what you observe in the parquet/CSV) -- this IS the truth
- Live codebook (.xls in mirror) -- authoritative documentation, may lag
- 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_cohortunder everyyearin 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, dropyearand de-duplicate on all remaining columns (or keep oneyearper 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)
- PSEO Explorer: Interactive visualization tool at
https://lehd.ces.census.gov/applications/pseo/ - Census bulk download: CSV/XLS files at
https://lehd.ces.census.gov/data/pseo/ - Census API:
https://api.census.gov/data/timeseries/pseo/earningsand.../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
| Pitfall | Issue | Solution |
|---|---|---|
| Using Census string codes | Portal uses integers (e.g., 5 for Bachelor's), not Census strings ("05") | Always check encoding; see variable-definitions.md |
| Ignoring suppression | Cells with <30 graduates are suppressed; missing data looks like no program exists | Check total_grads_count to confirm cell exists; negative-coded earnings (observed as -1) may mean suppression |
| Cross-institution comparison without controlling degree/CIP | Institutions offer different program mixes; aggregate comparison is misleading | Always filter to same degree_level and cipcode when comparing institutions |
| Treating PSEO as comprehensive | Participation is voluntary and changes by release; no verified national graduate-coverage percentage is documented here | Report the release/version and partner roster used; acknowledge selection bias and do not generalize to all U.S. graduates |
| Ignoring labor attachment | Graduates 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 data | Some graduates are employed but excluded; note this limitation |
| Assuming one dtype for Portal opeid | On 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 letters | In 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 spans | Bachelor's uses 3-year cohorts; all others use 5-year | Filter by degree_level first, then verify cohort format matches |
| Assuming inflation comparability | All earnings are in 2022 CPI-U dollars | No 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
| Feature | PSEO | College Scorecard | State Systems |
|---|---|---|---|
| Coverage | Graduates only | Federally aided students (entry cohorts incl. non-completers in institution files; completers in field-of-study files) | Graduates only |
| Geographic scope | National (cross-state) | National | In-state only |
| Sample | All graduates from partners | Federal aid recipients | All graduates |
| Earnings detail | 25th/50th/75th percentile | Percentiles (10th–90th per Census PSEO tech doc) | Varies |
| Industry data | Yes (NAICS sector) | No | Varies |
| Geographic flows | Yes (Census Division) | No | No |
| Privacy method | Differential privacy (noise on earnings histograms and flows counts) plus suppression of earnings cells with protected count < 30 | Differential-privacy noise on earnings counts/medians plus PS suppression | Varies |
Common Use Cases
| Use Case | Data Needed | Key Considerations |
|---|---|---|
| Compare programs within institution | Earnings by CIPCODE | Check cell counts for suppression |
| Compare institutions for same program | Earnings by INSTITUTION | Ensure same degree level and CIP |
| Analyze brain drain/retention | Flows by division + in-state | Only 9 Census Divisions |
| Career pathway analysis | Flows by NAICS sector | 2-digit NAICS only |
| ROI by degree level | Earnings across DEGREE_LEVEL | Different cohort spans |
Important Limitations
- Experimental status: Not official Census statistics; methodology may change
- 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
- Selection bias: Participating states/institutions may differ systematically
- Employment coverage: Excludes self-employed, independent contractors, military, some federal
- 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
- 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
- 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
| Source | Relationship | When to Use |
|---|---|---|
education-data-source-scorecard | Alternative earnings source (Title IV aid recipients; IRS/Treasury earnings) | When PSEO coverage is insufficient or need non-graduate outcomes |
education-data-source-ipeds | Institution characteristics, enrollment, graduation rates | Contextualizing PSEO institutions; join on unitid |
education-data-explorer | Parent discovery skill | Routing questions to mirror dataset files |
education-data-query | Data fetching | Downloading parquet/CSV files |
Topic Index
| Topic | Reference 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 download | Data Access section above |
| Bulk data download | Data Access section above |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |