Skip to content

Sample Classification tools

Jump to bottom
Olivo Miotto edited this page Nov 22, 2016 · 10 revisions

Single Sample Classification Tool

Invoking the Sample Classification tool for a single sample:

 java -Xms512m -Xmx2000m 'org.cggh.bam.sampleClass.SampleClassAnalysis$SingleSample' \
     <CONFIG_FILE> <SAMPLE_NAME> <BAM_FILE> <CHR_MAP_NAME> \
     <REF_FASTA_FILE> <CHR_MAP_FILE> <OUT_DIR>

Note that the qualified class name HAS to be between single quotes. The parameters are as follows:

  • CONFIG_FILE This is a configuration file, defining loci and targets, in Java .properties format. The format is specified in section “Sample Class configuration file”
  • SAMPLE_NAME The identifier of the sample, e.g. “PA0001-C”
  • BAM_FILE The path of the BAM file for the sample
  • CHR_MAP_NAME The name of the chromosome name map to be used for this sample (e.g. “default”). See section “Chromosome Maps”
  • REF_FASTA_FILE The path to a FASTA file containing the reference sequence used for alignment.
  • CHR_MAP_FILE The path to a file specifying the chromosome name maps available. See section “Chromosome Maps”.
  • OUT_DIR The path to the folder where the output files will be written to.

Multiple Sample Classification Tool

Invoking the Sample Classification tool for multiple samples:

java -Xms512m -Xmx2000m 'org.cggh.bam.sampleClass.SampleClassAnalysis$MultiSample' \
     <CONFIG_FILE> <SAMPLE_LIST_FILE> \
     <REF_FASTA_FILE> <CHR_MAP_FILE> <OUT_DIR>

Note that the qualified class name HAS to be between single quotes. The parameters are as follows:

  • CONFIG_FILE This is a configuration file, defining loci and targets, in Java .properties format. The format is specified in section “Sample Class configuration file”

  • SAMPLE_LIST_FILE The path of tab-separated text file, with one line (record) per sample to be processed. Each record contains three fields:

    • SAMPLE_NAME The identifier of the sample, e.g. “PA0001-C”
    • BAM_FILE The path of the BAM file for the sample
    • CHR_MAP_NAME The name of the chromosome name map to be used for this sample (e.g. “default”). See section “Chromosome Maps”

  • REF_FASTA_FILE The path to a FASTA file containing the reference sequence used for alignment.

  • CHR_MAP_FILE The path to a file specifying the chromosome name maps available. See section “Chromosome Maps”.

  • OUT_DIR The path to the folder where the output files will be written to.

Sample Classification Tools Outputs

The Sample Classification tools output two tab-separated text files for each sample. These files are placed in an output folder <OUT_DIR>/<SUB> where <SUB> is a string consisting of the first 4 letters of the sample name. For example, file PA0001-C.alleles.tab will be written to folder <OUT_DIR>/PA00. This simple file hashing scheme, which is particularly suited for the MalariaGEN naming scheme, prevents thousands of files accumulating in a single folder, which may cause indexing problems especially on Linux.

  • <SAMPLE_NAME>.classAlleles.tab contains one line (record) for each distinct class allele at each target. Each record has the following fields:

    • Num A sequential record number (can be ignored)
    • Sample The identifier of the sample, e.g. “PA0001-C”
    • Locus The name of the target’s locus, as specified in the configuration file
    • Target The name of the target, as specified in the configuration file
    • Allele The name of the target allele (a class or set of classes)
    • Count The number of supporting reads for this allele
    • SampleClass The sample class inferred as a result (e.g. the species)

  • <SAMPLE_NAME>.unlistedAlleles.tab contains one line (record) for each allele identified at each locus that was NOT one of the listed class alleles. This file can be informative for discovering new alleles that should be added to the configuration because they are present in numerous samples. Each record has the following fields:

    • Num A sequential record number (can be ignored)
    • Sample The identifier of the sample, e.g. “PA0001-C”
    • Locus The name of the target’s locus, as specified in the configuration file
    • Target The name of the target, as specified in the configuration file
    • Allele The nucleotide sequence of the target allele (result of concatenation, if this is specified in the configuration file)
    • Count The number of supporting reads for this allele in this sample
    • Proportion The proportion of reads for this allele in this sample
    • Closest The class whose target allele is the closest to the reported unlisted allele (i.e. it has fewest sequence differences)
    • Diff The number of sequence differences between the unlisted allele and the closest class allele

Sample Classification Aggregation Tool

The Sample Classification Aggregation Tool uses the files produced by the Sample Classification Tool and aggregates them, producing sampleset-wide outputs. The tool also scans the results for multiple targets, and determines whether there is consensus in assigning a class to the sample.

Invoking the Sample Classification Aggregation tool:

java -Xms512m -Xmx2000m 'org.cggh.bam.sampleClass.SampleClassAnalysis$MergeResults' \
     <CONFIG_FILE> <SAMPLE_LIST_FILE> \
     <REF_FASTA_FILE> <CHR_MAP_FILE> <OUT_DIR>

Note that the qualified class name HAS to be between single quotes. The parameters are as follows:

  • REF_FASTA_FILE
  • CONFIG_FILE This is a configuration file, defining loci and targets, in Java .properties format. The format is specified in section “Sample Class configuration file”
  • SAMPLE_LIST_FILE The path of tab-separated text file, with one line (record) per sample to be processed (note, only the first column is used here) . Each record contains three fields:
    • SAMPLE_NAME The identifier of the sample, e.g. “PA0001-C”
    • BAM_FILE The path of the BAM file for the sample
    • CHR_MAP_NAME The name of the chromosome name map to be used for this sample (e.g. “default”). See section “Chromosome Maps”
  • REF_FASTA_FILE The path to a FASTA file containing the reference sequence used for alignment.
  • CHR_MAP_FILE The path to a file specifying the chromosome name maps available. See section “Chromosome Maps”.
  • OUT_DIR The path to the folder where the output files will be written to.

Sample Classification Aggregation Tool Outputs

The Sample Classification Aggregation tool outputs several tab-separated text files in output folder <OUT_DIR>

  • AllSamples-AllTargets.classes.tab This is the main output file, which summarizes the class calls for all samples. Each line (record) shows the results for a sample, with the following fields:

    • Num A sequential record number (can be ignored)
    • Sample The identifier of the sample, e.g. “PA0001-C”
    • SampleClass The class assigned to the sample. If evidence is found for multiple classes, the class labels are reported as a comma-separated list. If a class label is followed by an asterisk, this means that that class is assigned with evidence but not consensus; i.e. there are some targets where the relevant allele was not observed.
    • One column per target, showing the class labels assigned at that locus. If evidence is found for multiple classes, the class labels are reported as a comma-separated list. At some loci, a given allele is assigned to multiple classes (e.g. to P. vivax and P. knowlesi); in this case, the labels are separated by a vertical bar.

  • AllSamples-<LOCUS>_<TARGET>.classAlleles.tab There is one of these files produced per target. It shows the counts of reads supporting each class, as observed in each sample at this target. Each record represents one sample, with the following fields:

    • Num A sequential record number (can be ignored)
    • Sample The identifier of the sample, e.g. “PA0001-C”
    • One column per class, containing the number of reads supporting the class in the sample.
    • SampleClass The class assigned to the sample. If evidence is found for multiple classes, the class labels are reported as a comma-separated list. If a class label is followed by an asterisk, this means that that class is assigned with evidence but not consensus; i.e. there are some targets where the relevant allele was not observed.

  • AllSamples-<LOCUS>_<TARGET>.unlistedAlleles.tab There is one of these files produced per target. It shows the counts of reads supporting each unlisted allele, as observed in each sample at this target. Each record represents one allele in one sample. This is essentially a concatenation of rows from all the <SAMPLE_NAME>.unlistedAlleles.tab files.

  • AllSamples-UnlistedAllelesStats.tab This file summarizes all unlisted alleles found, and can be useful to identify major class markers that are not included in the configuration file. It contains on record per allele at a given target, with the following fields:

    • Num A sequential record number (can be ignored)
    • Locus The name of the target’s locus, as specified in the configuration file
    • Target The name of the target, as specified in the configuration file
    • Allele The nucleotide sequence of the target allele (result of concatenation, if this is specified in the configuration file)
    • SampleCount The number of samples in which reads with this allele were found
    • MaxReadProp The highest proportion of reads containing this allele in any sample
    • MaxReadCount The highest number of reads containing this allele in any sample
    • Closest The class whose target allele is the closest to the reported unlisted allele (i.e. it has fewest sequence differences)
    • Diff The number of sequence differences between the unlisted allele and the closest class allele

#Sample Class configuration file

The configuration file for the Sample Classification tools is a file in Java .properties format (a text-based file of name/value pairs). The following properties are specified:

  • sampleClass.classes A comma-separated list of class names (e.g. species) that will be used in the analysis

  • sampleClass.loci A comma-separated list of locus names that will be used in the analysis

  • sampleClass.remapAllReads If set to 'true' all BAM-mapped reads will be remapped using the anchors (see below) instead of using the BAM-assigned position. Default (when property is missing) is 'false'.

  • sampleClass.locus.<LOCUS_NAME>.region The span of the locus, over which mapped reads will be analyzed, in the form <chr>:<startPos>-<endPos> (must be specified for each locus)

  • sampleClass.locus.<LOCUS_NAME>.analyzeUnmappedReads If set to 'true' the unmapped reads in the BAM will be searched for anchor sequences and remapped. Default (when property is missing) is 'false'. This has a performance impact, so it should only be set to true at loci thought to be problematic for alignments.

  • sampleClass.locus.<LOCUS_NAME>.anchors A comma-separated list of the anchors (regex) that will be used to match the reads. Each anchor is specified in the format <anchorStartPos>@<regex>

  • sampleClass.locus.<LOCUS_NAME>.targets A comma-separated list of the targets where genotyped alleles will be matched to the alleles of the classes. Each target is specified in the format <targetName>@<spans>, where <spans> is a sequence of one or more nucleotide position intervals which are concatenated to form the target allele; they are specified as <span1StartPos>-<span1EndPos>&<span2StartPos>-<span2EndPos>&...

  • sampleClass.locus.<LOCUS_NAME>.target.<CLASS_NAME>.alleles A comma-separated list of alleles that are matched exactly at the target to assign one or more classes, in the format <classList>@<alleles>, where <classList> is one or more class names separated by vertical bar characters, and <alleles> is one or more alleles (produced by concatenation of target spans) separated by vertical bar character.

The following is an example of a configuration file that will inspect two region of the mitochondrion to assign up to 6 species to the sample:

sampleClass.classes=Pf,Pv,Pm,Pow,Poc,Pk
sampleClass.loci=mito1,mito2 
#
sampleClass.locus.mito1.region=M76611:520-820 
sampleClass.locus.mito1.anchors=651@CCTTACGTACTCTAGCT....ACACAA
sampleClass.locus.mito1.targets=species1@668-671&678-683
sampleClass.locus.mito1.target.species1.alleles=Pf@ATGATTGTCT|ATGATTGTTT,Pv@TTTATATTAT,Pm@TTGTATTAAT,Pow@ATTTACATAA,Poc@ATTTATATAT,Pk@TTTTTATTAT
#
sampleClass.locus.mito2.region=M76611:600-900 
sampleClass.locus.mito2.anchors=741@GAATAGAA...GAACTCTATAAATAACCA
sampleClass.locus.mito2.targets=species2@728-733&740-740&749-751&770-773
sampleClass.locus.mito2.target.species2.alleles=Pf@GTTCATTTAAGATT|GTTCATTTAAGACT,Pv|Pk@TATTCATAAATACA,Pm@GTTCAATTAGTACT,Pow|Poc@GTTACAATAATATT

Clone this wiki locally