Plotting

The plotting module provides publication-ready visualization tools for ToF-SIMS spectra and peak analysis results.

Quick Example

from mioXpektron import PlotPeak

PlotPeak(corrected_data, peaks_df)

Single Spectrum Plotting

PlotPeak creates annotated spectrum plots with detected peaks:

from mioXpektron import PlotPeak

plot = PlotPeak(
    data,
    peaks,
    mz_min=1.0,
    mz_max=100.0,
    title="Sample Spectrum",
)

Features:

Automatic peak labeling with m/z values
Configurable m/z range
Peak prominence-based annotation filtering

Multi-Peak Visualization

PlotPeaks overlays spectra from multiple files for comparison:

from mioXpektron import PlotPeaks, PlotPeaksConfig

config = PlotPeaksConfig(
    mz_min=20.0,
    mz_max=30.0,
    color_map={"cancer": "red", "control": "blue"},
)

PlotPeaks(file_list, config=config)

Group-based coloring is automatically inferred from filenames.

Overlapping Peak Plots

Visualize and analyze overlapping peaks:

from mioXpektron import plot_overlapping_peaks

plot_overlapping_peaks(peaks, data, resolution_threshold=0.5)

API Reference

class mioXpektron.plotting.PlotPeak(mz_values, raw_intensities, sample_name, group=None, corrected_intensities=None)[source]

Bases: object

Helper for plotting raw and processed spectra.

Parameters:

mz_values (array-like of shape (n,)) – m/z axis aligned with the supplied intensities.
raw_intensities (array-like of shape (n,)) – Primary intensity trace used for plotting.
sample_name (str) – Label shown on the plot title.
group (str | None, optional) – Additional grouping label appended to the title.
corrected_intensities (array-like of shape (n,), optional) – Denoised/baseline-corrected intensities. When provided, displayed as the comparison trace and used as the default signal for peak detection.

mz_values: Iterable[float]

raw_intensities: Iterable[float]

sample_name: str

group: str | None = None

corrected_intensities: Iterable[float] | None = None

plot(*, mz_min=None, mz_max=None, show_peaks=True, peak_height=None, peak_prominence=None, min_peak_width=1, max_peak_width=None, corrected_intensities=None, figsize=(10, 6), save_plot=True)[source]

Plot raw and optional corrected spectra for the configured sample.

Parameters:

mz_min (float | None)
mz_max (float | None)
show_peaks (bool)
peak_height (float | None)
peak_prominence (float | None)
min_peak_width (float)
max_peak_width (float | None)
corrected_intensities (Iterable[float] | None)
figsize (Tuple[int, int])
save_plot (bool | None)

zoom(report, *, xlim, intensity=None, window_ppm=50.0, figsize=(6, 4), save_plot=True)[source]

Plot a zoomed segment with calibration-peak diagnostics.

Parameters:

report (DataFrame)
xlim (Tuple[float, float])
intensity (Iterable[float] | None)
window_ppm (float)
figsize (Tuple[int, int])
save_plot (bool | None)

class mioXpektron.plotting.PlotPeaks(config=None)[source]

Bases: object

Class for plotting overlapping peaks from multiple spectra files.

Features: - Load and group spectra by inferred labels (Cancer/Control/Unknown) - Overlay individual spectra with customizable transparency - Plot per-group median curves - Plot cumulative intensity by group - Flexible configuration through PlotPeaksConfig

Example:

>>> config = PlotPeaksConfig(
...     data_dir="data/spectra",
...     mz_min=100.0,
...     mz_max=200.0,
...     norm_tic=True,
...     save_fig=True,
...     save_path="../output_files/plots"
... )
>>> plotter = PlotPeaks(config)
>>> plotter.load_data()
>>> plotter.plot_overlay()
>>> plotter.plot_cumulative()

__init__(config=None)[source]

Initialize PlotPeaks.

Parameters:: config (PlotPeaksConfig, optional) – Configuration object. If None, must set attributes manually.

files: List[str]

grouped_curves: Dict[str, List[Tuple[ndarray, ndarray]]]

set_group_inference(func)[source]

Set custom group inference function.

Parameters:: func (callable) – Function that takes a file path and returns group label.

static load_window(file_path, mz_min, mz_max, norm_tic=False)[source]

Read one spectrum and return (m/z, intensity) in the requested window.

Parameters:

file_path (str) – Path to a tab or comma-separated spectrum with columns for m/z and intensity. Column names are case-insensitive and support variations: - m/z: “mz”, “m/z”, “M/Z”, “MZ”, “Mz” - intensity: “intensity”, “Intensity”, “INTENSITY”, “int”, “Int”
mz_min (float) – Inclusive m/z window to extract.
mz_max (float) – Inclusive m/z window to extract.
norm_tic (bool, default False) – If True, normalize intensities by total ion count (sum to 1).

Returns:

mz (np.ndarray)
inten (np.ndarray) – Intensities scaled by 1e6 (to keep values readable on plots).

Return type:

Tuple[ndarray, ndarray]

load_data()[source]

Load all files matching the pattern and group them by inferred labels.

Raises:: RuntimeError – If no files match the pattern.
Return type:: None

get_group_counts()[source]

Get counts of spectra per group.

Returns:: Dictionary with group names as keys and counts as values.
Return type:: dict

plot_overlay(ax=None, show=True)[source]

Plot overlapping spectra with optional median curves.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates new figure.
show (bool, default True) – If True, call plt.show() at the end.

Returns:

The figure object.

Return type:

matplotlib.figure.Figure

plot_cumulative(ax=None, show=True)[source]

Plot cumulative intensity curves by group.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates new figure.
show (bool, default True) – If True, call plt.show() at the end.

Returns:

The figure object.

Return type:

matplotlib.figure.Figure

plot_all()[source]

Convenience method to plot both overlay and cumulative plots.

Returns:

fig_overlay (matplotlib.figure.Figure) – The overlay plot figure.
fig_cumulative (matplotlib.figure.Figure) – The cumulative plot figure (or None if disabled).

Return type:

Tuple[Figure, Figure]

Parameters:: config (PlotPeaksConfig | None)

class mioXpektron.plotting.PlotPeaksConfig(data_dir, file_pattern='*.txt', mz_min=0.0, mz_max=1000.0, norm_tic=False, bin_width=0.001, alpha=0.18, show_median=True, show_group_cumulative=True, figsize=(10, 6), cumulative_figsize=(10, 4), color_map=None, save_fig=False, save_path='output_files/plots')[source]

Bases: object

Configuration for PlotPeaks class.

Parameters:

data_dir (str) – Directory containing spectra files.
file_pattern (str, default “*.txt”) – Glob pattern for matching spectrum files.
mz_min (float, default 0.0) – Minimum m/z value for the plotting window.
mz_max (float, default 1000.0) – Maximum m/z value for the plotting window.
norm_tic (bool, default False) – If True, normalize intensities by total ion count.
bin_width (float, default 0.001) – Bin width for interpolation grid.
alpha (float, default 0.18) – Transparency for individual spectra lines.
show_median (bool, default True) – If True, overlay median curves on the plot.
show_group_cumulative (bool, default True) – If True, create cumulative intensity plot.
figsize (tuple, default (10, 6)) – Figure size for overlay plot.
cumulative_figsize (tuple, default (10, 4)) – Figure size for cumulative plot.
color_map (dict, optional) – Dictionary mapping group names to colors.
save_fig (bool, default False) – If True, save figures as PDF files.
save_path (str, default "../output_files/plots") – Directory path where PDF files will be saved.

data_dir: str

file_pattern: str = '*.txt'

mz_min: float = 0.0

mz_max: float = 1000.0

norm_tic: bool = False

bin_width: float = 0.001

alpha: float = 0.18

show_median: bool = True

show_group_cumulative: bool = True

figsize: Tuple[int, int] = (10, 6)

cumulative_figsize: Tuple[int, int] = (10, 4)

color_map: Dict[str, str] | None = None

save_fig: bool = False

save_path: str = 'output_files/plots'