Metadata-Version: 2.3
Name: atlas-mpl-style
Version: 0.24.1
Summary: ATLAS style for Matplotlib 3.0+
Keywords: plotting,atlas,matplotlib,cern,root,hep,high-energy-physics,physics
Author-email: Beojan Stanislaus <beojan.stanislaus@cern.ch>
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Requires-Dist: matplotlib>=3
Requires-Dist: numpy
Requires-Dist: numexpr
Requires-Dist: pandas
Requires-Dist: importlib-resources>=6
Requires-Dist: packaging
Project-URL: Documentation, https://atlas-mpl.readthedocs.io/en/latest/
Project-URL: Home, https://github.com/beojan/atlas-mpl

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*.

