sample-group-sankey-plot
Use when generating Sankey or alluvial plots from sample annotation tables where rows are samples and selected columns are categorical stages such as risk group, response status, subtype, or cohort labels. NOT for: gene network flow analysis, continuous-value trajectories, or graph-structured pathway visualization.
- License 许可
- MIT
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- sample-group-sankey-plot
- license
- MIT
- description
- Use when generating Sankey or alluvial plots from sample annotation tables where rows are samples and selected columns are categorical stages such as risk group, response status, subtype, or cohort labels. NOT for: gene network flow analysis, continuous-value trajectories, or graph-structured pathway visualization.
- skill-author
- AIPOCH
02 资源文件 10
- 参考文档references/algorithm.md2.0 KB
- 参考文档references/cli-guide.md1.8 KB
- 参考文档references/troubleshooting.md2.3 KB
- 脚本scripts/functions.R3.5 KB
- 脚本scripts/install_dependencies.R1.1 KB
- 脚本scripts/main.R4.9 KB
- 脚本scripts/run_analysis.R2.7 KB
- 脚本scripts/utils.R3.3 KB
- 资产文件tests/data/sample_annotations.csv130 B
- 其他tests/run_smoke_test.R1.4 KB
03 SKILL.md 正文
Sample Group Sankey Plot
Builds a reproducible Sankey/alluvial visualization from a tabular sample annotation file and exports the selected annotations, lodes-format table, plot PDF, and session metadata.
Input Validation
This skill accepts: a sample annotation table in CSV or TSV format where rows are samples and selected columns are categorical stages (e.g., risk group, response status, subtype, cohort label). At least 2 stage columns are required.
If the user's request does not involve generating a Sankey or alluvial flow diagram from categorical sample annotations — for example, asking to visualize a gene regulatory network, plot continuous-value trajectories, analyze pathway flow, or process non-tabular data — do not proceed with the workflow. Instead respond:
"sample-group-sankey-plot is designed to generate Sankey/alluvial plots from categorical sample annotation tables. Your request appears to be outside this scope. Please provide a sample annotation table with at least 2 categorical stage columns, or use a more appropriate tool for gene network visualization or pathway analysis."
Readability guidance: Sankey plots are recommended for fewer than 8 unique values per stage and fewer than 5 stages total. For larger inputs, filter or aggregate categories before plotting to ensure readable output.
Agent Response Contract
After a successful run, report to the caller:
Sankey plot generated successfully.
Stages plotted : <comma-separated stage column names>
Samples : <row count>
Output prefix : <output_prefix>
Outputs:
table/selected_annotations.csv
table/sankey_lodes.csv
plot/<output_prefix>.pdf
data/session_info.txt
Readability warnings (if any): <advisory messages or "none">
If the script exits with a non-zero status, surface the SKILL_* error code and message verbatim. Do not attempt to continue or retry silently.
When to Read External Files
| Situation | File to Read | Purpose |
|---|---|---|
| Need to run analysis | scripts/main.R |
Execute: Rscript scripts/main.R --input_file ... --output_dir ... |
| Need algorithm details | references/algorithm.md |
Alluvial transformation logic, assumptions, and plotting choices |
| Encounter errors | references/troubleshooting.md |
Common errors and solutions |
| Need CLI examples | references/cli-guide.md |
Detailed CLI examples |
| Need test data | tests/data/ |
Sample annotation tables for smoke tests and regression checks |
→ Reference files algorithm.md, troubleshooting.md, and cli-guide.md are in references/. If absent, rely on the Error Handling table below for common issues.
Usage
Environment Setup
Install required R packages before the first run:
Rscript scripts/install_dependencies.R
Note: install_dependencies.R installs from CRAN without version pinning. Tested with ggalluvial >= 0.12.5 and ggplot2 >= 3.4.0. For reproducible CI environments, consider using remotes::install_version().
Basic Command
Rscript scripts/main.R \
--input_file ./annotations.csv \
--output_dir ./output \
--columns risk,Responder \
--seed 42
Arguments
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-i |
--input_file |
character | required | Input CSV/TSV annotation table |
-o |
--output_dir |
character | ./output/ |
Output directory |
-c |
--columns |
character | all columns | Comma-separated stage columns to include in the plot. When omitted, all columns in the file are used as stages. |
-p |
--output_prefix |
character | sankey_plot |
Prefix for generated output files (alphanumeric, dot, underscore, or hyphen characters only) |
--width |
numeric | 7 |
Plot width in inches | |
--height |
numeric | 5 |
Plot height in inches | |
--alpha |
numeric | 0.5 |
Flow transparency between 0 and 1 |
|
--label_size |
numeric | 4.5 |
Stratum label size | |
--missing_label |
character | Missing |
Replacement label for blank or NA strata |
|
--title |
character | empty | Optional plot title | |
-s |
--seed |
integer | 42 |
Random seed recorded for reproducibility |
--timeout |
integer | 3600 |
Maximum allowed elapsed runtime in seconds; use 0 to disable |
Input Format
Annotation Table (input_file)
Delimited text file where rows represent samples and each selected column is a categorical stage shown in the Sankey plot.
SampleID,risk,Responder,Subtype
S1,High,Yes,Basal
S2,Low,No,LumA
S3,High,Yes,Basal
S4,Low,No,LumB
Requirements:
- The file must contain at least 2 columns if
--columnsis omitted. - Each selected column must exist in the file header.
- Selected columns are interpreted as categorical stages and will be converted to character values.
- Blank strings and
NAvalues are replaced with--missing_label. - CSV and TSV inputs are supported.
- Recommended: fewer than 8 unique values per stage and fewer than 5 stages total for readable plots.
Output Files
| File | Description |
|---|---|
table/selected_annotations.csv |
Filtered table containing only the plotted stage columns |
table/sankey_lodes.csv |
Long-format lodes table used to build the Sankey plot |
plot/{output_prefix}.pdf |
Sankey/alluvial plot as a PDF file; default filename is sankey_plot.pdf |
data/session_info.txt |
R session information and runtime parameters |
selected_annotations.csv
| Column | Type | Description |
|---|---|---|
| stage columns | character | One column per plotted stage in original order |
sankey_lodes.csv
| Column | Type | Description |
|---|---|---|
sample_id |
character | Synthetic row identifier used as the alluvium key |
x |
character | Stage name |
stratum |
character | Category label for the stage |
Workflow
Step 1: Validate Input
- Check that the input file exists and is readable.
- Detect CSV vs TSV input.
- Validate that at least 2 stage columns are available.
- Validate that user-specified columns exist.
Step 2: Prepare Sankey Data
- Subset the selected stage columns.
- Replace missing or blank labels.
- Add a row-level
sample_ididentifier. - Convert the table with
ggalluvial::to_lodes_form().
Step 2a: Readability Advisories
After column selection, the script emits log_warn advisories when:
- More than 5 stages are selected:
"More than 5 stages selected; plot may be hard to read. Consider filtering." - A stage has more than 8 unique values:
"Stage <name> has <n> unique values; consider aggregating for readability."
These are advisory only — the script continues and produces the plot.
Step 3: Generate Visualization
- Build the Sankey/alluvial plot with
geom_flow()andgeom_stratum(). - Render stratum labels.
- Save the plot as PDF.
Step 4: Record Outputs
- Save the selected annotations and lodes-format table as CSV files.
- Save
sessionInfo()and runtime arguments for reproducibility.
Examples
Reproduce the Original Two-Column Plot
Rscript scripts/main.R \
-i tests/data/sample_annotations.csv \
-o tests/output \
-c risk,Responder
Plot Three Annotation Stages
Rscript scripts/main.R \
-i tests/data/sample_annotations.csv \
-o tests/output_three_stage \
-c risk,Responder,Subtype \
--title "Risk to response transitions"
Use All Columns Automatically
Rscript scripts/main.R \
-i tests/data/minimal_annotations.csv \
-o tests/output_all_columns
Error Handling
Common Errors
| Error | Cause | Solution |
|---|---|---|
SKILL_FILE_NOT_FOUND |
Input file does not exist | Check --input_file |
SKILL_EMPTY_DATA |
The input file has zero rows or fewer than 2 usable columns | Provide a non-empty table with at least 2 stage columns |
SKILL_MISSING_COLUMNS |
A requested stage column is absent | Correct --columns or fix the input header |
SKILL_INVALID_PARAMETER |
Width, height, alpha, label size, or output prefix is invalid | Provide valid arguments per the Arguments table |
SKILL_DEPENDENCY_MISSING |
A required R package is unavailable | Run Rscript scripts/install_dependencies.R |
SKILL_IO_ERROR |
Output directory cannot be created or written | Check permissions on --output_dir |
IF error persists, READ: references/troubleshooting.md
Testing
Test with Sample Data
Rscript scripts/install_dependencies.R
Rscript scripts/main.R --help
Rscript scripts/main.R \
-i tests/data/sample_annotations.csv \
-o tests/output \
-c risk,Responder,Subtype
Rscript tests/test_skill.R
Rscript tests/run_smoke_test.R
Validation Commands
ls -la tests/output/table
ls -la tests/output/plot
ls -la tests/output/data
References
- Brunson JC (2020) ggalluvial: Layered Grammar for Alluvial Plots. Journal of Open Source Software. doi:10.21105/joss.02017
- Wickham H (2016) ggplot2: Elegant Graphics for Data Analysis. Springer. doi:10.1007/978-3-319-24277-4
For detailed algorithm, READ: references/algorithm.md
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.