Metadata-Version: 2.4
Name: metrics-adjuster
Version: 1.1.0
Summary: Adjusted group-aware clinical prediction metrics with Python API and CLI.
Project-URL: Homepage, https://github.com/SaehwanPark/metrics-adjuster
Project-URL: Repository, https://github.com/SaehwanPark/metrics-adjuster
Project-URL: Issues, https://github.com/SaehwanPark/metrics-adjuster/issues
Author: Saehwan Park
License-Expression: GPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs>=2.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20260518; extra == 'dev'
Description-Content-Type: text/markdown

# metrics-adjuster

`metrics-adjuster` computes conventional and adjusted group-aware metrics for
binary prediction models. It provides a typed Python API, a command-line
interface, deterministic synthetic demos, self-contained HTML reports, and
optional parquet artifacts for downstream inspection.

## Installation

Install from [PyPI](https://pypi.org/project/metrics-adjuster/) (Python 3.11+):

```bash
python -m pip install metrics-adjuster
```

That one command installs both the `metrics-adjuster` CLI and the Python API.
Parquet input and artifact output work out of the box (`pyarrow` is included).

**Other setups:**

- CLI only, without a project environment: `pipx install metrics-adjuster`
- uv project: `uv add metrics-adjuster`
- conda or mamba env: run the pip command above inside your activated environment
- pinned release: `python -m pip install "metrics-adjuster==1.1.0"`
- source checkout: see [Contributing](https://github.com/SaehwanPark/metrics-adjuster/blob/main/CONTRIBUTING.md)

## Quick Example

```bash
metrics-adjuster demo \
  --output-dir demo_outputs \
  --report \
  --save-artifacts \
  --report-figures
```

For caller-provided CSV or Parquet data:

```bash
metrics-adjuster run \
  --input cohort.csv \
  --output-dir adjusted_metric_outputs \
  --group-col group \
  --ref-group ref \
  --response-col outcome \
  --risk-col risk \
  --id-col patient_id \
  --metrics aTPR,aPPV,aNB,aHR \
  --report \
  --save-artifacts \
  --report-figures
```

The CLI writes one CSV per adjusted metric. Optional outputs include:

- `report.html` when `--report` is enabled
- `figure_1_calibrated_density.svg` and `figure_2_weight_ratio.svg` when
  `--report-figures` is also used
- `calibration.parquet` and `weights.parquet` when `--save-artifacts` is used

## Python API

```python
from pathlib import Path

from metrics_adjuster import ColumnSpec, MetricConfig, OutputConfig, adjusted_metrics
from metrics_adjuster.synthetic import generate_synthetic_metrics_data

frame = generate_synthetic_metrics_data(n=600, seed=2026)
config = MetricConfig(
  columns=ColumnSpec(group="group", response="outcome", risk="risk", id="patient_id"),
  ref_group="ref",
  output=OutputConfig(
    calibration_path=Path("artifacts/calibration.parquet"),
    density_ratio_path=Path("artifacts/weights.parquet"),
    include_intermediates=True,
  ),
  random_state=2026,
)

result = adjusted_metrics(frame, config)
print(result.metrics["aTPR"])
print(result.weighted[["cal_risk", "dens_ratio"]].head())
```

For reports and standalone figures, use `adjusted_metrics_report(...)` and
`write_report_figures(...)`. See the [API manual](https://github.com/SaehwanPark/metrics-adjuster/blob/main/docs/API_MANUAL.md).

## Documentation

- [Quickstart](https://github.com/SaehwanPark/metrics-adjuster/blob/main/QUICKSTART.md)
- [API manual](https://github.com/SaehwanPark/metrics-adjuster/blob/main/docs/API_MANUAL.md)
- [CLI manual](https://github.com/SaehwanPark/metrics-adjuster/blob/main/docs/CLI_MANUAL.md)
- [R CLI guide](https://github.com/SaehwanPark/metrics-adjuster/blob/main/docs/R_CLI_GUIDE.md)
- [Contributing](https://github.com/SaehwanPark/metrics-adjuster/blob/main/CONTRIBUTING.md)

## Citation

If you use `metrics-adjuster` in published work, cite it as:

APA:

Park, S. (2026). _metrics-adjuster_ (Version 1.1.0) [Computer software]. GitHub. https://github.com/SaehwanPark/metrics-adjuster

AMA:

Park S. metrics-adjuster [computer program]. Version 1.1.0. Published 2026. Accessed June 24, 2026. https://github.com/SaehwanPark/metrics-adjuster

## License

`metrics-adjuster` is distributed under the GNU General Public License v3.0.
