Mass Calibration#

Mass calibration maps optical interferometric contrast to molecular mass (kDa). The calibration is typically obtained by measuring a reference standard containing proteins of known molecular weight (e.g., MassFerenceP1, BSA, or Urease) under identical optical and buffer conditions.

Calibration Conventions#

Note

massphoto vs. DiscoverMP Calibration Conventions

In commercial software (Refeyn DiscoverMP), linear calibrations are commonly expressed as:

\[\text{contrast} = \text{slope} \cdot \text{mass (kDa)} + \text{offset}\]

In massphoto, the polynomial maps contrast directly to mass:

\[\text{mass (kDa)} = c_0 + c_1 \cdot \text{contrast}\]

where \(c_0\) is the intercept (kDa) and \(c_1\) is the slope (kDa / contrast unit). To convert parameters from DiscoverMP:

\[c_1 = \frac{1}{\text{slope}}, \quad c_0 = -\frac{\text{offset}}{\text{slope}}\]

When using fit(), you can specify direction="contrast_to_mass" (default) or direction="mass_to_contrast" to match the desired convention.

For experimental protocols on preparing calibration standards and selecting protein reference peaks, see Kratochvíl et al., Nature Protocols (2025).

Module Reference#

Mass calibration utilities.

This module provides functions to fit and apply polynomial mass calibration between image contrast and mass (kDa), manage calibration coefficients stored in defaults, and validate or invert first-order polynomials.

The calibration function maps contrast to mass, e.g. a first-order polynomial (linear) function of the form:

mass_kDa = coeffs[0] + coeffs[1] * contrast

This is different from the DiscoverMP convention which uses:

contrast = slope * mass_kDa + offset

To convert between the two conventions, the parameter direction can be used to indicate the direction of the calibration.

massphoto.mass_calibration.apply(event_list, mass_calibration=None)[source]#

Apply mass calibration to fit results.

When event_list is an DataFrame (EventList), the masses_kDa column is created or overwritten. If no calibration is available (argument and defaults are None), the input is returned unchanged and a log message is emitted.

Parameters:

  • event_list (EventList | np.ndarray) – EventList containing a contrasts column, or a 1D array of contrast values.

  • mass_calibration (Callable[[np.ndarray], np.ndarray] | Sequence[float] | None) – Callable that maps contrast values to mass (kDa), or polynomial coefficients in Polynomial order (increasing), or None to read from massphoto.defaults.

Returns:

Updated EventList, or an array of masses.

Return type:

EventList | np.ndarray

See also

get_calibration, fit

massphoto.mass_calibration.get_calibration(mass_calibration=None, direction='contrast_to_mass', allow_none=False)[source]#

Return a callable mass calibration (contrast -> mass) or its inverse.

Sequences of coefficients are converted to a np.polynomial.Polynomial (callable). If a callable is provided and direction is ‘contrast_to_mass’, it is returned as-is. If direction is ‘mass_to_contrast’ and a non-polynomial callable is given, a ValueError is raised because inversion is ambiguous for arbitrary callables.

Parameters:

  • mass_calibration (Callable[[np.ndarray], np.ndarray] | Sequence[float] | np.polynomial.Polynomial | None) – Callable mapping contrast to mass, or sequence of polynomial coefficients in increasing order (index i is coefficient for x^i), or a Polynomial. If None, the calibration is read from defaults.mass_calibration.

  • direction (str) – ‘contrast_to_mass’ or ‘mass_to_contrast’. When requesting ‘mass_to_contrast’ the returned callable maps mass -> contrast.

  • allow_none (bool, default=False) – If True, return None when no calibration is available (both argument and defaults are None), instead of raising.

Returns:

Callable implementing the requested mapping, or None if allow_none=True and no calibration is available.

Return type:

Callable[[np.ndarray], np.ndarray] | None

massphoto.mass_calibration.get_coefficients(mass_calibration=None, direction='contrast_to_mass')[source]#

Return the raw coefficients of the mass calibration.

Always returns a sequence of coefficients (in increasing order). If a Polynomial is provided it is converted to a coefficient sequence. If direction == ‘mass_to_contrast’, the returned coefficients are inverted so they represent the requested mapping.

Parameters:

  • mass_calibration (Sequence[float] | np.polynomial.Polynomial | None) – Sequence of polynomial coefficients in increasing order or a Polynomial. If None, defaults.mass_calibration is used.

  • direction (str) – ‘contrast_to_mass’ or ‘mass_to_contrast’.

Returns:

Coefficients (in increasing order) representing the requested mapping.

Return type:

Sequence[float]

massphoto.mass_calibration.set_coefficients(coeffs, direction='contrast_to_mass', check=True)[source]#

Set the coefficients of the mass calibration function in defaults.

Parameters:

  • coeffs (Sequence[float] | np.polynomial.Polynomial) – Polynomial coefficients in Polynomial order (increasing), or a Polynomial instance.

  • direction (str) – Direction of the calibration. One of ‘contrast_to_mass’ or ‘mass_to_contrast’.

  • check (bool)

Return type:

None

massphoto.mass_calibration.check_coefficients(coeffs, direction='contrast_to_mass')[source]#

Check that the coefficients of the mass calibration function are valid.

Parameters:

  • coeffs (Sequence[float] | np.polynomial.Polynomial) – Polynomial coefficients in Polynomial order (increasing), or a Polynomial instance.

  • direction (str)

Return type:

None

massphoto.mass_calibration.fit(contrasts, masses_kDa, *, degree=1, update_defaults=False, direction='contrast_to_mass', input_unit='contrast', reference_calibration=None)[source]#

Fit a mass calibration polynomial to given contrasts and masses.

Parameters:

  • contrasts (np.ndarray | Sequence[float] | pd.DataFrame | FitResult-like) –

    Peak-position values used as calibration input. Supported inputs are:

    • 1D array-like values (contrast by default)

    • a DataFrame with a mu column (e.g. fitres.peaks)

    • an object with a peaks DataFrame containing mu (e.g. FitResult)

    When a DataFrame or FitResult-like object is provided, peak positions are extracted from mu and sorted ascending before fitting.

  • masses_kDa (np.ndarray) – Array of mass values in kDa.

  • degree (int | list[int]) – Maximum degree of the polynomial to fit. Provide a list of integers to specify the degrees of the terms to include, e.g. [1,] for linear without offset. Default is 1 (=[0,1] linear fit with offset).

  • update_defaults (bool) – If True, store the fitted calibration in massphoto.defaults.

  • direction (str) – Fit either 'contrast_to_mass' (default) or 'mass_to_contrast'. The returned polynomial always represents the fitted direction.

  • input_unit (str) – Unit of contrasts. One of 'contrast', 'mass', or 'auto'. If 'mass', values are converted to contrast via inversion of an existing calibration before fitting. If 'auto', values are interpreted as mass when the median absolute value is greater than 1, otherwise as contrast.

  • reference_calibration (Callable[[np.ndarray], np.ndarray] | Sequence[float] | np.polynomial.Polynomial | None) – Calibration to invert when input_unit resolves to 'mass'. If None, massphoto.defaults.mass_calibration is used. Inversion requires an invertible first-order polynomial calibration.

Returns:

Fitted calibration polynomial.

Return type:

np.polynomial.Polynomial