plot_columns

Command-line usage

usage: cell plot_columns [-h] [-xcolumn None] [-ycolumn None] [-t None]
                         [-xl None] [-yl None] [-yf 1.0] [-yrange None]
                         [-xrange None] [-colors None] [-width None]
                         [-height None] [-target-vs-predictions False]
                         [-loglog False] [-symlog False]
                         [-symlog-linthresh None] [-grid False]
                         [-grid-which major] [-grid-axis both]
                         [-grid-style None] [-show-yzero-axis False]
                         [-show-xlabel True] [-show-ylabel True]
                         [-show-xticklabels True] [-show-yticklabels True]
                         [-xaxis-top False] [-yaxis-right False]
                         [-xticks None] [-yticks None] [-legend True]
                         [-show-legend-frame True] [-legend-location best]
                         [-legend-handlelength None]
                         [-legend-handletextpad None] [-show-plot True]
                         [-sf None] [-dpi 300.0] [-fdn None] [-series None]
                         [-xf 1.0] [-rc-params None] [-legend-ncols 1]
                         [-legend-bbox-to-anchor None] [-annotations None]
                         [-savefig-bbox-inches None]
                         [source_filepath]

positional arguments:
  source_filepath       Path to serialized DerivativeStructures or
                        StructuresSet object.

options:
  -h, --help            show this help message and exit
  -xcolumn None         Default x-axis column used by series that do not
                        define xcolumn.
  -ycolumn None         Default y-axis column used by series that do not
                        define ycolumn.
  -t, --title None      Figure title.
  -xl, --xlabel None    Label for the x-axis of the plot.
  -yl, --ylabel None    Label for the y-axis of the plot.
  -yf, --yfactor 1.0    Multiplicative factor applied to y data before
                        plotting/export.
  -yrange None          Range for the y-axis of the plot (min,max).
  -xrange None          Range for the x-axis of the plot (min,max).
  -colors None          Optional list of default colors for series without
                        explicit color.
  -width None           Figure width in inches.
  -height None          Figure height in inches.
  -target-vs-predictions False
                        Enable target-vs-predictions parity mode: square axes,
                        shared limits, and y=x line.
  -loglog False         Use logarithmic scale on both x and y axes.
  -symlog False         Use symmetric logarithmic scale on both axes; supports
                        negative and zero values.
  -symlog-linthresh None
                        Linear threshold around zero for symlog axes. Inferred
                        from data when omitted.
  -grid False           Show plot grid lines.
  -grid-which major     Grid lines to draw: major, minor, or both.
  -grid-axis both       Axis for grid lines: both, x, or y.
  -grid-style None      Optional matplotlib grid style dictionary, e.g.
                        {linewidth=0.5, alpha=0.4}.
  -show-yzero-axis False
                        Show horizontal reference line at y=0.
  -show-xlabel True     Show x-axis name label.
  -show-ylabel True     Show y-axis name label.
  -show-xticklabels True
                        Show x-axis tick labels (numbers).
  -show-yticklabels True
                        Show y-axis tick labels (numbers).
  -xaxis-top False      Place x-axis label, tick marks, and tick labels on the
                        top side.
  -yaxis-right False    Place y-axis label, tick marks, and tick labels on the
                        right side.
  -xticks None          Custom x-axis tick locations.
  -yticks None          Custom y-axis tick locations.
  -legend True          Show legend if True.
  -show-legend-frame True
                        Show frame box around legend.
  -legend-location best
                        Legend position using Matplotlib names, e.g. upper
                        left/best.
  -legend-handlelength None
                        Legend handle length in font-size units.
  -legend-handletextpad None
                        Legend padding between handle and text in font-size
                        units.
  -show-plot True       Display the plot window if True.
  -sf, --savefig None   Filepath to save generated figure (e.g. plot.png).
  -dpi 300.0            Resolution in dots per inch used when saving figures.
  -fdn, --figdata-fname None
                        Filepath to save plotted data. Supported extensions:
                        .npz, .json, .txt, .dat.
  -series None          List of series dictionaries from TOML. Per-series
                        keys: xcolumn, ycolumn, source_filepath (optional),
                        mask_name (optional), label (optional),
                        filter_ycolumn/filter_value (optional),
                        xfactor/yfactor (optional),
                        color/marker/size/edgecolor/facecolor/linewidth/alpha
                        (optional), or style={...} for grouped styling. Also
                        supports ymode in {marker,cloud,violin,boxplot,auto}
                        for array-valued y columns. Set binned=true to group
                        scalar y values by unique x bin (with optional xtol
                        snap). Set weight_by_multiplicity=true to weight y
                        values by DerivativeStructures multiplicity.
  -xf, --xfactor 1.0    Multiplicative factor applied to x data before
                        plotting/export.
  -rc-params None       Matplotlib rcParams as a JSON dictionary, scoped to
                        this plot.
  -legend-ncols 1       Positive number of legend columns (default 1).
  -legend-bbox-to-anchor None
                        JSON list of 2 or 4 legend anchor coordinates in axes
                        fractions.
  -annotations None     JSON list of text/x/y dictionaries; coordinates: 'axes
                        fraction' or 'data'.
  -savefig-bbox-inches None
                        Use 'tight' to include outside legends and labels when
                        saving.

Arguments and behavior

clusterx.cli.plot_columns.plot_columns(source_filepath=None, xcolumn=None, ycolumn=None, title=None, xlabel=None, ylabel=None, yfactor=1.0, yrange=None, xrange=None, colors=None, width=None, height=None, target_vs_predictions=False, loglog=False, symlog=False, symlog_linthresh=None, grid=False, grid_which='major', grid_axis='both', grid_style=None, show_yzero_axis=False, show_xlabel=True, show_ylabel=True, show_xticklabels=True, show_yticklabels=True, xaxis_top=False, yaxis_right=False, xticks=None, yticks=None, legend=True, show_legend_frame=True, legend_location='best', legend_handlelength=None, legend_handletextpad=None, show_plot=True, savefig=None, dpi=300.0, figdata_fname=None, series=None, xfactor=1.0, rc_params=None, legend_ncols=1, legend_bbox_to_anchor=None, annotations=None, savefig_bbox_inches=None)

Plot one or more columns from serialized DerivativeStructures or StructuresSet objects.

This command can be driven from TOML using [plot_columns] and optional [[plot_columns.series]] blocks. If series is omitted or empty, one series is plotted using the top-level source_filepath, xcolumn, and ycolumn. Options available only per series use their built-in defaults.

Parameters:
source_filepathstr, optional

default serialized DerivativeStructures or StructuresSet file used by all series that do not explicitly set source_filepath.

xcolumn, ycolumnstr, optional

default x/y columns used by series that do not explicitly set them.

titlestr, optional

figure title.

xlabel, ylabelstr, optional

axis labels.

xfactor, yfactorfloat

multiply each coordinate once before grouping, plotting, parity limits and export (both default to 1.0). Source properties are unchanged. Each series can override either factor.

xrange, yrangelist[float, float], optional

axis limits in displayed units, after coordinate scaling. Ticks, xtol, distribution widths and x jitter also use displayed units and are not scaled again.

rc_paramsdict, optional

Matplotlib rcParams applied inside an rc_context spanning figure creation, formatting and saving. Settings are restored even on errors. Set the backend before calling this command; backend is not a supported presentation setting here.

colorslist[str], optional

default color palette for series without explicit color.

width, heightfloat, optional

figure size in inches. Defaults preserve existing behavior: 6x4 for regular plots and 6x6 for target_vs_predictions.

For target_vs_predictions, the figure is kept square. If width is provided, the size becomes (width, width) (height is ignored).

target_vs_predictionsbool

enable parity-plot mode for target values on x versus predictions on y. This uses a square plot frame, shared x/y limits, and a y=x reference line.

loglogbool

use logarithmic scale on both axes. All finite plotted x/y values must be positive.

symlogbool

use symmetric logarithmic scale on both axes. This is the signed-log option for data containing negative or zero values.

symlog_linthreshfloat, optional

half-width of the linear region around zero for symlog. If omitted, it is inferred from the smallest nonzero plotted absolute value.

gridbool

draw plot grid lines.

grid_whichstr

"major" (default), "minor", or "both".

grid_axisstr

"both" (default), "x", or "y".

grid_styledict, optional

matplotlib grid style passed to Axes.grid (e.g. linewidth, linestyle, alpha, color).

show_yzero_axisbool

draw a horizontal line at y=0.

show_xlabel, show_ylabelbool

show/hide axis name labels.

show_xticklabels, show_yticklabelsbool

show/hide numeric tick labels on each axis.

xaxis_topbool

if True, place x-axis label, tick marks, and tick labels on the top side.

yaxis_rightbool

if True, place y-axis label, tick marks, and tick labels on the right side.

xticks, ytickslist[float], optional

explicit tick locations to apply to the x/y axes via Axes.set_xticks and Axes.set_yticks.

legendbool

show legend.

show_legend_framebool

show/hide the legend frame box.

legend_locationstr

legend position using Matplotlib loc names (e.g. "best", "upper left", "lower center").

legend_ncolsint

positive number of legend columns (default 1).

legend_bbox_to_anchorlist, optional

2 or 4 finite numbers in axes fractions, passed as Matplotlib’s bbox_to_anchor. For two entries, anchor at (x, y); four entries specify (x, y, width, height). For a horizontal legend above the plot, use legend_ncols=2, legend_location="lower center" and anchor [0.5, 1.04].

legend_handlelengthfloat, optional

handle length passed to Matplotlib legend(handlelength=...).

legend_handletextpadfloat, optional

spacing between legend handles and labels passed to legend(handletextpad=...).

show_plotbool

show interactive window.

savefigstr, optional

output figure path (e.g. plot.png).

savefig_bbox_inchesstr, optional

"tight" includes outside legends and labels when saving PNG, PDF or SVG. Omitted by default to preserve existing figure dimensions. Legends participate in layout.

annotationslist[dict], optional

text labels with required keys text (str), x and y (finite numbers). coordinates defaults to "axes fraction": (0, 0) is the lower-left axes corner, (1, 1) the upper-right, independent of data limits. "data" uses displayed data coordinates. Optional keys are ha, va, fontsize, fontweight. Other keys are rejected. Annotation coordinates are not scaled again.

dpifloat

resolution used for savefig (default: 300).

figdata_fnamestr, optional

data export path (.json/.npz/.txt/.dat).

Notes

Per-series options ([[plot_columns.series]])

Required (directly or via top-level defaults):

  • xcolumn (str): x-axis column from the loaded configurations table.

  • ycolumn (str): y-axis column from the loaded configurations table.

Optional:

  • source_filepath (str): override top-level source for this series.

  • mask_name (str): mask name in the DerivativeStructures.

  • filter_ycolumn (str): optional column name used to filter rows before

    plotting.

  • filter_value: only rows where filter_ycolumn == filter_value are

    kept.

  • label (str): legend label.

  • xfactor / yfactor (float): override the corresponding top-level

    scaling factor for this series.

  • color (str): matplotlib color spec (e.g. "k", "#1f77b4",

    "red").

  • marker (str): matplotlib marker (e.g. "o", "s", "^", ".").

  • size (float): marker area passed as s to

    matplotlib.pyplot.scatter.

  • edgecolor (str): marker edge color.

  • facecolor (str): marker face color (e.g. "none" for hollow markers).

  • linewidth (float): marker edge line width.

  • alpha (float): marker transparency.

  • style (dict): compact style dict with keys color, marker,

    size/s, edgecolor/edgecolors, facecolor/facecolors, linewidth/linewidths, alpha.

  • ymode (str): "marker", "cloud", "violin",

    "boxplot", or "auto".

  • aggregation (str): for ymode="marker" with array-valued y,

    use "mean" (default) or "median".

  • xjitter (float): optional x-jitter amplitude for ymode="cloud".

  • width (float): width for violin/boxplot.

  • binned (bool): if True, group the scalar y values by unique x

    before plotting; ymode and aggregation then act on the per-bin y distribution (e.g. ymode="marker", aggregation="mean" plots one mean per bin; ymode="violin" plots the full per-bin distribution). Ignored when y is already array-valued.

  • weight_by_multiplicity (bool): if True, weight each structure by

    its derivative-structure multiplicity. Weighted means and medians are used for aggregation, and integer-weighted samples are used for cloud/violin/box distributions.

  • xtol (float): snap x values to a grid of this spacing before

    grouping (useful when concentrations differ only by floating-point noise, e.g. xtol=1e-6).

  • mean_line (bool): if True, overlay a line joining per-x means

    (x sorted in increasing order). Useful with binned=true or array-valued y columns.

  • mean_line_style (dict): optional matplotlib plot style for the

    mean line (e.g. linewidth, linestyle, alpha, color).

  • mean_line_label (str): optional legend label for the mean line.

If both style and direct keys are provided, direct keys win.

JSON exports record presentation settings and the transformed series x, y and y_samples values, with their effective x/y factors. NPZ exports include xfactor_i, yfactor_i and a JSON plot_metadata string. Text exports retain their three numeric columns and add factors in the comment header.

Color precedence

  1. Per-series color

  2. Top-level colors[i]

  3. Internal default palette (tab10-like)

Examples

Presentation example with named TOML steps

Run with cell --input_file plots.toml. Both energy columns in this example are stored in eV/atom and displayed in meV/atom:

do = ["parity"]

[parity]
command = "plot_columns"
source_filepath = "training_predictions.xyz"
xcolumn = "f_mix"
ycolumn = "f_mix_pred"
xfactor = 1000.0
yfactor = 1000.0
target_vs_predictions = true
xlabel = '$F_v$, TI [meV / atom]'
ylabel = '$F_v$, CE [meV / atom]'
show_plot = false
savefig = "parity.png"
savefig_bbox_inches = "tight"
figdata_fname = "parity.json"

[parity.rc_params]
"font.size" = 20.0
"axes.labelsize" = 24.0
"axes.spines.top" = false

[[parity.annotations]]
text = "300 K"
x = 0.06
y = 0.94
ha = "left"
va = "top"
fontweight = "bold"

Direct CLI structured options use JSON, for example -rc-params '{"axes.labelsize":24}', -legend-bbox-to-anchor '[0.5,1.04]', and -annotations '[{"text":"300 K","x":0.06,"y":0.94}]'.

[plot_columns]
source_filepath = "file1.pickle"
title = "Energy of mixing"
xlabel = "Concentration"
ylabel = "Energy"
yfactor = 1000.0
colors = ["k", "r", "b"]
width = 7.0
height = 4.5
legend = true
show_plot = true
savefig = "plot.png"
dpi = 300
# target_vs_predictions = true  # Square parity plot with y=x
# width = 7.5                   # In target_vs_predictions: uses (width, width)
# loglog = true                 # Logarithmic x/y axes
# symlog = true                 # Signed-log x/y axes
# grid = true
# grid_which = "both"
# grid_axis = "both"
# show_xlabel = false
# show_xticklabels = false
# show_legend_frame = false
# legend_location = "upper right"

[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing"
marker = "o"
label = "file1"

[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing"
color = "#2ca02c"
marker = "^"
mask_name = "lowest"
label = "file1 lowest"

[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing"
label = "styled"
[plot_columns.series.style]
marker = "o"
edgecolor = "red"
facecolor = "none"
size = 20
linewidth = 0.85

# Bagging/ensemble predictions stored as arrays per row
[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing_ensemble_predictions"
ymode = "cloud"
xjitter = 0.003
color = "tab:blue"
size = 8
alpha = 0.25
label = "bagging cloud"

[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing_ensemble_predictions"
ymode = "violin"
width = 0.02
color = "tab:red"
facecolor = "none"
linewidth = 0.8
label = "bagging violin"

[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing_ensemble_predictions"
ymode = "boxplot"
width = 0.02
showfliers = false
color = "black"
label = "bagging box"

# Group scalar y-values by concentration bins (after optional snapping)
[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing"
binned = true
xtol = 1e-6
ymode = "marker"
aggregation = "mean"
marker = "o"
color = "tab:purple"
label = "binned mean"

# Overlay a sorted mean line on top of per-bin distributions
[[plot_columns.series]]
xcolumn = "frconc_binary"
ycolumn = "energy_of_mixing"
binned = true
xtol = 1e-6
ymode = "violin"
mean_line = true
mean_line_label = "binned mean trend"
[plot_columns.series.mean_line_style]
linewidth = 1.4
linestyle = "-"
alpha = 0.95

# Target-vs-predictions parity plot
[[plot_columns.series]]
xcolumn = "target_energy"
ycolumn = "predicted_energy"
marker = "o"
label = "fit"