mioXpektron.adaptive

Adaptive parameterization helpers for the mioXpektron pipeline.

Each estimator derives a value from data that would otherwise be a fixed constant. All functions are pure (no mutation of global state) and return plain Python / NumPy values that callers feed into the existing config dataclasses.

Usage is opt-in: every config keeps its current defaults; the new auto_tune=True flag triggers adaptive estimation.

Functions

auto_tune_calib_config(files, ...[, ...])	Build a FlexibleCalibConfig with data-driven parameters.
estimate_autodetect_tolerance(files, ...[, ...])	Estimate autodetect_tol_da from observed peak widths near calibrant m/z values.
estimate_bootstrap_heuristics(files, *[, ...])	Derive adaptive bootstrap peak-matching constants from observed channel statistics (noise, spacing, range).
estimate_denoise_params(files, *[, sample_n])	Estimate hf_cutoff_frac and max_peaks for the denoise selection evaluator from pilot spectra.
estimate_flat_params(files, *[, sample_n])	Estimate savgol_window and quantile thresholds for FlatParams from the data.
estimate_multisegment_breakpoints(...[, ...])	Place segment breakpoints at quantile boundaries of the reference mass range so each segment contains roughly equal calibrant counts.
estimate_mz_tolerance(files, *[, sample_n, ...])	Estimate mz_tolerance from observed median m/z spacing, scaled by multiplier.
estimate_normalization_target(files, *[, ...])	Estimate normalization_target as the median raw TIC across a sample of spectra.
estimate_outlier_threshold(residuals, *[, ...])	Derive outlier_threshold from observed residual spread.
estimate_screening_thresholds(stability_df, *)	Derive screen_max_mean_abs_ppm and screen_min_valid_fraction from a reference-mass stability table (output of summarize_reference_mass_stability).

mioXpektron.adaptive.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.adaptive.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.adaptive.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]

mioXpektron.adaptive.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.adaptive.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.adaptive.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.adaptive.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.adaptive.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.adaptive.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.adaptive.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)