Skip to main content

Getting Started

CMS TEAM Analyzer runs in your dbt project alongside The Tuva Project. If Tuva is already installed and your claims data is conformed to Tuva core models, installation is a standard dbt package workflow.

Add The Package​

Add CMS TEAM Analyzer to packages.yml in the dbt project where Tuva is already installed:

packages:
  - package: tuva-health/the_tuva_project
    version: [">=0.17.0", "<1.0.0"]
  - git: "https://github.com/illuminatehealth/cms-team-analyzer.git"
    revision: main

Then run:

dbt deps
dbt seed --full-refresh --select package:cms_team_analyzer
dbt run --select +package:cms_team_analyzer
dbt test --select package:cms_team_analyzer

If your project already imports Tuva elsewhere in packages.yml, do not add a duplicate Tuva entry. Add CMS TEAM Analyzer alongside the existing Tuva package entry.

Configuration Defaults​

No vars are strictly required for the package to compile because defaults are built in. Production teams should still set the reporting-period and spend-basis vars deliberately so business users know exactly what period and payment basis the marts represent.

Common starter configuration:

vars:
  team_baseline_start_date: "2023-01-01"
  team_baseline_end_date: "2025-12-31"
  team_performance_year: 2026
  team_performance_start_date: "2026-01-01"
  team_performance_end_date: "2026-12-31"
  team_census_division: CENS_DIV_8
  team_spend_basis: paid_amount

Default values:

VarDefaultRequired to set?Notes
team_baseline_start_date2023-01-01NoUsed for local directional baseline estimates
team_baseline_end_date2025-12-31NoUsed for local directional baseline estimates
team_performance_year2026NoUsed for target-price lookup and reporting
team_performance_start_date2026-01-01NoUsed by performance-period marts
team_performance_end_date2026-12-31NoUsed by performance-period marts
team_census_divisionCENS_DIV_8NoUsed for public CMS regional target-price fallback
team_spend_basispaid_amountNoRecommended starting point for CCLF-based installs
team_snapshot_datenullNoWhen unset, package logic uses the current run context for snapshot reporting

For CCLF-based projects, start with paid_amount or a CCLF net-paid proxy if your connector provides one. Standard CCLF allowed amount fields are not populated consistently across claim settings; in particular, allowed amounts are generally not a usable complete episode-spend basis for institutional claims.

Run The Dashboard​

After package marts are built, launch the Streamlit dashboard:

cd cms-team-analyzer
pip install -r requirements-streamlit.txt
PYTHONPATH=. streamlit run streamlit_app/Home.py

The app can read connection details from direct environment variables or from a dbt profile.

Local DuckDB builds (development and demos):

TEAM_STREAMLIT_DUCKDB_PATH="/path/to/your.duckdb"

DuckDB allows one writer at a time, so stop the dashboard before rebuilding the database with dbt, then relaunch.

Cloud warehouse connections:

TEAM_STREAMLIT_ODBC_CONNECTION_STRING="..."
TEAM_STREAMLIT_DATABASE="..."
TEAM_STREAMLIT_SCHEMA="..."

Useful profile overrides:

TEAM_STREAMLIT_DBT_PROFILE="illuminate_fabric_dev"
TEAM_STREAMLIT_DBT_TARGET="dev"

If the selected dbt profile target is a duckdb target, the app uses its path automatically.