bg-mpl-stylesheets 0.6.1

Citation

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

Installation

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 bg-mpl-stylesheets
conda activate bg-mpl-stylesheets_env

To confirm that the installation was successful, type

python -c "import bg_mpl_stylesheets; print(bg_mpl_stylesheets.__version__)"

The output should print the latest version displayed on the badges above.

If the above does not work, you can 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 .

This package also provides command-line utilities. To check the software has been installed correctly, type

bg-mpl-stylesheets --version

You can also type the following command to verify the installation.

python -c "import bg_mpl_stylesheets; print(bg_mpl_stylesheets.__version__)"

To view the basic usage and available commands, type

bg-mpl-stylesheets -h

Getting Started

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 stylesheet 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 use_style
use_style()

To use another stylesheet by name, pass the style name to use_style()

use_style("<style-name>")

If you wish to use Billinge group stylesheet as the default style for all your plots, please follow these steps.

1. Use the following commands to figure out which matplotlib config directory on your system:

   import matplotlib
   config_dir = matplotlib.get_configdir()

2. Copy and paste the bg_mpl_stylesheet file from this repo to the config_dir found in the previous step.

Overriding the default styles

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)

Note 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.params 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'

Get individual color and color name

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="-")

Color list

Here are the 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"

Use a specific color to plot

You may select a 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()

Example code

You can also go to the example folder and run plot.py for testing. Running it requires installing the additional example dependencies:

pip install -r requirements/examples.txt

The example plot would be like this:

Colors

Run color_cycles.py to see the full color cycle of the bg-style, which also requires installing the additional example dependencies if you have not done so:

pip install -r requirements/examples.txt

For full reference, please see matplotlib doc: https://matplotlib.org/stable/users/prev_whats_new/dflt_style_changes.html

Support and Contribute

The 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 via 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.

1. Install pre-commit in your working environment by running conda install pre-commit.

2. 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 contributing, please read our Code of Conduct.

Contact

For more information on bg-mpl-stylesheets please visit the project web-page or email the maintainers, Simon J.L. Billinge group (sbillinge@ucsb.edu).

Acknowledgements

bg-mpl-stylesheets is built and maintained with scikit-package.