FAQ & Troubleshooting¶

Installation & setup¶

What Python versions are supported?¶

Python 3.10, 3.11, 3.12, and 3.13.

Do I need to install LaTeX?¶

No. PlotStyle uses Matplotlib’s built-in MathText renderer by default. LaTeX is optional. Use latex="auto" to enable it when available and fall back silently otherwise:

with plotstyle.use("nature", latex="auto") as style:
    ...

Use latex=True if you want an explicit error when LaTeX is not on your PATH.

Does PlotStyle work with Seaborn?¶

Yes. See the Seaborn integration guide.

Style & figures¶

Why do my figures look different after the `with` block ends?¶

plotstyle.use() snapshots and restores Matplotlib’s rcParams. When the block exits, the original settings come back. Figures created inside the block are already rendered and are not affected. Only new figures created after the block use the restored defaults.

Can I use `plotstyle.use()` without a context manager?¶

Yes. Call style.restore() manually when you are done:

style = plotstyle.use("nature")
# ... create figures ...
style.restore()

Calling restore() more than once is safe: subsequent calls are no-ops.

`style.figure()` raises `RuntimeError`. Why?¶

This happens when the journal’s column widths are not officially defined (Springer, for example, defers figure dimensions to individual journals). In this case, pass an explicit figsize to plt.subplots() directly:

fig, ax = plt.subplots(figsize=(3.5, 2.5))

To check before calling:

from plotstyle.specs import registry
spec = registry.get("springer")
spec.is_official("dimensions.single_column_mm")  # False

What does `columns=1` vs `columns=2` mean?¶

columns=1: single-column width (89 mm for Nature, 86.4 mm for Science)
columns=2: full text width (183 mm for Nature, 177.8 mm for Science)

Exact sizes come from each journal’s spec.

Why does `style.subplots()` always return a 2-D array?¶

By default, style.subplots() always returns a 2-D ndarray so you can use axes[i, j] indexing and axes.flat iteration for any grid shape without special-casing single rows or columns.

Pass squeeze=True to get Matplotlib-compatible behavior where size-1 dimensions are dropped:

fig, axes = style.subplots(nrows=1, ncols=3, squeeze=True)
for ax in axes:   # 1-D array
    ax.plot([1, 2, 3])

What is the difference between `fig.savefig()` and `style.savefig()`?¶

fig.savefig() is standard Matplotlib. style.savefig() adds two guarantees scoped to the single call:

pdf.fonttype and ps.fonttype are set to 42 (TrueType), preventing Type 3 fonts that many journal portals reject.
The journal’s minimum DPI is enforced when a journal spec is active.

Neither setting persists after the call returns.

Palettes & colors¶

How do I get the journal’s color palette without plotting?¶

Use style.palette() inside the context manager, or plotstyle.palette() outside:

colors = plotstyle.palette("nature", n=4)
# ['#E69F00', '#56B4E9', '#009E73', '#F0E442']

How do I access a built-in palette by name, without a journal?¶

Use plotstyle.apply_palette() to set the color cycle on an axes, or load_palette() to get the raw hex list:

from plotstyle.color.palettes import load_palette
colors = load_palette("okabe-ito")

plotstyle.apply_palette("tol-bright", ax=ax)

Available palette names: plotstyle.list_palettes().

How do I check if my palette is grayscale-safe?¶

from plotstyle.color.grayscale import is_grayscale_safe
is_grayscale_safe(colors, threshold=0.1)   # True or False

My journal requires grayscale-safe figures. What do I do?¶

Use with_markers=True when calling style.palette() to get (color, linestyle, marker) tuples:

for color, linestyle, marker in style.palette(n=3, with_markers=True):
    ax.plot(x, y, color=color, linestyle=linestyle, marker=marker, markevery=15)

Or apply the safe-grayscale overlay, but note that this will trigger a PaletteColorblindWarning on journals that require colorblind-safe colors (such as Science), since grayscale is not a substitute for colorblind safety.

Export & fonts¶

Why does `style.savefig()` print output to stderr?¶

It prints a compliance summary (dimensions, DPI, saved path) to stderr. Pass quiet=True to suppress it:

style.savefig(fig, "figure1.pdf", quiet=True)

Type 3 font warnings are emitted via Python’s warnings module regardless of quiet.

What are Type 3 fonts and why are they bad?¶

Type 3 fonts are bitmap fonts that many journal submission portals actively reject. PlotStyle sets pdf.fonttype=42 and ps.fonttype=42 on every savefig() call to enforce TrueType embedding instead.

My PDF still has Type 3 fonts. Why?¶

This can happen when:

You use latex=True and your LaTeX installation does not embed fonts by default. Add \usepackage[T1]{fontenc} to your LaTeX preamble, or switch to latex=False.
You saved with fig.savefig() instead of style.savefig(). The TrueType guarantee only applies to PlotStyle’s wrapper.

PlotStyle emits a warning via warnings.warn if it detects /Type3 in the saved PDF.

How do I check which fonts a journal requires?¶

plotstyle fonts --journal nature

This shows the preferred font list, which fonts are installed on your system, and which one was selected.

A font warning appeared. What does it mean?¶

A FontFallbackWarning means the journal’s preferred font is not installed and PlotStyle fell back to the next available option in its preference list. The figure will render correctly but may not use the journal’s recommended typeface. Install the missing font at the OS level, then rebuild Matplotlib’s font cache:

from matplotlib.font_manager import _load_fontmanager
_load_fontmanager(try_read_cache=False)

This may take a minute while Matplotlib scans all system fonts. Let it finish.

Validation¶

What does `WARN` vs `FAIL` mean in a validation report?¶

FAIL: the figure does not meet a journal-official requirement. report.passed returns False.
WARN: the check flagged an issue against a library-assumed default (the journal’s guidelines did not define this field). Advisory only; does not affect report.passed.

Can I skip specific validation checks?¶

Not via the public validate() API. All registered checks run in one pass.

Overlays¶

What is the difference between a journal preset and an overlay?¶

A journal preset (e.g. "nature") is a full specification: fonts, sizes, line widths, DPI, color requirements, and export formats. It connects to the spec registry so validate() and export_submission() know the journal’s rules.

An overlay is a partial, additive rcParam patch. It changes only the specific keys listed in its TOML file and has no journal-specific requirements.

Can I stack multiple overlays?¶

Yes. Pass them all in a list. Overlays are applied in declaration order; the last overlay wins on any rcParam key conflict:

with plotstyle.use(["nature", "minimal", "tol-bright"]) as style:
    ...

Can I use overlays without a journal?¶

Yes. Pass overlay keys without a journal key:

with plotstyle.use(["notebook", "minimal"]) as style:
    fig, ax = style.figure()   # falls back to Matplotlib's default size

Without a journal, style.palette(), style.validate(), and style.export_submission() raise RuntimeError. style.figure() and style.subplots() still work.

I see an `OverlaySizeWarning`. What does it mean?¶

An overlay you applied sets a figure.figsize width wider than the journal’s double-column width. This will produce a figure that is too large for the journal. Either remove the conflicting overlay or reduce the figure width manually.

I see a `PaletteColorblindWarning`. What does it mean?¶

You applied the safe-grayscale overlay on a journal that requires colorblind-safe colors (Science, for example). Grayscale is not a substitute for colorblind safety. Use a colorblind-safe palette such as okabe-ito or tol-bright instead.

Migration¶

Does `migrate()` modify my figure permanently?¶

Yes. plotstyle.migrate() mutates the figure in place and returns it. Clone it first if you need to keep the original:

import copy
fig_copy = copy.deepcopy(fig)
plotstyle.migrate(fig_copy, from_journal="nature", to_journal="ieee")

CLI¶

What can the CLI do?¶

The plotstyle command provides journal discovery and validation without writing Python:

plotstyle list                          # list all supported journals
plotstyle info nature                   # show Nature's full spec
plotstyle diff nature science           # compare two journals side by side
plotstyle fonts --journal ieee          # check font availability for IEEE
plotstyle overlays                      # list all overlays
plotstyle overlays --category color     # filter by category
plotstyle validate figure1.pdf --journal nature   # check font embedding

Build errors¶

Sphinx build fails with “module not found”¶

The package must be installed before building docs:

pip install -e ".[docs]"
hatch run docs:build