convert_observable

cinnabar.conversion.convert_observable(value: ~pint.Quantity, original_type: ~typing.Literal['dg', 'ki', 'ic50', 'pic50'], final_type: ~typing.Literal['dg', 'ki', 'ic50', 'pic50'], uncertainty: ~pint.Quantity | None = None, temperature: ~pint.Quantity = <Quantity(298.15, 'kelvin')>) → tuple[Quantity, Quantity | None]

Converts an affinity value into another derived quantity, including automatic error propagation if error is provided.

Parameters:

• value (openff.units.Quantity) – Numerical value of the original observable with units.

• original_type (str) – Code for the original observable. Can be dg, ki, ic50, pic50.

• final_type (str) – Code for the desired derived quantity. Can be dg, ki, ic50, pic50.

• uncertainty (openff.units.Quantity, default None) – The uncertainty/error in the original observable with units, should always be positive.

• temperature (openff.units.Quantity, default 298.15 * unit.kelvin) – Temperature in kelvin for conversions involving dG.

Notes

• The function uses the molar gas constant (R) and the provided temperature to perform conversions involving dG.

• If the original value is below a threshold (e.g., 1e-15 M for Ki/IC50), the function will return a default value to avoid numerical issues.

• The function rounds the converted value and uncertainty to 2 decimal places if the type changes to reflect the typical precision of such measurements.

• The following default units are used for the output based on the final_type:

  • dg: kilocalories per mole

  • ki: nanomolar

  • ic50: nanomolar

  • pic50: unitless (logarithmic scale)

Returns:

• converted_value (openff.units.Quantity) – The converted value in the desired units.

• converted_error (openff.units.Quantity or None) – The propagated error in the converted value, or None if no error was provided.

Examples

>>> from openff.units import unit
>>> from cinnabar.conversion import convert_observable
>>> value = -10.0 * unit("kilocalories / mole")
>>> uncertainty = 0.1 * unit("kilocalories / mole")
>>> convert_observable(value, "dg", "pic50", uncertainty)
(7.33, 0.07)
>>> convert_observable(value, "dg", "ki", uncertainty)
(46.77 nanomolar, 7.89 nanomolar)

Raises:

ValueError – If the original_type or final_type is not recognized or if the uncertainty is negative.