From 089d4a6d8fe525f3c0459f0998e5b66de0d24130 Mon Sep 17 00:00:00 2001
From: "Genheden, Samuel" <samuel.genheden@astrazeneca.com>
Date: Fri, 8 Mar 2024 12:21:09 +0100
Subject: [PATCH] Adding docs

---
 docs/index.rst  |  4 ++-
 docs/routes.rst | 68 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 docs/routes.rst

diff --git a/docs/index.rst b/docs/index.rst
index 602ad44..9981c85 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ The package is divided into (currently) three sub-packages:
 * `chem` - chemistry routines like template extraction or reaction cleaning
 * `data` - routines for manipulating various reaction data sources
 * `pipeline` - routines for building and executing simple pipelines for modifying and analyzing reactions
+* `routes` - routines for handling synthesis routes
 
 Auto-generated API documentation is available, as well as guides for common tasks.  See the menu to the left.
 
@@ -60,4 +61,5 @@ Limitations
     uspto
     ord
     pipeline
-    rxnutils
+    routes
+    rxnutils
\ No newline at end of file
diff --git a/docs/routes.rst b/docs/routes.rst
new file mode 100644
index 0000000..de1980a
--- /dev/null
+++ b/docs/routes.rst
@@ -0,0 +1,68 @@
+Routes
+======
+
+``rxnutils`` contains routines to analyse synthesis routes. There are a number of readers that can be used to read routes from a number of 
+formats, and there are routines to score the different routes.
+
+Reading
+-------
+
+The simplest route format supported is a text file, where each reaction is written as a reaction SMILES on a line. 
+Routes are separated by comma
+
+For instance:
+
+.. code-block::
+
+    CC(C)N.Clc1cccc(Nc2ccoc2)n1>>CC(C)Nc1cccc(Nc2ccoc2)n1
+    Brc1ccoc1.Nc1cccc(Cl)n1>>Clc1cccc(Nc2ccoc2)n1
+
+    Nc1cccc(NC(C)C)n1.Brc1ccoc1>>CC(C)Nc1cccc(Nc2ccoc2)n1
+    CC(C)N.Nc1cccc(Cl)n1>>Nc1cccc(NC(C)C)n1
+
+
+If this is saved to ``routes.txt``, these can be read into route objects with 
+
+.. code-block::
+
+    from rxnutils.routes.readers import read_reaction_lists
+    routes = read_reaction_lists("reactions.txt")
+
+
+If you have an environment with ``rxnmapper`` installed and the NextMove software ``namerxn`` in your PATH then you can
+add atom-mapping and reaction classes to these routes with
+
+.. code-block::
+
+    # This can be set on the command-line as well
+    import os
+    os.environ["RXNMAPPER_ENV_PATH"] = "/home/username/miniconda/envs/rxnmapper/"
+
+    for route in routes:
+        route.assign_atom_mapping(only_rxnmapper=True)
+    routes[1].remap(routes[0])
+
+
+The last line of code also make sure that the second route shares mapping with the first route. 
+
+
+Othe readers are available
+
+* ``read_aizynthcli_dataframe`` - for reading routes from aizynthcli output dataframe
+* ``read_reactions_dataframe`` - for reading routes stored as reactions in a dataframe
+
+
+For instance, to read routes from a dataframe with reactions. You can do something like what follows.
+The dataframe has column ``reaction_smiles`` that holds the reaction SMILES, and the individual routes
+are identified by a ``target_smiles`` and ``route_id`` column. The dataframe also has a column ``classification``,
+holding the NextMove classification. The dataframe is called ``data``.
+
+.. code-block::
+
+    from rxnutils.routes.readers import read_reactions_dataframe
+    routes = read_reactions_dataframe(
+        data, 
+        "reaction_smiles", 
+        group_by=["target_smiles", "route_id"], 
+        metadata_columns=["classification"]
+    )