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:
molecule (networkx.Graph) – Molecule to modify in-place.
threshold (float) – The distance threshold under which edges will be created. The distance is expressed in nm.
selection_a (collections.abc.Iterable[collections.abc.Hashable]) – List of node keys from the molecule.
selection_b (collections.abc.Iterable[collections.abc.Hashable]) – List of node keys from the molecule.
attribute (collections.abc.Hashable) – Name of the key in the node dictionaries under which the coordinates are stored.
- 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:
- 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))
where1
and2
are indices of molecules in molecules,10
is the key of a node frommolecules[0]
, and20
is the key of a node frommolecules[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:
molecules (collections.abc.Sequence[vermouth.molecule.Molecule]) – List of molecules to link.
edges (collections.abc.Iterable[tuple[int, collections.abc.Hashable]]) – List of edges in a
(molecule_index, node_key)
format as described above. Edges can have a third element, it is then a dictionary of attributes to be attached to the edge.
- Returns:
New list of molecules.
- Return type:
- 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:
molecules (collections.abc.Collection[vermouth.molecule.Molecule]) – A list of
vermouth.molecule.Molecule
.threshold (float) – A distance threshold in nm. Pairs are return if the nodes are closer than this threshold.
selection_a (collections.abc.Iterable[collections.abc.Hashable]) – List of nodes to consider at one end of the pairs. The format is described above.
selection_b (collections.abc.Iterable[collections.abc.Hashable]) – List of nodes to consider at the other end of the pairs. The format is described above.
attribute (collections.abc.Hashable) – The dictionary key under which the node positions are stored in the nodes.
min_edges (int) – Do not select pairs that are connected by less than that number of edges.
- 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:
molecule (networkx.Graph) – Molecule to prune in-place.
selection_a (collections.abc.Iterable[collections.abc.Hashable]) – List of node keys from the molecule.
selection_b (collections.abc.Iterable[collections.abc.Hashable]) – List of node keys from the molecule.
See also
- 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:
molecule (networkx.Graph) – Molecule to prune in-place.
selector_a (collections.abc.Callable) – A selector for one end of the edges.
selector_b (collections.abc.Callable) – A selector for the second end of the edges. If set to
None
, then ‘selector_a’ is used for both ends.
See also
- 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:
molecule (collections.abc.Iterable[Molecule]) – A list of molecules.
selector (collections.abc.Callable) – A selector function.
- Yields:
tuple[int, collections.abc.Hashable] – Molecule/key identifier for the selected nodes.