Plotting#
SpectroChemPy provides a high-level plotting interface built on top of Matplotlib, tailored for scientific spectroscopy workflows.
See also
Executable plotting examples
and the plot_multiple API for comparing datasets.
Most scientific plots in SpectroChemPy require only one line of code.
The goal is simple:
Produce clear, publication-quality scientific plots with minimal code, while remaining fully compatible with Matplotlib.
This approach is built on three core principles.
Sensible Defaults#
A good plot should not require configuration.
Calling:
dataset.plot()
immediately produces properly labeled axes (with units), a readable layout, consistent scientific styling, and appropriate color mapping for 2D data.
Plot configuration is automatically derived from dataset metadata (titles, coordinates, units), so in most cases no additional code is required.
Progressive Customization#
When adjustments are needed, they remain simple.
Modify a single plot with keyword arguments.
Change visual style without rewriting plotting code.
Adjust global defaults via
scp.preferences.
Users can start with defaults and progressively gain control, without modifying Matplotlib’s global configuration.
Full Matplotlib Compatibility#
SpectroChemPy does not replace Matplotlib — it builds on it.
Each plotting function returns a Matplotlib Axes object,
so advanced users retain full control over figure customization
and integration into complex layouts.
Current Plotting Contract#
For day-to-day use, the plotting contract is:
dataset.plot(method=...)selects the plotting geometry.Explicit helpers such as
plot_pen(),plot_scatter(),plot_bar(),plot_lines(),plot_contour(),plot_contourf(), andplot_image()make that intent explicit.Common keyword aliases such as
lw,ls,ms,mew,c, andcolormapare normalized internally to their canonical Matplotlib names.Style interpretation depends on the plotting geometry: the same
cmapormarkerinput can mean different things for lines, scatter plots, contour plots, and image-like plots.ax,clear, andshowcontrol figure lifecycle for both ordinary dataset plots and composite plots (plot_score,plot_scree,plot_compare,plot_merit,plot_baseline,plot_parity). Hereshowmeans “perform SpectroChemPy’s explicit display step after plotting”, not “guarantee figure visibility”. In notebook environments, figures can still render inline without that explicit call.outputis the destination file of the finished figure, and is accepted bydataset.plot(), the explicit geometry helpers listed above,plot_multiple(),multiplot(), and the composite plots. It accepts astror apathlib.Path, writes the whole figure once the plot is complete (legend, colorbars, and multi-panel layouts included), and does so before the display step. The format follows the extension, and thesavefig.*preferences control resolution, background, and bounding box. Missing parent directories are reported as anOSErrorinstead of being created silently. The internalplot_1D(),plot_2D(), andplot_3D()renderers remain draw-only implementation functions.plot_multiple()overlays several datasets on one axes, whilemultiplot()creates a grid of axes.
Designed for Scientific Workflows#
SpectroChemPy plotting is aware of:
Physical units
Dataset dimensionality
Spectroscopic conventions
Analysis and decomposition outputs
This reduces boilerplate code and keeps the focus on scientific interpretation.
In short, SpectroChemPy plotting should feel like Matplotlib — but smarter, cleaner, and more efficient for spectroscopy.
Structure of This Section#
The following pages introduce plotting progressively:
2D Maps with Marginal Panels#
Contour maps can carry calculated projections or external reference spectra.
For a dataset with dimensions ("y", "x"), retain x above the map:
ax = dataset.plot_contour(
projections=("x",), projection_reducer="mean", equal_aspect=True
)
projections=True selects both dimensions. Named dimensions keep their
meaning after transposition: the retained dimension determines whether its
panel is above or to the right of the map. The legacy show_projections
and show_projection_x/y preferences are honored when projections is
omitted; an explicit False disables panels for that call. These preferences
apply to contour maps and do not add panels to line or surface plots.
The reducers sum, mean and max operate over the other dimension and
exclude masked and non-finite samples. They are pointwise reductions, not
coordinate-weighted integrals. Supply reference spectra instead when those
curves have a different scientific meaning, as in the 2D-COS example:
ax = correlation_map.plot_contour(
projections=("x",),
projection_data={"x": [first_spectrum, last_spectrum]},
projection_kwargs={"x": {
"labels": ["Start", "End"], "legend": True,
"color": ["black", "orange"],
}},
positive_color="red", negative_color="blue",
positive_linestyle="-", negative_linestyle="--",
projection_size=0.25,
)
A reference may be one 1D dataset, a list of datasets, or a 2D series with one curve per row. Reference coordinates can have a different sampling grid; compatible units are converted without interpolation or input mutation. Non-overlapping coordinate ranges and incompatible units are rejected. The reference signal units are independent of the map signal units, which is necessary when showing absorbance spectra above squared-absorbance maps.
multiplot composes these complete panels. Common plot options apply to
every panel; panel_kwargs supplies one dictionary per dataset to override
levels, references or styles. height_ratios and width_ratios control
grid proportions, including grids mixing 1D spectra and 2D maps. Avoid sharing
axes that represent different physical quantities.
return_dict=True on a contour plot returns fig and an axes mapping
with roles main, top and/or right. In multiplot, axes and
axes_dict still identify the main grid axes; the additional panel_axes
mapping exposes each panel’s roles. output= saves the entire figure after
all reference curves, legends and colorbars have been drawn.