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(), and plot_image() make that intent explicit.

  • Common keyword aliases such as lw, ls, ms, mew, c, and colormap are normalized internally to their canonical Matplotlib names.

  • Style interpretation depends on the plotting geometry: the same cmap or marker input can mean different things for lines, scatter plots, contour plots, and image-like plots.

  • ax, clear, and show control figure lifecycle for both ordinary dataset plots and composite plots (plot_score, plot_scree, plot_compare, plot_merit, plot_baseline, plot_parity). Here show means “perform SpectroChemPy’s explicit display step after plotting”, not “guarantee figure visibility”. In notebook environments, figures can still render inline without that explicit call.

  • output is the destination file of the finished figure, and is accepted by dataset.plot(), the explicit geometry helpers listed above, plot_multiple(), multiplot(), and the composite plots. It accepts a str or a pathlib.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 the savefig.* preferences control resolution, background, and bounding box. Missing parent directories are reported as an OSError instead of being created silently. The internal plot_1D(), plot_2D(), and plot_3D() renderers remain draw-only implementation functions.

  • plot_multiple() overlays several datasets on one axes, while multiplot() 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.