:py:mod:`ecoPCR`: *in silico* PCR
=================================

author: Eric Coissac <eric.coissac@metabarcoding.org>

:py:mod:`ecoPCR` *in silico* PCR that preserves the taxonomic information 
of the selected sequences, and allows various specified conditions for the
*in silico* amplification.

Additionally to the different options, the command requires two arguments corresponding 
to the two primers.

   
:py:mod:`ecoPCR` specific options
---------------------------------   

   .. cmdoption::   -d <filename>   
   
        Filename containing the database used for the *in silico* PCR. The database
        must be in the ``ecoPCR format`` (see :py:mod:`obiconvert`). 
        
        .. WARNING:: This option is compulsory.
                       
  
   .. cmdoption::  -e <INTEGER>  
   
         Maximum number of errors (mismatches) allowed per primer (default: 0).
         See example 2 for avoiding errors on the 3' end of the primers.
                               
  
   .. cmdoption::  -l <INTEGER>   
   
			Minimum length of the *in silico* amplified DNA fragment, excluding primers.
                       
  
   .. cmdoption::  -L <INTEGER>   
   
			Maximum length of the *in silico* amplified DNA fragment, excluding primers.
                       
  
   .. cmdoption::  -r <TAXID>   
   
            Only the sequence records corresponding to the taxonomic group identified by its 
            ``TAXID`` are considered for the *in silico* PCR. The ``TAXID`` is an integer that 
            can be found either in the NCBI taxonomic database, or using the :py:mod:`ecofind` programme. 
  
   .. cmdoption::  -i <TAXID>   
    
			The sequences of the taxonomic group identified by its ``TAXID`` are not considered for 
			the *in silico* PCR.
                       
  
   .. cmdoption::  -c   
   
			Considers that the sequences of the database are circular (e.g. mitochondrial
			or chloroplast DNA).
                       
  
   .. cmdoption::  -D <INTEGER>   
   
			Keeps the specified number of nucleotides on each side of the *in silico* 
			amplified sequences, (including the amplified DNA fragment plus the two target 
			sequences of the primers).


   .. cmdoption::  -k   
   
			Print in the programme output the kingdom of the *in silico* amplified 
			sequences (default: print the superkingdom).
                       
  
   .. cmdoption::  -m <1|2>  
   
			Defines the method used for estimating the Tm (melting temperature) between 
			the primers and their corresponding target sequences (default: 1).
			
				1 SantaLucia method (SantaLucia J (1998) A unified view of polymer, dumbbell, and oligonucleotide DNA nearest-neighbor thermodynamics. PNAS, 95, 1460-1465).
				
				2 Owczarzy method (Owczarzy R, Vallone PM, Gallo FJ *et al.* (1997) Predicting sequence-dependent melting stability of short duplex DNA oligomers. Biopolymers, 44, 217-239).
				
                       
  
   .. cmdoption::  -a <FLOAT>
   
			Salt concentration used for estimating the Tm (default: 0.05).
                       
  
   .. cmdoption::  -h   
   
            Print help.
                       
  
  
Output file
-----------
	
		The output file contains several columns, with '|' as separator, and describes 
		the properties of the *in silico* amplified sequences.
			
		column 1: sequence identification in the reference database (= accession number when using EMBL or GenBank for building the reference database)
			
		column 2: length of the original sequence
			
		column 3: scientific name as indicated in the reference database
			
		column 4: taxonomic rank as indicated in the reference database
			
		column 5: TAXID of the species
			
		column 6: scientific name of the species
			
		column 7: TAXID of the genus
			
		column 8: genus name
			
		column 9: TAXID of the family
			
		column 10: family name
			
		column 11: TAXID of the super kingdom (or of the kingdom if the ``-k`` option is set)
			
		column 12: super kingdom name (or kingdom name if the ``-k`` option is set)
			
		column 13: strand (D or R, corresponding to direct or reverse, respectively)
			
		column 14: target sequence of the first primer
			
		column 15: number of mismatches for the first primer
			
		column 16: target sequence of the second primer
			
		column 17: number of mismatches for the second primer
			
		column 18: length of the amplified fragment (excluding primers)
			
		column 19: sequence
			
		column 20: definition  

  
  
Examples
--------
	
	*Example 1:*
	    
	    		.. code-block:: bash
	    
	       			>  ecoPCR -d mydatabase -e 3 -l 50 -L 500 TCACAGACCTGTTATTGC TYTGTCTGSTTRATTSCG > mysequences.ecopcr 
	     
			Launches an *in silico* PCR on mydatabase (in the ``ecoPCR format``, see :py:mod:`obiconvert`), 
			with a maximum of three mismatches for each primer. The minimum and maximum amplified sequence 
			lengths (excluding primers) are 50 bp and 500 bp, respectively. The primers used are 
			TCACAGACCTGTTATTGC and TYTGTCTGSTTRATTSCG (possibility to use :doc:`IUPAC codes <../iupac>`). 
			They amplify a short portion of the nuclear 18S gene. The results are saved in the 
			mysequence.ecopcr file.
	   
	
	
	*Example 2:*
	    
	    		.. code-block:: bash
	    
	       			> ecoPCR -d mydatabase -e 2  -l 80 -L 120 -D 50 -r 7742 TTAGATACCCCACTATG#C# TAGAACAGGCTCCTCTA#G# > mysequences.ecopcr
	     
			Launches an *in silico* PCR on mydatabase (in the ``ecoPCR format``, see :py:mod:`obiconvert`), 
			with a maximum of two mismatches for each primer, but with a perfect match on the last two nucleotides 
			of the 3' end of each primer (a perfect match can be enforced by adding a '#' after the considered 
			nucleotide). The minimum and maximum amplified sequence lengths (excluding primers) are 80 bp and 120 bp, 
			respectively. The ``-D`` option keeps 50 nucleotides on each side of the *in silico* amplified sequences, 
			(including the amplified DNA fragment plus the two target sequences of the primers). The primers used 
			are TTAGATACCCCACTATGC and TAGAACAGGCTCCTCTAG. They amplify a short portion of the mitochondrial 12S 
			gene. The ``-r`` option restricts the search to vertebrates (7742 is the TAXID of vertebrates). The 
			results are saved in the mysequence.ecopcr file.
	   
	   
References
----------
		
	Bellemain E, Carlsen T, Brochmann C, Coissac E, Taberlet P, Kauserud H (2010) ITS as an environmental DNA barcode for fungi: an *in silico* approach reveals potential PCR biases BMC Microbiology, 10, 189.

	Ficetola GF, Coissac E, Zundel S, Riaz T, Shehzad W, Bessiere J, Taberlet P, Pompanon F (2010) An *in silico* approach for the evaluation of DNA barcodes. BMC Genomics, 11, 434.
	
	   
	

