# Data Dictionary — `medical_claims.parquet`

Source: batch 0999  •  Row count: **97,953**


Columns:
- **Field** — column name
- **Type** — pyarrow dtype (canonical schema)
- **Key** — PK (primary key), PK part (composite PK), FK (foreign key)
- **Description** — what the field means
- **Expected values** — authored allowed list (from `config/dictionary.py`)
- **Observed values** — actual unique values (if ≤ 60 distinct) or stats / top-K
- **% null** — null fraction in this batch
- **Notes** — gotchas and format conventions

## `claim_id`

- **Type**: `string`
- **Key**: **PK part**
- **Description**: Parent claim identifier; multiple lines share.
- **Observed unique**: 41671 distinct (null: 0.0%)
- **Observed values**: (high cardinality, top 10) C09990000025893: 19 | C09990000025942: 19 | C09990000025960: 17 | C09990000025818: 17 | C09990000025830: 16 | C09990000026068: 15 | C09990000030199: 15 | C09990000025846: 14 | C09990000025927: 14 | C09990000026023: 14
- **Notes**: Format C{batch:04d}{seq:010d}. Composite PK with claim_line_id.

## `claim_line_id`

- **Type**: `int16`
- **Key**: **PK part**
- **Description**: Line sequence within parent claim (1, 2, 3, ...).
- **Observed unique**: 19 distinct (null: 0.0%)
- **Observed values**: 1: 41,671 (42.5%) | 2: 21,282 (21.7%) | 3: 13,006 (13.3%) | 4: 8,631 (8.8%) | 5: 5,721 (5.8%) | 6: 3,453 (3.5%) | 7: 2,046 (2.1%) | 8: 1,140 (1.2%) | 9: 566 (0.6%) | 10: 227 (0.2%) | 11: 98 (0.1%) | 12: 48 (0.0%) | 13: 28 (0.0%) | 14: 16 (0.0%) | 15: 7 (0.0%) | 16: 5 (0.0%) | 17: 4 (0.0%) | 18: 2 (0.0%) | 19: 2 (0.0%)
- **Notes**: Composite PK with claim_id. Unique only within claim.

## `member_id`

- **Type**: `string`
- **Key**: **FK** (eligibility.member_id)
- **Description**: Member identifier; FK to eligibility.
- **Observed unique**: 986 distinct (null: 0.0%)
- **Observed values**: (high cardinality, top 10) M099900000797: 620 | M099900000976: 588 | M099900000491: 472 | M099900000819: 373 | M099900000671: 367 | M099900000891: 349 | M099900000494: 331 | M099900000360: 323 | M099900000545: 306 | M099900000369: 295

## `claim_status`

- **Type**: `string`
- **Description**: Adjudication status.
- **Expected values** (4): 'PAID', 'DENIED', 'REVERSED', 'ADJUSTED'
- **Observed unique**: 4 distinct (null: 0.0%)
- **Observed values**: PAID: 91,139 (93.0%) | ADJUSTED: 4,543 (4.6%) | DENIED: 1,817 (1.9%) | REVERSED: 454 (0.5%)
- **Notes**: Only PAID counts toward PMPM. DENIED has paid=0. REVERSED has negative amounts. ADJUSTED is post-original.

## `bill_type_code`

- **Type**: `string`
- **Description**: UB-04 bill type (4-digit). Null for professional claims.
- **Expected values** (6): '0111', '0131', '0211', '0322', '0810', '0851'
- **Observed unique**: 4 distinct (null: 36.73%)
- **Observed values**: 0131: 48,717 (78.6%) | 0111: 5,381 (8.7%) | 0322: 4,431 (7.1%) | 0211: 3,450 (5.6%)
- **Notes**: 0111=IP, 0131=OP, 0211=SNF, 0322=HH, 0810=DME, 0851=Other.

## `revenue_code`

- **Type**: `string`
- **Description**: UB-04 revenue code (4-digit). Null for professional claims.
- **Observed unique**: 37 distinct (null: 34.23%)
- **Observed values**: 0270: 4,968 (7.7%) | 0440: 3,988 (6.2%) | 0410: 3,724 (5.8%) | 0300: 3,710 (5.8%) | 0250: 3,700 (5.7%) | 0360: 3,655 (5.7%) | 0710: 3,635 (5.6%) | 0450: 3,625 (5.6%) | 0636: 3,440 (5.3%) | 0301: 3,382 (5.2%) | 0260: 3,313 (5.1%) | 0918: 3,304 (5.1%) | 0320: 3,200 (5.0%) | 0610: 3,155 (4.9%) | 0510: 3,091 (4.8%) | 0274: 1,206 (1.9%) | 0192: 692 (1.1%) | 0194: 679 (1.1%) | 0550: 676 (1.0%) | 0191: 656 (1.0%) | 0560: 652 (1.0%) | 0190: 649 (1.0%) | 0580: 641 (1.0%) | 0193: 639 (1.0%) | 0570: 637 (1.0%) | 0420: 622 (1.0%) | 0430: 599 (0.9%) | 0120: 493 (0.8%) | 0150: 421 (0.7%) | 0121: 191 (0.3%) | 0130: 188 (0.3%) | 0123: 185 (0.3%) | 0122: 183 (0.3%) | 0110: 180 (0.3%) | 0140: 178 (0.3%) | 0921: 160 (0.2%) | 0350: 9 (0.0%)
- **Notes**: See config/revenue_codes.REVENUE_CODES_BY_BUCKET for the full list per bucket.

## `place_of_service`

- **Type**: `string`
- **Description**: CMS Place of Service code.
- **Expected values** (12): '11', '12', '21', '22', '23', '24', '31', '41', '49', '65', '71', '81'
- **Observed unique**: 8 distinct (null: 0.3%)
- **Observed values**: 11: 43,831 (44.9%) | 22: 19,926 (20.4%) | 81: 13,695 (14.0%) | 12: 6,853 (7.0%) | 21: 5,363 (5.5%) | 23: 3,728 (3.8%) | 31: 3,440 (3.5%) | 24: 824 (0.8%)
- **Notes**: 11=office, 12=home, 21=IP, 22=OP, 23=ER, 24=ASC, 31=SNF, 41=ambulance, 65=dialysis, 81=lab.

## `service_start_date`

- **Type**: `date32[day]`
- **Description**: Service start date.
- **Observed unique**: 1096 distinct (null: 0.0%)
- **Observed values**: range [2024-01-01, 2026-12-31]

## `service_end_date`

- **Type**: `date32[day]`
- **Description**: Service end date. For IP/SNF = discharge date; for office = same as start.
- **Observed unique**: 1103 distinct (null: 0.0%)
- **Observed values**: range [2024-01-01, 2027-01-20]

## `paid_date`

- **Type**: `date32[day]`
- **Description**: Date plan paid the claim.
- **Observed unique**: 1219 distinct (null: 0.0%)
- **Observed values**: range [2024-01-04, 2027-06-26]
- **Notes**: Lag = lognormal(mu=3, sigma=0.7) days from service_end. ~3-6% lag > 60 days (run-out).

## `allowed_amount`

- **Type**: `double`
- **Description**: Allowed (contracted) amount for the line.
- **Observed unique**: 41420 distinct (null: 0.0%)
- **Observed values**: range [-25430.59, 47392.83]  mean 345.16  P5/P50/P95 24.01 / 151.99 / 946.54
- **Notes**: Lognormal by bucket; see config/procedures.BUCKET_DEFAULT_ALLOWED.

## `paid_amount`

- **Type**: `double`
- **Description**: Plan-paid amount on the line.
- **Observed unique**: 39882 distinct (null: 0.0%)
- **Observed values**: range [-23396.14, 43601.40]  mean 311.99  P5/P50/P95 2.64 / 136.45 / 862.29
- **Notes**: ~92% of allowed for PAID; 0 for DENIED; negative for REVERSED.

## `coinsurance`

- **Type**: `double`
- **Description**: Member coinsurance portion.
- **Observed unique**: 7445 distinct (null: 0.0%)
- **Observed values**: range [0.00, 2369.64]  mean 18.32  P5/P50/P95 2.28 / 8.12 / 48.76
- **Notes**: Default ~5% of allowed.

## `copay`

- **Type**: `double`
- **Description**: Member copay portion.
- **Observed unique**: 3001 distinct (null: 0.0%)
- **Observed values**: range [0.00, 30.00]  mean 14.17  P5/P50/P95 0.00 / 14.10 / 28.47
- **Notes**: Uniform $0-30 for outpatient/professional; $0 for IP/SNF.

## `deductible`

- **Type**: `double`
- **Description**: Member deductible portion.
- **Observed unique**: 4997 distinct (null: 0.0%)
- **Observed values**: range [0.00, 50.00]  mean 9.58  P5/P50/P95 0.00 / 0.00 / 43.36
- **Notes**: Uniform $0-50 on first line of claim; $0 on subsequent lines.

## `procedure_code`

- **Type**: `string`
- **Description**: CPT or HCPCS code. Null on IP ancillary lines.
- **Observed unique**: 49 distinct (null: 10.57%)
- **Observed values**: 99214: 27,411 (31.3%) | 82947: 17,265 (19.7%) | 99213: 14,907 (17.0%) | 76700: 4,526 (5.2%) | 83036: 3,332 (3.8%) | 77067: 2,237 (2.6%) | 99285: 1,915 (2.2%) | 20610: 1,774 (2.0%) | 96413: 1,738 (2.0%) | 82962: 1,546 (1.8%) | 73721: 1,261 (1.4%) | 99215: 925 (1.1%) | 93306: 868 (1.0%) | 85610: 769 (0.9%) | 99232: 654 (0.7%) | 94010: 566 (0.6%) | 99291: 492 (0.6%) | 96365: 446 (0.5%) | 99233: 445 (0.5%) | 97110: 439 (0.5%) | 77014: 408 (0.5%) | 27130: 400 (0.5%) | H0001: 396 (0.5%) | 93000: 340 (0.4%) | 87798: 331 (0.4%) | 93922: 282 (0.3%) | 93010: 270 (0.3%) | 86701: 209 (0.2%) | 95910: 180 (0.2%) | 45378: 140 (0.2%) | 92928: 128 (0.1%) | 86703: 124 (0.1%) | 82565: 118 (0.1%) | 87534: 116 (0.1%) | 94660: 94 (0.1%) | 92920: 84 (0.1%) | 99284: 73 (0.1%) | 97597: 71 (0.1%) | 74177: 48 (0.1%) | 29581: 48 (0.1%) | 90961: 39 (0.0%) | 95816: 34 (0.0%) | 90960: 34 (0.0%) | 70450: 26 (0.0%) | 72100: 22 (0.0%) | 49450: 20 (0.0%) | 35371: 20 (0.0%) | 22515: 17 (0.0%) | 38221: 7 (0.0%)
- **Notes**: See config/procedures.PROCEDURE_CATALOG for the ~70-code library.

## `procedure_modifier`

- **Type**: `string`
- **Description**: CPT modifier code.
- **Expected values** (10): '', '25', '50', '59', 'GY', 'GZ', 'RT', 'LT', 'TC', '26'
- **Observed unique**: 10 distinct (null: 3.13%)
- **Observed values**: : 66,421 (70.0%) | 26: 3,218 (3.4%) | RT: 3,215 (3.4%) | 50: 3,198 (3.4%) | TC: 3,171 (3.3%) | GZ: 3,163 (3.3%) | 59: 3,147 (3.3%) | 25: 3,142 (3.3%) | LT: 3,109 (3.3%) | GY: 3,105 (3.3%)
- **Notes**: Most often empty/null. 25=significant separately identifiable E/M; 26=professional component.

## `icd_procedure_code`

- **Type**: `string`
- **Description**: ICD-10-PCS procedure code on IP first line.
- **Observed unique**: 1 distinct (null: 99.27%)
- **Observed values**: 0SS00ZZ: 712 (100.0%)
- **Notes**: Placeholder '0SS00ZZ' in v1; only populated on IP claim line_id=1.

## `diagnosis_code_1`

- **Type**: `string`
- **Description**: Primary diagnosis (ICD-10).
- **Observed unique**: 177 distinct (null: 0.0%)
- **Observed values**: (high cardinality, top 10) K21.9: 5,637 | R10.9: 5,599 | I10: 5,580 | Z00.01: 5,529 | R05.9: 5,449 | R51: 5,417 | M25.50: 5,338 | Z00.00: 5,284 | Z79.899: 5,236 | J06.9: 5,230
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_2`

- **Type**: `string`
- **Description**: Secondary diagnosis #2 (ICD-10), null if not applicable.
- **Observed unique**: 179 distinct (null: 2.36%)
- **Observed values**: (high cardinality, top 10) I10: 6,121 | M25.50: 5,651 | E78.5: 5,464 | K21.9: 5,417 | R05.9: 5,276 | J06.9: 5,276 | Z79.899: 5,252 | Z00.00: 5,241 | R51: 5,186 | Z00.01: 5,178
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_3`

- **Type**: `string`
- **Description**: Secondary diagnosis #3 (ICD-10), null if not applicable.
- **Observed unique**: 178 distinct (null: 3.31%)
- **Observed values**: (high cardinality, top 10) I10: 5,956 | E78.5: 5,589 | Z00.00: 5,438 | R10.9: 5,359 | K21.9: 5,356 | Z79.899: 5,328 | M25.50: 5,306 | J06.9: 5,279 | Z00.01: 5,151 | R05.9: 5,142
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_4`

- **Type**: `string`
- **Description**: Secondary diagnosis #4 (ICD-10), null if not applicable.
- **Observed unique**: 10 distinct (null: 99.54%)
- **Observed values**: I10: 115 (25.7%) | N17.9: 92 (20.5%) | E11.9: 63 (14.1%) | E87.2: 60 (13.4%) | N18.30: 37 (8.3%) | R65.21: 29 (6.5%) | E78.5: 18 (4.0%) | I25.10: 16 (3.6%) | J96.21: 9 (2.0%) | J18.9: 9 (2.0%)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_5`

- **Type**: `string`
- **Description**: Secondary diagnosis #5 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_6`

- **Type**: `string`
- **Description**: Secondary diagnosis #6 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_7`

- **Type**: `string`
- **Description**: Secondary diagnosis #7 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_8`

- **Type**: `string`
- **Description**: Secondary diagnosis #8 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_9`

- **Type**: `string`
- **Description**: Secondary diagnosis #9 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_10`

- **Type**: `string`
- **Description**: Secondary diagnosis #10 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_11`

- **Type**: `string`
- **Description**: Secondary diagnosis #11 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_12`

- **Type**: `string`
- **Description**: Secondary diagnosis #12 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_13`

- **Type**: `string`
- **Description**: Secondary diagnosis #13 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_14`

- **Type**: `string`
- **Description**: Secondary diagnosis #14 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_15`

- **Type**: `string`
- **Description**: Secondary diagnosis #15 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_16`

- **Type**: `string`
- **Description**: Secondary diagnosis #16 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_17`

- **Type**: `string`
- **Description**: Secondary diagnosis #17 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_18`

- **Type**: `string`
- **Description**: Secondary diagnosis #18 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_19`

- **Type**: `string`
- **Description**: Secondary diagnosis #19 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_20`

- **Type**: `string`
- **Description**: Secondary diagnosis #20 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_21`

- **Type**: `string`
- **Description**: Secondary diagnosis #21 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_22`

- **Type**: `string`
- **Description**: Secondary diagnosis #22 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_23`

- **Type**: `string`
- **Description**: Secondary diagnosis #23 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_24`

- **Type**: `string`
- **Description**: Secondary diagnosis #24 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `diagnosis_code_25`

- **Type**: `string`
- **Description**: Secondary diagnosis #25 (ICD-10), null if not applicable.
- **Observed unique**: 0 distinct (null: 100.0%)
- **Observed values**: (all null)
- **Notes**: Drawn from member's HCC dx pool + background pool (Z00.00, I10, E78.5, M25.50, ...).

## `drg_code`

- **Type**: `string`
- **Description**: MS-DRG code on IP claim first line.
- **Observed unique**: 23 distinct (null: 99.27%)
- **Observed values**: 191: 91 (12.8%) | 291: 91 (12.8%) | 639: 65 (9.1%) | 280: 49 (6.9%) | 872: 45 (6.3%) | 194: 42 (5.9%) | 470: 38 (5.3%) | 282: 24 (3.4%) | 917: 24 (3.4%) | 064: 24 (3.4%) | 682: 22 (3.1%) | 189: 21 (2.9%) | 292: 20 (2.8%) | 192: 20 (2.8%) | 281: 20 (2.8%) | 683: 19 (2.7%) | 377: 17 (2.4%) | 293: 17 (2.4%) | 190: 16 (2.2%) | 378: 14 (2.0%) | 871: 14 (2.0%) | 065: 11 (1.5%) | 195: 8 (1.1%)
- **Notes**: See config/procedures.COMMON_DRGS. Null on non-IP and on IP ancillary lines.

## `provider_specialty`

- **Type**: `string`
- **Description**: Specialty of the rendering provider.
- **Observed unique**: 15 distinct (null: 0.0%)
- **Observed values**: Lab: 27,640 (28.2%) | PCP: 16,745 (17.1%) | Specialist: 13,143 (13.4%) | Other: 11,597 (11.8%) | Radiology: 8,382 (8.6%) | Hospitalist: 5,163 (5.3%) | Home Health: 4,431 (4.5%) | ER: 3,738 (3.8%) | SNF: 3,450 (3.5%) | DME: 2,447 (2.5%) | Surgery: 775 (0.8%) | ICU: 218 (0.2%) | Cardiology: 132 (0.1%) | Wound: 47 (0.0%) | Orthopedics: 45 (0.0%)
- **Notes**: PCP / Specialist / ER / Hospitalist / Radiology / Lab / Cardiology / Oncology / SNF / Home Health / DME / Other / etc.

## `service_bucket`

- **Type**: `string`
- **Description**: Coarse service category for PMPM rollups.
- **Expected values** (7): 'IP', 'OP', 'PROF', 'SNF', 'HH', 'DME', 'OTHER'
- **Observed unique**: 6 distinct (null: 0.0%)
- **Observed values**: OP: 48,717 (49.7%) | PROF: 33,527 (34.2%) | IP: 5,381 (5.5%) | HH: 4,431 (4.5%) | SNF: 3,450 (3.5%) | DME: 2,447 (2.5%)
- **Notes**: IP=inpatient, OP=outpatient hospital, PROF=physician/professional, SNF=skilled nursing, HH=home health, DME=durable medical equipment.

## `units`

- **Type**: `int32`
- **Description**: Service units billed.
- **Observed unique**: 1 distinct (null: 0.0%)
- **Observed values**: 1: 97,953 (100.0%)
- **Notes**: Defaults to 1 in v1.

## `batch_id`

- **Type**: `int32`
- **Description**: Generation batch number.
- **Observed unique**: 1 distinct (null: 0.0%)
- **Observed values**: 999: 97,953 (100.0%)
