clinical-cad
Clinical Association Displacement (CAD) and Weighted Association Error (WAE) for lexical fairness over any binary demographic (sex, race, age group, etc.). Compare a reference corpus (e.g. ground-truth text) with model predictions to see how word associations with two groups change, and get a single fairness number (WAE).
Installation
pip install clinical-cad
Quick example
1. Run with your own CSVs (reference = ground truth, prediction = model output):
cad --reference_csv reference.csv --prediction_csv predictions.csv
Results go to ./cad_output by default. Use --output_dir my_results to change that.
2. Try it without data (demo):
cad --demo
3. Use a different demographic (e.g. race instead of sex):
Your CSV must have a column with exactly two values (e.g. White and Black). Then:
cad --reference_csv ref.csv --prediction_csv pred.csv \
--label_column race --group_a White --group_b Black
What it does (for new users)
-
CAD
For each word, it measures how strongly it’s associated with group A vs group B in the reference corpus, and how that changes in the prediction corpus. Words that shift a lot are “displaced” and can indicate bias. -
WAE (Weighted Association Error)
One number summarizing how much associations shifted overall. Lower WAE = fairer (less lexical bias). It comes with 95% confidence intervals (bootstrap).
You get JSON summaries, CSV tables, and plots in the output directory.
Input format
Both CSVs need:
- A text column (default:
findingsfor reference,predicted_reportfor predictions; override with--reference_text_column/--prediction_text_column). - A demographic column with exactly two values (e.g. M/F, White/Black, young/old). Default column name is
PatientSexif you don’t pass--label_column.
Example:
| PatientSex | findings |
|---|---|
| M | No acute findings. |
| F | Normal heart size. |
Parameters (only the important ones)
| Parameter | Default | Why it matters |
|---|---|---|
--reference_csv |
(required) | Path to reference (ground-truth) CSV. |
--prediction_csv |
(required) | Path to model-output CSV. |
--output_dir |
./cad_output |
Where to write results. |
--label_column |
PatientSex |
Column that holds the two groups (e.g. sex, race). |
--group_a |
F |
First group value (e.g. F, White). |
--group_b |
M |
Second group value (e.g. M, Black). |
--alpha |
0.1 |
Smoothing for rare words; keeps log-odds stable. |
--min_freq |
1 |
Ignore words with fewer than this many occurrences. |
--significance_level |
0.0455 |
P-value for “strong” association; lower = stricter. |
--neutral_significance |
0.317 |
P-value for “neutral”; higher = more words treated as neutral. |
--displacement_significance |
0.01 |
P-value for when a word is considered “displaced”. |
--wae_weight |
total |
How to weight words: total, ref, or pred. |
--bootstrap_samples |
1000 |
Number of bootstrap samples for WAE confidence intervals. |
--stopwords_path |
— | Optional file with extra stopwords (one per line). |
--no_stopword_removal |
False |
Turn off stopword removal. |
--demo |
False |
Run on built-in demo data (no CSVs needed). |
Paper and citation
This tool supports the methodology described in our paper on lexical fairness in clinical text (e.g. radiology report generation).
If you use clinical-cad in your work, please cite:
@article{parikh2026measuring,
title={Measuring What VLMs Don't Say: Validation Metrics Hide Clinical Terminology Erasure in Radiology Report Generation},
author={Parikh, Aditya and Feragen, Aasa and Das, Sneha and Frank, Stella},
journal={arXiv preprint arXiv:2603.01625},
year={2026}
}
Python API
from clinical_cad import parse_args, run_pipeline
args = parse_args()
run_pipeline(
args.reference_csv,
args.reference_text_column,
args.prediction_csv,
args.prediction_text_column,
args.label_column or "PatientSex",
args.output_dir,
args,
)
License
MIT
Metadata
Release files for clinical-cad 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clinical_cad-0.1.3.tar.gz | 25.4 kB | Without provenance | Details for clinical_cad-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clinical_cad-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for clinical_cad-0.1.3-py3-none-any.whl |
Total release size: 49.1 kB
Release files / clinical_cad-0.1.3.tar.gz
| Download URL | clinical_cad-0.1.3.tar.gz |
|---|---|
| Size | 25.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e72981e4d33152ebbafd297815e8cf97cd2269a516e73a76aa0997293f52c9f7
|
|
BLAKE2b-256 checksum How to use checksums |
37f3877aff1076b0bd72cc23b1b6321915012e9972c203516d3c4918e1c46edb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.5
|
Release files / clinical_cad-0.1.3-py3-none-any.whl
| Download URL | clinical_cad-0.1.3-py3-none-any.whl |
|---|---|
| Size | 23.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
307a1b25df006044d381df53fb529cab596b6fc1b8c917b9ee5aed02c1227487
|
|
BLAKE2b-256 checksum How to use checksums |
32ae61435e332bfe372830720cf7d314ba8891401ca506afaada3b35d1946de2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.5
|
Security for clinical-cad 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.