Source: https://github.com/aipoch/medical-research-skills

Differential Expression Gene Screening Analysis (Volcano Plot & Clustered Heatmap)

When to Use

Use this skill when you need a reproducible two-group DEG workflow on a bulk expression matrix and want:

• a full differential expression table
• a filtered DEG table
• a volcano plot
• a clustered heatmap of top differential genes

Typical requests include:

• compare case vs control samples with limma
• screen upregulated and downregulated genes from a normalized expression matrix
• generate a DEG table with volcano and heatmap outputs from bulk transcriptome data

Out of Scope

Do not use this skill for:

• single-cell RNA-seq workflows
• multi-group contrasts or factorial designs
• count-model pipelines that require DESeq2 or edgeR
• batch correction, covariate-adjusted models, or generalized design-matrix consulting
• non-expression omics data

If the request falls outside this scope, stop and hand off to a more appropriate analysis workflow instead of forcing the data through this skill.

Practical Caveats

• Diffanalysis.csv currently exports name, logFC, P.value, and P.adj.
• --p_type controls both DEG screening semantics and volcano plot significance semantics.
• plot/heatmap.pdf is generated only when at least two heatmap genes remain after ranking.
• When the result is very sparse, prefer keeping tables and volcano output as the primary artifacts.

When to Read External Files

Usage

Rscript scripts/main.R \
  --input_file tests/data/oa_exp.csv \
  --group_file tests/data/oa_group.csv \
  --case OA \
  --control control \
  --output_dir ./results

Arguments

Output Files

Workflow

Step 1: Validate Input

• check that input files exist
• load the expression matrix and ensure it is non-empty
• auto-detect sample and group columns in the group file
• verify sample IDs overlap correctly
• verify case/control groups exist and each selected group has at least two samples

Step 2: Run Differential Expression

• fit a two-group limma linear model
• build the contrast case - control
• compute empirical Bayes moderated statistics
• export the full differential result table

Step 3: Screen Differentially Expressed Genes

• apply p_threshold and logfc_threshold
• use P.value or P.adj based on --p_type
• label genes as up, down, or no
• export DEG tables and serialized result objects

Step 4: Generate Volcano Plot & Clustered Heatmap

• build plot/volcano_plot.pdf directly from the full differential table
• select top up and top down genes for heatmap input
• build plot/heatmap.pdf only when at least two heatmap genes are available

Error Handling

If you need step-by-step fixes, read references/troubleshooting.md.

Testing

Rscript tests/run_tests.R

Minimal CLI smoke test:

Rscript scripts/main.R \
  --input_file tests/data/oa_exp.csv \
  --group_file tests/data/oa_group.csv \
  --case OA \
  --control control \
  --output_dir ./tests_output

Expected outputs:

• tests_output/table/Diffanalysis.csv
• tests_output/table/DEG.csv
• tests_output/plot/volcano_plot.pdf
• tests_output/session_info.txt

tests_output/plot/heatmap.pdf is expected only when enough significant genes remain for heatmap rendering. Runs with fewer than two selected heatmap genes skip heatmap generation with a warning instead of failing. tests_output/table/DEG.csv may be empty when no genes pass the current thresholds.

Skill name: deg-screening-analysis