Improve Doc

gem-pasteur · Mar 11, 2016 · 240389f · 240389f
1 parent 4bef47c
commit 240389f
Show file tree

Hide file tree

Showing 10 changed files with 83 additions and 62 deletions.
diff --git a/doc/source/_static/benchmark.pdf b/doc/source/_static/benchmark.pdf
diff --git a/doc/source/_static/benchmark.png b/doc/source/_static/benchmark.png
diff --git a/doc/source/_static/pipeline.pdf b/doc/source/_static/pipeline.pdf
diff --git a/doc/source/_static/pipeline.png b/doc/source/_static/pipeline.png
diff --git a/doc/source/_static/schema.pdf b/doc/source/_static/schema.pdf
diff --git a/doc/source/_static/schema.png b/doc/source/_static/schema.png
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.3'
+version = '1.4'
 # The full version, including alpha/beta/rc tags.
-release = '1.3'
+release = '1.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -1,74 +1,22 @@
 .. IntegronFinder - Detection of Integron in DNA sequences
-   documentation master file, created by
-   sphinx-quickstart on Mon Jul 27 15:07:43 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+
 
 Welcome to IntegronFinder's documentation!
 ==========================================
 
 IntegronFinder is a program that detects integrons in DNA sequences.
 The program is available on a webserver :ref:`(Mobyle) <mobyle>`, or by command line (`IntegronFinder on github`_).
 
-You already read the :ref:`paper <references>` and want to install it ? Click :ref:`here <install>`
-
-Integrons are major genetic element, notorious for their major implication in the spread of antibiotic resistance genes. More generally,  integrons are gene-capturing device, whose broader evolutionary role remains poorly understood. IntegronFinder is able to detect with high accuracy integron in DNA sequences. It is accurate because it combines the use of HMM profiles for the detection of the essential protein, the site-specific integron integrase, and the use of Covariance Models for the detection of the recombination site, the *attC* site.
-
-|integron schema|
-
-**How does it work ?**
-
-- First, IntegronFinder annotates the DNA sequence's CDS with Prodigal.
-
-- Second, IntegronFinder detects independently integron integrase and *attC*
-  recombination sites. The Integron integrase is detected by using the intersection
-  of two HMM profiles:
-
-  - one specific of tyrosine-recombinase (PF00589)
-  - one specific of the integron integrase, near the patch III domain of tyrosine recombinases.
-
-The *attC* recombination site is detected with a covariance model (CM), which
-models the secondary structure in addition to the few conserved sequence
-positions.
-
-
-- Third, the results are integrated, and IntegronFinder distinguishes 3 types of
-  elements:
-
-  - complete integron
-      Integron with integron integrase nearby *attC* site(s)
-  - In0 element
-      Integron integrase only, without any *attC* site nearby
-  - CALIN element
-      *attC* sites only, without integron integrase nearby.
-      A rule of thumb to avoid false positive is to filter out singleton of
-      *attC* site.
-
-IntegronFinder can also annotate gene cassettes (CDS nearby *attC* sites) using
-Resfams, a database of HMM profiles aiming at annotating antibiotic resistance
-genes. This database is provided but the user can add any other HMM profiles
-database of its own interest.
-
-When available, IntegronFinder annotates the promoters and attI sites by pattern
-matching.
-
-.. image:: _static/pipeline.*
-     :width: 400px
-     :align: middle
-     :alt: IntegronFinder Pipeline
-
-.. |integron schema| image:: _static/schema.*
-      :align: middle
-      :width: 300px
-      :alt: Integron Schema
-
+- You already read the :ref:`paper <references>` and want to install it ? Click :ref:`here <install>`
+- You did not read the paper (yet) but you would like to have rapid introduction to integrons and the program? click :ref:`here <introduction>` 
 
 .. _`IntegronFinder on github`: https://github.com/gem-pasteur/Integron_Finder
 
 
 .. toctree::
    :maxdepth: 2
 
+   introduction
    installation
    tutorial
    mobyle

diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
@@ -0,0 +1,76 @@
+.. IntegronFinder - Detection of Integron in DNA sequences
+
+.. _introduction:
+
+************
+Introduction
+************
+
+Integrons are major genetic element, notorious for their major implication in the spread of antibiotic resistance genes. More generally, integrons are gene-capturing platform, whose broader evolutionary role remains poorly understood. IntegronFinder is able to detect with high accuracy integron in DNA sequences. It is accurate because it combines the use of HMM profiles for the detection of the essential protein, the site-specific integron integrase, and the use of Covariance Models for the detection of the recombination site, the *attC* site.
+
+|integron schema|
+
+**How does it work ?**
+
+- First, IntegronFinder annotates the DNA sequence's CDS with Prodigal.
+
+- Second, IntegronFinder detects independently integron integrase and *attC*
+  recombination sites. The Integron integrase is detected by using the intersection
+  of two HMM profiles:
+
+  - one specific of tyrosine-recombinase (PF00589)
+  - one specific of the integron integrase, near the patch III domain of tyrosine recombinases.
+
+The *attC* recombination site is detected with a covariance model (CM), which
+models the secondary structure in addition to the few conserved sequence
+positions.
+
+
+- Third, the results are integrated, and IntegronFinder distinguishes 3 types of
+  elements:
+
+  - complete integron (panel B above)
+      Integron with integron integrase nearby *attC* site(s)
+  - In0 element (panel C  above)
+      Integron integrase only, without any *attC* site nearby
+  - CALIN element (panel D above)
+      *attC* sites only, without integron integrase nearby.
+      A rule of thumb to avoid false positive is to filter out singleton of
+      *attC* site.
+
+IntegronFinder can also annotate gene cassettes (CDS nearby *attC* sites) using
+Resfams, a database of HMM profiles aiming at annotating antibiotic resistance
+genes. This database is provided but the user can add any other HMM profiles
+database of its own interest.
+
+When available, IntegronFinder annotates the promoters and attI sites by pattern
+matching.
+
+|pipeline|
+
+**Does it work ?**
+
+Yes! The estimated sensitivity is 61% on average with the default option and goes up to 88% with the `--local_max` option. The missing *attC* sites are usually at the end of the array.  The False positive rate with the `--local_max` option is estimated between 0.03 False Positive per Megabases (FP/Mb) to 0.72 FP/Mb. This leads to a probability of finding 2 consecutive *attC* sites within 4kb between 4.10^-6 and 7.10^-9. Finally, this parameters do not depend on the G+C percent of the given replicon.
+
+|benchmark|
+
+The time in the table correspond to the average time per run with a pseudogenome having attC sites on a Mac Pro, 2 x 2.4 GHz 6-Core Intel Xeon, 16 Gb RAM, with options --cpu 20 and --no-proteins.
+
+.. Note::
+    The time does not vary depending of the mode (default or local_max), and is about a couple of second, if the replicon does not contain any *attC* site.
+
+
+.. |benchmark| image:: _static/benchmark.*
+     :width: 400px
+     :align: middle
+     :alt: IntegronFinder Benchmark
+
+.. |pipeline| image:: _static/pipeline.*
+     :width: 400px
+     :align: middle
+     :alt: IntegronFinder Pipeline
+
+.. |integron schema| image:: _static/schema.*
+      :align: middle
+      :width: 300px
+      :alt: Integron Schema
diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
@@ -86,16 +86,13 @@ Parallelization
 ---------------
 
 The time limiting part are HMMER and INFERNAL. So IntegronFinder does not have
-parallel implementation, but the user can set the number of CPU used by HMMER and
+parallel implementation (yet?), but the user can set the number of CPU used by HMMER and
 INFERNAL::
 
   integron_finder mysequence.fst --cpu 4
 
 Default is 1.
 
-To start IntegronFinder on many nucleotide sequences, one can use "manual"
-parallelization by calling multiple times IntegronFinder in ``bash``.
-
 .. _advance:
 
 Advanced use