Deg Screening Analysis

> 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

| Situation | File to Read | Purpose | |-----------|--------------|---------| | Need algorithm details or statistical assumptions | references/algorithm.md | limma method, filtering logic, volcano/heatmap selection rules | | Need to execute the workflow | scripts/main.R | Get the exact CLI entry and runnable command | | Encounter an error code or bad input format | references/troubleshooting.md | Match SKILL_* errors to causes and fixes | | Need more CLI examples | references/cli-guide.md | See complete command examples for common use cases | | Need a minimal runnable example | tests/data/ | Use bundled test input files for validation |

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

| Short | Long | Type | Default | Required | Description | |-------|------|------|---------|----------|-------------| | -i | --input_file | character | none | yes | Expression matrix CSV. First column is gene ID, remaining columns are sample values. | | -g | --group_file | character | none | yes | Group annotation CSV. The script auto-detects sample and group columns, including files where the first column is row names or index. | | -o | --output_dir | character | ./DEG | no | Output directory for tables, plots, and session metadata. | | | --case | character | none | yes | Case group name to compare. Matching is case-insensitive and trimmed. | | | --control | character | none | yes | Control group name to compare. Matching is case-insensitive and trimmed. | | -m | --diff_method | character | limma | no | Differential expression method. Current implementation supports limma only. | | -p | --p_threshold | numeric | 0.05 | no | Significance threshold for DEG screening. | | -f | --logfc_threshold | numeric | 1 | no | Absolute log fold change threshold for DEG screening. | | | --top_n | integer | 5 | no | Number of top upregulated and top downregulated genes considered for heatmap selection. | | | --p_type | character | p.adj | no | P-value field used for significance filtering and volcano significance coloring. Allowed values: p, p.adj. | | | --run_plots | logical | TRUE | no | Whether to generate the volcano plot and clustered heatmap. | | | --timeout_seconds | integer | 3600 | no | Maximum allowed runtime before timeout. | | -s | --seed | integer | 42 | no | Random seed recorded for reproducibility. |

Output Files

| File | Format | Description | |------|--------|-------------| | session_info.txt | txt | R session metadata and package versions used in the run. | | data/DEG_list.rda | rda | Serialized R object containing method, groups, thresholds, the full differential table, and the screened DEG table. | | table/Diffanalysis.csv | csv | Full differential expression result table with columns name, logFC, P.value, and P.adj. | | table/DEG.csv | csv | Significant DEG table only, containing screened genes with group labels up or down. | | plot/volcano_plot.pdf | pdf | Volcano plot of differential genes using the p-value mode selected by --p_type. | | plot/heatmap.pdf | pdf | Clustered heatmap for selected top differential genes when at least two heatmap genes are available and plotting is enabled. |

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

| Error Code | Meaning | Typical Fix | |------------|---------|-------------| | SKILL_FILE_NOT_FOUND | Input file path does not exist | Verify the file path and rerun | | SKILL_PACKAGE_NOT_FOUND | Required R package is missing | Install the missing package, then rerun | | SKILL_MISSING_COLUMNS | Input file does not contain the necessary columns | Check CSV structure and column placement | | SKILL_EMPTY_DATA | Input file is empty or limma returns no analyzable rows | Validate input content or confirm the matrix contains enough valid values | | SKILL_INVALID_PARAMETER | Argument value or group selection is invalid | Check thresholds, --case, --control, and --p_type | | SKILL_SAMPLE_MISMATCH | Expression matrix samples and group file samples do not match | Align sample IDs between the two input files | | SKILL_TIMEOUT | The run exceeded the allowed runtime | Increase --timeout_seconds or simplify the run |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aipoch
• Source: aipoch/medical-research-skills
• License: MIT
• Homepage: https://aipoch.com/agent-skills

Install and usage instructions live in the source repository linked above.