TITLE: Creating Differential Transcript Expression Results with DESeq2
AUTHORS: David A Eccles

[DESCRIPTION]
Differential expression analysis of transcript count tables using DESeq2

[BEFORE_START]
You should have gene-annotated transcript count tables for multiple sequencing libraries, renamed to match the form of "<library_identifier>_wide_transcript_counts_<mapper>.csv". See here for how to create these tables from nanopore cDNA transcripts.

You should also have a sample metadata file that matches library/barcode pairs to experimental conditions, with at least "SampleID" and "Label" fields. The SampleID field should be of the form "<library_identifier>.BCXX"; this will be replaced by the "Label" field when results are output to a file.

[GUIDELINES]
Note: this is a demonstrative experimental protocol for a specific differential expression analysis; variables, file names and some other code will need to be changed for your own circumstances

[STEPS]
SECTION: Collating count data
1. Combine the transcript count data into a single data structure. To reduce confusion when this protocol is run multiple times, we declare an analysisDate variable to be used for output file names:


 
We also load libraries that will be used in the protocol:


 

SECTION: Collating count data
1.1. Collect a list of the count data files:

 

CHECK - print out the file names to make sure they're correct:


 


SECTION: Collating count data
1.2. Set up the skeleton structures for creating the combined table. This is created in two parts:
A gene lookup table, containing gene metadata
A count table, containing transcript counts


 


SECTION: Collating count data
1.3. The skeleton structures are then populated with the data from individual library files:

 
CHECK - make sure that the column headings of the aggregated count table match the expected names:

 

SECTION: Collating count data
2. Do some cleaning / reordering of the data, then create an intermediate aggregate count table
SECTION: Collating count data
2.1. The sample metadata file (see Guidelines & Warnings) is read in, mostly as factors; the sample ID is converted to a character vector:
 

Metadata rows are subset and to match IDs present in the count table, and underscores are replaced with dots in the sample IDs:
 

SECTION: Collating count data
2.2. Count table rows are subset and re-ordered to match the order of the metadata table, and counts are combined with gene annotation:
 

SECTION: Collating count data
2.4. The combined table is sorted based on total expression across all samples and output to an intermediate file, using the analysis date as a file name:

 

SECTION: Differential Expression
3. Note: What follows from here will be more case-specific. The steps outlined here represent one method of carrying out a differential expression analysis with a relatively simple statistical model. For further ideas for how to carry out a differential expression analysis, see the DESeq2 Workflow.

Set up variables to change output file names and behaviour:

Note: the countDate is not "today" because different explorations of differential expression could be done on the same count data.

 

Read in the intermediate aggregated count file and the metadata file:

 

SECTION: Differential Expression
4. Carry out metadata filtering (i.e. sample exclusion) and count filtering (e.g. gene / sample QC)

SECTION: Differential Expression
4.1. Filter the metadata table to only include the desired samples:

Note: this step will be situation specific

 

SECTION: Differential Expression
4.2. Filter the metadata file to match the count table (i.e. removing any samples filtered out in previous steps), and exclude any columns that have single values. Count tables are finally arranged as in the metadata table:
 


CHECK - make sure the SampleIDs in the column names match the exact order of the metadata table:

 

SECTION: Differential Expression
5. Create DESeq2 data structure, and run a differential expression analysis

SECTION: Differential Expression
5.1. Identify factors for the statistical model from the metadata file:

 

SECTION: Differential Expression
5.2. Create the transcript count matrix:

 

SECTION: Differential Expression
5.3. Convert to DESeq2 structure and run DESeq2:

 

CHECK - make sure dispersion and result names look reasonable:

Note: The result names will not indicate every possible comparison; just a subset from which all comparisons can be derived from.

 

 

SECTION: Result Collation
6. Prepare results table skeletons for DESeq2 results 
SECTION: Result Collation
6.1. Collect up comparisons to make:

 

SECTION: Result Collation
6.3. Create variance-stabilised [log2] count matrix from DESeq2 structure:

 

Rescale VST values to have the same 99th percentile, but a minimum value of zero. This makes the scaled counts resemble more closely the actual read counts:

 

Replace column names in the VST matrix with labels from the metadata:

Note: the substution removes any initial whitespace from the label

 

SECTION: Result Collation
6.4. Generate base count table:

 

Tack on VST matrix:

 

Pre-populate wth minimum p-value column:

 

SECTION: Result Collation
7. Fetch DESeq2 results for each comparison from the DESeq2 data structure and add to the base table:

 

SECTION: Result Collation
8. Write results out to a CSV file:

 

SECTION: Excel Worksheet Output
9. Separate results and put into an Excel file

Note: this step will be situation specific
SECTION: Excel Worksheet Output
9.1. Split out mitochondrial genes:

 

SECTION: Excel Worksheet Output
9.2. Write split datasets out to the Excel file:

 

SECTION: Excel Worksheet Output
9.3. Add worksheets for differentially-expressed pairs:

 

SECTION: Collating count data
2.3. Filters are applied to make sure that only reliably-expressed genes are included:


 

SECTION: Result Collation
6.2. Remove any unwanted comparisons for results output: