A Python User's Guide to Running the CMS-HCC Risk Adjustment Model
Medicare Advantage plans run the CMS-HCC risk adjustment model to secure accurate CMS payments, pinpoint enrollees with potential HCC discrepancies, and identify high-risk members for targeted disease management. Traditionally, operating CMS's software necessitates a SAS® license. However, MScore ® by riskadjustmentmodel.com presents a streamlined, user-friendly alternative that supports various operating systems and programming languages. This article introduces MScore® and offers a practical guide for using the software via Python.
Value Proposition of MScore®
MScore® is a SAS®-free alternative to perform CMS-HCC risk score calculations. It relieves organizations of the burden of coding the risk model and making revisions when a new version is released. MScore® enables organizations to harness the power of cloud and open-source technologies. It is compatible with Mac, Windows and Linux operating systems, underscoring its versatility. Whether utilized as a Python Package, through a command-line interface (CLI), or via an API integration, MScore® can be tailored to meet your diverse operational needs.
Highlighted Features of MScore®:
Up-to-Date: Supporting CMS-HCC models from 2021-2025, including v28, MScore® stays up-to-date with the latest CMS release.
Cross-Platform Compatibility: MScore® offers an easy-to-use solution that's not limited to a single programming language, OS, or computing environment.
Flexibility: Whether you prefer using a python package, CLI, or API, MScore® caters to diverse technical needs and preferences.
Rich Support: A variety of resources and integration support options ensures you can maximize the utility of MScore®.
Running MScore® using Python
To demonstrate MScore®'s practical application, we'll walk you through a Python workflow that includes: 1) executing a model run with MScore®, 2) generating a bar graph using Jupyter Notebook, and 3) visualizing the results.
Python dependencies:
Please ensure you complete this installation step before proceeding to execute the model.
To run the script, you'll need Person and Diagnosis data file along with a license key, which can be obtained by registering Here
Step 1: Executing a Model Run with MScore®
Below, we present Python code for loading the input files needed to run MScore®. Start by reading the Diag and Person CSV files, and then proceed to execute the MScore® application. In this example, we will write the script in the Jupyter Notebook extension on VSCode.
from mscore import AuthorizeLicense, MScore
import pandas as pd
from pathlib import Path
import plotly.express as px
import plotly.io as pio
from IPython.display import display
# Read person and diagnosis data from CSV files into pandas DataFrames
person_df = pd.read_csv('person.csv')
diag_df = pd.read_csv('diag.csv')
# Define the staging key for authorization
staging_key = "<your_license_key>"
# Validate the authorization using the staging key
auth = AuthorizeLicense(staging_key).validate()
# The MScore® class requires 7 arguments in order to run with 2 optional arguments.
model = MScore(
authorizer=auth,
year='2024',
version='V24',
model='CMS-HCC',
person_data=person_df,
diag_data=diag_df,
columns='all-fields',
rf_output=True,
)
# Calculate the risk scores using the MScore® model
v24_2024_scores = model.score_mscore()
# Create DataFrames from the risk scores and relative factors
scores = pd.DataFrame(v24_2024_scores.risk_scores)
relative_factors = pd.DataFrame(v24_2024_scores.relative_factors)
Step 2: Generating Bar Graph
Generate a bar graph visualizing average risk scores by model segment using Plotly Express, updates the plot's trace properties and layout, adds an annotation, and then displays the plot in a Jupyter Notebook.
df = pd.DataFrame(
[{i.split('_')[0]: round(scores[i].mean(), 3) for i in scores.columns if '_SCORE' in i}]
)
# Create a bar plot using Plotly Express
fig = px.bar(
df.values,
x=df.columns.tolist(),
y=df.values[0],
color_discrete_sequence=['green'],
title="Average Risk Score by Model Segment (V28): Synthetic Population",
labels={
"y": "Average Score",
"x": "Model Segment"
},
text_auto=True
)
# Update the plot's trace properties
fig.update_traces(textfont_size=12, textangle=0, textposition="inside")
# Update the plot's layout
fig.update_layout(
autosize=False,
width=1000,
height=700,
margin={'b': 100}
)
# Add an annotation to the plot
fig.add_annotation(
showarrow=False,
text="""
CNA: Community Non-dual aged, CND: Community Non-dual disabled, CFA: Community Full Benefit dual aged
CFD: Community Full Benefit dual disabled, CPA: Community Partial Benefit dual aged, CPD: Community Partial Benefit dual disabled
INS: Institutional, NE: New enrollee, SNPNE: C-SNP New enrollee
""",
align="left",
font=dict(size=8),
xref='x domain',
x=-0.01,
yref='paper',
y=-.18
)
# Set the default renderer to 'notebook' for Jupyter Notebooks
pio.renderers.default = "notebook"
# Display the plot
display(fig)
Step 3: Visualizing Average Risk Scores with Plotly
Finally, for visualizing the results, we use Plotly Express to create a bar chart, allowing us to examine specific descriptive statistics from our dataset. In this case, we focus on the average score by model segment. While MScore® uses abbreviations for these segments, our chart includes annotations with their full names for easy reference (see the list below):
- INS: Institutional
- CFA: Community Full Benefit dual aged
- CFD: Community Full Benefit dual disabled
- CPA: Community Partial Benefit dual aged
- CPD: Community Partial Benefit dual disabled
- CNA: Community Non-dual aged
- CND: Community Non-dual disabled
- NE: New enrollee
- SNPNE: C-SNP New enrollee
Conclusion
This straightforward three-step Python process enables you to run the MScore® CMS-HCC model efficiently, handle the output adeptly, and use visualization tools for insightful analysis. MScore®, known for its Python compatibility, offers significant benefits to data-driven healthcare organizations by streamlining data operations with a modern approach.
As the volume and complexity of healthcare data continue to escalate, tools like MScore® become indispensable in simplifying essential operations and reducing costs. With the combination of MScore® and Python, your organization is well-equipped to adeptly manage CMS-HCC risk adjustments, ensuring precise CMS payments for the care provided to Medicare enrollees.
Disclaimer : The code examples above are for illustrative purposes and may require proper environment setup, license keys, or additional parameters to work effectively in your specific context. Always refer to MScore® documentation or reach out to support@riskadjustmentmodel.com if you have questions.