healthsim-populationsim

PopulationSim - Population Intelligence & Cohort Generation

Overview

PopulationSim provides population-level intelligence using public data (Census ACS, CDC PLACES, SVI, ADI) for:

1. Standalone Analysis: Geographic profiling, health disparities, population comparisons
2. 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,
      "hispanic": 0.34,
      "asian": 0.12,
      "black": 0.05,
      "other": 0.06
    },
    "median_household_income": 102285,
    "poverty_rate": 0.103
  },
  "health_indicators": {
    "source": "CDC_PLACES_2024",
    "diabetes_prevalence": 0.095,
    "obesity_prevalence": 0.280,
    "hypertension_prevalence": 0.285,
    "depression_prevalence": 0.195,
    "smoking_prevalence": 0.098
  },
  "sdoh_indices": {
    "svi_overall": 0.42,
    "svi_themes": {
      "socioeconomic": 0.38,
      "household_composition": 0.45,
      "minority_language": 0.52,
      "housing_transportation": 0.35
    },
    "adi_national_rank": 35
  },
  "healthcare_access": {
    "uninsured_rate": 0.071,
    "pcp_per_100k": 82.4,
    "insurance_mix": {
      "employer": 0.52,
      "medicare": 0.15,
      "medicaid": 0.18,
      "individual": 0.08,
      "uninsured": 0.07
    }
  }
}

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, "65-74": 0.28, "75+": 0.12 }
    },
    "sex": { "male": 0.48, "female": 0.52 },
    "race_ethnicity": { "white_nh": 0.28, "black": 0.22, "hispanic": 0.38, "asian": 0.08 }
  },
  "clinical_profile": {
    "primary_condition": { "icd10": "E11", "name": "Type 2 Diabetes" },
    "comorbidities": {
      "I10": { "name": "Hypertension", "rate": 0.71 },
      "E78": { "name": "Hyperlipidemia", "rate": 0.68 },
      "E66": { "name": "Obesity", "rate": 0.62 }
    }
  },
  "sdoh_profile": {
    "poverty_rate": 0.18,
    "uninsured_rate": 0.16,
    "food_insecurity": 0.15,
    "svi_mean": 0.58
  },
  "z_code_rates": {
    "Z59.6": { "name": "Low income", "rate": 0.18 },
    "Z59.41": { "name": "Food insecurity", "rate": 0.15 }
  },
  "insurance_mix": {
    "medicare": 0.38, "medicaid": 0.22, "commercial": 0.32, "uninsured": 0.08
  }
}

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 (Embedded v2.0)

Embedded data package (148 MB, 100% US coverage):

Source	File	Records	Data Year
CDC PLACES (County)	data/county/places_county_2024.csv	3,143	2022 BRFSS
CDC PLACES (Tract)	data/tract/places_tract_2024.csv	83,522	2022 BRFSS
SVI (County)	data/county/svi_county_2022.csv	3,144	2018-2022 ACS
SVI (Tract)	data/tract/svi_tract_2022.csv	84,120	2018-2022 ACS
ADI (Block Group)	data/block_group/adi_blockgroup_2023.csv	242,336	2019-2023 ACS
Geography Crosswalks	data/crosswalks/*.csv	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

• PatientSim - Clinical patient data
• MemberSim - Health plan member data
• RxMemberSim - Pharmacy data
• TrialSim - Clinical trial data
• NetworkSim - Provider networks

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.