Merge branch 'release'

Author: yingzhanguri

.travis.yml

@@ -1,4 +1,4 @@
-sudo: false
+dist: trusty
 language: python
 cache:
     directories:
@@ -9,7 +9,9 @@ addons:
         packages:
             - libgmp-dev
             - libgmp10
-            - glpk
+            - libglpk36
+            - libglpk-dev
+            - glpk-utils
             - swig
 
 install:
@@ -28,7 +30,8 @@ install:
       fi
 
     - pip install tox coveralls
-
+    - pip install tox-travis
+    - pip install --upgrade six
 script: tox -v
 after_success: coveralls
 matrix:

NEWS.md

@@ -1,3 +1,21 @@
+v1.0 (2020-03-03)
+------------------
+
+- Adds the new `modelmapping` command for mapping reactions and
+  compounds ids between different GEMs.
+- Adds the new `psammotate` command for generating draft GEMs
+  using a template model and a mapping of orthologous genes to
+  another organism.
+- Adds the new `gimme` command which implements the GIMME algorithm
+  as described in Becker and Palsson, 2008 (PMID: 18483554).
+- Updates the `search` command to allow for searching of strings
+  within any reaction or compound property.
+- Updates to the `tableexport` and `excelexport` commands to allow
+  for the export of additional gene and reaction information.
+- Adds new section to the tutorial to detail how to use the
+  `findprimarypairs` commands.
+- Renamed `duplicatescheck` command to `dupcheck`.
+
 v0.31 (2017-06-30)
 ------------------
 

docs/api/bayesian.rst

@@ -0,0 +1,6 @@
+
+``psamm.bayesian`` -- Bayesian Matching Functions
+=================================================
+
+.. automodule:: psamm.bayesian
+   :members:

docs/api/bayesian_util.rst

@@ -0,0 +1,6 @@
+
+``psamm.bayesian_util`` -- Bayesian Matching Utility Functions
+==============================================================
+
+.. automodule:: psamm.bayesian_util
+   :members:

docs/api/graph.rst

@@ -0,0 +1,6 @@
+
+``psamm.graph`` -- Graph Related Functions
+===========================================
+
+.. automodule:: psamm.graph
+   :members:

docs/api/importer.rst

@@ -0,0 +1,6 @@
+
+``psamm.importer`` -- Import Functions
+=============================================
+
+.. automodule:: psamm.importer
+   :members:

docs/api/manual_curation.rst

@@ -0,0 +1,6 @@
+
+``psamm.manual_curation`` -- Model Mapping Curation
+===================================================
+
+.. automodule:: psamm.manual_curation
+   :members:

docs/api/mapmaker.rst

@@ -0,0 +1,6 @@
+
+``psamm.mapmaker`` -- Mapmaker Functions
+===================================================
+
+.. automodule:: psamm.mapmaker
+   :members:

docs/api/translate_id.rst

@@ -0,0 +1,6 @@
+
+``psamm.translate_id`` -- ID Translation Functions
+===================================================
+
+.. automodule:: psamm.translate_id
+   :members:

docs/commands.rst

@@ -11,9 +11,9 @@ The tools that can be applied to metabolic models are run through the
 
 This program allows you to specify a metabolic model and a command to apply to
 the given model. The available commands can be seen using the help command
-given above, and are also described in more details below.
+given above, and are also described in more detail below.
 
-To run the program with a model, use
+To run the program with a model, use the following command:
 
 .. code-block:: shell
 
@@ -37,7 +37,7 @@ Linear programming solver
 -------------------------
 
 Many of the commands described below use a linear programming (LP) solver in
-order to perform the analysis. These commands all take an option `--solver`
+order to perform the analysis. These commands all take an option ``--solver``
 which can be used to select which solver to use and to specify additional
 options for the LP solver. For example, in order to run the ``fba`` command
 with the QSopt_ex solver, the option ``--solver name=qsoptex`` can be added:
@@ -47,9 +47,9 @@ with the QSopt_ex solver, the option ``--solver name=qsoptex`` can be added:
     $ psamm-model fba --solver name=qsoptex
 
 The ``--solver`` option can also be used to specify additional options for the
-solver in use. For example, the Cplex solver recognizes the ``threads``
-option which can be used to adjust the maximum number of threads that Cplex
-will use internally (by default, Cplex will use as many threads as there are
+solver in use. For example, the CPLEX solver recognizes the ``threads``
+option which can be used to adjust the maximum number of threads that CPLEX
+will use internally (by default, CPLEX will use as many threads as there are
 cores on the computer):
 
 .. code-block:: shell
@@ -79,8 +79,8 @@ or with a specific reaction:
 
 By default, this performs a standard FBA and the result is output as
 tab-separated values with the reaction ID, the reaction flux and the reaction
-equation. If the parameter ``--loop-removal`` is given, the flux of the
-internal reactions is further constrained to remove internal loops
+equation. If the parameter ``--loop-removal`` is given, the fluxes of the
+internal reactions are further constrained to remove internal loops
 [Schilling00]_. Loop removal is more time-consuming and under normal
 circumstances the biomass reaction flux will *not* change in response to the
 loop removal (only internal reaction fluxes may change). The ``--loop-removal``
@@ -92,6 +92,14 @@ example, the following command performs an FBA with thermodynamic constraints:
 
     $ psamm-model fba --loop-removal=tfba
 
+By default, the output of the FBA command will only display reactions which
+have non-zero fluxes. This can be overridden with the ``--all-reactions``
+option to display all reactions even if they have flux values of zero.
+
+.. code-block:: shell
+
+    $ psamm-model fba --all-reactions
+
 Flux variability analysis (``fva``)
 -----------------------------------
 
@@ -114,10 +122,31 @@ In this example the ``PPCK`` reaction has a minimum flux of zero and maximum
 flux of 135.3 units. The ``PTAr`` reaction has a minimum flux of 62.3 and a
 maximum of 1000 units.
 
-If the parameter ``--loop-removal=tfba`` is given, additonal thermodynamic
+If the parameter ``--loop-removal=tfba`` is given, additional thermodynamic
 constraints will be imposed when evaluating model fluxes. This automatically
 removes internal flux loops [Schilling00]_ but is much more time-consuming.
 
+By default, FVA is performed with the objective reaction (either the biomass
+reaction or reaction given through the ``--objective`` option) fixed at its
+maximum value. It is also possible allow this reaction flux to vary by a
+specified amount through the ``--thershold`` option. When this option is
+used the variability results will show the possible flux ranges when the
+objective reaction is greater than or equal to the threshold value.
+
+The threshold can be specified by either giving a percentage of the maximum
+objective flux or by giving a defined flux value.
+
+.. code-block:: shell
+
+    $ psamm-model fva --threshold 90%
+    or
+    $ psamm-model fva --threshold 1.2
+
+The FVA command can also be run as parallel processes to speed up simulations
+done on larger models. This can be done using the ``--parallel`` option. Either
+a specific number of parallel jobs can be given or 0 can be given to
+automatically detect and use the maximum number of parallel processes.
+
 Robustness (``robustness``)
 ---------------------------
 
@@ -148,6 +177,16 @@ If the parameter ``--loop-removal`` is given, additional constraints on the
 model can be imposed that remove internal flux loops. See the section on the
 :ref:`commands-fba` command for more information on this option.
 
+It is also possible to print out the flux of all reactions for each step in
+the robustness simulation instead of just printing the varying reaction flux.
+This can be done through using the ``--all-reaction-fluxes`` option.
+
+The Robustness command can also be run as parallel processes to speed up
+simulations done on larger models. This can be done using the
+``--parallel`` option. Either a specific number of parallel jobs can
+be given or 0 can be given to automatically detect and use the maximum
+number of parallel processes.
+
 Random sparse network (``randomsparse``)
 ----------------------------------------
 
@@ -166,9 +205,20 @@ threshold. The tolerance can be specified as a relative value (as above) or as
 an absolute flux. Aggregating the results from multiple random sparse networks
 allows classifying reactions as essential, semi-essential or non-essential.
 
-If the option ``--exchange`` is given, the model will only try to delete
-exchange reactions. This can be used to provide putative minimal media for
-the model.
+By default, the randomsparse command will perform the deletions on reactions
+in the model. The ``--type`` option can be used to change this deletion to
+act on the genes in the model or to act on only the set of exchange reactions.
+The gene deletion option will remove a gene from a network and then assess
+which reactions would be affected by that gene loss based on the provided
+gene associations. The exchange reaction deletion will only delete reactions
+from the set of exchange reactions in the model and can be used to generate
+a putative minimal media for the model.
+
+.. code-block:: shell
+
+    $ psamm-model randomsparse --type genes 95%
+    or
+    $ psamm-model randomsparse --type exchange 95%
 
 The output of the command is a tab-separated list of reaction IDs and a value
 indicating whether the reaction was eliminated (``0`` when eliminated, ``1``
@@ -333,7 +383,7 @@ The output has now changed and the remaining residual has been shifted to
 another reaction. This iterative procedure can be continued until all
 stoichiometric inconsistencies have been corrected. In this example the
 `IR00149` reaction also had a missing `H+` for the reaction to balance. After
-fixing this error the model is consistent and the `H+` compounds can be
+fixing this error, the model is consistent and the `H+` compounds can be
 assigned a non-zero mass::
 
     $ psamm-model masscheck
@@ -386,7 +436,9 @@ constraints are imposed when considering whether reactions can take a non-zero
 flux. This automatically removes internal flux loops but is also much more
 time-consuming.
 
-Reaction duplicates check (``duplicatescheck``)
+Some reactions could
+
+Reaction duplicates check (``dupcheck``)
 -----------------------------------------------
 
 This command simply checks whether multiple reactions exist in the model that
@@ -398,7 +450,7 @@ properties as well.
 
 .. code-block:: shell
 
-    $ psamm-model duplicatescheck
+    $ psamm-model dupcheck
 
 Gap check (``gapcheck``)
 ------------------------
@@ -499,13 +551,37 @@ minimal solution.
 
     $ psamm-model fastgapfill --penalty penalty.tsv
 
+The penalty file provided should be a tab separated table that contains
+reaction IDs and assigned penalty values in two columns:
+
+.. code-block:: shell
+
+    RXN1    10
+    RXN2    15
+    RXN3    20
+    ....
+
+In addition to setting penalty values directly through the ``--penalty`` argument,
+default penalties for all other database reactions can be set through the
+``--db-penalty`` argument. Reactions that do not have penalty values
+explicitly set through the ``--penalty`` argument will be assigned
+this penalty value. Similarly, penalty values can be assigned for new
+exchange reactions and artificial transport reactions through the
+``--ex-penalty`` and ``--tp-penalty`` arguments. An example using
+all three of these arguments can be seen here:
+
+.. code-block:: shell
+
+    $ psamm-model fastgapfill --db-penalty 100 --tp-penalty 1000 --ex-penalty 150
+
+
 Predict primary pairs (``primarypairs``)
 ----------------------------------------------------------------------
 
 This command is used to predict element-transferring reactant/product pairs
 in the reactions of the model. This can be used to determine the flow of
 elements through reactions. Two methods for predicting the pairs are available:
-FindPrimaryPairs (``fpp``) [Steffensen17]_ and
+`FindPrimaryPairs` (``fpp``) [Steffensen17]_ and
 MapMaker (``mapmaker``) [Tervo16]_. The ``--method`` option can used to select
 which prediction method to use:
 
@@ -518,6 +594,21 @@ reactions ID, the second and third columns contain the compound ID of the
 reactant and product. The fourth column contains the predicted transfer of
 elements.
 
+The ``primarypairs`` command will run slowly on models that contain artificial
+reactions such as biomass reactions or condensed biosynthesis reactions.
+Because the reactant/product pair prediction in these reactions is
+not as biologically meaningful these reactions can be excluded through
+the ``--exclude`` option. This option can be used to either give reaction
+IDs to exclude or to give an input file containing a list of reactions
+IDs to exclude:
+
+.. code-block:: shell
+
+    $ psamm-model primarypairs --exclude BiomassReaction
+    or
+    $ psamm-model primarypairs --exclude @./exclude.tsv
+
+
 SBML Export (``sbmlexport``)
 ----------------------------
 
@@ -575,10 +666,25 @@ To search for a reaction use
 
 Use the ``--id`` option to search for a reaction with a specific identifier.
 The ``--compound`` option can be used to search for reactions that include a
-specific compound. If more that one compound identifier is given
+specific compound. If more than one compound identifier is given
 (comma-separated) this will find reactions that include all of the given
 compounds.
 
+PSAMM-SBML-Model
+----------------
+`PSAMM` normally takes a model in the `YAML` format as input. To deal with
+models that are in the `SBML` `PSAMM` includes various programs that allow
+users to convert these models to the `YAML` format. One additional option
+for dealing with models in the `SBML` format is using the `psamm-sbml-model`
+function. This function can be used to run any command normally accessed
+through `psamm-model` but with an `SBML` model as the input. To use this
+command the `SBML` model file needs to be specified first followed
+by the commands:
+
+.. code-block:: shell
+
+    $ psamm-sbml-model {model.xml} fba
+
 Console (``console``)
 ---------------------