Merge pull request #557 from slsgzs-cloud/fix-docs-545-546-554-555-556

fix: doc corrections for COMPAS reduction, Benefits Denial proxies, ROADMAP staleness (fixes #545, #546, #555)

Author: yakew7

Benefits Denial/README.md

@@ -19,7 +19,7 @@ python3 "Benefits Denial/fair.py"     # mitigated (protected attribute + proxies
 ## What the audit controls
 
 - Protected attribute(s): Sex, Race, Origin, Age
-- Proxy feature(s) removed in `fair.py`: Relationship, Marital Status, Hours, Occupation
+- Proxy feature(s) removed in `fair.py`: Relationship, Marital Status, Hours, Occupation, fnlwgt
 - Fairness metric: Demographic Parity (difference in positive-prediction rate between groups)
 
 ## Expected result (published, paper-aligned)

COMPAS/README.md

@@ -26,6 +26,6 @@ python3 "COMPAS/fair.py"     # mitigated (protected attribute + proxies dropped)
 
 | Group | Gap, biased (`unfair.py`) | Gap, mitigated (`fair.py`) | Reduction |
 |-------|--------------------------:|---------------------------:|----------:|
-| Race | 86.77% | 15.69% | 71% |
+| Race | 86.77% | 15.69% | 82% |
 
 These match the "Results at a Glance" table in the [main README](../README.md#results-at-a-glance) and the frozen snapshot in `paper/results-frozen/`. The scripts are deterministic at `random_state=42`, so a correct local run reproduces them exactly. If your numbers differ, check the seed, the split, and your package versions before opening an issue - and never edit the frozen numbers to match a local run (see [CLAUDE.md](../CLAUDE.md)).

README.md

@@ -68,12 +68,12 @@ Each audit ships as both a pair of Python scripts (`unfair.py` / `fair.py`) for
 
 | # | Domain | Protected Attribute | Proxies Removed | Gap Before → After | Reduction |
 |:-:|--------|--------------------|-----------------|--------------------|:---------:|
-| 01 | [Criminal Justice](#01--compas--criminal-justice-bias) | Race | Custody Status | 86.77% → 15.69% | **71%** |
+| 01 | [Criminal Justice](#01--compas--criminal-justice-bias) | Race | Custody Status | 86.77% → 15.69% | **82%** |
 | 02 | [Hiring](#02--ai-fair-recruitment--hiring-bias) | Gender | Age | 4.51% → 0.12% | **97.3%** |
 | 03 | [Lending](#03--german-credit-lending--lending-bias) | Age | Employment Tenure | 7.16% → 1.89% | **73.6%** |
 | 04 | [Healthcare](#04--insurance-denial--healthcare-bias) | Age, Gender | BMI, Smoker, Diabetic | Age: 7.93% → 3.18% | **60%** |
 | ↳  | | | | Gender: 5.44% → 1.54% | **72%** |
-| 05 | [Welfare](#05--benefits-denial--welfare-eligibility-bias) | Sex, Race, Origin, Age | Relationship, Marital Status, Hours, Occupation | Sex: 18.00% → 8.52% | **53%** |
+| 05 | [Welfare](#05--benefits-denial--welfare-eligibility-bias) | Sex, Race, Origin, Age | Relationship, Marital Status, Hours, Occupation, fnlwgt | Sex: 18.00% → 8.52% | **53%** |
 | ↳  | | | | Race: 12.75% → 6.90% | **46%** |
 | ↳  | | | | Origin: 4.40% → 0.52% | **88%** |
 | 06 | [Healthcare Readmission](#06--healthcare-readmission--clinical-bias) | Race, Gender, Age | Payer Code, Discharge Disposition, Medical Specialty, Prior Inpatient | Gender: 0.02% → 0.04% | **+100% ↑** |
@@ -367,11 +367,11 @@ X = pd.get_dummies(df[[
 
 | Group | High-Risk Flag Rate |
 |-------|:-------------------:|
-| Black Defendants | 84.71% |
+| Black Defendants | 84.82% |
 | White Defendants | 69.02% |
 | **New Fairness Gap** | **15.69%** |
 
-**Result: 71% reduction in the fairness gap.**
+**Result: 82% reduction in the fairness gap.**
 
 > **Key insight:** Removing race alone isn't enough. Proxy variables like custody status carry the same racial signal because of historical over-policing of Black communities. Both the protected attribute *and* its proxies must be removed.
 
@@ -550,8 +550,8 @@ Trained with sex, race, age, and national origin directly, plus four proxy varia
 
 | Group | Ineligibility Flag Rate |
 |-------|:-----------------------:|
-| Male applicants | 25.71% |
-| Female applicants | 7.71% |
+| Male applicants | 25.82% |
+| Female applicants | 7.82% |
 | **Fairness Gap (Sex)** | **18.00%** |
 
 | Group | Ineligibility Flag Rate |

ROADMAP.md

@@ -27,7 +27,7 @@ Fair Code is an open-source responsible AI platform explaining algorithmic bias,
 
 | Stars | Contributors | Forks | Watching | Social Reach | Countries | Audits | Explainers | CI |
 |:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
-| 46 | 28 | 32 | 8 | 30K+ | 20 | 7 | 53 | ✅ every push/PR |
+| 46 | 29 | 33 | 8 | 30K+ | 20 | 7 | 60 | ✅ every push/PR |
 
 > The earlier paper freeze has lifted - the real paper, with fresh results, is now planned for next
 > year. `paper/results-frozen/` (tag `v1.0-paper`, commit `bbef2ba`) is kept as a reference snapshot.