Merge branch 'release'

zhanglab · Sep 1, 2015 · 0defa7d · 0defa7d
2 parents 803af24 + 7478ca7
commit 0defa7d
Show file tree

Hide file tree

Showing 61 changed files with 2,487 additions and 1,435 deletions.
diff --git a/.gitignore b/.gitignore
@@ -36,6 +36,7 @@ pip-delete-this-directory.txt
 htmlcov/
 .tox/
 .coverage
+.coverage.*
 .cache
 nosetests.xml
 coverage.xml

diff --git a/NEWS.md b/NEWS.md
@@ -1,4 +1,37 @@
 
+v0.12 (2015-09-01)
+------------------
+
+- Add support for the Gurobi LP solver (Python 2.7 only).
+- Fix a bug in the `fastgapfill` command that caused the biomass reaction to
+  never be found in the model.
+- Add command line tool `psamm-list-lpsolvers` which will list the available
+  solvers, and report their attributes and whether they can be successfully
+  loaded.
+- Change the way the threshold parameter on the `randomsparse` command is
+  parsed. A threshold relative to the maximum flux is now given using
+  percentage notation (e.g. `95%`) while an absolute flux threshold is given as
+  a number (e.g `1.34`).
+- Log the model name at the beginning of every command. If the model exists in
+  a Git repository, the current Git commit ID is also reported.
+- Produce warnings when encountering invalid SBML constructs using non-strict
+  parsing. Previously, some of these could only be noticed when using the
+  strict mode.
+- Improve error reports from commands. This means that usage information is now
+  printed when a command fails to parse an argument.
+- Improve the API in the `fluxanalysis` module to allow commands to more
+  easily reuse LP problems. This improves the speed of robustness analysis in
+  particular.
+- Improve and expand the install instructions in the documentation.
+- Reorganize implementations of commands into the `psamm.commands` package. The
+  commands are now discovered through the entry point mechanism from
+  `setuptools` allowing any package to install additional commands into the
+  PSAMM user interface.
+- Use a simpler output format for log messages unless the environment variable
+  `PSAMM_DEBUG` is set. If set, this variable determines the logging level
+  (e.g. `PSAMM_DEBUG=debug` enables more messages).
+- Include Python 3.3 in the tox test suite.
+
 v0.11 (2015-08-06)
 ------------------
 

diff --git a/README.rst b/README.rst
@@ -11,8 +11,10 @@ PSAMM metabolic modeling tools
    :alt: Package Status
    :target: https://pypi.python.org/pypi/psamm
 
-Tools related to metabolic modeling, reconstruction, data parsing and
-formatting, consistency checking, automatic gap filling, and model simulations.
+PSAMM is an open source software that is designed for the curation and analysis
+of metabolic models. It supports model version tracking, model annotation, data
+integration, data parsing and formatting, consistency checking, automatic gap
+filling, and model simulations.
 
 See NEWS_ for information on recent changes. The ``master`` branch
 tracks the latest release while the ``develop`` branch is the latest version in

diff --git a/docs/api.rst b/docs/api.rst
@@ -4,25 +4,6 @@ PSAMM API
 
 .. toctree::
    :maxdepth: 2
+   :glob:
 
-   command
-   database
-   datasource_kegg
-   datasource_misc
-   datasource_modelseed
-   datasource_native
-   datasource_sbml
-   expression_affine
-   expression_boolean
-   fastcore
-   fluxanalysis
-   fluxcoupling
-   formula
-   gapfill
-   lpsolver_lp
-   lpsolver_generic
-   lpsolver_cplex
-   lpsolver_qsoptex
-   massconsistency
-   metabolicmodel
-   reaction
+   api/*
diff --git a/docs/command.rst → docs/api/command.rst b/docs/command.rst → docs/api/command.rst
diff --git a/docs/database.rst → docs/api/database.rst b/docs/database.rst → docs/api/database.rst
diff --git a/docs/datasource_kegg.rst → docs/api/datasource_kegg.rst b/docs/datasource_kegg.rst → docs/api/datasource_kegg.rst
diff --git a/docs/datasource_misc.rst → docs/api/datasource_misc.rst b/docs/datasource_misc.rst → docs/api/datasource_misc.rst
diff --git a/docs/datasource_modelseed.rst → docs/api/datasource_modelseed.rst b/docs/datasource_modelseed.rst → docs/api/datasource_modelseed.rst
diff --git a/docs/datasource_native.rst → docs/api/datasource_native.rst b/docs/datasource_native.rst → docs/api/datasource_native.rst
diff --git a/docs/datasource_sbml.rst → docs/api/datasource_sbml.rst b/docs/datasource_sbml.rst → docs/api/datasource_sbml.rst
diff --git a/docs/expression_affine.rst → docs/api/expression_affine.rst b/docs/expression_affine.rst → docs/api/expression_affine.rst
diff --git a/docs/expression_boolean.rst → docs/api/expression_boolean.rst b/docs/expression_boolean.rst → docs/api/expression_boolean.rst
diff --git a/docs/fastcore.rst → docs/api/fastcore.rst b/docs/fastcore.rst → docs/api/fastcore.rst
diff --git a/docs/fluxanalysis.rst → docs/api/fluxanalysis.rst b/docs/fluxanalysis.rst → docs/api/fluxanalysis.rst
diff --git a/docs/fluxcoupling.rst → docs/api/fluxcoupling.rst b/docs/fluxcoupling.rst → docs/api/fluxcoupling.rst
diff --git a/docs/formula.rst → docs/api/formula.rst b/docs/formula.rst → docs/api/formula.rst
diff --git a/docs/gapfill.rst → docs/api/gapfill.rst b/docs/gapfill.rst → docs/api/gapfill.rst
diff --git a/docs/lpsolver_cplex.rst → docs/api/lpsolver_cplex.rst b/docs/lpsolver_cplex.rst → docs/api/lpsolver_cplex.rst
diff --git a/docs/lpsolver_generic.rst → docs/api/lpsolver_generic.rst b/docs/lpsolver_generic.rst → docs/api/lpsolver_generic.rst
diff --git a/docs/api/lpsolver_gurobi.rst b/docs/api/lpsolver_gurobi.rst
@@ -0,0 +1,6 @@
+
+``psamm.lpsolver.gurobi`` -- Gurobi LP solver
+=================================================
+
+.. automodule:: psamm.lpsolver.gurobi
+   :members:
diff --git a/docs/lpsolver_lp.rst → docs/api/lpsolver_lp.rst b/docs/lpsolver_lp.rst → docs/api/lpsolver_lp.rst
diff --git a/docs/lpsolver_qsoptex.rst → docs/api/lpsolver_qsoptex.rst b/docs/lpsolver_qsoptex.rst → docs/api/lpsolver_qsoptex.rst
diff --git a/docs/massconsistency.rst → docs/api/massconsistency.rst b/docs/massconsistency.rst → docs/api/massconsistency.rst
diff --git a/docs/metabolicmodel.rst → docs/api/metabolicmodel.rst b/docs/metabolicmodel.rst → docs/api/metabolicmodel.rst
diff --git a/docs/reaction.rst → docs/api/reaction.rst b/docs/reaction.rst → docs/api/reaction.rst
diff --git a/docs/commands.rst b/docs/commands.rst
@@ -153,21 +153,22 @@ specifying the reaction explicitly.
 
 .. code-block:: shell
 
-    $ psamm-model randomsparse 0.95
+    $ psamm-model randomsparse 95%
 
 When the given reaction is the biomass reaction, this results in a smaller
 model which is still producing biomass within the tolerance given by the
-threshold. Aggregating the results from multiple random sparse networks allows
-classifying reactions as essential, semi-essential or non-essential.
+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.
 
 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``
-otherwise). If multiply minimal networks are desired, the command can be run
-again and it will produce a different random minimal network.
+otherwise). If multiple minimal networks are desired, the command can be run
+again and it will sample another random minimal network.
 
 Flux coupling analysis (``fluxcoupling``)
 -----------------------------------------

diff --git a/docs/conf.py b/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']
+MOCK_MODULES = ['cplex', 'qsoptex', 'gurobipy']
 for module in MOCK_MODULES:
     sys.modules[module] = mock.Mock()
 

diff --git a/docs/development.rst b/docs/development.rst
@@ -21,14 +21,28 @@ for coding style (PEP8) and building documentation, use tox_:
 
     $ tox
 
-When testing with tox, the URL for the Cplex python module must be provided in
-the environment variable ``CPLEX_PYTHON_PACKAGE`` for the Cplex tests to
-succeed. For example:
+When testing with tox, the local path for the Cplex python module must be
+provided in the environment variables ``CPLEX_PYTHON2_PACKAGE`` and
+``CPLEX_PYTHON3_PACKAGE`` for Python 2 and Python 3, respectively. For example:
 
 .. code-block:: shell
 
-    $ export CPLEX_PYTHON_PACKAGE=file:///path/to/IBM/ILOG/CPLEX_StudioXXX/cplex/python/x86-64_osx
-    $ tox
+    $ export CPLEX_PYTHON2_PACKAGE=/path/to/IBM/ILOG/CPLEX_StudioXXX/cplex/python/2.7/x86-64_osx
+    $ export CPLEX_PYTHON3_PACKAGE=/path/to/IBM/ILOG/CPLEX_StudioXXX/cplex/python/3.4/x86-64_osx
+    $ tox -e py27-cplex,py34-cplex
+
+.. note::
+
+    Python 3 support was added in a recent release of Cplex. Older versions
+    only support Python 2.
+
+Similarly, the local path to the Gurobi package must be specified in the
+environment variable ``GUROBI_PYTHON_PACKAGE``:
+
+.. code-block:: shell
+
+    $ export GUROBI_PYTHON_PACKAGE=/Library/gurobi604/mac64
+    $ tox -e py27-gurobi
 
 Adding new tests
 ----------------

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -0,0 +1,26 @@
+
+FAQ
+===
+
+**When I run PSAMM it exits with the error "No solvers available". How can I
+fix this?**
+
+This means that PSAMM is searching for a linear programming solver but was not
+able to find one. This can occur even when the Cplex solver is installed
+because the Cplex Python-bindings have to be installed separately from the
+main Cplex package (see :ref:`install-cplex`). Also, if using a `Virtualenv`
+with Python, the Cplex Python-bindings must be installed `in the Virtualenv`.
+The bindings will `not` be available in the Virtualenv if they are installed
+globally.
+
+To check whether the Cplex Python-bindings are correctly installed use the
+following command:
+
+.. code-block:: shell
+
+    (env) $ pip list
+
+This will show a list of Python packages that are available. The package
+``cplex`` will appear in this list if the Cplex Python-bindings are correctly
+installed. If the package does `not` appear in the list, follow the instuctions
+at :ref:`install-cplex` to install the package.
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,6 +12,7 @@ Contents:
    file_format
    commands
    development
+   faq
    api
    references
 

diff --git a/docs/install.rst b/docs/install.rst
@@ -2,45 +2,52 @@
 Install
 =======
 
-The Python module can be installed using ``pip``. This will typically require
-*root* permissions.
+PSAMM can be installed using the Python package installer ``pip``. We recommend
+that you use a `Virtualenv`_ when installing PSAMM. First, create a Virtualenv
+in your project directory and activate the environment. On Linux/OSX the
+following terminal commands can be used:
 
 .. code-block:: shell
 
-    $ pip install psamm
+    $ virtualenv env
+    $ source env/bin/activate
 
-Another option that does not require *root* permissions is to use a
-`Virtualenv`_. First set up a new environment in your project directory and
-activate it:
+Then, install PSAMM using the ``pip`` command:
 
 .. code-block:: shell
 
-    $ virtualenv env
-    $ . env/bin/activate
+    (env) $ pip install psamm
+
+When returning to the project from a new terminal window, simply reactivate
+the environment by running
+
+.. code-block:: shell
 
-Now the Python module can be installed in the virtual environment using the
-``pip`` command without requiring *root* permissions. When returning to the
-project, simply reactivate the environment by running the second command.
+    $ source env/bin/activate
 
 The *psamm-import* tool is developed in a separate Git repository. After
 installing PSAMM, the *psamm-import* tool can be installed using:
 
 .. code-block:: shell
 
-    $ pip install git+https://github.com/zhanglab/psamm-import.git
+    (env) $ pip install git+https://github.com/zhanglab/psamm-import.git
 
 Dependencies
 ------------
 
-- Linear programming solver (*Cplex*, *QSopt_ex*)
+- Linear programming solver (*Cplex*, *Gurobi*, or *QSopt_ex*)
 - PyYAML (for reading the native model format)
 - NumPy (optional; model matrix can be exported to NumPy matrix if available)
 
 PyYAML is installed automatically when PSAMM is installed through ``pip``. The
 linear programming solver is not strictly required but most analyses require
-one to work. The LP solver *Cplex* is the preferred solver. The rational solver
-*QSopt_ex* does not support MILP problems which means that some analyses
-require *Cplex*.
+one to work. The LP solver *Cplex* is the preferred solver. We recently added
+support for the LP solver *Gurobi*.
+
+The rational solver *QSopt_ex* does not support MILP problems which means that
+some analyses require one of the other solvers.
+
+.. _install-cplex:
 
 Cplex
 -----
@@ -50,9 +57,37 @@ a virtual environment (as described above) this should be done after activating
 the virtual environment:
 
 1. Locate the directory where Cplex was installed (e.g. ``/path/to/IBM/ILOG/CPLEX_StudioXXX``).
-2. Locate the appropriate subdirectory based on your platform:
-   ``cplex/python/<platform>`` (e.g. ``cplex/python/x86-64_osx``).
-3. Use ``pip`` to install the package from this directory: ``pip install /path/to/IBM/ILOG/CPLEX_StudioXXX/cplex/python/<platform>``
+2. Locate the appropriate subdirectory based on your platform and Python
+   version: ``cplex/python/<version>/<platform>``
+   (e.g. ``cplex/python/2.7/x86-64_osx``).
+3. Use ``pip`` to install the package from this directory using the following
+   command.
+
+.. code-block:: shell
+
+    (env) $ pip install \
+        /path/to/IBM/ILOG/CPLEX_Studio1262/cplex/python/<version>/<platform>
+
+.. note::
+
+    Python 3 support was added in a recent release of Cplex. Older versions
+    only support Python 2. If you are using Python 3 make sure that you have
+    the latest version of Cplex installed.
+
+Gurobi
+------
+
+The Gurobi Python bindings will have to be installed into the virtualenv. After
+activating the virtualenv:
+
+1. Locate the directory where the Guropi python bindings were installed. For
+   example, on OSX this directory is ``/Library/gurobiXXX/mac64`` where ``XXX``
+   is a version code.
+2. Use ``pip`` to install the package from this directory. For example:
+
+.. code-block:: shell
+
+    (env) $ pip install /Library/gurobi604/mac64
 
 QSopt_ex
 --------
@@ -63,7 +98,7 @@ can be installed using ``pip``:
 
 .. code-block:: shell
 
-    $ pip install python-qsoptex
+    (env) $ pip install python-qsoptex
 
 .. _Virtualenv: https://virtualenv.pypa.io/
 .. _python-qsoptex: https://pypi.python.org/pypi/python-qsoptex

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -2,14 +2,15 @@
 Overview
 ========
 
-PSAMM is a collection of tools related to metabolic modeling, model
-reconstruction, data parsing and formatting, consistency checking,
-automatic gap filling, and model simulations.
+PSAMM is an open source software that is designed for the curation and analysis
+of metabolic models. It supports model version tracking, model annotation, data
+integration, data parsing and formatting, consistency checking, automatic gap
+filling, and model simulations.
 
 PSAMM is developed as an open source project, coordinated through `Github`_.
-The PSAMM software is being developed in the `Zhang Laboratory`_ at the University of Rhode Island and
-is the subject of a research article that has been submitted for
-review. [Steffensen15]_
+The PSAMM software is being developed in the `Zhang Laboratory`_ at the
+University of Rhode Island and is the subject of a research article that has
+been submitted for review. [Steffensen15]_
 
 .. _Github: https://github.com/zhanglab/psamm
 .. _Zhang Laboratory: http://zhanglab.uri.edu/