make documentation

cdanielmachado · Aug 3, 2017 · eb9480a · eb9480a
1 parent b6a0164
commit eb9480a
Show file tree

Hide file tree

Showing 10 changed files with 287 additions and 44 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,6 @@ dist/*
 
 carveme.egg-info/*
 
+*.pyc
+
+docs/_build/*
diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -0,0 +1,134 @@
+.. highlight:: shell
+
+==============
+Advanced Usage
+==============
+
+Advanced blasting
+_________________
+
+Gene matching (*i.e.* blasting) between provided genomes and our internal database is performed with diamond_.
+
+.. _diamond: https://github.com/bbuchfink/diamond
+
+You can manually tweak the blasting options within diamond itself (at your own risk) as follows:
+
+.. code-block:: console
+
+    $ carve genome.faa --diamond-args="-e 1e-20 --top 20"
+
+The default arguments are ``"--more-sensitive --top 10"``. Please see diamond's documentation for more details.
+
+
+eggNOG-mapper
+_____________
+
+
+By default, **CarveMe** performs gene matching by *homology* search using diamond_.
+However, you can also perform *orthology*-based search using eggNOG-mapper_.
+
+.. _diamond: https://github.com/bbuchfink/diamond
+.. _eggNOG-mapper: https://github.com/jhcepas/eggnog-mapper
+
+For this you must first annotate your genome with eggNOG-mapper, and provide the output of eggNOG-mapper directly as
+input to **CarveMe**:
+
+.. code-block:: console
+
+    $ carve --egg eggnog_output.tsv
+
+Please make sure you install eggNOG-mapper from the *bigg* branch:
+
+https://github.com/jhcepas/eggnog-mapper/tree/bigg
+
+
+Media database
+______________
+
+
+**CarveMe** comes with a very small pre-built library_ of media compositions:
+
+.. _library: https://github.com/cdanielmachado/carveme/blob/master/carveme/data/input/media_db.tsv
+
+- ``LB`` (Lysogeny broth)
+- ``LB[-O2]`` (Lysogeny broth, anaerobic)
+- ``M9`` (Minimal M9 medium)
+- ``M9[-O2]`` (Minimal M9 medium, anaerobic)
+- ``M9[glyc]`` (Minimal M9 medium, glycerol as carbon source)
+
+Additionally, you can provide your own media library for gap-filling:
+
+.. code-block:: console
+
+    $ carve genome.faa --gapfill X,Y,Z --mediadb mylibrary.tsv
+
+The library must be a tab-separated file with four columns:
+
+- *medium*: short id to be passed in command line (example: X)
+- *description*: description of the medium (optional, example: Our magic X formula)
+- *compound*: compound id (example: glc)
+- *name*: compound name (optional, example: Glucose)
+
+Please note that, at this moment, CarveMe only supports metabolite ids from the BiGG_ database.
+
+.. _BiGG: http://bigg.ucsd.edu
+
+Please feel free to contact us with suggestions of more media compositions to add to our default library.
+
+
+SBML *flavor*
+_____________
+
+By default, **CarveMe** generates models compatible with the old **cobra toolbox** format.
+This format is outdated but is still compatible with most constraint-based modeling tools.
+The new format based on the **sbml-fbc2** specification is also supported.
+
+You can specify your desired SBML *flavor* with the following flags:
+
+.. code-block:: console
+
+    $ carve genome.faa --cobra -o model.xml
+
+    $ carve genome.faa --fbc2 -o model.xml
+
+
+Ensemble modeling
+_________________
+
+Our model reconstruction algorithm is implemented as an MILP optimization problem. The generated model is structured
+according to the solution to this problem. Often, one might want to explore how alternative solutions lead to slightly
+different network structures, and consequently, predict different phenotypes.
+
+**CarveMe** allows the generation of model ensembles. You only need to specify how many models you want to generate:
+
+.. code-block:: console
+
+    $ carve genome.faa -n 100 -o model.xml
+
+This example would generate an ensemble of 100 models. Note that the ensemble is stored as a single SBML file, using
+a compact notation (binary vectors) to represent the ensemble state of each reaction.
+
+Some utility methods to read/write and perform simulations using ensemble models are implemented in *framed*.
+
+
+Alternative universes
+_____________________
+
+
+**CarveMe** implements a top-down reconstruction approach that requires a well-curated universal model to be used as
+template for the model *carving* process.
+
+Currently, only a bacterial template is provided. However, you are free to try to build and use your own templates.
+
+A script with some utility functions is available to help you build your own templates. For instructions please check:
+
+.. code-block:: console
+
+    $ build_universe -h
+
+You can then provide your own customized universe model during reconstruction:
+
+.. code-block:: console
+
+    $ carve genome.faa -u yeast_universe.xml
+
diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -40,7 +40,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -56,7 +56,7 @@
 
 # General information about the project.
 project = u'CarveMe'
-copyright = u"2017, Daniel Machado"
+copyright = u"2017, Daniel Machado and Sergej Andrejev (EMBL)"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -111,7 +111,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
@@ -273,3 +273,5 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+
diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/history.rst b/docs/history.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,18 +1,14 @@
-Welcome to CarveMe's documentation!
-======================================
+Welcome to CarveMe!
+===================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
    usage
-   modules
-   contributing
-   authors
-   history
+   advanced
 
 Indices and tables
 ==================

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -4,48 +4,38 @@
 Installation
 ============
 
+**CarveMe** requires Python 2.7, which is available for all major operating systems. We recommend the `Anaconda python
+distribution <https://www.continuum.io/downloads>`_.
 
-Stable release
---------------
-
-To install CarveMe, run this command in your terminal:
+It can be easily installed using the **pip** package manager:
 
 .. code-block:: console
 
     $ pip install carveme
 
-This is the preferred method to install CarveMe, as it will always install the most recent stable release. 
-
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
+This will automatically install other dependencies as well:
 
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
+- framed_
+- pandas_
 
+.. _framed: https://github.com/cdanielmachado/framed
+.. _pandas: https://pandas.pydata.org/
 
-From sources
-------------
+Additionally, you must manually install two external dependencies:
 
-The sources for CarveMe can be downloaded from the `Github repo`_.
+- diamond_
+- IBM CPLEX_ Optimizer
 
-You can either clone the public repository:
+.. _diamond: https://github.com/bbuchfink/diamond
+.. _CPLEX: https://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/
 
-.. code-block:: console
+Note that you will need to register with IBM to obtain an academic license for CPLEX.
 
-    $ git clone git://github.com/cdanielmachado/carveme
-
-Or download the `tarball`_:
+Finally, you should run the initialization script. This will download larger files
+to build an internal database for *CarveMe*, which does not come bundled with the installer:
 
 .. code-block:: console
 
-    $ curl  -OL https://github.com/cdanielmachado/carveme/tarball/master
-
-Once you have a copy of the source, you can install it with:
-
-.. code-block:: console
-
-    $ python setup.py install
-
+    $ carveme_init
 
-.. _Github repo: https://github.com/cdanielmachado/carveme
-.. _tarball: https://github.com/cdanielmachado/carveme/tarball/master
+Everything should be ready now! See the next section for instructions on how to start *carving*.
diff --git a/docs/readme.rst b/docs/readme.rst