Merge branch 'release'

.travis.yml

@@ -1,3 +1,4 @@
+sudo: false
 language: python
 cache:
     directories:
@@ -30,12 +31,32 @@ install:
 
 script: tox -v
 after_success: coveralls
-env:
-    - TOXENV=py27-nosolver,py34-nosolver,coverage
-    - TOXENV=py27-qsoptex,py34-qsoptex,coverage
-    - TOXENV=py27-glpk,py34-glpk,coverage
-    - TOXENV=docs
-    - TOXENV=flake
+matrix:
+    include:
+        - env: TOXENV=flake
+
+        - env: TOXENV=py27-nosolver,coverage
+          python: '2.7'
+        - env: TOXENV=py27-glpk,coverage
+          python: '2.7'
+        - env: TOXENV=py27-qsoptex,coverage
+          python: '2.7'
+
+        - env: TOXENV=py35-nosolver,coverage
+          python: '3.5'
+        - env: TOXENV=py35-glpk,coverage
+          python: '3.5'
+        - env: TOXENV=py35-qsoptex,coverage
+          python: '3.5'
+
+        - env: TOXENV=py36-nosolver,coverage
+          python: '3.6'
+        - env: TOXENV=py36-glpk,coverage
+          python: '3.6'
+        - env: TOXENV=py36-qsoptex,coverage
+          python: '3.6'
+
+        - env: TOXENV=docs
 
 deploy:
     provider: pypi

NEWS.md

@@ -1,4 +1,47 @@
 
+v0.28 (2017-03-03)
+------------------
+
+- The YAML model format now allows users to specify compartment information and
+  compartment boundaries in the `model.yaml` file. See the file format
+  documentation for more information.
+- The `media` key in the `model.yaml` has changed name to `exchange` to
+  reflect the fact that not only uptake exchange must be defined here. The
+  `media` key is still supported but has been deprecated.
+- The gap-filling command `gapfill` and `fastgapfill` now use the compartment
+  information to determine which artificial transport and exchange reactions
+  to add. This means that a model *must* specify compartments and compartment
+  boundaries when using gap-filling commands.
+- The `gapcheck` command now has two new methods for detecting blocked
+  compounds. The new `prodcheck` is a more robust version of the GapFind check
+  which was previously used. The new `sinkcheck` method will find compounds
+  that cannot be produced in excess. This can find some additional blocked
+  compounds that were not detected by the other methods.
+- The `gapcheck` command now reports blocked compounds in the extracellular
+  space. Previously, these compounds were excluded. An option is available to
+  switch back the old behavior of excluding these from the final output.
+- The `gapcheck` command now has an option to run the check with unrestricted
+  exchange reactions.
+- The `gapfill` command can now be run without implicit sinks. This makes it
+  possible to use this command to solve additional model gaps. It is still
+  recommended to first solve gaps using implicit sinks, then later disable
+  implicit sinks when all other gaps have been closed.
+- The `gapfill` command now has an option to enable the bounds expansion
+  proposals (e.g. making irreversible reactions reversible). By default this
+  option is now off.
+- The `fastgapfill` has improved output that contains less superfluous
+  information. The output format is now identical to the `gapfill` command.
+  The `fastgapfill` also no longer runs an FBA on the induced model since this
+  caused some confusion.
+- Added new command `checkduplicates` which detects whether the model has
+  multiple reactions with the same (or similar) reaction equation.
+- The `sbmlexport` command now allows the user to specify a file path. The
+  command can also optionally output the SBML file in a more readable format
+  with an option.
+- Fixed support for the latest CPLEX release 12.7. A change in their API made
+  PSAMM incompatible with the 12.7 release. This is now fixed.
+- We now officially support Python 3.5 and Python 3.6.
+
 v0.27 (2016-12-23)
 ------------------
 

docs/api/datasource_context.rst

@@ -0,0 +1,6 @@
+
+``psamm.datasource.context`` -- File system contexts
+====================================================
+
+.. automodule:: psamm.datasource.context
+   :members:

docs/api/datasource_entry.rst

@@ -0,0 +1,6 @@
+
+``psamm.datasource.entry`` -- Model entry representations
+=========================================================
+
+.. automodule:: psamm.datasource.entry
+   :members:

docs/api/lpsolver_cplex.rst

@@ -1,5 +1,5 @@
 
-``psamm.lpsolver.cplex`` -- Cplex LP solver
+``psamm.lpsolver.cplex`` -- CPLEX LP solver
 ============================================
 
 .. automodule:: psamm.lpsolver.cplex

docs/api/lpsolver_glpk.rst

@@ -0,0 +1,6 @@
+
+``psamm.lpsolver.glpk`` -- GLPK LP solver
+============================================
+
+.. automodule:: psamm.lpsolver.glpk
+   :members:

docs/api/util.rst

@@ -0,0 +1,6 @@
+
+``psamm.util`` -- Internal utilities
+====================================
+
+.. automodule:: psamm.util
+   :members:

docs/commands.rst

@@ -344,6 +344,20 @@ 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``)
+-----------------------------------------------
+
+This command simply checks whether multiple reactions exist in the model that
+have the same or similar reaction equations. By default, this check will ignore
+reaction directionality and stoichiometric values when considering whether
+reactions are identical. The options ``--compare-direction`` and
+``--compare-stoichiometry`` can be used to make the command consider these
+properties as well.
+
+.. code-block:: shell
+
+    $ psamm-model duplicatescheck
+
 Gap check (``gapcheck``)
 ------------------------
 
@@ -362,7 +376,25 @@ every compound to also be consumed by another reaction (in other words, for
 the purpose of this analysis there are implicit sinks for every compound in
 the model). This means that even if this command reports that no compounds are
 blocked, it may still not be possible for the model to be viable under the
-steady-state assumption of FBA.
+steady-state assumption of FBA. The option ``--no-implicit-sinks`` can be used
+to perform the gap check without implicit sinks.
+
+The gap check is performed with the medium that is defined in the model. It
+may be useful to run the gap check with every compound in the medium available.
+This can easily be done by specifying the ``--unrestricted-exchange`` option
+which removes all limits on the exchange reactions during the check.
+
+There are some additional gap checking methods that can be enabled with the
+``--method`` option. The method ``sinkcheck`` can be used to find compounds
+that cannot be synthesized from scratch. The standard gap check will report
+compounds as produced if they can participate in a reaction, even if the
+compound itself cannot be synthesized from precursors in the medium. To find
+such compounds use the ``sinkcheck``. This check will generally indicate more
+compounds as blocked. Lastly, the method ``gapfind`` can be used. This method
+should produce the same result as the default method but is implemented in an
+alternative way that is specified in [Kumar07]_. This method is *not* used by
+default because it tends to result in difficulties for the solver when used
+with larger models.
 
 GapFill (``gapfill``)
 ---------------------
@@ -380,9 +412,10 @@ command is a variant of the gap-filling procedure described in [Kumar07]_.
 
 The command will first list the reactions in the model followed by the
 suggested reactions to add to the model in order to unblock the blocked
-compounds. The procedure may also suggest that existing model reactions have
-their flux bounds widened, e.g. making an existing irreversible reaction
-reversible. To unblock only specific compounds, use the ``--compound`` option:
+compounds. If ``--allow-bounds-expansion`` is specified, the procedure may also
+suggest that existing model reactions have their flux bounds widened, e.g.
+making an existing irreversible reaction reversible. To unblock only specific
+compounds, use the ``--compound`` option:
 
 .. code-block:: shell
 
@@ -401,6 +434,12 @@ file name with ``@``.
 The GapFind algorithm is defined in terms of a MILP problem and can therefore
 be computationally expensive to run for larger models.
 
+The original GapFill algorithm uses a solution procedure which implicitly
+assumes that the model contains implicit sinks for all compounds. This means
+that even with the reactions proposed by GapFill the model may need to produce
+compounds that cannot be used anywhere. The implicit sinks can be disabled
+with the ``--no-implicit-sinks`` option.
+
 FastGapFill (``fastgapfill``)
 -----------------------------
 
@@ -425,7 +464,11 @@ Exports the model to the SBML file format.
 
 .. code-block:: shell
 
-    $ psamm-model sbmlexport > model.xml
+    $ psamm-model sbmlexport model.xml
+
+If the file name is omitted, the file contents will be output directly to the
+screen. Using the ``--pretty`` option makes the output formatted for
+readability.
 
 Excel Export (``excelexport``)
 ------------------------------

docs/conf.py

@@ -29,7 +29,7 @@
 
 # Mock optional modules to allow autodoc to run even in the absense of these
 # modules.
-MOCK_MODULES = ['cplex', 'qsoptex', 'gurobipy']
+MOCK_MODULES = ['cplex', 'gurobipy', 'qsoptex', 'swiglpk']
 for module in MOCK_MODULES:
     sys.modules[module] = mock.Mock()
 

docs/file_format.rst

@@ -12,16 +12,30 @@ used as a template:
     name: Escherichia coli test model
     biomass: Biomass
     extracellular: e
+
+    compartments:
+      - id: e
+        name: Extracellular
+      - id: p
+        name: Periplasm
+        adjacent_to: [e, c]
+      - id: c
+        name: Cytosol
+        adjacent_to: p
+
     compounds:
       - include: ../path/to/ModelSEED_cpds.tsv
         format: modelseed
+
     reactions:
       - include: reactions/reactions.tsv
       - include: reactions/biomass.yaml
-    media:
-      - include: medium.yaml
+
+    exchange:
+      - include: exchange.yaml
     limits:
       - include: limits.yaml
+
     model:
       - include: model_def.tsv
 
@@ -48,6 +62,17 @@ 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).
 
+Compartments
+------------
+
+The ``compartments`` key is a list of compartment information for the model.
+Compartments must always have an ``id`` but can also have additional user
+defined properties. The ``adjacent_to`` property is used to define the
+boundaries between compartments. Notice that the adjacency can be specified as
+a single compartment or a list of compartments. Note that it is sufficient to
+specify that ``p`` is adjacent to ``e``. It is then inferred that ``e`` is
+adjacent to ``p`` so it is optional to specify both directions of adjacency.
+
 Compounds
 ---------
 
@@ -163,13 +188,21 @@ group of genes or when multiple genes can independently enable a reaction:
       equation: '|amp| + |atp| <=> (2) |adp|'
       genes: gene_0001 or (gene_0002 and gene_0003)
 
-Media
------
+Exchange compounds
+------------------
+
+The ``exchange`` key provides a way of defining the compounds that can
+enter and exit the model system (the boundary conditions). This includes
+compounds that can enter the system (*the medium*) and compounds that are
+allowed to exit the system, like metabolic byproducts. In most cases, all
+compounds that occur in the extracellular space should also be defined in the
+exchange compounds (with lower limit of zero) so that they are allowed to
+leave the model system, and PSAMM will generate a warning if this is not the
+case for some compounds. Compounds that are allowed to be taken up
+(*the medium*) should in addition be specified with a negative lower limit
+indicating the maximum allowed uptake.
 
-The optional ``media`` key provides a way of defining the medium (boundary
-conditions) for the model. The medium is defined by a set of compounds that are
-able enter or leave the model system. The following fragment is an example of
-the ``medium.yaml`` file:
+The following fragment is an example of the ``exchange.yaml`` file:
 
 .. code-block:: yaml
 
@@ -180,21 +213,18 @@ the ``medium.yaml`` file:
       - id: o2
       - id: glcD    # D-Glucose with uptake limit of 10
         lower: -10
-      - id: compound_x
-        compartment: c
-        lower: 0    # Provide a sink for compound_x
       # ...
 
-When a medium file is specified, the corresponding exchange reactions are
+When an exchange file is specified, the corresponding exchange reactions are
 automatically added. For example, if the compounds ``o2`` in compartment ``e``
-is in the medium, the exchange reaction ``EX_o2_e`` is added to the model. The
-desired ID for the exchange reaction can be set explicitly using the
+is in the exchange file, the exchange reaction ``EX_o2_e`` is added to the
+model. The desired ID for the exchange reaction can be set explicitly using the
 ``reaction`` attribute.
 
-The medium can also be specified using a TSV-file as the following fragment
-shows. The second column specifies the compartment while third and fourth
-columns specify the lower and upper bounds, respectively. Both can be omitted
-or specified as ``-`` to use the default flux bounds::
+The exchange set can also be specified using a TSV-file as the following
+fragment shows. The second column specifies the compartment while third and
+fourth columns specify the lower and upper bounds, respectively. Both can be
+omitted or specified as ``-`` to use the default flux bounds::
 
     # Acetate exchange with default lower and upper bounds
     ac      e
@@ -203,8 +233,9 @@ or specified as ``-`` to use the default flux bounds::
     # CO2 exchange with production limit of 50 and default uptake limit
     co2     e       -       50
 
-Multiple medium files can be included from the main ``model.yaml`` file, and
-these will be combined to form the final medium used for the simulations.
+Multiple exchange files can be included from the main ``exchange.yaml`` file,
+and these will be combined to form the final set of exchange reactions used for
+the simulations.
 
 Reaction flux limits
 --------------------