AI导哈

人口普查数据验证工具

利用Census MCP服务器查询美国人口普查数据并结合其他公共数据集进行SNAP资格和政策分析的验证工具。

  • by jennthom
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jennthom/snap-validation-lab

使用说明

SNAP验证实验室

演示人口普查MCP服务器功能的概念验证 用于结合公共数据集来分析SNAP（补充营养援助计划）资格和计划结果。

项目概述

本项目演示了如何使用 普查MCP（模型上下文协议）服务器 查询美国人口普查数据，并将其与其他公共数据集（SNAP质量控制微观数据）结合起来进行政策分析。

这表明了什么

  1. 通过MCP服务器查询人口普查数据 -收入、贫困和人口数据
  2. 组合多个数据源 -人口普查局+美国农业部公共数据集
  3. 自动数据分析 -用于资格评估和验证的Python脚本
  4. 数据验证工作流程 -输入验证和健全性检查模式

关于人口普查MCP服务器

这 人口普查MCP服务器 允许通过Claude Code向美国人口普查局API进行自然语言查询。您可以提出以下问题，而不是手动构建API请求：

  • “密西西比州欣兹县的贫困率是多少？”
  • “比较三个县的收入中位数”
  • “有多少人生活在贫困线130%以下？”

本项目展示了如何使用MCP服务器：

  • 交互式探索 -分析过程中的快速人口统计查询
  • 程序集成 -将人口普查数据与其他数据集相结合
  • 验证工作流程 -对照行政数据核对估计数

分析结果示例

备注：SNAP QC错误分析使用 密西西比 作为示范案例。人口普查MCP服务器适用于任何美国地理区域。

密西西比州SNAP分析（2023财年）：

  • 错误率38.4% 密西西比州SNAP病例
  • 收入是主要的错误驱动因素：工薪阶层的错误率为73.3%，非工薪阶层为30.9%
  • 收入复杂性很重要：收入来源为3+的家庭的错误率为77.8%
  • 每年2940万美元的影响 仅在密西西比州
  • 留住人才的挑战：行政错误可能导致符合条件的工薪家庭循环取消福利

看 docs/notes.md 进行完整分析。

项目结构

snap-validation-lab/
├── analysis/                    # Analysis scripts
│   ├── analyze_qc_data.py       # Basic QC data analysis
│   ├── analyze_error_impact.py  # Error impact quantification ($$ estimates)
│   └── analyze_error_types.py   # Income vs deduction error breakdown
│
├── data/                        # Data files (gitignored)
│   └── qc_pub_fy2023.csv        # SNAP QC microdata
│
├── docs/                        # Documentation
│   ├── notes.md                 # Complete exploration notes and findings
│   └── VALIDATION.md            # Input validation documentation
│
├── outputs/                     # Generated outputs (gitignored)
│
├── us-census-bureau-data-api-mcp/  # Census API MCP server
│
└── README.md                    # This file

快速开始

📖 看 设置.md 有关详细的设置说明

1.设置

# Install Python dependencies
pip install -r requirements.txt

# Setup Census API key (IMPORTANT!)
cp .env.example .env
# Edit .env and add your Census API key
# Get key from: https://api.census.gov/data/key_signup.html

# Get SNAP QC data
# Download from: https://www.fns.usda.gov/snap/qc-annual-reports
# Place in: data/qc_pub_fy2023.csv

需要帮助？ 请参阅中的详细说明 设置.md

2.运行分析

# Basic QC analysis
python3 analysis/analyze_qc_data.py

# Error impact analysis (financial)
python3 analysis/analyze_error_impact.py

# Error type breakdown (income vs deductions)
python3 analysis/analyze_error_types.py

3.使用人口普查MCP服务器

人口普查MCP服务器是本次演示的核心 -它允许通过Claude Code对人口普查数据进行自然语言查询。

# Server is configured in .mcp.json
# Use through Claude Code interface to query Census data:

# "What is the median income in Hinds County, MS?"
# "Compare poverty rates for Hinds and Bolivar counties"
# "What percentage of people in Bolivar County are below 130% poverty level?"
# "Show me educational attainment data for Mississippi counties"

本项目中演示的示例查询：

  • SNAP资格估算的收入与贫困比率（表C17002）
  • 人口背景下的家庭收入分配（B19001）
  • 用于参与差距分析的SNAP收据数据（S2201）
  • 县级人口统计比较

数据源

SNAP质量控制数据

  • 源：美国农业部食品和营养服务局
  • 统一资源定位符: https://www.fns.usda.gov/snap/qc-annual-reports
  • 文件：2023财年公用文件
  • 覆盖：全国样本（约44000例，全部50个州）
  • 这一分析：密西西比子集（1181例）用作示范
  • 备注：公共文件包括州标识符，但不包括县标识符

人口普查数据（通过MCP服务器）

  • 源：美国人口普查局美国社区调查（ACS）
  • API：人口普查数据API
  • 数据集：ACS 5年预测（2023年）
  • 使用的表格:
    • C17002：收入与贫困水平之比
    • B19001：家庭收入分配
    • S1701：贫困状况
    • S2201:SNAP收据
    • S1501：教育程度

方法论

以密西西比州为例进行分析

资格评估（密西西比州各县）

  1. MS县收入与贫困比率查询普查（表C17002）
  2. 计算FPL≤130%的人口（SNAP收入阈值）
  3. 示例估计：辛德斯县约28.7%符合条件，玻利瓦尔县约43.5%符合条件

质量控制数据验证（密西西比州）

  1. 密西西比州筛选的SNAP QC微观数据（1181例）
  2. 确认99.5%的参与者FPL≤130%（验证阈值）
  3. 将参与者的人口统计数据与人口普查估计值进行比较
  4. 分析可能导致符合条件的人失去福利的管理错误

误差分析（密西西比州）

  1. 分类案例：正确（61.6%）、付款错误（21.3%）、错误案例（17.1%）
  2. 按家庭特征分析错误模式
  3. 隔离收入与扣除误差来源
  4. 全州范围内的项目财务影响

示例分析结果

聚焦：了解导致符合条件的人失去福利或收到不正确金额的行政错误

保留风险：按类别划分的高错误率

  1. 收入证明 -工薪阶层的错误率为73%（可能导致重新认证失败）
  2. 扣除计算 -医疗（72.7%），庇护所（50%）（福利金额不正确）
  3. 复杂家庭 -7人以上家庭的错误率为87.5%（行政负担）

面临行政人员流失风险的家庭

  1. 工作家庭 -错误率为73.3%，而非工薪阶层的错误率为30.9%（工资文件问题）
  2. 多种收入来源 -3+源的错误率为77.8%（复杂性导致错误→ 终止）
  3. 有孩子的家庭 -错误率为48.9%，无错误率为31.1%（风险更高，波动性更大）

成功保留家庭（错误率较低）

  1. 零收入家庭 -5.9%错误率（简单验证）
  2. 单人家庭 -29.8%的错误率（复杂性较低）
  3. 非常贫困的家庭 （贫困率<50%）-19.5%的错误率（稳定的资格）

文档

分析脚本

所有脚本都包括全面的输入验证：

analyze_qc_data.py

密西西比州基本质量控制数据分析：

  • 样本量和人口统计
  • 收入/贫困分配
  • 福利金额
  • 按家庭类型分列的错误率

analyze_error_impact.py

量化行政错误的财务影响：

  • 按家庭规模/贫困程度分列的错误率
  • 按错误类型划分的平均超额/少付
  • 预计全州影响（每年2940万美元）
  • 按人口统计的错误模式

分析错误类型.py

深入探讨收入与扣除错误：

  • 收入来源模式（工资、SSI、社会保障）
  • 扣除模式（住房、医疗、劳动收入）
  • 复杂性分析（1-3+收入来源）
  • 计算流量验证（总计→ net → 效益）
  • 针对质量控制的高风险情况

需求

Python包

pandas>=2.0.0
numpy>=1.24.0

安装方式：

pip install -r requirements.txt

数据需求

  • SNAP QC公用文件（2023财年）：约64MB CSV
  • 人口普查API密钥（用于MCP服务器）

安全注意事项

⚠️ 重要：永远不要将敏感文件提交到git！

看 设置.md 获取详细的秘密管理指南

秘密管理

您的人口普查API密钥应在 .env 文件：

# .env (gitignored - never committed)
CENSUS_API_KEY=your_actual_key_here

这 .gitignore 文件保护：

  • ✅ 人口普查API密钥(.env, .mcp.json)
  • ✅ 数据文件(data/, *.csv)
  • ✅ 环境文件(.env, .env.local)
  • ✅ 输出(outputs/)

在推送到GitHub之前：

  1. 验证 .gitignore 已到位

    cat .gitignore  # Should include .env and data/

  2. 在代码中不检查API键

    git grep -i "api.key\|census_api_key" | grep -v ".env"
# Should only show variable names, not actual keys

  3. 确认数据文件已排除

    git status  # Should NOT show data/ or .env

  4. 验证.env是否受保护

    git check-ignore .env  # Should output: .env

看 设置.md 获取完整的安全设置指南。

潜在扩展

这个概念证明可以扩展到证明：

附加分析

  • []县级细分（QC数据访问受限）
  • []多州比较（不同的经济背景）
  • []交互式可视化仪表板
  • []预测建模方法

技术演示

  • []分析管道中的实时人口普查数据查询
  • []与其他公共数据集的集成模式
  • []自动化数据验证框架
  • []其他人口普查表的MCP服务器使用模式

贡献

这是一个概念验证示范项目。对于问题或探索类似方法：

许可证

展示人口普查MCP服务器用于公共政策分析的演示项目。

致谢

  • 数据：美国农业部食品和营养服务局（SNAP QC）、美国人口普查局（ACS）
  • 工具：人口普查数据API MCP服务器，Claude代码
  • 上下文SNAP程序验证和质量控制分析

相关 MCP