Immune Pathway Analysis

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

Immune Pathway Analysis

When to Use

Use this skill when the goal is to quantify immune-related pathway activity from bulk expression data and compare pathway enrichment between two sample groups.

Typical requests:

• "Run immune pathway GSVA for these samples."
• "Score immune Reactome pathways and compare case versus control."
• "Generate an immune pathway heatmap from a saved result."
• "Use a local immune gene-set table for pathway scoring."

This skill is appropriate for:

• Bulk RNA-seq or microarray-like expression matrices
• Local immune Reactome gene-set tables prepared in advance
• Two-group pathway differential analysis with limma
• Reproducible CLI execution with append-only provenance files

Execution Model

This is a hybrid skill.

1. Confirm the request is in scope with this SKILL.md.
2. Ask only for missing file paths or missing group labels.
3. Run scripts/main.R with the appropriate mode.
4. Use --mode analyze to score pathways and export tables.
5. Use --mode visualize to regenerate a heatmap from a saved result object.
6. Use --mode full to run analysis and visualization in one pass.
7. Read reference files only when you need deeper algorithm, troubleshooting, or CLI details.
8. After execution, report the output directory, scoring method, comparison groups, and the primary output files.

Completion Format

After a successful run, summarize the outcome in 3 short parts:

1. Mode and method used, plus the compared groups.
2. Output directory and key files written.
3. Important warnings that affect interpretation, such as no pathways meeting fdr_threshold and fallback to |t| ranking.

Example completion summary:

Completed immune pathway analysis in ./output/run_001 using gsva for Case versus Control. Key outputs: table/immune_pathway_diff.csv, table/immune_pathway_scores.csv, data/immune_pathway_result.rds, and plot/immune_pathway_heatmap.pdf. No pathways passed FDR <= 0.05, so the workflow used the documented fallback ranking by |t| for the top-pathway export and heatmap subset.

When to Read External Files

When Not to Use

• Immune cell fraction estimation or deconvolution
• Gene-level differential expression without pathway scoring
• Single-cell clustering, annotation, or communication analysis
• Clinical diagnosis or treatment selection

If the request falls outside these boundaries, stop and state that this skill only covers bulk immune pathway GSVA or ssGSEA analysis from a local immune gene-set table.

Input Validation

This skill accepts:

• A bulk expression matrix in CSV or TSV format
• A sample group file with exactly two comparison groups for analysis mode
• A local immune gene-set table in long format
• An existing output directory containing data/immune_pathway_result.rds for visualize mode

If the user's request does not involve bulk immune pathway scoring from local files, do not proceed with the workflow. Instead respond:

"Immune Pathway Analysis is designed for bulk immune pathway GSVA or ssGSEA analysis from a local gene-set table. Your request appears to be outside this scope. Please provide a bulk expression matrix, a two-group sample file, and a local pathway table, or use a more appropriate skill for deconvolution, differential expression, or single-cell analysis."

If the request is in scope but required inputs are missing, ask only for the missing file paths or group labels before running scripts/main.R.

Usage

Rscript scripts/main.R \
  --mode full \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --geneset_file ./immune_genesets.csv \
  --case_group Case \
  --control_group Control \
  --output_dir ./output/run_001 \
  --seed 42

Arguments

Input Format

Expression Matrix

• CSV or TSV file
• The first column contains gene identifiers
• Remaining columns are sample names
• Values must be numeric
• Missing values are not allowed

Group File

• CSV or TSV file with a header
• Supported sample column names: sample, sample_name, sample_id, sampleid
• Supported group column names: group, condition, class, cluster
• Sample names must match the expression matrix columns

Gene-Set Table

• CSV or TSV file in long format
• One row per gene-to-pathway mapping
• Must contain a pathway column and a gene column
• Default column names are gs_name and gene_symbol
• Alternate schemas are supported through --geneset_column and --gene_column

Output Files

When no pathways pass the selected fdr_threshold, the workflow logs a warning and falls back to ranking pathways by |t|. In that case, table/immune_pathway_scores_top.csv can still be populated for downstream plotting and review.

Error Handling

Read references/troubleshooting.md if the error persists.

Testing

• Minimal runnable files are bundled in tests/data/.
• The bundled smoke-test dataset is intended to validate execution and the fallback path. It may legitimately produce zero pathways with FDR <= 0.05.
• tests/data/immune_genesets_minimal.csv is a unit-test fixture, not a drop-in full-workflow demo with tests/data/expression_matrix.csv unless you prepare a matching matrix with overlapping genes.
• Use Rscript tests/run_unit_tests.R to run boundary checks, helper-function checks, and validation tests without the full GSVA workflow.
• Use Rscript tests/run_tests.R to execute the unit checks plus the full smoke-test workflow.
• Use Rscript tests/test_skill.R tests/output to validate the expected outputs.
• The validated test baseline, package versions, fixture notes, and custom-column CLI examples are documented in references/cli-guide.md.