correct-rna-reads

Error-correct RNA reads against the cluster each was assigned to.

Usage

Template:

exacto correct-rna-reads \
    --bam-file <bam_file> \
    --clusters-tsv-file <clusters_tsv_file> \
    --cluster-reference-transcripts-tsv-file <cluster_reference_transcripts_tsv_file> \
    --cluster-splice-junctions-tsv-file <cluster_splice_junctions_tsv_file> \
    --cluster-variants-tsv-file <cluster_variants_tsv_file> \
    --reference-gene-annotation-file <reference_gene_annotation_file> \
    --output-dir <output_dir> \
    --output-prefix <output_prefix> \
    [--max-correctable-event-len MAX_CORRECTABLE_EVENT_LEN] \
    [--corrected-base-quality CORRECTED_BASE_QUALITY] \
    [--trim-transcript-ends] \
    [--reference-gene-annotation-source REFERENCE_GENE_ANNOTATION_SOURCE] \
    [--reference-gene-annotation-assembly REFERENCE_GENE_ANNOTATION_ASSEMBLY] \
    [--reference-gene-annotation-version REFERENCE_GENE_ANNOTATION_VERSION] \
    [--num-threads NUM_THREADS] \
    [--chunk-size CHUNK_SIZE]

Example:

exacto correct-rna-reads \
    --bam-file tumor_rna.sorted.bam \
    --clusters-tsv-file pass1/tumor_pass1_exacto_rna_clusters.tsv \
    --cluster-reference-transcripts-tsv-file pass1/tumor_pass1_exacto_rna_clusters_reference_transcripts.tsv \
    --cluster-splice-junctions-tsv-file pass1/tumor_pass1_exacto_rna_clusters_splice_junctions.tsv \
    --cluster-variants-tsv-file pass1/tumor_pass1_exacto_rna_clusters_variants_passed.tsv \
    --reference-gene-annotation-file gencode.gtf.gz \
    --reference-gene-annotation-source gencode \
    --reference-gene-annotation-assembly hg38 \
    --reference-gene-annotation-version v45 \
    --output-dir pass1/ \
    --output-prefix tumor_pass1

Description

Error-correct RNA reads against the cluster each was assigned to.

At a glance

Inputs: *.bam (the same alignment cluster-rna-reads ran on; reads are recovered from their primary records in their original orientation, with their base qualities, or Q60 when the BAM has none), the four pass-1 cluster TSVs (clusters, reference transcripts, splice junctions, variants passed), *.gtf.gz (gene annotation)

Outputs: {prefix}_exacto_rna_corrected_reads.fastq.gz (BGZF, one record per clustered read in cluster order, read names preserved; reads in no cluster are not written). It is written as {prefix}_exacto_rna_corrected_reads.fastq.gz.partial and renamed when complete, and nothing is written when a clustered read is missing from the BAM

Typical next step: Realign the corrected FASTQ with minimap2 (--cs is required), then re-run cluster-rna-reads with --preset corrected and a distinct --output-prefix

Required arguments

Flag	Type	Description
`--bam-file`	`str`	Input BAM file. Must be the same alignment exacto cluster-rna-reads was run on. Reads are recovered from their primary records in their original orientation, with their base quality scores.
`--clusters-tsv-file`	`str`	Clusters TSV file (an output of exacto cluster-rna-reads). Expected columns: ‘cluster_id’, ‘read_name’.
`--cluster-reference-transcripts-tsv-file`	`str`	Cluster reference transcripts TSV file (an output of exacto cluster-rna-reads).
`--cluster-splice-junctions-tsv-file`	`str`	Cluster splice junctions TSV file (an output of exacto cluster-rna-reads).
`--cluster-variants-tsv-file`	`str`	Cluster variants TSV file (an output of exacto cluster-rna-reads). Each read is rewritten to the reference plus its cluster’s called alleles: a base, insertion or deletion that disagrees with them is corrected, and at a called variant the read takes the called allele, so this file is what separates real variation from sequencing error.
`--reference-gene-annotation-file`	`str`	Reference gene annotation file.
`--output-dir`	`str`	Output directory.
`--output-prefix`	`str`	Output prefix.

Optional arguments

Flag	Type	Default	Description
`--max-correctable-event-len`	`int`	`50`	Maximum length of an uncalled insertion or deletion that correction will rewrite; longer ones are left as sequenced. Called alleles are written at any length, and terminal soft clips are kept unless their cluster called them as an insertion.
`--corrected-base-quality`	`int`	`60`	Base quality assigned to a corrected base.
`--trim-transcript-ends`	`flag`	`False`	Cut a read end that runs past an annotated exon into the intron back to the exon, when that exon is not the first or last exon of the reference transcripts that carry the read’s terminal splice junction. A called variant in the removed span keeps the end. Such an end is also what cluster-rna-reads counts as a retained intron, so trimming removes retained introns from the corrected reads. Requires –reference-gene-annotation-file.
`--reference-gene-annotation-source`	`str`	`gencode`	Reference gene annotation source.
`--reference-gene-annotation-assembly`	`str`		Reference gene annotation assembly (e.g. ‘hg38’).
`--reference-gene-annotation-version`	`str`		Reference gene annotation version (e.g. ‘v41’).
`--num-threads`	`int`	`4`	Number of threads.
`--chunk-size`	`int`	`10000`	Number of reads corrected per chunk; a cluster is never split across chunks.