Metadata-Version: 2.5
Name: ml-vizkit
Version: 0.0.1
Summary: Reusable visualizations for inspecting, comparing, and explaining trained machine-learning models.
Project-URL: Homepage, https://github.com/analytics-toolworks/ml-vizkit
Project-URL: Repository, https://github.com/analytics-toolworks/ml-vizkit
Project-URL: Documentation, https://analytics-toolworks.github.io/ml-vizkit/
Project-URL: Issues, https://github.com/analytics-toolworks/ml-vizkit/issues
Project-URL: Changelog, https://github.com/analytics-toolworks/ml-vizkit/blob/main/CHANGELOG.md
Author: Denise Case
License-File: LICENSE
Keywords: data science,explainable AI,machine learning,model interpretability,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Description-Content-Type: text/markdown

# ML VizKit

[![Docs Site](https://img.shields.io/badge/docs-site-blue?logo=github)](https://analytics-toolworks.github.io/ml-vizkit/)
[![Python 3.14](https://img.shields.io/badge/python-3.14%2B-blue?logo=python)](https://github.com/analytics-toolworks/ml-vizkit/blob/main/pyproject.toml)
![uv](https://img.shields.io/badge/uv-managed-DE5FE9)
[![CI Status](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/ci-python-zensical.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[![CI](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/ci-python-zensical.yml)
[![Docs](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/deploy-zensical.yml)
[![Links](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/analytics-toolworks/ml-vizkit/actions/workflows/links.yml)
[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/analytics-toolworks/ml-vizkit/security)

<img
src="https://raw.githubusercontent.com/analytics-toolworks/ml-vizkit/main/docs/images/profile.png"
alt="profile logo"
width="110">

> Reusable visualizations for inspecting, comparing, and
> explaining trained machine-learning models.

ML VizKit provides high-level Python functions for
common machine-learning visualizations.
It works with trained models, predictions, and experiment
results produced by libraries such as scikit-learn.

The package does not train models, select features,
choose algorithms, or make analytical decisions.

## Design

- Accept already-trained models, predictions, or completed experiment results.
- Reuse established visualization primitives from scikit-learn when they exist.
- Add small higher-level visualizations where the underlying libraries do not.
- Return Matplotlib `Axes` objects.
- Never call `plt.show()`.
- Keep analytical choices visible to the caller.
- Keep the implementation readable and replaceable.

## Install

```shell
uv add ml-vizkit
```

## Example

```python
from ml_vizkit import show_confusion_matrix

ax = show_confusion_matrix(y_test, y_pred)
ax.set_title("Penguin Species Classification")
```

The caller controls display and composition. In a script, for example:

```python
import matplotlib.pyplot as plt

ax = show_confusion_matrix(y_test, y_pred)
plt.show()
```

## Initial API

Classification:

- `show_decision_boundary()`
- `show_confusion_matrix()`
- `show_prediction_errors()`
- `show_class_distribution()`

Regression:

- `show_actual_vs_predicted()`
- `show_residuals()`

Model inspection:

- `show_feature_importance()`

Experiment inspection:

- `show_train_test_split()`
- `compare_splits()`
- `compare_models()`

## Developer Command Reference

<details>
<summary>Show command reference</summary>

### In a machine terminal

Open a machine terminal where you want the project:

```shell
git clone https://github.com/pup-pack/pup-up

cd pup-up
code .
```

### In a VS Code terminal

```shell
uv self update
uv python pin 3.14
uv python install
uv lock --upgrade
uv sync

uv run pre-commit install
uv run pre-commit autoupdate

git add -A
uv run pre-commit run --all-files
# repeat if changes were made
uv run pre-commit run --all-files

# run locally to test
uv run pup-up
uv run pup-up --diff
uv run pup-up --write
uv run pup-up --write .gitattributes .github/.yamllint.yml .github/workflows/links.yml

# types, tests, docs
uv run ty check
uv run python -m pytest
uv run python -m zensical build

# save progress
git add -A
git commit -m "update"
git push -u origin main
```

</details>

## Documentation

- [Documentation](https://pup-pack.github.io/pup-up/)

## Annotations

[.annotations/annotations.md](./.annotations/annotations.md)

## Citation

[CITATION.cff](./CITATION.cff)

## License

[MIT](./LICENSE)
