Merge pull request #311 from AdamaJava/qbasepileup.doc.mar

update document on qbasepileup

Author: ChristinaXu2017

docs/qbasepileup/index.md

@@ -1,4 +1,8 @@
 # qbasepileup
+```diff
+-This tool is dated due to some input file format (dccq, dcc1) is no longer available!
+```
+
 
 ## Introduction
 
@@ -8,39 +12,28 @@ metrics on the reads at the positions of interest.
 
 ## Installation
 
-qbasepileup requires java 7 and (ideally) a multi-core machine (5 threads 
+qbasepileup requires java 8 and (ideally) a multi-core machine (5 threads 
 are run concurrently) with at least 20GB of RAM.
-Download the qbasepileup tar file
-Untar the tar file into a directory of your choice
-You should see jar files for qbasepileup and its dependencies:
 
-~~~~{.text}
-$ tar xjvf qbasepileup.tar.bz2
-x antlr-3.2.jar
-x ini4j-0.5.2-SNAPSHOT.jar
-x jopt-simple-3.2.jar
-x picard-1.110.jar
-x qbamfilter-1.0pre.jar
-x qcommon-0.1pre.jar
-x qio-0.1pre.jar
-x qpicard-0.1pre.jar
-x qpileup-0.1pre.jar
-x sam-1.110.jar
-x jhdfobj.jar
-x jhdf5obj.jar
-x jhdf5.jar
-x jhdf.jar
-~~~~
+* **To do a build of qbasepileup, first clone the adamajava repository using "git clone":**
+  ```
+  git clone https://github.com/AdamaJava/adamajava
+  ```
 
-## Usage
+  Then move into the adamajava folder:
+  ```
+  cd adamajava
+  ```
+  Run gradle to build qbasepileup and its dependent jar files:
+  ```
+  ./gradlew :qbasepileup:build
+  ```
+  This creates the qbasepileup jar file along with dependent jars in the `qbasepileup/build/flat` folder
 
-A general invocation of qbasepileup looks like:
 
-~~~~{.text}
-java -jar qbasepileup.jar [OPTIONS]
-~~~~
+## Usage
 
-A typical invocation might look like:
+A general invocation of qbasepileup looks like:
 
 ~~~~{.text}
 java -jar qbasepileup.jar -m mode \
@@ -50,57 +43,56 @@ java -jar qbasepileup.jar -m mode \
 ## Options
 
 ~~~~{.text}
---help, -h      Show help message.
---version       Print version.
--b              Path to tab delimited file with list of bams.
---bq            Minimum base quality score for accepting a read.
---dup           Include duplicates
--f              Format of SNPs file [ddc1,maf,db,dccq,vcf,torrent,RNA,DNA], Def=dcc1
---filter        Query string for qbamfilter
---gatk          Adjust insertion position to conform to GATK format
---hdf           HDF file to read list of bam files from
---hp            window around indel to check for homopolymers  [default:10]
--i              Path to bam file.
---ig            Path to somatic indel file
---in            Path to normal bam file
---ind           Include reads with indels. (y or n, default y).
---intron        Include reads mapping across introns. (y or n, default y).
---is            Path to somatic indel file
---it            Path to tumour bam file
---log           Req, Log file.
---loglevel      Logging level required, e.g. INFO, DEBUG. Default INFO.
--m              snp,indel,coverage or compoundsnp
---maxcov        Report reads that are less than the mininmum coverage option. Integer
---mincov        Report reads that are less than the
---mq            Minimum mapping quality score for accepting a read.
--n              Bases around indel to check for other indels., Def=3.
---novelstarts   Report novelstarts rather than read count [Y,N], Def=Y.
--o              Output file.
---of            Output file format [rows,columns].
---og            Output file for germline indels.
---os            Output file for somatic indels.
--p              Pileup profile type [ddc1,maf,db,dccq,vcf,torrent,RNA,DNA] Def=dcc1.
---pd            <pindel_deletions> Path to normal bam file
---pindel        adjust insertion position to conform to pindel format
--r              Path to reference genome fasta file.
--s              Path to tab delimited file containing snps. Formats: dcc1,dccq,vcf,maf,txt
---sc            <soft_clip_window> number of bases around indel to check for softclipped bases [default:13]
---strand        Separate coverage by strand. (y or n, default y)
---strelka       adjust insertion position to conform to strelka format (same as pindel)
--t              Thread number. Total = number supplied + 2.
+Option                   Description                                                                             
+------                   -----------                                                                             
+-V, -v, --version        Print version info.                                                                     
+-b <txt file>            Opt (coverage and snp mode),  path to tab delimited file with list of bams.             
+--bq <Integer>           Opt (snp related mode), minimum base quality score for accepting a read. Def = null.    
+--dup                    Opt (indel and snp mode), a flag to include duplicates reads.                           
+-f [format]              Opt(snp mode) snp file format: [dcc1, dccq, vcf, tab, maf].Def=dcc1. or                 
+                         Opt(coverage mode), snp file format: [dcc1, dccq, vcf, tab, maf, gff3, gtf]. Def=dcc1.  
+--filter <query>         Opt, a qbamfilter query to filter out BAM records. Def=null.                            
+--gatk                   Opt (indel mode), a flag to conform gatk format, but do nothing.                        
+-h, --help               Shows this help message.                                                                
+--hdf <hdf file>         Opt (snp mode), path to hdf file which header contains a list of bams.                  
+--hp <Integer>           Opt (indel mode), base around indel to check for homopolymers. Def=10.                  
+-i <bam file>            Opt (coverage and snp mode), specify a single SAM/BAM file here.                        
+--ig <dcc1>              Req (indel mode), path to germline indel file in dcc1 format.                           
+--in <bam file>          Req (indel mode), path to normal bam file                                               
+--ind <y|n>              Opt (snp related mode), include reads with indels [y,n]. Def=y.                         
+--intron <y|n>           Opt (snp related mode), include reads mapping across introns [y,n]. Def=y.              
+--is <dcc1>              Req (indel mode), path to somatic indel file in dcc1 format.                            
+--it <bam file>          Req (indel mode), path to tumour bam file                                               
+--log                    Req, log file.                                                                          
+--loglevel               Opt, logging level required, e.g. INFO, DEBUG. Default INFO.                            
+-m <mode>                Opt, Mode [snp, compoundsnp, snpcheck, indel, coverage]. Def=snp.                       
+--mincov <Integer>       Opt, report reads that are less than the mininmum coverage option.                      
+--mq <Integer>           Opt (snp related mode), minimum mapping quality score for accepting a read. Def = null. 
+-n <Integer>             Opt (indel mode), bases around indel to check for other indels. Def=3.                  
+--novelstarts <y|n>      Opt (snp related mode), report novelstarts rather than read count [Y,N], Def=y.         
+-o <txt file>            Req (coverage and snp related mode), the output file path.                              
+--of <format>            Opt (snp mode only), output file format [columns]. this option only works with input snp
+                           file format is tab, otherwise it will ignored.                                        
+--og <dcc1>              Req (indel mode), output file for germline indels.                                      
+--os <dcc1>              Req (indel mode), output file for somatic indels.                                       
+-p [profile]             Opt (snp mode), pileup profile type [torrent,RNA,DNA, standard]. Def="standard".        
+--pd <pindel_deletions>  Req (indel mode), path to normal bam file                                               
+--pindel                 Opt (indel mode), a flag to conform pindel format, but do nothing.                      
+-r <fasta file>          Req (indel and snp mode), path to reference genome fasta file.                          
+-s <txt file>            Req (coverage and snp mode), path to tab delimited file containing snps.                
+--sc <Integer>           Opt (indel mode), bases around indel to check for softclip. Def=13.                     
+--strand <y|n>           Opt (snp related mode), separate coverage by strand [y,n]. Def=y.                       
+--strelka                Opt (indel mode), a flag to conform strelka format, but do nothing.                     
+-t [Integer]             Opt, number of worker threads (yields n+2 total threads). Def=1.         
 ~~~~
 
+## Modes
+### coverage
 
-### `-n`
-
-This integer is the number of bases around and indel to check for nearby
-indel.  Default=3.
-
-### `--pd`
+Reads one or more BAM files, and a file containing reference ranges and
+piles up the reads around the indel to count the number of reads covering
+each position in the range.
 
-<pindel_deletions> Path to normal bam file
-
-## Modes
 
 ### [snp](qbasepileup_snp_mode)
 
@@ -111,24 +103,31 @@ region. Coverage per nucleotide is reported and the total coverage at that
 position is reported. By default, duplicates and unmapped reads are excluded.
 
 ### [compoundsnp](qbasepileup_compound_snp_mode)
+```diff
+-This mode is deprecated due to the input snp position file format (dcc1) is no longer available!
+```
 
-Reads one or more BAM files, a reference genome, and a file containing 
-positions of compound SNPs (SNPs that sit next to each other). It finds the
-reference genome base at the compound SNP positions as well as the bases 
-found at that position in all reads aligned to that region. Coverage per 
-nucleotide is reported and the total coverage at that position is reported. 
 
-By default, the `--filter` qbamfilter query string is:
+In this mode, qbasepileup reads one or more BAM files, a reference genome, and a file containing positions of compound SNPs (SNPs that sit next to each other). It finds the reference genome base at the compound SNP positions as well as the bases found at that position in all reads aligned to that region. Coverage per nucleotide is reported and the total coverage at that position is reported. By default, the filter is:
 
 ~~~~{.text}
 and( Flag_DuplicateRead==false, CIGAR_M>34, MD_mismatch <= 3, option_SM > 10)
 ~~~~
 
 For a more detailed description of qbamfilter and how it works to filter
-reads in and out of a particular analysis, see
-[qbamfilter](../qbamfilter/).
+reads in and out of a particular analysis, see[qbamfilter](../qbamfilter/).
+
+
+This mode is for compound SNPs, is very similar to [snp mode](qbasepileup_snp_mode.md) except:
+
+* Only dcc1 format (`-f`) is currently accepted
+* Default filter is: `and(Flag_DuplicateRead==false, CIGAR_M>34, MD_mismatch<=3, option_SM>10)`
+
 
 ### [indel](qbasepileup_indel_mode)
+```diff
+-This mode is deprecated due to the indle file format (dcc1) is no longer available!
+```
 
 Reads tumour and normal BAM files, a reference genome, and somatic and/or 
 germline files containing positions of indels and pileups the reads around 
@@ -141,9 +140,27 @@ the indel to count a number of metrics. Metrics include:
 * number of reads with nearby soft clipping
 * number of reads with nearby indels
 
-### coverage
+#### Examples
 
-Reads one or more BAM files, and a file containing reference ranges and
-piles up the reads around the indel to count the number of reads covering
-each position in the range.
+* Somatic and Germline input files in pindel format
+~~~~{.text}
+qbasepileup -t 2 -m indel -r reference.fa --pindel \
+    --it tumour.bam --in normal.bam \
+    --is somatic.input.dcc1 --ig germline.input.dcc1 \
+    --os somatic.output.dcc1 --og germline.output.dcc1 \
+    --log basepileup.log
+~~~~
+
+* Somatic input file in gatk format
+~~~~{.text}
+qbasepileup -t 2 -m indel --it tumour.bam --in normal.bam \
+    --is somatic.input.dcc1 --os somatic.output.dcc1 
+    --log basepileup.log -r reference.fa --gatk
+~~~~
 
+* Germline input file in pindel format
+~~~~{.text}
+qbasepileup -t 2 -m indel --it tumour.bam --in normal.bam \
+    --ig germline.input.dcc1 --og germline.output.dcc1
+    --log basepileup.log -r reference.fa --pindel
+~~~~