Skip to main content

Matplotlib styles for HEP

Project description

DOI Scikit-HEP Docs

Actions Status pre-commit.ci status pre-commit

PyPI version Conda-forge version Supported Python versions

PyPI download week

Binder

A set of helpers for matplotlib to more easily produce plots typically needed in HEP as well as style them in way that's compatible with current collaboration requirements (ROOT-like plots for CMS, ATLAS, LHCb, ALICE).

Installation

pip install mplhep

Getting Started

A tutorial given at PyHEP 2020 is available as a binder here or you can watch the recording here.

Documentation can be found at mplhep.readthedocs.io.

Styling

import mplhep as hep
hep.style.use(hep.style.ROOT) # For now ROOT defaults to CMS
# Or choose one of the experiment styles
hep.style.use(hep.style.ATLAS)
# or
hep.style.use("CMS") # string aliases work too
# {"ALICE" | "ATLAS" | "CMS" | "LHCb1" | "LHCb2"}

Or use matplotlib API directly

plt.style.use(hep.style.ROOT)

If the default styles are not what you need, please open an issue.

Default experiment labels are also available.

# Overall - both left and right annotation
hep.<experiment>.label(<text>, data=<True|False>, lumi=50, year=2017)
# Just experiment label and <text> such as 'Preliminary' or 'Simulation'
hep.<experiment>.text(<text>)

You can use loc={0..5} to control the label positioning.

Plotting

1D Histograms

h, bins = [2, 3, 2], [0, 1, 2, 3]
hep.histplot(h, bins)

2D Histograms

import numpy as np
xbins, ybins = [0, 1, 2, 3], [0, 1, 2, 3]
H = np.array([[2,3,2], [1,2,1], [3,1,3]])
hep.hist2dplot(H, xbins, ybins)

More Information

Save all labels at once

  • hep.savelabels('test.png') will produces 4 variation on experiment label
    • "" -> "test.png"
    • "Preliminary" -> "test_pas.png"
    • "Supplementary" -> "test_supp.png"
    • "Work in Progress" -> "test_wip.png"
  • Options can also be specified manually
    • hep.savelabels('test', labels=["FOO", "BAR"], suffixes=["foo.pdf", "bar"]) will produce
      • "FOO" -> "foo.pdf"
      • "BAR" -> "test_bar.png"
  • Other components of <experiment>.label() will remain unchanged.

Other styles:

  • hep.style.use("fira") - use Fira Sans
  • hep.style.use("firamath") - use Fira Math

Styles can be chained:

  • e.g. hep.style.use(["CMS", "fira", "firamath"])
  • reappearing rcParams get overwritten silently

Styles can be modified on the fly

  • Since styles are dictionaries and they can be chained/overwritten they can be easily modified on the fly. e.g.
hep.style.use("CMS")
hep.style.use({"font.sans-serif":'Comic Sans MS'})

Styling with LaTeX

  • hep.style.use("CMSTex") - Use LaTeX to produce all text labels
  • Requires having the full tex-live distro
  • True Helvetica
  • Use sansmath as the math font
  • Takes longer and not always better
  • In general more possibilities, but a bit more difficult to get everything working properly

Notes

Consistency & Fonts

As it is ROOT does not come with any fonts and therefore relies on using system fonts. Therefore the font in a figure can be dependent on whether it was produced on OSX or PC. The default sans-serif font used is Helvetica, but it only comes with OSX, in Windows this will silently fallback to Arial.

License

Both Helvetica and Arial are proprietary, which as far as fonts go means you can use it to create any text/graphics once you have the license, but you cannot redistribute the font files as part of other software. That means we cannot just package Helvetica with this to make sure everyone has the same font in plots.

Luckily for fonts it seems only the software is copyrighted, not the actual shapes, which means there are quite a few open alternatives with similar look. The most closely resembling Helvetica being Tex Gyre Heros

Tex Gyre Heros

http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros

You can compare yourself if the differences are meanigful below.

They are Tex Gyre Heros, Helvetica and Arial respectively.

Math Fonts

  • Math fonts are a separate set from regular fonts due to the amount of special characters
  • It's not trivial to make sure you get a matching math font to your regular font
  • Most math-fonts are serif fonts, but this is not ideal if one wants to use sans-serif font for normal text like Helvetica or Arial
  • The number of sans-serif math-fonts is very limited

For consistent styling Fira Sans is included as well.

Default Fira Sans

https://github.com/mozilla/Fira

Math font extension

https://github.com/firamath/firamath

What doesn't work

Context styles and fonts

with pyplot.style.context(style.ROOT):
    plotting...

For now one has to set the style globally:

Use in publications

Updating list of citations and use cases of mplhep in publications:

Project details


Release history Release notifications | RSS feed

This version

0.4.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mplhep-0.4.0.tar.gz (1.6 MB view details)

Uploaded Source

Built Distribution

mplhep-0.4.0-py3-none-any.whl (48.4 kB view details)

Uploaded Python 3

File details

Details for the file mplhep-0.4.0.tar.gz.

File metadata

  • Download URL: mplhep-0.4.0.tar.gz
  • Upload date:
  • Size: 1.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mplhep-0.4.0.tar.gz
Algorithm Hash digest
SHA256 485d67db2dd7a1091eee86580fe46cf32dd0b0fc34d6db6246b1ef59346a810c
MD5 d015560a58752eaec926a295ada87d63
BLAKE2b-256 ac15aa82c96b15f181289f7f2a593cb75e62d29bf63cf8e5c3e1f36fcff6d72d

See more details on using hashes here.

Provenance

The following attestation bundles were made for mplhep-0.4.0.tar.gz:

Publisher: cd.yml on scikit-hep/mplhep

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mplhep-0.4.0-py3-none-any.whl.

File metadata

  • Download URL: mplhep-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 48.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mplhep-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c9ab1786157bda0a214f92e48ccf21a4d8ff08f44e5f34857739bbc837d1ec28
MD5 8cfffa2c480c3abb03119d1b419523c7
BLAKE2b-256 0bad7d61c08d945a598fa19d05f73309f57bea694480ae90ab9ea1339d5bf704

See more details on using hashes here.

Provenance

The following attestation bundles were made for mplhep-0.4.0-py3-none-any.whl:

Publisher: cd.yml on scikit-hep/mplhep

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page