Goals

1) Make the Sage coexpression software runnable by any data analyst in R.

Document the analysis steps, package functions, and adjustable parameters.  Write start-to-finish vignette(s) having sufficient detail to guide a new analyst through the software, including making parameter settings and other intermediate decisions.  Refactoring software to enhance readability and/or to make decision points and adjustable parameters explicit, is within scope for this goal.

2) Clearly explain the methodology underlying the coexpression algorithms.

This includes contrasting the Sage algorithms with the separately published “WGCNA” algorithms and explaining the rationale for the differences and the decision process for choosing which to use.

3) Make the Sage coexpression software publicly available.

The code must be available through a standard R distribution channel (CRAN or Bioconductor).  An option is to merge Sage-specific algorithms or steps into WGCNA (if the two are sufficiently overlapping).

4) Make the Sage coexpression software perform well, on commonly available hardware.

Currently, special high capacity hardware is required to run the Sage coexpression software on commonly encountered data set sizes.  The goal is to optimize the code to run on commonly available hardware, at a minimum the code should be runnable on the 68GB, quad core servers available through Amazon Web Services. Ideally, the code would be runnable on a “heavy” Sage laptop (8 GB total RAM).

Strategy

The steps for Sage Coexpression are: 

1. Compute correlation coefficient matrix.
2. Determine optimal value for the scale free exponent, beta, and collect regression statistics.
3. Compute the topological overlap matrix (TOM).
4. Perform hierarchical clustering of genes, based on TOM.
5. Detect and label modules in TOM, using "Dynamic Tree Cutting".
6. Merge modules based on hierarchical clustering of representative genes.
7. Cluster samples hierarchically.
8. Compute intra/inter-module network statistics, per gene.
9. Produce diagnostic plots (dendrograms, heat maps, statistical scatter plots).
10. Produce tabular output of module membership, network statistics, and scale-free regression statistics.

Elsewhere http://sagebionetworks.jira.com/wiki/display/SCICOMP/Coexpression+Evaluation we have shown that for realistic dataset sizes, the vast majority of time is spent in steps 1 and 3, and that steps 1, 3, and 4 are identical in the Sage and UCLA-WGCNA code bases, while the UCLA-WGCNA code uses compiled/optimized software for these three steps.  Further, we have seen that steps 2 and 5 (with the right parameter choices in the UCLA package) produce extremely similar results.  (Note, the observed similarity is no surprise, since the two code bases represent forks from an original set of algorithms, which have evolved separately for appx. 6 years.)

Our strategy, therefore, is:

• leverage the UCLA-WGCNA package for the "common" steps, 1->5, gaining significant performance
• provide the user a parameter choice at step 5, to do "tree cutting" in the manner of the Sage algorithm, or in that of the UCLA-WGCNA algorithm
• provide two algorithms for step 6 (module merging), allowing a user to choose the Sage or UCLA-WGCNA algorithm
• leverage the UCLA-WGCNA dendrogram/module plotting algorithm in step 9
• maintain the Sage algorithms for the Sage-specific post-processing, i.e. step 7, step 8, the heat maps in step 9.

External dependencies

WGCNA::cor  -- the compiled/accelerated Pearson correlation computation

WGCNA::pickSoftThreshold -- optimal choice of scale free exponent

WGCNA::Tomdist -- the compiled/accelerated TOM computation

flashClust::flashClust -- the compiled/accelerated hierarchical clustering computation

WGCNA::scaleFreePlot -- scatter plot of network connectivity, with regression line

dynamicTreeCut::cutreeDynamic -- tree cutting / module determination

WGCNA::plotDendroAndColors -- graphic function to plot dendrogram with colored modules aligned underneath

Sage software dependencies

module merging, by analyzing most-highly-connected genes in each module

fixed-cluster-number tree cutting for sample module definition

computation of within- and between- module per-gene connectivity statistics

heatmap generation for correlation and TOM matrices

The Package

The source code for the created package is available on our Atlassian-hosted SVN repository, under the SCICOMP project:

http://sagebionetworks.jira.com/source/browse/SCICOMP/trunk/Coexpression/SageBionetworksCoex

Package functions

The main 'points of entry' into the package are:

performCoexFromFiles - run the entire package using a file of gene expression data as input

performCoexpressionAnalysis - run the analysis portion of Coexpression, taking a data frame as input

clusterGenes - run the rote, time consuming portion of Coexpression, taking a data frame as input

modulesFromGeneTree - choose modules from a gene dendrogram, taking the output of 'clusterGenes' as input

clusterSamples, intraModularStatistics - analysis steps auxiliary to module determination

createDiagnosticPlots - create dendrogram, heatmap plots, etc., from the results of the coexpression analysis

Package features

Comparison to Sage code base

Correlation computation is faster, with identical results.
TOM computation is faster, with identical results.
Hierarchical clustering is faster, with identical results.
Scale-free exponent (beta) determination is similar, with very similar results and regression statistics.
"Dynamic tree cutting" algorithm is the same, with very similar results.
Diagnostic plot set is reduced from 12 to 8, omitting redundant plots.

Additional Features

Option to do tree cutting and/or subsqeuent merging by UCLA-WGCNA algorithm or by 'Sage classic' algorithm.
Separation of rote, time consuming steps (correlation, TOM computation) from tree cutting.
Separation of analysis from plotting.
Separation of analysis from file system, to facilitate Synpase integration.

Evaluation

* Force beta in Package to match beta in Sage code.

Note: We skip the performance evaluation for the small data sets.

The details of the differences summarized in the table can be found here: http://sagebionetworks.jira.com/wiki/display/SCICOMP/Package+Comparison+Details

Goals, Revisited