calibration

The calibration module provides functionality to calibrate measured quantities like mass-to-charge ratios, retention times, and ion mobilities.

Calibration estimator module.

Thin Python wrapper around the Rust calibration estimator (alphadia_search_rs.CalibrationEstimator). The numeric algorithm (LOESS fit, prediction, deviation transform, metrics) lives in Rust; this wrapper only pulls the relevant columns out of a dataframe, passes them as arrays, and keeps the plotting on the Python side.

class alphadia.calibration.estimator.CalibrationEstimator(name: str, n_kernels: int, transform_deviation: float | None, input_column: str, target_column: str, output_column: str)

Bases: object

A single estimator for a property (e.g. mz, rt, or mobility).

Calibration models the deviation of an input value (e.g. mz_library) from an observed property (e.g. mz_observed). Once fitted, calibrated values (e.g. mz_calibrated) are predicted from the input values. The numeric LOESS model lives in the Rust backend; its two configuration values (n_kernels and the deviation transform) are passed in from here.

__init__(name: str, n_kernels: int, transform_deviation: float | None, input_column: str, target_column: str, output_column: str)

Initialize the estimator.

Parameters:

• name (str) – Name of the estimator for logging and plotting e.g. ‘mz’.

• n_kernels (int) – Number of LOESS kernels used by the underlying model.

• transform_deviation (float | None) – If set, the deviation is expressed as a fraction of the input value (e.g. 1e6 for ppm). If None, the deviation is absolute.

• input_column (str) – Column used as input for the estimator e.g. ‘mz_library’.

• target_column (str) – Column used as target for the estimator e.g. ‘mz_observed’.

• output_column (str) – Column the calibrated prediction is written to e.g. ‘mz_calibrated’.

calc_deviation(df: DataFrame) → ndarray

Calculate the observed, calibrated and residual deviations.

Parameters:

df (pd.DataFrame) – Dataframe containing the input and target columns.

Returns:

Array of shape (n_samples, 4) with columns [observed deviation, calibrated deviation, residual deviation, input].

Return type:

np.ndarray

ci(df: DataFrame, ci: float = 0.95) → float

Calculate the residual deviation at the given confidence interval.

Parameters:

• df (pandas.DataFrame) – Dataframe containing the input and target columns.

• ci (float, default=0.95) – confidence interval.

Returns:

the confidence interval of the residual deviation after calibration.

Return type:

float

fit(df: DataFrame, *, plot: bool = True, figure_path: str | None = None) → None

Fit the estimator based on the input and target columns of the dataframe.

Parameters:

• df (pd.DataFrame) – Dataframe containing the input and target columns.

• plot (bool, default=True) – If True, a plot of the calibration is generated.

• figure_path (str, default=None) – If not None, the plot is saved to the given path.

property input_column: str

Column used as input for the estimator e.g. ‘mz_library’.

predict(df: DataFrame, *, inplace: bool = True) → ndarray | None

Predict calibrated values based on the input column of the dataframe.

Parameters:

• df (pd.DataFrame) – Dataframe containing the input column.

• inplace (bool, default=True) – If True, the prediction is added as the output column of the dataframe.

Returns:

Array of predictions, or None if written inplace / not fitted.

Return type:

np.ndarray | None

class alphadia.calibration.estimator.CalibrationMetrics(median_bias: float, median_variance: float)

Bases: object

Fitted calibration quality metrics for a single estimator.

median_bias

Median absolute calibrated deviation (systematic bias after calibration).

Type:

float

median_variance

Median absolute residual deviation (spread after calibration).

Type:

float

__init__(median_bias: float, median_variance: float) → None

median_bias: float

median_variance: float