Gsva Analysis And Visualization

table/GSVA_diff.csv

Workflow

Step 1: Validate Input

• Check that the expression matrix and group file exist
• Validate supported columns and matching sample names
• Validate CLI ranges and mode-specific required parameters

Step 2: Run Pathway Analysis

• Load MSigDB gene sets for the requested species and collection
• Compute GSVA or ssGSEA scores for each sample
• Fit a limma model for the case-vs-control pathway comparison

Step 3: Generate Output

• Save the full score matrix, top pathway subset, and differential results to table/
• Save the reusable gsva_result object to data/GSVA_list.rda
• Generate the heatmap PDF in plot/ when running visualize or full
• Append a new section to output_manifest.txt and run_record.txt for each invocation so earlier provenance is preserved when reusing one output_dir

Examples

Basic Usage

Rscript scripts/main.R \
  --mode full \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --case_group treatment \
  --control_group control \
  --output_dir ./output

With ssGSEA and Custom Parameters

Rscript scripts/main.R \
  --mode analyze \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --case_group treatment \
  --control_group control \
  --method ssgsea \
  --top_n 30 \
  --fdr_threshold 0.1 \
  --output_dir ./ssgsea_output \
  --seed 123

Reuse a Saved Result Object

Rscript scripts/main.R \
  --mode visualize \
  --output_dir ./output \
  --plot_file custom_heatmap.pdf \
  --top_up 10 \
  --top_down 10 \
  --top_mode both

For the bundled real-data baseline record, READ: references/cli-guide.md

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 genes as rows and samples as columns
• A sample group file with one supported sample column and one supported group column
• A valid case/control comparison for pathway-level GSVA or ssGSEA analysis
• Optional heatmap customization parameters for visualization of a saved GSVA_list.rda

Privacy and data-handling note:

• If your matrix or group file can be linked to patients or protected records, anonymize it before use
• This workflow writes result tables, a saved R object, plots, and session metadata to the local output_dir
• Review local output retention practices before using sensitive material

If the user's request does not involve bulk expression pathway enrichment analysis or GSVA heatmap generation — for example, asking for single-cell analysis, gene-level DE testing, methylation analysis, or clinical diagnosis — do not proceed with this workflow. Instead respond:

"gsva-analysis-and-visualization is designed for bulk expression pathway-level GSVA/ssGSEA analysis and saved-result heatmap visualization. Your request appears to be outside this scope. Please provide a bulk expression matrix plus sample group file for GSVA/ssGSEA analysis, or use a more appropriate skill for your task."

Testing

Rscript scripts/main.R --help

Rscript tests/run_tests.R

Rscript scripts/main.R \
  --mode full \
  --input_file tests/data/expr_matrix.csv \
  --group_file tests/data/group.csv \
  --case_group Tumor \
  --control_group Healthy \
  --species "Homo sapiens" \
  --category C2 \
  --subcategory KEGG \
  --output_dir tests/output \
  --seed 42

Expected outputs:

• tests/output/table/GSVA_diff.csv
• tests/output/table/GSVA_enrichment_results.csv
• tests/output/table/GSVA_enrichment_results_topN.csv
• tests/output/data/GSVA_list.rda
• tests/output/plot/GSVA_heatmap.pdf
• tests/output/session_info.txt
• tests/output/output_manifest.txt
• tests/output/run_record.txt

Optional post-check:

Rscript tests/test_skill.R tests/output

tests/run_tests.R executes the full demo workflow, validates the expected output files, then reruns visualize in the same output_dir to confirm that output_manifest.txt and run_record.txt preserve both run sections.

References

1. Hanzelmann S, Castelo R, Guinney J. (2013) GSVA: gene set variation analysis for microarray and RNA-seq data. BMC Bioinformatics. doi:10.1186/1471-2105-14-7
2. Ritchie ME, Phipson B, Wu D, et al. (2015) limma powers differential expression analyses for RNA-sequencing and microarray studies. Nucleic Acids Research. doi:10.1093/nar/gkv007
3. Liberzon A, Birger C, Thorvaldsdottir H, et al. (2015) The Molecular Signatures Database Hallmark Gene Set Collection. Cell Systems. doi:10.1016/j.cels.2015.12.004

For detailed algorithm notes, READ: references/algorithm.md

Implementation Checklist

• CLI parsing with optparse
• set.seed() for reproducibility
• Only CRAN/Bioconductor packages
• Documented parameters match script
• get_script_dir() defined before any call to it
• File reading instructions in SKILL.md
• Test data provided in tests/data/
• Error handling implemented with SKILL_* messages
• Rscript scripts/main.R --help works