Identifying Context-Specific TF Targets with CoGAPS

This repository contains the R scripts and saved analysis outputs used for the manuscript Identifying Context-Specific Transcription Factor Targets from Prior Knowledge and Gene Expression Data. It is an analysis built around CoGAPS matrix factorization and a transcription-factor-to-target probability statistic (rather than a standalone R package).

The code is organized around two end-to-end analysis scripts:

• R/SimTFDataAllTFs.R reproduces the simulated transcription factor (TF) workflow used to validate the method and test it under noisy or error-prone priors.
• R/GISTAnalysis5e7.R reproduces the gastrointestinal stromal tumor (GIST) analysis from the paper.

Repository Overview

The paper's workflow is the same in both the simulated and GIST analyses:

1. Start with an expression matrix and a prior TF-to-gene mapping.
2. Run CoGAPS to factor the data into amplitude and pattern matrices.
3. Convert the CoGAPS output into TF set statistics and gene-level probabilities.
4. Compare those probabilities to the prior TF annotations.
5. Plot the inferred patterns, gene set summaries, and overlap structure.
6. Save the derived objects and figures for downstream reporting.

The key idea in the manuscript is that CoGAPS provides a pattern space in which the prior TF target sets can be rescored, allowing for selection of genes whose expression looks contextually consistent.

Repository contents

Analysis Scripts

• R/SimTFDataAllTFs.R runs the paper's simulated data analysis. It:
  • Constructs a synthetic dataset with four TFs, simulated patterns, overlap among TF targets, and controlled noise.
  • Runs CoGAPS and computes fit statistics.
  • Runs robustness experiments where error is intenionally introduced to the TF sets.
• R/GISTAnalysis5e7.R runs the paper's real data analysis on the GIST dataset. It:
  • Loads GIST_TS_20084 and TFGSList data (originally via CoGAPS package data calls; repository-local copies are provided in the inputs directory).
  • Rebuilds a TF regulation matrix from TRANSFAC-derived annotations.
  • Runs CoGAPS with 5 patterns and computes fit statistics.
  • Derives the TF-specific gene statistics used for the manuscript figures and tables.

Shared Helpers

• R/calcPermGS.R implements the gene-level statistic used to turn CoGAPS gene set evidence into per gene TF probabilities.
• R/ReadCoGAPSResults.R reads CoGAPS output files from disk and reconstructs the A, P, M, and uncertainty matrices.
• R/PlotGSPatterns.R groups genes by p-values and plots genes' normalized expression patterns across samples, overlaying an inferred pattern summary or mean gene expression if desired.
• R/TFTargetHeatmaps.R visualizes how inferred gene probabilities compare to TF priors and, when present, simulation results.
• R/MatError.R adds errorbar plotting used in the simulation robustness analysis.

Data Included

• outputs/SimData.RData is the saved synthetic dataset.
• outputs/SimDataResults.Rda is the saved simulation analysis workspace.
• inputs/GIST_TS_20084.Rdata is the data used in the GIST workflow.
• inputs/TFGSList.RData are the TF gene set annotations used by the GIST workflow.
• outputs/GISTResults.Rda is the saved GIST analysis workspace.

The scripts also write their own results into analysis specific folders created at runtime, such as GIST5e7/ and SimDataOverlapAllTFs/.

Reproducing the Analysis

The scripts load R packages CoGAPS, ClassDiscovery, gplots, AnnotationDbi, xtable, gtools, vioplot, and Hmisc to be available. The full session information is included in outputs/SimDataResults.Rda as session.

Important

The code in this repository has been preserved as it was executed for the associated manuscript. If you intend to run the analysis, please note:

• This analysis uses CoGAPS v0.99.1. Because the package has undergone significant changes since then, modern versions are lacking functions required for this analysis.
• To bypass installing the legacy version, the included workspace data can be loaded and code chunks calling the outdated functions can be skipped (these functions include GAPS, calcCoGAPSStat, and functions that depend on them).
• The GIST_TS_20084 and TFGSList data are no longer bundled with the CoGAPS package, so they have been provided here in the inputs directory. To run the analysis script, you will need to replace the original data calls with load calls that point to the correct file paths.

Run the scripts from the repository root so their getwd()-based path construction resolves correctly:

source("R/GISTAnalysis5e7.R")
source("R/SimTFDataAllTFs.R")

The scripts are a self-contained workflow, but full reruns depend on legacy CoGAPS behavior. The scripts will:

1. Create the needed output directories.
2. Run CoGAPS with the hard-coded iteration settings (if the appropriate version of CoGAPS is available).
3. Read the generated CoGAPS result files back in (if they were created).
4. Generate the figures and summary tables.
5. Save the final .Rda workspace snapshots.

Citation

If you use this method in your work, please cite the associated manuscript:

Fertig, E. J., Favorov, A. V. & Ochs, M. F. Identifying Context-Specific Transcription Factor Targets from Prior Knowledge and Gene Expression Data. IEEE Trans Nanobioscience 12, 142–149 (2013).