Metadata-Version: 2.4
Name: ac-plotting-ut
Version: 0.2.1
Summary: Elegant wrappers around matplotlib and seaborn for scientific plotting
Project-URL: Homepage, https://github.com/andrecossa5/plotting_utils
Project-URL: Repository, https://github.com/andrecossa5/plotting_utils
Project-URL: Issues, https://github.com/andrecossa5/plotting_utils/issues
Author: Andrea Cossa
License: MIT License
        
        Copyright (c) 2023 acox1
        
        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.
License-File: LICENSE
Keywords: matplotlib,plotting,seaborn,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: joblib>=1.3
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: pillow>=10.0
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Dist: seaborn>=0.13
Requires-Dist: statannotations>=0.7.2
Requires-Dist: textalloc>=1.0
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# plotting_utils

[![PyPI](https://img.shields.io/pypi/v/ac-plotting-ut.svg)](https://pypi.org/project/ac-plotting-ut/)
[![Python](https://img.shields.io/pypi/pyversions/ac-plotting-ut.svg)](https://pypi.org/project/ac-plotting-ut/)
[![Tests](https://github.com/andrecossa5/plotting_utils/actions/workflows/test.yml/badge.svg)](https://github.com/andrecossa5/plotting_utils/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Elegant wrappers around matplotlib and seaborn, for scientific plotting that stays
consistent across figures.

## Installation

```bash
pip install ac-plotting-ut
```

> **Note on the package name.** This project was previously published on PyPI as
> `plotting_utils`. From v0.2.0 it is distributed as **`ac-plotting-ut`**.
> The import name is unchanged — `import plotting_utils as plu` keeps working.
> The old `plotting_utils` distribution is no longer maintained.

## Quick Start

```python
import matplotlib.pyplot as plt
import pandas as pd
import plotting_utils as plu

# Journal-style rcParams
plu.set_rcParams()

df = pd.DataFrame({
    'x': [1, 2, 3, 4],
    'y': [2, 4, 5, 8],
    'group': ['a', 'a', 'b', 'b'],
})

fig, ax = plt.subplots(figsize=(6, 4))
plu.scatter(df, 'x', 'y', by='group', ax=ax)
plu.format_ax(ax, xlabel='X values', ylabel='Y values', reduced_spines=True)

plu.save_best_pdf_quality(fig, figsize=(6, 4), path='.', name='my_plot.pdf')
```

Every plotting function takes a `pd.DataFrame` plus column names, draws onto an
`ax` you provide, and returns that `ax` — so they compose freely with plain
matplotlib.

## API

### 🎨 Colors

| Function | Purpose |
| --- | --- |
| `create_palette()` | Build a `{category: color}` mapping from a DataFrame column |
| `ten_godisnot`, `darjeeling`, `fantastic_fox` | Ready-made qualitative palettes |

### 📊 Plots

| Function | Purpose |
| --- | --- |
| `scatter()` | Scatter, coloured/sized by categorical or continuous columns |
| `dist()` | Kernel density distributions, optionally split by group |
| `counts_plot()` | Category frequencies |
| `bar()`, `box()`, `strip()`, `violin()` | Categorical comparisons, optionally grouped by `by` |
| `bb_plot()` | Stacked composition (crosstab) plot |
| `plot_heatmap()` | Heatmap with optional row/column clustering |
| `dotplot()` | Dotplot with size and colour encodings |
| `volcano()` | Volcano plot with automatic label placement |
| `stem_plot()`, `rank_plot()` | Ranked-value displays |

### 🛠 Axis decoration and utilities

| Function | Purpose |
| --- | --- |
| `set_rcParams()` | Apply journal-style matplotlib defaults |
| `format_ax()` | Labels, ticks, rotation, log scale, reduced spines |
| `add_legend()`, `add_cbar()` | Legends and colorbars from a palette or array |
| `add_wilcox()` | Statistical annotations via `statannotations` |
| `order_from_index()` | Ordering helper for matrix plots |
| `save_best_pdf_quality()` | High-DPI PDF export |
| `Timer`, `run_command`, `make_folder`, `update_params` | Small helpers |

## Requirements

Python 3.10+. Dependencies (`numpy`, `pandas`, `scipy`, `matplotlib`, `seaborn`,
`scikit-learn`, `joblib`, `pillow`, `statannotations`, `textalloc`) are installed
automatically.

Tested on Linux and macOS against Python 3.10, 3.11 and 3.12.

## Development

```bash
git clone https://github.com/andrecossa5/plotting_utils.git
cd plotting_utils
pip install -e ".[test]"
pytest
```

## Release History

### 0.2.1
- Fixed `bar()` silently ignoring `categorical_cmap`: an unreachable branch meant an
  explicit palette was never applied and bars rendered in seaborn's default colour
- `bar()` no longer needs an explicit `categorical_cmap=None` when `by` is unset
- Replaced seaborn's deprecated `palette`-without-`hue` usage, removed in seaborn 0.14
- Added tests asserting rendered colours, not just that a call succeeds

### 0.2.0
- Renamed the PyPI distribution to `ac-plotting-ut`; import name unchanged
- Modern `pyproject.toml` packaging (hatchling); `setup.py` removed
- Declared previously-missing dependencies: `numpy`, `pandas`, `scipy`, `pillow`
- Requires Python 3.10+; verified against numpy 2.5, pandas 3.0, matplotlib 3.11, seaborn 0.13
- Added a test suite (85 tests) and CI across Linux/macOS on Python 3.10–3.12
- Automated PyPI releases via Trusted Publishing
- Fixed `volcano()` raising `ValueError` when called with its own default `ylim`
- Fixed `volcano()` and `rank_plot()` label placement failing on non-integer indices
- Fixed `rank_plot()` passing an invalid positional argument to `ax.scatter`
- Fixed `dotplot` and `rank_plot` being absent from `__all__`
- `violin()` no longer needs an explicit `categorical_cmap=None` when `by` is unset

### 0.1.5
- Last release under the `plotting_utils` distribution name

### 0.1.4 (2025-09-11)
- Enhanced README with comprehensive documentation
- Added proper package metadata (long_description, author, classifiers)
- Improved PyPI package presentation

### 0.1.3
- Previous stable release

## License

MIT — see [LICENSE](LICENSE).
