Merge branch 'release'

NEWS.md

@@ -1,4 +1,28 @@
 
+v0.25 (2016-10-28)
+------------------
+
+- Fixed an error parsing decimal values in reactions which resulted in a
+  failure to run FBA and other analyses on certain models.
+- The `fastgapfill` command no longer tries to unblock exchange reactions by
+  default. Only internal reactions will be unblocked by default.
+- The `fastgapfill` command has a new `--subset` option to explicitly specify
+  set of reactions to unblock. This means that the command can now be used to
+  unblock a specific reaction.
+- The weight options on `fastgapfill` have changed name to `--db-penalty`,
+  `--tp-penalty` and `--ex-penalty` for consistency with the existing
+  `--penalty` option.
+- Fixed an error in `gapfill` that in some cases would result in a compound
+  incorrectly marked as non-blocked.
+- The `sbmlexport` command now follows the FBCv2 specification for writing
+  flux bounds, biomass reaction, gene products and various other properties to
+  SBML files.
+- The `sbmlexport` command now uses the same ID for compartment IDs as used
+  in the YAML files.
+- The order of compounds in the output from commands now reflects the order
+  of compounds in the reactions as specified in the model files.
+- Experimental support for solving MILP problems with GLPK has been activated.
+
 v0.24 (2016-08-23)
 ------------------
 - When specifying flux bounds in media and limits, the `fixed` key can now be

docs/commands.rst

@@ -63,7 +63,7 @@ Flux balance analysis (``fba``)
 
 This command will try to maximize the flux of the biomass reaction defined in
 the model. It is also possible to provide a different reaction on the command
-line to maximize.
+line to maximize. [Orth10]_ [Fell86]_
 
 To run FBA use:
 
@@ -80,13 +80,13 @@ 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. Loop
-removal is more time-consuming and under normal cicumstances the biomass
-reaction flux will *not* change in response to the loop removal (only internal
-reaction fluxes may change). The ``--loop-removal`` option is followed by
-``none`` (no loop removal), ``tfba`` (removal using thermodynamic constraints),
-or ``l1min`` (L1 minimization of the fluxes). For example, the following
-command performs an FBA with thermodynamic constraints:
+internal reactions is further constrained to remove internal loops
+[Schilling00]_. Loop removal is more time-consuming and under normal
+cicumstances the biomass reaction flux will *not* change in response to the
+loop removal (only internal reaction fluxes may change). The ``--loop-removal``
+option is followed by ``none`` (no loop removal), ``tfba`` (removal using
+thermodynamic constraints), or ``l1min`` (L1 minimization of the fluxes). For
+example, the following command performs an FBA with thermodynamic constraints:
 
 .. code-block:: shell
 
@@ -96,9 +96,9 @@ Flux variability analysis (``fva``)
 -----------------------------------
 
 This command will find the possible flux range of each reaction when the
-biomass is at the maximum value. The command will use the biomass reaction
-specified in the model definition, or alternatively, a reaction can be given on
-the command line.
+biomass is at the maximum value [Mahadevan03]_. The command will use the
+biomass reaction specified in the model definition, or alternatively, a
+reaction can be given on the command line.
 
 .. code-block:: shell
 
@@ -116,15 +116,16 @@ maximum of 1000 units.
 
 If the parameter ``--tfba`` is given, additonal thermodynamic constraints will
 be imposed when evaluating model fluxes. This automatically removes internal
-flux loops but is much more time-consuming.
+flux loops [Schilling00]_ but is much more time-consuming.
 
 Robustness (``robustness``)
 ---------------------------
 
 Given a reaction to maximize and a reaction to vary, the robustness analysis
 will run flux balance analysis and flux minimization while fixing the reaction
 to vary at each iteration. The reaction will be fixed at a given number of
-steps between the minimum and maximum flux value specified in the model.
+steps between the minimum and maximum flux value specified in the model
+[Edwards00]_.
 
 .. code-block:: shell
 
@@ -213,7 +214,8 @@ Flux coupling analysis (``fluxcoupling``)
 
 The flux coupling analysis identifies any reaction pairs where the flux of one
 reaction constrains the flux of another reaction. The reactions can be coupled
-in three distinct ways depending on the ratio between the reaction fluxes.
+in three distinct ways depending on the ratio between the reaction fluxes
+[Burgard04]_.
 
 The reactions can be fully coupled (the ratio is static and non-zero);
 partially coupled (the ratio is bounded and non-zero); or directionally
@@ -230,7 +232,7 @@ A model or reaction database can be checked for stoichiometric inconsistencies
 (mass inconsistencies). The basic idea is that we should be able to assign a
 positive mass to each compound in the model and have each reaction be balanced
 with respect to these mass assignments. If it can be shown that assigning the
-masses is impossible, we have discovered an inconsistency.
+masses is impossible, we have discovered an inconsistency [Gevorgyan08]_.
 
 Some variants of this idea is implemented in the :mod:`psamm.massconsistency`
 module. The mass consistency check can be run using
@@ -350,7 +352,7 @@ algorithm will try to compute an extension of the model with reactions from the
 reaction database and try to find a minimal subset that allows all blocked
 compounds to be produced. This command will run GapFind to identify the blocked
 compounds and then uses GapFill to try to reconstruct a model that allows these
-compounds to be produced.
+compounds to be produced [Kumar07]_.
 
 .. code-block:: shell
 
@@ -370,7 +372,7 @@ The FastGapFill algorithm tries to reconstruct a flux consistent model (i.e. a
 model where every reaction takes a non-zero flux for at least one solutions).
 This is done by extending the model with reactions from the reaction database
 and trying to find a minimal subset that is flux consistent. The solution is
-approximate.
+approximate [Thiele14]_.
 
 The database reactions can be assigned a weight (or "cost") using the
 ``--penalty`` option. These weights are taken into account when determining the
@@ -389,6 +391,24 @@ Exports the model to the SBML file format.
 
     $ psamm-model sbmlexport > model.xml
 
+Excel Export (``excelexport``)
+------------------------------
+
+Exports the model to the Excel file format.
+
+.. code-block:: shell
+
+    $ psamm-model excelexport model.xls
+
+Table Export (``tableexport``)
+------------------------------
+
+Exports the model to the tsv file format.
+
+.. code-block:: shell
+
+    $ psamm-model tableexport reactions > model.tsv
+
 Search (``search``)
 -------------------
 

docs/file_format.rst

@@ -38,6 +38,16 @@ The optional ``extracellular`` key specifies the default string for
 the extracellular compartment on compounds. If this option is not
 specified it will be assumed that the extracellular compartment is called ``e``.
 
+Default Compartment
+--------------------------
+
+The optional ``default_compartment`` key specifies the default compartment
+that is used if a compound in a reaction does not explicitly specify a
+compartment.  For example, the reaction ``|x[e]| + |atp| => |x| + |adp| + |pi|``
+does not specify a compartment on four of the compounds so those four would
+automatically be presumed to be in the default compartment (or ``c`` if no default
+compartment is specified).
+
 Compounds
 ---------
 
@@ -203,7 +213,8 @@ The optional ``limits`` property lists the files that are to be combined and
 applied as the reaction flux limits. This can be used to limit certain
 reactions in the model. The following fragment is an example of a limits file
 in the YAML format. The lower and upper specifies the flux bounds and they are
-both optional:
+both optional. The fixed key is a shortcut to set both lower and upper to its
+value:
 
 .. code-block:: yaml
 
@@ -212,6 +223,8 @@ both optional:
     - reaction: ADE2t
       lower: -50
       upper: 50
+    - reaction: DHPTDNRN
+      fixed: 0
 
 The limits can also be specified using a TSV-file as shown in the following
 fragment::

docs/references.rst

@@ -5,15 +5,31 @@ References
 .. [Burgard04] Burgard AP, Nikolaev E V, Schilling CH, Maranas CD. Flux
     coupling analysis of genome-scale metabolic network reconstructions.
     Genome Res. 2004;14: 301–312. :doi:`10.1101/gr.1926504`.
+.. [Edwards00] Edwards JS, Palsson BO. Robustness Analysis of the Escherichia
+    coli Metabolic Network. Biotechnol Prog. American Chemical Society;
+    2000;16: 927–939. :doi:`10.1021/bp0000712`.
+.. [Fell86] Fell DA, Small JR. Fat synthesis in adipose tissue. An examination
+    of stoichiometric constraints. Biochem J. 1986;238.
+    :doi:`10.1042/bj2380781`.
 .. [Gevorgyan08] Gevorgyan A, Poolman MG, Fell DA. Detection of stoichiometric
     inconsistencies in biomolecular models. Bioinformatics. 2008;24: 2245–2251.
     :doi:`10.1093/bioinformatics/btn425`.
 .. [Kumar07] Satish Kumar V, Dasika MS, Maranas CD. Optimization based
     automated curation of metabolic reconstructions. BMC Bioinformatics.
     2007;8: 212. :doi:`10.1186/1471-2105-8-212`.
+.. [Mahadevan03] Mahadevan R, Schilling CH. The effects of alternate optimal
+    solutions in constraint-based genome-scale metabolic models. Metab Eng.
+    2003;5: 264–276. :doi:`10.1016/j.ymben.2003.09.002`.
 .. [Muller13] Müller AC, Bockmayr A. Fast thermodynamically constrained flux
     variability analysis. Bioinformatics. 2013;29: 903–909.
     :doi:`10.1093/bioinformatics/btt059`.
+.. [Orth10] Orth JD, Thiele I, Palsson BØ. What is flux balance analysis? Nat
+    Biotechnol. Nature Publishing Group; 2010;28: 245–8.
+    :doi:`10.1038/nbt.1614`.
+.. [Schilling00] Schilling CH, Letscher D, Palsson BO. Theory for the systemic
+    definition of metabolic pathways and their use in interpreting metabolic
+    function from a pathway-oriented perspective. J Theor Biol. 2000;203:
+    229–48. :doi:`10.1006/jtbi.2000.1073`.
 .. [Thiele14] Thiele I, Vlassis N, Fleming RMT. fastGapFill: efficient gap
     filling in metabolic networks. Bioinformatics. 2014;30: 2529–31.
     :doi:`10.1093/bioinformatics/btu321`.