Updated documentation for readthedocs

lobolab · Apr 24, 2023 · 31d81ec · 31d81ec
1 parent 2af0ee8
commit 31d81ec
Show file tree

Hide file tree

Showing 8 changed files with 124 additions and 4 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,11 +18,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'mergem'
-copyright = '2022, The Lobo Lab'
+copyright = '2023, The Lobo Lab'
 author = 'The Lobo Lab'
 
 # The full version, including alpha/beta/rc tags
-release = '0.21'
+release = '0.22'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,76 @@
+**********************************
+Use examples
+**********************************
+
+Running on Command-line
+========================================
+
+Merging reconstructions built using different templates
+--------------------------------------------------------------------------------
+To compare the effect of reconstruction parameters, we merged two P. putida draft
+reconstructions built on ModelSEED using either a gram-positive or core template.
+
+::
+
+    mergem -v MS1_PPU.sbml MS2_PPU.sml -o MS1_MS2_merged_PPU.xml
+
+Results from merging the two reconstructions on the command-line using mergem are
+shown below.
+
+.. code-block:: none
+
+    Merging models complete. Merged model saved as MS1_MS2_merged_PPU.xml
+    Jaccard distance matrix: [[0, 0.02425267907501405], [0.049657534246575374, 0]]
+    Metabolites merged: 1730
+    Reactions merged: 1666
+
+
+The figure below shows the same merging on the web-application Fluxer and can be
+accessed `here <https://fluxer.umbc.edu/model?id=7fe8a8e65427f5f30412cc3341b5ec596e956f42_8483528fcd5891b944d53a6e4f61214acb596f42_obj_merge>`_.
+
+.. image:: fluxerMergingMS1MS2PPU.png
+    :width: 700
+
+
+Importing Python package
+========================================
+
+Studying model versions
+---------------------------
+
+Different versions of models can be compared to analyze elements that were added or removed during update.
+The results of comparing three versions of a P. putida KT2400 model using mergem on the Python console are
+shown below:
+
+::
+
+    import mergem
+
+    input_models_list = ['models/iJN1463.xml', 'models/iJN746.xml', 'models/MNX_iJN746.sbml']
+    merge_results = mergem.merge(input_models_list, set_objective='merge')
+
+    print('Number of metabolites in merged model: ', len(merge_results['merged_model'].metabolites))
+    print('Number of reactions in merged model: ', len(merge_results['merged_model'].reactions))
+
+    print("Jaccard matrix: \n", merge_results['jacc_matrix'])
+
+    print('Number of metabolites merged between input models: ', merge_results['num_met_merged'])
+    print('Number of reactions merged between input models: ', merge_results['num_reac_merged'])
+
+Running the above script produces the following output:
+
+::
+
+    Number of metabolites in merged model:  2186
+    Number of reactions in merged model:  3001
+    Jaccard matrix:
+    [[0, 0.5976168652612283, 0.5986270022883295], [0.6765588529509836, 0, 0.00658616904500553], [0.679, 0.01526717557251911, 0]]
+    Number of metabolites merged between input models:  1783
+    Number of reactions merged between input models:  2024
+
+The same result including the Jaccard matrix can be visualized on Fluxer as shown below:
+
+.. image:: fluxerMergingModelUpdatesPPU.png
+    :width: 700
+
+The above Fluxer result can be accessed `here <https://fluxer.umbc.edu/model?id=f4f30bd4265c5734d98b719ce39e0dbbd5d4ecfb_0bab56f8be08a3d62f24dd16c00b6b01fd85cb27_7fe25baa10e0f3ee212b5b8b4edc4742e5ebfd8b_obj_merge>`_.
diff --git a/docs/source/fluxerMergingMS1MS2PPU.png b/docs/source/fluxerMergingMS1MS2PPU.png
diff --git a/docs/source/fluxerMergingModelUpdatesPPU.png b/docs/source/fluxerMergingModelUpdatesPPU.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -31,6 +31,8 @@ Documentation for Fluxer based merging can be found on its `tutorial page <https
    output
    visualize
    update
+   mapper
+   examples
    citation
    acknowledgements
    license

diff --git a/docs/source/mapper.rst b/docs/source/mapper.rst
@@ -0,0 +1,42 @@
+*******************************
+Save ID mapping tables
+*******************************
+
+Saving mappers from the command-line
+========================================
+
+The database ID mapping tables can be downloaded as csv files. Each file contains all the
+universal IDs for either metabolites or reactions followed by the corresponding cross-referenced
+identifiers in other databases.
+
+The ID mapping tables are saved as :file:`mergem_univ_id_mapper_metabolites.csv` and
+:file:`mergem_univ_id_mapper_reactions.csv` in the working directory.
+
+The :code:`-s` argument can be used to save the ID mapping tables on the command line:
+
+::
+
+    mergem -s
+
+Saving mappers using Python script
+========================================
+
+When importing mergem into a python script, the :code:`save_mapping_tables()` function can be called to
+save the mapping tables as shown below:
+
+::
+
+    import mergem
+
+    mergem.save_mapping_tables()
+
+
+Custom filenames for saving ID mappers
+------------------------------------------
+
+The mapping table filenames can be customized by providing the desired filenames as input to the
+function.
+
+::
+
+   mergem.save_mapping_tables('custom_met_mapper_filename.csv', 'custom_reac_mapper_filename.csv')
diff --git a/docs/source/output.rst b/docs/source/output.rst
@@ -48,7 +48,7 @@ Statistics are printed in the format as shown in the example below:
 
 ::
 
-    Model (Met, Reac) jaccard distances: [(0, 0), (0, 0)]
+    Jaccard distance matrix: [[0, 0], [0, 0]]
     Mets merged: 72
     Reacs merged: 94
 

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -11,7 +11,7 @@ model.
 
 .. _cli:
 
-Command-line execution
+Command-line
 ==========================
 Once mergem has been installed using pip, the following commands can be run on the command-line.
 Printing help text displays all the options.