Update README.md

README.md

@@ -1,9 +1,71 @@
 ---
 license: apache-2.0
 ---
-LogiSHAP-Studio-LogReg/
-│
-├── model.joblib            # sklearn pipeline (preprocess + logistic regression)
-├── meta.json               # metrics, feature types, label mapping
-├── requirements.txt        # optional, for reproducibility
-└── README.md               # model card
+# ExplainML Studio – Logistic Regression Models
+
+This repository hosts **versioned, trained machine learning models** produced using the **ExplainML Studio** framework.  
+The current releases implement **logistic regression pipelines with full explainability and clinical evaluation artifacts**.
+
+These models are designed for **transparent, auditable, and clinically interpretable binary classification tasks**.
+
+---
+
+## Model Overview
+
+- **Framework:** ExplainML Studio
+- **Algorithm:** Logistic Regression (scikit-learn)
+- **Pipeline:**  
+  - Numeric features → median imputation + standard scaling  
+  - Categorical features → most-frequent imputation + one-hot encoding  
+- **Explainability:** SHAP (LinearExplainer)
+- **Output:** Predicted probability (0–1)
+
+Each model is packaged as a single `model.joblib` file containing the full preprocessing + classifier pipeline.
+
+---
+
+## Evaluation Metrics (stored in `meta.json`)
+
+All models are evaluated on a **held-out test split** and include the following:
+
+### Discrimination
+- ROC AUC
+- ROC curve (FPR, TPR, thresholds)
+- Precision–Recall curve
+- Average Precision (AP)
+
+### Classification (default threshold = 0.5)
+- Sensitivity (Recall)
+- Specificity
+- Precision
+- F1 score
+- Accuracy
+- Balanced accuracy
+- Confusion matrix (TP, FP, TN, FN)
+
+### Calibration
+- Calibration (reliability) curve
+- Brier score
+- Configurable binning strategy (uniform / quantile)
+
+### Clinical Utility
+- Decision Curve Analysis (DCA)
+- Net benefit curves:
+  - Model
+  - Treat-all
+  - Treat-none
+
+All metrics and curve data are stored explicitly in `meta.json` for reproducibility and downstream analysis.
+
+---
+
+## Repository Structure
+
+releases/
+└── <version>/
+├── model.joblib # trained sklearn pipeline
+└── meta.json # schema + metrics + curves
+latest/
+├── model.joblib
+└── meta.json
+README.md