vermouth.edge_tuning module

Set of tools to add and remove edges.

vermouth.edge_tuning.add_edges_at_distance(molecule, threshold, selection_a, selection_b, attribute='position')[source]

Add edges within a molecule when the distance is below a threshold.

Create edges within a molecule between nodes that have an end part of ‘selection_a’, the other end part of ‘selection_b’, and a distance between the ends that is lesser than the given threshold.

All nodes that are part of ‘selection_a’ or ‘selection_b’ must have a position stored under the attribute which key is given with the ‘attribute’ argument. That key is ‘position’ by default. If at least one node has the position missing, then a KeyError is raised.

Parameters:
Raises:

KeyError – At least one node from the selections does not have a position.

vermouth.edge_tuning.add_edges_threshold(molecules, threshold, templates_a, templates_b, attribute='position', min_edges=0)[source]

Add edges between two selections when under a given threshold.

Edges are added within and between the molecules and connect nodes that match the given template. Molecules that get connected by an edge are merged and the new list of molecules is returned.

Parameters:

  • molecules (collections.abc.Sequence[Molecule]) – A list of molecules.

  • threshold (float) – The distance threshold in nanometers under which an edge is created.

  • templates_a (dict) – A list of templates; a node need to match at least one of them to be selected at one end.

  • templates_b (dict) – A list of templates; a node need to match at least one of them to be selected at the other end.

  • attribute (str) – Name of the key in the node dictionaries under which the coordinates are stored.

  • min_edges (int) – Minimum number of edges between to nodes for an edge to be added.

Returns:

A new list of molecules.

Return type:

list[vermouth.molecule.Molecule]

vermouth.edge_tuning.add_inter_molecule_edges(molecules, edges)[source]

Create edges between molecules.

The function is given a list of molecules and a list of edges. Each edge is provided as a tuple of two nodes, each node being a tuple of the molecule index in the list of molecule, and the node key in that molecule. An edge therefore looks like ((0, 10), (2, 20)) where 1 and 2 are indices of molecules in molecules, 10 is the key of a node from molecules[0], and 20 is the key of a node from molecules[2].

The function can create edges within a molecule if the same molecule index is given for both ends of edges.

Molecules that get linked are merged. In a merged molecule, the order of the input molecules is kept. In a list of molecules numbered from 0 to 4, if molecules 1, 2, and 4 are merged, then the result molecules are, in order, 0, 1-2-4, 3.

Parameters:
Returns:

New list of molecules.

Return type:

list

vermouth.edge_tuning.pairs_under_threshold(molecules, threshold, selection_a, selection_b, attribute='position', min_edges=0)[source]

List pairs of nodes from a selection that are closer than a threshold.

Get the distance between nodes from multiple molecules and list the pairs that are closer than the given threshold. The molecules are given as a list of molecules, the selection is a list of nodes each of them a tuple (index of the molecule in the list, key of the node in the molecule). The result of the function is a generator of node pairs followed by the distance between the nodes, each node formated as in the selection.

All nodes from the selection must have a position accessible under the key given as the ‘attribute’ argument. That key is ‘position’ by default.

With the min_edges argument, one can prevent pairs to be selected if there is a path between two nodes that is shorter than a given number of edges.

Parameters:
Yields:

tuple[collections.abc.Hashable, collections.abc.Hashable, float] – Pairs of node closer than the threshold in the format described above and the distance between the nodes.

Raises:

KeyError – Raised if a node from the selection does not have a position.

Notes

Symetric node pairs are not deduplicated.

vermouth.edge_tuning.prune_edges_between_selections(molecule, selection_a, selection_b)[source]

Remove edges which have their ends part of given selections.

An edge is removed if has one end that is part of ‘selection_a’, and the other end part of ‘selection_b’.

Parameters:

See also

prune_edges_with_selectors

vermouth.edge_tuning.prune_edges_with_selectors(molecule, selector_a, selector_b=None)[source]

Remove edges with the ends between selections defined by selectors.

An edge is removed if one of its end is part of the selection defined by ‘selector_a’, and its other end is part of the selection defined by ‘selector_b’. A selector is a function that accept a node dictionary as argument and returns True if the node is part of the selection.

The ‘selection_b’ argment is optional. If it is None, then ‘selector_a’ is used for the selection at both ends.

Parameters:

See also

prune_edges_between_selections

vermouth.edge_tuning.select_nodes_multi(molecules, selector)[source]

Find the nodes that correspond to a selector among multiple molecules.

Runs a selector over multiple molecules. The selector must be a function that takes a node dictionary as argument and returns True if the node should be selected. The selection is yielded as tuples of a molecule indice from the molecule list input, and a key from the molecule.

Parameters:
Yields:

tuple[int, collections.abc.Hashable] – Molecule/key identifier for the selected nodes.