Estimate Immune Score Analysis

ESTIMATE Immune Score Analysis

When to Use

Use this skill when the user wants to:

• compute ESTIMATE-derived immune and stromal scores from a bulk expression matrix
• transform an expression matrix into estimate package input files and score outputs
• generate an ESTIMATE score heatmap across samples
• compare ESTIMATE scores across sample groups when a sample group file is available
• create a reproducible CLI-backed ESTIMATE workflow with structured output records

Typical request patterns:

• "Run ESTIMATE immune score analysis on this expression matrix"
• "Calculate ImmuneScore and StromalScore from my bulk RNA-seq data"
• "Generate ESTIMATE scores and save a sample-level result table"

Execution Model

This is a CLI-backed analysis skill.

1. Use SKILL.md to confirm that the task is ESTIMATE score generation from bulk expression data.
2. Use scripts/main.R for the real execution.
3. Provide one expression matrix file with genes in the first column and samples in the remaining columns.
4. Optionally provide a sample group file to generate ESTIMATE score boxplots and a significance summary table.
5. The workflow always generates an ESTIMATE score heatmap from the computed score table.
6. Read reference files only when you need algorithm details, troubleshooting, or baseline execution notes.

When to Read External Files

When Not to Use

• Immune cell fraction estimation: use a CIBERSORT-like deconvolution workflow instead
• Differential testing between biological groups: use a differential analysis skill instead
• Single-cell analysis: use a single-cell-specific workflow
• Clinical diagnosis or treatment decision support: do not use this skill

If the request is outside ESTIMATE score generation for bulk expression matrices, stop and explain that this skill only covers ESTIMATE-based score computation.

Input Validation

This skill accepts:

• one bulk expression matrix in CSV or TSV format with genes in the first column and samples in the remaining columns
• an optional sample group file in CSV or TSV format for grouped boxplots and significance testing
• requests to compute ESTIMATE-derived StromalScore, ImmuneScore, ESTIMATEScore, TumorPurity, and related visualizations from bulk transcriptomic data

Do not use this workflow for:

• single-cell RNA-seq or spatial transcriptomics
• immune cell deconvolution requests
• direct clinical diagnosis, treatment recommendation, or patient-level medical decision making
• unrelated tasks such as literature writing, web scraping, or generic plotting without ESTIMATE score generation

If the user's request is outside this scope, do not proceed with the workflow. Instead respond:

estimate-immune-score-analysis is designed to compute ESTIMATE-based tumor microenvironment scores from a bulk expression matrix. Your request appears to be outside this scope. Please provide a valid bulk expression matrix and, if needed, a matching sample group file, or use a more appropriate skill for your task.

Usage

Rscript scripts/main.R \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --output_dir ./output \
  --gene_id_type GeneSymbol \
  --platform affymetrix \
  --seed 42

Arguments

Input Format

• CSV or TSV file
• First column contains gene identifiers
• Remaining columns are sample names
• Expression values must be numeric and non-missing
• Sample column names must be unique; duplicate sample column names raise SKILL_INVALID_PARAMETER

Example:

gene,S1,S2,S3
TP53,8.1,7.9,6.5
EGFR,5.2,5.0,4.2

The bundled tests/data/expression_matrix.csv was copied from cibersort-immune-infiltration-analysis/tests/data/expression_matrix.csv for demo and validation use.

Optional Group File

• CSV or TSV file
• Must contain one sample column and one group column
• Sample names must match the ESTIMATE score table sample IDs
• Exactly two group levels are supported for boxplot comparison. If more than two groups are present in the group file, SKILL_INVALID_PARAMETER is raised.
• Each group must contain at least 3 samples for valid statistical testing. Groups with fewer samples trigger SKILL_INVALID_PARAMETER.
• If the group file is provided but grouped comparison fails after core scoring, the command exits with a SKILL_* error after preserving the core ESTIMATE outputs and failure records

Example:

sample,group
S1,Tumor
S2,Tumor
S3,Healthy
S4,Healthy