riskaudit 0.1.1__tar.gz

riskaudit-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest --cov=riskaudit.audit --cov-fail-under=90

riskaudit-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

riskaudit-0.1.1/.gitignore

@@ -0,0 +1,36 @@
+# Data and artifacts are never versioned (PROTOCOL §1, guardrail 5)
+data/
+artifacts/
+*.dta
+*.zip
+*.parquet
+demo_report.html
+
+# Keep the data tree and the checksum manifest
+!data/
+!data/**/.gitkeep
+!data/checksums.txt
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS / editor
+desktop.ini
+Thumbs.db
+.DS_Store
+.idea/
+.vscode/

riskaudit-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=512]

riskaudit-0.1.1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## v0.1.1 — 2026-07-19
+
+- Published to PyPI: `pip install riskaudit`.
+- **Split dependencies:** the core auditor needs only `numpy`, `pandas`,
+  `scikit-learn`, `matplotlib`; the MEPS example's heavy stack (`lightgbm`, `shap`,
+  `pyreadstat`, …) moves to the `[meps]` extra.
+- PyPI packaging metadata (classifiers, project URLs).
+
+## v0.1.0 — 2026-07-19
+
+First release. The product is the **`riskaudit` auditing library**; the MEPS study
+and the synthetic demo are worked examples.
+
+### `riskaudit.audit`
+- `top_k_capture` — weighted top-k capture of need, reported against a random-score
+  floor (= k) and an oracle ceiling (ranking by need itself).
+- `reclassification` — weighted 2×2 of who enters and leaves the top-k when the label changes.
+- `label_choice_curve` — mean need across score percentiles, with a bootstrap band.
+- `ablation` — **cross-fitted** Δ global performance vs Δ capture of an independent
+  need measure, per feature group.
+- `regression_to_mean` — descriptive share of a top-k drop attributable to RTM
+  (weighted regression slope).
+- `incremental_lift` — the contribution metric: excess future outcome, in the
+  deprioritized tail, of the distressed over everyone else.
+- `audit_report` — self-contained HTML report.
+- `SurveyDesign` — stratified cluster (VARSTR/VARPSU) bootstrap CIs; warns on
+  single-PSU strata. Public inputs are validated (finite, equal length). ~99% test coverage.
+
+### Examples
+- **MEPS 2021–2023**: verified ETL, three comparable LightGBM models, full weighted
+  design-based audit. On this data the spend model captures need barely above chance
+  and under-serves the distressed on total cost; the effect does **not** appear on
+  non-psychiatric utilization, so that mechanism is not demonstrated (docs/methods.md §2).
+- **Synthetic demo** (`demo/run_demo.py`): end-to-end, no external data, no PHI.

riskaudit-0.1.1/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "riskaudit: auditing label-choice bias in healthcare risk-stratification models"
+abstract: >-
+  A Python library that audits any risk-stratification model for label-choice
+  bias: how much real need it leaves behind when trained on a proxy such as
+  healthcare spending. Ships with a reproducible MEPS example and a synthetic demo.
+authors:
+  - family-names: Proromant
+    given-names: Conrado
+version: 0.1.0
+date-released: 2026-07-19
+license: MIT
+repository-code: "https://github.com/CProromant/risk-equity-audit"
+doi: 10.5281/zenodo.21461268
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.21461268
+    description: "Concept DOI (resolves to the latest version)"
+keywords:
+  - algorithmic-fairness
+  - health-equity
+  - risk-stratification
+  - label-choice-bias

riskaudit-0.1.1/CLAUDE.md

@@ -0,0 +1,85 @@
+CLAUDE.md
+
+Read PROTOCOL.md first — it is the binding spec (architecture, data sources, phases, acceptance criteria). Execute phase by phase; do not advance with acceptance criteria unmet. This file governs how the code reads. On style, this file wins.
+
+Voice
+
+Write like one careful researcher who codes daily, not like a code generator. The test for every line: would a senior data scientist, writing quickly but well, produce it? If a line exists to explain the obvious, impress, or hedge, delete it.
+
+Comments
+
+
+Comments explain why, never what. If the code needs a what-comment, rewrite the code instead.
+No banner comments (# ===== Load data =====), no numbered-step comments, no comment restating the line below it.
+No chat residue, ever: "Here we...", "Note that...", "As requested", # rest of the code, placeholder TODOs.
+A file with zero comments is normal. Real TODOs are fine only when something is genuinely deferred: # TODO: two-part model (backlog, PROTOCOL §7). Never invent one.
+
+
+Docstrings
+
+
+Public API of riskaudit.audit: full NumPy-style docstrings with the exact math — PROTOCOL §4.4 requires it.
+Everything else: one line or nothing. No Args/Returns scaffolding on trivial functions. Never open with "This function".
+
+
+Structure
+
+
+Simplest thing that works. Functions over classes; a class must earn its existence with state plus behavior. No abstract bases, factories, or config objects for two parameters.
+Do not extract a helper before the third real use. Duplicating twice is cheaper than the wrong abstraction.
+Scripts read top to bottom: constants, functions, if __name__ == "__main__":. No framework ceremony.
+Let it crash. No try/except unless the except does something specific. Validate at data boundaries (ETL); trust internal calls.
+No logging framework. A terse print at script level for progress is fine. No emoji, no exclamation marks.
+
+
+Naming
+
+
+Domain shorthand a colleague would use: wt, k6, df, topk, oof, capture. Short names in tight scopes (i, col, m).
+Banned generator vocabulary: data, result, temp, process_, handle_, my_, _list/_dict suffixes, enhanced, comprehensive, robust, utils grab-bags.
+Type hints on public signatures. Skip locals and obvious internals.
+
+
+Pandas / analysis idiom
+
+
+Moderate method chains (2–4 steps), then a named intermediate. Never a ten-step chain; never .copy() reflexively.
+Vectorize. No iterrows unless unavoidable — and then one comment saying why.
+Test fixtures use MEPS-plausible values (ages 18–85, K6 in 0–24, right-skewed costs), never foo/bar or tidy round numbers.
+
+
+Tests
+
+
+Plain pytest functions, no test classes. One behavior per test; hand-computed expected values in the audit tests. Names describe behavior: test_capture_weights_change_result, not test_1.
+
+
+README and prose
+
+
+Plain and factual, first person singular where natural ("I use the Panel 26 file because..."). No emoji, no "Features 🚀", no comprehensive/leverages/seamless/state-of-the-art. Badges: CI, license, DOI — nothing else.
+
+
+Commits
+
+
+Subject ≤ 60 chars, imperative, conventional prefix per PROTOCOL §6. Body only when the why is not obvious: one to three plain sentences. Never bullet-list what the diff already shows. One logical change per commit — mixed commits are the strongest generator tell.
+
+
+Dependencies and imports
+
+
+Only what is used; stdlib first. No dependency for what ten lines of stdlib can do. Remove dead imports before committing.
+
+
+Hard limits — do not "humanize"
+
+
+Never introduce deliberate typos, bugs, dead code, or artificial inconsistency to look human. Human-quality means fewer defects, not planted ones.
+Never rewrite git history or fake timestamps or authorship.
+Formatter-enforced consistency (ruff) is normal for humans too. Keep it.
+
+
+Self-check before closing any file
+
+Read it once asking: is there any line whose existence could only be explained with "the tool put it there"? If yes, delete or rewrite until every line has a reason the author can state out loud — in a code review.

riskaudit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conrado Proromant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

riskaudit-0.1.1/Makefile

@@ -0,0 +1,28 @@
+# Windows: run these under Git Bash, or invoke the underlying scripts directly.
+.PHONY: download etl models audit demo all test lint format
+
+all: download etl models audit
+
+download:
+	python scripts/download_meps.py
+
+etl:
+	python scripts/build_panel.py
+
+models:
+	python scripts/train_models.py
+
+audit:
+	python scripts/run_audit.py
+
+demo:
+	python demo/run_demo.py
+
+test:
+	pytest
+
+lint:
+	ruff check .
+
+format:
+	ruff format .

riskaudit-0.1.1/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: riskaudit
+Version: 0.1.1
+Summary: Audit any risk-stratification model for label-choice bias — how much real need it leaves behind
+Project-URL: Homepage, https://github.com/CProromant/risk-equity-audit
+Project-URL: Repository, https://github.com/CProromant/risk-equity-audit
+Project-URL: Changelog, https://github.com/CProromant/risk-equity-audit/blob/main/CHANGELOG.md
+Author: Conrado Proromant
+License: MIT
+License-File: LICENSE
+Keywords: algorithmic-fairness,auditing,health-equity,label-choice-bias,risk-stratification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Provides-Extra: dev
+Requires-Dist: lightgbm; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyarrow; extra == 'dev'
+Requires-Dist: pyreadstat; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: shap; extra == 'dev'
+Provides-Extra: meps
+Requires-Dist: lightgbm; extra == 'meps'
+Requires-Dist: pyarrow; extra == 'meps'
+Requires-Dist: pyreadstat; extra == 'meps'
+Requires-Dist: pyyaml; extra == 'meps'
+Requires-Dist: requests; extra == 'meps'
+Requires-Dist: shap; extra == 'meps'
+Description-Content-Type: text/markdown
+
+# risk-equity-audit
+
+**Auditing label-choice bias in healthcare risk-stratification models — and the mental-health blind spot it creates.**
+
+`riskaudit` is a Python toolkit that audits *any* risk-stratification model for **label-choice bias**: the systematic error that appears when a model is trained on the wrong proxy for "need" (typically **healthcare spending**) instead of need itself. The tool is the product; a reproducible worked example on U.S. MEPS data shows it finds real bias.
+
+[![CI](https://github.com/CProromant/risk-equity-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/CProromant/risk-equity-audit/actions/workflows/ci.yml)
+![license](https://img.shields.io/badge/license-MIT-green)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21461268-blue)](https://doi.org/10.5281/zenodo.21461268)
+
+> **Project status.** **`v0.1.0` released** and archived on Zenodo (DOI above). The `riskaudit` auditing library is implemented and tested (7 functions, design-based CIs, ~99% coverage); the MEPS case study and a self-contained demo run end to end. Built phase by phase per [`PROTOCOL.md`](PROTOCOL.md) and [`PLAN.md`](PLAN.md).
+
+*(Versión en español más abajo — [ir al español](#español).)*
+
+---
+
+## What this is
+
+Health systems have limited budgets for expensive programs — case management, home visits, close follow-up — so a model decides **who gets prioritized**, usually by predicting who is "high risk." The catch is *how you define* high risk. Most deployed models define it as **"who will spend the most,"** because spending is recorded for everyone.
+
+That choice has a blind spot. Consider someone in psychological distress who **does not seek care**: their observed spending is near zero, so a spend-trained model labels them *low risk* and ignores them — and the concern is that untreated distress may surface next year as other medical need (ER visits, worsened physical illness). The need was there; the label never looked for it.
+
+This is **label-choice bias**: a well-documented failure where an algorithm trained on cost as a proxy for need under-serves people whose need hasn't yet turned into spending. This project applies that lens to **untreated mental-health need** and packages the audit as a reusable tool.
+
+**The claim in one sentence:** a risk model trained on healthcare spending captures barely more measured need than a coin flip and systematically under-serves people in psychological distress — because the *label* (spending), not the algorithm, decides who counts as high risk. This project measures that label-choice cost on MEPS.
+
+---
+
+## What's in the box
+
+1. **`riskaudit`** — an installable Python package that audits label-choice bias in any risk-stratification model. **This is the product:** a reusable tool that does not depend on any particular dataset.
+2. **A worked example on MEPS 2021–2023** — a reproducible pipeline (three targets, identical models, full audit) that shows the tool finds real bias on U.S. survey data. It is a demonstration, not the point.
+3. **End-to-end demo** — a self-contained synthetic run (`demo/run_demo.py`), with **no credentials and no PHI**, so anyone can see the tool working in seconds.
+
+---
+
+## The `riskaudit` toolkit
+
+`riskaudit` does **not** train models or make predictions. It is an **auditor**: give it the scores a model assigned and an independent measure of real need, and it quantifies how much need the model leaves behind — with population weights and confidence intervals (a plain row bootstrap, or a design-based one over survey strata/PSUs).
+
+Because it works purely on scores and a need measure, `riskaudit` is **domain- and country-agnostic**: the same functions audit a hospital's readmission model, an insurer's cost model, or a ministry's triage algorithm. The MEPS mental-health study below is one worked example showing the tool finds real bias — an illustration, not the tool's scope.
+
+| Function | Question it answers |
+|---|---|
+| `top_k_capture(scores, need, k, weights)` | Of all real need in the population, what fraction lands in the top-*k* the model prioritizes? |
+| `reclassification(scores_a, scores_b, k, weights)` | If we switch the label from A to B, **who** enters and leaves the priority list? |
+| `ablation(fit_fn, X, y, feature_groups, k, weights)` | If we remove a feature group and retrain, how much does *global performance* drop vs. how much does *capture of that group* collapse? |
+| `label_choice_curve(scores, need, weights, bins)` | Curve of score percentile vs. observed mean need — where does high need sit on the score? |
+| `regression_to_mean(y_t, y_t1, scores_t, k, weights)` | How much of the top-*k* spending drop from year *t* to *t+1* is just regression to the mean? |
+| `incremental_lift(y_t1, y_pred, distress, scores, k, weights)` | **The contribution metric:** among people the model deprioritizes, do those with measured need generate *more future outcome than predicted* than the rest? Makes the argument non-circular. |
+| `audit_report(results, out_html)` | Bundles everything into a self-contained HTML report. |
+
+**What the audit finds on MEPS** (weighted, with design-based confidence intervals): the spend-trained model captures only ~15% of top-decile K6 need — barely above the ~10% a random score gets, and far below the ~41% an oracle (ranking by need itself) reaches; a need-trained model reaches ~29%. Among the people the spend model deprioritizes, those in distress run up more *total* future cost than it predicted (incremental lift +0.8 log-dollars with the mental-health features, +1.0 without — both 95% CIs exclude zero), so the bias comes from the **label, not from missing information**.
+
+**Honest limit.** That excess does **not** appear on non-psychiatric utilization (ER + hospitalizations; lift ≈ 0, CI includes zero), so we do *not* claim the distress surfaces specifically as non-psychiatric spending — the total-spend excess may be partly mental-health spending, and a clean test needs a non-psychiatric spend target (backlog). The severe-untreated subgroup (n ≈ 40) is descriptive only.
+
+---
+
+## Install
+
+> Requires Python ≥ 3.11. Until the first release is published, install from source:
+
+```bash
+git clone https://github.com/<user>/risk-equity-audit.git
+cd risk-equity-audit
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Minimal end-to-end audit on your own model's scores:
+
+```python
+import numpy as np
+from riskaudit.audit import top_k_capture, label_choice_curve, audit_report
+
+rng = np.random.default_rng(2026)
+n = 5_000
+scores  = rng.random(n)            # what your risk model output per person
+need    = rng.random(n)            # an independent measure of real need
+weights = rng.random(n)            # survey / population weights
+
+capture = top_k_capture(scores, need, k=0.10, weights=weights)
+curve   = label_choice_curve(scores, need, weights=weights, bins=20)
+
+print(f"Top-decile capture of need: {capture.value:.1%}")
+audit_report({"capture": capture, "curve": curve}, out_html="audit.html")
+```
+
+The audit API above runs today, and a self-contained synthetic demo shows the whole flow end to end:
+
+```bash
+python demo/run_demo.py   # no real data, no PHI, a few seconds, writes demo_report.html
+```
+
+---
+
+## Data sources
+
+No data is stored in this repository. Only download scripts and checksums are versioned; everything under `data/` is git-ignored.
+
+- **Core — MEPS (AHRQ, U.S.):** HC-233 (2021), HC-243 (2022), HC-251 (2023), **HC-244 (Panel 26 Longitudinal 2021–2022)**, plus **HC-231** (2021 Conditions) and **HC-229A** (2021 Prescribed Medicines) for the mental-health treatment proxy — free, no registration; downloaded with SHA-256 checksums. See [`PROTOCOL.md`](PROTOCOL.md) §3 for exact files, weights, and codebook references.
+- **Synthetic (demo):** generated in-script by `demo/run_demo.py` — no external data, no real patients.
+
+---
+
+## Limitations
+
+Honesty about limits is a feature of this project, not a footnote:
+
+- **The severe untreated subgroup is small** (~135 people have severe distress, K6 ≥ 13, in both panel years; the untreated subset is smaller still). It is reported **descriptively, with wide confidence intervals** — never modeled. The robust finding is the population-level mechanism, not an anecdote about invisible patients.
+- **"Need" is a normative choice.** Calling a model "biased" requires asserting which target is the legitimate measure of need. That judgment is stated and defended in `docs/methods.md`, not assumed.
+- **Survey design is respected throughout** — final results always use sample weights and design-based variance (a stratified cluster bootstrap over VARSTR/VARPSU, with subpopulation/domain estimation), never unweighted or naïvely filtered.
+
+---
+
+## Roadmap · Hoja de ruta
+
+Built phase by phase (see [`PLAN.md`](PLAN.md) for task-level detail and acceptance criteria):
+
+- **Phase 0** ✅ — Scaffolding: package layout, CI, tooling.
+- **Phase 1** ✅ — MEPS ETL: verified data dictionary, cleaned panel (6,741 persons).
+- **Phase 2** ✅ — Models + full weighted, design-based audit on MEPS.
+- **Phase 3** ✅ — `riskaudit.audit` API (~99% coverage) + self-contained synthetic demo.
+- **Phase 4** ✅ — Release `v0.1.0`, archived on Zenodo ([10.5281/zenodo.21461268](https://doi.org/10.5281/zenodo.21461268)).
+
+## How to cite
+
+If you use `riskaudit`, please cite it:
+
+> Proromant, C. (2026). *riskaudit: auditing label-choice bias in healthcare risk-stratification models* (v0.1.0) [Software]. Zenodo. https://doi.org/10.5281/zenodo.21461268
+
+Machine-readable metadata is in [`CITATION.cff`](CITATION.cff).
+
+## License
+
+[MIT](LICENSE) © Conrado — MD (PUC), MSc(c) Data Science (PUC).
+
+---
+---
+
+<a name="español"></a>
+
+# risk-equity-audit (español)
+
+**Auditoría del sesgo por elección de etiqueta en modelos de estratificación de riesgo en salud — y el punto ciego de salud mental que produce.**
+
+`riskaudit` es una herramienta en Python que audita *cualquier* modelo de estratificación de riesgo en busca de **sesgo por elección de la etiqueta** (*label-choice bias*): el error sistemático que aparece cuando el modelo se entrena con un proxy equivocado de "necesidad" (típicamente el **gasto sanitario**) en lugar de la necesidad misma. La herramienta es el producto; un ejemplo reproducible sobre datos de MEPS (EE.UU.) muestra que encuentra sesgo real.
+
+> **Estado del proyecto.** **`v0.1.0` publicado** y archivado en Zenodo (DOI arriba). La librería de auditoría `riskaudit` está implementada y testeada (7 funciones, IC de diseño, ~99% de cobertura); el estudio MEPS y un demo auto-contenido corren de punta a punta. Construido por fases según [`PROTOCOL.md`](PROTOCOL.md) y [`PLAN.md`](PLAN.md).
+
+## Qué es esto
+
+Los sistemas de salud tienen presupuesto limitado para programas caros —gestión de caso, visitas domiciliarias, seguimiento cercano— así que un modelo decide **a quién se prioriza**, normalmente prediciendo quién es "de alto riesgo". El problema está en *cómo se define* ese alto riesgo. La mayoría de los modelos desplegados lo definen como **"quién va a gastar más"**, porque el gasto está registrado para todos.
+
+Esa elección tiene un punto ciego. Pensemos en una persona con distrés psíquico que **no consulta**: su gasto observado es casi cero, así que un modelo entrenado con gasto la etiqueta como *bajo riesgo* y la ignora — y la inquietud es que el distrés no tratado pueda reaparecer al año siguiente como otra necesidad médica (urgencias, enfermedades físicas agravadas). La necesidad estaba; la etiqueta nunca la buscó.
+
+Esto es el **sesgo por elección de la etiqueta**: una falla bien documentada en la que un algoritmo entrenado con el costo como proxy de necesidad sub-atiende a quienes su necesidad aún no se tradujo en gasto. Este proyecto aplica esa mirada a la **necesidad de salud mental no tratada** y empaqueta la auditoría como herramienta reutilizable.
+
+**La idea en una frase:** un modelo de riesgo entrenado con gasto sanitario captura la necesidad medida apenas por encima del azar y sub-atiende sistemáticamente a las personas con distrés psíquico — porque es la *etiqueta* (el gasto), no el algoritmo, la que decide quién es de alto riesgo. Este proyecto mide ese costo de la elección de etiqueta con MEPS.
+
+## Qué incluye
+
+1. **`riskaudit`** — paquete Python instalable que audita el sesgo por elección de etiqueta en cualquier modelo de estratificación de riesgo. **Es el producto:** una herramienta reutilizable que no depende de ninguna base en particular.
+2. **Un ejemplo demostrativo sobre MEPS 2021–2023** — pipeline reproducible (tres targets, modelos idénticos, auditoría completa) que muestra que la herramienta encuentra sesgo real con datos de EE.UU. Es una demostración, no el objetivo.
+3. **Demo end-to-end** — una corrida auto-contenida sobre datos sintéticos (`demo/run_demo.py`), **sin credenciales ni datos sensibles**, en segundos.
+
+## La herramienta `riskaudit`
+
+`riskaudit` **no** entrena modelos ni predice. Es un **auditor**: le das los puntajes que asignó un modelo y una medida independiente de necesidad real, y cuantifica cuánta necesidad el modelo deja fuera — con pesos poblacionales e intervalos de confianza (bootstrap de filas, o de diseño sobre estratos/PSU de la encuesta).
+
+Como trabaja solo con puntajes y una medida de necesidad, `riskaudit` es **agnóstico al dominio y al país**: las mismas funciones auditan el modelo de reingresos de un hospital, el de gasto de una aseguradora o el algoritmo de priorización de un ministerio. El estudio MEPS de salud mental de abajo es un ejemplo demostrativo que muestra que la herramienta encuentra sesgo real — una ilustración, no el alcance de la herramienta.
+
+| Función | Pregunta que responde |
+|---|---|
+| `top_k_capture` | De toda la necesidad real de la población, ¿qué fracción cae en el top-*k* que prioriza el modelo? |
+| `reclassification` | Si cambio la etiqueta de A a B, ¿**quién** entra y sale de la lista de prioridad? |
+| `ablation` | Si quito un grupo de features y reentreno, ¿cuánto baja el *desempeño global* vs. cuánto se desploma la *captura* de ese grupo? |
+| `label_choice_curve` | Curva de percentil de score vs. necesidad observada media — ¿dónde cae la necesidad alta en el score? |
+| `regression_to_mean` | ¿Cuánto de la caída de gasto del top-*k* entre *t* y *t+1* es solo regresión a la media? |
+| `incremental_lift` | **La métrica-contribución:** entre los que el modelo deprioriza, ¿los que tienen necesidad medida generan *más desenlace futuro del predicho* que el resto? Hace no-circular el argumento. |
+| `audit_report` | Empaqueta todo en un informe HTML autocontenido. |
+
+**Lo que encuentra la auditoría en MEPS** (ponderado, con IC de diseño): el modelo de gasto captura solo ~15% de la necesidad K6 del top-decil — apenas sobre el ~10% que daría un score al azar, y muy por debajo del ~41% de un oráculo (rankear por la propia necesidad); un modelo de K6 llega a ~29%. Entre las personas que el modelo de gasto deprioriza, las que están en distrés acumulan más gasto *total* futuro del que el modelo predijo (lift incremental +0.8 log-dólares con las features de salud mental, +1.0 sin ellas — ambos IC 95% excluyen el cero), así que el sesgo viene de la **etiqueta, no de falta de información**.
+
+**Límite honesto.** Ese exceso **no** aparece en la utilización no-psiquiátrica (urgencias + hospitalizaciones; lift ≈ 0, IC incluye el cero), así que **no** afirmamos que el distrés se manifieste específicamente como gasto no psiquiátrico — el exceso de gasto total puede ser en parte gasto en salud mental, y un test limpio necesita un target de gasto no-psiquiátrico (backlog). El subgrupo severo no tratado (n ≈ 40) es solo descriptivo.
+
+## Instalación y quickstart
+
+Igual que en la sección en inglés (Python ≥ 3.11, `pip install -e ".[dev]"`). El ejemplo mínimo de la API funciona hoy, y un demo auto-contenido muestra el flujo completo: `python demo/run_demo.py` (sin datos reales, sin PHI, segundos).
+
+## Limitaciones
+
+La honestidad sobre los límites es parte del proyecto, no una nota al pie:
+
+- **El subgrupo severo no tratado es pequeño** (~135 personas con distrés severo, K6 ≥ 13, en ambos años del panel; el subgrupo *sin tratamiento* es aún menor): se reporta **descriptivamente, con IC anchos**, nunca se modela. El hallazgo robusto es el mecanismo poblacional, no la anécdota de "los invisibles".
+- **"Necesidad" es una elección normativa.** Llamar "sesgado" a un modelo exige afirmar cuál es la vara legítima de necesidad. Ese juicio se declara y defiende en `docs/methods.md`.
+- **El diseño muestral se respeta siempre:** los resultados finales usan pesos y varianza basada en el diseño (bootstrap de clúster estratificado sobre VARSTR/VARPSU, con estimación de subpoblación/dominio).
+
+## Licencia
+
+[MIT](LICENSE) © Conrado — Médico (PUC), MSc(c) Data Science (PUC).