Cibersort Immune Infiltration Analysis

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

CIBERSORT Immune Infiltration Analysis

When to Use

• Estimate relative immune cell fractions from a bulk expression matrix.
• Compare one case group against one control group after deconvolution.
• Generate structured tables, a serialized result object, and optional PDF plots.

When Not to Use

• Single-cell RNA-seq, spatial transcriptomics, or clustering tasks.
• Absolute clinical interpretation or treatment recommendation.
• Workflows that require the original online CIBERSORT service instead of a local R implementation.

Workflow

1. Confirm that the expression matrix, group file, and signature matrix are available.
2. Run scripts/main.R with the case and control groups.
3. Review the full result table, derived summary tables, and optional plots.
4. Inspect run_record.txt and output_manifest.txt after each run, including failed validation attempts.

When to Read External Files

Usage

Rscript scripts/main.R \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --signature_file ./LM22.txt \
  --case_group treatment \
  --control_group control \
  --output_dir ./output \
  --qn false \
  --seed 42

Arguments

Input Format

Expression Matrix

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

When --auto_unlog=true, the workflow reports summary statistics and applies 2^x only if the matrix passes a conservative log-scale heuristic. If the matrix is ambiguous, the values are left unchanged and the startup log explains why.

If duplicate gene identifiers are present, they are consolidated after gene-ID normalization by taking the per-sample maximum before downstream filtering and deconvolution.

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

Group File

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

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

Signature Matrix

The packaged default is tests/data/LM22.txt. A custom signature matrix must contain one gene column followed by immune-cell signature columns.

All immune-cell signature columns must be numeric and finite. If duplicate gene identifiers are present, they are consolidated by taking the per-cell-type maximum before gene intersection.

Output Files

When --make_plots=false, the plot/ directory may still exist as part of the standard output layout, but no PDF plot files are written.

When --perm=0, the workflow logs a warning and completes without empirical permutation testing, so the P-value column is recorded as NA.

When a rerun targets an existing --output_dir and then fails validation or execution, the previous successful payload is preserved and the failure is appended to run_record.txt and output_manifest.txt.

Error Handling

If the error persists, READ: references/troubleshooting.md

Input Validation

This skill accepts:

• A bulk expression matrix file in CSV or TSV format with one gene column and numeric sample columns.
• A group annotation file in CSV or TSV format with one sample column and one group column.
• Exactly one case group label and one control group label for comparison.
• An optional custom signature matrix compatible with the documented LM22-style schema.

Do not use this skill for:

• Single-cell RNA-seq, spatial transcriptomics, or cell clustering workflows.
• Clinical diagnosis, treatment recommendation, or patient-level medical decision making.
• Requests that need the hosted CIBERSORT web service rather than this local R implementation.
• Multi-group study designs that require more than one case group versus one control group in a single run.

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

"cibersort-immune-infiltration-analysis is designed for local CIBERSORT-style immune deconvolution from a bulk expression matrix with one case group and one control group. Your request appears to be outside this scope. Please provide compatible bulk-expression inputs and group labels, or use a more appropriate tool for your task."

Testing

Rscript scripts/main.R --help

Rscript tests/run_tests.R

Rscript tests/test_skill.R

Validated packaged test path:

Rscript scripts/main.R \
  --input_file tests/data/expression_matrix.csv \
  --group_file tests/data/group_info.csv \
  --signature_file tests/data/LM22.txt \
  --case_group Tumor \
  --control_group Healthy \
  --output_dir tests/output \
  --perm 25 \
  --qn false \
  --svm_cores 1 \
  --seed 42

Container note:

• The packaged test path uses --qn false because preprocessCore::normalize.quantiles() may trigger environment-level thread failures in some containers.
• If you need a quantile-normalized run, validate that environment first and record the result in references/cli-guide.md.
• tests/run_tests.R also checks that a failed rerun does not erase an existing successful payload directory.