Add columns to HCC recapture (#1355)

* updating row number to rank

* updating end date

* updating coalesce for end dates

* split end date update into separate PR

* fix missing comma

* Updating yml config

* formatting

* formatting

* Normalizing the facility NPI field

* removing claim start date

* Updating tests to use test prefix + normalizing facility NPI

* Adding data source constraint

* remove suspect hcc flag from output

* updating suspect hcc flag

* updating suspect hcc flag

* removing suspect hcc flag from gaps

* adding reason

* fixing bug with duplicate as

* adding uniqueness test

* adding distinct

* adding distinct

* adding data source col

* updating pk

* fixing coded hccs

* updating coded hccs pk check

* updating pk

* adding hcc type and source

* fixing stray comma

* updating aliases

* including suspects

* using external hccs as a name instead

* updating gap status

* adding year lookback variable

* updating hcc hier group

* fixing bug

* updating recap rates logic

* adding lookback period variable

---------

Co-authored-by: Andreas Martinson <amartinson193@gmail.com>
Co-authored-by: Chase Jones <60072797+chase-jones@users.noreply.github.com>
Co-authored-by: Aaron Neiderhiser <anneiderhiser@gmail.com>

Author: 4 people

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

@@ -10,7 +10,7 @@ The HCC recapture data mart enables organizations to track HCCs which have been
 - It affects that patient's risk score
 - The risk score affects reimbursement for value-based care contracts
 
-This mart not only tracks HCCs which were previously coded, but also automatically includes any suspect HCCs from the suspect HCC mart and flags them using the `suspect_hcc_flag`.
+This mart not only tracks HCCs which were previously coded, but also automatically includes any suspect HCCs from the suspect HCC mart.
 
 Additionally, the mart provides recapture rates and a lot of detail into the type of gap closure.
 
@@ -44,8 +44,12 @@ The following options are customizable in the HCC recapture mart to provide grea
 
 ### HCC Suspect Lists
 
-The `hcc_recapture_suspect_list` variable defaults to `false` and 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.
+The `hcc_recapture_external_suspect_list` variable defaults to `false` and 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 defaults to `false` and 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.
+The `hcc_recapture_external_chronic_hccs` variable defaults to `false` and 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.
+
+### Lookback Period
+
+The `hcc_recapture_year_lookback` variable defaults to 1 and can be changed to determine the number of years to lookback to find coded HCCs.

models/data_marts/hcc_recapture/final/hcc_recapture__gap_status.sql

@@ -14,8 +14,9 @@ select distinct
     , recapturable_flag
     , hcc_type
     , hcc_source
+    , hcc_gap_type
+    , hcc_gap_source
     , gap_status
-    , suspect_hcc_flag
-from {{ ref('hcc_recapture__int_gap_status')}}
+from {{ ref('hcc_recapture__int_gap_status') }}
 -- Apply hierarchies
 where filtered_by_hierarchy_flag = 0

models/data_marts/hcc_recapture/final/hcc_recapture__hcc_status.sql

@@ -16,7 +16,8 @@ select distinct
     , hccs.hcc_description
     , hccs.hcc_hierarchy_group
     , hccs.hcc_hierarchy_group_rank
-    , coalesce(gap.suspect_hcc_flag, hccs.suspect_hcc_flag) as suspect_hcc_flag
+    , hccs.external_hcc_flag
+    , hccs.reason
     -- Latest risk_model_code per person/year/model_version based on recorded_date
     , first_value(hccs.risk_model_code) over (
         partition by 
@@ -27,13 +28,15 @@ select distinct
     ) as risk_model_code
     , hccs.hcc_type
     , hccs.hcc_source
+    , gap.hcc_gap_type
+    , gap.hcc_gap_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
+    , 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
@@ -55,4 +58,4 @@ left join {{ ref('hcc_recapture__int_gap_status') }} as gap
           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
+where hccs.eligible_bene_flag = 1

models/data_marts/hcc_recapture/final/hcc_recapture__recapture_rates_monthly.sql

@@ -20,13 +20,14 @@ select distinct
     , model_version
     , hcc_code
     , gap_status
+    , case when hcc_type = 'suspect' then 1 else 0 end as suspect_hcc_flag
     , recapturable_flag
-    , suspect_hcc_flag
-    , row_number() over (partition by person_id, payer, payment_year, model_version, hcc_code order by recorded_date asc) as earliest_hcc_code
+    , row_number() over (partition by person_id, payer, payment_year, model_version, hcc_code 
+                        order by case hcc_type when 'coded' then 1 when 'captured' then 2 else 3 end, recorded_date asc) as earliest_hcc_code
 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 hcc_type in ('captured', 'coded', 'suspect')
   and recapturable_flag = 1
   and filtered_by_hierarchy_flag = 0
 )

models/data_marts/hcc_recapture/final_models.yml

@@ -301,7 +301,6 @@ models:
               - model_version
               - hcc_hierarchy_group
               - hcc_hierarchy_group_rank
-              - suspect_hcc_flag
               - filtered_by_hierarchy_flag
               - hcc_type
               - hcc_source
@@ -396,9 +395,8 @@ models:
           meta:
             data_type: integer
             is_primary_key: true
-      - name: suspect_hcc_flag
-        description: Flag indicating whether the HCC comes from suspecting logic rather
-          than a billed diagnosis.
+      - name: external_hcc_flag
+        description: "These HCCs are not based on claims, but based on data provided from clinical or additional payer HCC lists."
         config:
           meta:
             data_type: integer
@@ -594,9 +592,4 @@ models:
         config:
           meta:
             data_type: varchar
-      - name: suspect_hcc_flag
-        description: Flag indicating whether the HCC comes from suspecting logic rather
-          than a billed diagnosis.
-        config:
-          meta:
-            data_type: integer
+

models/data_marts/hcc_recapture/intermediate/hcc_recapture__int_determine_gap_status.sql

@@ -3,6 +3,8 @@
    )
 }}
 
+{% set lookback = var('hcc_recapture_year_lookback', 1) | int %}
+
 -- Get recapturable HCCs within the past 1 year
 with filtered_hccs as (
     select *
@@ -11,15 +13,16 @@ with filtered_hccs as (
 ),
 
 risk_gaps as (
+{% for year_offset in range(1, lookback + 1) %}
+
     select distinct
         person_id
         , payer
-        , collection_year + 1 as collection_year
+        , collection_year + {{ year_offset }} as collection_year
         , model_version
         , hcc_code
         , hcc_hierarchy_group
         , hcc_hierarchy_group_rank
-        , suspect_hcc_flag
         , recapturable_flag
         , hcc_type
         , hcc_source
@@ -28,6 +31,10 @@ risk_gaps as (
     from filtered_hccs
     where hcc_type = 'coded'
 
+    {% if not loop.last %} union all {% endif %}
+
+{% endfor %}
+
     union all
 
     -- No need to add +1 to collection year since these are already identified as captured/suspect in the same year identified
@@ -40,7 +47,6 @@ risk_gaps as (
         , hcc_code
         , hcc_hierarchy_group
         , hcc_hierarchy_group_rank
-        , suspect_hcc_flag
         , recapturable_flag
         , hcc_type
         , hcc_source
@@ -50,7 +56,7 @@ risk_gaps as (
     where hcc_type = 'suspect'
 ),
 
-best_past_rank as (
+hcc_rank as (
     select distinct
         person_id
         , payer
@@ -59,25 +65,10 @@ best_past_rank as (
         , hcc_code
         , hcc_hierarchy_group
         , hcc_hierarchy_group_rank
-        , min(hcc_hierarchy_group_rank) over (partition by person_id, payer, collection_year, model_version, hcc_hierarchy_group) as best_past_rank
+        , min(hcc_hierarchy_group_rank) over (partition by person_id, payer, collection_year, model_version, hcc_hierarchy_group) as best_hcc_rank
     from filtered_hccs
     where hcc_type in ('coded', 'captured')
-),
-
-
-best_current_rank as (
-    select distinct
-        person_id
-        , payer
-        , collection_year
-        , model_version
-        , hcc_code
-        , hcc_hierarchy_group
-        , hcc_hierarchy_group_rank
-        , risk_model_code
-        , eligible_bene_flag
-        , min(hcc_hierarchy_group_rank) over (partition by person_id, payer, collection_year, model_version, hcc_hierarchy_group) as best_current_rank
-    from filtered_hccs
+        and hcc_hierarchy_group != 'no hierarchy'
 ),
 
 equiv_coef as (
@@ -99,31 +90,30 @@ equiv_coef as (
 select
     coalesce(base.payer, gap.payer) as payer
     , coalesce(base.person_id, gap.person_id) as person_id
-    , coalesce(base.risk_model_code, gap.risk_model_code, current_year_hier.risk_model_code) as risk_model_code
-    , coalesce(base.eligible_bene_flag, gap.eligible_bene_flag, current_year_hier.eligible_bene_flag) as eligible_bene_flag
+    , coalesce(base.risk_model_code, gap.risk_model_code) as risk_model_code
+    , coalesce(base.eligible_bene_flag, gap.eligible_bene_flag) as eligible_bene_flag
     , coalesce(base.hcc_code, gap.hcc_code) as hcc_code
     , gap.hcc_code as recaptured_hcc_code
-    , current_year_hier.hcc_code as current_year_hcc_code
-    , grp.hcc_code as past_year_hcc_code
-    , coalesce(greatest(base.suspect_hcc_flag, gap.suspect_hcc_flag), 0) as suspect_hcc_flag
+    , grp.hcc_code as best_current_year_hcc_code
     , coalesce(base.model_version, gap.model_version) as model_version
     , coalesce(base.collection_year, gap.collection_year) as collection_year
     , coalesce(base.hcc_hierarchy_group, gap.hcc_hierarchy_group) as hcc_hierarchy_group
     , coalesce(base.hcc_hierarchy_group_rank, gap.hcc_hierarchy_group_rank) as hcc_hierarchy_group_rank
     , coalesce(base.recapturable_flag, gap.recapturable_flag) as recapturable_flag
-    , coalesce(base.hcc_type, gap.hcc_type) as hcc_type
-    , coalesce(base.hcc_source, gap.hcc_source) as hcc_source
+    , base.hcc_type
+    , gap.hcc_type as hcc_gap_type
+    , base.hcc_source
+    , gap.hcc_source as hcc_gap_source
     , case
         when
             gap.hcc_code is not null and base.hcc_code is not null and gap.hcc_code != base.hcc_code and equiv.risk_model_code is not null
             then 'closed - equivalent coefficient hcc in hierarchy group'
         when
-            grp.hcc_hierarchy_group is not null and base.hcc_hierarchy_group_rank < grp.best_past_rank
+            grp.hcc_hierarchy_group is not null and base.hcc_hierarchy_group_rank < grp.best_hcc_rank
             then 'closed - higher coefficient hcc in hierarchy group'
-        when current_year_hier.best_current_rank < gap.hcc_hierarchy_group_rank then 'closed - higher coefficient hcc in hierarchy group'
         when gap.hcc_code is not null and base.hcc_code is not null then 'closed'
         when
-            grp.hcc_hierarchy_group is not null and base.hcc_hierarchy_group_rank > grp.best_past_rank
+            grp.hcc_hierarchy_group is not null and base.hcc_hierarchy_group_rank > grp.best_hcc_rank
             then 'closed - lower coefficient hcc in hierarchy group'
         when gap.hcc_code is not null and base.hcc_code is null then 'open'
         when gap.hcc_code is null and base.hcc_code is not null then 'new'
@@ -142,20 +132,13 @@ left join equiv_coef as equiv
     and base.hcc_hierarchy_group = equiv.hcc_hierarchy_group
     and base.hcc_code = equiv.hcc_code
     and base.risk_model_code = equiv.risk_model_code
-left join best_past_rank as grp
+left join hcc_rank as grp
     on base.person_id = grp.person_id
     and base.payer = grp.payer
     and base.collection_year = grp.collection_year
     and base.model_version = grp.model_version
     and base.hcc_hierarchy_group = grp.hcc_hierarchy_group
-    and grp.best_past_rank = grp.hcc_hierarchy_group_rank
-left join best_current_rank as current_year_hier
-    on gap.person_id = current_year_hier.person_id
-    and gap.payer = current_year_hier.payer
-    and gap.collection_year = current_year_hier.collection_year
-    and gap.model_version = current_year_hier.model_version
-    and gap.hcc_hierarchy_group = current_year_hier.hcc_hierarchy_group
-    and current_year_hier.best_current_rank = current_year_hier.hcc_hierarchy_group_rank
+    and grp.best_hcc_rank = grp.hcc_hierarchy_group_rank
 -- Gaps are only eligible to be closed by claims data and the base table here is closing the gap aliased table
 -- The or hcc_type is null allows open HCCs to flow through
 where base.hcc_type in ('coded', 'captured') or base.hcc_type is null

models/data_marts/hcc_recapture/intermediate/hcc_recapture__int_gap_status.sql

@@ -9,12 +9,13 @@ with add_rankings as (
         person_id
         , payer
         , hcc_code
-        , suspect_hcc_flag
         , model_version
         , collection_year + 1 as payment_year
         , recapturable_flag
         , hcc_type
         , hcc_source
+        , hcc_gap_type
+        , hcc_gap_source
         , eligible_bene_flag
         , gap_status
         , risk_model_code
@@ -35,14 +36,16 @@ with add_rankings as (
 
 -- Pick the best hcc type
     -- 1. Best rank
-    -- 2. If tie → prefer recapture (suspect_hcc_flag = 0)
+    -- 2. If tie → prefer recapture
 , best_hcc_type as (
     select *
     , row_number() over (
         partition by person_id, payer, hcc_code, model_version, payment_year
         order by 
             hcc_type_rank asc,
-            suspect_hcc_flag asc   -- 0 preferred over 1
+            -- If it was already coded, prefer coded > suspect
+            case when hcc_type = 'suspect' then 1 else 0 end asc,
+            case when hcc_gap_type = 'suspect' then 1 else 0 end asc
     ) as best_rank
     from add_rankings
 )
@@ -90,10 +93,11 @@ select distinct
     , bgap.recapturable_flag
     , bgap.hcc_type
     , bgap.hcc_source
+    , bgap.hcc_gap_type
+    , bgap.hcc_gap_source    
     , bgap.gap_status
     , bgap.hcc_hierarchy_group
     , bgap.hcc_hierarchy_group_rank
-    , bgap.suspect_hcc_flag
     -- Apply hierarchies (i.e. if the hierarchy is not the min hierarchy, then remove it)
     , case when bgap.hcc_hierarchy_group is not null and mhier.hcc_hierarchy_group is null then 1 else 0 end as filtered_by_hierarchy_flag
 from best_gap_status as bgap

models/data_marts/hcc_recapture/intermediate/hccs/hcc_recapture__int_all_hccs.sql

@@ -59,7 +59,8 @@ select distinct
     , case when elig_bene.person_id is not null then 1 else 0 end as eligible_bene_flag
     , eligible_claim_flag
     , med.rendering_npi
-    , suspect_hcc_flag
+    , sus.external_hcc_flag
+    , sus.reason
     , case when chronic.chronic_flag = 1 and eligible_claim_flag = 1 then 1 else 0 end as recapturable_flag
     , hcc_type
     , hcc_source

models/data_marts/hcc_recapture/intermediate/hccs/hcc_recapture__int_coded_hccs.sql

@@ -12,7 +12,7 @@ with eligible_claims as (
     from {{ ref('cms_hcc__int_eligible_conditions') }}
 )
 
-select
+select distinct
     cond.person_id
     , cond.payer
     , cond.data_source
@@ -21,11 +21,12 @@ select
     , cond.claim_id
     , cond.hcc_code
     , cond.hcc_description
-    , 0 as suspect_hcc_flag
+    , 0 as external_hcc_flag
     , case
         when elig.claim_id is not null then 1
         else 0
     end as eligible_claim_flag
+    , 'prior coding history' as reason
     , 'coded' as hcc_type
     , 'payer' as hcc_source
 -- Not using list_all since it doesn't have claim_id pulled through
@@ -35,4 +36,5 @@ left join eligible_claims as elig
     on cond.person_id = elig.person_id
     and cond.payer = elig.payer
     and cond.claim_id = elig.claim_id
-where lower(condition_type) = 'discharge_diagnosis'
+where lower(condition_type) = 'discharge_diagnosis'
+    and hcc_code is not null

models/data_marts/hcc_recapture/intermediate/hccs/hcc_recapture__int_recapturable_hccs.sql

@@ -18,7 +18,7 @@ select
     , model_version
     , data_source
     , hcc_hierarchy_group
-    , suspect_hcc_flag
+    , external_hcc_flag
     , hcc_chronic_flag
     , min(hcc_hierarchy_group_rank) as min_hcc_hier_group_rank
 from base
@@ -29,7 +29,7 @@ group by
     , model_version
     , data_source
     , hcc_hierarchy_group
-    , suspect_hcc_flag
+    , external_hcc_flag
     , hcc_chronic_flag
 )
 
@@ -49,7 +49,7 @@ select
     , base.risk_model_code
     , base.eligible_bene_flag
     , base.rendering_npi
-    , base.suspect_hcc_flag
+    , base.external_hcc_flag
     , base.recapturable_flag
     , base.hcc_type
     , base.hcc_source
@@ -63,5 +63,5 @@ left join min_hierarchy as mhier
     and base.data_source = mhier.data_source
     and base.hcc_hierarchy_group = mhier.hcc_hierarchy_group
     and base.hcc_hierarchy_group_rank = mhier.min_hcc_hier_group_rank
-    and base.suspect_hcc_flag = mhier.suspect_hcc_flag
+    and base.external_hcc_flag = mhier.external_hcc_flag
     and base.hcc_chronic_flag = mhier.hcc_chronic_flag