V(D)J junction mapping

CdrBlast-batch

Description

A script to extract CDR3 sequences. Will properly combine reads coming from paired and overlapped data and perform analysis for both raw and assembled data.

Performs CDR3 extraction and V/J segment determination for both raw (Checkout output) and assembled-data. Gene parameter -R is required unless metadata (--sample-metadata) is provided that specifies gene for each sample; supported genes are TRA, TRB, TRG, TRD, IGH, IGK and IGL. If either of assembly_output_folder or checkout_output_folder is not specified, the processing will be done solely for the remaining input, this is useful e.g. if one wants quickly process the assembled data. Otherwise only samples and file types (paired, overlapped or single) that are present in both outputs will be used. Processing both raw and assembled data is required for second stage error correction (removal of hot-spot errors).

Usage

General:

java -jar migec.jar CdrBlastBatch [options] -R gene [checkout_output_folder/ or .] [assemble_output_folder/ or .] output_folder

Several default CdrBlast parameters could be set,

--default-mask <R1=[0,1]:R2=[0,1]> - mask which specifies for which read(s) in paired-end data to perform CDR3 extraction. In case of 0:0 mask will process only overlapped reads --default-species - default species to be used for all samples, human (used by default) or mouse --default-file-types - default file types (paired, overlapped or single) to be processed for each sample. If several file types are specified, the corresponding raw and assembled files will be combined and used as an input to CdrBlast

--default-quality-threshold <Phred=[2..40],CQS=[2..40]> - quality threshold pair, default for all samples. First threshold in pair is used for raw sequence quality (sequencing quality phred) and the second one is used for assembled sequence quality (CQS score, the fraction of reads in MIG that contain dominant letter at a given position) --no-sort - no sorting is performed for output files which speeds up processing. Could be safely used in full pipeline as FilterCdrBlastResults will provide final clonotype table in sorted format

A sample metadata file could also be provided with --sample-metadata <file_name> argument to guide the batch CDR3 extraction. This file should have the following tab-separated table structure:

Sample ID Species Gene File types Mask Quality threshold pair
S0 human TRA paired, overlapped 1:0 25,30
S1 human TRB unpaired
25,30
S2 mouse TRB,TRA paired 0:1 20,25

See section below for more details.

Output format

The output of V-D-J mapping routines of MIGEC is a standard tab-delimited clonotype table with some information on the number of reads and UMI tags that correspond to a given clonotype.

Each clonotype is specified by count, fraction, V, D and J segment identifier list, CDR3 nucleotide and amino acid sequence.

The positions of last V nucleotide, first and last D nucleotide, and first J nucleotide specify the germline region markup within the hypervariable CDR3 sequence, they are given in 0-based coordinates where 0 marks the first base of CDR3.

The total reads and good reads fields contain the number of reads supporting a given clonotype prior to and after the quality filtering.

The total events and good events fields contain the number of UMI tags supporting a given clonotype prior to and after the quality filtering. For raw (unassembled) data these are equal to total reads and good reads respectively.

CdrBlast-manual

Description

A script to map V-(D)-J junctions, extract CDR3 sequences and assemble clonotypes.

Usage

General:

java -jar migec.jar CdrBlast [options] -R gene file1.fastq[.gz] [file2.fastq[.gz] ...] output_file

Standard, assuming an example of a library containing T-cell Receptor Alpha Chain sequences

in case of MIG-assembled data:

java -jar migec.jar CdrBlast -a -R TRA assembly/S1_R2.fastq.gz cdrblast/S1_asm.cdrblast.txt

for raw data:

java -jar migec.jar CdrBlast -R TRA checkout/S1_R2.fastq.gz cdrblast/S1_raw.cdrblast.txt

to concatenate and process two or more FASTQ files at once:

java -jar migec.jar CdrBlast -R TRA checkout/S1_R2.fastq.gz checkout/S2_R2.fastq.gz cdrblast/S12_raw.cdrblast.txt

Gene parameter -R is required, supported genes are TRA, TRB, TRG, TRD, IGH, IGK and IGL. Several chains can be specified, for example -R TRA,TRB or -R IGH,IGL. Species could be provided with -S parameter, by default uses HomoSapiens, supported species are HomoSapiens, MusMusculus and others. Assembled data should be passed to the script with -a option. --same-sample option should be used if several assembled files are provided from the same sample, so duplicate UMIs will be discarded and not counted twice.

To get a sorted output use -o option, otherwise sorting will be performed at FilterCdrBlastResults step. Note that both raw and assembled data should be processed to apply the last step of filtration.

Note

In order to use all alleles, not just the major (*01 ones), use the --all-alleles option. To include non-coding segments (V segment pseudogenes) use the --all-segments option.