Merge pull request #8 from karel-brinda/devel

Another update of documentation

bin/rnf-join-fq.py

@@ -10,8 +10,8 @@
 
 allowed_modes = [
 			"single-end",
-			"pair-end-bwa",
-			"pair-end-bfast",
+			"paired-end-bwa",
+			"paired-end-bfast",
 		]
 
 class Mixer:
@@ -39,10 +39,10 @@ def __init__(self,mode,input_files,output_prefix):
 		if args.m=="single-end":
 			self.output=Output(fn_1="{}.fq".format(output_prefix),reads_in_tuple=1,read_id_length=read_id_length_est)
 			self._reads_in_tuple=1
-		elif args.m=="pair-end-bwa":
+		elif args.m=="paired-end-bwa":
 			self.output=Output(fn_1="{}.1.fq".format(output_prefix),fn_2="{}.2.fq".format(output_prefix),reads_in_tuple=2,read_id_length=read_id_length_est)
 			self._reads_in_tuple=2
-		elif args.m=="pair-end-bfast":
+		elif args.m=="paired-end-bfast":
 			self.output=Output(fn_1="{}.fq".format(output_prefix),reads_in_tuple=2,read_id_length=read_id_length_est)
 			self._reads_in_tuple=2
 		else:
@@ -113,7 +113,13 @@ def save_read(self,ln1,ln2,ln3,ln4):
 		self.fs[file_id].write("".join([ln1,os.linesep,ln2,os.linesep,ln3,os.linesep,ln4,os.linesep]))
 
 
-parser = argparse.ArgumentParser()
+parser = argparse.ArgumentParser(
+			description="Join FASTQ files with reads in RNF format.",
+			epilog="Source FASTQ files should satisfy the following conditions:"
+					" 1) Each file contains only reads corresponding to one genome (with the same genome id)."
+					" 2) All files contain reads of the same type (single-end / paired-end)."
+					" 3) Reads with more reads per tuple (e.g., paired-end) have '/1', etc. in suffix (for identification of nb of read)."
+		)
 
 parser.add_argument(
 		'-i',
@@ -129,7 +135,7 @@ def save_read(self,ln1,ln2,ln3,ln4):
 		metavar='mode',
 		choices=allowed_modes,
 		#type=lambda x: is_valid_mode(parser,x),
-		help='mode',
+		help='mode for joining files (single-end / paired-end-bwa / paired-end-bfast)',
 	)
 
 

docs/conf.py

@@ -49,9 +49,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.0.1'
+version = '0.1.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.0.1'
+release = '0.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -92,7 +92,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 = 'sphinx_rtd_theme'
 
 # 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

docs/reference/02_lavender.rst

@@ -5,56 +5,28 @@ LAVEnder
    :depth: 2
 
 
-LAVender
---------
-
-LAVEnder is a RNF-compatible evaluation tool for evaluation of mappers of Next-Generation Sequencing reads.
-
-
-
-Usage
-^^^^^
-
-1. Create simulated reads using a RNF-compatible read simulator, for example `MIShmash`_
-2. Map the simulated reads to your reference with your tested mappers and put the obtained BAM files into a standalone directory.
-3. Create an empty directory where a report will be created.
-4. Create there a file named ``Snakefile``, which will serve as a configuration script. Save the following content into it and adjust it as you want.
-
-	.. code-block:: python
-
-		# a mandatory line
-		import rnftools.lavender
-
-		# this command says: "create a report called 'my_amazing_report' for BAM files
-		# in directory 'my_bam_directory'"
-		lavender.Report(
-			bam_dirs=["my_bam_directory"],
-			name="My amazing report"
-		)
-
-		# two mandatory lines
-		include: lavender.include()
-		rule: input: rnftools.input()
-
-5. Run ``snakemake`` in the directory
-
-
-
-Technical documentation
-^^^^^^^^^^^^^^^^^^^^^^^
+Report class
+------------
 
 .. autoclass:: rnftools.lavender.Report
 	:members:
 	:inherited-members:
 	:show-inheritance:
 
+
+Panel class
+-----------
+
 .. autoclass:: rnftools.lavender.Panel
 	:members:
 	:inherited-members:
 	:show-inheritance:
 
+
+BAM class
+---------
+
 .. autoclass:: rnftools.lavender.Bam
 	:members:
 	:inherited-members:
 	:show-inheritance:
-

docs/reference/04_other_tools.rst

@@ -1,4 +1,27 @@
 Other tools
 ===========
 
+``rnf-join-fq.py``
+------------------
 
+A program for joining FASTQ files with reads in RNF format.
+
+.. code::
+
+	$ rnf-join-fq.py  -h
+	usage: rnf-join-fq.py [-h] -i inp [inp ...] -m mode -o out
+
+	Join FASTQ files with reads in RNF format.
+
+	optional arguments:
+	  -h, --help        show this help message and exit
+	  -i inp [inp ...]  input FASTQ files
+	  -m mode           mode for joining files (single-end / paired-end-bwa /
+	                    paired-end-bfast)
+	  -o out            output prefix
+
+	Source FASTQ files should satisfy the following conditions: 1) Each file
+	contains only reads corresponding to one genome (with the same genome id). 2)
+	All files contain reads of the same type (single-end / paired-end). 3) Reads
+	with more reads per tuple (e.g., paired-end) have '/1', etc. in suffix (for
+	identification of nb of read).

docs/resources/read_simulators.rst

@@ -1,5 +1,7 @@
 List of read simulators
-^^^^^^^^^^^^^^^^^^^^^^^
+=======================
+
+Here we provide list of existing read simulators with additional information. Only several of them are supported by RNFtools.
 
 ART
 ~~~
@@ -41,8 +43,7 @@ DwgSim
 | URL:         | http://github.com/nh13/dwgsim                                           |
 +--------------+-------------------------------------------------------------------------+
 
-Format of read names
-""""""""""""""""""""
+**Format of read names**
 
 .. code-block::
 

docs/tutorial.rst

@@ -4,9 +4,6 @@
 Tutorial
 --------
 
-We suppose that you have already read Getting started thay your Snakemake and RNFtools installations are working and
-that you already know how to call Snakemake.
-
 .. toctree::
    :glob:
    :maxdepth: 1

docs/tutorial/00_installation.rst

@@ -2,13 +2,35 @@ Installation
 ------------
 
 Requirements
-""""""""""""
+^^^^^^^^^^^^
+
+Requirements for basic installation of RNFtools.
 
 * Unix-like operating system (Linux, MacOS, etc.).
-* `Python`_ 3.2+. If not installed yet, download it from https://www.python.org/downloads/. This minimum version is required by `SnakeMake`_ on which RNFtools are based.
+* `Python`_ 3.2+.
+
+	* If not installed yet, it can be downloaded it from https://www.python.org/downloads/.
+
+Additional requirements
+"""""""""""""""""""""""
+
+RNFtools is installing all required programs on fly when requisted. Some needed libraries are required for successful compilation. If some of the libraries is missing, a problem will not occur during installation of RNFtools but during execution of RNFtools scripts.
+
+**On Linux**
+
+* *GCC 4.7+*
+* *zlib* library.
+
+**On OSX**
+
+* *XCode*.
+* *pdflib* library. It can be installed by ``brew install pdflib-lite``.
+
+	* RNFtools use PNG and PDF GnuPlot terminals which cannot compiled without this library. 
+
 
 Installation using PIP
-""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^
 
 On most of machines, RNFtools can be installed using `PIP`_ by 
 
@@ -26,7 +48,7 @@ Upgrade to the newest version can be done by `PIP`_, too.
 
 
 Installation using Easy Install
-"""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can install RNFtools also using `Easy Install`_:
 
@@ -36,7 +58,7 @@ You can install RNFtools also using `Easy Install`_:
 
 
 Installation from GIT
-"""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^
 
 If you want to install RNFtools directly from `GIT repository`_, enter these commands:
 
@@ -46,6 +68,7 @@ If you want to install RNFtools directly from `GIT repository`_, enter these com
 	cd rnftools
 	./install.sh
 
+
 .. _Python: http://python.org
 .. _Anaconda: http://continuum.io/downloads
 .. _SnakeMake: http://bitbucket.org/johanneskoester/snakemake/

docs/tutorial/01_first_snakefile.rst

@@ -16,6 +16,8 @@ Every RNFtools script consists of three parts:
 
 .. literalinclude:: ../../examples/tutorial/01_first_snakefile/Snakefile
 	:language: python
+	:linenos:
+
 
 As it has been mentioned in comment, all your code must be inserted into part 2. Now save this file with name ``Snakefile`` and run
 

docs/tutorial/02_simulation.rst

@@ -4,8 +4,8 @@ Read simulation
 In this chapter we show how to simulate reads in basic simulation. For this task, component called MIShmash is used.
 
 
-Simple simulation
-"""""""""""""""""
+Basic example
+"""""""""""""
 
 First let us show how to simulate reads from a single genome (saved in a FASTA file) using a single simulator. Then a
 corresponding RNFtools configuration script can look as follows:
@@ -52,8 +52,6 @@ When you are changing the used simulator, be aware of these limitations:
 * ART Illumina in "paired-end" mode can simulate only reads of equal lengths.
 
 
-
-
 .. literalinclude:: ../../examples/tutorial/02_simulation/03_different_simulator/Snakefile
 	:language: python
 	:linenos:

docs/tutorial/03_evaluation.rst

@@ -1,2 +1,60 @@
 Mapper evalution
 ----------------
+
+In this chapter we show how to evaluate read mappers using read names in RNF format. For this task, component called LAVEnder is used.
+
+Basic example
+"""""""""""""
+
+The basic approach of mapper evaluation consists of the following steps:
+
+1. Simulation of reads (see the previous chapter of this tutorial).
+2. Mapping reads to a reference genome.
+3. Creating the report.
+
+First you need to simulate RNF reads and map them to a reference genome. If you don't have any own BAM file, please use the following toy Snakefile which performs first two steps:
+
+.. literalinclude:: ../../examples/tutorial/03_evaluation/01_simple_evaluation/bams/Snakefile
+	:language: python
+	:linenos:
+
+In a directory for this experiment, create a directory ``bams`` and place there the previous code and run ``snakemake`` there. If you have your own BAM files, create the ``bams`` directory as well and place them there.
+
+Now let us create a directory ``report`` with the following ``Snakefile``:
+
+.. literalinclude:: ../../examples/tutorial/03_evaluation/01_simple_evaluation/report/Snakefile
+	:language: python
+	:linenos:
+
+Evaluation of all BAM files in a dir is requested by creating an instance of the ``rnftools.lavender.Report`` class (line 3). Parameter ``bam_dirs`` accepts a list of directories with BAM files. Every entry of the list corresponds to a single panel in the final HTML report. The ``name`` argument defines name of the report (the final HTML file will have name ``{name}.html``). Parameter ``keep_intermediate_files`` indicates if intermediate MIS and MIR files created during evaluation should be kept. Argument ``allowed_delta`` is used for setting maximum allowed distance between reported position and original position for considering the segment still correctly mapped. 
+
+When you execute ``snakemake``, the report is created.
+
+
+Auxiliary files
+"""""""""""""""
+
+For every BAM file, the following files are created.
+
+* **HTML** -- detailed report for the BAM file
+* **MIS** (mapping information: segments) -- file with information about mapping categories of each segment
+* **MIR** (mapping information: read tuples) -- file with information about category of entire read tuples
+* **ROC** -- source file for plotting graphs, it contains information about how many reads are in which category in dependence on threshold on mapping qualities
+* **GP** -- GnuPlot file used for plotting detailed graphs for this BAM  (**SVG**, **PDF**)
+
+
+Adjusting plotted graphs
+""""""""""""""""""""""""
+
+For details about adjusting graphs, please see Reference/LAVEnder.
+
+First, you can change default values for the basic graphs:
+
+* range of x and y axes (``default_x_run``, ``default_y_run``), 
+* sizes of created PDF and SVG files (``default_pdf_size_cm``, ``default_svg_size_px``)
+* label of x-axis (``default_x_label``)
+* values on x-axis (``default_x_axis``).
+
+Then you can add your own graphs using ``rnftools.lavender.Report.add_graph`` method.
+
+

examples/.gitignore

@@ -1,3 +1,17 @@
-*
-*/
-!Snakefile
+*.html
+*.fq
+*.fastq
+*.fa
+*.fasta
+*.vcf
+*.gz
+*.mir
+*.mis
+*.bam
+*.sam
+*.png
+*.pdf
+*.svg
+*.roc
+*.gp
+*.txt