v1_README

# README
IronThrone-GoT: processes GoT amplicon data and generates a table of metrics


(Getting Ready)
  (1) amplicon R1.fastq & R2.fastq files:
      - R1.fastq (includes barcodes and UMIs sequences)
        R2.fastq (includes primer, shared and targeted sequences)

      - IronThrone-GoT supports both uncompressed and GZipped formats.

  (2) config file:
      - To scan the expected sequences at specific positions in amplicon reads,
        .config file should be prepared as follows.

        (linear_example.config)
        (1st row)  primer.sequence start.pos end.pos
        (2nd row)  shared.sequence start.pos end.pos
        (3rd row)      WT.sequence start.pos end.pos
        (4th row)     MUT.sequence start.pos end.pos
        GCAGCAGAGAAACAAATGAAGGA 1 23
        AAACAGGACGAGGAGCAGAGG 25 45
        AAGAAGACAAG 59 69
        TGAGGACAAAG 59 69

        (circ_example.config)
        (1st row)          primer.sequence start.pos end.pos
        (2nd row)          shared.sequence start.pos end.pos
        (3rd row)              WT.sequence start.pos end.pos
        (4th row)             MUT.sequence start.pos end.pos
        (5th row)   PCR#2Fw_in_WT.sequence start.pos end.pos
        (6th row)  PCR#2Fw_in_MUT.sequence start.pos end.pos
        (7th row)   PCR#2Rv_in_WT.sequence start.pos end.pos
        (8th row)  PCR#2Fv_in_MUT.sequence start.pos end.pos
        GAAGAAGACAAGAAACGCAAAGAGG 1 25
        AGGAGGAGGCAGAGGACAA 26 44
        GGAGGATGATG 45 55
        TTGTCGGAGGA 45 55
        TGAGGATGAGGAGGATGAGG 66 85
        TGAGGATGAGGAGGATGAGG 71 90
        CACTGAGAATGTAAGAACTACAAACAA 96 122
        CACTGAGAATGTAAGAACTACAAACAA 101 127

      - A config file should be prepared in tab-separated format.

  (3) whitelist barcode file:
      - This file provides a list of barcodes that are put in preparation
        for both GoT and 10X libraries, so that false barcodes are distinguished.

      - Whitelisted barcode files provided by 10X are collected at barcodes10X/.
        Choose the whitelist barcode file considering which 10X chemistry version used:
        10X v2.chemistry: 737K-august-2016.txt (default)
        10X v3.chemistry: 3M-february-2018.txt

        * Also, the length of UMI depends on 10X chemistry version so set --bclen if needed.
        10X v2.chemistry: 10 (default)
        10X v3.chemistry: 12


(Output table)
  - (prefix).summTable.txt is a table of
    aggregated (semi-colon separated) and averaged metrics sorted by unique cell barcode and UMI.

  - Column headers are shown as follows:
    1) [BC] barcode
    2) [whitelist]
        Y:barcode was perfectly matched with the whitelisted barcodes
        N:barcode was not perfectly matched with the whitelisted barcodes, and replaced with statistical significance
    3) [UMI] UMIs sharing the same barcode
    4) [num.WT.in.dups] counts of WT calls for each duplicate read (barcode + each UMI)
    5) [num.MUT.in.dups] counts of MUT calls for each duplicate read (barcode + each UMI)
    6) [num.amb.in.dups] counts of amb calls for each duplicate read (barcode + each UMI)
    7) [call.in.dups] calls for each duplicate read (barcode + each UMI)
    8) [avg.base_error.R2] average of base errors for entire R2.fastq reads sharing the same barcode
    9) [avg.base_error.primer] average of base errors for the primer region in R2.fastq reads sharing the same barcode
   10) [avg.base_error.shared] average of base errors for the shared region in R2.fastq reads sharing the same barcode
   11) [avg.base_error.WT] average of base errors for the WT region in R2.fastq reads sharing the same barcode
   12) [avg.base_error.MUT] average of base errors for the MUT region in R2.fastq reads sharing the same barcode
   13) [mismatch.primer] counts of mismatches in the primer region for each duplicate read (barcode + each UMI)
   14) [mismatch.shared] counts of mismatches in the shared region for each duplicate read (barcode + each UMI)
   15) [mismatch.WT] counts of mismatches in the WT region for each duplicate read (barcode + each UMI)
   16) [mismatch.MUT] counts of mismatches in the MUT region for each duplicate read (barcode + each UMI)
   17) [WT.calls] counts of total WT call
   18) [MUT.calls] counts of total MUT call
   19) [amb.calls] counts of total amb call

(Run an example)
  - Test with example .fastq and .config files at testdata/

    #(linear-GoT)
      IronThrone-GoT --run linear \
                     --fastqR1 linear_example.R1.fastq --fastqR2 linear_example.R2.fastq --config linear_example.config \
                     --outdir game --log of --sample throne
    #(circ-GoT)
      IronThrone-GoT --run circ \
                     --fastqR1 circ_example.R1.fastq --fastqR2 circ_example.R2.fastq --config circ_example.config \
                     --outdir game --log of --sample throne


  - See more options:
    $> IronThrone-GoT --help