comparison stringtie.xml @ 15:dd4df992d93d draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/stringtie commit a834a41c94d184df80e45ffa2339723826a075b1

14:eafd5dc95228

<tool id="stringtie" name="StringTie" version="1.3.3.2">
    <description>transcript assembly and quantification</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />

        #end if

        ## Replace commas with tabs
        &&
        sed -i.bak -e "s/,/\${TAB}/g" -e "s/\${CR}//g" gene_counts.csv transcript_counts.csv
        #if $guide.special_outputs.keep_header:
            &&
            head -n 1 gene_counts.csv | sed -e 's/sample1/$escaped_element_identifier/' > '$gene_counts'
            &&
            head -n 1 transcript_counts.csv | sed -e 's/sample1/$escaped_element_identifier/' > '$transcript_counts'
        #end if
        ## Sort count files on the first column
        &&
        tail -n +2 gene_counts.csv | sort -t"\${TAB}" -k1,1 >> '$gene_counts'
        &&
        tail -n +2 transcript_counts.csv | sort -t"\${TAB}" -k1,1 >> '$transcript_counts'

                </conditional>
                <param name="input_estimation" argument="-e" type="boolean" truevalue="-e" falsevalue="" checked="False" label="Use Reference transcripts only?" help="Limit the processing of read alignments to only estimate and output the assembled transcripts matching the reference transcripts given with the -G option. With this option, read bundles with no reference transcripts (novel transcripts) will be entirely skipped, which may provide a considerable speed boost when the given set of reference transcripts is limited to a set of target genes, for example. Default: No"/>
                <conditional name="special_outputs">
                    <param name="special_outputs_select" type="select" label="Output files for differential expression?" help="Select to output additional files that can be used with Ballgown or DESeq2/edgeR. See Help section below for more information">
                        <option value="ballgown">Ballgown</option>
                        <option value="deseq2">DESeq2/edgeR</option>
                        <option value="no" selected="True">No additional output</option>
                    </param>
                    <when value="ballgown" />
                    <when value="deseq2">
                        <param name="read_length" argument="--length" type="integer" min="0" value="75" label="Specify the average read length" help="Default: 75" />

                        <param argument="--key" type="text" label="Prefix for clustering" help="If clustering, what prefix to use for geneIDs assigned by this script. Only letters and numbers will be retained in this field. Default: prepG">
                            <sanitizer>
                                <valid initial="string.letters,string.digits"></valid>
                            </sanitizer>
                        </param>
                        <param name="keep_header" type="boolean" checked="true" label="Output header line?" help="Keep the header line for edgeR, remove it for DESeq2" />
                    </when>
                    <when value="no" />
                </conditional>
                <param name="coverage_file" argument="-C" type="boolean" truevalue="-C" falsevalue="" checked="False" label="Output coverage file?" help="If StringTie is run with this option (requires -G), it returns a file with all the transcripts in the reference annotation that are fully covered, end to end, by reads. The output format is a GTF file as described below. Each line of the GTF is corresponds to a gene or transcript in the reference annotation. Default: No"/>
            </when>

    </outputs>
    <tests>
         <!--Ensure default GTF output works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <output name="output_gtf" file="stringtie_out1.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure fraction option works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="fraction" value="0.17" />
            <output name="output_gtf" file="stringtie_out2.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure guide option works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <output name="output_gtf" file="stringtie_out3.gtf" ftype="gtf" lines_diff="2"  />
        </test>
        <!--Ensure guide with fraction works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.17" />
            <output name="output_gtf" file="stringtie_out4.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure coverage and output for Ballgown works -->
        <test expect_num_outputs="7">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />

            <output name="exon_expression" file="./ballgown/e_data.ctab" ftype="tabular" />
            <output name="intron_expression" file="./ballgown/i_data.ctab" ftype="tabular" />
            <output name="transcript_expression" file="./ballgown/t_data.ctab" ftype="tabular" />
            <output name="exon_transcript_mapping" file="./ballgown/e2t.ctab" ftype="tabular" />
            <output name="intron_transcript_mapping" file="./ballgown/i2t.ctab" ftype="tabular" />
            <output name="output_gtf" file="stringtie_out5.gtf" ftype="gtf" lines_diff="2" />
            <output name="coverage" file="stringtie_out_coverage.gtf" ftype="gtf" />
        </test>
        <!--Ensure output for edgeR works -->
        <test expect_num_outputs="5">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />

            <param name="coverage_file" value="True" />
            <param name="clustering" value="True" />
            <output name="gene_counts" file="gene_counts_edger.tsv" ftype="tabular" />
            <output name="transcript_counts" file="transcript_counts_edger.tsv" ftype="tabular" />
            <output name="legend" file="legend.tsv" ftype="tabular" />
            <output name="output_gtf" file="stringtie_out6.gtf" ftype="gtf" lines_diff="2" />
            <output name="coverage" file="stringtie_out_coverage.gtf" ftype="gtf" />
        </test>
        <!--Ensure output for DESeq2 works -->
        <test expect_num_outputs="5">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="special_outputs_select" value="deseq2" />
            <param name="keep_header" value="False" />
            <param name="input_estimation" value="True" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="coverage_file" value="True" />
            <param name="clustering" value="True" />
            <output name="gene_counts" file="gene_counts_deseq2.tsv" ftype="tabular" />
            <output name="transcript_counts" file="transcript_counts_deseq2.tsv" ftype="tabular" />
            <output name="legend" file="legend.tsv" ftype="tabular" />
            <output name="output_gtf" file="stringtie_out6.gtf" ftype="gtf" lines_diff="2" />
            <output name="coverage" file="stringtie_out_coverage.gtf" ftype="gtf" />
        </test>
        <!--Ensure gene abundances output works -->
        <test expect_num_outputs="2">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.17" />
            <param name="abundance_estimation" value="True" />
            <output name="output_gtf" file="stringtie_out4.gtf" ftype="gtf" lines_diff="2" />
            <output name="gene_abundance_estimation" file="stringtie_out7.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure another fraction value works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.15" />
            <output name="output_gtf" file="stringtie_out8.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure built-in GTFs work -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" dbkey="hg38" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="cached" />
            <param name="fraction" value="0.15" />
            <output name="output_gtf" file="stringtie_out8.gtf" ftype="gtf" lines_diff="2" />
        </test>
    </tests>
    <help><![CDATA[

.. class:: infomark

**What it does**

StringTie_ is a fast and highly efficient assembler of RNA-Seq alignments into potential transcripts. It uses a novel network flow algorithm as well as an optional *de novo* assembly step to assemble and quantitate full-length transcripts representing multiple splice variants for each gene locus. Its input can include not only the alignments of raw reads used by other transcript assemblers, but also alignments of longer sequences that have been assembled from those reads. In order to identify differentially expressed genes between experiments, StringTie's output can be processed by specialized software like Ballgown_, Cuffdiff_ or other programs (DESeq2_, edgeR_, etc.).

-----

**Inputs**

    * a TSV (tab-delimited) file of **Gene abundances**

If a reference GTF/GFF3 file is used as a guide, StringTie can also output:

    * a GTF file containing all **fully-covered reference transcripts** in the provided reference file that are covered end-to-end by reads
    * Files (tables) for **Ballgown** and/or **DESeq2/edgeR**, which can use them to estimate differential expression


**StringTie's primary GTF output**

The primary output of StringTie is a Gene Transfer Format (GTF) file that contains details of the transcripts that StringTie assembles from RNA-Seq data. GTF is an extension of GFF (Gene Finding Format, also called General Feature Format), and is very similar to GFF2 and GFF3. The field definitions for the 9 columns of GTF output can be found at the `Ensembl site here`_. The following is an example of a transcript assembled by StringTie as shown in a GTF file:

If StringTie is run with the use reference guide option (-G), it will also return a file with all the transcripts in the reference annotation that are fully covered, end to end, by reads. The output format is a GTF file as described above. Each line of the GTF is corresponds to a gene or transcript in the reference annotation.

**Ballgown Input Table Files**

An option to output files for Ballgown can be selected under **Output additional files** above. If selected, StringTie will return Ballgown input table files containing coverage data for the reference transcripts given with the -G option. These tables have these specific names: (1) e2t.ctab, (2) e_data.ctab, (3) i2t.ctab, (4) i_data.ctab, and (5) t_data.ctab. A detailed description of each of these five required inputs to Ballgown can be found at `this link`. With this option StringTie can be used as a direct replacement of the tablemaker program included with the Ballgown distribution.


**DESeq2/edgeR Input Table Files**

DESeq2_ and edgeR_ are two popular Bioconductor_ packages for analyzing differential expression, which take as input a matrix of read counts mapped to particular genomic features (e.g., genes). This read count information can be extracted directly from the files generated by StringTie (run with the -e parameter) by selecting DESeq2/edgeR under **Output additional files** above. This uses the StringTie helper script ``prepDE.py`` to convert the GTF output from StringTie into two tab-delimited (TSV) files, containing the count matrices for genes and transcripts, using the coverage values found in the output of StringTie -e.

-----

**More Information**

*Evaluating transcript assemblies:*
A simple way of getting more information about the transcripts assembled by StringTie (summary of gene and transcript counts, novel vs. known etc.), or even performing basic tracking of assembled isoforms across multiple RNA-Seq experiments, is to use the **gffcompare** program. Basic usage information for this program can be found on the `GFF utilities page`_.

*Differential expression analysis:*

Together with HISAT and Ballgown (or DESeq2/edgeR), StringTie can be used for estimating differential expression across multiple RNA-Seq samples and generating plots and differential expression tables as described in our `protocol paper`_ and shown in a diagram in the `StringTie manual here`_.

Our recommended workflow includes the following steps:

 1. For each RNA-Seq sample, map the reads to the genome with HISAT2 using the --dta option. It is highly recommended to use the reference annotation information when mapping the reads, which can be either embedded in the genome index (built with the --ss and --exon options, see HISAT2 manual), or provided separately at run time (using the --known-splicesite-infile option of HISAT2). The SAM output of each HISAT2 run must be sorted and converted to BAM using samtools as explained above.

 2. For each RNA-Seq sample, use this StringTie tool to assemble the read alignments obtained in the previous step; it is recommended to run StringTie with the -G option if the reference annotation is available.

 3. Run the separate **StringTie merge** tool in order to generate a non-redundant set of transcripts observed in all the RNA-Seq samples assembled previously. ``StringTie merge`` takes as input a list of all the assembled transcripts files (in GTF format) previously obtained for each sample, as well as a reference annotation file (-G option) if available.

 4. For each RNA-Seq sample, run this StringTie tool selecting to output files for Ballgown (or DESeq2/edgeR), which will generate tables of transcript and gene estimated abundances (count files). The option -e (*Use Reference transcripts only*) is not required but is recommended for this run in order to produce more accurate abundance estimations of the input transcripts. Each StringTie run in this step will take as input the sorted read alignments (BAM file) obtained in step 1 for the corresponding sample and the -G option with the merged transcripts (GTF file) generated by ``stringtie merge`` in step 3. Please note that this is the only case where the -G option is not used with a reference annotation, but with the global, merged set of transcripts as observed across all samples. (This step is the equivalent of the *Tablemaker* step described in the original Ballgown pipeline.)

 5. Ballgown (or DESeq2/edgeR) can now be used to load the coverage tables generated in the previous step and perform various statistical analyses for differential expression, generate plots etc.

An alternate, faster differential expression analysis workflow can be pursued if there is no interest in novel isoforms (i.e. assembled transcripts present in the samples but missing from the reference annotation), or if only a well known set of transcripts of interest are targeted by the analysis. This simplified protocol has only 3 steps (depicted in the `StringTie manual here`_) as it bypasses the individual assembly of each RNA-Seq sample and the "transcript merge" step. This simplified workflow attempts to directly estimate and analyze the expression of a known set of transcripts as given in the reference annotation file.

.. _StringTie: http://ccb.jhu.edu/software/stringtie/
.. _Ballgown: https://www.biorxiv.org/content/early/2014/09/05/003665
.. _Cuffdiff: http://cole-trapnell-lab.github.io/cufflinks/cuffdiff/
.. _DESeq2: https://bioconductor.org/packages/release/bioc/html/DESeq2.html
.. _edgeR: https://bioconductor.org/packages/release/bioc/html/edgeR.html
.. _Bioconductor: https://www.bioconductor.org/
.. _SAM: http://samtools.github.io/hts-specs/SAMv1.pdf
.. _HISAT2: http://ccb.jhu.edu/software/hisat2
.. _`GTF/GFF3`: https://ccb.jhu.edu/software/stringtie/gff.shtml
.. _`this link`: https://github.com/alyssafrazee/ballgown#ballgown-readable-expression-output

15:dd4df992d93d

<tool id="stringtie" name="StringTie" version="@TOOL_VERSION@">
    <description>transcript assembly and quantification</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />

        #end if

        ## Replace commas with tabs
        &&
        sed -i.bak -e "s/,/\${TAB}/g" -e "s/\${CR}//g" gene_counts.csv transcript_counts.csv
        ## Output header
        &&
        head -n 1 gene_counts.csv | sed -e 's/sample1/$escaped_element_identifier/' > '$gene_counts'
        &&
        head -n 1 transcript_counts.csv | sed -e 's/sample1/$escaped_element_identifier/' > '$transcript_counts'
        ## Sort count files on the first column
        &&
        tail -n +2 gene_counts.csv | sort -t"\${TAB}" -k1,1 >> '$gene_counts'
        &&
        tail -n +2 transcript_counts.csv | sort -t"\${TAB}" -k1,1 >> '$transcript_counts'

                </conditional>
                <param name="input_estimation" argument="-e" type="boolean" truevalue="-e" falsevalue="" checked="False" label="Use Reference transcripts only?" help="Limit the processing of read alignments to only estimate and output the assembled transcripts matching the reference transcripts given with the -G option. With this option, read bundles with no reference transcripts (novel transcripts) will be entirely skipped, which may provide a considerable speed boost when the given set of reference transcripts is limited to a set of target genes, for example. Default: No"/>
                <conditional name="special_outputs">
                    <param name="special_outputs_select" type="select" label="Output files for differential expression?" help="Select to output additional files that can be used with Ballgown or DESeq2/edgeR. See Help section below for more information">
                        <option value="ballgown">Ballgown</option>
                        <option value="deseq2">DESeq2/edgeR/limma-voom</option>
                        <option value="no" selected="True">No additional output</option>
                    </param>
                    <when value="ballgown" />
                    <when value="deseq2">
                        <param name="read_length" argument="--length" type="integer" min="0" value="75" label="Specify the average read length" help="Default: 75" />

                        <param argument="--key" type="text" label="Prefix for clustering" help="If clustering, what prefix to use for geneIDs assigned by this script. Only letters and numbers will be retained in this field. Default: prepG">
                            <sanitizer>
                                <valid initial="string.letters,string.digits"></valid>
                            </sanitizer>
                        </param>
                    </when>
                    <when value="no" />
                </conditional>
                <param name="coverage_file" argument="-C" type="boolean" truevalue="-C" falsevalue="" checked="False" label="Output coverage file?" help="If StringTie is run with this option (requires -G), it returns a file with all the transcripts in the reference annotation that are fully covered, end to end, by reads. The output format is a GTF file as described below. Each line of the GTF is corresponds to a gene or transcript in the reference annotation. Default: No"/>
            </when>

    </outputs>
    <tests>
         <!--Ensure default GTF output works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <output name="output_gtf" file="stringtie_out1.gtf" ftype="gtf" lines_diff="4" />
        </test>
        <!--Ensure fraction option works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="fraction" value="0.17" />
            <output name="output_gtf" file="stringtie_out2.gtf" ftype="gtf" lines_diff="4" />
        </test>
        <!--Ensure guide option works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <output name="output_gtf" file="stringtie_out3.gtf" ftype="gtf" lines_diff="4"  />
        </test>
        <!--Ensure guide with fraction works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.17" />
            <output name="output_gtf" file="stringtie_out4.gtf" ftype="gtf" lines_diff="4" />
        </test>
        <!--Ensure coverage and output for Ballgown works -->
        <test expect_num_outputs="7">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />

            <output name="exon_expression" file="./ballgown/e_data.ctab" ftype="tabular" />
            <output name="intron_expression" file="./ballgown/i_data.ctab" ftype="tabular" />
            <output name="transcript_expression" file="./ballgown/t_data.ctab" ftype="tabular" />
            <output name="exon_transcript_mapping" file="./ballgown/e2t.ctab" ftype="tabular" />
            <output name="intron_transcript_mapping" file="./ballgown/i2t.ctab" ftype="tabular" />
            <output name="output_gtf" file="stringtie_out5.gtf" ftype="gtf" lines_diff="4" />
            <output name="coverage" file="stringtie_out_coverage.gtf" ftype="gtf" />
        </test>
        <!--Ensure output for edgeR works -->
        <test expect_num_outputs="5">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />

            <param name="coverage_file" value="True" />
            <param name="clustering" value="True" />
            <output name="gene_counts" file="gene_counts_edger.tsv" ftype="tabular" />
            <output name="transcript_counts" file="transcript_counts_edger.tsv" ftype="tabular" />
            <output name="legend" file="legend.tsv" ftype="tabular" />
            <output name="output_gtf" file="stringtie_out6.gtf" ftype="gtf" lines_diff="4" />
            <output name="coverage" file="stringtie_out_coverage.gtf" ftype="gtf" />
        </test>
        <!--Ensure gene abundances output works -->
        <test expect_num_outputs="2">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.17" />
            <param name="abundance_estimation" value="True" />
            <output name="output_gtf" file="stringtie_out4.gtf" ftype="gtf" lines_diff="4" />
            <output name="gene_abundance_estimation" file="stringtie_out7.gtf" ftype="gtf" lines_diff="2" />
        </test>
        <!--Ensure another fraction value works -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="history" />
            <param name="ref_hist" ftype="gtf" value="stringtie_in.gtf" />
            <param name="fraction" value="0.15" />
            <output name="output_gtf" file="stringtie_out8.gtf" ftype="gtf" lines_diff="4" />
        </test>
        <!--Ensure built-in GTFs work -->
        <test expect_num_outputs="1">
            <param name="input_bam" ftype="bam" dbkey="hg38" value="stringtie_in1.bam" />
            <param name="use_guide" value="yes" />
            <param name="guide_gff_select" value="cached" />
            <param name="fraction" value="0.15" />
            <output name="output_gtf" file="stringtie_out8.gtf" ftype="gtf" lines_diff="4" />
        </test>
    </tests>
    <help><![CDATA[

.. class:: infomark

**What it does**

StringTie_ is a fast and highly efficient assembler of RNA-Seq alignments into potential transcripts. It uses a novel network flow algorithm as well as an optional *de novo* assembly step to assemble and quantitate full-length transcripts representing multiple splice variants for each gene locus. Its input can include not only the alignments of raw reads used by other transcript assemblers, but also alignments of longer sequences that have been assembled from those reads. In order to identify differentially expressed genes between experiments, StringTie's output can be processed by specialized software like Ballgown_, Cuffdiff_ or other programs (DESeq2_, edgeR_, limma_ etc.).

-----

**Inputs**

    * a TSV (tab-delimited) file of **Gene abundances**

If a reference GTF/GFF3 file is used as a guide, StringTie can also output:

    * a GTF file containing all **fully-covered reference transcripts** in the provided reference file that are covered end-to-end by reads
    * Files (tables) for **Ballgown** and/or **DESeq2/edgeR/limma-voom**, which can use them to estimate differential expression


**StringTie's primary GTF output**

The primary output of StringTie is a Gene Transfer Format (GTF) file that contains details of the transcripts that StringTie assembles from RNA-Seq data. GTF is an extension of GFF (Gene Finding Format, also called General Feature Format), and is very similar to GFF2 and GFF3. The field definitions for the 9 columns of GTF output can be found at the `Ensembl site here`_. The following is an example of a transcript assembled by StringTie as shown in a GTF file:

If StringTie is run with the use reference guide option (-G), it will also return a file with all the transcripts in the reference annotation that are fully covered, end to end, by reads. The output format is a GTF file as described above. Each line of the GTF is corresponds to a gene or transcript in the reference annotation.

**Ballgown Input Table Files**

An option to output files for Ballgown can be selected under **Output files for differential expression?** above. If selected, StringTie will return Ballgown input table files containing coverage data for the reference transcripts given with the -G option. These tables have these specific names: (1) e2t.ctab, (2) e_data.ctab, (3) i2t.ctab, (4) i_data.ctab, and (5) t_data.ctab. A detailed description of each of these five required inputs to Ballgown can be found at `this link`. With this option StringTie can be used as a direct replacement of the tablemaker program included with the Ballgown distribution.


**DESeq2/edgeR/limma-voom Input Table Files**

DESeq2_, edgeR_ and limma_ are three popular Bioconductor_ packages for analyzing differential expression, which take as input a matrix of read counts mapped to particular genomic features (e.g., genes). This read count information can be extracted directly from the files generated by StringTie (run with the -e parameter) by selecting DESeq2/edgeR/limma-voom under **Output files for differential expression?** above. This uses the StringTie helper script ``prepDE.py`` to convert the GTF output from StringTie into two tab-delimited (TSV) files, containing the count matrices for genes and transcripts, using the coverage values found in the output of StringTie -e.

-----

**More Information**

*Evaluating transcript assemblies:*
A simple way of getting more information about the transcripts assembled by StringTie (summary of gene and transcript counts, novel vs. known etc.), or even performing basic tracking of assembled isoforms across multiple RNA-Seq experiments, is to use the **gffcompare** program. Basic usage information for this program can be found on the `GFF utilities page`_.

*Differential expression analysis:*

Together with HISAT and Ballgown (or DESeq2/edgeR/limma-voom), StringTie can be used for estimating differential expression across multiple RNA-Seq samples and generating plots and differential expression tables as described in our `protocol paper`_ and shown in a diagram in the `StringTie manual here`_.

Our recommended workflow includes the following steps:

 1. For each RNA-Seq sample, map the reads to the genome with HISAT2 using the --dta option. It is highly recommended to use the reference annotation information when mapping the reads, which can be either embedded in the genome index (built with the --ss and --exon options, see HISAT2 manual), or provided separately at run time (using the --known-splicesite-infile option of HISAT2). The SAM output of each HISAT2 run must be sorted and converted to BAM using samtools as explained above.

 2. For each RNA-Seq sample, use this StringTie tool to assemble the read alignments obtained in the previous step; it is recommended to run StringTie with the -G option if the reference annotation is available.

 3. Run the separate **StringTie merge** tool in order to generate a non-redundant set of transcripts observed in all the RNA-Seq samples assembled previously. ``StringTie merge`` takes as input a list of all the assembled transcripts files (in GTF format) previously obtained for each sample, as well as a reference annotation file (-G option) if available.

 4. For each RNA-Seq sample, run this StringTie tool selecting to output files for Ballgown (or DESeq2/edgeR/limma-voom), which will generate tables of transcript and gene estimated abundances (count files). The option -e (*Use Reference transcripts only*) is not required but is recommended for this run in order to produce more accurate abundance estimations of the input transcripts. Each StringTie run in this step will take as input the sorted read alignments (BAM file) obtained in step 1 for the corresponding sample and the -G option with the merged transcripts (GTF file) generated by ``stringtie merge`` in step 3. Please note that this is the only case where the -G option is not used with a reference annotation, but with the global, merged set of transcripts as observed across all samples. (This step is the equivalent of the *Tablemaker* step described in the original Ballgown pipeline.)

 5. Ballgown (or DESeq2/edgeR/limma-voom) can now be used to load the coverage tables generated in the previous step and perform various statistical analyses for differential expression, generate plots etc.

An alternate, faster differential expression analysis workflow can be pursued if there is no interest in novel isoforms (i.e. assembled transcripts present in the samples but missing from the reference annotation), or if only a well known set of transcripts of interest are targeted by the analysis. This simplified protocol has only 3 steps (depicted in the `StringTie manual here`_) as it bypasses the individual assembly of each RNA-Seq sample and the "transcript merge" step. This simplified workflow attempts to directly estimate and analyze the expression of a known set of transcripts as given in the reference annotation file.

.. _StringTie: http://ccb.jhu.edu/software/stringtie/
.. _Ballgown: https://www.biorxiv.org/content/early/2014/09/05/003665
.. _Cuffdiff: http://cole-trapnell-lab.github.io/cufflinks/cuffdiff/
.. _DESeq2: https://bioconductor.org/packages/release/bioc/html/DESeq2.html
.. _edgeR: https://bioconductor.org/packages/release/bioc/html/edgeR.html
.. _limma: https://bioconductor.org/packages/release/bioc/html/limma.html
.. _Bioconductor: https://www.bioconductor.org/
.. _SAM: http://samtools.github.io/hts-specs/SAMv1.pdf
.. _HISAT2: http://ccb.jhu.edu/software/hisat2
.. _`GTF/GFF3`: https://ccb.jhu.edu/software/stringtie/gff.shtml
.. _`this link`: https://github.com/alyssafrazee/ballgown#ballgown-readable-expression-output