atlas-mpl-style 0.25.0
ATLAS style for Matplotlib 3.0+
Requires Python: >=3.9
Keywords: plotting, atlas, matplotlib, cern, root, hep, high-energy-physics, physics

ATLAS Matplotlib Style
======================
.. image:: https://img.shields.io/pypi/v/atlas-mpl-style?label=PyPI&style=for-the-badge   :alt: PyPI 

**Despite the last commit date, this package is still maintained. If you have any comments or improvements, open an issue or PR.**

Provides a Matplotlib style replicating that used by the
`ATLAS <http://atlas.cern>`__ collaboration.

**Please open an issue if you find this style deviates from the guidelines.**

Install from PyPI using pip: :code:`pip install atlas-mpl-style`

Documentation: https://atlas-mpl.readthedocs.io/en/latest/index.html

In addition, this package also provides:

- A function to draw the ATLAS label
- A ``plot`` module containing functions to plot pre-binned histograms and
   limits. This includes functionality for plotting stacked backgrounds along
   with data and ratios in the usual ATLAS style.
- A matplotlib style based on the background / foreground from the VIM `Paper <https://github.com/NLKNguyen/papercolor-theme>`__ color scheme, along with a print version with a white background.
  - The default color cycle in all three styles is generated with HCL Wizard

- Additional Matplotlib color definitions based on the Paper theme, and the
   `Oceanic Next <https://github.com/voronianski/oceanic-next-color-scheme>`__
   theme

UHI and the PlottableHistogram protocol
----------------------------------------- 

With the development of the `UHI <https://github.com/henryiii/uhi>`__ interface,
this package now has support for histogram objects that follow the
``PlottableHistogram`` protocol. ``plot.Background`` objects can be constructed
using ``PlottableHistograms`` and a list of such ``Backgrounds`` can be passed
to ``plot.plot_backgrounds`` omitting the ``bins`` argument. The other histogram
plotting functions could not be modified to accept ``PlottableHistogram`` in a
backward compatible manner since they take ``bins`` before the histogram
argument. Alternate versions of these functions are therefore provided in the
``uhi`` module.

As a result of this support, the histogram objects returned by `Uproot 4
<https://github.com/scikit-hep/uproot4>`__ can be plotted directly, as can
`Boost-Histogram <https://github.com/scikit-hep/boost-histogram>`__ histograms
and `Hist <https://github.com/scikit-hep/hist>`__ objects (once the relevent PRs
are merged into those repositories).


``usetex=False`` Mode
------------------------

``usetex=False`` is now the default, removing the LaTeX dependency.

If you convert a plotting script that uses ``usetex=True`` mode, make sure labels
are updated to remove LaTeX macros that are not supported by Matplotlib's
mathtext.


TeXLive and Fonts Needed
------------------------
If you have a full LaTeX installation available, you can use LaTeX to typeset the text by passing  ``usetex=True`` to ``use_atlas_style``. This will give you much greater options in terms of what can
be included in labels.

A working TeXLive installation providing the following is required:

- pdflatex
- amsmath
- TeX Gyre Heros
- mathastext
- physics (the package)
- siunitx

If no LaTeX installation is available, the style will warn and fall back to the ``usetex=False`` behaviour.
To check if all necessary packages are installed, try building ``atlas_mpl_style/testing/ampl-test.tex``.

On Arch (and related distributions), the ``texlive-most`` group is sufficient.

On Debian (Jessie or above) or Ubuntu (18.04+), the following set of packages should be sufficient. It is however highly recommended
that you install `texlive-full` to obtain a complete installation of texlive.

- texlive
- texlive-latex-extra
- texlive-fonts-recommended
- texlive-lang-greek
- tex-gyre
- dvipng
- ghostscript

On CentOS 7, the supplied TeXLive (2012) is extremely old. TeXLive should be
installed from `upstream <https://www.tug.org/texlive/quickinstall.html>`__.

**TeXLive is not required for the "slides" or "print" style.** `Fira Sans
<https://bboxtype.com/typefaces/FiraSans/>`__ and `Iosevka
<https://github.com/be5invis/Iosevka/releases/>`__ should be installed
for these styles to appear as intended. However, neither is *necessary*.