A package for using Billinge group style files
- bg-mpl-stylesheets is a Python software package that creates a standardized matplotlib figure format. This includes specialized fonts, figure border, color cycle, tick parameters, and more.
If you use bg-mpl-stylesheets in a scientific publication, we would like you to cite this package as
bg-mpl-stylesheets Package, https://github.com/Billingegroup/bg-mpl-stylesheets
The preferred method is to use Miniconda Python and install from the "conda-forge" channel of Conda packages.
To add "conda-forge" to the conda channels, run the following in a terminal.
conda config --add channels conda-forge
We want to install our packages in a suitable conda environment.
The following creates and activates a new environment named bg-mpl-stylesheets_env
conda create -n bg-mpl-stylesheets_env python=3 conda activate bg-mpl-stylesheets_env
Then, to fully install bg-mpl-stylesheets in our active environment, run
conda install --file requirements/examples.txt conda install bg-mpl-stylesheets
Another option is to use pip to download and install the latest release from
Python Package Index.
To install using pip into your bg-mpl-stylesheets_env environment, type
pip install bg-mpl-stylesheets
If you prefer to install from sources, after installing the dependencies, obtain the source archive from
GitHub. Once installed, cd into your bg-mpl-stylesheets directory
and run the following
pip install .
matplotlib can accept a manually defined stylesheet file that is located remotely or locally.
By default the package uses LaTeX fonts for mathematical symbols. This feature requires a Latex package on your computer. It is not required for the use of the style-sheet but gives better results for things like angstrom symbols. Matplotlib will look for your installed latex package, for example TeXLive or MikTex. If it can't find a latex package it will look for non-latex font replacements.
To use the stylesheet, near the beginning your python script type
from bg_mpl_stylesheets.styles import all_styles plt.style.use(all_styles["<style-name>"])
for example
from bg_mpl_stylesheets.styles import all_styles plt.style.use(all_styles["bg-style"])
If you wish to use BillingeGroup stylesheet as the default style for all your plots, please follow these steps.
Use following commands to figure out which matplotlib config directory on your system:
import matplotlib config_dir = matplotlib.get_configdir()
Copy and paste the
bg_mpl_stylesheetfile from this repo to theconfig_dirfound in the previous step.
You can configure any matplotlib style parameter by updating its value in the rcParams dictionary dynamically in your python session, For example, by typing:
plt.rcParams['figure.dpi'] = 180 plt.rcParams['font.size'] = 18 (... and so on)
Not that the rcParams are global. It can get very confusing if these are updated everywhere in the code. It is much better to make local updates to their values by defining functions for your plots and using the @matplotlib.style.context() decorator, e.g.,
import matplotlib.pyplot as plt
@mpl.rc_context({'lines.linewidth': 1, 'axes.linewidth': 0.7, 'xtick.major.size':
0.7, 'xtick.major.width': 0.7, 'xtick.labelsize': 5, 'legend.frameon': False,
'legend.loc': 'best', 'font.size': 5, 'axes.labelsize': 5, 'ytick.left': False,
'ytick.labelleft': False, 'ytick.right': False
})
def all_plot(x-array, yarray):
plt.plot(x-array, y-array)
plt.ylabel('some numbers')
plt.show()
return
This will confine the style updates to just apply in the function namespace.
You can also update style parameters locally by using the matplotlib style context manager, for example:
with plot.style.context(<new_stylesheet>):
plt.plot(x-array, y-array)
plt.ylabel('some numbers')
plt.show()
Here are a snapshot of values in all_styles["bg-style"] sheet which you may override with rc.parms to fine tune things:
'lines.linewidth': 2.50,
'lines.markeredgewidth': 0.25,
'lines.markersize': 6.00,
'lines.solid_capstyle': 'round',
'font.size': 15.0,
'font.family': ['sans-serif'],
###################
# axes properties #
###################
'axes.titlesize': 14.0,
'axes.labelsize': 16.0,
'axes.labelcolor': 'k',
'axes.linewidth': 2.5,
'axes.edgecolor': 'k',
'axes.prop_cycle': cycler('color',
['#0B3C5D', '#B82601', '#1C6B0A', '#328CC1',
'#A8B6C1', '#D9B310', '#6C5050', '#76323F',
'#626E60', '#918770', '#C09F80', '#B0B0B0FF']),
####################
# xtick properties #
####################
'xtick.top': True,
'xtick.direction': 'in',
'xtick.color': 'k',
'xtick.labelsize': 15.0,
'xtick.minor.width': 0.5,
'xtick.major.width': 1.7,
'xtick.major.pad': 5.0,
####################
# ytick properties #
####################
'ytick.right': True,
'ytick.direction': 'in',
'ytick.color': 'k',
'ytick.labelsize': 15.0,
'ytick.minor.width': 0.5,
'ytick.major.width': 1.7,
'ytick.major.pad': 5.0,
###################
# grid properties #
###################
'grid.color': '#b2b2b2',
'grid.linestyle': '--',
'grid.linewidth': 1.0,
#####################
# figure properties #
#####################
'figure.facecolor': 'w',
'savefig.bbox': 'tight'
You may select a specific color to plot from Colors:
from bg_mpl_stylesheets.colors import Colors
# Get color name
Colors.bg_blue.name # returns "bg_blue"
# Get hex color code
Colors.bg_blue.value # returns "#0B3C5D"
# Get color name from a hex code
color_name = Colors(hex).name # returns: 'bg_blue'
# Get a list of all bg-style color objects
bg_colors = Colors.get_bg_colors()
# Assign colors to variables with short names
og = Colors.bg_olive_green
plt.plot(x, y, color=og.value, label=f'Color: {og.name}')
# if you know the hex and need the name. E.g., you want to make the plot shown here
for i, hex in enumerate(cycle):
ax.plot(x, y + offset * i, label=Colors(hex).name, color=hex, linestyle="-")
Here are available colors in Colors:
bg_blue = "#0B3C5D" bg_red = "#B82601" bg_green = "#1C6B0A" bg_light_blue = "#328CC1" bg_light_grey = "#A8B6C1" bg_yellow = "#D9B310" bg_brown = "#6C5050" bg_burgundy = "#76323F" bg_olive_green = "#626E60" bg_muted_olive = "#918770" bg_beige = "#C09F80" bg_grey = "#B0B0B0FF" columbia_blue = "#B9D9EB"
You may select the specific color to plot:
import matplotlib.pyplot as plt
from bg_mpl_stylesheets.colors import Colors
x = [0, 1, 2, 3, 4, 5]
y = [i ** 3 for i in x] # Example data: y = x^3
plt.plot(x, y, color=Colors.bg_blue.value, label=f'Color: {Colors.bg_blue.name}')
plt.title("Plot Example Using Enum Colors")
plt.xlabel("X-axis")
plt.ylabel("Y-axis")
plt.legend()
plt.show()
You can also go to the example folder and run plot.py for testing. The example plot would be like this:
Run color_cycles.py to see the full color cycle of the bg-style:
For full reference, please see matplotlib doc: https://matplotlib.org/stable/users/prev_whats_new/dflt_style_changes.html
Diffpy user group is the discussion forum for general questions and discussions about the use of bg-mpl-stylesheets. Please join the bg-mpl-stylesheets users community by joining the Google group. The bg-mpl-stylesheets project welcomes your expertise and enthusiasm!
If you see a bug or want to request a feature, please report it as an issue and/or submit a fix as a PR. You can also post it to the Diffpy user group.
Feel free to fork the project and contribute. To install bg-mpl-stylesheets in a development mode, with its sources being directly used by Python rather than copied to a package directory, use the following in the root directory
pip install -e .
To ensure code quality and to prevent accidental commits into the default branch, please set up the use of our pre-commit hooks.
- Install pre-commit in your working environment by running
conda install pre-commit. - Initialize pre-commit (one time only)
pre-commit install.
Thereafter your code will be linted by black and isort and checked against flake8 before you can commit. If it fails by black or isort, just rerun and it should pass (black and isort will modify the files so should pass after they are modified). If the flake8 test fails please see the error messages and fix them manually before trying to commit again.
Improvements and fixes are always appreciated.
Before contribuing, please read our Code of Conduct.
For more information on bg-mpl-stylesheets please visit the project web-page or email Prof. Simon Billinge at sb2896@columbia.edu.