im2deep.calibration

CCS calibration utilities.

This module provides calibration strategies to map predicted CCS values to the aligned target scale.

class im2deep.calibration.Calibration(*args, **kwargs)[source]

Bases: ABC

Abstract base class for CCS calibration methods.

abstract property is_fitted: bool: Check if the calibration has been fitted.

abstractmethod fit(psm_df_target, psm_df_source)[source]

Fit the calibration using target and source CCS values.

Parameters:

psm_df_target (DataFrame)
psm_df_source (DataFrame)

Return type:

None

abstractmethod transform(psm_df)[source]

Transform source CCS into the calibrated target space.

Parameters:: psm_df (DataFrame)
Return type:: ndarray

class im2deep.calibration.LinearCCSCalibration(per_charge=True, use_charge_state=None)[source]

Bases: Calibration

Linear calibration for CCS predictions.

This class implements a simple linear calibration method for CCS predictions by applying shift factors calculated from overlapping peptides between calibration and reference datasets. Shift factor calculation can be performed globally or per charge state.

Parameters:

per_charge (bool, optional) – Whether to calculate shift factors per charge state. Default is True.
use_charge_state (int or None, optional) – Charge state to use for global shift calculation when per_charge is False. Default is 2 if not specified.

property is_fitted: bool: Check if the calibration has been fitted.

fit(psm_df_target, psm_df_source=None, multi=False)[source]

Fit the calibration using target and source CCS values.

Parameters:

psm_df_target (DataFrame)
psm_df_source (DataFrame | None)
multi (bool)

Return type:

None

transform(psm_df)[source]

Transform source CCS into the calibrated target space.

Parameters:: psm_df (DataFrame)
Return type:: ndarray

calculate_ccs_shift_global(target_df, source_df)[source]

Calculate a single global CCS shift factor.

Parameters:

target_df (DataFrame) – DataFrame containing peptidoforms and observed CCS values from the target PSMList.
source_df (DataFrame) – DataFrame containing peptidoforms and predicted CCS values from the source PSMList.

Returns:

Shift factors per charge state if per_charge is True, otherwise a single shift factor.

Return type:

dict[int, float] | float

Raises:

CalibrationError – If no overlapping peptides are found for shift calculation.

Notes

The function automatically filters out charges >6 as IM2Deep predictions are not reliable for higher charge states. A warning is logged if any peptides are filtered out.

calculate_ccs_shift_per_charge(target_df, source_df)[source]

Calculate CCS shift factors per charge state.

Parameters:

target_df (DataFrame) – DataFrame containing peptidoforms and observed CCS values from the target PSMList.
source_df (DataFrame) – DataFrame containing peptidoforms and predicted CCS values from the source PSMList.

Returns:

Shift factors per charge state.

Return type:

dict[int, float]

Raises:

CalibrationError – If no overlapping peptides are found for any charge state.

im2deep.calibration.get_default_reference(multi=False)[source]

Get the default reference DataFrame for calibration.

Parameters:: multi (bool) – Whether to use the multi-charge reference dataset.
Returns:: Default reference DataFrame with ‘peptidoform’ and ‘CCS’ columns.
Return type:: pd.DataFrame