Metadata-Version: 2.4
Name: rikabplotlib
Version: 0.0.4
Summary: Plotting Library for Rikab
Author-email: Rikab Gambhir <rikab@mit.edu>
License: MIT
License-File: LICENSE
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 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.7
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy
Description-Content-Type: text/markdown

# rikabplotlib

Matplotlib style sheets and plotting helpers for physics figures. A figure made with
`newplot` comes out at the size it will occupy on the page, in the font it will be typeset
in, so nothing gets rescaled between the notebook and the paper.

```bash
pip install -e .
```

```python
import numpy as np
from rikabplotlib import newplot, hist_with_errors, hist_stack, ratio_panel, legend, BLUE, GREEN

fig, main, pull = newplot(ratio = True)

model = hist_stack(main, [continuum, reducible], bins = 40, range = (100, 180), colors = [BLUE, GREEN], labels = ["Continuum", "Reducible"])
data = hist_with_errors(main, measured, bins = 40, range = (100, 180), color = "black", label = "Data")
ratio_panel(pull, data.centers, data.counts, model.counts, data.errors, model.errors, mode = "pull")

main.set_ylabel("Events / 2 GeV")
pull.set_xlabel(r"$m_{\gamma\gamma}$ [GeV]")
legend(main)
```

Everything below is worked through end to end in
[`examples/rikabplotlib_examples.ipynb`](examples/rikabplotlib_examples.ipynb).

## Gallery

![Stacked model under the data](examples/figures/stack.png)

![Spectrum with a pull panel](examples/figures/spectrum_pull.png)

![Sideband fit](examples/figures/spectrum_fit.png)

![Pull in the mass-pt plane](examples/figures/pull_plane.png)

![Jet events](examples/figures/jets.png)

![Multiplicity with spread bands](examples/figures/multiplicity.png)

![Spectrum at five pt cuts](examples/figures/cuts.png)

![Colors](examples/figures/colors.png)

## Figures

| Function | What it does |
| --- | --- |
| `newplot(scale, subplot_array, ratio, square, stamp, use_tex, aspect_ratio, golden_ratio)` | Applies the style sheet and sizes the figure, square by default. `scale="full"` is the 510 pt text width, `scale="column"` the 245 pt column. `ratio=` splits each column into a body over a short pull panel and returns `fig, main, pull`. `aspect_ratio` is width over height for the occasional figure that has to be wide, `golden_ratio=True` its usual value. |
| `set_style(scale, use_tex)` | Applies a style sheet on its own, without making a figure. |
| `add_whitespace(ax, upper_fraction, lower_fraction)` | Opens up headroom above the tallest point, in decades when the axis is log. |
| `stamp(left_x, top_y, ax, line_0=, line_1=, ...)` | Stacks left-aligned lines downward from a point in axes coordinates, first line bold. |
| `badge(ax, lines, xy, loc, colors, weights, sizes)` | The same idea in a rounded framed box, one color and weight per line. |
| `legend(ax, **kwargs)` | A legend whose keys match what was drawn: a filled histogram shows as a filled swatch with its outline, a line with a band shows as both overlaid. |

## Data

| Function | What it does |
| --- | --- |
| `hist_with_errors(ax, points, bins, range, weights, density, show_zero)` | Histogram drawn as points with sqrt of the summed squared weights as the error, and half-bin x errors. Returns a `Histogram(counts, errors, edges, centers, artist)`. Empty bins are dropped unless `show_zero`; negative bins always survive. |
| `hist_with_outline(ax, points, bins, range, weights, color, alpha_1, alpha_2)` | A translucent filled histogram under an opaque outline of the same data. Returns the same `Histogram`. |
| `hist_stack(ax, components, bins, range, weights, colors, labels)` | The components stacked, one color each, filled with an outline on top. Returns the `Histogram` of the total. Without `colors` it takes the style sheet cycle in order. |
| `ratio_panel(ax, x, numerator, denominator, numerator_errors, denominator_errors, mode)` | Fills a pull panel. `mode="ratio"` plots num/den against 1, `mode="difference"` plots num minus den against 0, `mode="pull"` plots their difference over sigma against 0. Returns `Ratio(values, errors, dropped, artist)`, where `dropped` counts the bins with no defined value. |
| `function_with_band(ax, f, range, params, pcov, color, rng)` | `f(x, *params)` over a range, with a one sigma band from sampling the parameter covariance. |
| `line_with_band(ax, x, samples, mode)` | A central line with a spread band over per-x sample arrays: `"median"` with its 25 to 75 range, or `"mean"` with its standard deviation. |
| `plot_event(ax, event, R, values, cmap, colorbar, show_circle)` | An event of `(pt, y, phi)` rows in the rapidity-azimuth plane, marker area tracking the pT fraction, with the jet circle of radius R. `values=` colors the particles by any per-particle array. |

## Colors

The style sheet cycle is available by name as `COLORS`, or as `BLUE`, `GREEN`, `ORANGE`,
`RED`, `PURPLE`, `DARK`, `GRAY`, or as `palette(n)` for the first n of the cycle.

| Function | What it does |
| --- | --- |
| `shade(color, fraction, toward)` | Blends one color toward black or white, holding the hue fixed. |
| `ramp(color, n, toward, start, stop)` | n colors of one hue, light to dark, for several curves that are the same thing at different settings. |
| `blend(color_a, color_b, fraction, space)` | Mixes two colors. In `space="hue"` the hue takes the shorter arc around the circle, so blue to red passes through magenta rather than through mud; `space="rgb"` interpolates straight. |
| `gradient(color_a, color_b, n, space)` | n colors running from one color to another, the two-color analogue of `ramp`. |
| `hue_shift(color, delta)` | Rotates a color around the hue circle by `delta` turns, holding saturation and value. |
| `colormap(color, toward, start, stop)` | A continuous colormap of one hue, the continuous analogue of `ramp`. |
| `diverging_colormap(color_low, color_high)` | Low through white to high, for signed quantities like a pull. |

## Style sheets

Four sheets ship with the package, selected by `newplot` from `scale` and `use_tex`:
`rikab_full`, `rikab_full_notex`, `rikab_column`, `rikab_column_notex`. The TeX sheets set
`text.usetex` and Computer Modern; the notex sheets are sans-serif and need no TeX
installation. Applying one by hand is `plt.style.use("rikabplotlib.rikab_full")`.

## Versioning

The version comes from `git describe` through `hatch-vcs`, so tag a release to get a real
version number:

```bash
git tag v0.0.4
```
