Add documentation scripts

README.rst

@@ -57,9 +57,10 @@ Table of contents
 News
 ====
 
-* **170404**: New documentation about creating and analyzing DeepCpG data `released <http://deepcpg.readthedocs.io/data.html>`_!
+* **170406**: A short description of all `DeepCpG scripts <http://deepcpg.readthedocs.io/scripts/index.html>`_!
+* **170404**: New guide on creating and analyzing DeepCpG data `released <http://deepcpg.readthedocs.io/data.html>`_!
 * **170404**: Training on continuous data, e.g. from bulk experiments, now `supported <http://deepcpg.readthedocs.io/data.html>`_!
-* **170305**: New documentation about DeepCpG model architectures `released <http://deepcpg.readthedocs.io/models.html>`_!
+* **170305**: New documentation of DeepCpG model architectures `released <http://deepcpg.readthedocs.io/models.html>`_!
 * **170302**: New guide on DeepCpG model training `released <http://deepcpg.readthedocs.io/train.html>`_!
 * **170228**: New example shell scripts for building a DeepCpG pipeline `released <./examples/README.md>`_!
 

docs/source/index.rst

@@ -52,7 +52,8 @@ Documentation
 * :ref:`data` -- Creating and analyzing data.
 * :ref:`train` -- Training DeepCpG models.
 * :ref:`models` -- Description of DeepCpG model architectures.
-* :ref:`libdoc` -- Documentation of DeepCpG source code.
+* :ref:`scripts` -- Documentation of DeepCpG scripts.
+* :ref:`library` -- Documentation of DeepCpG library.
 
 
 Indices and tables
@@ -69,4 +70,5 @@ Indices and tables
   data
   train
   models
+  scripts/index
   lib/index

docs/source/lib/deepcpg.rst

@@ -24,9 +24,3 @@
 
 .. automodule:: deepcpg.utils
   :members:
-
-dcpg_train
-==========
-
-.. automodule:: dcpg_train
-  :members:

docs/source/lib/index.rst

@@ -1,10 +1,10 @@
-.. _libdoc:
+.. _library:
 
-=================
-API documentation
-=================
+=======
+Library
+=======
 
-Documentation of DeepCpG modules.
+Documentation of DeepCpG library.
 
 .. toctree::
   :maxdepth: 2

docs/source/scripts/index.rst

@@ -0,0 +1,71 @@
+.. _scripts:
+
+=======
+Scripts
+=======
+
+Documentation of DeepCpG scripts.
+
+.. toctree::
+  :maxdepth: 2
+
+
+dcpg_data.py
+=============
+
+.. automodule:: scripts.dcpg_data
+  :members:
+
+dcpg_data_show.py
+=================
+
+.. automodule:: scripts.dcpg_data_show
+  :members:
+
+dcpg_data_stats.py
+==================
+
+.. automodule:: scripts.dcpg_data_stats
+  :members:
+
+dcpg_download.py
+================
+
+.. automodule:: scripts.dcpg_download
+  :members:
+
+dcpg_eval.py
+=============
+
+.. automodule:: scripts.dcpg_eval
+  :members:
+
+dcpg_eval_export.py
+===================
+
+.. automodule:: scripts.dcpg_eval_export
+  :members:
+
+dcpg_filter_act.py
+==================
+
+.. automodule:: scripts.dcpg_filter_act
+  :members:
+
+dcpg_filter_motifs.py
+=====================
+
+.. automodule:: scripts.dcpg_filter_motifs
+  :members:
+
+dcpg_train.py
+=============
+
+.. automodule:: scripts.dcpg_train
+  :members:
+
+dcpg_train_viz.py
+=================
+
+.. automodule:: scripts.dcpg_train_viz
+  :members:

scripts/dcpg_data.py

@@ -5,38 +5,42 @@
 Takes as input incomplete CpG methylation profiles of multiple cells, extracts
 neighboring CpG sites and/or DNA sequences windows, and writes data chunk files
 to output directory. Output data can than be used for model training using
-`dcpg_train.py` model evaluation using `dcpg_eval.py`.
+``dcpg_train.py`` model evaluation using ``dcpg_eval.py``.
 
 Examples
 --------
 Create data files for training a CpG and DNA model, using 50 neighboring
 methylation states and DNA sequence windows of 1001 bp from the mm10 genome
 build:
 
-    dcpg_data.py \
-        --cpg_profiles ./cpg/*.tsv \
-        --cpg_wlen 50 \
-        --dna_files ./mm10 \
-        --dna_wlen 1001 \
+.. code:: bash
+
+    dcpg_data.py
+        --cpg_profiles ./cpg/*.tsv
+        --cpg_wlen 50
+        --dna_files ./mm10
+        --dna_wlen 1001
         --out_dir ./data
 
 Create data files from gzip-compressed bedGraph files for predicting the mean
 methylation rate and cell-to-cell variance from the DNA sequence:
 
-    dcpg_data.py \
-        --cpg_profiles ./cpg/*.bedGraph.gz \
-        --dna_files ./mm10 \
-        --dna_wlen 1001 \
-        --win_stats mean var \
-        --win_stats_wlen 1001 2001 3001 4001 5001 \
+.. code:: bash
+
+    dcpg_data.py
+        --cpg_profiles ./cpg/*.bedGraph.gz
+        --dna_files ./mm10
+        --dna_wlen 1001
+        --win_stats mean var
+        --win_stats_wlen 1001 2001 3001 4001 5001
         --out_dir ./data
 
 
 See Also
 --------
-    `dcpg_data_stats.py`: For computing statistics of data files.
-    `dcpg_data_show.py`: For showing the content of data files.
-    `dcpg_train.py`: For training a model.
+* ``dcpg_data_stats.py``: For computing statistics of data files.
+* ``dcpg_data_show.py``: For showing the content of data files.
+* ``dcpg_train.py``: For training a model.
 """
 
 from __future__ import print_function

scripts/dcpg_data_show.py

@@ -2,7 +2,7 @@
 
 """Show the content of DeepCpG data files.
 
-Shows the content of `dcpg_data.py` output files for a selected region, for
+Shows the content of ``dcpg_data.py`` output files for a selected region, for
 example the methylation state of the target CpG site, neighboring CpG sites, or
 the DNA sequence.
 
@@ -11,36 +11,42 @@
 Show the output methylation state of CpG sites on on chromosome 19 between
 position 3028955 and 3079682:
 
-    dcpg_data_show.py \
-        ./data/*.h5 \
-        --chromo 1 \
-        --start 3028955 \
-        --end 3079682 \
+.. code:: bash
+
+    dcpg_data_show.py
+        ./data/*.h5
+        --chromo 1
+        --start 3028955
+        --end 3079682
         --outputs
 
 Show output methylation states and the state as well as the distance of
 10 neighboring CpG sites of cell BS27_1_SER:
 
-    dcpg_data_show.py \
-        ./data/*.h5 \
-        --chromo 1 \
-        --start 3028955 \
-        --end 3079682 \
-        --outputs cpg/BS27_1_SER \
-        --cpg BS27_1_SER \
-        --cpg_wlen 10 \
+.. code:: bash
+
+    dcpg_data_show.py
+        ./data/*.h5
+        --chromo 1
+        --start 3028955
+        --end 3079682
+        --outputs cpg/BS27_1_SER
+        --cpg BS27_1_SER
+        --cpg_wlen 10
         --cpg_dist
 
 Show output methylation states and DNA sequence windows of length 11 and
-store the results in HDF5 file `selected.h5`:
-
-    dcpg_data_show.py \
-        ./data/*.h5 \
-        --chromo 1 \
-        --start 3028955 \
-        --end 3079682 \
-        --outputs \
-        --dna_wlen 11 \
+store the results in HDF5 file ``selected.h5``:
+
+.. code:: bash
+
+    dcpg_data_show.py
+        ./data/*.h5
+        --chromo 1
+        --start 3028955
+        --end 3079682
+        --outputs
+        --dna_wlen 11
         --out_hdf selected.h5
 """
 

scripts/dcpg_data_stats.py

@@ -7,7 +7,10 @@
 
 Examples
 --------
-    dcpg_data_stats.py \
+
+.. code:: bash
+
+    dcpg_data_stats.py
         ./data/*.h5
 """
 

scripts/dcpg_download.py

@@ -9,12 +9,16 @@
 --------
 Show available models:
 
+.. code:: bash
+
     dcpg_download --show
 
 Download DNA model trained on serum cells from Smallwood et al:
 
-    dcpg_download.py \
-        Smallwood2014_serum_dna \
+.. code:: bash
+
+    dcpg_download.py
+        Smallwood2014_serum_dna
         -o ./model
 """
 

scripts/dcpg_eval.py

@@ -3,21 +3,25 @@
 """Evaluate the prediction performance of a DeepCpG model.
 
 Imputes missing methylation states and evaluates model on observed states.
-`--out_report` will write evaluation metrics to a TSV file using. `--out_data`
-will write predicted and observed methylation state to a HDF5 file with
-following structure:
-    chromo: The chromosome of the CpG site.
-    pos: The position of the CpG site on the chromosome.
-    outputs: The input methylation state of each cell and CpG site, which can
-        either observed or missing (-1).
-    preds: The predicted methylation of each cell and CpG site.
+``--out_report`` will write evaluation metrics to a TSV file using.
+``--out_data`` will write predicted and observed methylation state to a HDF5
+file with following structure:
+
+* ``chromo``: The chromosome of the CpG site.
+* ``pos``: The position of the CpG site on the chromosome.
+* ``outputs``: The input methylation state of each cell and CpG site, which \
+    can either observed or missing (-1).
+* ``preds``: The predicted methylation state of each cell and CpG site.
 
 Examples
 --------
-    dcpg_eval.py \
-        ./data/*.h5 \
-        --model_files ./model \
-        --out_data ./eval/data.h5 \
+
+.. code:: bash
+
+    dcpg_eval.py
+        ./data/*.h5
+        --model_files ./model
+        --out_data ./eval/data.h5
         --out_report ./eval/report.tsv
 """
 

scripts/dcpg_eval_export.py

@@ -12,18 +12,22 @@
 --------
 Export profiles of all cells as HDF5 files to `./eval`:
 
-    dcpg_eval_export.py \
-        ./eval/data.h5 \
+.. code:: bash
+
+    dcpg_eval_export.py
+        ./eval/data.h5
         --out_dir ./eval
 
 Export the profile of cell Ca01 for chromosomes 4 and 5 to a bedGraph file:
 
-    dcpg_eval_export.py \
-        ./eval/data.h5 \
-        --output cpg/Ca01 \
-        --chromo 4 5 \
-        --format bedGraph \
-        --out_dir ./eval \
+.. code:: bash
+
+    dcpg_eval_export.py
+        ./eval/data.h5
+        --output cpg/Ca01
+        --chromo 4 5
+        --format bedGraph
+        --out_dir ./eval
 """
 
 from __future__ import print_function

scripts/dcpg_filter_act.py

@@ -11,26 +11,30 @@
 Compute activations in 25000 sequence windows and also store DNA sequences.
 For example to visualize motifs.
 
-    dcpg_filter_act.py \
-        ./data/*.h5 \
-        --model_files ./models/dna \
-        --out_file ./activations.h5 \
-        --nb_sample 25000 \
+.. code:: bash
+
+    dcpg_filter_act.py
+        ./data/*.h5
+        --model_files ./models/dna
+        --out_file ./activations.h5
+        --nb_sample 25000
         --store_inputs
 
 Compute the weighted mean activation in each sequence window and also store
 model predictions. For example to cluster motifs or to correlated mean motif
 activations with model predictions.
 
-    dcpg_filter_act.py \
-        ./data/*.h5 \
-        --model_files ./models/dna \
-        --out_file ./activations.h5 \
+.. code:: bash
+
+    dcpg_filter_act.py
+        ./data/*.h5
+        --model_files ./models/dna
+        --out_file ./activations.h5
         --act_fun wmean
 
 See Also
 --------
-    `dcpg_filter_motifs.py`: For motif visualization and analysis.
+* ``dcpg_filter_motifs.py``: For motif visualization and analysis.
 """
 
 from __future__ import print_function