# plotting_utils

A Python package providing elegant wrappers around matplotlib and seaborn functions to make scientific plotting easier and more consistent.

## Features

### 🎨 Color Palettes
- **Custom color schemes**: `ten_godisnot`, `darjeeling`, `fantastic_fox`
- **Palette creation utilities**: `create_palette()` for generating custom color schemes

### 📊 Plotting Functions
High-level plotting functions with sensible defaults:
- **Basic plots**: `scatter()`, `bar()`, `box()`, `strip()`, `violin()`
- **Distribution plots**: `dist()`, `counts_plot()`
- **Specialized plots**: `heatmap()`, `dotplot()`, `volcano()`, `stem_plot()`, `rank_plot()`
- **Statistical plots**: Built-in support for statistical annotations with `add_wilcox()`

### 🛠 Utility Functions
- **Styling**: `set_rcParams()` for Nature journal-style settings
- **Plot enhancement**: `format_ax()`, `add_legend()`, `add_cbar()`
- **File operations**: `save_best_pdf_quality()`, `make_folder()`
- **Performance**: `Timer` class for benchmarking

## 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 updated; please install `ac-plotting-ut` instead.

## Quick Start

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

# Set journal-style parameters
plu.set_rcParams()

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

# Scatter, coloured by a categorical column
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)

# Save at publication quality
plu.save_best_pdf_quality(fig, figsize=(6, 4), path='.', name='my_plot.pdf')
```

## Requirements

Python 3.10+, plus `numpy`, `pandas`, `scipy`, `matplotlib`, `seaborn`,
`scikit-learn`, `joblib`, `pillow`, `statannotations` and `textalloc`.
These are installed automatically.

## Development

```bash
pip install -e ".[test]"
pytest
```

## Release History

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

### 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

See LICENSE file for details.

## Version

Current version: 0.1.4
