API Reference

This page provides auto-generated API documentation for the public interface of mioXpektron.

mioXpektron

Public package interface for the Xpektron toolkit.

Top-Level Exports

Public package interface for the Xpektron toolkit.

class mioXpektron.AggregateParams(bin_width: 'float' = 0.1, coverage_threshold: 'float' = 0.5, top_k: 'int' = 6)

Bases: object

Parameters:

• bin_width (float)

• coverage_threshold (float)

• top_k (int)

bin_width: float = 0.1

coverage_threshold: float = 0.5

top_k: int = 6

class mioXpektron.BaselineBatchCorrector(in_dir: 'Union[str, Path]', pattern: 'str' = '*.csv', recursive: 'bool' = False, method: 'str' = 'airpls', method_kwargs: 'Dict' = <factory>, clip_negative: 'bool' = True, per_file_best: 'bool' = False, best_method_map: 'Optional[Dict[str, str]]'=None, n_jobs: 'int' = -1, save_plots: 'bool' = False)

Bases: object

Parameters:

• in_dir (str | Path)

• pattern (str)

• recursive (bool)

• method (str)

• method_kwargs (Dict)

• clip_negative (bool)

• per_file_best (bool)

• best_method_map (Dict[str, str] | None)

• n_jobs (int)

• save_plots (bool)

in_dir: str | Path

pattern: str = '*.csv'

recursive: bool = False

method: str = 'airpls'

method_kwargs: Dict

clip_negative: bool = True

per_file_best: bool = False

best_method_map: Dict[str, str] | None = None

n_jobs: int = -1

save_plots: bool = False

run(out_root=None)

Parameters:

out_root (str | Path | None)

Return type:

Path

class mioXpektron.BaselineMethodEvaluator(files=<factory>, methods=None, param_grid=None, use_small_param_preset=False, auto_scale_window_size=True, eval_clip_negative=False, topk_for_snr=5, raw_noise_quantile=0.2, flat_windows=None, metrics_for_composite=('rfzn', 'nar', 'snr', 'bbi', 'br', 'nbc'), n_jobs=-1)

Bases: object

Evaluate baseline algorithms on ToF‑SIMS files supplied as paths or globs.

Parameters:

• files (List[str | Path])

• methods (List[str] | None)

• param_grid (Dict[str, List[Dict]] | None)

• use_small_param_preset (bool)

• auto_scale_window_size (bool)

• eval_clip_negative (bool)

• topk_for_snr (int)

• raw_noise_quantile (float)

• flat_windows (List[Tuple[float, float]] | None)

• metrics_for_composite (Tuple[str, ...])

• n_jobs (int)

files: List[str | Path]

methods: List[str] | None = None

param_grid: Dict[str, List[Dict]] | None = None

use_small_param_preset: bool = False

auto_scale_window_size: bool = True

eval_clip_negative: bool = False

topk_for_snr: int = 5

raw_noise_quantile: float = 0.2

flat_windows: List[Tuple[float, float]] | None = None

metrics_for_composite: Tuple[str, ...] = ('rfzn', 'nar', 'snr', 'bbi', 'br', 'nbc')

n_jobs: int = -1

labels: List[str]

specs: List[Tuple[str, Dict]]

evaluate(noise_quantile=None, n_jobs=None)

Parameters:

• noise_quantile (float | None)

• n_jobs (int | None)

warning_log()

Return type:

DataFrame

plot(out_dir='baseline_selection_output')

Parameters:

out_dir (str | Path)

Return type:

List[Path]

preview_overlay(file, methods=None, max_methods=5, save_to='baseline_selection_output', show_errors=True)

Plot raw, baseline and corrected overlays for a few methods on a single file.

Parameters:

• file (str or Path) – Path to a single spectrum file (not a list!)

• methods (list of str, optional) – Method names to plot. If None, uses top methods from evaluation.

• max_methods (int) – Maximum number of methods to plot (default: 5)

• save_to (str or Path, optional) – Directory to save plots. Set to None to skip saving.

• show_errors (bool) – If True (default), print errors when methods fail instead of silently ignoring them.

class mioXpektron.BatchDenoising(file_paths, *, method='wavelet', n_workers=None, backend='threads', progress=True, params=None)

Bases: object

Run denoising across a batch of spectra with stable outputs.

__init__(file_paths, *, method='wavelet', n_workers=None, backend='threads', progress=True, params=None)

Store batch processing parameters for later execution.

run(output_root=None, folder_name='denoised_spectrums', save_result=True)

Execute the batch denoising run.

Parameters:

• output_root (str | Path | None) – Directory where the result folder will be created. If omitted, defaults to OUTPUT_DIR.

• folder_name (str, default "denoised_spectrums") – Name for the result folder.

• save_result (bool, default True) – Persist the executor results dataframe to OUTPUT_DIR.

Returns:

Records describing each processed file.

Return type:

list[BatchResult]

class mioXpektron.DenoisingMethods(mz_values, raw_intensities)

Bases: object

Evaluate and visualize denoising strategies for mass spectrometry data.

Parameters:

• mz (np.ndarray | pl.Series) – The m/z axis of the spectrum.

• intensity (np.ndarray | pl.Series) – Raw intensity values aligned with mz.

__init__(mz_values, raw_intensities)

Store the raw spectrum that downstream helpers will operate on.

classmethod compare_across_files(file_paths, *, windows=None, min_mz=None, max_mz=None, per_window_max_peaks=50, min_prominence=None, search_ppm=20.0, match_min_prominence_ratio=0.1, match_min_prominence_abs=0.0, match_min_width_pts=0.25, resample_to_uniform=True, include_derivatives=False, return_format='pandas', w_match=3.0, w_mz=2.0, w_area=2.0, w_height=1.5, w_fwhm=1.0, w_spread=1.0, w_noise_db=2.0, w_delta_snr_db=1.5, selection_criteria=None, file_n_jobs=0, file_parallel_backend='thread', method_n_jobs=None, method_parallel_backend='thread', progress=True, save_summary=True)

Rank denoising methods across a cohort of spectra files.

Each file contributes one per-method summary, and the final cohort ranking aggregates those summaries with equal file weighting. This is a stronger basis for selecting a default denoiser than evaluating a single arbitrary spectrum.

Parallelism

This method supports two levels of parallelism: - file-level via file_n_jobs / file_parallel_backend - method-level inside each file via method_n_jobs / method_parallel_backend

When file_n_jobs=0 (default), worker counts are chosen automatically to avoid nested oversubscription.

returns:

(ranked_summary, sample_summary_all, detail_all) where sample_summary_all contains one aggregated row per file/method pair and detail_all contains all per-peak rows.

rtype:

tuple

compare(min_mz, max_mz, return_format='pandas', match_min_prominence_ratio=0.1, match_min_prominence_abs=0.0, match_min_width_pts=0.25, include_derivatives=False, w_match=3.0, w_mz=2.0, w_area=2.0, w_height=1.5, w_fwhm=1.0, w_spread=1.0, w_noise_db=2.0, w_delta_snr_db=1.5, selection_criteria=None, save_summary=True)

Compare denoising methods across the full spectrum window.

Parameters:

• min_mz (float) – Bounds for the evaluation window.

• max_mz (float) – Bounds for the evaluation window.

• return_format ({"pandas", "polars"}, default "pandas") – Determines the summary dataframe type returned by the lower-level evaluators.

• w_match (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_mz (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_area (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_height (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_fwhm (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_spread (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_noise_db (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• w_delta_snr_db (float) – Weights applied by rank_method() when building the secondary dimensionless tie-break score.

• selection_criteria (dict | None, optional) – Override the default peak-preservation and denoising thresholds used to define scientifically acceptable methods.

• save_summary (bool, default True) – When True and the summary is a pandas object, persist an Excel copy in OUTPUT_DIR for later inspection.

Returns:

Ranked table whose concrete type depends on return_format.

Return type:

DataFrame or LazyFrame

compare_in_windows(windows, per_window_max_peaks=50, min_prominence=None, search_ppm=20.0, match_min_prominence_ratio=0.1, match_min_prominence_abs=0.0, match_min_width_pts=0.25, resample_to_uniform=True, include_derivatives=False, return_format='pandas', w_match=3.0, w_mz=2.0, w_area=2.0, w_height=1.5, w_fwhm=1.0, w_spread=1.0, w_noise_db=2.0, w_delta_snr_db=1.5, selection_criteria=None, save_summary=True)

Compare denoising methods within pre-defined m/z windows.

Parameters mirror compare() with additional controls for window segmentation. The return value matches return_format and includes a ranking aggregated across all windows.

Returns:

Ranked summary consistent with return_format.

Return type:

DataFrame or LazyFrame

plot(summary, annotate=True, top_k=3, save_plot=True, save_pareto=True)

Visualize the Pareto front of SNR gain versus peak-height deviation.

Parameters:

• summary (DataFrame or LazyFrame) – Ranking output generated by compare() or compare_in_windows().

• annotate (bool, default True) – If True, label the top top_k points on the Pareto chart.

• top_k (int, default 3) – Number of top-ranked methods to annotate.

• save_plot (bool, default True) – Persist the Matplotlib figure via plot_pareto_delta_snr_vs_height().

• save_pareto (bool, default True) – Persist the underlying data used to draw the plot.

Returns:

The axis used for further customization.

Return type:

matplotlib.axes.Axes

denoise_check(denoise_params, *, sample_name='test', group=None, log_scale_y=False, mz_min=0, mz_max=500, show_peaks=False, peak_height=1000, peak_prominence=50, min_peak_width=1, max_peak_width=None, figsize=(10, 6), save_plot=True)

Preview a single denoising configuration by plotting selected peaks.

Parameters:

• denoise_params (Mapping[str, Any]) – Keyword arguments forwarded directly to noise_filtering().

• sample_name (str, default "test") – Label forwarded to PlotPeak for file naming.

• group (str | None, optional) – Group identifier used by PlotPeak when saving plots.

• log_scale_y (bool, default False) – Apply log1p before plotting, useful for high-dynamic-range spectra.

• mz_min (float) – m/z bounds for the preview overlay.

• mz_max (float) – m/z bounds for the preview overlay.

• show_peaks (bool, default False) – Highlight top peaks using PlotPeak detection settings.

• peak_height (float) – Tuning knobs passed to PlotPeak when show_peaks is True.

• peak_prominence (float) – Tuning knobs passed to PlotPeak when show_peaks is True.

• min_peak_width (float) – Tuning knobs passed to PlotPeak when show_peaks is True.

• max_peak_width (float) – Tuning knobs passed to PlotPeak when show_peaks is True.

• save_plot (bool, default True) – Persist the rendered preview when requested by PlotPeak.

Returns:

Axis returned by PlotPeak so callers can layer annotations.

Return type:

matplotlib.axes.Axes

method_parameters(summary, rank=0, basis='constrained_pareto_then_snr', require_pass=True, require_finite_metrics=True, save_selected=True)

Extract the configuration for a ranked denoising method.

Parameters:

• summary (DataFrame | pl.DataFrame) – Ranked output produced by the comparison helpers.

• rank (int, default 0) – Zero-based index of the desired method after Pareto filtering.

• basis (str, default "constrained_pareto_then_snr") – Strategy forwarded to select_methods() when Pareto filtering is available.

• require_pass (bool, default True) – If True, discard rows that failed the minimum denoising constraint.

• require_finite_metrics (bool, default True) – Drop methods with NaNs before ranking.

• save_selected (bool, default True) – Persist the filtered table to OUTPUT_DIR for reproducibility.

Returns:

Parameters suitable for passing into noise_filtering().

Return type:

dict

class mioXpektron.FlatParams(y_quantile: 'float' = 0.2, grad_quantile: 'float' = 0.4, curv_quantile: 'float' = 0.4, savgol_window: 'int' = 11, savgol_poly: 'int' = 2, min_width: 'float' = 0.2, min_points: 'int' = 20)

Bases: object

Parameters:

• y_quantile (float)

• grad_quantile (float)

• curv_quantile (float)

• savgol_window (int)

• savgol_poly (int)

• min_width (float)

• min_points (int)

y_quantile: float = 0.2

grad_quantile: float = 0.4

curv_quantile: float = 0.4

savgol_window: int = 11

savgol_poly: int = 2

min_width: float = 0.2

min_points: int = 20

class mioXpektron.ScanForFlatRegion(files: 'List[Union[str, Path]]'=<factory>, out_dir: 'Union[str, Path]'='flat_windows_out', n_jobs: 'int' = -1, flat_params: 'FlatParams' = <factory>, agg_params: 'AggregateParams' = <factory>, auto_tune: 'bool' = False)

Bases: object

Parameters:

• files (List[str | Path])

• out_dir (str | Path)

• n_jobs (int)

• flat_params (FlatParams)

• agg_params (AggregateParams)

• auto_tune (bool)

files: List[str | Path]

out_dir: str | Path = 'flat_windows_out'

n_jobs: int = -1

flat_params: FlatParams

agg_params: AggregateParams

auto_tune: bool = False

run()

mioXpektron.align_peaks(peaks_df, mz_tolerance=0.2, mz_rounding_precision=1, output='intensity')

Cluster peaks by m/z and return an aligned feature matrix.

Uses a greedy sorted-bin algorithm that guarantees every aligned bin spans at most mz_tolerance in m/z.

mioXpektron.baseline_correction(intensities, method='airpls', window_size=101, poly_order=4, clip_negative=True, return_baseline=False, **kwargs)

Baseline-correct a 1‑D spectrum with pybaselines or custom filters.

Parameters:

• intensities (array-like) – Raw y values.

• method (str) – Algorithm name; see baseline_method_names().

• window_size (int) – Kernel width for the two custom filters.

• poly_order (int) – Polynomial order for the ‘poly’ alias.

• clip_negative (bool) – If True, negative corrected values are set to 0.

• return_baseline (bool) – If True, also return the estimated baseline.

• **kwargs – Forwarded to the chosen algorithm (e.g. lam=1e6, p=0.01).

Return type:

corrected or (corrected, baseline)

mioXpektron.baseline_method_names()

Return a sorted list of available baseline algorithms.

Based on pybaselines.Baseline public callables, plus two custom filters (“median_filter”, “adaptive_window”) and a ‘poly’ alias. A few methods that are not 1‑D safe or impractically slow are removed.

Return type:

List[str]

mioXpektron.batch_denoise(files, output_dir, method='wavelet', n_workers=0, backend='threads', progress=True, params=None)

Apply the configured denoising method to multiple spectrum files.

Parameters:

• files (Iterable[str | Path]) – Collection of filesystem paths (glob results, manual list, etc.).

• output_dir (str | Path) – Directory where the denoised outputs will be written.

• method (str, default "wavelet") – Name of the smoothing routine forwarded to noise_filtering().

• n_workers (int, default 0) – Worker count for the executor. 0 or None selects a CPU-aware default.

• backend ({"threads", "processes"}, default "threads") – Execution strategy for the worker pool.

• progress (bool, default True) – If True, wrap the executor iterator in tqdm when available.

• params (dict | None) – Extra keyword arguments forwarded to noise_filtering().

Returns:

Status records describing each attempted file.

Return type:

list[BatchResult]

Raises:

ValueError – If no input paths exist or an unsupported backend name is provided.

class mioXpektron.FlexibleCalibrator(config=None)

Bases: object

Single-model calibrator with user-selected method.

Unlike AutoCalibrator, this calibrator fits exactly one model and provides more control over outlier rejection, quality thresholds, and per-model parameters.

Parameters:

config (FlexibleCalibConfig | None)

last_autodetect_methods: Dict[str, List[str]]

last_reference_masses_initial: List[float]

last_reference_masses_used: List[float]

last_reference_masses_screened_out: List[float]

last_reference_mass_screening: DataFrame

last_failed_or_excluded_files: DataFrame

calibrate(files, calib_channels_dict=None)

Calibrate all files using the selected calibration method.

Parameters:

• files (Sequence[str])

• calib_channels_dict (Dict[str, Sequence[float]] | None)

Return type:

DataFrame

class mioXpektron.FlexibleCalibConfig(reference_masses, calibration_method='quad_sqrt', output_folder='calibrated_spectra', output_mz_range=None, max_workers=None, autodetect_tol_da=None, autodetect_tol_ppm=None, autodetect_method='gaussian', autodetect_fallback_policy='max', autodetect_strategy='mz', prefer_recompute_from_channel=False, outlier_threshold=3.0, use_outlier_rejection=True, max_iterations=3, min_calibrants=3, max_ppm_threshold=100.0, fail_on_high_error=False, retry_high_error_with_pruning=False, retry_high_error_with_mz_fallback=False, retry_high_error_max_removals=5, exclude_reference_masses=<factory>, auto_screen_reference_masses=False, screen_max_mean_abs_ppm=50.0, screen_max_median_abs_ppm=None, screen_min_valid_fraction=0.8, screen_min_count=3, screen_exclude_below_mz=1.5, spline_smoothing=None, multisegment_breakpoints=<factory>, instrument_params=<factory>, save_diagnostic_plots=False, verbose=True, auto_tune=False)

Bases: object

Configuration for flexible calibration with a single user-selected method.

Parameters:

• reference_masses (List[float])

• calibration_method (Literal['quad_sqrt', 'linear_sqrt', 'poly2', 'reflectron', 'multisegment', 'spline', 'physical'])

• output_folder (str)

• output_mz_range (Tuple[float | None, float | None] | None)

• max_workers (int | None)

• autodetect_tol_da (float | Sequence[float] | None)

• autodetect_tol_ppm (float | None)

• autodetect_method (str)

• autodetect_fallback_policy (str)

• autodetect_strategy (str)

• prefer_recompute_from_channel (bool)

• outlier_threshold (float)

• use_outlier_rejection (bool)

• max_iterations (int)

• min_calibrants (int)

• max_ppm_threshold (float | None)

• fail_on_high_error (bool)

• retry_high_error_with_pruning (bool)

• retry_high_error_with_mz_fallback (bool)

• retry_high_error_max_removals (int)

• exclude_reference_masses (List[float])

• auto_screen_reference_masses (bool)

• screen_max_mean_abs_ppm (float)

• screen_max_median_abs_ppm (float | None)

• screen_min_valid_fraction (float)

• screen_min_count (int)

• screen_exclude_below_mz (float)

• spline_smoothing (float | None)

• multisegment_breakpoints (List[float])

• instrument_params (Dict[str, float])

• save_diagnostic_plots (bool)

• verbose (bool)

• auto_tune (bool)

reference_masses: List[float]

calibration_method: Literal['quad_sqrt', 'linear_sqrt', 'poly2', 'reflectron', 'multisegment', 'spline', 'physical'] = 'quad_sqrt'

output_folder: str = 'calibrated_spectra'

output_mz_range: Tuple[float | None, float | None] | None = None

max_workers: int | None = None

autodetect_tol_da: float | Sequence[float] | None = None

autodetect_tol_ppm: float | None = None

autodetect_method: str = 'gaussian'

autodetect_fallback_policy: str = 'max'

autodetect_strategy: str = 'mz'

prefer_recompute_from_channel: bool = False

outlier_threshold: float = 3.0

use_outlier_rejection: bool = True

max_iterations: int = 3

min_calibrants: int = 3

max_ppm_threshold: float | None = 100.0

fail_on_high_error: bool = False

retry_high_error_with_pruning: bool = False

retry_high_error_with_mz_fallback: bool = False

retry_high_error_max_removals: int = 5

exclude_reference_masses: List[float]

auto_screen_reference_masses: bool = False

screen_max_mean_abs_ppm: float = 50.0

screen_max_median_abs_ppm: float | None = None

screen_min_valid_fraction: float = 0.8

screen_min_count: int = 3

screen_exclude_below_mz: float = 1.5

spline_smoothing: float | None = None

multisegment_breakpoints: List[float]

instrument_params: Dict[str, float]

save_diagnostic_plots: bool = False

verbose: bool = True

auto_tune: bool = False

mioXpektron.batch_tic_norm(input_pattern, output_dir='normalized_spectra', mz_min=None, mz_max=None, normalization_target=1000000.0, verbose=False)

Batch‑import and preprocess multiple ToF‑SIMS spectra, then save the (m/z, normalized_intensity) arrays for each file as a tab‑separated text file in output_dir.

Parameters:

• input_pattern (str) – Glob pattern (e.g. ‘spectra/*.txt’) that expands to the input files.

• output_dir (str) – Folder where ‘<original‑name>_normalized.txt’ will be written; created if it does not already exist.

• mz_min (float | None) – Passed through to :pyfunc:`data_preprocessing`.

• mz_max (float | None) – Passed through to :pyfunc:`data_preprocessing`.

• normalization_target (float | None) – Passed through to :pyfunc:`data_preprocessing`.

• verbose (bool) – Passed through to :pyfunc:`data_preprocessing`.

Returns:

Paths of the files written, in processing order.

Return type:

List[str]

mioXpektron.check_overlapping_peaks(data_dir, file_name, mz_min, mz_max, norm_tic=False, alpha=0.2)

mioXpektron.check_overlapping_peaks2(data_dir, file_pattern, mz_min, mz_max, norm_tic=False, alpha=0.18, bin_width=0.001, show_median=True, show_group_cumulative=True)

Overlay spectra with two colors (Cancer vs Control) inferred from file names.

Parameters:

• data_dir (str) – Directory containing spectra.

• file_pattern (str) – Glob pattern (e.g., “*.txt”).

• mz_min (float) – m/z window to visualize.

• mz_max (float) – m/z window to visualize.

• norm_tic (bool, default False) – Normalize each spectrum by its TIC prior to plotting.

• alpha (float, default 0.18) – Line transparency for individual spectra.

• bin_width (float, default 0.001) – Common grid step for interpolation (used for medians/cumulative plots).

• show_median (bool, default True) – If True, overlay per-group median curves (thicker lines).

• show_group_cumulative (bool, default True) – If True, plot per-group cumulative intensity curves on a separate figure.

Notes

• Group detection is based on substrings in filenames: “_CC” (Cancer), “_CT” (Control).

• Files without these markers are labeled “Unknown” and plotted in grey.

mioXpektron.collect_peak_properties_batch(files, mz_min=None, mz_max=None, baseline_method='airpls', noise_method='wavelet', missing_value_method='interpolation', normalization_target=100000000.0, method='Gaussian', min_intensity=1, min_snr=3, min_distance=5, window_size=10, peak_height=50, prominence=50, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, distance_threshold=0.01, combined=False, noise_model='global', noise_bins=20, noise_min_points=25, deconvolution_min_bic_delta=10.0, deconvolution_overlap_factor=0.75, deconvolution_replace_singles=True)

Collect peak properties from a batch of ToF-SIMS files.

Parameters:

• files (list of str) – List of file paths to process.

• mz_min (float or None) – m/z window for data import (if supported).

• mz_max (float or None) – m/z window for data import (if supported).

• baseline_method (str) – Method for baseline correction.

• noise_method (str) – Noise filtering method.

• missing_value_method (str) – Method for handling missing values.

• normalization_target (float) – Target TIC normalization value.

• min_snr (int or float) – Minimum signal-to-noise ratio for peak detection.

• min_distance (int) – Minimum distance between peaks (in data points).

• prominence (int or float or None) – Minimum peak prominence for detection.

• width_rel_height (float) – Relative height for width calculation (e.g., 0.5 = FWHM).

• noise_model ({"global", "mz_binned"}) – Noise model used to derive peak thresholds.

• noise_bins (int) – Number of m/z bins for noise_model="mz_binned".

• noise_min_points (int) – Minimum positive noise points per bin before using local estimates.

Returns:

peaks_df – DataFrame with all peak properties for all files.

Return type:

pd.DataFrame

mioXpektron.compare_denoising_methods(x, y, *, min_mz=None, max_mz=None, max_peaks=300, min_prominence=None, rel_height=0.5, search_ppm=20.0, match_min_prominence_ratio=0.1, match_min_prominence_abs=0.0, match_min_width_pts=0.25, resample_to_uniform=False, include_derivatives=False, target_dx=None, return_format='pandas', n_jobs=-1, parallel_backend='thread', progress=True, baseline_expand=2.0, flank_inner=1.5, flank_outer=3.0, hf_enabled=True, hf_cutoff_hz=None, hf_cutoff_frac=0.3, hf_resample_dx=None, hf_psd_method='welch', hf_welch_nperseg=None)

Run a battery of denoising/smoothing methods and quantify both peak preservation and noise reduction.

Parameters:

• x (array-like or None) – m/z axis. If None, an index axis [0..N-1] is used.

• y (array-like) – Raw intensities.

• min_mz (float, optional) – Optional range restriction on x prior to peak detection and evaluation.

• max_mz (float, optional) – Optional range restriction on x prior to peak detection and evaluation.

• max_peaks (int, default 300) – Maximum number of reference peaks (by prominence) to evaluate in the selected range.

• min_prominence (float, optional) – Prominence threshold for scipy.signal.find_peaks during reference detection.

• rel_height (float, default 0.5) – Relative height used for FWHM measurements (e.g., 0.5 = half-height).

• search_ppm (float, default 20.0) – ±ppm window around each reference m/z used to re-detect peaks after denoising.

• match_min_prominence_ratio (float, default 0.1) – Minimum post-denoise prominence required for a matched peak, expressed as a fraction of the raw reference prominence.

• match_min_prominence_abs (float, default 0.0) – Absolute lower bound for post-denoise peak prominence.

• match_min_width_pts (float, default 0.25) – Minimum acceptable peak width in index points for a post-denoise match.

• resample_to_uniform (bool, default False) – If True, allow denoisers to resample to a uniform grid internally when beneficial.

• include_derivatives (bool, default False) – If True, include derivative-style Savitzky-Golay (deriv>0) and Gaussian (order>0) operators in the candidate grid. By default the search includes only smoothing/denoising variants.

• target_dx (float, optional) – Desired spacing when resample_to_uniform=True.

• return_format ({"pandas","polars"}, default "pandas") – Backend for output DataFrames.

• n_jobs (int, default -1) – Number of workers used to evaluate methods in parallel (1 disables parallelism).

• parallel_backend ({"thread","process"}, default "thread") – Parallelism backend. Threads are often efficient because NumPy/SciPy/PyWavelets drop the GIL.

• progress (bool, default True) – Show a progress bar if tqdm is available.

• baseline_expand (float, default 2.0) – Multiplier to expand each peak’s FWHM window when masking baseline regions used for noise/PSD estimates.

• flank_inner (float, defaults 1.5 and 3.0) – Distances (in FWHM multiples) defining flanking bands used for local noise estimation.

• flank_outer (float, defaults 1.5 and 3.0) – Distances (in FWHM multiples) defining flanking bands used for local noise estimation.

• hf_enabled (bool, default True) – If True, compute high-frequency (HF) residual power metrics on baseline regions via PSD.

• hf_cutoff_hz (float, optional) – Absolute HF cutoff frequency (cycles per m/z). If None, uses hf_cutoff_frac * Nyquist.

• hf_cutoff_frac (float, default 0.3) – Fraction of the Nyquist frequency used as the HF band when hf_cutoff_hz is None.

• hf_resample_dx (float, optional) – Δx used to resample baseline segments to a uniform grid for PSD; defaults to median Δx if None.

• hf_psd_method ({"welch","periodogram"}, default "welch") – PSD estimator for HF power. Welch provides lower-variance estimates on finite windows.

• hf_welch_nperseg (int, optional) – Segment length for Welch PSD. If None, chosen automatically (≈ max(16, N/8), power-of-two, ≤1024).

Returns:

summary_df, per_peak_df – If return_format=”pandas”, returns pandas.DataFrame; if “polars”, returns polars.DataFrame. summary_df contains method-level medians/IQRs, noise and HF metrics; per_peak_df has per-peak rows.

Return type:

DataFrame

mioXpektron.compare_methods_in_windows(x, y, windows, *, per_window_max_peaks=50, min_prominence=None, rel_height=0.5, search_ppm=20.0, match_min_prominence_ratio=0.1, match_min_prominence_abs=0.0, match_min_width_pts=0.25, resample_to_uniform=False, include_derivatives=False, target_dx=None, return_format='pandas', n_jobs=-1, parallel_backend='thread', progress=True, baseline_expand=2.0, flank_inner=1.5, flank_outer=3.0, hf_enabled=True, hf_cutoff_hz=None, hf_cutoff_frac=0.3, hf_resample_dx=None, hf_psd_method='welch', hf_welch_nperseg=None, auto_tune=False, auto_tune_files=None)

Evaluate denoising methods across multiple m/z windows and aggregate results.

Parameters:

• x (np.ndarray) – m/z axis and intensity values.

• y (np.ndarray) – m/z axis and intensity values.

• windows (list[tuple[float, float]]) – Each tuple is (min_mz, max_mz) for a window to evaluate.

• per_window_max_peaks (int, default 50) – Max number of strongest peaks (by prominence) to measure within each window.

• min_prominence (float, optional) – Minimum prominence passed to signal.find_peaks for reference peak detection.

• rel_height (float, default 0.5) – Relative height used to define FWHM when measuring peaks.

• search_ppm (float, default 20.0) – ±ppm window around each reference m/z used to re-detect peaks after denoising.

• match_min_prominence_ratio (floats) – Forwarded to the peak re-matching logic used after denoising.

• match_min_prominence_abs (floats) – Forwarded to the peak re-matching logic used after denoising.

• match_min_width_pts (floats) – Forwarded to the peak re-matching logic used after denoising.

• resample_to_uniform (optional) – Passed through to denoisers that support resampling.

• target_dx (optional) – Passed through to denoisers that support resampling.

• include_derivatives (bool, default False) – If True, include derivative-style Savitzky-Golay and Gaussian candidates inside each window’s method grid.

• return_format ({"pandas","polars"}) – Backend for output DataFrames.

• n_jobs (int, default -1) – Workers used within each window’s call to compare_denoising_methods.

• parallel_backend ({"thread","process"}, default "thread") – Parallelism backend.

• progress (bool, default True) – Show progress bars during evaluation.

• baseline_expand (floats) – Baseline mask expansion and flanking-band multipliers forwarded to noise metrics.

• flank_inner (floats) – Baseline mask expansion and flanking-band multipliers forwarded to noise metrics.

• flank_outer (floats) – Baseline mask expansion and flanking-band multipliers forwarded to noise metrics.

• hf_enabled (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• hf_cutoff_hz (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• hf_cutoff_frac (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• hf_resample_dx (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• hf_psd_method (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• hf_welch_nperseg (optional) – High-frequency PSD controls forwarded to noise metrics (Welch is lower-variance).

• auto_tune (bool)

• auto_tune_files (list[str] | None)

Returns:

• If return_format == “pandas” –

  rolluppd.DataFrame

  Method-level aggregation across all windows.

  summary_allpd.DataFrame

  Per-window, per-method summary table (noise and peak metrics).

  detail_allpd.DataFrame

  Per-peak detail table across all windows.

• If return_format == “polars” – rollup, summary_all, detail_all : pl.DataFrame

mioXpektron.data_preprocessing(file_path, mz_min=None, mz_max=None, normalization_target=1000000.0, verbose=True, return_all=False)

Import and preprocess ToF-SIMS data from a text file.

Parameters:

file_pathstr

Path to the ToF-SIMS data file

mz_min, mz_maxfloat, optional

m/z range to import

normalization_targetfloat or None

Target TIC for normalization, or None to skip

verbosebool

Print progress if True

return_allbool

If True, return all intermediate arrays

Returns:

mz_values : numpy.ndarray normalized_intensities : numpy.ndarray sample_name : str group : str (optionally: intermediate arrays)

mioXpektron.decode_method_label(label)

Translate a compact label back into noise_filtering parameters.

Parameters:

label (str)

Return type:

dict

mioXpektron.detect_peaks_cwt_with_area(mz_values, intensities, sample_name, group, min_intensity=1, min_snr=3, min_distance=2, window_size=10, peak_height=50, prominence=10, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, noise_model='global', noise_bins=20, noise_min_points=25, verbose=False)

Peak detection using Continuous Wavelet Transform (CWT) for ToF-SIMS spectra.

Returns:

peak_propertiespd.DataFrame

Contains: mz, intensities, widths (approx), amplitudes, areas

mioXpektron.detect_peaks_with_area(mz_values, intensities, sample_name, group, min_intensity=1, min_snr=3, min_distance=2, window_size=10, peak_height=50, prominence=10, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, noise_model='global', noise_bins=20, noise_min_points=25, verbose=False)

Fast peak detection in ToF-SIMS or similar spectra, including peak area.

Returns:

peak_indicesnp.ndarray

Indices of detected peaks

peak_propertiesdict

Contains: mz, intensities, widths, prominences, heights, areas

mioXpektron.detect_peaks_with_area_v2(mz, intens, sample_name, group, *, min_intensity=1, min_snr=3, min_distance=2, prominence=10, min_peak_width=1, max_peak_width=75, rel_height=0.5, noise_model='global', noise_bins=20, noise_min_points=25, noise_window=10, verbose=False)

mioXpektron.import_data(file_path, mz_min=None, mz_max=None, group_patterns=None, group_fn=None)

Import ToF-SIMS data from a spectrum file.

Parameters:

• file_path (str) – Path to the ToF-SIMS data file. Supports tab-delimited .txt exports with m/z + Intensity columns and CSV exports with mz + corrected_intensity or intensity columns.

• mz_min (float, optional) – Minimum m/z value to be imported (inclusive).

• mz_max (float, optional) – Maximum m/z value to be imported (inclusive).

• group_patterns (dict[str, str], optional) – Mapping of {regex_pattern: group_label}. Patterns are tested against the sample name (filename without extension) in order; the first match determines the group. Defaults to {'_CC...': 'Cancer', '_CT...': 'Control'}.

• group_fn (callable, optional) – A function (sample_name: str) -> str that returns the group label directly. When provided this takes priority over group_patterns.

Returns:

• mz (np.ndarray) – Mass-to-charge ratio values.

• intensity (np.ndarray) – Intensity values.

• sample_name (str) – Sample name extracted from file name.

• group (str) – Group label derived from the filename.

Return type:

Tuple[ndarray, ndarray, str, str]

mioXpektron.normalization_target(files, mz_min=None, mz_max=None)

Normalize peak intensities or areas to a target value.

Parameters:

• files (list of str) – List of file paths to process.

• mz_min (float or None) – m/z window for data import (if supported).

• mz_max (float or None) – m/z window for data import (if supported).

• baseline_method (str) – Method for baseline correction.

• noise_method (str) – Noise filtering method.

• missing_value_method (str) – Method for handling missing values.

Returns:

normalized_df – Normalized DataFrame.

Return type:

pd.DataFrame

mioXpektron.noise_filtering(intensities, *, method='wavelet', window_length=15, polyorder=3, deriv=0, gauss_sigma_pts=None, gaussian_order=0, wavelet='sym8', level=None, threshold_strategy='universal', threshold_mode='soft', sigma=None, sigma_strategy='per_level', variance_stabilize='none', anscombe_negative_policy='warn_clip', cycle_spins=0, pywt_mode='periodization', clip_nonnegative=True, preserve_tic=False, x=None, resample_to_uniform=False, target_dx=None, forward_interp='pchip')

Apply 1D denoising/smoothing to ToF-SIMS spectra.

Notes

• Savitzky–Golay / Gaussian / Median assume ~uniform sampling. If your m/z grid is nonuniform, pass x and set resample_to_uniform=True. The wavelet path can also resample when resample_to_uniform=True.

• Wavelet shrinkage preserves narrow peaks; consider Bayes/SURE and cycle-spins.

Parameters:

• intensities (np.ndarray) – 1D intensity array.

• method ({'savitzky_golay','gaussian','median','wavelet','none'})

• window_length (int) – Odd window for Savitzky–Golay or median; will be coerced to odd >=3.

• polyorder (int) – For Savitzky–Golay, 0 ≤ polyorder < window_length.

• deriv (int) – For Savitzky–Golay, derivative order (0 = smoothing; 1/2/… compute derivatives). Requires polyorder >= deriv.

• gauss_sigma_pts (float or None) – If provided, overrides default sigma = window_length/6 for Gaussian filter.

• gaussian_order (int) – For Gaussian filtering, derivative order for ndimage.gaussian_filter1d. 0 = smoothing; >0 computes derivatives.

• wavelet (Literal['db4', 'db8', 'sym5', 'sym8', 'coif2', 'coif3']) – Passed to wavelet processing (see wavelet_denoise).

• level (int | None) – Passed to wavelet processing (see wavelet_denoise).

• threshold_strategy (Literal['universal', 'bayes', 'sure', 'sure_opt']) – Passed to wavelet processing (see wavelet_denoise).

• threshold_mode (Literal['soft', 'hard']) – Passed to wavelet processing (see wavelet_denoise).

• sigma (float | None) – Passed to wavelet processing (see wavelet_denoise).

• cycle_spins (Literal[0, 4, 8, 16, 32]) – Passed to wavelet processing (see wavelet_denoise).

• pywt_mode (str) – Passed to wavelet processing (see wavelet_denoise).

• sigma_strategy ({"per_level","global"}) – Strategy if sigma is None. “per_level” = σ_j via MAD on each detail subband; “global” = one σ via MAD on the finest detail of the unshifted input.

• variance_stabilize ({"none","anscombe"}) – Apply variance‑stabilizing transform before denoising. "anscombe" uses the classical Anscombe transform for non-negative Poisson-like input.

• anscombe_negative_policy ({"warn_clip","clip","raise"}) – Handling policy for negative values before the classical Anscombe transform.

• clip_nonnegative (bool) – Output behaviors.

• preserve_tic (bool) – Output behaviors.

• x (np.ndarray or None) – Optional m/z (or channel) axis aligned with intensities.

• resample_to_uniform (bool) – If True and x is provided, internally resample to a uniform grid and back.

• target_dx (float or None) – Target spacing for the uniform grid (if None, inferred).

• forward_interp ({'pchip','linear'}) – Interpolant used when building the uniform-grid signal (PCHIP recommended).

Returns:

Filtered intensities aligned to the input grid/order.

Return type:

np.ndarray

Raises:

ValueError – If intensities or x have mismatched shapes or if intensities is not 1D. If Savitzky–Golay has polyorder < deriv after clamping, or if method is unknown.

See also

wavelet_denoise

Core wavelet denoising routine used when method=”wavelet”.

class mioXpektron.PlotPeak(mz_values, raw_intensities, sample_name, group=None, corrected_intensities=None)

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)

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)

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)

mioXpektron.plot_pareto_delta_snr_vs_height(summary, annotate=True, top_k=12, out_path=None, ax=None, basis='constrained_pareto_then_snr', require_pass=True, require_finite_metrics=True, save_plot=True, save_pareto=True)

Render ΔSNR vs. |%height| with Pareto annotations.

Parameters mirror select_methods(); see DenoisingMethods.plot for additional discussion. The helper creates the Matplotlib figure when ax is omitted and optionally saves both the chart and frontier table.

mioXpektron.rank_method(input_format, summary_df, per_peak_df, w_match=3.0, w_mz=2.0, w_area=2.0, w_height=1.5, w_fwhm=1.0, w_spread=1.0, w_noise_db=2.0, w_delta_snr_db=1.5, w_hf_db=1.5, w_hf_frac=1.0, min_noise_db=0.5, min_delta_snr_db=1.0, selection_criteria=None)

Dispatch ranking to pandas or polars implementation with identical semantics.

Returns a DataFrame (pandas or polars) sorted by ascending score and includes explicit pass/fail flags for denoising and peak-preservation criteria.

Parameters:

• min_noise_db (float)

• min_delta_snr_db (float)

• selection_criteria (Dict[str, float] | None)

mioXpektron.resample_spectrum(mz_values, intensity_values, target_mz, method='linear')

Resample a spectrum onto a target m/z grid.

The input axis is sorted, duplicate m/z positions are collapsed to their first occurrence, and values outside the native m/z range are filled with zero. Supported interpolation methods are linear, pchip, akima, makima, and cubic.

mioXpektron.select_methods(summary, basis='constrained_pareto_then_snr', top_k=12, require_pass=True, require_finite_metrics=True)

Returns:

the post-filter DataFrame (shared!) frontier_df: DataFrame of Pareto points (or None if basis=’score’ and Pareto not computed) selected_df: the DataFrame of selected rows to annotate/return (top_k)

Return type:

filtered_df

mioXpektron.robust_noise_estimation(intensities, peak_indices=None, window=2, peak_height=None, peak_prominence=None, min_peak_width=1, max_peak_width=75)

Robust noise estimation by excluding regions near detected peaks.

Parameters:

• intensities (np.ndarray) – Denoised, baseline-corrected intensities.

• peak_indices (np.ndarray or None) – Indices of detected peaks. If None, function will detect peaks automatically.

• window (int) – Extra number of data points to exclude on each side of the detected peak width. The measured peak extent is always masked first.

• peak_height (float or None) – Minimum height for peak detection. If None, defaults to the median of positive intensities (data-adaptive).

• peak_prominence (float or None) – Minimum prominence for peak detection. If None, defaults to 3x the MAD of positive intensities (data-adaptive).

Returns:

• median_intensity (float) – Median intensity of noise region.

• robust_std (float) – Robust standard deviation (Gaussian-equivalent MAD) of noise region.

mioXpektron.robust_noise_estimation_mz(mz_values, intensities, min_mz, max_mz)

Estimate noise from a user-specified m/z baseline region.

Parameters:

• mz_values (np.ndarray) – m/z axis.

• intensities (np.ndarray) – Corresponding intensity values.

• min_mz (float) – m/z window that defines the baseline region.

• max_mz (float) – m/z window that defines the baseline region.

Returns:

• median_intensity (float) – Median intensity of the baseline region.

• robust_std (float) – Robust standard deviation (MAD-scaled) of the baseline region.

mioXpektron.robust_peak_detection(mz_values, intensities, sample_name, group, method='Gaussian', min_intensity=1, min_snr=3, min_distance=2, window_size=10, peak_height=50, prominence=10, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, distance_threshold=0.1, combined=False, use_cwt=False, noise_model='global', noise_bins=20, noise_min_points=25, deconvolution_min_bic_delta=10.0, deconvolution_overlap_factor=0.75, deconvolution_replace_singles=True, verbose=False)

Fast peak detection in ToF-SIMS or similar spectra, including peak area.

Returns:

peak_indicesnp.ndarray

Indices of detected peaks

peak_propertiesdict

Contains: mz, intensities, widths, prominences, heights, areas

Notes

Overlapping-peak deconvolution now requires both geometric overlap and a BIC improvement over a single-Gaussian window fit. Fitted component widths must also remain within the user-specified peak-width bounds.

mioXpektron.small_param_grid_preset(n_points=None)

A compact parameter grid for common methods.

Keys must match pybaselines.Baseline method names (plus ‘poly’ and our two filters).

Parameters:

n_points (int, optional) – Number of data points in spectrum. If provided, window_size will be calculated adaptively as a percentage of data size. If None, uses moderate defaults suitable for ~100K point spectra.

Returns:

Parameter grid with method names as keys

Return type:

dict

Notes

Window sizes are calculated as: - Small: 0.05% of data (min 51) - Medium: 0.10% of data (min 101) - Large: 0.20% of data (min 501)

This adaptive scaling ensures that filter methods perform consistently across datasets of different sizes. Fixed window sizes work poorly: - For 10K points: window=101 is 1.0% (OK) - For 1M points: window=101 is 0.01% (too small, causes jagged baselines)

Examples

>>> # Auto-scale for 938K point spectrum
>>> grid = small_param_grid_preset(n_points=938000)
>>> grid['median_filter']
[{'window_size': 469}, {'window_size': 938}, {'window_size': 1876}]

>>> # Use defaults for unknown size
>>> grid = small_param_grid_preset()
>>> grid['median_filter']
[{'window_size': 501}, {'window_size': 1001}, {'window_size': 2001}]

mioXpektron.tic_normalization(intensities, target_tic=1000000.0)

Scale intensities so the total-ion current equals target_tic.

This is the most common normalisation in ToF-SIMS. Each spectrum is multiplied by target_tic / sum(intensities) so that all spectra share the same TIC.

Parameters:

• intensities (array-like) – Raw ion counts or intensities.

• target_tic (float or None) – Desired total-ion current after scaling. Pass None to skip.

Return type:

np.ndarray

mioXpektron.run_pipeline(files, *, calib_channels_dict=None, config=None)

Run the end‑to‑end ToF‑SIMS batch pipeline and return aligned matrices.

Steps

1. Optional recalibration (Channel→m/z)

2. Denoising

3. Baseline correction

4. TIC normalization

5. Peak detection and alignment → unified m/z × samples tables

rtype:

(intensity_df, area_df) aligned by m/z across samples.

Parameters:

• files (Sequence[str])

• calib_channels_dict (Dict[str, Sequence[float]] | None)

• config (PipelineConfig | None)

Return type:

Tuple[DataFrame, DataFrame]

class mioXpektron.PipelineConfig(use_recalibration=True, reference_masses=None, output_folder_calibrated='calibrated_spectra', denoise_method='wavelet', denoise_params=None, baseline_method='airpls', baseline_params=None, clip_negative_after_baseline=True, normalization_target=1000000.0, mz_min=None, mz_max=None, mz_tolerance=0.2, mz_rounding_precision=1, max_workers=None, auto_tune=False)

Bases: object

High-level pipeline configuration for batch ToF‑SIMS processing.

Parameters:

• use_recalibration (bool)

• reference_masses (List[float] | None)

• output_folder_calibrated (str)

• denoise_method (str)

• denoise_params (Dict | None)

• baseline_method (str)

• baseline_params (Dict | None)

• clip_negative_after_baseline (bool)

• normalization_target (float)

• mz_min (float | None)

• mz_max (float | None)

• mz_tolerance (float)

• mz_rounding_precision (int)

• max_workers (int | None)

• auto_tune (bool)

use_recalibration: bool = True

reference_masses: List[float] | None = None

output_folder_calibrated: str = 'calibrated_spectra'

denoise_method: str = 'wavelet'

denoise_params: Dict | None = None

baseline_method: str = 'airpls'

baseline_params: Dict | None = None

clip_negative_after_baseline: bool = True

normalization_target: float = 1000000.0

mz_min: float | None = None

mz_max: float | None = None

mz_tolerance: float = 0.2

mz_rounding_precision: int = 1

max_workers: int | None = None

auto_tune: bool = False

class mioXpektron.AutoCalibrator(config=None)

Bases: object

Automatic multi-model calibrator.

Fits all requested models, selects the best one per file, and writes calibrated spectra.

Parameters:

config (AutoCalibConfig | None)

last_autodetect_methods: Dict[str, List[str]]

calibrate(files, calib_channels_dict=None)

Calibrate all files with automatic model selection.

Parameters:

• files (Sequence[str])

• calib_channels_dict (Dict[str, Sequence[float]] | None)

Return type:

DataFrame

class mioXpektron.AutoCalibConfig(reference_masses, output_folder='calibrated_spectra', max_workers=None, autodetect_tol_da=None, autodetect_tol_ppm=None, autodetect_method='gaussian', autodetect_fallback_policy='max', autodetect_strategy='mz', prefer_recompute_from_channel=False, outlier_threshold=3.0, use_outlier_rejection=True, max_iterations=3, model=None, models_to_try=None, prefer_physical_models=True, min_calibrants=3, max_ppm_warning=100.0, max_ppm_error=500.0, use_bootstrap_init=True, spline_smoothing=None, multisegment_breakpoints=<factory>, instrument_params=<factory>)

Bases: object

Universal calibration configuration with robust options.

Parameters:

• reference_masses (list of float) – Known calibrant ion masses (m/z).

• model (str, optional) – Convenience shortcut — a single model name (or common alias like 'quadratic', 'tof', 'linear'). Resolved into models_to_try during __post_init__. Ignored when models_to_try is explicitly provided.

• models_to_try (list of str, optional) – Explicit list of model names to fit. Default: all production-ready models (excludes experimental ones such as multisegment and physical).

• output_folder (str)

• max_workers (int | None)

• autodetect_tol_da (float | None)

• autodetect_tol_ppm (float | None)

• autodetect_method (str)

• autodetect_fallback_policy (str)

• autodetect_strategy (str)

• prefer_recompute_from_channel (bool)

• outlier_threshold (float)

• use_outlier_rejection (bool)

• max_iterations (int)

• prefer_physical_models (bool)

• min_calibrants (int)

• max_ppm_warning (float)

• max_ppm_error (float)

• use_bootstrap_init (bool)

• spline_smoothing (float | None)

• multisegment_breakpoints (List[float])

• instrument_params (Dict[str, float])

reference_masses: List[float]

output_folder: str = 'calibrated_spectra'

max_workers: int | None = None

autodetect_tol_da: float | None = None

autodetect_tol_ppm: float | None = None

autodetect_method: str = 'gaussian'

autodetect_fallback_policy: str = 'max'

autodetect_strategy: str = 'mz'

prefer_recompute_from_channel: bool = False

outlier_threshold: float = 3.0

use_outlier_rejection: bool = True

max_iterations: int = 3

model: str | None = None

models_to_try: List[str] | None = None

prefer_physical_models: bool = True

min_calibrants: int = 3

max_ppm_warning: float = 100.0

max_ppm_error: float = 500.0

use_bootstrap_init: bool = True

spline_smoothing: float | None = None

multisegment_breakpoints: List[float]

instrument_params: Dict[str, float]

class mioXpektron.PlotPeaks(config=None)

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)

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)

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)

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()

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()

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)

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)

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()

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.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')

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'

mioXpektron.plot_overlapping_peaks(data_dir, file_pattern, mz_min, mz_max, norm_tic=False, alpha=0.18, bin_width=0.001, show_median=True, show_group_cumulative=True)

Overlay spectra with two colors (Cancer vs Control) inferred from file names.

DEPRECATED: This function is maintained for backwards compatibility. Use PlotPeaks class for new code.

Parameters:

• data_dir (str) – Directory containing spectra.

• file_pattern (str) – Glob pattern (e.g., “*.txt”).

• mz_min (float) – m/z window to visualize.

• mz_max (float) – m/z window to visualize.

• norm_tic (bool, default False) – Normalize each spectrum by its TIC prior to plotting.

• alpha (float, default 0.18) – Line transparency for individual spectra.

• bin_width (float, default 0.001) – Common grid step for interpolation (used for medians/cumulative plots).

• show_median (bool, default True) – If True, overlay per-group median curves (thicker lines).

• show_group_cumulative (bool, default True) – If True, plot per-group cumulative intensity curves on a separate figure.

Notes

• Group detection is based on substrings in filenames: “_CC” (Cancer), “_CT” (Control).

• Files without these markers are labeled “Unknown” and plotted in grey.

Examples

>>> # New recommended approach
>>> config = PlotPeaksConfig(
...     data_dir="data/spectra",
...     mz_min=100.0,
...     mz_max=200.0
... )
>>> plotter = PlotPeaks(config)
>>> plotter.load_data()
>>> plotter.plot_all()

class mioXpektron.FlexibleCalibratorDebug(config=None)

Bases: FlexibleCalibrator

Debug variant of FlexibleCalibrator with verbose peak-picking.

Inherits all calibration logic and overrides only _autodetect_channels to route through the diagnostic versions of _enhanced_pick_channels and _parabolic_peak_center.

Parameters:

config (FlexibleCalibConfig | None)

mioXpektron.FlexibleCalibConfigDebug

alias of FlexibleCalibConfig

class mioXpektron.BatchTicNorm(input_pattern, output_dir='normalized_spectra', normalization_target=1000000.0, n_workers=-1, verbose=True)

Bases: object

Batch TIC normalization for multiple spectra files using Polars and concurrent.futures.

Supports both CSV and TXT file formats: - CSV: Uses ‘corrected_intensity’ if available, otherwise ‘intensity’ - TXT: Tab-separated m/z and intensity values

Output files contain: channel, mz, intensity (normalized)

Parameters:

• input_pattern (str)

• output_dir (str)

• normalization_target (float)

• n_workers (int)

• verbose (bool)

__init__(input_pattern, output_dir='normalized_spectra', normalization_target=1000000.0, n_workers=-1, verbose=True)

Initialize BatchTicNorm processor.

Parameters:

• input_pattern (str) – Glob pattern for input files (e.g., ‘data/.csv’ or ‘data/.txt’)

• output_dir (str) – Directory to save normalized files

• normalization_target (float) – Target TIC value for normalization (default: 1e6)

• n_workers (int) – Number of parallel workers (default: 16)

• verbose (bool) – Print progress information

process()

Process all files using concurrent.futures.

Returns:

List of output file paths that were successfully created

Return type:

List[str]

get_tic_statistics()

Calculate TIC statistics for all input files before normalization.

Returns:

DataFrame with columns: filename, tic_original, tic_million

Return type:

pl.DataFrame

mioXpektron.normalize(intensities, method='tic', **kwargs)

Apply a named normalization method to a 1-D intensity array.

Parameters:

• intensities (array-like) – Raw intensity values (1-D).

• method (str, default "tic") – Name of the normalization method. Call normalization_method_names() for the full list.

• **kwargs – Method-specific keyword arguments forwarded to the underlying function (e.g. target_tic for TIC, reference_mz_idx for selected-ion normalization).

Returns:

Normalized intensity values.

Return type:

np.ndarray

Raises:

ValueError – If method is not recognised.

mioXpektron.normalization_method_names()

Return a sorted list of available 1-D normalization method names.

Return type:

List[str]

class mioXpektron.NormalizationEvaluator(files=<factory>, methods=None, method_kwargs_map=None, mz_min=None, mz_max=None, n_clusters=None, cluster_bootstrap_rounds=30, cluster_bootstrap_frac=0.8, random_state=0, compute_supervised=True, n_jobs=-1, group_patterns=None, group_fn=None)

Bases: object

Evaluate normalization methods on labelled ToF-SIMS spectra.

Parameters:

• files (list of str or Path) – Paths or glob patterns expanding to spectrum text files.

• methods (list of str, optional) – Normalization method names. Defaults to a sensible subset.

• method_kwargs_map (dict, optional) – {method_name: {kwarg: value, ...}} for method-specific params.

• mz_min (float, optional) – m/z range to import.

• mz_max (float, optional) – m/z range to import.

• n_clusters (int, optional) – Number of clusters for KMeans evaluation. Auto-detected if omitted.

• cluster_bootstrap_rounds (int) – Bootstrap rounds for stability metric.

• random_state (int) – RNG seed for reproducibility.

• compute_supervised (bool) – Run supervised classification (requires scikit-learn + >=2 groups).

• n_jobs (int) – Parallel workers (joblib). -1 = all CPUs, 1 = sequential.

• cluster_bootstrap_frac (float)

• group_patterns (Dict[str, str] | None)

• group_fn (Any | None)

Examples

>>> evaluator = NormalizationEvaluator(files=["data/*.txt"])
>>> summary = evaluator.evaluate()
>>> evaluator.plot()

files: List[str | Path]

methods: List[str] | None = None

method_kwargs_map: Dict[str, Dict[str, Any]] | None = None

mz_min: float | None = None

mz_max: float | None = None

n_clusters: int | None = None

cluster_bootstrap_rounds: int = 30

cluster_bootstrap_frac: float = 0.8

random_state: int = 0

compute_supervised: bool = True

n_jobs: int = -1

group_patterns: Dict[str, str] | None = None

group_fn: Any | None = None

evaluate()

Evaluate all methods and return a scored DataFrame.

Returns:

One row per method, sorted by score_combined (descending). Includes raw metrics, z-scored metrics, and four composite scores.

Return type:

pd.DataFrame

plot(out_dir='normalization_selection_output', save=True)

Generate evaluation plots (box plots, bar charts, radar).

Parameters:

• out_dir (str or Path) – Sub-folder inside OUTPUT_DIR for saved figures.

• save (bool) – Persist plots as PNG + PDF.

Returns:

Saved file paths.

Return type:

list of Path

print_summary(top_n=5)

Print a ranked summary of evaluation results.

Parameters:

top_n (int, default 5) – Number of top methods to display per score variant.

Return type:

None

preview_overlay(file, methods=None, max_methods=5, mz_min=None, mz_max=None, save_to='normalization_selection_output')

Plot raw vs normalised overlays for quick visual comparison.

Parameters:

• file (str or Path) – Single spectrum file to visualise.

• methods (list of str, optional) – Methods to overlay. Defaults to top methods from evaluation.

• max_methods (int) – Cap on the number of overlays.

• mz_min (float, optional) – m/z window for the plot.

• mz_max (float, optional) – m/z window for the plot.

• save_to (str, Path, or None) – Save directory (relative to OUTPUT_DIR). None skips saving.

Return type:

None

class mioXpektron.NormalizationMethods(mz_values, raw_intensities)

Bases: object

Evaluate and apply normalization strategies for ToF-SIMS data.

Parameters:

• mz_values (array-like) – The m/z axis shared by all spectra.

• raw_intensities (array-like) – Raw intensity values aligned with mz_values.

apply(method='tic', **kwargs)

Apply a named normalization to the stored spectrum.

Parameters:

• method (str) – Normalization method name (see normalization_method_names()).

• **kwargs – Method-specific keyword arguments.

Returns:

Normalized intensity array.

Return type:

np.ndarray

compare_visual(methods=None, method_kwargs_map=None, mz_min=0, mz_max=500, sample_name='test', group=None, figsize=(12, 8), save_plot=True)

Plot the raw spectrum alongside several normalized versions.

Parameters:

• methods (list of str, optional) – Normalization methods to overlay. Defaults to a curated set.

• method_kwargs_map (dict, optional) – {method: {kwarg: value}} for method-specific parameters.

• mz_min (float) – m/z bounds for the preview window.

• mz_max (float) – m/z bounds for the preview window.

• sample_name (str) – Label used for file naming.

• group (str or None) – Group identifier.

• figsize (tuple) – Figure size.

• save_plot (bool) – Persist the rendered figure.

Return type:

matplotlib.axes.Axes

normalize_and_check(method='tic', method_kwargs=None, *, sample_name='test', group=None, mz_min=0, mz_max=500, show_peaks=False, peak_height=1000, peak_prominence=50, min_peak_width=1, max_peak_width=None, figsize=(10, 6), save_plot=True)

Apply one normalization and visualise the result with peak overlay.

Parameters:

• method (str) – Normalization method.

• method_kwargs (dict, optional) – Extra kwargs forwarded to normalize().

• sample_name (str) – Plot labels.

• group (str) – Plot labels.

• mz_min (float) – m/z window for the plot.

• mz_max (float) – m/z window for the plot.

• show_peaks (bool) – Annotate detected peaks.

• peak_height (float) – Peak detection tuning passed to PlotPeak.

• peak_prominence (float) – Peak detection tuning passed to PlotPeak.

• min_peak_width (int) – Peak detection tuning passed to PlotPeak.

• max_peak_width (int | None) – Peak detection tuning passed to PlotPeak.

• figsize (tuple)

• save_plot (bool)

Return type:

matplotlib.axes.Axes

static evaluate(files, methods=None, method_kwargs_map=None, mz_min=None, mz_max=None, n_jobs=-1, compute_supervised=True, save_results=True)

Evaluate normalization methods across multiple spectra files.

Thin wrapper around NormalizationEvaluator that runs evaluation, prints a summary, and optionally saves results.

Parameters:

• files (list of str or Path) – Spectrum file paths or glob patterns.

• methods (list of str, optional) – Method names to evaluate.

• method_kwargs_map (dict, optional) – Per-method keyword arguments.

• mz_min (float, optional) – m/z range for data import.

• mz_max (float, optional) – m/z range for data import.

• n_jobs (int) – Parallel workers (-1 = all CPUs).

• compute_supervised (bool) – Run supervised classification (requires scikit-learn).

• save_results (bool) – Save CSV + JSON + plots to OUTPUT_DIR.

Returns:

The evaluator instance (call .plot() for figures).

Return type:

NormalizationEvaluator

static available_methods()

Return sorted list of available normalization method names.

Return type:

List[str]

class mioXpektron.PeakAlignIntensityArea(mz_tolerance=0.2, mz_rounding_precision=1, min_intensity=1, min_snr=3, min_distance=2, peak_height=50, prominence=10, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, noise_model='global', noise_bins=20, noise_min_points=25, method=None, deconvolution_min_bic_delta=10.0, deconvolution_overlap_factor=0.75, deconvolution_replace_singles=True, output_dir=None, verbose=False, group_patterns=None, group_fn=None)

Bases: object

Process normalized ToF-SIMS spectra from CSV files, detect peaks, align them across samples, and calculate both intensity and area tables for each aligned m/z value.

Parameters:

• mz_tolerance (float, optional (default=0.2)) – Maximum distance (in m/z units) for clustering peaks across samples.

• mz_rounding_precision (int, optional (default=1)) – Number of decimal places for rounding aligned m/z values in output tables.

• min_intensity (float, optional (default=1)) – Minimum intensity threshold for considering data points.

• min_snr (float, optional (default=3)) – Minimum signal-to-noise ratio for peak detection.

• min_distance (int, optional (default=2)) – Minimum distance (in data points) between peaks.

• peak_height (float, optional (default=50)) – Minimum peak height for initial peak detection.

• prominence (float, optional (default=10)) – Minimum prominence for peak detection.

• min_peak_width (int, optional (default=1)) – Minimum peak width (in data points).

• max_peak_width (int, optional (default=75)) – Maximum peak width (in data points).

• width_rel_height (float, optional (default=0.5)) – Relative height for peak width calculation (0.5 = FWHM).

• noise_model ({"global", "mz_binned"}, optional (default="global")) – Noise model used for threshold estimation.

• noise_bins (int, optional (default=20)) – Number of m/z bins when using noise_model="mz_binned".

• noise_min_points (int, optional (default=25)) – Minimum positive noise points per bin for the local model.

• method (str or None, optional (default=None)) – Peak-detection / fitting method. None uses simple local-max detection (detect_peaks_with_area_v2), 'cwt' uses CWT detection, and 'Gaussian' / 'Lorentzian' / 'Voigt' use curve-fit detection via robust_peak_detection.

• deconvolution_min_bic_delta (float, optional (default=10.0)) – Minimum BIC improvement required before accepting a two-Gaussian deconvolution over a single-peak fit.

• deconvolution_overlap_factor (float, optional (default=0.75)) – Scale factor applied to the mean measured peak width when deriving the adaptive deconvolution spacing gate.

• deconvolution_replace_singles (bool, optional (default=True)) – If True, replace overlapping single-peak fits with the accepted deconvoluted components in the output table.

• output_dir (str or None, optional) – Directory to save output CSV files. If None, files are not saved.

• verbose (bool, optional (default=False)) – If True, print progress information.

Examples

>>> from mioXpektron.detection import PeakAlignIntensityArea
>>> import glob
>>>
>>> # Get all normalized spectra
>>> csv_files = glob.glob('output_files/normalized_spectra/*.csv')
>>>
>>> # Create analyzer instance
>>> analyzer = PeakAlignIntensityArea(
...     mz_tolerance=0.1,
...     min_snr=3,
...     output_dir='output_files/peak_analysis'
... )
>>>
>>> # Process with m/z cutoff
>>> intensity_table, area_table, peaks_df = analyzer.run(
...     csv_files,
...     mz_min=50,
...     mz_max=500
... )
>>>
>>> print(f"Detected {len(peaks_df)} peaks across {len(csv_files)} samples")
>>> print(f"Aligned to {intensity_table.shape[1]} unique m/z values")

__init__(mz_tolerance=0.2, mz_rounding_precision=1, min_intensity=1, min_snr=3, min_distance=2, peak_height=50, prominence=10, min_peak_width=1, max_peak_width=75, width_rel_height=0.5, noise_model='global', noise_bins=20, noise_min_points=25, method=None, deconvolution_min_bic_delta=10.0, deconvolution_overlap_factor=0.75, deconvolution_replace_singles=True, output_dir=None, verbose=False, group_patterns=None, group_fn=None)

Initialize the PeakAlignIntensityArea analyzer with default parameters.

run(csv_files, mz_min=None, mz_max=None)

Process CSV files and perform peak detection, alignment, and quantification.

Parameters:

• csv_files (list of str) – List of paths to normalized spectrum CSV files. Each CSV should have columns: ‘channel’, ‘mz’, ‘intensity’

• mz_min (float or None, optional) – Minimum m/z value to consider for peak detection. If None, use full range.

• mz_max (float or None, optional) – Maximum m/z value to consider for peak detection. If None, use full range.

Returns:

• intensity_table (pd.DataFrame) – DataFrame with samples as rows and aligned m/z values as columns, containing peak intensities (amplitudes). Missing peaks are filled with 0.

• area_table (pd.DataFrame) – DataFrame with samples as rows and aligned m/z values as columns, containing peak areas. Missing peaks are filled with 0.

• peaks_df (pd.DataFrame) – DataFrame containing all detected peaks with their properties before alignment.

mioXpektron.auto_tune_calib_config(files, reference_masses, *, base_config=None, sample_n=10)

Build a FlexibleCalibConfig with data-driven parameters.

Starts from base_config (or the default) and replaces tolerance, screening values, and breakpoints with adaptive estimates. The caller can further override any field afterwards.

Returns a FlexibleCalibConfig instance.

Parameters:

• files (Sequence[str])

• reference_masses (Sequence[float])

• sample_n (int)

mioXpektron.estimate_autodetect_tolerance(files, reference_masses, *, sample_n=10, quantile=0.9)

Estimate autodetect_tol_da from observed peak widths near calibrant m/z values.

Reads a sample of spectra, measures the FWHM of the strongest peak within +/-1 Da of each reference mass, and returns a tolerance equal to quantile of those widths (clamped to [0.05, 2.0] Da).

Parameters:

• files (Sequence[str])

• reference_masses (Sequence[float])

• sample_n (int)

• quantile (float)

Return type:

float

mioXpektron.estimate_bootstrap_heuristics(files, *, sample_n=10)

Derive adaptive bootstrap peak-matching constants from observed channel statistics (noise, spacing, range).

Returns a dict whose keys match the _BOOTSTRAP_* constant names in _models.py (without the leading underscore).

Parameters:

• files (Sequence[str])

• sample_n (int)

Return type:

Dict[str, float]

mioXpektron.estimate_denoise_params(files, *, sample_n=5)

Estimate hf_cutoff_frac and max_peaks for the denoise selection evaluator from pilot spectra.

Returns a dict of keyword overrides for compare_denoising_methods.

Parameters:

• files (Sequence[str])

• sample_n (int)

Return type:

Dict[str, object]

mioXpektron.estimate_flat_params(files, *, sample_n=10)

Estimate savgol_window and quantile thresholds for FlatParams from the data.

Returns a dict of keyword overrides suitable for dataclasses.replace(FlatParams(), **result).

Parameters:

• files (Sequence[str])

• sample_n (int)

Return type:

Dict[str, object]

mioXpektron.estimate_multisegment_breakpoints(reference_masses, n_segments=3)

Place segment breakpoints at quantile boundaries of the reference mass range so each segment contains roughly equal calibrant counts.

Parameters:

• reference_masses (Sequence[float])

• n_segments (int)

Return type:

List[float]

mioXpektron.estimate_mz_tolerance(files, *, sample_n=10, multiplier=3.0)

Estimate mz_tolerance from observed median m/z spacing, scaled by multiplier. Clamped to [0.01, 1.0].

Parameters:

• files (Sequence[str])

• sample_n (int)

• multiplier (float)

Return type:

float

mioXpektron.estimate_normalization_target(files, *, sample_n=20, mz_min=None, mz_max=None)

Estimate normalization_target as the median raw TIC across a sample of spectra. Falls back to 1e6 on failure.

Parameters:

• files (Sequence[str])

• sample_n (int)

• mz_min (float | None)

• mz_max (float | None)

Return type:

float

mioXpektron.estimate_outlier_threshold(residuals, *, target_false_rejection_rate=0.01, bounds=(2.0, 5.0))

Derive outlier_threshold from observed residual spread.

Uses the empirical quantile corresponding to 1 - target_false_rejection_rate of absolute z-scores (MAD-scaled), clamped to bounds.

Parameters:

• residuals (ndarray[tuple[Any, ...], dtype[float64]])

• target_false_rejection_rate (float)

• bounds (Tuple[float, float])

Return type:

float

mioXpektron.estimate_screening_thresholds(stability_df, *, ppm_quantile=0.85, valid_frac_quantile=0.2)

Derive screen_max_mean_abs_ppm and screen_min_valid_fraction from a reference-mass stability table (output of summarize_reference_mass_stability).

Returns a dict with keys screen_max_mean_abs_ppm and screen_min_valid_fraction.

Parameters:

• stability_df (DataFrame)

• ppm_quantile (float)

• valid_frac_quantile (float)

Return type:

Dict[str, float]