mdhewei/bioinfor-claw/coexpression-for-gene

Co-expression for Gene (TCGA / GTEx Patient Samples)

⚠️ SCOPE: This skill analyzes co-expression across patient/tissue samples

(TCGA tumors, GTEx normal tissues). For co-expression across cancer cell lines

(DepMap), use depmap-analysis-for-gene → depmap_coexpression.py instead.

Data Sources

1. TCGA (default) — Fetches mRNA expression (RNA-Seq V2 RSEM) from the

cBioPortal REST API (www.cbioportal.org). Queries TCGA PanCancer Atlas studies (32 cancer types). Requires internet access.

1. GTEx — Requires a user-provided expression matrix file (genes × samples

TSV). GTEx data is not available via cBioPortal.

1. Custom — User-provided expression matrix TSV via --expression-file.

Purpose

Discover genes whose expression patterns correlate with a query gene, enabling:

• Identification of functionally related genes (co-expressed gene modules)
• Gene set enrichment and pathway analysis
• Functional annotation of uncharacterized genes
• Network-based gene prioritization for disease studies
• Tissue-specific co-expression patterns

Use When

• You want to find genes functionally related to a query gene
• You're characterizing gene regulatory networks in specific tissues
• You need functional annotations for uncharacterized genes
• You're building disease-associated gene modules
• You want tissue-specific vs pan-cancer co-expression patterns
• You need pathway enrichment for co-expressed gene sets

Do Not Use When

• You need causal regulatory relationships (use ChIP-seq or ATAC-seq data)
• You want direct protein-protein interactions (use STRING or BioGRID)
• You're analyzing time-series or developmental gene expression
• You need single-cell resolution (use scRNA-seq tools)
• You want cell-type specific co-expression (tissue level analysis only)
• You want co-expression across cancer cell lines → use depmap-analysis-for-gene/depmap_coexpression.py
• You want co-essentiality (CRISPR dependency correlations) → use depmap-analysis-for-gene/depmap_coessentiality.py

Expected Inputs & Outputs

Inputs

• --gene (required): Query gene symbol (e.g., TP53, BRCA1)
• --dataset: Source of expression data (choices: tcga, gtex, custom; default: tcga)
• --cancer-type: TCGA project code (default: BRCA; ignored if dataset != tcga)
• --tissue: GTEx tissue name (default: Breast_Mammary_Tissue; ignored if dataset != gtex)
• --expression-file: Path to custom expression matrix TSV (required if dataset=custom or gtex)
• --method: Correlation method (choices: pearson, spearman; default: pearson)
• --top-n: Number of top co-expressed genes to report (default: 100)
• --fdr-cutoff: FDR threshold for significance (default: 0.01)
• --network-top-n: Number of top genes to include in network visualization (default: 30)
• --run-go: Flag to run GO enrichment analysis using Enrichr API
• --outdir: Output directory

Outputs

• coexpression_results.tsv: Complete results (gene, correlation, pvalue, fdr)
• top_coexpressed.png: Horizontal bar chart of top N co-expressed genes
• coexpression_network.png: Force-directed network of top 30 genes
• go_enrichment.tsv: GO term enrichment results (if --run-go)
• go_bubble.png: Bubble plot of GO enrichment (if --run-go)
• coexpression_summary.txt: Summary statistics and parameters

Key Execution Patterns

Pan-TCGA breast cancer (default):

python scripts/coexpression_for_gene.py \
  --gene BRCA1 \
  --dataset tcga \
  --cancer-type BRCA \
  --outdir results/brca1_coexpr

Specific TCGA cohort with GO enrichment:

python scripts/coexpression_for_gene.py \
  --gene TP53 \
  --dataset tcga \
  --cancer-type LUAD \
  --run-go \
  --top-n 150 \
  --outdir results/tp53_luad

GTEx tissue-specific (requires local file):

python scripts/coexpression_for_gene.py \
  --gene EGFR \
  --dataset gtex \
  --expression-file gtex_lung_expression.tsv \
  --tissue Lung \
  --method spearman \
  --fdr-cutoff 0.001 \
  --outdir results/egfr_lung

Custom expression matrix:

python scripts/coexpression_for_gene.py \
  --gene MYC \
  --dataset custom \
  --expression-file my_expression_matrix.tsv \
  --run-go \
  --network-top-n 50 \
  --outdir results/myc_custom

Parameter Decision Guide

Failure Modes

Technical Notes

• TCGA expression data: RNA-Seq V2 RSEM normalized values from cBioPortal PanCancer Atlas
• Correlations computed only on samples with complete data for both genes
• Gene variance threshold: requires SD > 0.01 to avoid spurious correlations
• FDR correction uses Benjamini-Hochberg procedure
• Network layout: spring/force-directed layout
• Pearson assumes linear relationships; Spearman is more robust to outliers
• GO enrichment uses Enrichr database (GO_Biological_Process_2023)
• Minimum 30 samples recommended for reliable correlation estimates