AGENT SKILL

deg-screening-analysis

Use when screening differentially expressed genes from a bulk expression matrix between two user-specified groups, producing DEG tables, a volcano plot, and a clustered heatmap. Triggers include DEG analysis, volcano plot, clustered heatmap, limma-based two-group comparison, and case-vs-control screening. NOT for single-cell RNA-seq, multi-group contrasts, count-model workflows such as DESeq2/edgeR, or non-expression omics data.

License 许可
MIT
最近更新
2026-10-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
deg-screening-analysis
author
AIPOCH
license
MIT
description
Use when screening differentially expressed genes from a bulk expression matrix between two user-specified groups, producing DEG tables, a volcano plot, and a clustered heatmap. Triggers include DEG analysis, volcano plot, clustered heatmap, limma-based two-group comparison, and case-vs-control screening. NOT for single-cell RNA-seq, multi-group contrasts, count-model workflows such as DESeq2/edgeR, or non-expression omics data.

02 资源文件 12

03 SKILL.md 正文

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

04 同仓库更多 Skills

mrsonord2240
mrsonord2240/openscience-specialists

bio-workflows-metabolomics-pipeline

Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-xcms-preprocessing

Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-statistical-analysis

Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-pathway-mapping

Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-normalization-qc

Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-msdial-preprocessing

Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.

★ 2