Dual-Disease Transcriptomic Machine Learning Research Planner

Generates a complete dual-disease transcriptomic + ML study design from a user-provided disease pair. Always outputs four workload configurations and a recommended primary plan.

Supported Study Styles

Minimum User Input

• Two diseases or phenotypes
• If limited detail is provided, infer a reasonable default design and state all assumptions explicitly (Hard Rule 9)

Step-by-Step Execution

Step 1: Infer Study Type

Identify:

• Disease pair and biological theme (vascular, autoimmune, fibrotic, metabolic, neurodegenerative, infectious-oncologic, comorbidity)
• User goal: shared biomarkers, shared mechanisms, immune relevance, or publication strength
• Whether ML is central (hub consensus, ROC) or supportive (biological interpretation)
• Whether immune analysis is appropriate — consult Hard Rule 5 and tissue/tool decision guide below
• Resource constraints: public data only, dataset count per disease, time limit, single-gene focus

Step 2: Output Four Configurations

Always generate all four. For each describe: goal, required data, major modules, expected workload, figure set, strengths, weaknesses.

Step 3: Recommend One Primary Plan

Select the best-fit configuration and explain why, given disease pair biology, GEO data availability, time constraints, and publication ambition.

Step 4: Full Step-by-Step Workflow

For each step include: step name, purpose, input, method, key parameters/thresholds, expected output, failure points, alternative approaches.

Dataset & Preprocessing

• GEO dataset search: one discovery + one validation per disease when feasible (see references/geo_search_and_tools.md)
• Tissue-only filtering: exclude blood/CSF unless disease-appropriate; match tissue type across both diseases
• Tissue selection rule: use the tissue most proximal to disease pathology; for metabolic diseases refer to the tissue/tool decision guide
• Platform compatibility check: verify GPL IDs match or are cross-compatible before merging
• Normalization; batch-awareness without forced merging
• Disease vs control group assignment

Fault tolerance — dataset level:

• If no GEO dataset exists for one disease: state infeasibility, suggest the closest available proxy phenotype, downgrade to Lite with discovery-only design
• If only one dataset is available per disease: downgrade to Lite; clearly state validation ROC is not feasible; provide GEO search strategy for a second cohort

DEG & Shared Signature

• limma-based DEG analysis (logFC > 1–2, adj.p \x3C 0.05)
• Volcano plots, heatmaps
• Shared up/downregulated DEG intersection (Venn diagram)
• Shared-gene summary table

Fault tolerance — DEG intersection:

• If shared DEG count = 0: do not proceed with PPI/hub analysis; apply the following recovery sequence in order:
  1. Relax logFC threshold to 0.5 (report alongside original results)
  2. Extend to top 500 DEGs per disease regardless of threshold
  3. Switch to WGCNA co-expression module overlap instead of direct DEG intersection
  4. Re-evaluate whether the disease pair shares a common tissue or biological mechanism; recommend alternative pairing if not

Enrichment & Shared Mechanism

• GO enrichment (BP, MF, CC) + KEGG enrichment (clusterProfiler / DAVID)
• Pathway visualization; shared biological module summarization

PPI & Hub Prioritization

• STRING PPI construction (confidence score > 0.4)
• Cytoscape visualization; MCODE dense-cluster identification
• CytoHubba multi-algorithm ranking (≥5 algorithms required: Degree, MCC, Betweenness, Closeness, EPC)
• Hub-gene consensus logic → top 1 / top 3 / top 10 candidates

Biomarker Performance

• ROC / AUC analysis (pROC); AUC > 0.70 as minimum threshold
• Discovery-cohort ROC + validation-cohort ROC (Standard and above)
• Expression validation across cohorts

Fault tolerance — ROC:

• If AUC ≈ 0.5 in discovery cohort: do not interpret as biomarker; flag as non-informative; consider mini-signature (3–5 genes) instead of single hub gene
• If n \x3C 30 per group: explicitly flag AUC inflation risk; interpret AUC with bootstrap CI; do not generalize

Immune Infiltration (when disease-appropriate per Hard Rule 5)

• Deconvolution tool selection — consult references/tissue_and_tool_decisions.md for the correct tool by tissue type
• Immune-cell proportion comparison (disease vs control); gene–immune cell correlation (Spearman)
• Violin plots, lollipop / heatmap correlation

Single-Gene Deepening (Standard and above)

• Stratify samples by hub gene expression (high vs low quartile)
• Single-gene GSEA in both diseases; cross-disease pathway convergence interpretation

Step 5: Figure Plan

→ Full figure list and table templates: references/figure_plan_template.md

Core figures: workflow schematic (Fig 1), DEG volcanos + Venn (Fig 2), shared DEG heatmap (Fig 3), GO/KEGG enrichment (Fig 4), PPI + MCODE + hub ranking (Fig 5), ROC curves (Fig 6), immune infiltration + correlation (Fig 7), single-gene GSEA (Fig 8). Tables: dataset summary, shared DEG list, hub rankings, ROC/AUC summary.

Step 6: Validation and Robustness Plan

State what each layer proves and what it does not prove:

• Shared-expression evidence — DEG overlap + threshold reproducibility
• Hub-prioritization evidence — PPI topology + multi-algorithm consensus (association, not causation)
• Biomarker performance evidence — ROC/AUC in discovery + validation cohorts (diagnostic signal, not mechanistic proof)
• Immune support — immune landscape differences + gene–immune correlation (associative only; Hard Rule 8)
• Single-gene mechanistic support — GSEA pathway themes (hypothesis-generating only; Hard Rule 7)

Step 7: Risk Review

Always include a self-critical section addressing:

• Strongest part of the design
• Most assumption-dependent part (typically: small cohort ROC inflation; platform differences across datasets)
• Most likely false-positive source (hub ranking with few shared DEGs; AUC > 0.9 in n \x3C 50)
• Easiest part to overinterpret (immune deconvolution as causal; one hub gene as mechanistic proof)
• Most likely reviewer criticisms: small cohorts, no experimental validation, platform heterogeneity, overinterpretation of single biomarker, immune deconvolution limitations, CRC/infectious disease subtype heterogeneity
• Revision strategy if first-pass findings fail (broaden DEG threshold, alternate validation cohort, switch to mini-signature)

Step 8: Minimal Executable Version

Public data only, one discovery dataset per disease, DEG + Venn + GO/KEGG, STRING + MCODE + CytoHubba top gene, ROC in discovery cohort, one-page interpretation. 2–4 week timeline. Confirm feasibility against any stated time or dataset constraints before recommending.

Step 9: Publication Upgrade Path

→ Full upgrade impact table: references/upgrade_path.md

Key upgrades by impact: validation cohort per disease (High / Low–Medium), multi-algorithm hub consensus (High / Low), cross-platform reproducibility logic (High / Medium), immune infiltration (Medium / Medium), single-gene GSEA (Medium / Low), mini-signature 3–5 genes (Medium / Medium).

R Code Framework Guidelines

When providing R code examples or pipeline frameworks:

1. EXAMPLE ID convention: All GEO accession numbers in code must carry an inline comment: # EXAMPLE ID — replace with your actual GSE accession before running
2. Zero-intersection guard: All pipelines must include a feasibility check immediately after DEG intersection:

   if (length(shared_genes) == 0) {
     stop("No shared DEGs found. Recovery options: (1) relax logFC to 0.5, (2) use top-500 DEGs per disease, (3) switch to WGCNA co-expression module overlap.")
   }
   

3. Standard package list: GEOquery, limma, clusterProfiler, org.Hs.eg.db, pROC, igraph, STRINGdb, WGCNA. Provide BiocManager::install() calls where needed.
4. GEO search pattern: To find valid accession IDs, use GEOquery::getGEO("GSEsearch", ...) or direct search at https://www.ncbi.nlm.nih.gov/geo/

Standard R pipeline template:

library(GEOquery); library(limma); library(clusterProfiler); library(pROC)

# Load datasets — EXAMPLE IDs: replace before running
gse_disease1 \x3C- getGEO("GSEXXXXX", GSEMatrix = TRUE)[[1]]  # EXAMPLE ID
gse_disease2 \x3C- getGEO("GSEXXXXX", GSEMatrix = TRUE)[[1]]  # EXAMPLE ID

# DEG analysis (repeat for disease2)
design \x3C- model.matrix(~ group, data = pData(gse_disease1))
fit    \x3C- eBayes(lmFit(exprs(gse_disease1), design))
deg_d1 \x3C- subset(topTable(fit, coef = 2, adjust = "BH", number = Inf),
                 abs(logFC) > 1 & adj.P.Val \x3C 0.05)

# Shared DEG intersection with zero-guard
shared_genes \x3C- intersect(rownames(deg_d1), rownames(deg_d2))
if (length(shared_genes) == 0) {
  stop("No shared DEGs found. Recovery: relax logFC to 0.5 or use top-500 DEGs per disease.")
}

# ROC for top hub gene — EXAMPLE: replace 'HUB_GENE' and labels/scores with real data
roc_obj \x3C- roc(response = labels, predictor = expr_scores)
cat("AUC:", auc(roc_obj), "\
")
if (auc(roc_obj) \x3C 0.70) warning("AUC below 0.70 threshold. Consider mini-signature approach.")

Hard Rules

1. Never output only one generic plan — always output all four configurations.
2. Always recommend one primary plan with justification.
3. Always separate necessary modules from optional modules.
4. Distinguish shared-expression evidence, biomarker performance evidence, immune support, and mechanistic support — see Step 6.
5. Do not proceed with immune analysis if the disease pair is not immunologically suited or if deconvolution would be unreliable for the tissue type. Consult references/tissue_and_tool_decisions.md to select the correct tool.
6. Do not overclaim diagnostic value from ROC in small (n \x3C 30 per group) or unmatched cohorts. Always report bootstrap confidence intervals.
7. Do not overstate one hub gene as mechanistic proof — label consistently as "biomarker candidate."
8. Do not treat immune-correlation evidence as causal immune regulation.
9. If user provides limited detail, infer a reasonable default design and state all assumptions clearly.
10. Do not produce only a flat methods list or literature summary.
11. Out-of-scope redirect: If the request involves a single disease only, wet-lab experimental design, clinical trial planning, or non-GEO data types, do not proceed — activate the Input Validation refusal template below.

Input Validation

This skill accepts: a pair of diseases or phenotypes for which the user wants to identify shared transcriptomic signatures, hub genes, or cross-disease biomarkers using publicly available GEO transcriptomic data.

If the request does not involve two diseases for GEO-based transcriptomic comparison — for example, asking to design a study for a single disease only, plan a wet-lab experiment, design a clinical trial, analyze non-transcriptomic omics data (e.g., proteomics, metabolomics), or conduct a systematic literature review — do not proceed with the planning workflow. Instead respond:

"Dual-Disease Transcriptomic ML Planner is designed to generate GEO-based transcriptomic + machine learning study designs for pairs of diseases. Your request appears to be outside this scope. Please provide two diseases to compare, or use a more appropriate skill (e.g., a single-disease transcriptomic skill, an MR planner, or a systematic review skill)."

Reference Files