1.1.1.3.1.1.1.3. ExplorationTree

class molpher.swig_wrappers.core.ExplorationTree(*args, **kwargs)

Represents an exploration tree and facilitates the most basic interaction with it. It is a tight wrapper around the C++ implementation. The molpher.core.ExplorationTree class extends upon this implementation and provides a more user-friendly version of this class.

Attention

This class does not define a constructor. Use the create() factory method to spawn instances.

static create(*args)

Returns an ExplorationTree instance using a supplied ExplorationData, tree snapshot or SMILES strings of the source molecule and the target molecule.

Parameters

*args (ExplorationData or str) – an ExplorationData instance, path to a tree snapshot or a source molecule and a target molecule as two arguments.

Returns

ExplorationTree instance created from the supplied snapshot

Return type

ExplorationTree

save(filename)

Saves the tree to a snapshot file. The filename should end with either .xml or .snp.

Parameters

filename (str) – path to the new snapshot file

runOperation(operation)

Takes a TreeOperation instance and attempts to run it by attaching itself to it and calling its __call__() method.

See also

Tree Operation Classes

Note

Doing this will also automatically attach the given TreeOperation instance to this ExplorationTree object.

Parameters

operation (TreeOperation) – a TreeOperation instance to run

fetchLeaves(increase_dist_improve_counter=False)

Gives a tuple of MolpherMol instances that represent the leaves of this ExplorationTree.

Returns

tuple of MolpherMol instances representing the leaves of this tree

Return type

tuple

fetchMol(canonSMILES)

Attempts to fetch a molecule (represented by its canonical SMILES string) from the current tree. If the molecule exists, it returns an appropriate MolpherMol instance. Otherewise, it raises a RuntimeError.

Parameters

canonSMILES (str) – a str representing SMILES of the molecule being searched for

Returns

MolpherMol representing the looked up molecule

Return type

MolpherMol

Raises

RuntimeError if the molecule specified could not be found in the tree

hasMol(canonSMILES)

Returns True or False to indicate the presence of a molecule in the current tree.

Parameters

canonSMILES (str) – a str representing SMILES of the molecule being searched for

Returns

bool value representing the presence of the searched molecule in this tree (True if it is present, False otherwise)

Return type

bool

deleteSubtree(canonSMILES, descendents_only=False)

Deletes a specified molecule from the tree and all of its descendents.

Parameters

canonSMILES (str) – a str representing SMILES of the molecule being removed

generateMorphs(*args)

Generates mew candidate morphs using the current exploration parameters and saves them (see ExplorationData for details).

The generated compounds can be retrieved using the getCandidateMorphs method.

Note

All morphs already present in the tree are filtered out automatically.

sortMorphs()

Sorts the candidate morphs according to their distances from the target molecule.

Warning

When morphs are generated the distance to the current target is saved for each morph. This distance is not updated if the target of the tree changes afterwards.

filterMorphs(*args)

Filters the candidate morphs according to the supplied filtering options (see the table below for a listing of the available filters). The filtering options can be easily combined and passed to the method using the | operator. For example, the method can be called like this: tree.filterMorphs(FilterMorphsOper.SYNTHESIS | FilterMorphsOper.PROBABILITY). If no filter information is passed, all filters are used automatically (equal to passing FilterMorphsOper.ALL).

Table 1.5 Filtering options and their descriptions.

Option	Description
PROBABILITY	Filter the candidate morphs according to probability based on their position in ExplorationTree.candidates.
WEIGHT	Remove molecules that do not satisfy the weight constraints.
SYNTHESIS	The inbuilt synthetic feasibility filter.
MAX_DERIVATIONS	Maximum number of morphs derived from one molecule.
DUPLICATES	Remove candidates that are already in the tree (always on).
HISTORIC_DESCENDENTS	Remove candidates that have already been tried by their parents.
ALL	Use all of the above filters.

The results of the filtering can be observed using the getCandidateMorphsMask method.

See also

FilterMorphsOper

Parameters

*args (FilterMorphsOper options) – one or more filtering options combined using the | operator

extend()

Attach all candidate morphs that have not been filtered out to the tree. In other words, make them the new leaves.

Note

By calling this method a morphing iteration is committed.

prune()

Perform the pruning of the tree according to the rules specified by current exploration parameters (see ExplorationData for details).

getThreadCount()

Returns the number of threads this particular ExplorationTree will use. The value of 0 indicates that the same number of threads as the number of available cores will be used.

asData()

Can be used to obtain the current exploration parameters.

Returns

instance of ExplorationData, which holds the current configuration options for the computations on the tree

Return type

ExplorationData

getCandidateMorphs()

Gives a tuple of MolpherMol instances that represent the candidate morphs of this ExplorationTree instance.

Returns

tuple of MolpherMol instances representing the candidate morphs

Return type

tuple

getCandidateMorphsMask()

Returns a mask for the tuple returned by getCandidateMorphs. The filtered out morphs are denoted by False at the respective position in the mask.

Morphs filtered out in this way will not be attached to the tree when extend() is called.

Returns

tuple of bool instances which shows what candidate morphs were filtered out

Return type

tuple

getGenerationCount()

Returns the number of morph generations in the tree. Basically the number of morphing iterations performed so far.

Returns

number of morphing iterations performed so far

Return type

int

setThreadCount(threadCnt)

Sets the maximum number of threads used by this instance. The value of 0 indicates that the same number of threads as the number of available cores will be used.

Parameters

threadCnt (int) – an int indicating the number of threads to use

update(data)

Change the current exploration parameters for this instance. If the supplied ExplorationData instance contains a tree topology, it is ignored and only the parameters are taken into account.

Warning

This may invalidate some data in the tree (such as the distances from the target molecule computed so far).

Parameters

param (ExplorationData) – an instance of ExplorationData, which represents the new exploration parameters for this instance

setCandidateMorphsMask(mask)

Sets the morphs’ mask of this instance to a custom value. If the length of the new mask does not correspond to the number of candidate morphs in the tree, a RuntimeError will be raised.

Parameters

mask (tuple) – tuple of bool instances which shows what candidate morphs will be filtered out (not attached to the tree when extend() is called)

Raises

RuntimeError if the length of the new mask does not correspond to the number of candidate morphs in the tree

traverse(*args)

Traverses the tree and calls the () of the callback on each morph in it. A SMILES string of a root of a subtree can be specified before the callback in order to traverse just the subtree.

Parameters

*args (TraverseCallback or str and TraverseCallback) – either an instance of a class derived from TraverseCallback or both SMILES of the root of a subtree and a TraverseCallback