release 2.2.5 (#25)

New functionalities are implemented to:

add reaction nodes to a SynGraph object
remove reaction nodes from a SynGraph object
extract synthetic routes from the network obtained by merging a group of SynGraph objects
Improvements in ChemicalEquationConstructor and ChemicalEquation object are implemented:

better handling of Disconnection information
better handling of stoichiometry
Various bugs are solved.

Author: MartaPasquini

docs/source/chemical_objects_classes.rst

@@ -51,6 +51,10 @@ passing a ``molecular_identity_property_name`` string, indicating which property
 of the molecules involved in the reaction (e.g. ‘smiles’) and a ``chemical_equation_identity_name`` string,
 indicating which representation of the reaction should be used for determining the identity (e.g., 'r_p'
 only considers reactants and products, while 'r_r_p' also takes into account the reagents.
+The methods :method:`~linchemin.cheminfo.constructors.ChemicalEquationConstructor.build_from_reaction_string`
+and :method:`~linchemin.cheminfo.constructors.ChemicalEquationConstructor.build_from_rdrxn` can then be used to
+create the new :class:`~models.ChemicalEquation` by passing, respectively, a reaction string and the type of string
+(e.g., 'smiles' or 'smarts'), or an rdkit ChemicalReaction object.
 
 :class:`~models.ChemicalEquation` objects are characterized by various attributes.
 The ``catalog`` attribute stores the instances of the Molecule objects involved in the reaction
@@ -65,6 +69,10 @@ The ``rdrxn`` attribute, storing the rdkit ChemicalReaction object associated wi
 can be used to compute reaction properties and fingerprints. The ``smiles`` attribute
 contains the smiles string associated with the ChemicalEquation instance.
 
+If the object used to instantiate the new :class:`~models.ChemicalEquation` instance contains
+the atom mapping information, three additional attributes will also be created:
+ ``mapping``, ``disconnection`` and ``template``.
+
 
 .. code-block:: python
 

docs/source/code_customization/code_customization_translate.rst

@@ -51,9 +51,14 @@ Implementing a new input format
 In order to include a new input format among those that LinChemIn can 'read', you
 firstly need to create a new subclass of the abstract class
 :class:`~linchemin.cgu.translate.AbsTranslator` in the :mod:`~linchemin.cgu.translate` module.
+The new subclass should also be decorated with the ``@TranslatorFactory.register_format_translator``
+decorator: it is used by the :class:`~linchemin.cgu.translate.TranslatorFactory` to register
+the new translator among the available ones. The decorator takes two arguments: the name that will be used
+to select the translator and a brief description that will appear in the heper functions.
 
 .. code-block:: python
 
+    @TranslatorFactory.register_format_translator("new_input", "brief description")
     class TranslatorNewInputFormat(AbsTranslator):
     """ Translator subclass to handle translations from NewInputFormat objects """
         as_input = None
@@ -76,14 +81,15 @@ objects, not list of objects.
 If you need more information regarding the Iron format, you can have a look at the
 :ref:`Iron <iron_link>` description.
 You should also set the ``as_input`` attribute of the subclass to ``implemented``, so that
-the new format will appear as available in the helper function.
+the new format will appear as available input format in the helper function.
 
 
 When the code will be implemented you will have something similar
 to this:
 
 .. code-block:: python
 
+    @TranslatorFactory.register_format_translator("new_input", "brief description")
     class TranslatorNewInputFormat(AbsTranslator):
     """ Translator subclass to handle translations from NewInputFormat objects """
         as_input = 'implemented'
@@ -96,29 +102,12 @@ to this:
             # some super cool code
             return iron_graph
 
-The last step is to add the 'name' of your new format in the ``translators`` dictionary
-of :class:`~linchemin.cgu.translate.TranslatorFactory`, to make it available to the factory.
 
-.. code-block:: python
 
-    translators = {
-        'networkx': {'value': TranslatorNetworkx, 'info': 'Translating from/into Networkx objects'},
-        'pydot': {'value': TranslatorDot, 'info': 'Translating from/into Pydot objects'},
-        'ibm_retro': {'value': TranslatorIbm, 'info': 'Translating from outputs generated by the IBMRXN CASP tool'},
-        'az_retro': {'value': TranslatorAz,
-                     'info': 'Translating from outputs generated by the AiZynthFinder CASP tool'},
-        'mit_retro': {'value': TranslatorMit,
-                     'info': 'Translating from outputs generated by the Askos CASP tool'},
-        'syngraph': {'value': None,
-                     'info': 'Translating from/into SynGraph objects'},
-        'pydot_visualization': {'value': TranslatorDotVisualization,
-                                'info': 'Creates PNG pictures of the input routes'},
-        'iron': {'value': None, 'info': 'Translating from/into a list of Iron objects'},
-        'noc': {'value': TranslatorNOC,
-                'info': 'Translating to a format compatible with a Network of Organic Chemistry'},
-        'new_input': {'value': TranslatorNewInputFormat,
-                      'info': 'Brief description that will appear in the helper function'}
-    }
+
+All the available formats are stored in the ``_formats`` attributes of the
+:class:`~linchemin.cgu.translate.TranslatorFactory` class. As previously mentioned, the factory can
+self-register new options via the decorator.
 
 That's it, you are all done! Now your newly developed format is available to all the LinChemIn
 functionalities that use the
@@ -152,6 +141,7 @@ return a graph object in the new format.
 
 .. code-block:: python
 
+    @TranslatorFactory.register_format_translator("new_output", "brief description")
     class TranslatorNewOutputFormat(AbsTranslator):
     """ Translator subclass to handle translations from NewOutputFormat objects """
         as_input = None

docs/source/conf.py

@@ -21,7 +21,7 @@
 
 autosummary_generate = True
 
-version = "2.0.3"
+version = "2.2.5"
 # The full version, including dev info
 release = version.replace("_", "")
 

docs/source/index.rst

@@ -31,6 +31,8 @@ Contents
    data_structure
    chemical_objects_classes
    atom_mapping
+   route_sanity_check
+   manual_manipulation
    reference/index
 
 License

docs/source/manual_manipulation.rst

@@ -0,0 +1,71 @@
+Manual Route Manipulation
+==========================
+
+
+Being able to manipulate the predicted routes means that you can include your domain knowledge directly into
+the output of the models!
+LinChemIn allows you to perform various operations on single and multiple routes
+
+.. currentmodule:: linchemin.cgu.syngraph_operations
+
+Node Removal
+---------------
+If looking at the predicted route(s) you realize that are some molecules or chemical reactions
+that you are not interested in, that re various functions and methods that you can use.
+
+If you just want to remove a single node from a route, you can use the
+:meth:`~linchemin.cgu.syngraph.remove_node` method, which is available for all types of SynGraph.
+However, you need to build the :class:`~linchemin.cheminfo.models.Molecule` or the
+:class:`~linchemin.cheminfo.models.ChemicalEquation` instance corresponding to the node to be removed
+and use its unique identifier property.
+
+.. code-block:: python
+
+    from linchemin.cheminfo.constructors import MoleculeConstructor
+
+    smiles_to_remove = 'CC(=O)O'   # the smiles of the molecule to be removed
+    mol_to_remove = MoleculeConstructor().build_from_molecule_string(smiles_to_remove, 'smiles')    # the Molecule object is built
+    syngraph.remove_node(mol_to_remove.uid)
+
+
+In case you want to remove a reaction node based on its smiles, you can use the
+:func:`~linchemin.cgu.syngraph_operations.remove_reaction_from_syngraph` function. In this case, you
+can also ask to remove the potential "dangling" nodes that the removal could leave behind.
+A new SynGraph object is created.
+
+.. code-block:: python
+
+    from linchemin.cgu.syngraph_operations import remove_reaction_from_syngraph
+
+    smiles_to_remove = 'CCN.CCOC(=O)CC>>CCNC(=O)CC'   # the smiles of the reaction to be removed
+    new_graph = remove_reaction_from_syngraph(original_syngraph,    # the syngraph to be edited
+                                              smiles_to_remove,     # the smiles of the reaction to be removed
+                                              remove_dandling_nodes=True)   # whether dandling nodes should be removed
+
+
+.. currentmodule:: linchemin.cgu.route_mining
+
+Route Mining and Node Addition
+----------------------------------
+So, you predicted a nice set of routes for a target,
+but checking them, you notice that
+a particular reaction or a sequence of reactions that you think might be very useful
+is not included in any of them.
+
+No worries, you can provide the already existing routes, the smiles of the target molecule and
+a list of reactions that you want to add, and will be able to retrieve all
+the routes from the obtained tree.
+All you need is the :func:`~linchemin.cgu.route_mining.mine_routes` function!
+
+.. code-block:: python
+
+    from linchemin.cgu.route_mining import mine_routes
+
+    input_list = [route1, route2]                       # the initial set of routes
+    root = 'CCC(=O)Nc1ccc(cc1)C(=O)N[C@@H](CO)C(=O)O'   # the target molecule for which routes should be retrieved
+    new_reaction_list = ['CC=O.O=O>>CC(=O)O']           # the reaction(s) to be added
+    routes = mine_routes(input_list, root, new_reaction_list)   # all the mined routes
+
+The input routes should be instances of any :class:`~linchemin.cgu.syngraph.SynGraph` subclasses
+and the output routes
+will be :class:`~linchemin.cgu.syngraph.MonopartiteReacSynGraph` objects.

docs/source/reference/generated/linchemin.cgu.syngraph.BipartiteSynGraph.rst

@@ -14,12 +14,19 @@
    .. autosummary::
 
       ~BipartiteSynGraph.__init__
+      ~BipartiteSynGraph.add_molecular_roots
       ~BipartiteSynGraph.add_node
       ~BipartiteSynGraph.add_nodes_sequence
+      ~BipartiteSynGraph.build_chemical_equations
       ~BipartiteSynGraph.builder_from_iron
       ~BipartiteSynGraph.builder_from_reaction_list
+      ~BipartiteSynGraph.find_reactants_products
       ~BipartiteSynGraph.get_leaves
       ~BipartiteSynGraph.get_roots
+      ~BipartiteSynGraph.get_unique_nodes
+      ~BipartiteSynGraph.initialize_with_iron
+      ~BipartiteSynGraph.remove_isolated_ces
+      ~BipartiteSynGraph.remove_node
       ~BipartiteSynGraph.set_source
 
 

docs/source/reference/generated/linchemin.cgu.syngraph.MonopartiteMolSynGraph.rst

@@ -14,11 +14,17 @@
    .. autosummary::
 
       ~MonopartiteMolSynGraph.__init__
+      ~MonopartiteMolSynGraph.add_molecular_roots
       ~MonopartiteMolSynGraph.add_node
+      ~MonopartiteMolSynGraph.build_chemical_equations
       ~MonopartiteMolSynGraph.builder_from_iron
       ~MonopartiteMolSynGraph.builder_from_reaction_list
+      ~MonopartiteMolSynGraph.find_reactants_products
       ~MonopartiteMolSynGraph.get_leaves
       ~MonopartiteMolSynGraph.get_roots
+      ~MonopartiteMolSynGraph.get_unique_nodes
+      ~MonopartiteMolSynGraph.initialize_with_iron
+      ~MonopartiteMolSynGraph.remove_node
       ~MonopartiteMolSynGraph.set_source
 
 

docs/source/reference/generated/linchemin.cgu.syngraph.MonopartiteReacSynGraph.rst

@@ -14,13 +14,20 @@
    .. autosummary::
 
       ~MonopartiteReacSynGraph.__init__
+      ~MonopartiteReacSynGraph.add_molecular_roots
       ~MonopartiteReacSynGraph.add_node
+      ~MonopartiteReacSynGraph.build_chemical_equations
       ~MonopartiteReacSynGraph.builder_from_iron
       ~MonopartiteReacSynGraph.builder_from_reaction_list
+      ~MonopartiteReacSynGraph.find_reactants_products
       ~MonopartiteReacSynGraph.get_leaves
       ~MonopartiteReacSynGraph.get_molecule_leaves
       ~MonopartiteReacSynGraph.get_molecule_roots
       ~MonopartiteReacSynGraph.get_roots
+      ~MonopartiteReacSynGraph.get_unique_nodes
+      ~MonopartiteReacSynGraph.initialize_with_iron
+      ~MonopartiteReacSynGraph.remove_isolated_ces
+      ~MonopartiteReacSynGraph.remove_node
       ~MonopartiteReacSynGraph.set_source
 
 

docs/source/reference/generated/linchemin.cgu.syngraph.SynGraph.rst

@@ -14,11 +14,17 @@
    .. autosummary::
 
       ~SynGraph.__init__
+      ~SynGraph.add_molecular_roots
       ~SynGraph.add_node
+      ~SynGraph.build_chemical_equations
       ~SynGraph.builder_from_iron
       ~SynGraph.builder_from_reaction_list
+      ~SynGraph.find_reactants_products
       ~SynGraph.get_leaves
       ~SynGraph.get_roots
+      ~SynGraph.get_unique_nodes
+      ~SynGraph.initialize_with_iron
+      ~SynGraph.remove_node
       ~SynGraph.set_source
 
 

docs/source/reference/generated/linchemin.cgu.translate.AbsTranslator.rst

@@ -14,7 +14,9 @@
    .. autosummary::
 
       ~AbsTranslator.__init__
+      ~AbsTranslator.build_iron_node
       ~AbsTranslator.from_iron
+      ~AbsTranslator.get_node_info
       ~AbsTranslator.to_iron