Module 3: Learn Regulatory Topics And Visualize Differential GRNs

Overview (Module 3)

---

Input:

• Per-condition TF->TFBS->target link summary matrices from Module 2
• A metadata table specifying pairwise comparisons to compute (example)
• A TF motif cluster assignment table from Module 1

Process:

1. Compute differential links with the find_differential_links() function. A link is flagged as up if both the target-gene-expression log2 fold change and the footprint-score delta between the two contrasting conditions are positive and exceed their respective cutoffs specified in *.yaml file. A link is flagged as down if both values are negative and pass the same cutoffs. Links in which TF expression changes significantly in the opposite direction of the target gene are removed.

2. Construct joint RNA+footprint doc_term documents and train joint topic models using the train_topic_models() function.

   2.1. Build documents (typically comparison × TF-cluster × direction).

   • Define terms as GENE:<symbol> (RNA) and PEAK:<chr:start-end> (TFBS).
   • Compute continuous weights from effect sizes (RNA: log2 fold change; TFBS: delta score), then aggregate weights per document and per term.
   • Within each document, rescale RNA and footprint weights by the minimum of the two modality-wise summed weights to prevent one modality from dominating.
   • Convert continuous weights into pseudocounts for topic modeling.

   2.2. Train joint RNA+footprint topic models.

   • Split pseudocounts into gene and peak feature vectors.
   • Encode genes and peaks into seperate 128-dim Rectified Linear Unit (ReLU) layers.
   • Concatenate to 256-dim and fuse with an Multilayer Perceptron (MLP) (256 → 128 → 128).
   • Train a Variational Autoencoder (VAE)** to learn topic mixtures per document and a topic–term matrix for each user-defined K.
   • Output model selection metrics plots (e.g. perplexity and second-derivative curves) across the full user-defined K series (example).

3. Extract topics with the extract_regulatory_topics() function, which computes link→topic probabilities and applies optimized cutoffs (example) to assign links to topics for a user-selected k.

4. Visualize differential GRNs by Topics/Comparisions with the build_per_comparison_per_topic_differential_grns() function. Options to output in interactive HTML or static PDF format.

Output:

• A directory containing differential link tables and corresponding interactive scatter plots per comparison, and a static PDF containing all scatter plots from all comparisons.
• A directory containing per-comparison master TF summary tables and corresponding summary plots of aggregated regulatory changes and connectivities of all active TFs.
• A directory containing per-comparison summary tables of significantly enriched pathways and pathway-stratified GRN visualizations (interactive HTML files or static PDFs).
• A directory containing a combined doc_term.csv(example), VAE topic model outputs, and model selection metrics across all user-defined Ks.
• A directory containing topic-term and topic-link probability and assignment matrices, overall topic-wise TF/pathway enrichment summaries and QC plots, and subdirectories containing comparison-specific TF/pathway enrichment summaries by topics (if enabled).
• A directory containing topic-stratified GRN visualizations for each comparison (interactive HTML files or static PDFs).

---

Quick start (Module 3)

# Compare and extract differential TF->FP->target links
find_differential_links(
  config = "episcope_grn.yaml",
  compar = "episcope_comparisons.csv", 
  output_dir = "differential_links",
  qc = TRUE
)

# Train topic models & output model metrics across the K grid
train_topic_models(
   Kgrid = c(2:10, 15, 20, 25, 30),
   input_dir = "differential_links",
   output_dir = "topic_models"
)

# Assign links to topics based on link-topic probabilities and user-selected K
extract_regulatory_topics(
   k = 10, # selected by user based on model selection metrics (e.g., perplexity / derivative knee)
   link_dir = "differential_links",
   model_dir = "topic_models",
   output_dir = "final_topics",
   qc = TRUE
)

# Condition/Topic-level visualizations
build_per_comparison_per_topic_differential_grns(
   link_dir = "differential_links",
   topic_dir = "final_topics",
   output_dir = "topic_visualizations",
   output_style = "html" # or "pdf"
)

---