Onsaemiro

Publication-quality matplotlib styling for Academic Research.

Onsaemiro provides a streamlined interface for generating figures that meet the rigorous standards of scientific journals. It handles font scaling, consistent subplot positioning, colour-blind friendly palettes, and GitHub-safe progress bars — all with minimal boilerplate.

Key Features

• Fixed-Fraction Layout: Prevents axes jumping between figures by enforcing consistent subplot dimensions.
• Automatic Scaling: Adjusts font sizes, line widths, and tick marks based on the physical figure width.
• Academic Palettes: Built-in support for Okabe-Ito, Paul Tol (Vibrant, Muted, Bright), and IBM palettes.
• TableMaker: Renders LaTeX-style "booktabs" tables directly in Jupyter notebooks or the terminal.
• ProgressBar / track(): Static-HTML progress bar that survives GitHub's notebook renderer — no ipywidgets required.
• Context Management: Use fixed_frame for one-off figures with specific dimensions without affecting global settings.

Installation

Install Onsaemiro from PyPI:

pip install onsaemiro

The package is published on PyPI and can also be installed directly from a local clone.

For local development, clone the repository, move into the package directory, and run:

pip install -e .

The -e (editable) flag means changes to the Onsaemiro source are reflected immediately — no reinstall needed.

Quick Start

import onsaemiro as osm
import matplotlib.pyplot as plt
import numpy as np

# 1. Global setup
osm.set_style(figure_size=(3.5, 2.5), palette="okabe-ito")

# 2. Get the palette
colors = osm.get_palette()

# 3. Plotting
x = np.linspace(0, 10, 100)
fig, ax = plt.subplots()

ax.plot(x, np.sin(x), color=colors['blue'], label='Signal A')
ax.plot(x, np.cos(x), color=colors['orange'], label='Signal B')

ax.set_xlabel('Time (s)')
ax.set_ylabel('Amplitude (V)')
ax.legend()

# 4. Finalise (handles legend borders and origin overlaps)
osm.finalize(ax)
plt.show()

Core Components

1. Global Styling (set_style)

Configures plt.rcParams for publication. Unlike standard matplotlib behaviour, it disables autolayout to ensure that labels do not shift the axes box. Defaults to a Times-style serif font.

osm.set_style(
    base_fontsize=12.5,
    linewidth=1.2,
    figure_size=(3.5, 2.5),
    use_tex=False
)

2. Colour Palettes (Palette)

Access colours by name or index. Supports fuzzy name matching.

• okabe-ito (Default, colour-blind safe)
• paul-tol-vibrant | paul-tol-bright | paul-tol-muted
• ibm
• tableau10

p = osm.get_palette("vibrant")
color = p['red']    # Name access
color = p[0]        # Index access (wraps around)

3. Layout Control (fixed_frame)

A context manager for creating figures with precise axes placement.

with osm.fixed_frame(figure_size=(5, 4)) as (fig, ax):
    ax.scatter(data_x, data_y)
    # Axes position is determined by internal fractions,
    # ensuring consistent whitespace across different plots.

4. TableMaker

Creates professional tables for results analysis. In Jupyter, renders a monochrome theme inspired by academic journals (booktabs style). In terminals, renders via rich.

table = osm.TableMaker(
    title="Performance Metrics",
    columns=["Metric", "Result", "Unit"]
)
table.add_row("R-Squared", "0.9942", "—")
table.add_row("RMSE", "0.021", "m/s")
table.display()

For live updates during a loop (e.g. training), use mode="live":

table = osm.TableMaker(title="Training Log", columns=["Epoch", "Loss"], mode="live")
for epoch in range(10):
    loss = train_one_epoch()
    table.add_row(str(epoch), f"{loss:.4f}")

5. ProgressBar and track()

A static-HTML progress bar designed for Jupyter notebooks. Unlike tqdm.auto, it renders as plain text/html output — so the completed bar is preserved when notebooks are committed to GitHub, rather than showing an empty widget placeholder.

Simple iterator (tqdm-style)

for x in osm.track(range(1000), desc="Training"):
    osm.sleep(0.001)

Context manager (manual update)

Use this when the loop body controls iteration (e.g. custom data loaders).

with osm.ProgressBar(total=N, desc="Sweep") as pb:
    for i in range(N):
        compute(i)
        pb.update()

Joblib parallel jobs

When using joblib.Parallel, pass return_as="generator" and wrap with osm.track(). Results are yielded as each job completes, so the progress bar advances in real time.

from joblib import Parallel, delayed

def process(i):
    osm.sleep(0.05)   # simulate work
    return i ** 2

results = list(
    osm.track(
        Parallel(n_jobs=-1, return_as="generator")(
            delayed(process)(i) for i in range(100)
        ),
        total=100,
        desc="Parallel",
    )
)

Note: return_as="generator" requires joblib ≥ 1.2. The progress bar advances as jobs complete, not as they are dispatched — so the count accurately reflects finished work.

Key parameters

API Reference

Version History

• v1.0.1 (10 Aug 2026): Refactored the internal package structure while preserving the public API.
• v1.0.0 (24 Jul 2026): Initial Onsaemiro release, based on the final DataGraph 3.1.0 implementation.

Created and maintained by Hanseul Kang.