Skip to main content

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:

  1. A text column (default: findings for reference, predicted_report for predictions; override with --reference_text_column / --prediction_text_column).
  2. A demographic column with exactly two values (e.g. M/F, White/Black, young/old). Default column name is PatientSex if 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)

Source distribution for clinical-cad 0.1.3
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)

Table of built distributions (wheels) for clinical-cad 0.1.3
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page