Update Documentation

.gitignore

@@ -54,8 +54,7 @@ output/*/index.html
 
 # Sphinx
 docs/_build
-docs/outrigger*.rst
-docs/outrigger.rst
+docs/outrigger*rst
 docs/modules.rst
 docs/_deploy
 

CONTRIBUTING.rst

@@ -40,6 +40,120 @@ Outrigger could always use more documentation, whether as part of the
 official Outrigger docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
+Tips for writing documentation
+------------------------------
+
+To keep documentation writing separate from code and test writing, I have an
+environment only for documentation writing that was created in this way:
+
+```
+# Go to the folder where you cloned outrigger
+cd outrigger
+conda create -n outrigger-documentation docs/requirements.txt
+```
+
+Now activate the environment and build the docs. This command will both build
+what you have and open a web browser so you can see the latest version.
+
+```
+source activate outrigger-documentation
+make docs
+```
+
+Make changes as you want in the `docs` folder. Once you're ready to deploy
+them to the `yeolab.github.io/outrigger` website, you'll need to change to the
+`docs` directory and use the `make deploy` directive there to build the docs
+and push the HTML files to the `gh-pages` branch. Here is an example with
+output:
+
+```
+(outrigger-documentation) ➜  docs git:(documentation) ✗ cd docs
+(outrigger-documentation) ➜  docs git:(documentation) ✗ make deploy
+echo "Preparing gh_pages deployment..."
+Preparing gh_pages deployment...
+echo "Pulling any updates from Github Pages..."
+Pulling any updates from Github Pages...
+cd _deploy; git pull;
+remote: Counting objects: 2039, done.
+remote: Compressing objects: 100% (127/127), done.
+remote: Total 2039 (delta 462), reused 402 (delta 401), pack-reused 1510
+Receiving objects: 100% (2039/2039), 164.78 MiB | 9.19 MiB/s, done.
+Resolving deltas: 100% (1206/1206), completed with 84 local objects.
+From github.com:YeoLab/outrigger
+ * [new branch]      checklist  -> origin/checklist
+ + c68a887...04316b6 documentation -> origin/documentation  (forced update)
+ * [new branch]      flake8-weirdness -> origin/flake8-weirdness
+ * [new branch]      logo       -> origin/logo
+ * [new branch]      low_memory -> origin/low_memory
+   82b6296..9c80211  master     -> origin/master
+ * [new branch]      merge_exon_finding_and_junction_adjacencies -> origin/merge_exon_finding_and_junction_adjacencies
+ * [new branch]      py3.6      -> origin/py3.6
+ * [new branch]      segfault   -> origin/segfault
+ * [new branch]      strandedness -> origin/strandedness
+ * [new branch]      v1.0.0rc1  -> origin/v1.0.0rc1
+ * [new tag]         v1.0.0     -> v1.0.0
+Already up-to-date.
+mkdir -p _deploy/
+echo "Copying files from '_build/html/.' to '_deploy/'"
+Copying files from '_build/html/.' to '_deploy/'
+cp -r _build/html/. _deploy/
+echo "Deploying on github pages now..."
+Deploying on github pages now...
+cd _deploy; git add -A; git commit -m "docs updated at `date -u`";\
+		git push origin  --quiet
+[gh-pages fa0420c] docs updated at Tue Apr  4 01:31:17 UTC 2017
+ 134 files changed, 103905 insertions(+), 2704 deletions(-)
+ create mode 100644 _images/outrigger_index-300ppi.png
+ create mode 100644 _images/outrigger_overview-300ppi.png
+ create mode 100644 _images/outrigger_psi-1x.png
+ create mode 100644 _images/outrigger_validate-1x.png
+ rewrite _modules/outrigger/psi/compute.html (68%)
+ create mode 100644 _sources/license.txt
+ rewrite _sources/releases/v0.2.7.txt (83%)
+ create mode 100644 _sources/releases/v1.0.0.txt
+ create mode 100644 _sources/releases/v1.0.1.txt
+ create mode 100644 _static/exon_vs_junction_start_stop.ai
+ create mode 100644 _static/logo-150ppi.png
+ create mode 100644 _static/logo-1x.png
+ create mode 100644 _static/logo-300ppi.png
+ create mode 100644 _static/logo.ai
+ create mode 100644 _static/logo.svg
+ create mode 100644 _static/outrigger_franken-events.ai
+ create mode 100644 _static/outrigger_index-150ppi.png
+ create mode 100644 _static/outrigger_index-1x.png
+ create mode 100644 _static/outrigger_index-300ppi.png
+ create mode 100644 _static/outrigger_index.ai
+ create mode 100644 _static/outrigger_index.svg
+ create mode 100644 _static/outrigger_index_flanking_exons.ai
+ create mode 100644 _static/outrigger_index_mxe.ai
+ create mode 100644 _static/outrigger_index_se.ai
+ create mode 100644 _static/outrigger_overview-150ppi.png
+ create mode 100644 _static/outrigger_overview-1x.png
+ create mode 100644 _static/outrigger_overview-300ppi.png
+ create mode 100644 _static/outrigger_overview.svg
+ create mode 100644 _static/outrigger_overview_v1.ai
+ create mode 100644 _static/outrigger_overview_v1.svg
+ create mode 100644 _static/outrigger_overview_v2.ai
+ create mode 100644 _static/outrigger_psi-150ppi.png
+ rewrite _static/outrigger_psi-1x.png (98%)
+ rewrite _static/outrigger_psi-300ppi.png (92%)
+ create mode 100644 _static/outrigger_psi_pathological_cases.ai
+ create mode 100644 _static/outrigger_psi_v1.ai
+ create mode 100644 _static/outrigger_psi_v2.ai
+ create mode 100644 _static/outrigger_psi_v3.ai
+ create mode 100644 _static/outrigger_validate-150ppi.png
+ create mode 100644 _static/outrigger_validate-1x.png
+ create mode 100644 _static/outrigger_validate-300ppi.png
+ create mode 100644 _static/outrigger_validate.ai
+ create mode 100644 _static/outrigger_validate.svg
+ create mode 100644 license.html
+ rewrite objects.inv (97%)
+ create mode 100644 releases/v1.0.0.html
+ create mode 100644 releases/v1.0.1.html
+ rewrite searchindex.js (99%)
+echo "Github Pages deploy was completed at `date -u`"
+Github Pages deploy was completed at Tue Apr  4 01:31:24 UTC 2017```
+
 Submit Feedback
 ~~~~~~~~~~~~~~~
 

README.rst

@@ -4,7 +4,7 @@
 
 |BuildStatus|\ |codecov|\ |PyPIVersions|\ |PythonVersionCompatibility|
 
-.. |OutriggerLogo| image:: https://raw.githubusercontent.com/YeoLab/outrigger/master/logo/logo-1x.png
+.. |OutriggerLogo| image:: http://yeolab.github.io/outrigger/_static/logo-400px.png
     :target: https://github.com/YeoLab/outrigger
 .. |BuildStatus| image:: https://travis-ci.org/YeoLab/outrigger.svg?branch=master
     :target: https://travis-ci.org/YeoLab/outrigger
@@ -15,11 +15,11 @@
 .. |PythonVersionCompatibility| image:: https://img.shields.io/pypi/pyversions/outrigger.svg
     :target: https://pypi.python.org/pypi/outrigger
 
-=============================================================================
-Large-scale detection and calculation of alternative splicing with Outrigger_
-=============================================================================
+==================================================================================
+Fast detection and accurate calculation of alternative splicing with ``outrigger``
+==================================================================================
 
-Outrigger_ is a program which uses junction reads from RNA seq data, and
+outrigger_ is a program which uses junction reads from RNA seq data, and
 a graph database to create a *de novo* alternative splicing annotation
 with a graph database, and quantify percent spliced-in (Psi) of the
 events.
@@ -40,28 +40,26 @@ Features
 
 |OutriggerOverview|
 
-.. |OutriggerOverview| image:: https://raw.githubusercontent.com/YeoLab/outrigger/master/docs/_static/outrigger_overview-300ppi.png
-    :target: https://raw.githubusercontent.com/YeoLab/outrigger/master/docs/_static/outrigger_overview-300ppi.png
+.. |OutriggerOverview| image:: http://yeolab.github.io/outrigger/_static/outrigger_overview-1x.png
+    :target: http://yeolab.github.io/outrigger/_static/outrigger_overview-300ppi.png
 
 Installation
 ============
 
 To install ``outrigger``, we recommend using the `Anaconda Python
 Distribution <http://anaconda.org/>`__ and creating an environment.
 
-You'll want to add the `bioconda <https://bioconda.github.io/>`__
-channel to make installing `bedtools <bedtools.readthedocs.io>`__ and
-its Python wrapper, `pybedtools <https://daler.github.io/pybedtools/>`__
-easy (these programs are necessary for both ``outrigger index`` and
-``outrigger validate``).
+You'll want to add the bioconda_ channel to make installing bedtools_ and its
+Python wrapper, pybedtools_ easy, as these programs are necessary for both
+``outrigger index`` and ``outrigger validate``.
 
 ::
 
     conda config --add channels r
     conda config --add channels bioconda
 
 Create an environment called ``outrigger-env``. Python 2.7, Python 3.4,
-and Python 3.5 are supported.
+Python 3.5, and Python 3.6 are supported.
 
 ::
 
@@ -101,7 +99,7 @@ option (``-h``), ``outrigger -h``. The output should look like this:
 Bleeding edge code from Github (here)
 -------------------------------------
 
-For advanced users, if you have `git <https://git-scm.com/>`__ and
+For advanced users, if you have git_ and
 `Anaconda Python <https://www.continuum.io/downloads>`__ installed, you
 can:
 
@@ -136,22 +134,35 @@ change directories to that folder with ``cd``.
 
 Then you need find all alternative splicing events, which you do by
 running ``outrigger index`` on the splice junction files and the gtf.
-Here is an example command:
 
-Input: ``.SJ.out.tab`` files
-----------------------------
+.. note::
+
+    We highly recommend to use ``outrigger index`` on a supercomputer with
+    multiple processors (at least 4) as the indexing process takes a long time
+    -- over 24 hours, and by using multiple threads, the program will run much
+    faster.
+
+Here is an example command:
 
+Input: ``.SJ.out.tab`` files (faster)
+-------------------------------------
+This is faster than using ``.bam`` files because the junction counts are
+already aggregated.
 ::
 
     outrigger index --sj-out-tab *SJ.out.tab \
         --gtf /projects/ps-yeolab/genomes/mm10/gencode/m10/gencode.vM10.annotation.gtf
 
-Input: ``.bam`` files
----------------------
+Input: ``.bam`` files (slower)
+------------------------------
 
 If you're using ``.bam`` files instead of ``SJ.out.tab`` files, never despair!
+This will be slightly slower because ``outrigger`` needs to count every time a read
+spans an exon-exon junction.
+
+
 Below is an example command. Keep in mind that for this program to work, the
-events must be sorted and indexed.
+``bams`` must be sorted and indexed.
 
 ::
 
@@ -201,47 +212,63 @@ produced it.
 ::
 
     $ tree outrigger_output
-    outrigger_output..........................................................index
-    ├── index.................................................................index
-    │   ├── gtf...............................................................index
-    │   │   ├── gencode.vM10.annotation.gtf...................................index
-    │   │   ├── gencode.vM10.annotation.gtf.db................................index
-    │   │   └── novel_exons.gtf...............................................index
-    │   ├── exon_direction_junction_triples.csv...............................index
-    │   ├── mxe...............................................................index
-    │   │   ├── event.bed.....................................................index
-    │   │   ├── events.csv....................................................index
-    │   │   ├── exon1.bed.....................................................index
-    │   │   ├── exon2.bed.....................................................index
-    │   │   ├── exon3.bed.....................................................index
-    │   │   ├── exon4.bed.....................................................index
-    │   │   ├── intron.bed....................................................index
-    │   │   ├── splice_sites.csv...........................................validate
-    │   │   └── validated..................................................validate
-    │   │       └── events.csv.............................................validate
-    │   └── se................................................................index
-    │       ├── event.bed.....................................................index
-    │       ├── events.csv....................................................index
-    │       ├── exon1.bed.....................................................index
-    │       ├── exon2.bed.....................................................index
-    │       ├── exon3.bed.....................................................index
-    │       ├── intron.bed....................................................index
-    │       ├── splice_sites.csv...........................................validate
-    │       └── validated..................................................validate
-    │           └── events.csv.............................................validate
-    ├── junctions.............................................................index
-    │   ├── metadata.csv......................................................index
-    │   └── reads.csv.........................................................index
-    └── psi.....................................................................psi
-        ├── mxe.................................................................psi
-        |   ├── psi.csv.........................................................psi
-        │   └── summary.csv.....................................................psi
-        ├── outrigger_psi.csv...................................................psi
-        └── se..................................................................psi
-            ├── psi.csv.........................................................psi
-            └── summary.csv.....................................................psi
+    outrigger_output...................................................index
+    ├── index..........................................................index
+    │   ├── gtf........................................................index
+    │   │   ├── gencode.vM10.annotation.gtf............................index
+    │   │   ├── gencode.vM10.annotation.gtf.db.........................index
+    │   │   └── novel_exons.gtf........................................index
+    │   ├── exon_direction_junction_triples.csv........................index
+    │   ├── mxe........................................................index
+    │   │   ├── event.bed..............................................index
+    │   │   ├── events.csv.............................................index
+    │   │   ├── exon1.bed..............................................index
+    │   │   ├── exon2.bed..............................................index
+    │   │   ├── exon3.bed..............................................index
+    │   │   ├── exon4.bed..............................................index
+    │   │   ├── intron.bed.............................................index
+    │   │   ├── splice_sites.csv....................................validate
+    │   │   └── validated...........................................validate
+    │   │       └── events.csv......................................validate
+    │   └── se.........................................................index
+    │       ├── event.bed..............................................index
+    │       ├── events.csv.............................................index
+    │       ├── exon1.bed..............................................index
+    │       ├── exon2.bed..............................................index
+    │       ├── exon3.bed..............................................index
+    │       ├── intron.bed.............................................index
+    │       ├── splice_sites.csv....................................validate
+    │       └── validated...........................................validate
+    │           └── events.csv......................................validate
+    ├── junctions......................................................index
+    │   ├── metadata.csv...............................................index
+    │   └── reads.csv..................................................index
+    └── psi..............................................................psi
+        ├── mxe..........................................................psi
+        |   ├── psi.csv..................................................psi
+        │   └── summary.csv..............................................psi
+        ├── outrigger_psi.csv............................................psi
+        └── se...........................................................psi
+            ├── psi.csv..................................................psi
+            └── summary.csv..............................................psi
 
     10 directories, 26 files
 
+Approximate runtimes
+====================
+
+Here are the expected runtimes for the different steps of ``outrigger``. In all
+ cases, we **strongly recommend** using a supercomputer with at least 4 cores, ideally 8-16.
+
+
+- ``outrigger index``: This will run for 24-48 hours.
+- ``outrigger validate``: This will take 2-4 hours.
+- ``outrigger psi``: This will run for 4-8 hours.
+
+
 
-.. _Outrigger: https://github.com/YeoLab/outrigger
+.. _outrigger: https://github.com/YeoLab/outrigger
+.. _bioconda: https://bioconda.github.io/
+.. _bedtools: http://bedtools.readthedocs.io
+.. _git: https://git-scm.com
+.. _pybedtools: https://daler.github.io/pybedtools/

docs/_templates/about.html

@@ -0,0 +1,20 @@
+{% if theme_logo %}
+<p class="logo">
+  <a href="{{ pathto(master_doc) }}">
+    <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo"/>
+    {% if theme_logo_name|lower == 'true' %}
+    <h1 class="logo logo-name">{{ project }}</h2>
+    {% endif %}
+  </a>
+</p>
+{% else %}
+<!--<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>-->
+{% endif %}
+
+<!--<a href="{{ pathto(master_doc) }}">-->
+<!--<img src="{{ pathto('_static/logo/logo-v2/logo-1x.png', 1) }}" width=80%>-->
+<!--</a>-->
+
+{% if theme_description %}
+<p class="blurb">{{ theme_description }}</p>
+{% endif %}

docs/_templates/globaltoc.html

@@ -0,0 +1,18 @@
+<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+
+<ul>
+  <li><a href="{{ pathto('index') }}">Home</a></li>
+  <li><a href="{{ pathto('contents') }}">Contents</a></li>
+  <li><a href="{{ pathto('installation') }}">Install</a></li>
+  <li><a href="{{ pathto('Usage') }}">Usage</a></li>
+  <li><a href="{{ pathto('subcommands/outrigger_index') }}"><code>index</code>: Detect exons</a></li>
+  <li><a href="{{ pathto('subcommands/outrigger_validate') }}"><code>validate</code>: Remove non-canonical splice sites</a></li>
+  <li><a href="{{ pathto('subcommands/outrigger_psi') }}"><code>psi</code>: Quantify exon inclusion</a></li>
+  <li><a href="{{ pathto('history') }}">Changelog</a></li>
+  <li><a href="{{ pathto('license') }}">License</a></li>
+</ul>
+
+{%- if display_toc %}
+  <hr>
+  {{ toc }}
+{%- endif %}