Update README.md

README.md

@@ -6,6 +6,7 @@ colorTo: purple
 sdk: static
 pinned: false
 ---
+
 # Tuva Project: Open-Source Healthcare Modeling
 
 Welcome to the Tuva ML Models Hub — an open-source ecosystem for healthcare risk prediction, cost benchmarking, and expected value modeling.
@@ -18,9 +19,10 @@ The Tuva Project is dedicated to democratizing healthcare knowledge.
 We believe that access to robust models should not be locked behind paywalls or proprietary systems.
 
 These models are typically:
-- Expensive to build and maintain
-- Trained on complex healthcare data
-- Essential for policy, research, and actuarial strategy
+
+- Expensive to build and maintain  
+- Trained on complex healthcare data  
+- Essential for policy, research, and actuarial strategy  
 
 By open-sourcing these tools, we empower health systems, researchers, and startups to build with transparency and scale with trust.
 
@@ -30,16 +32,95 @@ By open-sourcing these tools, we empower health systems, researchers, and startu
 
 This hub is a growing library of machine learning models designed to support:
 
-- Cost prediction
-- Encounter forecasting
-- Risk stratification
-- Benchmarking for Medicare, Medicaid, and commercial populations
+- Cost prediction  
+- Encounter forecasting  
+- Risk stratification  
+- Benchmarking for Medicare, Medicaid, and commercial populations  
 
 Each model includes:
 
-- Trained model artifacts (e.g., `.pkl`, `.joblib`)
-- Scripts for running predictions
-- Complete documentation and evaluation metrics
+- Trained model artifacts (e.g., `.pkl`, `.joblib`)  
+- Scripts for running predictions  
+- Complete documentation and evaluation metrics  
+
+---
+
+## Quick Start: End-to-End Workflow
+
+This section provides high-level instructions for running a model with the Tuva Project. The workflow involves preparing benchmark data using dbt, running a Python prediction script, and optionally ingesting the results back into dbt for analysis.
+
+### 1. Configure Your dbt Project
+
+You need to enable the correct variables in your `dbt_project.yml` file to control the workflow.
+
+#### A. Enable Benchmark Marts
+
+These two variables control which parts of the Tuva Project are active. They are `false` by default.
+
+```yaml
+# in dbt_project.yml
+vars:
+  benchmarks_train: true
+  benchmarks_already_created: true
+```
+
+- `benchmarks_train`: Set to `true` to build the datasets that the ML models will use for making predictions.  
+- `benchmarks_already_created`: Set to `true` to ingest model predictions back into the project as a new dbt source.
+
+#### B. (Optional) Set Prediction Source Locations
+
+If you plan to bring predictions back into dbt for analysis, you must define where dbt can find the prediction data.
+
+```yaml
+# in dbt_project.yml
+vars:
+  predictions_person_year: "{{ source('benchmark_output', 'person_year') }}"
+  predictions_inpatient: "{{ source('benchmark_output', 'inpatient') }}"
+```
+
+#### C. Configure `sources.yml`
+
+Ensure your `sources.yml` file includes a definition for the source you referenced above (e.g., `benchmark_output`) that points to the database and schema where your model's prediction outputs are stored.
+
+---
+
+### 2. The 3-Step Run Process
+
+This workflow can be managed by any orchestration tool (e.g., Airflow, Prefect, Fabric Notebooks) or run manually from the command line.
+
+#### Step 1: Generate the Training & Benchmarking Data
+
+Run the Tuva Project with `benchmarks_train` enabled. This creates the input data required by the ML model.
+
+```bash
+dbt build --vars '{benchmarks_train: true}'
+```
+
+To run only the benchmark mart:
+
+```bash
+dbt build --select tag:benchmarks_train --vars '{benchmarks_train: true}'
+```
+
+#### Step 2: Run the Prediction Python Code
+
+Execute the Python script to generate predictions. This script will read the data created in Step 1 and write the prediction outputs to a persistent location (e.g., a table in your data warehouse).
+
+*We have provided example Snowflake Notebook code within each model's repository that was used in Tuva's environment.*
+
+#### Step 3: (Optional) Analyze Predictions in dbt
+
+To bring the predictions back into the Tuva Project for analysis, run dbt again with `benchmarks_already_created` enabled. This populates the analytics marts.
+
+```bash
+dbt build --vars '{benchmarks_already_created: true, benchmarks_train: false}'
+```
+
+To run only the analysis models:
+
+```bash
+dbt build --select tag:benchmarks_analysis --vars '{benchmarks_already_created: true, benchmarks_train: false}'
+```
 
 ---
 
@@ -47,13 +128,13 @@ Each model includes:
 
 Our initial models use de-identified CMS data to calculate:
 
-- Expected values for paid amounts and encounter counts at the member-year level
-- Readmission rate
-- Discharge location
-- Length of stay
-
+- Expected values for paid amounts and encounter counts at the member-year level  
+- Readmission rate  
+- Discharge location  
+- Length of stay  
 
 Models like the **Encounter Cost Prediction Model** are trained on the 2020 Medicare Standard Analytic Files (SAF), using standardized preprocessing and evaluation pipelines.
+
 Models trained on 2022 and 2023 data are coming soon.
 
 ---
@@ -62,8 +143,8 @@ Models trained on 2022 and 2023 data are coming soon.
 
 We are expanding to include:
 
-- Commercial claims models (e.g., ESI, employer-based populations)
-- Medicaid utilization and cost models
+- Commercial claims models (e.g., ESI, employer-based populations)  
+- Medicaid utilization and cost models  
 
 ---
 
@@ -73,12 +154,10 @@ This hub is open to community contributions.
 
 If you're working on a healthcare machine learning model and want to share it:
 
-1. Fork one of our repositories
-2. Upload your trained model and code
-3. Document your inputs, outputs, and evaluation
-4. Open a pull request or reach out to our team
-
-
+1. Fork one of our repositories  
+2. Upload your trained model and code  
+3. Document your inputs, outputs, and evaluation  
+4. Open a pull request or reach out to our team  
 
 We believe risk modeling should be open infrastructure.  
 Help us build a future where healthcare knowledge is free and shared.