1.1.1.1. molpher.core package¶
This package contains the most essential features of the library. It provides everything that the user of the library will need. All the modules and classes below and their contents are meant to be imported by external scripts.
Table of Contents
1.1.1.1.1. Modules¶
1.1.1.1.1.1. molpher.core.ExplorationData module¶
This module houses the ExplorationData
class:
-
class
molpher.core.ExplorationData.
ExplorationData
(other=None, **kwargs)[source]¶ Bases:
molpher.swig_wrappers.core.ExplorationData
Parameters: - other (
molpher.swig_wrappers.core.ExplorationData
) – an instance ofmolpher.swig_wrappers.core.ExplorationData
to wrap with this class - **kwargs (
Dictionary displays
) – the morphing parameters to be set (can be incomplete)
Note
If both
other
and**kwargs
are specified, then everything in**kwargs
will be applied after the instance inother
is wrapped.This a specialized version of the
molpher.swig_wrappers.core.ExplorationData
proxy class. It implements some additional functionality for ease of use from Python.It contains all the information needed to initialize an
ExplorationTree
instance. Additionally, any tree can be transformed into an instance of this class by calling theasData()
method.One advantage of this class over the
ExplorationTree
is that it allows direct modifications of the exploration tree structure. This is especially useful when we want to create an initial tree topology before the exploration itself.Warning
Note that current implementations of the modification methods is experimental and may result in undefined behaviour. Therefore, it is only recommended to use it as a means of setting morphing parameters and spawning tree instances or spawning new trees from existing ones without the need to create a snapshot file.
Because it inherits from
molpher.swig_wrappers.core.ExplorationData
, it provides the same interface as the corresponding C++ class, but exposes the morphing parameters as object attributes for ease of use. These attributes follow a slightly different name convention than the corresponding getters and setters of the parent class. Their names are derived from the names of the parameters used in the XML template files that are more self-explanatory and easier to remember and type. The table below gives an overview of all available parameters, their default values and short descriptions and the respective getters and setters of the base class:¶ Attribute Default Value Brief Description Setter Getter source
None
SMILES of the source molecule. setSource
getSource
target
None
SMILES of the target molecule. setTarget
getTarget
operators
a tuple
of selectors [1]A tuple
of identifiers of the permittedchemical operators
.setChemicalOperators
getChemicalOperators
accept_max
100 Maximum number of candidates accepted at once (based on their position in ExplorationTree.candidates
).setCntCandidatesToKeepMax
getCntCandidatesToKeepMax
accept_min
50 Minimum number of candidates accepted during probability filtering. setCntCandidatesToKeep
getCntCandidatesToKeep
close_produce
150 Maximum number of morphs to produce with an ExplorationTree.generateMorphs()
call when close to the target molecule.setCntMorphsInDepth
getCntMorphsInDepth
far_produce
80 Maximum number of morphs to produce with an ExplorationTree.generateMorphs()
call.setCntMorphs
getCntMorphs
far_close_threshold
0.15 Molecular distance below which the target molecule and a morph are considered to be close. setDistToTargetDepthSwitch
getDistToTargetDepthSwitch
fingerprint
FP_MORGAN
Identification string of the current fingerprint strategy. setFingerprint
getFingerprint
similarity
SC_TANIMOTO
Identification string of the current fingerprint strategy. setSimilarityCoefficient
getSimilarityCoefficient
max_morphs_total
1500 Maximum number of morphs allowed to be derived from one molecule and the allowed number of non-producing descendants before a molecule is removed from the tree. setCntMaxMorphs
getCntMaxMorphs
non_producing_survive
5 Number of iterations before descendants of a non-producing molecule are removed from the tree. setItThreshold
getItThreshold
weight_max
100000.0 Maximum molecular weight of one morph. setMaxAcceptableMolecularWeight
getMaxAcceptableMolecularWeight
weight_min
0.0 Minimum molecular weight of one morph. setMinAcceptableMolecularWeight
getMinAcceptableMolecularWeight
[1] ( OP_ADD_ATOM
,OP_ADD_BOND
,OP_BOND_CONTRACTION
,OP_BOND_REROUTE
,OP_INTERLAY_ATOM
,OP_MUTATE_ATOM
,OP_REMOVE_ATOM
,OP_REMOVE_BOND
)-
exception
UnknownParameterException
[source]¶ Bases:
Exception
Indicates that an unknown parameter was supplied.
-
ExplorationData.
accept_max
¶ The maximum number of morphs allowed to be connected to the tree upon one call to
extend()
.If more than
accept_max
morphs withTrue
in the appropriate position ofcandidates_mask
are present incandidates
andextend()
is called, only firstaccept_max
morphs fromcandidates
will be connected to the tree and the rest will be discarded.See also
Returns: maximum number of candidates accepted upon extend()
Return type: int
-
ExplorationData.
accept_min
¶ If
FilterMorphsOper.PROBABILITY
is used during filtering, this is the number of morphs accepted with 100% probability.See also
Returns: minimum number of candidates accepted during probability filtering Return type: int
-
ExplorationData.
close_produce
¶ This is the maximum number of morphs generated from one leaf when the leaf of the tree currently being processed with
generateMorphs()
lies less thanfar_close_threshold
from the target molecule.See also
Returns: maximum number of morphs to produce with an generateMorphs()
callReturn type: int
-
ExplorationData.
far_close_threshold
¶ This distance threshold controls the number of morphs generated with
generateMorphs()
for molecules closer or further from the target molecule. Morphs that have distance from the target molecule lower thanfar_close_threshold
are considered to be close.See also
Returns: distance threshold for far_produce
andclose_produce
Return type: float
-
ExplorationData.
far_produce
¶ The maximum number of morphs generated from one leaf when the leaf of the tree currently being processed with
generateMorphs()
lies more thanfar_close_threshold
from the target molecule.See also
Returns: maximum number of morphs to produce with a generateMorphs()
callReturn type: int
-
ExplorationData.
fingerprint
¶ Returns an identifier of the currently used molecular fingerprint.
¶ Identifier Description FP_ATOM_PAIRS
— FP_MORGAN
— FP_TOPOLOGICAL
— FP_TOPOLOGICAL_LAYERED_1
— FP_TOPOLOGICAL_LAYERED_2
— FP_VECTORFP
— FP_TOPOLOGICAL_TORSION
— FP_EXT_ATOM_PAIRS
— FP_EXT_MORGAN
— FP_EXT_TOPOLOGICAL
— FP_EXT_TOPOLOGICAL_LAYERED_1
— FP_EXT_TOPOLOGICAL_LAYERED_2
— FP_EXT_TOPOLOGICAL_TORSION
— Returns: molecular fingerprint identifier Return type: str
-
ExplorationData.
is_valid
¶ Shows if this instance represents valid parameters. The instance becomes invalid, if there are any bad or nonsensical parameter values, values are missing (such as undefined chemical operators) or the tree structure is for any reason unacceptable.
Returns: True
for a valid instance,False
for invalidReturn type: bool
-
static
ExplorationData.
load
(snapshot)[source]¶ A factory method to create an instance of
ExplorationData
from a tree snapshot.Parameters: snapshot ( str
) – path to the snapshot fileReturns: new instance representing the data loaded from the snapshot file Return type: ExplorationData
-
ExplorationData.
max_morphs_total
¶ This value is the maximum number of morphs allowed to be generated from one molecule. If the number of generated morphs exceeds this number, all additional morphs can be filtered out using the
FilterMorphsOper.MAX_DERIVATIONS
filter.It is also the maximum number of ‘bad morphs’ generated from one molecule. If a molecule has more than
max_morphs_total
descendants and none of them are closer to the target molecule than the molecule in question, then the molecule is permanently removed from the tree with all of its descendants whenprune()
is called.See also
Returns: maximum number of ‘bad morphs’ before pruning Return type: int
-
ExplorationData.
non_producing_survive
¶ A molecule that has not produced any morphs closer to the target molecule than itself (a non-producing molecule) for
non_producing_survive
number of calls toextend()
will have its descendants removed during the nextprune()
call.Returns: number of calls to generateMorphs()
before descendants of a non-producing molecule are removed from the treeReturn type: int
-
ExplorationData.
operators
¶ A set of chemical operators to use. These define how the input molecule and its descendants can be manipulated during morphing.
Can be set using an iterable of the appropriate selectors or their names as
str
. Any duplicates are automatically removed¶ Identifier Description OP_ADD_ATOM
Add a random atom to the molecule. OP_REMOVE_ATOM
Remove an atom from the molecule. OP_ADD_BOND
Add a bond between two random atoms. OP_REMOVE_BOND
Remove a bond between two random atoms. OP_MUTATE_ATOM
Change a randomly selected atom to a different element. OP_INTERLAY_ATOM
— OP_BOND_REROUTE
— OP_BOND_CONTRACTION
— Returns: names of the current chemical operators Return type: tuple
ofstr
-
ExplorationData.
param_dict
¶ Holds a dictionary of current morphing parameters values for this instance. A new dictionary of parameters can be assigned to change them.
Returns: a dictionary of parameters Return type: Dictionary displays
-
ExplorationData.
similarity
¶ Returns an identifier of the currently used similarity measure.
¶ Identifier Description SC_ALL_BIT
— SC_ASYMMETRIC
— SC_BRAUN_BLANQUET
— SC_COSINE
— SC_DICE
— SC_KULCZYNSKI
— SC_MC_CONNAUGHEY
— SC_ON_BIT
— SC_RUSSEL
— SC_SOKAL
— SC_TANIMOTO
— SC_TVERSKY_SUBSTRUCTURE
— SC_TVERSKY_SUPERSTRUCTURE
— Returns: similarity measure identifier Return type: str
-
ExplorationData.
source
¶ The source molecule. All morphs in an exploration tree are derived from this molecule during morphing. This is the root of the created tree.
Can be set using a
MolpherMol
instance or a SMILES string of the new source molecule.Returns: current source molecule Return type: MolpherMol
-
ExplorationData.
target
¶ The target molecule. This is the molecule being searched for during morphing. In the original version of the algorithm the goal is to maximize similarity (minimize structural distance) of the generated morphs and this molecule.
Can be set using a
MolpherMol
instance or a SMILES string of the new target molecule.Returns: current target molecule Return type: MolpherMol
-
ExplorationData.
weight_max
¶ If
FilterMorphsOper.WEIGHT
filter is used on an exploration tree, this will be the maximum weight of the candidate morphs accepted during a filtering procedure.See also
Returns: maximum acceptable weight during filtering Return type: float
-
ExplorationData.
weight_min
¶ If
FilterMorphsOper.WEIGHT
filter is used on an exploration tree, this will be the minimum weight of the candidate morphs accepted during a filtering procedure.See also
Returns: minimum acceptable weight during filtering Return type: float
- other (
1.1.1.1.1.2. molpher.core.ExplorationTree module¶
-
class
molpher.core.ExplorationTree.
Callback
(callback)[source]¶ Bases:
molpher.swig_wrappers.core.TraverseCallback
Parameters: callback (any callable object with one required parameter) – the callable to call every time a molecule is encountered during traversal Basic callback class used to traverse the tree with the
ExplorationTree.traverse()
method.It registers a callable and calls it every time a morph is processed.
-
class
molpher.core.ExplorationTree.
ExplorationTree
[source]¶ Bases:
molpher.swig_wrappers.core.ExplorationTree
This a specialized version of the
molpher.swig_wrappers.core.ExplorationTree
proxy class. It implements some additional functionality for ease of use from Python.Attention
This class has no constructor defined. Use the
create()
factory method to obtain instances of this class.-
asData
()[source]¶ Returns: the tree as an ExplorationData
instanceReturn type: ExplorationData
-
candidates
¶ Returns: the candidate morphs (morphs generated by a single call to generateMorphs()
.)Return type: tuple
ofMolpherMol
instances
-
candidates_mask
¶ A
tuple
ofbool
objects that serve as means of filtering the candidate morphs. Each morph incandidates
has abool
variable assigned to it in thistuple
– only morphs withTrue
at the appropriate position are added to the tree whenextend()
is called.It can be changed by assigning a new
tuple
or a call tosetCandidateMorphsMask()
.Returns: currently selected candidate morphs represented as a tuple
ofbool
objectsReturn type: tuple
-
static
create
(tree_data=None, source=None, target=None, callback_class=<class 'molpher.core.ExplorationTree.Callback'>)[source]¶ Create an exploration tree.
Parameters: - tree_data (
molpher.swig_wrappers.core.ExplorationData
(or its derived class), aDictionary displays
of parameters (in the same format as inExplorationData
‘s constructor) or a path to a XML template or a tree snapshot) – the morphing parameters (optional ifsource
andtarget
are specified) - source (
str
orMolpherMol
) – SMILES of the source molecule or a molecule directly (uses a copy not the instance itself) - target (
str
) – SMILES of the target molecule - callback_class (any class derived from
Callback
) – the class to use when making a callback using thetraverse()
method
Note
When
tree_data
is specified,source
andtarget
are always ignored.- tree_data (
-
fetchMol
(canonSMILES)[source]¶ Returns a molecule from the tree using a canonical SMILES string.
Raises a
RuntimeError
if the molecule is not found.Parameters: canonSMILES ( str
) – SMILES string of the molecule to fetchReturns: molecule from a tree Return type: MolpherMol
-
generation_count
¶ Returns: Number of morph generations connected to the tree so far. Return type: int
-
leaves
¶ Returns: the current leaves of the tree Return type: tuple
ofMolpherMol
instances
-
params
¶ A dictionary representing the current exploration parameters.
It is possible to assign a new dictionary (or an instance of the
molpher.swig_wrappers.core.ExplorationData
class) to update the current parameters.Note
Only parameters defined in the supplied dictionary are changed and if an instance of
molpher.swig_wrappers.core.ExplorationData
is supplied only the parameters are read from it (the tree structure remains the same).Returns: current parameters Return type: Dictionary displays
-
path_found
¶ Returns: True
if the target molecule is present in the tree,False
otherwise.Return type: bool
-
traverse
(callback, start_mol=None)[source]¶ This method can be used to traverse the whole tree structure (or just a subtree) starting from the root to leaves. It takes a callback function that accepts a single required argument and traverses the whole tree starting from its root (or root of a specified subtree – see
start_mol
) and calls the supplied callback with with encountered morph as its parameter.Parameters: - callback (a callable object that takes a single argument) – the callback to call
- start_mol (
str
orMolpherMol
) – the root of a subtree to explore as canonical SMILES orMolpherMol
instance
-
1.1.1.1.1.3. molpher.core.MolpherMol module¶
-
class
molpher.core.MolpherMol.
MolpherMol
(smiles=None, other=None)[source]¶ Bases:
molpher.swig_wrappers.core.MolpherMol
Parameters: - smiles (
str
) – smiles of the molecule that is to be created - other (
molpher.swig_wrappers.core.MolpherMol
or its derived class) – another instance, the new instance will be its copy (tree ownership is not transferred onto the copy)
This a specialized version of the
molpher.swig_wrappers.core.MolpherMol
proxy class. It implements some additional functionality for ease of use from Python.-
copy
()[source]¶ Returns a copy of this instance. If this instance has a
tree
assigned, the returned will haveNone
instead.Returns: a copy of this instance Return type:
-
descendents
¶ Canonical SMILES strings of all molecules derived from this compound that are currently present in the tree.
Returns: Return type: str
-
dist_to_target
¶ The value of the objective function. In the original implementation, this is the structural distance to the target molecule using a
similarity measure
.This value can be changed.
Returns: value of the objective function Return type: float
-
gens_without_improvement
¶ Number of morph generations derived from this molecule that did not contain any morphs with an improvement in the objective function from the target molecule.
This value can be changed.
Returns: number of non-producing generations Return type: int
-
historic_descendents
¶ Canonical SMILES strings of all molecules derived from this compound.
Returns: Return type: str
-
parent_operator
¶ The name of the chemical operator selector that lead to the creation of this molecule.
Returns: name of the parent chemical operator Return type: str
-
parent_smiles
¶ Canonical SMILES string of the parent molecule in the tree.
Can be an empty
str
, if the molecule is a root of the tree or is not associated with any.Returns: canonical SMILES string of the parent molecule in the tree Return type: str
-
sascore
¶ The synthetic feasibility score of the molecule according to Ertl.
This value can be changed.
Returns: synthetic feasibility score Return type: float
-
tree
¶ A reference to the tree this instance is currently in. If the molecule is not present in any tree, this value is
None
.Returns: reference to the tree this instance is currently in Return type: ExplorationTree
orNone
- smiles (
1.1.1.1.1.4. molpher.core.selectors module¶
Contains all global selectors that are usually used when creating an exploration tree or setting any of its parameters during runtime.
There are three types of selectors:
- fingerprints selectors
Their names are prepended with ‘FP_’ and are used to either set the
fingerprint
member of theExplorationData
class or as the value of the fingerprint key when callingcreate()
with theparams
parameter or writing into theparams
member of theExplorationTree
.
FP_MORGAN
is the default option.
- similarity coefficient selectors
Their names are prepended with ‘SC_’ and are used to either set the
similarity
member of theExplorationData
class or as the value of the similarity key when callingcreate()
with theparams
parameter or writing into theparams
member of theExplorationTree
.
SC_TANIMOTO
is the default option.
- chemical operators
Their names are prepended with ‘OP_’ and an iterable of them is used to either set the
operators
member of theExplorationData
class or as items of the iterable assigned to operators key when callingcreate()
with theparams
parameter or writing into theparams
member of theExplorationTree
.All of the available selectors are used by default.
-
molpher.core.selectors.
FP_ATOM_PAIRS
= 0¶
-
molpher.core.selectors.
FP_EXT_ATOM_PAIRS
= 7¶
-
molpher.core.selectors.
FP_EXT_MORGAN
= 8¶
-
molpher.core.selectors.
FP_EXT_TOPOLOGICAL
= 9¶
-
molpher.core.selectors.
FP_EXT_TOPOLOGICAL_LAYERED_1
= 10¶
-
molpher.core.selectors.
FP_EXT_TOPOLOGICAL_LAYERED_2
= 11¶
-
molpher.core.selectors.
FP_EXT_TOPOLOGICAL_TORSION
= 12¶
-
molpher.core.selectors.
FP_MORGAN
= 1¶ This is the default selector that is used when no other option is specified.
-
molpher.core.selectors.
FP_TOPOLOGICAL
= 2¶
-
molpher.core.selectors.
FP_TOPOLOGICAL_LAYERED_1
= 3¶
-
molpher.core.selectors.
FP_TOPOLOGICAL_LAYERED_2
= 4¶
-
molpher.core.selectors.
FP_TOPOLOGICAL_TORSION
= 6¶
-
molpher.core.selectors.
FP_VECTORFP
= 5¶
-
molpher.core.selectors.
OP_ADD_ATOM
= 0¶
-
molpher.core.selectors.
OP_ADD_BOND
= 2¶
-
molpher.core.selectors.
OP_BOND_CONTRACTION
= 7¶
-
molpher.core.selectors.
OP_BOND_REROUTE
= 6¶
-
molpher.core.selectors.
OP_INTERLAY_ATOM
= 5¶
-
molpher.core.selectors.
OP_MUTATE_ATOM
= 4¶
-
molpher.core.selectors.
OP_REMOVE_ATOM
= 1¶
-
molpher.core.selectors.
OP_REMOVE_BOND
= 3¶
-
molpher.core.selectors.
SC_ALL_BIT
= 0¶
-
molpher.core.selectors.
SC_ASYMMETRIC
= 1¶
-
molpher.core.selectors.
SC_BRAUN_BLANQUET
= 2¶
-
molpher.core.selectors.
SC_COSINE
= 3¶
-
molpher.core.selectors.
SC_DICE
= 4¶
-
molpher.core.selectors.
SC_KULCZYNSKI
= 5¶
-
molpher.core.selectors.
SC_MC_CONNAUGHEY
= 6¶
-
molpher.core.selectors.
SC_ON_BIT
= 7¶
-
molpher.core.selectors.
SC_RUSSEL
= 8¶
-
molpher.core.selectors.
SC_SOKAL
= 9¶
-
molpher.core.selectors.
SC_TANIMOTO
= 10¶ This is the default selector that is used when no other option is specified.
-
molpher.core.selectors.
SC_TVERSKY_SUBSTRUCTURE
= 11¶
-
molpher.core.selectors.
SC_TVERSKY_SUPERSTRUCTURE
= 12¶
1.1.1.1.2. Subpackages¶
- 1.1.1.1.2.1. molpher.core.tests package
- 1.1.1.1.2.2. molpher.core.operations package
- 1.1.1.1.2.2.1. Submodules
- 1.1.1.1.2.2.2. molpher.core.operations.ExtendTreeOper module
- 1.1.1.1.2.2.3. molpher.core.operations.FilterMorphsOper module
- 1.1.1.1.2.2.4. molpher.core.operations.FindLeavesOper module
- 1.1.1.1.2.2.5. molpher.core.operations.GenerateMorphsOper module
- 1.1.1.1.2.2.6. molpher.core.operations.PruneTreeOper module
- 1.1.1.1.2.2.7. molpher.core.operations.SortMorphsOper module
- 1.1.1.1.2.2.8. molpher.core.operations.TraverseOper module
- 1.1.1.1.2.2.9. molpher.core.operations.TreeOperation module
- 1.1.1.1.2.2.10. molpher.core.operations.callbacks module
- 1.1.1.1.2.2.11. Module contents
1.1.1.1.3. Module contents¶
1.1.1.1.3.2. ExplorationTree¶
A direct reference to molpher.core.ExplorationTree.ExplorationTree
.
See also
1.1.1.1.3.3. ExplorationData¶
A direct reference to molpher.core.ExplorationData.ExplorationData
.
See also