← LeaderboardThe Skill Leaderboard

ssgsea-immune-infiltration-analysis

Use when estimating immune infiltration from bulk RNA-seq expression matrices with ssGSEA/GSVA, comparing case versus control groups, and generating downstream immune-score visualizations. NOT for single-cell RNA-seq, absolute cell proportion estimation, or clinical decision making.

Published by aipoch ↗aipoch/medical-research-skills

Try your first task

Start a fresh conversation. Replace the highlighted placeholders.

Use ssgsea-immune-infiltration-analysis to analyze [bulk expression matrix, group file with case/control labels, and immune gene-set CSV], producing relative immune-enrichment comparisons, result tables, and optional visualizations for research review only, not clinical decision-making.

Required inputs

[bulk expression matrix, group file with case/control labels, and immune gene-set CSV]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: ssgsea-immune-infiltration-analysisdescription: Use when estimating immune infiltration from bulk RNA-seq expression matrices with ssGSEA/GSVA, comparing case versus control groups, and generating downstream immune-score visualizations. NOT for single-cell RNA-seq, absolute cell proportion estimation, or clinical decision making.license: MITauthor: AIPOCH

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

ssGSEA Immune Infiltration Analysis

When to Use

Estimate relative immune infiltration from a bulk RNA-seq expression matrix.
Compare immune enrichment scores between one case group and one control group.
Generate structured result tables plus optional PDF visualizations for downstream review.

When Not to Use

Single-cell RNA-seq or spatial transcriptomics.
Absolute immune cell proportion estimation or deconvolution.
Clinical diagnosis, treatment recommendation, or any other medical decision making.

Workflow

Confirm that the expression matrix, group file, and gene-set file match the documented schemas.
Run scripts/main.R with the target case and control groups.
Review run_record.txt, output_manifest.txt, and the generated tables or plots.
If execution fails, read references/troubleshooting.md before retrying.

When to Read External Files

Situation	File to Read	Purpose
Need to run the analysis	`scripts/main.R`	CLI entry point
Need algorithm details	`references/algorithm.md`	Method assumptions and interpretation
Encounter an error	`references/troubleshooting.md`	Error codes and fixes
Need CLI examples or baseline execution details	`references/cli-guide.md`	Examples and recorded run details
Need dependency declarations	`DESCRIPTION`	Package list and Bioconductor source note
Need test commands	`tests/run_tests.R`	End-to-end test entry

Usage

Rscript scripts/main.R \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --gene_set ./immune_gene_sets.csv \
  --case_group treatment \
  --control_group control \
  --output_dir ./output \
  --method ssgsea \
  --seed 42

Validated path note:

ssgsea is the default validated path.
gsva is supported, but only with kernels validated in the local GSVA environment.
In the current audited environment, gsva with Gaussian completed successfully and is the documented baseline.

Arguments

Short	Long	Type	Default	Description
`-i`	`--input_file`	file	required	Expression matrix with genes as rows and samples as columns
`-g`	`--group_file`	file	required	Group annotation table
`-e`	`--gene_set`	file	`tests/data/immune_gene_sets.csv`	Immune gene-set CSV
`-a`	`--case_group`	string	required	Case group label
`-b`	`--control_group`	string	required	Control group label
`-o`	`--output_dir`	dir	`./output`	Output directory
`-m`	`--method`	string	`ssgsea`	GSVA method: `ssgsea`, `gsva`
`-k`	`--kcdf`	string	`Gaussian`	Kernel mode: `Gaussian`, `Poisson`; `Gaussian` is the validated GSVA baseline
`-n`	`--min_sz`	integer	`2`	Minimum overlap genes per gene set
`-x`	`--max_sz`	integer	`10000`	Maximum genes per gene set
`-p`	`--parallel_sz`	integer	`2`	Requested parallel CPU count
`-u`	`--tau`	numeric	`0.25`	Tau parameter for ssGSEA
`-d`	`--mx_diff`	boolean	`true`	GSVA `mx.diff` switch
`-c`	`--gene_id_case`	string	`upper`	Gene ID normalization: `asis`, `upper`, `lower`
`-s`	`--seed`	integer	`42`	Random seed
`-t`	`--timeout_seconds`	integer	`0`	Optional timeout; `0` disables it
	`--sample_col`	string/int	none	Sample column name or 1-based index
	`--group_col`	string/int	none	Group column name or 1-based index
	`--make_plots`	boolean	`true`	Generate PDF plots
	`--verbose`	boolean	`true`	Print progress logs

Input Format

Expression Matrix

CSV or TSV. The first column must contain gene identifiers. Remaining columns are sample-level numeric expression values.

gene,Sample1,Sample2,Sample3
TP53,10.2,8.5,9.1
CXCL9,4.3,6.1,5.7

Group File

CSV or TSV with at least one sample column and one group column.

sample,group
Sample1,control
Sample2,treatment
Sample3,treatment

Gene Set File

CSV with gene and cell_type; immunity_class is optional.

gene,cell_type,immunity_class
CXCL9,Activated CD8 T cell,Adaptive
CD3D,Activated CD8 T cell,Adaptive

Output Files

File	Description
`data/ssgsea_list.rds`	Serialized analysis result object
`table/ssgsea_scores_long.csv`	Long-format immune infiltration scores
`table/ssgsea_scores_wide.csv`	Wide-format immune infiltration score matrix
`table/ssgsea_group_compare.csv`	Case-vs-control comparison summary
`table/immune_cell_correlation_matrix.csv`	Immune-cell Spearman correlation matrix
`table/immune_cell_correlation_pvalue.csv`	Correlation p-value matrix
`plot/immune_cell_composition_sample.pdf`	Sample-level composition plot; generated only when `--make_plots=true`
`plot/immune_group_boxplot.pdf`	Group comparison boxplot; generated only when `--make_plots=true`
`plot/immune_correlation_heatmap.pdf`	Immune-cell correlation heatmap; generated only when `--make_plots=true`
`plot/gene_immune_correlation_scatter_*.pdf`	Auto-selected gene-vs-cell scatter plot; generated only when `--make_plots=true`
`run_record.txt`	Structured execution record
`output_manifest.txt`	Output file manifest with descriptions
`session_info.txt`	R session information

Error Handling

Error	Cause	Solution
`SKILL_FILE_NOT_FOUND`	Input file path is invalid	Check file paths
`SKILL_MISSING_COLUMNS`	Required columns are absent	Fix the input schema
`SKILL_EMPTY_DATA`	No usable rows, gene sets, or aligned samples remain	Check IDs and filters
`SKILL_INVALID_PARAMETER`	CLI value is invalid or data is malformed	Review arguments and file content
`SKILL_SAMPLE_MISMATCH`	Expression and group samples do not align	Harmonize sample identifiers
`SKILL_PACKAGE_NOT_FOUND`	Required R package is missing	Install the missing package
`SKILL_TIMEOUT`	The configured time limit was exceeded	Increase `--timeout_seconds` or disable it with `0`

Testing

Rscript scripts/main.R --help

Rscript tests/run_tests.R

Rscript tests/test_skill.R

tests/test_skill.R is self-contained: if expected outputs are absent, it first runs tests/run_tests.R and then validates both file presence and core result structure.