Styling Guide

Understanding Styles

A style in PubPlotLib consists of:

  1. Column Widths: Figure dimensions for single and double-column layouts

  2. Matplotlib Style File (.mplstyle): Visual settings (fonts, colors, line widths, etc.)

Built-in Styles

PubPlotLib comes with several pre-configured styles:

  • aanda: Astronomy & Astrophysics journal style

  • apj: Astrophysical Journal style

  • presentation: For presentations and slides

Applying Styles

Global Style

Set a style globally so all subsequent figures use it:

import pubplotlib as pplt

pplt.style.use('aanda')

# All figures created after this will use 'aanda' style

Local Style (Per-Figure)

Apply a style to a specific figure without affecting the global state:

import pubplotlib as pplt

fig, ax = pplt.subplots(style='aanda')
# This figure uses 'aanda' style
# Global state is unchanged

fig2, ax2 = pplt.subplots(style='apj')
# This figure uses 'apj' style

Creating Custom Styles

Create your own style by defining a new Style object:

import pubplotlib as pplt

# Create a custom style
my_style = pplt.Style(
    name='my_journal',
    onecol=3.5,        # Single-column width in inches
    twocol=7.0,        # Double-column width in inches
    mplstyle='my_style.mplstyle'  # Path to matplotlib style file
)

Step 1: Create the .mplstyle File

Create a file my_style.mplstyle with Matplotlib style settings:

# Font settings
font.family: serif
font.serif: Times, DejaVu Serif
font.size: 10

# Axes settings
axes.labelsize: 10
axes.titlesize: 12
axes.linewidth: 0.8

# Tick settings
xtick.labelsize: 9
ytick.labelsize: 9
xtick.major.width: 0.8
ytick.major.width: 0.8

# Line and patch settings
lines.linewidth: 1.5
patch.linewidth: 0.8

# Legend settings
legend.fontsize: 9
legend.framealpha: 0.9

# Figure settings
figure.autolayout: True
savefig.format: pdf
savefig.dpi: 300
savefig.bbox: tight

Step 2: Register Your Style

Register your style to make it available globally:

import pubplotlib as pplt

my_style = pplt.Style(
    name='my_journal',
    onecol=3.5,
    twocol=7.0,
    mplstyle='my_style.mplstyle'
)

# Register the style (saves it to ~/.pubplotlib/style/)
my_style.register(overwrite=True)

Now you can use it like a built-in style:

pplt.style.use('my_journal')
fig, ax = pplt.subplots(style='my_journal')

Step 3 (Optional): Customize Further

You can also create a custom .mplstyle by modifying an existing one:

import pubplotlib as pplt
from pathlib import Path

# Copy and modify the aanda style
my_style = pplt.Style(
    name='aanda_custom',
    onecol=3.54,   # A&A standard
    twocol=7.25,   # A&A standard
    mplstyle='aanda_custom.mplstyle'
)

my_style.register(overwrite=True)

Managing Styles

View Available Styles

import pubplotlib as pplt

styles = pplt.style.available()
for style_name in styles:
    s = pplt.style.get(style_name)
    print(f"{style_name}: {s.onecol}\" x ? (1 col), {s.twocol}\" x ? (2 col)")

Get Current Style

import pubplotlib as pplt

current = pplt.style.current()
print(f"Current style: {current}")

Get Style Details

import pubplotlib as pplt

s = pplt.style.get('aanda')
print(f"One-column: {s.onecol} inches")
print(f"Two-column: {s.twocol} inches")
print(f"Style file: {s.mplstyle}")

Remove a Custom Style

import pubplotlib as pplt

pplt.stylebuilder.remove_style('my_journal')

Matplotlib Style Files Reference

Here are some common .mplstyle settings:

# Fonts
font.family: serif | sans-serif | monospace
font.size: 10
font.serif: Times New Roman, Times, DejaVu Serif
font.sans-serif: Arial, Helvetica, DejaVu Sans

# Text rendering
text.usetex: False | True  # Use LaTeX rendering
text.latex.preamble: \usepackage{amsmath}

# Axes
axes.labelsize: 10
axes.titlesize: 12
axes.linewidth: 0.8
axes.grid: False | True
axes.axisbelow: True
axes.xmargin: 0.0
axes.ymargin: 0.05

# Ticks
xtick.labelsize: 9
ytick.labelsize: 9
xtick.major.size: 4
xtick.minor.size: 2
ytick.major.size: 4
ytick.minor.size: 2
xtick.major.width: 0.8
xtick.minor.width: 0.6
ytick.major.width: 0.8
ytick.minor.width: 0.6
xtick.direction: in | out
ytick.direction: in | out

# Lines and markers
lines.linewidth: 1.5
lines.markersize: 6

# Legend
legend.fontsize: 9
legend.framealpha: 0.9
legend.fancybox: True
legend.loc: best

# Figure
figure.figsize: 8.0, 6.0  # width, height in inches
figure.autolayout: True
figure.titlesize: 14

# Saving figures
savefig.dpi: 300
savefig.bbox: tight
savefig.format: pdf
savefig.transparent: False

For a complete reference, see Matplotlib’s style documentation.