Risk Adjustment Data Marts

Note that Zus Risk Adjustment features are currently in public preview and are subject to change.

Risk adjustment analytics are exposed via flattened, query-friendly tables derived from the underlying FHIR MeasureReport resources.

Risk Gap Views

A denormalized view of one row per risk gap (MeasureReport).

Common field	Notes
`id`	Risk gap identifier.
`patient_id`, `upid`	Patient identifiers.
`code_hcc`, `hcc_version`	HCC code and model version.
`gap_type`	Recapture, suspect, or net-new.
`gap_status`	Current/latest status.
`confidence_level`	1–5 (5 = highest confidence).
`period_start`	Start date for the calendar-year period.
`created_at`, `last_updated_at`	Creation and last update timestamps.

Typical use case	Description
Population listing	List all current-year gaps for a population.
Segmentation	Segment by gap type/status.
Trends	Trend monitoring by period.

One row per status update event per risk gap (full history).

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`created_at`, `created_by`	When and by whom the status was created.
`status`	Status code for this update.
`note` (optional)	Free-text note.
`substatus_one`, `substatus_two`, `substatus_three` (optional)	Additional categorization fields.

Typical use case	Description
Audit trail	Audit trail of review workflows.
Operational metrics	Measuring time-to-close or time-to-review.
Status evolution	Understanding how gaps evolve (e.g., open → expected-to-close → closed).

Represents superseding relationships between gaps based on HCC hierarchy.

Common field	Notes
`risk_gap_id`	The superseded gap.
`superseded_by_risk_gap_id`	The superseding gap.

Typical use case	Description
Top-level filtering	Filter to top-level gaps only.
Accurate counts	Avoid double-counting related HCCs in reporting.

Identifies which upstream sources contributed to each risk gap.

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`source`	Contributing source (e.g., rules-based, AI, payer, user).
`last_updated`	When the risk gap was last updated.

Typical use case	Description
Attribution	"Which systems are producing gaps?"
QA	QA and monitoring by source.

Normalized mapping of ICD-10 codes to risk gaps (one row per ICD-10 per gap).

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`code_icd_10`	ICD-10 diagnosis code.

Typical use case	Description
Drilldown	Drilldown from HCC gap → supporting ICD-10s.
Comparisons	Compare coding patterns across providers.

Normalized mapping from risk gaps to evidence resources.

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`resource_type`, `resource_id`	The referenced FHIR resource.
`type`	`evaluated` or `related`.
`last_updated`	When the risk gap was last updated.
`last_encounter_diagnosis_recorded_date` (when applicable)	Most recent encounter diagnosis timestamp for the evaluated resource.

Typical use case	Description
Reviewer experiences	Build reviewer experiences (evidence panels).
Analytics	Analytics on evidence completeness/recency.

Linking back to FHIR

You can often construct a direct FHIR reference using:

.../fhir/{resource_type}/{resource_id}

(Your exact base URL will depend on your deployment/environment.)

One row per patient, builder, and calendar year with aggregated RAF metrics.

Common field	Notes
`upid`	Universal patient identifier.
`patient_id`	Patient identifier.
`period_start`	Start date for the calendar-year period.
`potential_raf`	RAF score if all non-dismissed gaps were paid.
`potential_hcc_count`	Count of HCCs contributing to potential score.
`expected_raf`	RAF score for expected-to-close and closed gaps.
`expected_hcc_count`	Count of HCCs contributing to expected score.
`actual_raf`	RAF score for closed gaps only.
`actual_hcc_count`	Count of HCCs contributing to actual score.
`raf_gap`	Difference: potential_raf − actual_raf.
`hcc_gap`	Difference: potential_hcc_count − actual_hcc_count.

Typical use case	Description
Population overview	Aggregate RAF opportunity across a patient panel.
Gap prioritization	Identify patients with largest `raf_gap`.
Trend tracking	Monitor score changes over time.