Metadata-Version: 2.4
Name: paspale
Version: 0.1.2
Summary: A unified plotting framework for academic papers
Author-email: Jinchen Jiang <jiangjc.mail@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Jinchen Jiang
        
        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.
        
Project-URL: Homepage, https://github.com/undefined-c0der/paspale
Project-URL: Repository, https://github.com/undefined-c0der/paspale.git
Keywords: plotting,visualization,academic,paper,matplotlib
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: seaborn>=0.11.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Dynamic: license-file

# PasPale

PasPale provides a consistent, configurable interface for creating publication-ready figures with minimal boilerplate code.

## Features

- 🎨 **Unified Style** - Consistent colors, fonts, and layouts across all plots
- ⚙️ **Configurable** - Dataclass-based configuration with sensible defaults
- 📊 **Multiple Plot Types** - Bar charts, stacked bars, dual-axis, KDE, and more
- 📄 **Publication Ready** - PDF output with proper fonts and sizing
- 🔧 **Extensible** - Easy to create custom plotters by inheritance

## Installation

```bash
pip install paspale
```

Or install from source:

```bash
git clone https://github.com/undefined-c0der/paspale.git
cd paspale
pip install -e .
```

## Quick Start

### 1. Simple Bar Chart

```python
from paspale import paspale

paspale(
    data="data/results.csv",
    output="figures/comparison.pdf",
    ylabel="Speedup",
    legend=["Method A", "Method B", "Method C"],
)
```

### 2. Using Configuration

```python
from paspale import BarPlotter, PlotConfig

config = PlotConfig(
    output="figures/performance.pdf",
    ylabel="Speedup",
    ylim=6.0,
    legend=["Baseline", "Optimized", "Ours"],
    colors="primary",
)

plotter = BarPlotter(config)
plotter.load_csv("data/results.csv")
plotter.plot()
```

### 3. KDE Distribution Plot

```python
from paspale import KDEPlotter, KDEConfig

config = KDEConfig(
    output="figures/distribution.pdf",
    xlabel="Value",
    ylabel="Density",
)

# From CSV (each column is a distribution)
plotter = KDEPlotter(config)
plotter.load_csv("data/distributions.csv")
plotter.plot()

# Or from arrays
import numpy as np
plotter = KDEPlotter(config)
plotter.load_data([arr1, arr2], labels=["A", "B"])
plotter.plot()
```

### 4. Custom Plotter

```python
from paspale import BarPlotter, PlotConfig

class MyPlotter(BarPlotter):
    def configure(self) -> PlotConfig:
        return PlotConfig(
            output="figures/my_plot.pdf",
            ylabel="Performance",
            ylim=10.0,
            legend=["A", "B", "C"],
        )
    
    def customize(self):
        self.ax.axhline(y=1.0, color='red', linestyle='--')

plotter = MyPlotter()
plotter.load_csv("data/my_data.csv")
plotter.plot()
```

## Unified Interface

All plotters follow the same pattern:

```python
plotter = SomePlotter(config)
plotter.load_csv("data.csv")   # or load_data(df)
plotter.plot()
```

| Plotter | Config | Description |
|---------|--------|-------------|
| `BarPlotter` | `PlotConfig` | Grouped bar charts |
| `StackedBarPlotter` | `PlotConfig` | Stacked bar charts |
| `DualAxisPlotter` | `PlotConfig` | Dual Y-axis plots |
| `LinePlotter` | `PlotConfig` | Line charts |
| `KDEPlotter` | `KDEConfig` | Kernel density estimation |

## Configuration

### PlotConfig Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output` | str | Required | Output file path |
| `size` | tuple | (14, 4.5) | Figure size (width, height) |
| `ylabel` | str | "" | Y-axis label |
| `xlabel` | str | "" | X-axis label |
| `ylim` | float | None | Y-axis upper limit |
| `ylim_min` | float | 0.0 | Y-axis lower limit |
| `legend` | list | [] | Legend labels |
| `colors` | str/list | "primary" | Color scheme or list |
| `log_scale` | bool | False | Use log scale for Y-axis |

### KDEConfig Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output` | str | "" | Output file path |
| `size` | tuple | (8, 5) | Figure size |
| `xlabel` | str | "" | X-axis label |
| `ylabel` | str | "Density" | Y-axis label |
| `xlim` | tuple | None | X-axis limits |
| `fill` | bool | True | Fill under curve |
| `alpha` | float | 0.3 | Fill transparency |
| `use_percentage` | bool | False | Show Y as percentage |

### Color Schemes

```python
from paspale import colors

colors.PRIMARY    # 6 pastel colors
colors.EXTENDED   # 11 colors
colors.GRADIENT   # Blue gradient for ablations
colors.BREAKDOWN  # Component colors
colors.LINES      # Line plot colors
```

## Examples

See [examples/](examples/) directory:

- `examples/bar.py` - Basic bar chart
- `examples/ablation.py` - Ablation study with gradient colors
- `examples/dual_axis.py` - Bandwidth with miss rate overlay
- `examples/kde.py` - Distribution visualization

## License
Paspale is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
