paper_quality_plot_python

Python tools for publication-quality research figures.

This repository is a Python-first adaptation of a MATLAB plotting repository originally credited to Hyungtae Lim and Urban Robotics Lab @ KAIST, with additional credit in the original repository to Giseop Kim and Byeongho Yu. I am Chieh Tsai, a PhD student at the University of Arizona, and I prefer a Python-based research workflow. I built this version to make the original plotting ideas easier to reuse in modern Python projects.

I am grateful to the original author. The MATLAB repository was genuinely helpful for my research plotting workflow, and this Python version exists because that work gave me a strong starting point.

This repo is meant to be practical and open. If you find issues, want to improve the API, or would like to add more plotting coverage, contributions and discussion are welcome.

Provenance and credit

• Original MATLAB plotting repository concept and codebase: Hyungtae Lim, Urban Robotics Lab @ KAIST
• MATLAB repository README also credits: Giseop Kim and Byeongho Yu
• Python adaptation and packaging: Chieh Tsai, University of Arizona

This repository is a downstream Python adaptation. It does not replace the original MATLAB work, and it should be understood as a Python-oriented port of the reusable plotting ideas.

Why this repo exists

The original MATLAB repository contains many useful plotting patterns for paper figures:

• consistent paper-friendly styling
• distinguishable qualitative colors
• compact layouts with reduced whitespace
• CDF, line, boxplot, bar, and related figure patterns

This Python version keeps the same general design philosophy, but reorganizes the reusable parts into a maintainable Python package built around matplotlib.

Preview

Representative outputs from the current Python examples:

Trend / comparison	Distribution / robustness

Categorical comparison	Runtime / pipeline breakdown

Spatial trajectory	Weighted correspondence

Features

• publication-style figure defaults
• reusable color palette inspired by linspecer
• line plots and multi-series plots
• CDF plots
• boxplots
• PDF / histogram plots
• precision-recall curves
• horizontal stacked bars
• 2x2 tiled metric summaries
• export helpers for PNG / PDF / SVG
• simple class-based API via PlotPub

Plot categories

This repository is organized around common figure families that appear in research papers:

• Trend and comparison Line plots, multi-series plots, grouped bars, and tiled summaries for method-vs-method comparisons across conditions.
• Distribution and robustness CDFs, boxplots, and histogram-style PDFs for showing variance, stability, and tail behavior instead of only reporting means.
• Detection and ranking PR curves for threshold-sensitive evaluation and imbalanced settings.
• Systems and budget breakdown Horizontal stacked bars and stacked area plots for timing, resource, or pipeline composition analysis.
• Geometry and robotics Trajectory plots and weighted correspondence scatter plots for localization, matching, navigation, and robotics visual evidence.

Design principles

The plotting philosophy is intentionally research-oriented:

• figures should support a specific claim, not just look polished
• the same visual language should carry across an entire paper
• simple faithful plots are better than overloaded dashboards
• if the claim depends on robustness, show distributions rather than only averages
• if the claim depends on system cost, show decomposition rather than only totals
• if the claim depends on geometry, show spatial structure rather than only scalar metrics

Data expectations

Different figure families need different evidence:

• Line / bar / tiled summary Collect aligned measurements across methods and operating points; ideally 3 to 5 conditions at minimum.
• CDF / boxplot / PDF Keep raw per-trial values; 30 to 50 samples per condition is a practical minimum for stable distribution views.
• PR curve Keep prediction scores and binary labels, not only thresholded metrics.
• Runtime / budget plots Collect per-stage timing or resource counters, aligned over the same workload.
• Trajectory / correspondence plots Keep coordinate-level outputs, poses, matches, and optional weights or confidences.

Installation

python -m pip install -r requirements.txt

Optional editable install:

python -m pip install -e .

Quick start

from pathlib import Path
import numpy as np

from paper_quality_plot import PlotPub

plotter = PlotPub(output_dir=Path("examples_output"))

x = np.array([5, 10, 15])
series = {
    "A": [91.4, 94.0, 95.3],
    "B": [83.8, 91.8, 92.3],
    "C": [73.3, 80.9, 87.7],
}

fig, ax = plotter.multi_series(
    x,
    series,
    xlabel="X LABEL",
    ylabel="Y LABEL",
)
plotter.save(fig, "quickstart")

Run the examples

python examples/generate_examples.py

Generated outputs are written to:

examples_output/

Current examples include:

• line plot
• CDF plot
• horizontal stacked bar plot
• boxplot
• grouped bar plot
• PDF / histogram plot
• PR curve
• stacked time breakdown
• tiled metric summary
• 2D trajectory plot
• weighted correspondence scatter

MATLAB to Python coverage

The Python port currently covers the main reusable plot families from the MATLAB repository:

• template.m
• plot_linegraph*.m
• plot_cdf*.m
• calcCDF.m
• plot_horizontal_bars*.m
• plot_boxplot*.m
• plot_pdf.m
• plot_pr_curve.m
• plot_tilelayout.m
• linspecer.m

These are reorganized into reusable Python helpers rather than copied line by line.

The following MATLAB files are still more repository-specific and are not yet first-class Python helpers:

• plot_trajectory.m
• plot_trajectory_w_airbornej.m
• plot_scatter_w_heatmap.m
• plot_time_stacked.m
• parseCSV.m
• parseRawCSV.m
• calcModelAidedOutput.m
• RMSE.m

Project structure

paper_quality_plot/
  api.py
  core.py
  palette.py
  style.py
examples/
docs/
examples_output/

Tutorial

• docs/TUTORIAL_PYTHON.md
• docs/PLOT_GALLERY.md
• examples/README.md
• CREDITS.md

License

This repository keeps the original BSD 2-Clause license. Please retain the original copyright and license notice.