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. Ifseriesis omitted or empty, one series is plotted using the top-levelsource_filepath,xcolumn, andycolumn. 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_contextspanning figure creation, formatting and saving. Settings are restored even on errors. Set the backend before calling this command;backendis 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:
6x4for regular plots and6x6fortarget_vs_predictions.For
target_vs_predictions, the figure is kept square. Ifwidthis provided, the size becomes(width, width)(heightis 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=xreference 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_xticksandAxes.set_yticks.- legendbool
show legend.
- show_legend_framebool
show/hide the legend frame box.
- legend_locationstr
legend position using Matplotlib
locnames (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, uselegend_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),xandy(finite numbers).coordinatesdefaults 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 areha,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 beforeplotting.
filter_value: only rows wherefilter_ycolumn == filter_valuearekept.
label(str): legend label.xfactor/yfactor(float): override the corresponding top-levelscaling 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 asstomatplotlib.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 keyscolor,marker,size/s,edgecolor/edgecolors,facecolor/facecolors,linewidth/linewidths,alpha.
ymode(str):"marker","cloud","violin","boxplot", or"auto".
aggregation(str): forymode="marker"with array-valued y,use
"mean"(default) or"median".
xjitter(float): optional x-jitter amplitude forymode="cloud".width(float): width forviolin/boxplot.binned(bool): ifTrue, group the scalar y values by unique xbefore plotting;
ymodeandaggregationthen 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): ifTrue, weight each structure byits 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 beforegrouping (useful when concentrations differ only by floating-point noise, e.g.
xtol=1e-6).
mean_line(bool): ifTrue, overlay a line joining per-x means(x sorted in increasing order). Useful with
binned=trueor array-valued y columns.
mean_line_style(dict): optional matplotlibplotstyle for themean line (e.g.
linewidth,linestyle,alpha,color).
mean_line_label(str): optional legend label for the mean line.
If both
styleand direct keys are provided, direct keys win.JSON exports record presentation settings and the transformed series
x,yandy_samplesvalues, with their effective x/y factors. NPZ exports includexfactor_i,yfactor_iand a JSONplot_metadatastring. Text exports retain their three numeric columns and add factors in the comment header.Color precedence
Per-series
colorTop-level
colors[i]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"