medxfair 0.4.0__tar.gz

medxfair-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MedxFair contributors
+
+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.

medxfair-0.4.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: medxfair
+Version: 0.4.0
+Summary: Diagnosis-first intersectional auditing of binary clinical predictions
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: explain
+Requires-Dist: shap>=0.44; extra == "explain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# MedxFair-ROBUST (v0.4.0)
+
+Research-oriented Python package for retrospective fairness auditing of binary prediction models, including intersectional subgroup analysis, descriptive SHAP explanations, input substitution sensitivity checks, model mitigation review, and partial-identification bounds under missing protected attributes.
+
+**Research use only:** model disparities do not prove discrimination; feature substitutions are not causal interventions; mitigation eligibility is not clinical safety. Missing-membership identification bounds are not sampling confidence intervals.
+
+## Install
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+python examples/quickstart.py
+python -m build
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+from medxfair import MedxFair, AuditConfig
+df = pd.read_csv("examples/example_predictions.csv")
+config = AuditConfig(outcome_col="readmitted_30d", probability_col="predicted_probability", protected_attributes=["race","payer","age_group"], min_group_size=5,min_positive_support=2,min_negative_support=2)
+report = MedxFair(config).run(df)
+report.export_json("outputs/audit.json")
+report.export_csv("outputs")
+report.export_html("outputs/report.html")
+```
+
+The package accepts precomputed binary-outcome probabilities and does not retrain the model. Threshold mode uses p>=threshold; budget mode selects exactly ceil(budget*N) high-risk rows, ties broken by input order. Missing attributes remain explicit categories; supported-group thresholds guard headline worst-group estimates. Wilson confidence intervals are pointwise, not simultaneous.
+
+For partial-identification APIs, see `ROBUST.md`; for explanation, sensitivity and candidate review modules see `MILESTONE2.md`. The examples are synthetic software tests, not clinical data. Aggregate outputs can still disclose small-group information. Review before sharing.

medxfair-0.4.0/README.md

@@ -0,0 +1,31 @@
+# MedxFair-ROBUST (v0.4.0)
+
+Research-oriented Python package for retrospective fairness auditing of binary prediction models, including intersectional subgroup analysis, descriptive SHAP explanations, input substitution sensitivity checks, model mitigation review, and partial-identification bounds under missing protected attributes.
+
+**Research use only:** model disparities do not prove discrimination; feature substitutions are not causal interventions; mitigation eligibility is not clinical safety. Missing-membership identification bounds are not sampling confidence intervals.
+
+## Install
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+python examples/quickstart.py
+python -m build
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+from medxfair import MedxFair, AuditConfig
+df = pd.read_csv("examples/example_predictions.csv")
+config = AuditConfig(outcome_col="readmitted_30d", probability_col="predicted_probability", protected_attributes=["race","payer","age_group"], min_group_size=5,min_positive_support=2,min_negative_support=2)
+report = MedxFair(config).run(df)
+report.export_json("outputs/audit.json")
+report.export_csv("outputs")
+report.export_html("outputs/report.html")
+```
+
+The package accepts precomputed binary-outcome probabilities and does not retrain the model. Threshold mode uses p>=threshold; budget mode selects exactly ceil(budget*N) high-risk rows, ties broken by input order. Missing attributes remain explicit categories; supported-group thresholds guard headline worst-group estimates. Wilson confidence intervals are pointwise, not simultaneous.
+
+For partial-identification APIs, see `ROBUST.md`; for explanation, sensitivity and candidate review modules see `MILESTONE2.md`. The examples are synthetic software tests, not clinical data. Aggregate outputs can still disclose small-group information. Review before sharing.

medxfair-0.4.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "medxfair"
+version = "0.4.0"
+description = "Diagnosis-first intersectional auditing of binary clinical predictions"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.23", "pandas>=1.5", "scipy>=1.9", "scikit-learn>=1.2"]
+
+[project.optional-dependencies]
+explain = ["shap>=0.44"]
+dev = ["pytest>=7", "build>=1", "ruff>=0.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

medxfair-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

medxfair-0.4.0/src/medxfair/__init__.py

@@ -0,0 +1,12 @@
+"""MedxFair: retrospective fairness auditing and optional diagnostic extensions."""
+from .config import AuditConfig
+from .core import MedxFair
+from .reporting import AuditReport
+from .explainability import explain_predictions, ExplanationResult
+from .sensitivity import feature_substitution, SensitivityResult
+from .mitigation import review_candidates, ReviewConstraints, MitigationReview
+__version__ = "0.4.0"
+__all__ = ["AuditConfig","MedxFair","AuditReport","explain_predictions","ExplanationResult","feature_substitution","SensitivityResult","review_candidates","ReviewConstraints","MitigationReview"]
+
+from .missingness_robust import audit_missing_group_bounds, mask_observed_groups, MissingGroupBounds
+from .disparity_robust import audit_pairwise_disparity_bounds, DisparityBounds

medxfair-0.4.0/src/medxfair/config.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import Literal
+from .exceptions import AuditError
+
+@dataclass(frozen=True)
+class AuditConfig:
+    outcome_col: str
+    probability_col: str
+    protected_attributes: tuple[str, ...] | list[str]
+    threshold: float = 0.5
+    evaluation_mode: Literal["threshold", "budget"] = "threshold"
+    review_budget: float | None = None
+    min_group_size: int = 30
+    min_positive_support: int = 10
+    min_negative_support: int = 10
+    max_intersection_depth: int | None = None
+    confidence_level: float = 0.95
+    patient_id_col: str | None = None
+    record_id_col: str | None = None
+    high_missingness_threshold: float = 0.2
+
+    def __post_init__(self):
+        attrs = tuple(self.protected_attributes)
+        if not attrs or len(set(attrs)) != len(attrs):
+            raise AuditError("protected_attributes must be a nonempty set of unique column names")
+        object.__setattr__(self, "protected_attributes", attrs)
+        if not (0 <= self.threshold <= 1): raise AuditError("threshold must be in [0,1]")
+        if self.evaluation_mode not in ("threshold", "budget"): raise AuditError("invalid evaluation_mode")
+        if self.evaluation_mode == "budget" and (self.review_budget is None or not 0 < self.review_budget <= 1):
+            raise AuditError("budget mode requires review_budget in (0,1]")
+        if self.min_group_size < 1 or self.min_positive_support < 1 or self.min_negative_support < 1:
+            raise AuditError("support thresholds must be positive")
+        if not 0 < self.confidence_level < 1: raise AuditError("confidence_level must be in (0,1)")
+        if self.max_intersection_depth is not None and not 1 <= self.max_intersection_depth <= len(attrs):
+            raise AuditError("invalid max_intersection_depth")
+        if not 0 <= self.high_missingness_threshold <= 1: raise AuditError("invalid high_missingness_threshold")

medxfair-0.4.0/src/medxfair/core.py

@@ -0,0 +1,45 @@
+from dataclasses import asdict
+from datetime import datetime, timezone
+import numpy as np
+import pandas as pd
+from .config import AuditConfig
+from .data_audit import cohort, missingness, missingness_by_groups
+from .intersectional import subgroups, disparities
+from .reporting import AuditReport
+from .utils import validate, predicted_flags
+from .validation import metrics
+
+class MedxFair:
+    """Audit precomputed probabilities for a binary outcome; does not train a model."""
+    def __init__(self, config: AuditConfig): self.config=config
+
+    def run(self, df: pd.DataFrame) -> AuditReport:
+        """Return an offline audit; does not modify input or retain patient-level rows."""
+        c=self.config
+        data=df.reset_index(drop=True).copy()
+        y,p=validate(data,c)
+        flags,mode_info=predicted_flags(p,c)
+        overall=metrics(y,p,flags)
+        group_table=subgroups(data,y,p,flags,c,overall)
+        miss=missingness(data)
+        warnings=[]
+        def warn(code,severity,affected,message):warnings.append({"code":code,"severity":severity,"affected":affected,"message":message})
+        if not (y.min()!=y.max()):warn("SINGLE_CLASS","warning",c.outcome_col,"AUROC undefined with only one observed class")
+        if not np.isfinite(overall["precision"]):warn("UNDEFINED_PRECISION","warning","overall","No predicted positives")
+        for _,row in miss.iterrows():
+            if row.missing_rate >= c.high_missingness_threshold and row.missing_count:
+                warn("HIGH_MISSINGNESS","warning",row.column,f"Missing rate {row.missing_rate:.1%}")
+        for a in c.protected_attributes:
+            if data[a].isna().any():warn("MISSING_PROTECTED","warning",a,"Missing values audited as explicit category")
+        if c.patient_id_col:
+            repeated=int(data[c.patient_id_col].duplicated(keep=False).sum())
+            if repeated:warn("REPEATED_PATIENT","warning",c.patient_id_col,f"{repeated} records have repeated patient identifiers; record-level uncertainty assumes independence")
+        if c.record_id_col and data[c.record_id_col].duplicated(keep=False).any():
+            warn("DUPLICATE_RECORD_ID","warning",c.record_id_col,"Duplicate record identifiers found")
+        for _,r in group_table.iterrows():
+            if r.support_status!="SUPPORTED":warn("SPARSE_OR_UNDEFINED_GROUP","warning",r.group,f"{r.support_status}: n={r.n}, positives={r.positives}, negatives={r.negatives}")
+        warn("NO_SPLIT_PROVENANCE","info","evaluation","Prediction-only input cannot establish patient-disjoint train/test provenance")
+        warn("MULTIPLE_COMPARISONS","info","subgroups","Wilson intervals are pointwise, not multiplicity-adjusted")
+        return AuditReport(metadata={"package_version":"0.4.0","generated_at":datetime.now(timezone.utc).isoformat(),"config":asdict(c),"evaluation_mode":c.evaluation_mode,**mode_info},
+           cohort_summary=cohort(data,y,c),missingness=miss,missingness_by_group=missingness_by_groups(data,c),
+           overall_metrics=overall,subgroup_metrics=group_table,disparity_summary=disparities(group_table),warnings=warnings)

medxfair-0.4.0/src/medxfair/data_audit.py

@@ -0,0 +1,25 @@
+import pandas as pd
+from .utils import normalized_groups
+
+def cohort(df, y, config):
+    d = {"records":len(df),"positive_outcomes":int(y.sum()),"prevalence":float(y.mean())}
+    if config.patient_id_col:
+        d["unique_patients"] = int(df[config.patient_id_col].nunique(dropna=True))
+        d["repeated_patient_records"] = int(df[config.patient_id_col].duplicated(keep=False).sum())
+    if config.record_id_col:
+        d["duplicate_record_ids"] = int(df[config.record_id_col].duplicated(keep=False).sum())
+    return d
+
+def missingness(df):
+    return pd.DataFrame([{"column":c,"missing_count":int(df[c].isna().sum()),"missing_rate":float(df[c].isna().mean()),"dtype":str(df[c].dtype)} for c in df.columns])
+
+def missingness_by_groups(df, config):
+    rows=[]; attrs=config.protected_attributes
+    groups=normalized_groups(df,attrs)
+    for target in attrs:
+        for by in [x for x in attrs if x!=target]+[config.outcome_col]:
+            keys=groups[by] if by in groups else df[by].astype("string")
+            for label, idx in keys.groupby(keys,sort=True,dropna=False).groups.items():
+                subset=df.loc[idx,target]
+                rows.append({"target":target,"by":by,"group":str(label),"n":len(subset),"missing_rate":float(subset.isna().mean())})
+    return pd.DataFrame(rows,columns=["target","by","group","n","missing_rate"])

medxfair-0.4.0/src/medxfair/disparity_robust.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+@dataclass(frozen=True)
+class DisparityBounds:
+    table: pd.DataFrame
+    metadata: dict
+    def export_csv(self, path): self.table.to_csv(path, index=False)
+
+def audit_pairwise_disparity_bounds(data, *, group_col, outcome_col, prediction_col, pairs=None, threshold=0.5, max_missing_share=1.0, missing_values=None, tolerance=0.0):
+    """Bounds for FNR_A-FNR_B and FPR_A-FPR_B with coupled unknown labels."""
+    if not 0 <= max_missing_share <= 1 or not 0 <= threshold <= 1 or tolerance < 0:
+        raise ValueError("Invalid threshold, allocation cap, or tolerance")
+    for col in (group_col,outcome_col,prediction_col):
+        if col not in data: raise ValueError(f"Missing column: {col}")
+    if data.empty: raise ValueError("Empty data")
+    y=pd.to_numeric(data[outcome_col],errors="coerce").to_numpy(dtype=float)
+    p=pd.to_numeric(data[prediction_col],errors="coerce").to_numpy(dtype=float)
+    if not np.isfinite(y).all() or not np.isin(y,[0,1]).all(): raise ValueError("Invalid outcomes")
+    if not np.isfinite(p).all() or ((p<0)|(p>1)).any(): raise ValueError("Invalid probabilities")
+    labels=data[group_col].astype("string")
+    missing=labels.isna()
+    if missing_values is not None: missing=missing|labels.isin([str(v) for v in missing_values]).fillna(False)
+    missing=missing.to_numpy(dtype=bool)
+    names=list(labels[~missing].dropna().unique())
+    if pairs is None: pairs=[(names[i],names[j]) for i in range(len(names)) for j in range(i+1,len(names))]
+    pred=p>=threshold
+    cells={"fn":(y==1)&~pred,"tp":(y==1)&pred,"fp":(y==0)&pred,"tn":(y==0)&~pred}
+    missing_counts={k:int((v&missing).sum()) for k,v in cells.items()}
+    counts={}
+    for g in names:
+        membership=labels.eq(g).fillna(False).to_numpy(dtype=bool)&~missing
+        counts[g]={k:int((membership&v).sum()) for k,v in cells.items()}
+    def ratio(a,b): return float(a/b) if b>0 else float("nan")
+    def bounds(a,b,metric):
+        num,den=("fn","tp") if metric=="fnr" else ("fp","tn")
+        an,ad=a[num],a[den];bn,bd=b[num],b[den]
+        mn=max_missing_share*missing_counts[num];md=max_missing_share*missing_counts[den]
+        return ratio(an,an+ad+md)-ratio(bn+mn,bn+bd+mn),ratio(an+mn,an+ad+mn)-ratio(bn,bn+bd+md),ratio(an,an+ad)-ratio(bn,bn+bd)
+    rows=[]
+    for a,b in pairs:
+        a,b=str(a),str(b)
+        if a==b or a not in counts or b not in counts: raise ValueError(f"Unknown pair {a}, {b}")
+        for metric in ("fnr","fpr"):
+            low,high,observed=bounds(counts[a],counts[b],metric)
+            direction="UNDEFINED" if not np.isfinite(low+high) else "A_HIGHER" if low>tolerance else "B_HIGHER" if high < -tolerance else "NOT_IDENTIFIED"
+            rows.append(dict(group_a=a,group_b=b,metric=metric,observed_difference=observed,difference_lower=low,difference_upper=high,direction=direction,group_a_observed_n=sum(counts[a].values()),group_b_observed_n=sum(counts[b].values()),max_missing_share=float(max_missing_share)))
+    return DisparityBounds(pd.DataFrame(rows),dict(n=len(data),missing_group_n=int(missing.sum()),missing_confusion_counts=missing_counts,threshold=threshold,max_missing_share=max_missing_share,tolerance=tolerance,assumptions="Observed labels fixed; unknown labels allocated to A, B or other",interpretation="Coupled partial-identification bounds; not confidence intervals",caveat="Caps below 1 are fractional relaxations and require justification"))

medxfair-0.4.0/src/medxfair/exceptions.py

@@ -0,0 +1,2 @@
+class AuditError(ValueError):
+    """Raised when audit configuration or data are invalid."""

medxfair-0.4.0/src/medxfair/explainability.py

@@ -0,0 +1,58 @@
+"""Optional SHAP-based descriptive attribution audit; not causal inference."""
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+from .exceptions import AuditError
+
+@dataclass
+class ExplanationResult:
+    global_importance: pd.DataFrame
+    subgroup_importance: pd.DataFrame
+    metadata: dict
+
+def explain_predictions(predict_fn, features: pd.DataFrame, *, groups=None,
+                        background_size=40, sample_size=80, seed=42, max_evals=None):
+    """Compute probability-scale SHAP attribution for a callable returning P(Y=1).
+
+    Permutation SHAP with a background masker; only sampled rows are explained.
+    Requires pip install medxfair[explain]. Features must be numeric and finite.
+    No raw feature rows or per-patient explanations are returned.
+    """
+    try:
+        import shap
+    except ImportError as exc:
+        raise ImportError("Install optional dependency: pip install medxfair[explain]") from exc
+    if not isinstance(features,pd.DataFrame) or features.empty or not features.columns.is_unique:
+        raise AuditError("features must be a nonempty DataFrame with unique column names")
+    x=features.reset_index(drop=True)
+    try: vals=x.to_numpy(dtype=float)
+    except (TypeError,ValueError) as exc: raise AuditError("SHAP feature matrix must be numeric") from exc
+    if not np.isfinite(vals).all(): raise AuditError("SHAP feature matrix must be finite")
+    if not callable(predict_fn): raise AuditError("predict_fn must be callable")
+    if background_size < 1 or sample_size < 1: raise AuditError("sample sizes must be positive")
+    rng=np.random.default_rng(seed)
+    bg_idx=np.sort(rng.choice(len(x),size=min(background_size,len(x)),replace=False))
+    sm_idx=np.sort(rng.choice(len(x),size=min(sample_size,len(x)),replace=False))
+    def wrapped(array):
+        inp=pd.DataFrame(np.asarray(array),columns=x.columns)
+        out=np.asarray(predict_fn(inp),dtype=float).reshape(-1)
+        if len(out)!=len(inp) or not np.isfinite(out).all() or np.any((out<0)|(out>1)):
+            raise AuditError("predict_fn must return finite probabilities in [0,1]")
+        return out
+    nfeatures=len(x.columns)
+    budget=max_evals if max_evals is not None else max(2*nfeatures+1, 30)
+    if budget < 2*nfeatures+1: raise AuditError("max_evals must be at least 2*n_features+1")
+    explainer=shap.Explainer(wrapped,shap.maskers.Independent(x.iloc[bg_idx]),algorithm="permutation",seed=seed)
+    values=np.asarray(explainer(x.iloc[sm_idx],max_evals=budget).values)
+    if values.shape!=(len(sm_idx),nfeatures): raise AuditError("Unexpected SHAP output dimensions")
+    importance=pd.DataFrame({"feature":x.columns,"mean_abs_shap":np.abs(values).mean(axis=0),"mean_shap":values.mean(axis=0)}).sort_values("mean_abs_shap",ascending=False).reset_index(drop=True)
+    group_rows=[]
+    if groups is not None:
+        g=pd.Series(groups).reset_index(drop=True)
+        if len(g)!=len(x): raise AuditError("groups must match feature row count")
+        for label in sorted(g.iloc[sm_idx].fillna("<MISSING>").astype(str).unique()):
+            mask=(g.iloc[sm_idx].fillna("<MISSING>").astype(str).to_numpy()==label)
+            for j,col in enumerate(x.columns):
+                group_rows.append({"group":label,"feature":col,"n_explained":int(mask.sum()),"mean_abs_shap":float(np.abs(values[mask,j]).mean()),"mean_shap":float(values[mask,j].mean())})
+    return ExplanationResult(importance,pd.DataFrame(group_rows,columns=["group","feature","n_explained","mean_abs_shap","mean_shap"]),
+        {"method":"permutation_SHAP","output_scale":"predicted_probability","background_n":len(bg_idx),"explained_n":len(sm_idx),"seed":seed,"warning":"Attributions depend on background, feature dependence, and model; not causal effects"})

medxfair-0.4.0/src/medxfair/intersectional.py

@@ -0,0 +1,39 @@
+from itertools import combinations
+import numpy as np
+import pandas as pd
+from .statistics import wilson_interval
+from .validation import metrics
+from .utils import normalized_groups
+
+PROPORTIONS = {"fnr":("fn","positives"),"fpr":("fp","negatives"),"sensitivity":("tp","positives"),"specificity":("tn","negatives"),"prevalence":("positives","n")}
+
+def subgroups(df, y, p, flags, config, overall):
+    groups=normalized_groups(df,config.protected_attributes)
+    rows=[]; depth=config.max_intersection_depth or len(config.protected_attributes)
+    for k in range(1,depth+1):
+        for attrs in combinations(config.protected_attributes,k):
+            for values, indices in groups.groupby(list(attrs),dropna=False,sort=True).indices.items():
+                if k==1: values=(values,)
+                ix=np.asarray(indices,dtype=int)
+                m=metrics(y[ix],p[ix],flags[ix])
+                eligible = m["n"] >= config.min_group_size and m["positives"] >= config.min_positive_support and m["negatives"] >= config.min_negative_support
+                status = "UNDEFINED_METRIC" if m["positives"]==0 or m["negatives"]==0 else ("SUPPORTED" if eligible else "LOW_SUPPORT")
+                row={"depth":k,"attributes":" × ".join(attrs),"group":" | ".join(f"{a}={v}" for a,v in zip(attrs,values)),"support_status":status,**m}
+                for key,(num,den) in PROPORTIONS.items():
+                    row[f"{key}_ci_low"],row[f"{key}_ci_high"]=wilson_interval(m[num],m[den],config.confidence_level)
+                for key in ("fnr","fpr","selection_rate","calibration_gap"):
+                    row[f"{key}_difference"] = m[key]-overall[key]
+                rows.append(row)
+    return pd.DataFrame(rows)
+
+def disparities(table):
+    rows=[]
+    for depth, t in table.groupby("depth"):
+        eligible=t[t.support_status=="SUPPORTED"]
+        for metric in ("fnr","fpr","selection_rate","calibration_gap"):
+            vals=eligible[metric].dropna()
+            if len(vals):
+                rows.append({"depth":int(depth),"metric":metric,"eligible_groups":len(vals),"worst_value":float(vals.max()),"between_group_gap":float(vals.max()-vals.min()),"worst_group":str(eligible.loc[vals.idxmax(),"group"])})
+            else:
+                rows.append({"depth":int(depth),"metric":metric,"eligible_groups":0,"worst_value":float("nan"),"between_group_gap":float("nan"),"worst_group":None})
+    return pd.DataFrame(rows)

medxfair-0.4.0/src/medxfair/missingness_robust.py

@@ -0,0 +1,54 @@
+"""Missing protected-group labels: partial-identification error-rate bounds."""
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+@dataclass(frozen=True)
+class MissingGroupBounds:
+    table: pd.DataFrame
+    metadata: dict
+    def export_csv(self, path): self.table.to_csv(path,index=False)
+
+def audit_missing_group_bounds(data, *, group_col, outcome_col, prediction_col, threshold=0.5, groups=None, missing_values=None):
+    for col in (group_col,outcome_col,prediction_col):
+        if col not in data: raise ValueError(f"Missing column: {col}")
+    if data.empty or not 0 <= threshold <= 1: raise ValueError("Invalid data/threshold")
+    y=pd.to_numeric(data[outcome_col],errors="coerce").to_numpy(dtype=float)
+    p=pd.to_numeric(data[prediction_col],errors="coerce").to_numpy(dtype=float)
+    if not np.isfinite(y).all() or not np.isin(y,[0,1]).all(): raise ValueError("Invalid outcome")
+    if not np.isfinite(p).all() or ((p<0)|(p>1)).any(): raise ValueError("Invalid predictions")
+    labels=data[group_col].astype("string")
+    missing=labels.isna()
+    if missing_values is not None: missing=missing|labels.isin([str(v) for v in missing_values]).fillna(False)
+    missing=missing.to_numpy(dtype=bool)
+    observed=labels[~missing]
+    names=list(observed.unique()) if groups is None else [str(g) for g in groups]
+    if len(names)<2 or len(set(names))!=len(names): raise ValueError("At least two unique groups required")
+    if not observed.isin(names).all(): raise ValueError("groups must contain observed categories")
+    pred=p>=threshold
+    cells=dict(fn=(y==1)&~pred,tp=(y==1)&pred,fp=(y==0)&pred,tn=(y==0)&~pred)
+    missing_counts={k:int((v&missing).sum()) for k,v in cells.items()}
+    def ratio(a,b): return float(a/b) if b else float("nan")
+    rows=[]
+    for g in names:
+        m=labels.eq(g).fillna(False).to_numpy(dtype=bool)&~missing
+        a,b,c,d=[int((m&cells[k]).sum()) for k in ("fn","tp","fp","tn")]
+        u,v,w,z=[missing_counts[k] for k in ("fn","tp","fp","tn")]
+        rows.append(dict(group=g,observed_n=int(m.sum()),observed_positives=a+b,observed_negatives=c+d,observed_fn=a,observed_tp=b,observed_fp=c,observed_tn=d,observed_fnr=ratio(a,a+b),fnr_lower=ratio(a,a+b+v),fnr_upper=ratio(a+u,a+b+u),observed_fpr=ratio(c,c+d),fpr_lower=ratio(c,c+d+z),fpr_upper=ratio(c+w,c+d+w),fnr_identified=bool(u==0 and v==0 and a+b>0),fpr_identified=bool(w==0 and z==0 and c+d>0)))
+    return MissingGroupBounds(pd.DataFrame(rows),dict(n_records=len(data),missing_group_n=int(missing.sum()),missing_group_fraction=float(missing.mean()),missing_confusion_counts=missing_counts,threshold=float(threshold),assumption="Unrestricted missing-group assignments",interpretation="Marginal identification bounds, not sampling confidence intervals",joint_attainability=False,outcome_and_predictions_fully_observed=True))
+
+def mask_observed_groups(data, *, group_col, outcome_col, prediction_col, fraction, mechanism="MCAR",random_state=42):
+    if not 0<=fraction<1: raise ValueError("Invalid masking fraction")
+    if mechanism not in {"MCAR","OUTCOME_DEPENDENT","ERROR_DEPENDENT"}: raise ValueError("Invalid masking mechanism")
+    result=data.copy(deep=True)
+    observed=np.flatnonzero(result[group_col].notna().to_numpy())
+    n=int(round(len(observed)*fraction))
+    if not n:return result
+    rng=np.random.default_rng(random_state)
+    y=result[outcome_col].to_numpy()[observed];p=result[prediction_col].to_numpy()[observed]
+    weight=np.ones(len(observed))
+    if mechanism=="OUTCOME_DEPENDENT":weight=np.where(y==1,5.,1.)
+    if mechanism=="ERROR_DEPENDENT":weight=np.where((y==1)&(p<.5),7.,1.)
+    selected=rng.choice(observed,size=n,replace=False,p=weight/weight.sum())
+    result.iloc[selected,result.columns.get_loc(group_col)]=np.nan
+    return result

medxfair-0.4.0/src/medxfair/mitigation.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass, asdict
+from typing import Mapping
+import numpy as np
+import pandas as pd
+from .config import AuditConfig
+from .core import MedxFair
+from .exceptions import AuditError
+
+@dataclass(frozen=True)
+class ReviewConstraints:
+    max_auroc_drop: float = 0.01
+    max_brier_increase: float = 0.005
+    max_fnr_increase: float = 0.03
+    max_worst_group_fnr_increase: float = 0.03
+    min_worst_group_fnr_improvement: float = 0.0
+    def __post_init__(self):
+        if any(v < 0 or not np.isfinite(v) for v in asdict(self).values()):
+            raise AuditError('Constraints must be finite and nonnegative')
+
+@dataclass
+class MitigationReview:
+    comparison: pd.DataFrame
+    metadata: dict
+
+def review_candidates(data: pd.DataFrame, config: AuditConfig, candidate_probabilities: Mapping[str, object], *, constraints: ReviewConstraints = ReviewConstraints()):
+    if not isinstance(data, pd.DataFrame) or data.empty or not candidate_probabilities:
+        raise AuditError('Nonempty data and candidate probabilities required')
+    base = MedxFair(config).run(data)
+    def worst(report):
+        t = report.subgroup_metrics
+        t = t[(t.support_status == 'SUPPORTED') & np.isfinite(t.fnr)]
+        return float(t.fnr.max()) if len(t) else float('nan')
+    bm = base.overall_metrics; bw = worst(base)
+    rows = [dict(candidate='baseline', decision='BASELINE', reason='reference', auroc=bm['auroc'], brier=bm['brier'], fnr=bm['fnr'], worst_supported_fnr=bw, delta_auroc=0.,delta_brier=0.,delta_fnr=0.,delta_worst_supported_fnr=0.)]
+    for name, prob in candidate_probabilities.items():
+        if name == 'baseline': raise AuditError('baseline is reserved')
+        p = np.asarray(prob, dtype=float).reshape(-1)
+        if len(p) != len(data) or not np.isfinite(p).all() or ((p < 0) | (p > 1)).any(): raise AuditError('Invalid candidate')
+        tmp = data.copy(); tmp[config.probability_col] = p
+        mreport = MedxFair(config).run(tmp)
+        m = mreport.overall_metrics; w = worst(mreport)
+        delta = dict(auroc=m['auroc'] - bm['auroc'], brier=m['brier'] - bm['brier'], fnr=m['fnr'] - bm['fnr'], worst_supported_fnr=w-bw)
+        if not all(np.isfinite(v) for v in delta.values()): decision, reason = 'DEFER', 'Undefined evidence'
+        elif delta['auroc'] < -constraints.max_auroc_drop or delta['brier'] > constraints.max_brier_increase or delta['fnr'] > constraints.max_fnr_increase or delta['worst_supported_fnr'] > constraints.max_worst_group_fnr_increase: decision, reason = 'REJECT', 'Constraint violated'
+        elif delta['worst_supported_fnr'] < -constraints.min_worst_group_fnr_improvement: decision, reason = 'ELIGIBLE', 'Requires independent confirmation'
+        else: decision, reason = 'DEFER', 'No qualifying improvement'
+        rows.append(dict(candidate=str(name),decision=decision,reason=reason,auroc=m['auroc'],brier=m['brier'],fnr=m['fnr'],worst_supported_fnr=w,**{'delta_'+k:v for k,v in delta.items()}))
+    return MitigationReview(pd.DataFrame(rows), dict(constraints=asdict(constraints),evaluation_mode=config.evaluation_mode,selection_only=True,warning='Point-estimate rules are not clinical safety certificates'))

medxfair-0.4.0/src/medxfair/reporting.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass
+from pathlib import Path
+from html import escape
+import json
+import math
+import numpy as np
+import pandas as pd
+
+def clean(value):
+    if isinstance(value, dict): return {str(k):clean(v) for k,v in value.items()}
+    if isinstance(value,(list,tuple)): return [clean(v) for v in value]
+    if isinstance(value,np.generic): return clean(value.item())
+    if isinstance(value,(float,int)) and not isinstance(value,bool):
+        return None if not math.isfinite(value) else value
+    if pd.isna(value): return None
+    return value
+
+@dataclass
+class AuditReport:
+    metadata: dict
+    cohort_summary: dict
+    missingness: pd.DataFrame
+    missingness_by_group: pd.DataFrame
+    overall_metrics: dict
+    subgroup_metrics: pd.DataFrame
+    disparity_summary: pd.DataFrame
+    warnings: list[dict]
+
+    def as_dict(self):
+        return clean({"metadata":self.metadata,"cohort_summary":self.cohort_summary,
+            "overall_metrics":self.overall_metrics,"missingness":self.missingness.to_dict("records"),
+            "missingness_by_group":self.missingness_by_group.to_dict("records"),
+            "subgroup_metrics":self.subgroup_metrics.to_dict("records"),
+            "disparity_summary":self.disparity_summary.to_dict("records"),"warnings":self.warnings})
+
+    def export_json(self,path):
+        path=Path(path);path.parent.mkdir(parents=True,exist_ok=True)
+        path.write_text(json.dumps(self.as_dict(),indent=2,allow_nan=False),encoding="utf-8")
+
+    def export_csv(self,directory):
+        d=Path(directory);d.mkdir(parents=True,exist_ok=True)
+        tables={"overall_metrics":pd.DataFrame([self.overall_metrics]),"subgroup_metrics":self.subgroup_metrics,
+            "missingness":self.missingness,"missingness_by_group":self.missingness_by_group,
+            "disparities":self.disparity_summary,"warnings":pd.DataFrame(self.warnings,columns=["code","severity","affected","message"])}
+        for name,frame in tables.items():frame.to_csv(d/f"{name}.csv",index=False)
+
+    def export_html(self,path):
+        path=Path(path);path.parent.mkdir(parents=True,exist_ok=True)
+        sections=[("Cohort",pd.DataFrame([self.cohort_summary])),("Overall metrics",pd.DataFrame([self.overall_metrics])),
+          ("Missingness",self.missingness),("Missingness by group",self.missingness_by_group),
+          ("Intersectional and marginal fairness",self.subgroup_metrics),("Disparity summary",self.disparity_summary),
+          ("Warnings",pd.DataFrame(self.warnings))]
+        html=['<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>MedxFair Audit</title>',
+        '<style>body{font:15px system-ui,sans-serif;max-width:1150px;margin:40px auto;padding:0 18px;color:#17212b;background:#fafbfc}h1{color:#12364a}section{margin:28px 0}table{border-collapse:collapse;width:100%;font-size:12px}th,td{border-bottom:1px solid #ddd;padding:7px;text-align:left}th{background:#e8eff3;position:sticky;top:0}.scroll{overflow:auto;max-height:470px;background:white;border:1px solid #ddd}p{line-height:1.5}</style></head><body><h1>MedxFair — Audit Report</h1>',
+        '<p>Retrospective prediction audit. Differences do not establish discrimination or causality. This is not a clinical safety assessment. Sparse-group estimates may be unstable; intervals are unadjusted for multiplicity.</p>']
+        for title,frame in sections:
+            html.extend([f'<section><h2>{escape(title)}</h2><div class="scroll">',frame.to_html(index=False,escape=True,na_rep='—'),'</div></section>'])
+        html.append('</body></html>');path.write_text(''.join(html),encoding='utf-8')

medxfair-0.4.0/src/medxfair/sensitivity.py

@@ -0,0 +1,47 @@
+"""Non-causal feature-substitution sensitivity diagnostics."""
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+from .exceptions import AuditError
+
+@dataclass
+class SensitivityResult:
+    summary: pd.DataFrame
+    by_group: pd.DataFrame
+    metadata: dict
+
+def feature_substitution(predict_fn, features:pd.DataFrame, interventions:dict, *, groups=None):
+    """Compare model probabilities after hypothetical feature substitutions.
+
+    Changes to feature values are not do-operator interventions, counterfactual
+    outcomes, or evidence of a causal pathway. Never modify the input dataframe.
+    """
+    if not isinstance(features,pd.DataFrame) or features.empty or not callable(predict_fn):
+        raise AuditError("Provide nonempty features DataFrame and callable predict_fn")
+    if not interventions: raise AuditError("interventions cannot be empty")
+    x=features.reset_index(drop=True).copy(deep=True)
+    def predict(frame):
+        p=np.asarray(predict_fn(frame),dtype=float).reshape(-1)
+        if len(p)!=len(frame) or not np.isfinite(p).all() or np.any((p<0)|(p>1)):
+            raise AuditError("predict_fn must return finite probabilities in [0,1] for every row")
+        return p
+    base=predict(x)
+    g=None
+    if groups is not None:
+        g=pd.Series(groups).reset_index(drop=True).fillna("<MISSING>").astype(str)
+        if len(g)!=len(x):raise AuditError("groups length must match features")
+    summary=[];by_group=[]
+    for col,value in interventions.items():
+        if col not in x: raise AuditError(f"Unknown intervention feature: {col}")
+        changed=x.copy(deep=True)
+        if callable(value):raise AuditError("Callable interventions prohibited; provide a fixed scalar value")
+        if not np.isscalar(value):raise AuditError("Intervention values must be scalars")
+        changed[col]=value
+        delta=predict(changed)-base
+        summary.append({"feature":col,"substituted_value":str(value),"n":len(delta),"mean_probability_change":float(delta.mean()),"mean_abs_change":float(np.abs(delta).mean()),"min_change":float(delta.min()),"max_change":float(delta.max())})
+        if g is not None:
+            for label in sorted(g.unique()):
+                mask=(g.to_numpy()==label)
+                by_group.append({"feature":col,"group":label,"n":int(mask.sum()),"mean_probability_change":float(delta[mask].mean()),"mean_abs_change":float(np.abs(delta[mask]).mean())})
+    return SensitivityResult(pd.DataFrame(summary),pd.DataFrame(by_group,columns=["feature","group","n","mean_probability_change","mean_abs_change"]),
+        {"method":"feature_substitution","warning":"Associational model sensitivity only; not causal identification or a clinical intervention"})

medxfair-0.4.0/src/medxfair/statistics.py

@@ -0,0 +1,14 @@
+import numpy as np
+from scipy.stats import norm
+
+def safe_div(numerator, denominator):
+    return float(numerator / denominator) if denominator else float("nan")
+
+def wilson_interval(successes: int, total: int, confidence: float = 0.95):
+    if total == 0: return (float("nan"), float("nan"))
+    z = norm.ppf((1 + confidence) / 2)
+    p = successes / total
+    den = 1 + z*z/total
+    center = (p + z*z/(2*total)) / den
+    radius = z / den * np.sqrt(p*(1-p)/total + z*z/(4*total*total))
+    return float(max(0, center-radius)), float(min(1, center+radius) if successes != total else 1.0)

medxfair-0.4.0/src/medxfair/utils.py

@@ -0,0 +1,37 @@
+import numpy as np
+import pandas as pd
+from .exceptions import AuditError
+
+MISSING = "<MISSING>"
+
+def normalized_groups(df, attributes):
+    out = df[list(attributes)].copy()
+    for col in attributes:
+        s = out[col].astype("string")
+        s = s.mask((s == MISSING).fillna(False), "<OBSERVED:MISSING>")
+        out[col] = s.fillna(MISSING)
+    return out
+
+def validate(df, config):
+    if not isinstance(df, pd.DataFrame) or df.empty: raise AuditError("expected a nonempty pandas DataFrame")
+    required = [config.outcome_col, config.probability_col, *config.protected_attributes]
+    required += [x for x in (config.patient_id_col, config.record_id_col) if x]
+    if len(set(required)) != len(required): raise AuditError("configuration columns must be distinct")
+    absent = [x for x in required if x not in df.columns]
+    if absent: raise AuditError(f"missing columns: {absent}")
+    y = pd.to_numeric(df[config.outcome_col], errors="coerce")
+    if y.isna().any() or not y.isin([0,1]).all(): raise AuditError("outcome must be nonmissing binary 0/1")
+    p = pd.to_numeric(df[config.probability_col], errors="coerce").to_numpy(dtype=float)
+    if not np.isfinite(p).all() or np.any((p < 0) | (p > 1)):
+        raise AuditError("probabilities must be finite numeric values in [0,1]")
+    return y.to_numpy(dtype=int), p
+
+def predicted_flags(probabilities, config):
+    n = len(probabilities)
+    if config.evaluation_mode == "threshold":
+        return (probabilities >= config.threshold).astype(int), {"threshold":config.threshold, "selected_count":int((probabilities >= config.threshold).sum())}
+    k = int(np.ceil(n * config.review_budget))
+    order = np.lexsort((np.arange(n), -probabilities))
+    flags = np.zeros(n, dtype=int)
+    flags[order[:k]] = 1
+    return flags, {"review_budget":config.review_budget,"selected_count":k,"cutoff_probability":float(probabilities[order[k-1]])}

medxfair-0.4.0/src/medxfair/validation.py

@@ -0,0 +1,19 @@
+import numpy as np
+from sklearn.metrics import roc_auc_score, average_precision_score, brier_score_loss, log_loss
+from .statistics import safe_div
+
+def metrics(y, p, flags):
+    y = np.asarray(y, dtype=int); p = np.asarray(p, dtype=float); flags = np.asarray(flags, dtype=int)
+    tp = int(((y==1)&(flags==1)).sum()); tn = int(((y==0)&(flags==0)).sum())
+    fp = int(((y==0)&(flags==1)).sum()); fn = int(((y==1)&(flags==0)).sum())
+    positives = tp+fn; negatives = tn+fp
+    result = {"n":len(y),"positives":positives,"negatives":negatives,"tp":tp,"tn":tn,"fp":fp,"fn":fn,
+       "prevalence":safe_div(positives,len(y)),"accuracy":safe_div(tp+tn,len(y)),
+       "precision":safe_div(tp,tp+fp),"recall":safe_div(tp,positives),"sensitivity":safe_div(tp,positives),
+       "specificity":safe_div(tn,negatives),"fnr":safe_div(fn,positives),"fpr":safe_div(fp,negatives),
+       "f1":safe_div(2*tp,2*tp+fp+fn),"selection_rate":float(flags.mean()),
+       "mean_probability":float(p.mean()),"calibration_gap":float(p.mean()-y.mean()),
+       "brier":float(brier_score_loss(y,p)),"log_loss":float(log_loss(y,np.clip(p,1e-15,1-1e-15),labels=[0,1]))}
+    result["auroc"] = float(roc_auc_score(y,p)) if positives and negatives else float("nan")
+    result["auprc"] = float(average_precision_score(y,p)) if positives else float("nan")
+    return result

medxfair-0.4.0/src/medxfair.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: medxfair
+Version: 0.4.0
+Summary: Diagnosis-first intersectional auditing of binary clinical predictions
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: explain
+Requires-Dist: shap>=0.44; extra == "explain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# MedxFair-ROBUST (v0.4.0)
+
+Research-oriented Python package for retrospective fairness auditing of binary prediction models, including intersectional subgroup analysis, descriptive SHAP explanations, input substitution sensitivity checks, model mitigation review, and partial-identification bounds under missing protected attributes.
+
+**Research use only:** model disparities do not prove discrimination; feature substitutions are not causal interventions; mitigation eligibility is not clinical safety. Missing-membership identification bounds are not sampling confidence intervals.
+
+## Install
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+python examples/quickstart.py
+python -m build
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+from medxfair import MedxFair, AuditConfig
+df = pd.read_csv("examples/example_predictions.csv")
+config = AuditConfig(outcome_col="readmitted_30d", probability_col="predicted_probability", protected_attributes=["race","payer","age_group"], min_group_size=5,min_positive_support=2,min_negative_support=2)
+report = MedxFair(config).run(df)
+report.export_json("outputs/audit.json")
+report.export_csv("outputs")
+report.export_html("outputs/report.html")
+```
+
+The package accepts precomputed binary-outcome probabilities and does not retrain the model. Threshold mode uses p>=threshold; budget mode selects exactly ceil(budget*N) high-risk rows, ties broken by input order. Missing attributes remain explicit categories; supported-group thresholds guard headline worst-group estimates. Wilson confidence intervals are pointwise, not simultaneous.
+
+For partial-identification APIs, see `ROBUST.md`; for explanation, sensitivity and candidate review modules see `MILESTONE2.md`. The examples are synthetic software tests, not clinical data. Aggregate outputs can still disclose small-group information. Review before sharing.

medxfair-0.4.0/src/medxfair.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+LICENSE
+README.md
+pyproject.toml
+src/medxfair/__init__.py
+src/medxfair/config.py
+src/medxfair/core.py
+src/medxfair/data_audit.py
+src/medxfair/disparity_robust.py
+src/medxfair/exceptions.py
+src/medxfair/explainability.py
+src/medxfair/intersectional.py
+src/medxfair/missingness_robust.py
+src/medxfair/mitigation.py
+src/medxfair/reporting.py
+src/medxfair/sensitivity.py
+src/medxfair/statistics.py
+src/medxfair/utils.py
+src/medxfair/validation.py
+src/medxfair.egg-info/PKG-INFO
+src/medxfair.egg-info/SOURCES.txt
+src/medxfair.egg-info/dependency_links.txt
+src/medxfair.egg-info/requires.txt
+src/medxfair.egg-info/top_level.txt
+tests/test_disparity_robust.py
+tests/test_intersectional.py
+tests/test_missingness_robust.py
+tests/test_reporting.py
+tests/test_statistics.py
+tests/test_validation.py

medxfair-0.4.0/src/medxfair.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

medxfair-0.4.0/src/medxfair.egg-info/requires.txt

@@ -0,0 +1,12 @@
+numpy>=1.23
+pandas>=1.5
+scipy>=1.9
+scikit-learn>=1.2
+
+[dev]
+pytest>=7
+build>=1
+ruff>=0.5
+
+[explain]
+shap>=0.44

medxfair-0.4.0/src/medxfair.egg-info/top_level.txt

@@ -0,0 +1 @@
+medxfair

medxfair-0.4.0/tests/test_disparity_robust.py

@@ -0,0 +1,11 @@
+import pandas as pd
+import pytest
+from medxfair import audit_pairwise_disparity_bounds
+
+def test_pair_bounds():
+    d=pd.DataFrame(dict(group=["A","A","B","B",pd.NA,pd.NA],y=[1,1,1,1,1,1],p=[0,1,0,1,0,1]))
+    t=audit_pairwise_disparity_bounds(d,group_col="group",outcome_col="y",prediction_col="p",pairs=[("A","B")]).table
+    f=t[t.metric=="fnr"].iloc[0]
+    assert f.difference_lower==pytest.approx(-1/3)
+    assert f.difference_upper==pytest.approx(1/3)
+    assert f.direction=="NOT_IDENTIFIED"

medxfair-0.4.0/tests/test_intersectional.py

@@ -0,0 +1,13 @@
+from medxfair import MedxFair
+
+def test_intersections(sample,config):
+    table=MedxFair(config).run(sample).subgroup_metrics
+    assert set(table.depth)=={1,2,3}
+
+def test_missing_and_no_mutation(sample,config):
+    d=sample.copy()
+    d.loc[0,"payer"]=None
+    before=d.copy(deep=True)
+    report=MedxFair(config).run(d)
+    assert report.subgroup_metrics.group.str.contains("<MISSING>",regex=False).any()
+    assert d.equals(before)

medxfair-0.4.0/tests/test_missingness_robust.py

@@ -0,0 +1,14 @@
+import pandas as pd
+from medxfair import audit_missing_group_bounds,mask_observed_groups
+
+def test_missing_labels():
+    df=pd.DataFrame(dict(g=["A","B",pd.NA,pd.NA],y=[1,1,1,1],p=[0,1,0,1]))
+    t=audit_missing_group_bounds(df,group_col="g",outcome_col="y",prediction_col="p").table
+    assert len(t)==2
+    assert t.iloc[0].fnr_lower <= t.iloc[0].observed_fnr <= t.iloc[0].fnr_upper
+
+def test_mask_preserves_input():
+    df=pd.DataFrame(dict(g=["A","B","A","B"],y=[1,0,1,0],p=[0.,1.,0.,1.]))
+    m=mask_observed_groups(df,group_col="g",outcome_col="y",prediction_col="p",fraction=.5)
+    assert m.g.isna().sum()==2
+    assert df.g.notna().all()

medxfair-0.4.0/tests/test_reporting.py

@@ -0,0 +1,11 @@
+import json
+from medxfair import MedxFair
+
+def test_exports(sample,config,tmp_path):
+    d=sample.copy();d["y"]=1
+    report=MedxFair(config).run(d)
+    report.export_json(tmp_path/"report.json")
+    report.export_csv(tmp_path/"csv")
+    report.export_html(tmp_path/"report.html")
+    assert json.loads((tmp_path/"report.json").read_text())["overall_metrics"]["auroc"] is None
+    assert (tmp_path/"csv"/"subgroup_metrics.csv").exists()

medxfair-0.4.0/tests/test_statistics.py

@@ -0,0 +1,9 @@
+import math
+import pytest
+from medxfair.statistics import wilson_interval
+
+def test_wilson():
+    assert all(math.isnan(x) for x in wilson_interval(0,0))
+    low,high=wilson_interval(5,10)
+    assert low==pytest.approx(.236593,abs=1e-5)
+    assert high==pytest.approx(.763407,abs=1e-5)

medxfair-0.4.0/tests/test_validation.py

@@ -0,0 +1,34 @@
+import numpy as np
+import pytest
+from sklearn.metrics import roc_auc_score,average_precision_score
+from medxfair import MedxFair,AuditConfig
+from medxfair.utils import predicted_flags
+from medxfair.exceptions import AuditError
+
+def test_confusion_and_auc(sample,config):
+    r=MedxFair(config).run(sample).overall_metrics
+    assert (r["tp"],r["tn"],r["fp"],r["fn"])==(2,2,2,2)
+    assert r["fnr"]==.5 and r["fpr"]==.5
+    assert r["auroc"]==pytest.approx(roc_auc_score(sample.y,sample.p))
+    assert r["auprc"]==pytest.approx(average_precision_score(sample.y,sample.p))
+
+def test_one_class(sample,config):
+    d=sample.copy();d["y"]=1
+    r=MedxFair(config).run(d)
+    assert np.isnan(r.overall_metrics["auroc"])
+    assert any(w["code"]=="SINGLE_CLASS" for w in r.warnings)
+
+def test_no_predicted_positives(sample,config):
+    d=sample.copy();d["p"]=0
+    r=MedxFair(config).run(d)
+    assert np.isnan(r.overall_metrics["precision"])
+
+def test_invalid_probabilities(sample,config):
+    for value in [1.2,-.1,float("nan"),float("inf"),"oops"]:
+        d=sample.copy();d["p"]=d["p"].astype(object);d.loc[0,"p"]=value
+        with pytest.raises(AuditError):MedxFair(config).run(d)
+
+def test_budget_ties():
+    c=AuditConfig("y","p",["race"],evaluation_mode="budget",review_budget=.25)
+    flags,_=predicted_flags(np.array([.5,.5,.5,.5,.1,.1,.1,.1]),c)
+    assert flags.tolist()==[1,1,0,0,0,0,0,0]