| name | populationsim |
| description | PopulationSim provides population-level intelligence using public data sources. Use this skill for ANY request involving: (1) population demographics or profiles, (2) geographic health patterns or disparities, (3) social determinants of health (SDOH), (4) SVI or ADI analysis, (5) cohort definition or specification, (6) clinical trial feasibility, site selection, or enrollment projection, (7) service area analysis, (8) health equity assessment, (9) census data or ACS variables, (10) CDC PLACES health indicators.
|
PopulationSim - Population Intelligence & Cohort Generation
Overview
PopulationSim provides population-level intelligence using public data (Census ACS, CDC PLACES, SVI, ADI) for:
- Standalone Analysis: Geographic profiling, health disparities, population comparisons
- Cross-Product Integration: Cohort specs driving generation in PatientSim, MemberSim, RxMemberSim, TrialSim
Key Differentiator: PopulationSim analyzes real population characteristics and creates specifications — it does not generate synthetic records itself.
Quick Reference
| I want to... | Use This Skill | Key Triggers |
|---|
| Data Access (v2.0) | | |
| Look up exact data values | data-access/data-lookup.md | "what is the exact", "look up", "from PLACES" |
| Resolve FIPS codes | data-access/geography-lookup.md | "FIPS for", "which county is", "list counties in MSA" |
| Aggregate geographic data | data-access/data-aggregation.md | "aggregate tracts", "metro total", "combine counties" |
| Geographic Intelligence | | |
| Profile a county or region | geographic/county-profile.md | "county profile", "demographics for", "health indicators" |
| Analyze census tracts | geographic/census-tract-analysis.md | "tract level", "granular", "hotspots" |
| Profile a metro area | geographic/metro-area-profile.md | "metro", "MSA", "metropolitan" |
| Define custom region | geographic/custom-region-builder.md | "service area", "combine", "custom region" |
| Health Patterns | | |
| Analyze disease prevalence | health-patterns/chronic-disease-prevalence.md | "diabetes rate", "prevalence", "CDC PLACES" |
| Analyze health behaviors | health-patterns/health-behavior-patterns.md | "smoking rate", "obesity", "physical activity" |
| Assess healthcare access | health-patterns/healthcare-access-analysis.md | "uninsured", "provider ratio", "access" |
| Identify health disparities | health-patterns/health-outcome-disparities.md | "disparities", "equity", "by race" |
| SDOH Analysis | | |
| Analyze SVI | sdoh/svi-analysis.md | "SVI", "social vulnerability", "vulnerable" |
| Analyze ADI | sdoh/adi-analysis.md | "ADI", "area deprivation", "deprived" |
| Analyze economics | sdoh/economic-indicators.md | "poverty", "income", "unemployment" |
| Analyze community factors | sdoh/community-factors.md | "housing", "transportation", "food access" |
| Cohort Definition | | |
| Define a cohort | cohorts/cohort-specification.md | "define cohort", "cohort spec", "population segment" |
| Build demographics | cohorts/demographic-distribution.md | "age distribution", "demographics for cohort" |
| Build clinical profile | cohorts/clinical-prevalence-profile.md | "comorbidity rates", "clinical profile" |
| Build SDOH profile | cohorts/sdoh-profile-builder.md | "SDOH profile", "Z-code rates" |
| Trial Support | | |
| Estimate trial feasibility | trial-support/feasibility-estimation.md | "feasibility", "eligible population" |
| Select trial sites | trial-support/site-selection-support.md | "site selection", "best locations" |
| Project enrollment | trial-support/enrollment-projection.md | "enrollment timeline", "recruitment rate" |
Safety Guardrails
All Generated Data is Synthetic
PopulationSim outputs synthetic, fictional, simulated data — never real patient records. All profiles and cohort specs are derived from aggregated public statistics and must not be treated as real patient data.
Do NOT:
- Present synthetic data as actual patient records
- Make clinical recommendations (e.g., "you should prescribe," "the patient needs") based on generated data
- Pull from or reference real patient databases — use only public reference data
Do:
- Remind users that all generated data is synthetic test data
- Use real, valid medical code systems for standards: ICD-10 (diagnoses), CPT/HCPCS (procedures), LOINC (labs), SNOMED (clinical terms), RxNorm/NDC (medications), NPI (providers)
- Use real public reference data (Census ACS, CDC PLACES, SVI, ADI) for population characteristics
Negative Examples — What PopulationSim Must NOT Do
| Scenario | Wrong Response | Correct Response |
|---|
| "What should this patient take?" | "I recommend starting them on metformin" | "This is synthetic test data; PopulationSim does not provide clinical recommendations." |
| "Generate individual patient records" | Emit named patient rows | Route to PatientSim — PopulationSim produces population-level profiles and cohort specs, not individual records |
| "Show me real patient data from the database" | Pull from a patient database | "All PopulationSim data is synthetic. Real reference data (Census, PLACES) is population-level only." |
| Population prevalence as individual risk | "This patient has a 28% chance of obesity" | "The county obesity prevalence is 28.0% (CDC PLACES 2024)" — population rates are not individual probabilities |
Edge Cases
- Missing FIPS: Validate inputs; return clear error if FIPS not found in crosswalk files
- Partial data: Some tracts lack PLACES or SVI coverage — flag gaps rather than imputing zeros
- Invalid codes: Only emit ICD-10, CPT, LOINC, RxNorm, NDC codes from recognized systems
Output Types
PopulationProfile
Geographic entity with demographics, health indicators, and SDOH indices:
{
"geography": {
"type": "county",
"fips": "06073",
"name": "San Diego County",
"state": "CA",
"region": "Pacific"
},
"demographics": {
"total_population": 3286069,
"median_age": 37.1,
"age_distribution": {
"0-17": 0.21,
"18-64": 0.62,
"65+": 0.17
},
"race_ethnicity": {
"white_nh": 0.43
CohortSpecification
Generation input for other HealthSim products:
{
"cohort_id": "houston_diabetics_2024",
"name": "Houston Metro Diabetic Adults",
"target_size": 10000,
"geography": {
"type": "msa",
"cbsa_code": "26420",
"name": "Houston-The Woodlands-Sugar Land, TX"
},
"demographics": {
"age": {
"min": 18, "max": 85, "mean": 58.4,
"brackets": { "18-44": 0.18, "45-64": 0.42,
Cross-Product Integration
Integration Flow
┌─────────────────────┐
│ PopulationSim │
│ CohortSpecification│
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PatientSim │ │ MemberSim │ │ TrialSim │
│ - patients │ │ - members │ │ - subjects │
│ - diagnoses │ │ - claims │ │ - diversity │
│ - SDOH codes│ │ - plans │ │ - sites │
└──────┬──────┘ └──────┬──────┘ └─────────────┘
│ │
└─────────┬─────────┘
▼
┌─────────────┐
│ RxMemberSim │
│ - Rx claims │
│ - adherence │
└─────────────┘
Integration Patterns
| Output | Receiver | Result |
|---|
| CohortSpecification | PatientSim | Patients matching demographic/clinical profile |
| CohortSpecification | MemberSim | Members with realistic plan/utilization mix |
| CohortSpecification | TrialSim | Diverse trial subjects meeting FDA guidance |
| PopulationProfile | NetworkSim | Service area provider network design |
Data Sources
Reference data (100% US coverage) accessible via healthsim MCP tools:
| Source | Table | Records | Data Year |
|---|
| CDC PLACES (County) | population.places_county (via healthsim_query_reference) | 3,143 | 2022 BRFSS |
| CDC PLACES (Tract) | population.places_tract (via healthsim_query_reference) | 83,522 | 2022 BRFSS |
| SVI (County) | population.svi_county (via healthsim_query_reference) | 3,144 | 2018-2022 ACS |
| SVI (Tract) | population.svi_tract (via healthsim_query_reference) | 84,120 | 2018-2022 ACS |
| ADI (Block Group) | population.adi_blockgroup (via healthsim_query_reference) | 242,336 | 2019-2023 ACS |
| Geography Crosswalks | geography crosswalks (via healthsim_query) | Various | 2023 Census |
DuckDB Reference Tables
Reference data also available in DuckDB:
| Table | Source | Purpose |
|---|
population.places_tract | CDC PLACES | Tract-level health indicators |
population.places_county | CDC PLACES | County-level health indicators |
population.svi_tract | CDC SVI | Tract-level vulnerability |
population.svi_county | CDC SVI | County-level vulnerability |
population.adi_blockgroup | ADI | Block group deprivation |
See Data Architecture for details.
Directory Structure
skills/populationsim/
├── SKILL.md # This file - master router
├── README.md # Product overview
├── population-intelligence-domain.md # Core domain knowledge
│
├── data/ # Embedded Data Package (v2.0)
│ ├── README.md # Data dictionary
│ ├── county/ # County-level files
│ ├── tract/ # Tract-level files
│ ├── block_group/ # Block group files (ADI)
│ └── crosswalks/ # FIPS and CBSA mappings
│
├── data-access/ # Data Access Skills (v2.0)
│ ├── README.md # Category overview
│ ├── data-lookup.md # Direct value lookups
│ ├── geography-lookup.md # FIPS code resolution
│ └── data-aggregation.md # Geographic aggregation
│
├── geographic/ # Geographic Intelligence
│ ├── README.md # Category overview
│ ├── county-profile.md # County-level profiles
│ ├── census-tract-analysis.md # Tract-level analysis
│ ├── metro-area-profile.md # MSA/CBSA profiles
│ └── custom-region-builder.md # Custom region aggregation
│
├── health-patterns/ # Health Analysis
│ ├── README.md # Category overview
│ ├── chronic-disease-prevalence.md # Disease burden analysis
│ ├── health-behavior-patterns.md # Risk factor analysis
│ ├── healthcare-access-analysis.md # Coverage and access
│ └── health-outcome-disparities.md # Disparity analysis
│
├── sdoh/ # Social Determinants
│ ├── README.md # SDOH framework overview
│ ├── svi-analysis.md # Social Vulnerability Index
│ ├── adi-analysis.md # Area Deprivation Index
│ ├── economic-indicators.md # Income, poverty, employment
│ └── community-factors.md # Housing, transportation, food
│
├── cohorts/ # Cohort Definition
│ ├── README.md # CohortSpecification schema
│ ├── cohort-specification.md # Complete cohort definition
│ ├── demographic-distribution.md # Age, sex, race distributions
│ ├── clinical-prevalence-profile.md # Comorbidity patterns
│ └── sdoh-profile-builder.md # SDOH and Z-code rates
│
└── trial-support/ # Clinical Trial Support
├── README.md # Trial integration overview
├── feasibility-estimation.md # Eligible population modeling
├── site-selection-support.md # Site network optimization
└── enrollment-projection.md # Timeline projections
Quick Examples
Example 1: County Health Profile
Request: "Profile San Diego County health indicators"
Response:
San Diego County, CA (FIPS 06073) Population Profile:
Demographics (ACS 2022 5-year):
- Total Population: 3,286,069
- Median Age: 37.1 years
- Race/Ethnicity: 43% White NH, 34% Hispanic, 12% Asian, 5% Black
Health Indicators (CDC PLACES 2024):
- Diabetes: 9.5% (vs 10.1% national)
- Obesity: 28.0% (vs 32.1% national)
- Hypertension: 28.5% (vs 32.4% national)
SDOH Indices:
- SVI Overall: 0.42 (moderate vulnerability)
- ADI National Rank: 35th percentile
Example 2: Disparities by SVI Quartile
Request: "How do health outcomes vary across SVI quartiles?"
Response: Stratification by SVI quartile shows clear outcome variation:
| SVI Quartile | Diabetes | Obesity | Uninsured |
|---|
| Q1 (lowest vulnerability) | 8.2% | 26% | 5.1% |
| Q4 (highest vulnerability) | 13.8% | 38% | 14.2% |
Disparity: Q4 tracts show higher prevalence vs Q1 across all indicators; lower-vulnerability areas have better outcomes. See health-patterns/health-outcome-disparities.md.
Example 3: Cohort for PatientSim
Request: "Define a cohort of high-risk diabetics in underserved California"
Response: Creates CohortSpecification with:
- Geography: CA census tracts with SVI ≥ 0.70
- Demographics: Hispanic 58%, mean age 58.4
- Comorbidities: HTN 71%, obesity 62%
- SDOH: Rx cost barrier 31%, food insecurity 22%
Example 4: Trial Feasibility
Request: "Feasibility for T2DM trial: age 40-70, HbA1c 8-11%"
Response:
| Stage | Population | Conversion |
|---|
| T2DM Prevalent | 34.2M | - |
| Age 40-70 | 24.8M | 72.5% |
| HbA1c 8-11% | 7.4M | 29.8% |
| After exclusions | 4.2M | - |
Top Metros: Houston (128K), Miami (115K), Los Angeles (108K)
Related Products
Domain Knowledge
See Population Intelligence Domain for geographic hierarchy, census data, and SDOH frameworks.
Generative Framework Integration
PopulationSim feeds the Generative Framework via CohortSpecifications that drive synthetic generation in PatientSim, MemberSim, and TrialSim.
