Update HCC recapture

docs/docs/data-marts/hcc-recapture.md

@@ -25,12 +25,12 @@ The type of gap closure if provided using the `gap_status` field. Here are the g
 
 | Gap Status | Definition |
 |------------|------------|
-| closed using higher coefficient hcc in hierarchy group | An HCC in the same group was closed, but its coefficient is greater than the prior year HCC |
+| closed - higher coefficient hcc in hierarchy group | An HCC in the same group was closed, but its coefficient is greater than the prior year HCC |
 | closed | The specific HCC in question has been observed in a risk adjustable claim during the collection year |
-| closed using lower coefficient hcc in hierarchy group | An HCC in the same group was closed, but its coefficient is less than the prior year HCC |
+| closed - lower coefficient hcc in hierarchy group | An HCC in the same group was closed, but its coefficient is less than the prior year HCC |
 | new | Defined as an HCC that has not been coded in the past 2 years |
 | open | For gaps and claims, it's a chronic condition appropriate for recapture that has not been documented in current collection year |
-| inappropriate for recapture | The specific HCC in question is "Open" and no related/equivalent HCC has been closed, but it is not appropriate for risk adjustment because it's not a chronic diagnosis |
+| ineligible for recapture | The specific HCC in question is "Open" and no related/equivalent HCC has been closed, but it is not appropriate for risk adjustment because it's not a chronic diagnosis |
 
 Instead of just listing an HCC as closed, more detail is provided which presents an opportunity to improve future HCC recapture initiatives.
 
@@ -39,3 +39,13 @@ When calculating HCC gap closure, YTD recapture curves are often used. Recapture
 
 All of the models below are the final models output from the HCC recapture data mart.
 
+## Customizations
+The following options are customizable in the HCC recapture mart to provide greater flexibility.
+
+### HCC Suspect Lists
+
+The `hcc_recapture_suspect_list` variable can be set to `true` in the `dbt_project.yml` in order to provide your own HCC suspect list from a payer or clinical source. The data needs to be input into a model called `suspect_hccs`. The required fields can be found in the `hcc_recapture__stg_suspect_hccs` model.
+
+### Chronic HCCs
+
+The `hcc_recapture_chronic_hccs` variable can be set to `true` in the `dbt_project.yml` in order to provide your own custom chronic HCC definition instead of using the CMS chronic HCC definitions already provided. The data needs to be input into a model called `chronic_hccs`. The required fields can be found in the `hcc_recapture__stg_chronic_hccs` model.

models/data_marts/cms_hcc/cms_hcc_models.yml

@@ -262,7 +262,7 @@ models:
       schema: |
         {%- if var('tuva_schema_prefix',None) != None -%}{{var('tuva_schema_prefix')}}_cms_hcc{% else %}cms_hcc{%- endif -%}
       alias: _int_demographic_factors
-      tags: cms_hcc
+      tags: ["cms_hcc", "hcc_recapture"]
       materialized: table
     description: >
       Demographic and enrollment risk relative factor values for the  corresponding HCC model version and payment year.

models/data_marts/hcc_recapture/final/hcc_recapture__gap_status.sql

@@ -11,9 +11,11 @@ select distinct
     , risk_model_code
     , model_version
     , payment_year
-    , recapture_flag
+    , recapturable_flag
+    , hcc_type
+    , hcc_source
     , gap_status
     , suspect_hcc_flag
-from {{ ref('hcc_recapture__int_gap_status') }}
+from {{ ref('hcc_recapture__int_gap_status')}}
 -- Apply hierarchies
-where filtered_out_by_hierarchy = 0
+where filtered_by_hierarchy_flag = 0

models/data_marts/hcc_recapture/final/hcc_recapture__hcc_status.sql

@@ -4,34 +4,55 @@
 }}
 
 select distinct
-      stg.person_id
-    , stg.payer
-    , stg.data_source
-    , coalesce(gap.payment_year, {{ date_part('year', 'recorded_date') }} + 1) as payment_year
-    , stg.recorded_date
-    , stg.claim_id
-    , stg.rendering_npi
-    , stg.model_version
-    , stg.hcc_code
-    , stg.hcc_description
-    , stg.hcc_hierarchy_group
-    , stg.hcc_hierarchy_group_rank
-    , stg.suspect_hcc_flag
-    , stg.risk_model_code
-    , stg.eligible_claim_indicator
-    , stg.eligible_bene
-    , stg.reason
-    , gap.gap_status
-    , gap.recapture_flag
-from {{ ref('hcc_recapture__int_hccs') }} as stg
-left outer join {{ ref('hcc_recapture__gap_status') }} as gap
-  on stg.person_id = gap.person_id
-  and stg.payer = gap.payer
-  and stg.model_version = gap.model_version
-  and stg.hcc_code = gap.hcc_code
-  and stg.suspect_hcc_flag = gap.suspect_hcc_flag
-  and (case
-          when gap.gap_status = 'open' then stg.collection_year + 2
-          else stg.collection_year + 1
-      end) = gap.payment_year
-where eligible_bene = 1
+    hccs.person_id
+    , hccs.payer
+    , hccs.data_source
+    , coalesce(gap.payment_year, {{ date_part('year', 'hccs.recorded_date') }} + 1) as payment_year
+    , hccs.recorded_date
+    , hccs.claim_id
+    , hccs.rendering_npi
+    , hccs.model_version
+    , hccs.hcc_code
+    , hccs.hcc_description
+    , hccs.hcc_hierarchy_group
+    , hccs.hcc_hierarchy_group_rank
+    , hccs.suspect_hcc_flag
+    -- Latest risk_model_code per person/year/model_version based on recorded_date
+    , first_value(hccs.risk_model_code) over (
+        partition by 
+            hccs.person_id,
+            coalesce(gap.payment_year, {{ date_part('year', 'hccs.recorded_date') }} + 1),
+            hccs.model_version
+        order by hccs.recorded_date desc
+    ) as risk_model_code
+    , hccs.hcc_type
+    , hccs.hcc_source
+    , coalesce(gap.gap_status,'ineligible for recapture') as gap_status
+    -- Filters that may lead to an 'ineligible for recapture' gap status
+    , hccs.hcc_chronic_flag
+    , hccs.recapturable_flag
+    , hccs.eligible_claim_flag
+    , hccs.eligible_bene_flag
+    , coalesce(gap.filtered_by_hierarchy_flag, recap.filtered_by_hierarchy_flag,0) as filtered_by_hierarchy_flag
+from {{ ref('hcc_recapture__int_all_hccs') }} as hccs
+left join {{ ref('hcc_recapture__int_recapturable_hccs') }} as recap
+    on hccs.person_id = recap.person_id
+    and hccs.hcc_code = recap.hcc_code
+    and hccs.data_source = recap.data_source
+    and hccs.payer = recap.payer
+    and hccs.model_version = recap.model_version
+    and hccs.collection_year = recap.collection_year
+    and hccs.hcc_hierarchy_group = recap.hcc_hierarchy_group
+    and coalesce(hccs.claim_id, '') = coalesce(recap.claim_id, '')
+left join {{ ref('hcc_recapture__int_gap_status') }} as gap
+    on hccs.person_id = gap.person_id
+    and hccs.payer = gap.payer
+    and hccs.model_version = gap.model_version
+    and hccs.hcc_code = gap.hcc_code
+    -- For TUVA gaps, +2 is needed because we’re comparing collection year to payment year - we already need a +1 for that comparison, and an additional +1 to account for closure in the following year.
+    -- For suspect HCCs, we only apply +1, since it’s ok for those HCCs to close themselves within the same year (e.g., CY 2025 suspect list HCCs can be closed in CY 2025 based on claims rather than CY 2026).
+    and (case
+          when gap.gap_status = 'open' and hccs.hcc_type = 'coded' then hccs.collection_year + 2
+          else hccs.collection_year + 1
+    end) = gap.payment_year
+where hccs.eligible_bene_flag = 1

models/data_marts/hcc_recapture/final/hcc_recapture__recapture_rates_monthly.sql

@@ -20,12 +20,14 @@ select distinct
     , model_version
     , hcc_code
     , gap_status
-    , recapture_flag
+    , recapturable_flag
     , row_number() over (partition by person_id, payer, payment_year, model_version, hcc_code order by recorded_date asc) as earliest_hcc_code
-from {{ ref('hcc_recapture__hcc_status') }}
-where gap_status not in ('inappropriate for recapture', 'new')
-  and gap_status is not null
-  and suspect_hcc_flag = 0
+from {{ ref('hcc_recapture__hcc_status')}}
+where 1=1
+  and gap_status not in ('ineligible for recapture', 'new')
+  and hcc_type in ('captured', 'coded')
+  and recapturable_flag = 1
+  and filtered_by_hierarchy_flag = 0
 )
 
 , monthly_hcc_counts as (