FEMap

class cinnabar.femap.FEMap

Free Energy map of both simulations and bench measurements

Contains a set (non-duplicate entries) of different measurements.

Examples

To construct a FEMap by hand:

>>> # Load/create experimental results
>>> from openff.units import unit
>>> kJpm = unit.kilojoule_per_mole
>>> g = ReferenceState()
>>> experimental_result1 = Measurement(labelA=g, labelB="CAT-13a", DG=-8.83 * kJpm, uncertainty=0.10 * kJpm,
...                                    computational=False)
>>> experimental_result2 = Measurement(labelA=g, labelB="CAT-17g", DG=-9.73 * kJpm, uncertainty=0.10 * kJpm,
...                                    computational=False)
>>> # Load/create calculated results
>>> calculated_result = Measurement(labelA="CAT-13a", labelB="CAT-17g", DG=0.36 * kJpm,
...                                 uncertainty=0.11 * kJpm, computational=True)
>>> # Incrementally created FEMap
>>> fe = FEMap()
>>> fe.add_measurement(experimental_result1)
>>> fe.add_measurement(experimental_result2)
>>> fe.add_measurement(calculated_result)

To read from a legacy csv file specifically formatted for this, you can use:

>>> fe = FEMap.from_csv('../data/example.csv')

Methods

add_absolute_calculation	Add a single ABFE calculation
add_experimental_measurement	Add a single experimental measurement
add_measurement	Add new observation to FEMap, modifies the FEMap in-place
add_relative_calculation	Add a single RBFE calculation
check_weakly_connected	Checks if all results in the graph are reachable from other results
draw_graph
from_csv	Construct from legacy csv format
from_networkx	Create FEMap from network representation
generate_absolute_values	Populate the FEMap with absolute computational values based on MLE
get_absolute_dataframe	Get a dataframe of all absolute results
get_relative_dataframe	Gets a dataframe of all relative results
to_legacy_graph	Produce single graph version of this FEMap
to_networkx	A copy of the FEMap as a networkx Graph

Attributes

degree	Average degree of computational nodes
ligands	All ligands in the graph
n_edges	Number of computational edges
n_ligands	Total number of unique ligands
n_measurements	Total number of both experimental and computational measurements

add_absolute_calculation(label, value: ~pint.util.Quantity, uncertainty: ~pint.util.Quantity, *, source: str = '', temperature=<Quantity(298.15, 'kelvin')>)

Add a single ABFE calculation

Parameters:

• label – the ligand being measured

• value (openff.units.Quantity) – the measured value, as kcal/mol, or kJ/mol.

• uncertainty (openff.units.Quantity) – the uncertainty in the measurement

• source (str, optional) – an identifier for the source of the data

• temperature (openff.units.Quantity, optional) – the temperature the measurement was taken at, defaults to 298.15 K

add_experimental_measurement(label: str | ~typing.Hashable, value: ~pint.util.Quantity, uncertainty: ~pint.util.Quantity, *, source: str = '', temperature=<Quantity(298.15, 'kelvin')>)

Add a single experimental measurement

Parameters:

• label – the ligand being measured

• value (openff.units.Quantity) – the measured value, as either Ki, IC50, kcal/mol, or kJ/mol. The type of input is determined by the units of the input.

• uncertainty (openff.units.Quantity) – the uncertainty in the measurement

• source (str, optional) – an identifier for the source of the data

• temperature (openff.units.Quantity, optional) – the temperature the measurement was taken at, defaults to 298.15 K

add_measurement(measurement: Measurement)

Add new observation to FEMap, modifies the FEMap in-place

Any other attributes on the measurement are used as annotations

:raises ValueError : if bad type given:

add_relative_calculation(labelA: str | ~typing.Hashable, labelB: str | ~typing.Hashable, value: ~pint.util.Quantity, uncertainty: ~pint.util.Quantity, *, source: str = '', temperature=<Quantity(298.15, 'kelvin')>)

Add a single RBFE calculation

Parameters:

• labelA, labelB – the ligands being measured. The measurement is taken from ligandA to ligandB, i.e. ligandA is the “old” or lambda=0.0 state, and ligandB is the “new” or lambda=1.0 state.

• value (openff.units.Quantity) – the measured DDG value, as kcal/mol, or kJ/mol.

• uncertainty (openff.units.Quantity) – the uncertainty in the measurement

• source (str, optional) – an identifier for the source of the data

• temperature (openff.units.Quantity, optional) – the temperature the measurement was taken at, defaults to 298.15 K

check_weakly_connected() → bool

Checks if all results in the graph are reachable from other results

property degree: float

Average degree of computational nodes

classmethod from_csv(filename, units: Quantity | None = None)

Construct from legacy csv format

classmethod from_networkx(graph: MultiDiGraph)

Create FEMap from network representation

Note

Currently absolutely no validation of the input is done.

generate_absolute_values()

Populate the FEMap with absolute computational values based on MLE

get_absolute_dataframe() → DataFrame

Get a dataframe of all absolute results

The dataframe will have the following columns: - label - DG - uncertainty - source - computational

get_relative_dataframe() → DataFrame

Gets a dataframe of all relative results

The pandas DataFrame will have the following columns: - labelA - labelB - DDG - uncertainty - source - computational

property ligands: list

All ligands in the graph

property n_edges: int

Number of computational edges

property n_ligands: int

Total number of unique ligands

property n_measurements: int

Total number of both experimental and computational measurements

to_legacy_graph() → DiGraph

Produce single graph version of this FEMap

This graph will feature: - experimental DDG values calculated as the difference between experimental DG values - calculated DG values calculated via mle

This matches the legacy format of this object, notably: - drops multi edge capability - removes units from values

to_networkx() → MultiDiGraph

A copy of the FEMap as a networkx Graph

The FEMap is represented as a multi-edged directional graph

Edges have the following attributes:

• DG: the free energy difference of going from the first edge label to the second edge label

• uncertainty: uncertainty of the DG value

• temperature: the temperature at which DG was measured

• computational: boolean label of the original source of the data

• source: a string describing the source of data.

Note

All edges appear twice, once with the attribute source=’reverse’, and the DG value flipped. This allows “pathfinding” like approaches, where the DG values will be correctly summed.