restraintmaker.algorithm package

Submodules

restraintmaker.algorithm.Filter module

The module Filters contains functionality of filtering selections by criteria like in ring structure or element.

class restraintmaker.algorithm.Filter.ElementFilter(atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Filter._Filter

__init__(atoms: List[restraintmaker.utils.Utilities.Atom])

Filter for certain Element(s)

Parameters

atoms (t.List[u.Atom]) – List of atoms that are filtered over

filter() → List[restraintmaker.utils.Utilities.Atom]

Returns a filtered version of the class attribute atoms, filtered by the class attribute element

Returns

Filtered atom list

Return type

t.List[u.Atom]

get_args(input_function: typing.Callable = <function ElementFilter.<lambda>>)

get_args(…) Needs to be called, before filter() can be used.

For the Element_Filter it finds out which element should be filtered

Parameters

• input_function (function(str)) – A function that will find the input needed ofr the filter.

• message (str) – A string that is displayed if if input function needs to communicate with the user

Return type

NoReturn

class restraintmaker.algorithm.Filter.PropertyFilter(atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Filter._Filter

__init__(atoms: List[restraintmaker.utils.Utilities.Atom])

Filters by any attribute of atom

Parameters

atoms (t.List[u.Atom]) – List of atoms that are filtered over

filter() → List[restraintmaker.utils.Utilities.Atom]

Returns a list of atoms, filtered using the provided criterion and value

Returns

Filtered atom list

Return type

t.List[u.Atom]

get_args(input_function: Callable)

get_args(…) Needs to be called, before filter() can be used. For the Property_Filter it finds out which

property should be filter-criterion and then which value it should have.

Todo: think about multiple property selections

Parameters

• input_function (function(str)) – A function that will find the input needed ofr the filter.

• message (str) – A string that is displayed if if input function needs to communicate with the user

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

class restraintmaker.algorithm.Filter.RingFilter(atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Filter._Filter

__init__(atoms: List[restraintmaker.utils.Utilities.Atom])

Ring Filter chooses all Atoms that are part of a Ring Warnings: using tools_Rdkit. Needs conversion to tools_Rdkit molecules. => Needs the pdb as input

Parameters

• atoms (t.List[u.Atom]) – List of atoms to be

• args (t.List[str]) – Extra Arguments the subclasses might need

filter()

filter should be overridden by every subclass of _Filter. Returns a filtered List of atoms

In the case of Ring Filter: All atoms which are in rings

Returns

Filtered atom list

Return type

t.List[u.Atom]

get_args(input_function: Callable)

get_args(…) Needs to be called, before filter() can be used. It uses an input function to find all arguments required by a certain instance of a _Filter.

For RingFilter that is a List of all Molecules in the pdb format (CAREFULL: The Molecules need to contain ALL atoms in the Molecules, not just the selected one.)

TODO: What Kind of Error will I get if tools_Rdkit conversion fails?/ Catch it here

Parameters

• input_function (function(str)) – A function that can get the input

• message (str) – A string that is displayed if if input function needs to communicate with the user

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

restraintmaker.algorithm.Optimizer module

The optimizers of this package are contained in this module. The optimizers can be used too….

class restraintmaker.algorithm.Optimizer.BruteForceRingOptimzer(atoms)

Bases: restraintmaker.algorithm.Optimizer._MoleculeRingOptimizer

__init__(atoms)

A Molecule Ring Optimzier that connects TwoMolecules by finding Optimizing some criterion by brute force TODO: Think: Could we use a version of volume optimizer that does not do pairwise connections?

Parameters

atoms (t.List[u.Atom]) – list of atoms

connect_two_molecules(m1: List[restraintmaker.utils.Utilities.Atom], m2: List[restraintmaker.utils.Utilities.Atom], n) → List[restraintmaker.utils.Restraints._Restraint]

connect_two_molecules places n restraint between 2 molecules, using criteria depending on the Optimizer

Parameters

• m1 (t.List[u.Atom]) – Molecule 1

• m2 (t.List[u.Atom]) – Molecule 1

• n

Returns

Restraints between those atoms

Return type

t.List[RestraintType._RestraintType]

Raises

NotImplementedError – if _MoleculeRingOptimizer.connect_two_molecules is called directly.

get_args(input_function: Callable)

needs to be called by every Optimizer after its creation, t It uses an input function to find all arguments required by a certain instance of a _Filter

Parameters

input_function (t.Callable[str]) – A function that can get the input

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

class restraintmaker.algorithm.Optimizer.GreedyGraphOptimizer(atoms)

Bases: restraintmaker.algorithm.Optimizer._MoleculeRingOptimizer

__init__(atoms)

First the all Molecules pairs are connected. Then a ring is formed by using the best pairs. These restraints between two molecules are chosen heuristically by finding distance restraints that are as far apart as possilbe. (Non optimal solution)

TODO: Speed is far from optimal, because some of the taks done by the utility functions are redundant:

1. We do not need to construct the whole spanning tree. We could stop, after we have found best connections

2. The info about which atom belongs to which molecule is lost when we call get_all_short_connections(…), and get_all_short_connections checks it again

3. The info about connectiviy in the tree is lost when it is returned as a list as has to be tediouly reconstructed while walking the tree

Parameters

atoms (t.List[u.Atom]) – list of selected atoms

connect_two_molecules(m1: List[restraintmaker.utils.Utilities.Atom], m2: List[restraintmaker.utils.Utilities.Atom], n) → List[restraintmaker.utils.Restraints._Restraint]

For three heurstic Optimizer that is by greedly picking restraints according to a criterion depending on the already chosen restraints

Parameters

• m1 (t.List[u.Atom]) – Molecule 1

• m2 (t.List[u.Atom]) – Molecule 2

• n

Returns

Restraints between those atoms

Return type

t.List[RestraintType._RestraintType]

get_args(input_function: Callable)

needs to be called by every Optimizer after its creation, t It uses an input function to find all arguments required by a certain instance of a _Filter

Parameters

input_function (t.Callable[str]) – A function that can get the input

Returns

if the input function does not provide all arguments in the necessary format

Return type

BadArgumentException

class restraintmaker.algorithm.Optimizer.MetaMoleculeRingOptimizer(atoms)

Bases: restraintmaker.algorithm.Optimizer._MoleculeRingOptimizer

__init__(atoms)

Meta Optimizer which compares the solution of different Optimizers for each Molecule pair and picks the best

Warning: As implemented now, it can NOT be generalized to other Optimizer types than RingOptimizers. Warning: The complete solution of the BestMoleculesRingOPtimizer is NOT equal to any of the Optimizers it test. It will pick the best solution for each pair of molecules, leading to a different ring than any of the single Optimizers Warning: As Implemented now, it can not deal with future Molecule Ring Optimizers, which might have additional arguments

TODO GENERALIZE: 1) Allow to indicate which Optimizers to include, instead of hardcoding all of them

2. Allow to give the arguments for each single Optimizer, instead of using the same ones for each Optimizer(except of course criterion/update function.)

Would be perfect if we could pass Optimizers as arguments

connect_two_molecules(m1: List[restraintmaker.utils.Utilities.Atom], m2: List[restraintmaker.utils.Utilities.Atom], n)

Parameters

• m1

• m2

• n

get_args(input_function: Callable)

needs to be called by every Optimizer after its creation, t It uses an input function to find all arguments required by a certain instance of a _Filter

Parameters

input_function (t.Callable[str]) – A function that can get the input

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

restraintmaker.algorithm.Optimizer._calculate_value_convex_hull(restraint_pos: List[Tuple[float, float, float]]) → float

calculate the conves hull volume of a set of restraint cogs.

Parameters

restraint_pos

Returns

volume of the convex hull

Return type

float

restraintmaker.algorithm.Optimizer._calculate_value_scaled_pca_2d(restraint_pos)

Todo: to be removed # TODO: Scaling before pca is not really reasonable, because we do prefer a big relative variance in the biggest dimensions # TODO: Function returns a lot of stuff we do not need.

Parameters

restraint_pos

restraintmaker.algorithm.Optimizer._calculate_value_unscaled_pca_2d(restraint_pos) → float

Quantity to optimize is the 2d-volume of the PCA of the restraint positions

TODO: Test!!!!!! TODO: Think about other possibilities: 3d-volume / covariance / pca of all involved atoms instead of restraint

Parameters

restraint_pos

Returns

eigenvalue product -> in twoD, a square area of “deviation”

Return type

float

restraintmaker.algorithm.Optimizer.additional_ring_interconnections(molecule_pair_list: List[Tuple[int, int]], i_chosen_pairs: List[int], addditional_ringConnections: int = 0, _verbosity_level=5)

For a large number of end-states in one system it might be useful to add additional restraints. This algorithm adds restraints by the following approach:

Parameters

• molecule_pair_list (t.List[t.Tuple[int,int]]) – Molecule edge pairs

• i_chosen_pairs (t.List[int]) – A list of all already chosen molecule edge pairs

• addditional_ringConnections (int) – Number additional restrained molecule pairs

Returns

Extended list of selected molecule pair edge sets by addditional_ringConnections.

Return type

t.List[ind]

restraintmaker.algorithm.Optimizer.calculate_value_pca_relative_to_pca_of_both_molecules(restraint_pos)

calculate eigenvalues for restraints-cogs Todo: to be removed

Parameters

restraint_pos

Returns

eigenvals

Return type

List[float]

restraintmaker.algorithm.Optimizer.cog_distance_restraint(r: restraintmaker.utils.Restraints.DistanceRestraint) → Tuple[float, float, float]

Calculate the cog of a distance restraint

Parameters

r (Restraints.DistanceRestraint)

Returns

the cog between two atoms building a distance restraint

Return type

Tuple[float, float, float]

restraintmaker.algorithm.Optimizer.get_all_short_pair_restraints(atoms: List[restraintmaker.utils.Utilities.Atom], max_dis: float) → List[restraintmaker.utils.Restraints.DistanceRestraint]

finds all pairs of atoms within a certain cutoff distance of each other. Atoms withing the same molecules can are not connected

TODO: SPEED: first sort bymolecules and then only compare the molecule list, to avaiod all forbidden combinations of atoms within the samemolecules

Parameters

• atoms (t.List[u.Atom]) – List of atoms

• max_dis (float) – maximal distance of two connected atoms in nm

Returns

A list of all connections, shorter than max_dis

Return type

t.List[RestraintType.Pair_Restraint]

restraintmaker.algorithm.Optimizer.maximal_spanning_tree_greedy(potential_restraints: List[restraintmaker.utils.Restraints.DistanceRestraint], n: int, priority_algo: str = 'minmax') → List[restraintmaker.utils.Restraints.DistanceRestraint]

Finds a maximal spanning tree in which the nodes represent distance restraints and edges the distance between their middles. The ‘tree’ will be provided in the form of a list. Connectivity info is not explicitly given. Due to the working of Prims Algorithm it is guaranteed, that every vortex in the list is connected to one vortex before it in the list WARNING: But it is not guaranteed that the edges are ordered by size WARNING: Involves calculating distances between all Restraint pairs. => O(n!). Only use on preselected lists of connections

TODO: Implement different options for distance calculation within this function. I think passing a function get_priority as argument would become really dirty really, quickly. But I can define some options as inner functions BUT: Do I slow it down thisway. What is the cost of a function call?

Options i want: 1) Prim: Distance to farthest node in tree not yet in tree

2. closest: Distance to closeest node in maximal_spanning_tree_prim)

3. Average: Average distance to all nodes already in tree

Have to define priority_node as class for now, even though it is totally overkill. I need it to be mutable, so I can update priorities. But now I actually have to use opeator overloading to make it heapq compatible => TODO: Find a better solution

Give each node its initial priority: The dstance to the FARTHEST node Read carefully: I sacrificed readability to mimize having to call certain attributes to often. Use _ as . operator

TODO: Move those inner functions out, so they can be reused in othre places Define the different Algorithms

TODO: The current setup is a bit confusing: _update_priority_(v) accesses the newly chosen node from within the function. Would be cleaner to give list of chosen restraints as arg as well

Parameters

• potential_restraints (t.List[u.connections]) – List of connections (Pairwise Distance Restraints)

• n (int) – how many restraints should be set?

• priority_algo (str) – Which algorithm should be used to update priorities of not yet chosen nodes?

Returns

The tree in the form of Pairs of connections and their distances

Return type

t.List[u.RestraintPair]

restraintmaker.algorithm.Optimizer.maximal_weight_chain(edge_list: List[Tuple[int, int]], value_list: List[float], n_nodes: int, _verbosity_level: int = 5)

chooses from a list of edges the ones that form the biggest chain including all nodes. Nodes are considered as ints (indices) and edges as tuples of nodes

@Warning: if the input is NOT a fully connected graph there might be no solution

Parameters

• edge_list (t.List[t.Tuple[int,int]]) – list of all edges as tuples of ints

• value_list (t.List[float]) – A list of all edge weights

• n_nodes (int) – Number of nodes

Returns

Indices of the chosen edges

Return type

t.List[ind]

restraintmaker.algorithm.Optimizer.maximal_weight_ring(edge_list: List[Tuple[int, int]], value_list: List[float], n_nodes: int, _verbosity_level: int = 5)

chooses from a list of edges the ones that form the biggest ring including all nodes. Nodes are considered as ints (indices) and edges as tuples of nodes

@Warning: if the input is NOT a fully connected graph there might be no solution

Parameters

• edge_list (t.List[t.Tuple[int,int]]) – list of all edges as tuples of ints

• value_list (t.List[float]) – A list of all edge weights

• n_nodes (int) – Number of nodes

Returns

Indices of the chosen edges

Return type

t.List[ind]

class restraintmaker.algorithm.Optimizer.priority_node(priority, node)

Bases: tuple

node

Alias for field number 1

priority

Alias for field number 0

restraintmaker.algorithm.Selection module

The module Selections contains the selection logics. A selected atom will be considered for restraint placement. These Selections are mostly useful for the GUI mode.

class restraintmaker.algorithm.Selection.AllSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection._Selection

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Universial Selections can be used to select all present atoms with one click. (Actually it 2 Clicks)

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

_update_confirm()

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_move(new_x: float, new_y: float, new_z: float)

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_select(new_atoms: List[restraintmaker.utils.Utilities.Atom])

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_size(increase: bool)

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

get_args(input_function: Callable)

should be overridden by every subclass of _Selection. It will assign all necessary variables using input function. In Universal selection, the selection will be set directly by this function to all atoms.

Parameters

input_function (t.Callable (str)) – a function that will provide the arguments for the selection in the necessary format. Here: Not necessesary. Just pass an ‘empty’ function or any function at all. It will not be called.

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

update()

will be called by get_args, to initially set all atoms as selected. => The Selection will start the first time it will be checked

Return type

NoReturn

class restraintmaker.algorithm.Selection.LimitedSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection._Selection

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

A selection containing a fix maximal number of atoms

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

_update_select(new_atoms: List[restraintmaker.utils.Utilities.Atom])

_update_select should be overridden by every subclass of _Selection that wants to be notified when new atoms have been selected/marked in the GUI LimitedSelection.update () only accepts one molecule in new_atoms at a time.

Parameters

new_atoms (t.List) – List of atom selection that has been added since last updated

Return type

NoReturn

get_args(input_function: Callable)

should be overridden by every subclass of _Selection. It will assign all necessart variables using input function. For Limited_Filter those are: max_size: int - Maximal number of atoms in selection.

Parameters

input_function (t.Callable(str)) – a function that will provide the arguments for the selection in the necessary format: int

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

class restraintmaker.algorithm.Selection.MCSSelection(all_atoms)

Bases: restraintmaker.algorithm.Selection._Selection

__init__(all_atoms)

Selects all atoms, which are in the MCS of at least on pair of molecules

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

_update_confirm()

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_move(new_x: float, new_y: float, new_z: float)

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_select(new_atoms: List[restraintmaker.utils.Utilities.Atom])

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

_update_size(increase: bool)

Dummy no selection possible

Parameters

new_atoms (t.List[u.Atom]) – not used here, because all atoms are selected

Return type

NoReturn

get_args(input_function: Callable)

should be overridden by every subclass of _Selection. It will assign all necessart variables using input function. For MCS_Selection the argument is a list of the Molecules in the pdb format.

Parameters

input_function (t.Callable (str)) – a function that will provide the arguments for the selection in the necessary format. Here: Not necessesary. Just pass an ‘empty’ function or any function at all. It will not be called.

Return type

NoReturn

Raises

BadArgumentException: – if the input function does not provide all arguments in the necessary format

update()

general update function

Return type

NoReturn

class restraintmaker.algorithm.Selection.PaintSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection.SphericalSelection

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Works like a Spherical selection, but does keep Atoms Selected, once the Selection Spher has touched them

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

select_atoms_within_sphere()

get all atoms within the sphere Override select_atoms_within_sphere, so it will keep old atoms This works, because when the inherited update functions are called, they will still call the overriden select_atoms_within_sphere

Parameters

a (u.Atom) – the atom, to be checked if it is inside the selection sphere.

Returns

atom is in sphere?

Return type

bool

class restraintmaker.algorithm.Selection.PairSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection.LimitedSelection

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

A Selection containing up to 2 Atoms. A Shortcut to create a Limited_Selection with max_atoms = 2

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

get_args(input_function: Callable)

should be overridden by every subclass of _Selection. It will assign all necessart variables using input function.

For Pairwise_Filter there is no additional arguments. get_args(…) still needs to be called because it sets the fixed arguments directly.

Parameters

input_function (t.Callable (str)) – a function that will provide the arguments for the selection in the necessary format. Here: Not necessesary. Just pass an ‘empty’ function or any function at all. It will not be called.

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

class restraintmaker.algorithm.Selection.SingleAtomSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection.LimitedSelection

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

A selection containing only one atom. A Shortcut to create a Limited_Selection with max_atoms+1 This is usefull for GUI programs, that use refresh, once a selection is full: Just allow to pick atoms.

Parameters

all_atoms

get_args(input_function: Callable)

should be overridden by every subclass of _Selection. It will assign all necessart variables using input function. For Pairwise_Filter there is no additional arguments. get_args(…) still needs to be called because it sets the fixed arguments directly. :Parameters: input_function (t.Callable(str)) – a function that will provide the arguments for the selection in the necessary format. Here: Not necessesary. Just pass an ‘empty’ function or any function at all. It will not be called.

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

class restraintmaker.algorithm.Selection.SphericalSelection(all_atoms: List[restraintmaker.utils.Utilities.Atom])

Bases: restraintmaker.algorithm.Selection._Selection

..class SphericalSelection:

__init__(all_atoms: List[restraintmaker.utils.Utilities.Atom])

A spherical selection selects all atoms within a given sphere. The Handling Program (restraintmaker_PyMol needs to provide a function that displays and chagnes the sphere

Parameters

all_atoms (t.List[u.Atom]) – all possible selectable atoms

_update_confirm()

should be overriden by everz subclass of _Selection that needs some kind of confirmation before it finsihes. For Spherical_Selection, this indicates, that the user has moved to Sphere to where he wants it.

Return type

NoReturn

_update_move(new_x: float, new_y: float, new_z: float)

should be overridden by every subclass of _Selection that diplays a postion or similar, that the user can change.

Parameters

• new_x (float) – New x Position

• new_y (float) – New y Position

• new_z (float) – New z Position

_update_size(increase: bool)

should be overridden by every subclass of _Selection who has some value, such as a size, that can be changed by the user during the selection.

Carefull: This method merely shows that the user WANTS to change the size. The actual changes are made by the selection itself. For SphericalSelection this will change the radius of the spehere

Parameters

increase (bool) – should the radius increase(True) or decrease (False)

Return type

NoReturn

atom_within_sphere(a: restraintmaker.utils.Utilities.Atom) → bool

get all atoms within the sphere

Parameters

a (u.Atom) – the atom, to be checked if it is inside the selection sphere.

Returns

atom is in sphere?

Return type

bool

get_args(input_function: Callable[[str], str])

should be overridden by every subclass of _Selection. It will assign all necessart variables using input function.

Parameters

input_function (t.Callable (str)) – a function that will provide the arguments for the selection in the necessary format. Here: Not necessesary. Just pass an ‘empty’ function or any function at all. It will not be called.

Return type

NoReturn

Raises

BadArgumentException – if the input function does not provide all arguments in the necessary format

select_atoms_within_sphere()

update selection, select all atoms inside the sphere

Return type

NoReturn

Module contents