API Reference

Main Functions

Figure and Subplot Creation

pubplotlib.figure(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None, journal=None, **kwargs)[source]: Create a figure with style-appropriate dimensions.

pubplotlib.subplots(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None, journal=None, **kwargs)[source]: Create subplots with style-appropriate dimensions.

Style Management

pubplotlib.set_style(style=None)[source]: Apply the style. Does nothing if already set.

pubplotlib.set_journal(journal=None)[source]: Apply the journal style. Does nothing if already set.

pubplotlib.get_style(style=None)[source]: Return a Style instance (from string or directly).

pubplotlib.available_styles()[source]: Return a list of available styles.

pubplotlib.restore()[source]: Restore matplotlib’s default style.

Figure Sizing

pubplotlib.setup_figsize(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None)[source]: Return (width, height) in inches for the style.

Axis Formatting

pubplotlib.set_ticks(ax=None, minor=True, direction='in', right=True, top=True, major_length=3.5, minor_length=1.75)[source]

Configure tick appearance on axes.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to configure. If None, uses current axes.
minor (bool, default True) – Whether to show minor ticks.
direction ({'in', 'out', 'inout'}, default 'inout') – Direction of tick marks.
right (bool, default False) – Whether to show ticks on right y-axis.
top (bool, default False) – Whether to show ticks on top x-axis.
major_length (float, default 3.5) – Length of major ticks.
minor_length (float, default 1.75) – Length of minor ticks.

pubplotlib.set_formatter(ax=None, low=0.01, high=100, axis='both')[source]

Apply custom formatting to axis that preserves matplotlib’s tick placement.

Uses decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to format. If None, uses current axes.
low (float, default 0.01) – Lower bound for decimal notation.
high (float, default 100) – Upper bound for decimal notation.
axis ({'x', 'y', 'both'}, default 'both') – Which axes to format.

Examples

>>> fig, ax = plt.subplots()
>>> ax.loglog(x, y)
>>> set_formatter(ax, low=0.01, high=100)

Style Namespace

The pplt.style object provides a matplotlib-like interface:

class pubplotlib.pubplotlib._StyleManager[source]

Manager for style operations, providing a matplotlib-like interface.

Mimics matplotlib.style.use() syntax while integrating with PubPlotLib’s style framework.

use(style=None)[source]

Apply a style globally. Mimics matplotlib.style.use() syntax.

Parameters:: style (str or Style, optional) – Name of the style to apply, or a Style instance.

Examples

>>> pplt.style.use('aanda')

available()[source]

Return list of available styles.

Returns:: Names of all available styles.
Return type:: list

Examples

>>> pplt.style.available()
['aanda', 'apj', 'presentation']

get(style=None)[source]

Get a Style instance.

Parameters:: style (str or Style, optional) – Name of the style or a Style instance. If None, returns the current active style.
Returns:: The requested Style instance.
Return type:: Style

Examples

>>> s = pplt.style.get('aanda')
>>> print(s.onecol, s.twocol)

current()[source]

Get the name of the currently active style.

Returns:: Name of the current style.
Return type:: str

Examples

>>> pplt.style.current()
'aanda'

restore()[source]

Restore matplotlib’s default style.

Examples

>>> pplt.style.restore()

Style Objects

class pubplotlib.stylebuilder.Style(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Represents a generic figure formatting style (journal, slide, poster, etc).

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)

name

The style’s name.

Type:: str

onecol

Width of a single column (in inches).

Type:: Optional[float]

twocol

Width of a double column (in inches).

Type:: Optional[float]

fullpage

Width of a full page (in inches).

Type:: Optional[float]

mplstyle

Path to the associated .mplstyle file.

Type:: Optional[str]

register(overwrite=False)[source]

Register this Style in the user’s styles YAML file. Copies the mplstyle file into the user’s style directory if needed.

Parameters:: overwrite (bool) – If True, overwrite existing entry and style file.

class pubplotlib.stylebuilder.Journal(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)

Constants

pubplotlib.golden = 1.618033988749895: Convert a string or number to a floating point number, if possible.

pubplotlib.pt = 0.013837000138370002: Convert a string or number to a floating point number, if possible.

pubplotlib.cm = 0.39370078740157477: Convert a string or number to a floating point number, if possible.

Formatter Utilities

class pubplotlib.formatter.ScalarFormatter(low=0.001, high=1000.0, **kwargs)[source]

Custom scalar formatter with configurable scientific notation bounds.

Shows decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

low (float, default 1e-3) – Lower bound for decimal notation.
high (float, default 1e3) – Upper bound for decimal notation.
**kwargs – Additional arguments passed to matplotlib’s ScalarFormatter.

class pubplotlib.formatter.LogFormatterSciNotation(low=0.001, high=1000.0, **kwargs)[source]

Custom logarithmic formatter with configurable scientific notation bounds.

Shows decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

low (float, default 1e-3) – Lower bound for decimal notation.
high (float, default 1e3) – Upper bound for decimal notation.
**kwargs – Additional arguments passed to matplotlib’s LogFormatterSciNotation.

Style Builder Module

pubplotlib.stylebuilder.check_fonts(font_list=None, verbose=True)[source]: Check if the required fonts are available to Matplotlib. Prints a summary and returns a dict {font_name: found_bool}.

pubplotlib.stylebuilder.build_builtin_styles(overwrite=False)[source]

Build and write the default built-in styles YAML file with standard styles (e.g., journals). Overwrites the file if overwrite=True.

Parameters:: overwrite (bool) – if True, overwrites the YAML file if it exists.
Returns:: The built-in style dict with dimensions in inches and style paths.
Return type:: Dict[str, Dict[str, object]]

pubplotlib.stylebuilder.remove_style(name)[source]

Remove a user style from the user YAML registry and delete its style file. Built-in styles cannot be removed.

Parameters:: name (str) – The name of the style to remove.

class pubplotlib.stylebuilder.Style(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Bases: object

Represents a generic figure formatting style (journal, slide, poster, etc).

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)

name

The style’s name.

Type:: str

onecol

Width of a single column (in inches).

Type:: Optional[float]

twocol

Width of a double column (in inches).

Type:: Optional[float]

fullpage

Width of a full page (in inches).

Type:: Optional[float]

mplstyle

Path to the associated .mplstyle file.

Type:: Optional[str]

register(overwrite=False)[source]

Register this Style in the user’s styles YAML file. Copies the mplstyle file into the user’s style directory if needed.

Parameters:: overwrite (bool) – If True, overwrite existing entry and style file.

class pubplotlib.stylebuilder.Journal(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Bases: Style

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)

Formatter Module

class pubplotlib.formatter.LogFormatterSciNotation(low=0.001, high=1000.0, **kwargs)[source]

Bases: LogFormatterSciNotation

Custom logarithmic formatter with configurable scientific notation bounds.

Shows decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

low (float, default 1e-3) – Lower bound for decimal notation.
high (float, default 1e3) – Upper bound for decimal notation.
**kwargs – Additional arguments passed to matplotlib’s LogFormatterSciNotation.

class pubplotlib.formatter.ScalarFormatter(low=0.001, high=1000.0, **kwargs)[source]

Bases: ScalarFormatter

Custom scalar formatter with configurable scientific notation bounds.

Shows decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

low (float, default 1e-3) – Lower bound for decimal notation.
high (float, default 1e3) – Upper bound for decimal notation.
**kwargs – Additional arguments passed to matplotlib’s ScalarFormatter.

class pubplotlib.formatter.SelectiveFormatter(tick_labels, *args, **kwargs)[source]

Bases: LogFormatterSciNotation

Formatter that only displays labels for specified tick values.

Useful for showing labels only on major ticks while keeping minor ticks unlabeled.

Parameters:

tick_labels (array-like) – The numerical values for which labels should be shown.
*args – Additional arguments passed to LogFormatterSciNotation.
**kwargs – Additional arguments passed to LogFormatterSciNotation.

Examples

>>> import matplotlib.pyplot as plt
>>> import matplotlib.ticker as ticker
>>>
>>> # Setup selective formatting
>>> tickvalues = generate_log_ticks(0.01, 100)
>>> major_ticks = generate_powers_of_10_ticks(0.01, 100)
>>> minor_ticks = filter_major_ticks(tickvalues, major_ticks)
>>> formatter = SelectiveFormatter(major_ticks)
>>>
>>> # Apply to axes
>>> fig, ax = plt.subplots()
>>> ax.xaxis.set_major_formatter(formatter)
>>> ax.xaxis.set_major_locator(ticker.FixedLocator(major_ticks))
>>> ax.xaxis.set_minor_locator(ticker.FixedLocator(minor_ticks))

pubplotlib.formatter.set_formatter(ax=None, low=0.01, high=100, axis='both')[source]

Apply custom formatting to axis that preserves matplotlib’s tick placement.

Uses decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to format. If None, uses current axes.
low (float, default 0.01) – Lower bound for decimal notation.
high (float, default 100) – Upper bound for decimal notation.
axis ({'x', 'y', 'both'}, default 'both') – Which axes to format.

Examples

>>> fig, ax = plt.subplots()
>>> ax.loglog(x, y)
>>> set_formatter(ax, low=0.01, high=100)

Tick Setter Module

pubplotlib.ticksetter.set_ticks(ax=None, minor=True, direction='in', right=True, top=True, major_length=3.5, minor_length=1.75)[source]

Configure tick appearance on axes.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to configure. If None, uses current axes.
minor (bool, default True) – Whether to show minor ticks.
direction ({'in', 'out', 'inout'}, default 'inout') – Direction of tick marks.
right (bool, default False) – Whether to show ticks on right y-axis.
top (bool, default False) – Whether to show ticks on top x-axis.
major_length (float, default 3.5) – Length of major ticks.
minor_length (float, default 1.75) – Length of minor ticks.

Complete Module Reference

pubplotlib.set_style(style=None)[source]: Apply the style. Does nothing if already set.

pubplotlib.get_style(style=None)[source]: Return a Style instance (from string or directly).

pubplotlib.available_styles()[source]: Return a list of available styles.

pubplotlib.restore()[source]: Restore matplotlib’s default style.

pubplotlib.setup_figsize(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None)[source]: Return (width, height) in inches for the style.

pubplotlib.figure(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None, journal=None, **kwargs)[source]: Create a figure with style-appropriate dimensions.

pubplotlib.subplots(style=None, twocols=False, fullpage=False, width_fraction=1.0, height_ratio=None, journal=None, **kwargs)[source]: Create subplots with style-appropriate dimensions.

pubplotlib.set_journal(journal=None)[source]: Apply the journal style. Does nothing if already set.

pubplotlib.set_formatter(ax=None, low=0.01, high=100, axis='both')[source]

Apply custom formatting to axis that preserves matplotlib’s tick placement.

Uses decimal notation for values between low and high, and scientific notation outside this range.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to format. If None, uses current axes.
low (float, default 0.01) – Lower bound for decimal notation.
high (float, default 100) – Upper bound for decimal notation.
axis ({'x', 'y', 'both'}, default 'both') – Which axes to format.

Examples

>>> fig, ax = plt.subplots()
>>> ax.loglog(x, y)
>>> set_formatter(ax, low=0.01, high=100)

pubplotlib.set_ticks(ax=None, minor=True, direction='in', right=True, top=True, major_length=3.5, minor_length=1.75)[source]

Configure tick appearance on axes.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to configure. If None, uses current axes.
minor (bool, default True) – Whether to show minor ticks.
direction ({'in', 'out', 'inout'}, default 'inout') – Direction of tick marks.
right (bool, default False) – Whether to show ticks on right y-axis.
top (bool, default False) – Whether to show ticks on top x-axis.
major_length (float, default 3.5) – Length of major ticks.
minor_length (float, default 1.75) – Length of minor ticks.

class pubplotlib.Style(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Bases: object

Represents a generic figure formatting style (journal, slide, poster, etc).

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)

name

The style’s name.

Type:: str

onecol

Width of a single column (in inches).

Type:: Optional[float]

twocol

Width of a double column (in inches).

Type:: Optional[float]

fullpage

Width of a full page (in inches).

Type:: Optional[float]

mplstyle

Path to the associated .mplstyle file.

Type:: Optional[str]

register(overwrite=False)[source]

Register this Style in the user’s styles YAML file. Copies the mplstyle file into the user’s style directory if needed.

Parameters:: overwrite (bool) – If True, overwrite existing entry and style file.

class pubplotlib.Journal(name, onecol=None, twocol=None, fullpage=None, mplstyle=None)[source]

Bases: Style

Parameters:

name (str)
onecol (float | None)
twocol (float | None)
fullpage (float | None)
mplstyle (str | None)