cibersort-immune-infiltration-analysis
Use when estimating relative immune cell infiltration from a bulk expression matrix with a CIBERSORT-style nu-SVR deconvolution workflow based on an LM22 signature matrix, comparing one case group against one control group, and generating structured tables plus immune-fraction plots. NOT for single-cell RNA-seq, spatial data, clinical diagnosis, or workflows that require the original hosted CIBERSORT web service.
- License 许可
- MIT
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- cibersort-immune-infiltration-analysis
- author
- AIPOCH
- license
- MIT
- description
- Use when estimating relative immune cell infiltration from a bulk expression matrix with a CIBERSORT-style nu-SVR deconvolution workflow based on an LM22 signature matrix, comparing one case group against one control group, and generating structured tables plus immune-fraction plots. NOT for single-cell RNA-seq, spatial data, clinical diagnosis, or workflows that require the original hosted CIBERSORT web service.
02 资源文件 18
- 参考文档references/algorithm.md3.7 KB
- 参考文档references/cli-guide.md7.8 KB
- 参考文档references/troubleshooting.md5.0 KB
- 脚本scripts/cli_options.R3.9 KB
- 脚本scripts/deconvolution.R2.7 KB
- 脚本scripts/functions.R4.6 KB
- 脚本scripts/io.R5.9 KB
- 脚本scripts/main.R2.6 KB
- 脚本scripts/recording_helpers.R2.2 KB
- 脚本scripts/recording_reports.R5.5 KB
- 脚本scripts/recording.R106 B
- 脚本scripts/run_analysis.R9.1 KB
- 脚本scripts/utils.R3.1 KB
- 脚本scripts/visualization.R2.6 KB
- 资产文件tests/data/expression_matrix.csv38.7 KB
- 资产文件tests/data/group_info.csv193 B
- 参考文档tests/data/LM22.txt143.3 KB
- 其他tests/run_tests.R4.1 KB
03 SKILL.md 正文
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
- Confirm that the expression matrix, group file, and signature matrix are available.
- Run
scripts/main.Rwith the case and control groups. - Review the full result table, derived summary tables, and optional plots.
- Inspect
run_record.txtandoutput_manifest.txtafter each run, including failed validation attempts.
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 |
HQ reference workflow and result interpretation |
| Encounter an error | references/troubleshooting.md |
Error codes and environment fixes |
| Need CLI examples or the baseline record | references/cli-guide.md |
Example commands and validation notes |
| Need packaged test inputs | tests/data/ |
Demo expression matrix, group file, and LM22 file |
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
| 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 |
-a |
--case_group |
string | required | Case group label |
-b |
--control_group |
string | required | Control group label |
-o |
--output_dir |
dir | ./output |
Output directory |
--signature_file |
file | tests/data/LM22.txt when present |
Signature matrix file | |
--sample_col |
string/int | none | Optional sample column name or 1-based index | |
--group_col |
string/int | none | Optional group column name or 1-based index | |
--gene_id_case |
string | upper |
Gene ID normalization: asis, upper, or lower |
|
--auto_unlog |
boolean | true |
Apply 2^x only if the expression matrix passes a conservative log-scale heuristic |
|
--min_mean_expression |
numeric | 1 |
Minimum mean expression before deconvolution | |
--perm |
integer | 1000 |
Permutation count for empirical p-value estimation; 0 keeps the run lightweight but records P-value as NA |
|
--qn |
boolean | true |
Apply quantile normalization to the mixture matrix | |
--svm_cores |
integer | 1 |
Worker count for the nu-SVR model selection step | |
--make_plots |
boolean | true |
Generate PDF plots | |
--plot_width |
numeric | 16 |
Default plot width in inches | |
--plot_height |
numeric | 10 |
Default plot height in inches | |
-s |
--seed |
integer | 42 |
Random seed |
-t |
--timeout_seconds |
integer | 0 |
Optional timeout in seconds; 0 disables it |
--verbose |
boolean | true |
Print progress logs |
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
| File | Description |
|---|---|
data/cibersort_input.rds |
Serialized aligned input matrices used by the local algorithm |
data/cibersort_null_distribution.rds |
Serialized permutation null distribution |
data/cibersort_result.rds |
Serialized result object with cell fractions, metrics, runtime settings, and heatmap rendering metadata |
table/CIBERSORT_Results.csv |
Full result table in CSV format |
table/CIBERSORT-Results.txt |
Full result table in tab-delimited text format |
table/cibersort_cell_fractions_wide.csv |
Wide-format immune cell fraction table |
table/cibersort_cell_fractions_long.csv |
Long-format immune cell fraction table |
table/cibersort_group_compare.csv |
Case-vs-control comparison summary |
table/cibersort_quality_metrics.csv |
Sample-level P-value, Correlation, and RMSE table |
table/immune_cell_correlation_matrix.csv |
Spearman correlation matrix across immune cell types |
table/immune_cell_correlation_pvalue.csv |
P-value matrix aligned to the correlation matrix |
plot/immune_cell_composition_sample.pdf |
Sample-level stacked composition plot when --make_plots=true |
plot/immune_group_boxplot.pdf |
Group comparison boxplot when --make_plots=true |
plot/immune_correlation_heatmap.pdf |
Immune-cell correlation heatmap when --make_plots=true |
session_info.txt |
R session information |
output_manifest.txt |
Append-only output manifest for successful and failed runs |
run_record.txt |
Append-only structured run record, including runtime notes and failed-run summaries |
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
| Error Code | Meaning | Solution |
|---|---|---|
SKILL_FILE_NOT_FOUND |
An input file or signature matrix was not found | Check the file path and rerun |
SKILL_MISSING_COLUMNS |
A required column is missing | Fix the input schema |
SKILL_EMPTY_DATA |
No usable genes, samples, or deconvolution outputs remain | Check the data, filtering, or signature overlap |
SKILL_INVALID_PARAMETER |
A CLI parameter is missing or invalid | Review the argument table and input values |
SKILL_SAMPLE_MISMATCH |
Expression samples and group annotations do not align | Harmonize sample identifiers |
SKILL_PACKAGE_NOT_FOUND |
A required R package is missing | Install the missing package |
SKILL_TIMEOUT |
The configured time limit was exceeded | Increase --timeout_seconds or set it to 0 |
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 falsebecausepreprocessCore::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.Ralso checks that a failed rerun does not erase an existing successful payload directory.
04 同仓库更多 Skills
bio-workflows-metabolomics-pipeline
Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.
bio-metabolomics-xcms-preprocessing
Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.
bio-metabolomics-statistical-analysis
Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.
bio-metabolomics-pathway-mapping
Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.
bio-metabolomics-normalization-qc
Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.
bio-metabolomics-msdial-preprocessing
Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.