ssgsea-immune-infiltration-analysis

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

1. Confirm that the expression matrix, group file, and gene-set file match the documented schemas.
2. Run scripts/main.R with the target case and control groups.
3. Review run_record.txt, output_manifest.txt, and the generated tables or plots.
4. 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.