qlat_utils.qplot — Gnuplot-Based Plotting Utilities

Source: qlat-utils/qlat_utils/qplot.py

Note: Update this document when updating the source file.

Outline

  1. Overview

  2. Data Table I/O

  3. Plot Generation

  4. Display Helpers

  5. Module-Level Configuration

  6. Examples

Overview

qplot provides a lightweight interface for generating publication-quality plots using gnuplot as the backend. It handles:

  • Saving and loading numeric data tables (real and complex) as text files.

  • Generating gnuplot plotfiles and Makefiles in temporary directories.

  • Running make + gnuplot + pdflatex + pdftoppm to produce PNG/PDF output.

  • Displaying images inline in Jupyter notebooks.

The typical workflow is:

  1. Prepare data as a dict of 2-D arrays (dts).

  2. Write gnuplot commands (cmds) and plot lines (lines).

  3. Call plot_save() to render to a file, or plot_view() to display inline.

Data Table I/O

show_datatable

q.show_datatable(arr, *, is_return_list_of_string=False)

Convert a 2-D array to a whitespace-separated string (or list of lines). Supports real and complex numbers.

save_datatable

q.save_datatable(arr, fn, *, is_directory_exist=False)

Save a 2-D numpy array to a text file. Creates parent directories automatically.

read_datatable

q.read_datatable(lines)

Parse a string or list of strings into a list of lists of numbers (float or complex). Complex numbers are represented as real imagi (e.g. 1.5 2.0i).

load_datatable

q.load_datatable(fn)

Load a data table from a text file.

azip

q.azip(vec, *vecs)

Zip multiple 1-D arrays column-wise into a 2-D array, truncating to the shortest length. Useful for assembling (x, y, yerr) tables.

Plot Generation

plot_save

q.plot_save(
    fn=None, dts=None, cmds=None, lines=None, *,
    is_run_make=True, is_display=False, is_verbose=False,
    display_width=None,
)

Generate a plot and optionally render it.

Parameter

Description

fn

Output filename (e.g. "plot.png"), or None for a temporary plot

dts

Dict of { "table.txt": [[x, y, yerr], ...], ... }

cmds

List of gnuplot commands (e.g. ["set xlabel '$x$'"])

lines

List of gnuplot plot lines (e.g. ["plot", "'table.txt' w yerrorb"])

is_run_make

If True, run the Makefile to produce the plot

is_display

If True, display inline in Jupyter

Returns: Path to the generated PNG, or to the source directory if is_run_make=False.

When called with all None arguments, generates a demo cosine plot and prints the full call signature for easy copy-paste customisation.

plot_view

q.plot_view(
    fn=None, dts=None, cmds=None, lines=None, *,
    is_verbose=False, display_width=None,
)

Convenience wrapper around plot_save with is_display=True. Renders the plot and displays it inline in a Jupyter notebook.

Display Helpers

display_img

q.display_img(fn, *, width=None)

Display an image file in a Jupyter notebook using IPython.display.

Module-Level Configuration

gnuplot_png_density

q.gnuplot_png_density  # default: 500

DPI for the pdftoppm PNG rasterisation step.

gnuplot_plotfile_header

q.gnuplot_plotfile_header  # default: ["set terminal epslatex standalone color clip lw 3"]

Header lines prepended to every generated gnuplot plotfile.

plot_save_display_width

q.plot_save_display_width  # default: None

Default display width (in pixels) used by plot_view when showing images in Jupyter. Can be overridden per-call via the display_width parameter.

Examples

Simple scatter plot with error bars

import qlat_utils as q
import numpy as np

x = np.linspace(0, 2 * np.pi, 30)
y = np.sin(x)
yerr = 0.1 * np.ones_like(x)

q.plot_save(
    fn="sine_plot.png",
    dts={"sine.txt": q.azip(x, y, yerr)},
    cmds=[
        "set xlabel '$x$'",
        "set ylabel '$y$'",
        "set title 'Sine function'",
    ],
    lines=[
        "plot [:] [-1.5:1.5]",
        "sin(x) w l t '$\\sin(x)$'",
        "'sine.txt' u 1:2:3 w yerrorb t 'data'",
    ],
)

Display inline in Jupyter

import qlat_utils as q

q.plot_view(
    fn="my_plot.png",
    dts=dts,
    cmds=cmds,
    lines=lines,
    display_width=600,
)

Load a saved data table

import qlat_utils as q

data = q.load_datatable("sine.txt")
# data is a list of lists: [[x0, y0, yerr0], [x1, y1, yerr1], ...]