svm-model-importance-analysis

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

SVM Model Importance Analysis

When to Read External Files

Situation	File to Read	Purpose
Need algorithm details	references/algorithm.md	Explain SVM-RFE ranking, cross-validation logic, assumptions, and interpretation
Need to execute the analysis	scripts/main.R	Run the CLI entry point with a complete Rscript command
Encounter an error	references/troubleshooting.md	Map standardized error codes to causes and fixes
Need CLI examples	references/cli-guide.md	Review installation steps and runnable CLI examples
Need a runnable smoke test	tests/data/	Use the bundled small dataset for verification

Usage

Rscript scripts/main.R \
  --input_file ./input/expression_matrix.csv \
  --group_file ./input/group_info.csv \
  --case_group Case \
  --control_group Control \
  --output_dir output/basic-run \
  --seed 42 \
  --timeout_seconds 600

Arguments

Short	Long	Type	Default	Required	Description
-i	--input_file	character	none	yes, unless --plot_only TRUE	Expression matrix file with samples in rows and features in columns
-g	--group_file	character	none	yes, unless --plot_only TRUE	Group file with sample IDs in the first column
-c	--case_group	character	none	yes, unless --plot_only TRUE	Case group label
-r	--control_group	character	none	yes, unless --plot_only TRUE	Control group label
-o	--output_dir	character	output	yes	Output directory inside the skill root
-p	--plot_only	logical	FALSE	no	Reuse output_dir/data/svm_result.rds and regenerate plots without rerunning SVM-RFE
-s	--seed	integer	42	no	Random seed for reproducibility
-t	--timeout_seconds	integer	600	no	Elapsed time limit for the run
	--svm_k	integer	10	no	Number of stratified outer folds used for SVM-RFE and validation
	--svm_halve_above	integer	50	no	If surviving features exceed this count, remove half per iteration
	--svm_max_features_cap	integer	30	no	Maximum feature count evaluated on the error curve
	--svm_select_rule	character	min	no	Feature-count rule: min or tolerance
	--svm_tol	numeric	0.01	no	Tolerance used when --svm_select_rule tolerance is selected
	--svm_error_height	numeric	5	no	SVM error plot height in inches
	--svm_error_width	numeric	6	no	SVM error plot width in inches
	--svm_error_xlab	character	Number of Features	no	X-axis label for the SVM error plot
	--svm_error_ylab	character	Classification Error Rate	no	Y-axis label for the SVM error plot
	--svm_error_main_line_color	character	black	no	Main line color for the SVM error plot
	--svm_error_second_line_color	character	#2BA2DE	no	Baseline line color for the SVM error plot
	--svm_error_best_point_color	character	red	no	Highlight color for the best feature-count point
	--svm_error_noinfo_lty	integer	3	no	Line type for the no-information baseline
	--svm_error_label_cex	numeric	0.75	no	Label size for the best-point annotation
	--svm_error_label_pos	integer	4	no	Label position for the best-point annotation
	--svm_rank_top_n	integer	20	no	Maximum number of ranked features shown in the ranking plot
	--svm_rank_width	numeric	7	no	Ranking plot width in inches
	--svm_rank_height	numeric	6	no	Ranking plot height in inches
	--svm_rank_color	character	#2BA2DE	no	Bar color for the ranking plot
	--svm_rank_title	character	SVM-RFE Feature Ranking	no	Title for the ranking plot

Input Format

Expression Matrix

• CSV or TSV.
• First column: sample IDs.
• Remaining columns: numeric features.
• Samples must be rows.
• Missing or non-numeric feature values are not allowed.

Example:

sample,HIF1A,NR4A1,SOCS1
S1,6.21,-1.34,2.01
S2,6.57,0.37,3.62
S3,7.05,2.12,5.01

Group File

• CSV or TSV.
• First column: sample IDs.
• One additional column must contain both the case and control labels.
• Exactly two groups are supported.

Example:

sample,group
S1,Case
S2,Case
S3,Control

Output Files

File	Format	Description
data/svm_result.rds	RDS	Serialized SVM-RFE bundle with ranking results and metadata
table/svm_rfe_features.csv	CSV	Selected ranked features using the chosen feature-count rule
table/svm_rfe_full_ranking.csv	CSV	Full ranking table across all input features
plot/svm_rfe_error_plot.pdf	PDF	Cross-validated classification error across feature counts
plot/svm_rfe_ranking_plot.pdf	PDF	Bar plot of the highest-ranked SVM-RFE features
session_info.txt	TXT	R version, platform, and package version information

Error Handling

• Successful runs exit with status code 0.
• Failed runs exit with status code 1.
• Error messages use standardized names such as SKILL_FILE_NOT_FOUND and SKILL_INVALID_PARAMETER.
• Output paths are validated so that --output_dir cannot write outside the skill root.
• The analysis never performs network requests and never executes user input through eval(), exec(), or system().

Common codes:

Error Code	Meaning
SKILL_FILE_NOT_FOUND	An input file or required plot-only artifact does not exist
SKILL_MISSING_COLUMNS	The input file does not contain the required columns
SKILL_EMPTY_DATA	An input file is empty or a required ranking table is unavailable
SKILL_INVALID_PARAMETER	A CLI argument, group setting, numeric constraint, or path is invalid
SKILL_SAMPLE_MISMATCH	Sample IDs do not match between the expression matrix and group file
SKILL_PACKAGE_NOT_FOUND	One or more required CRAN packages are missing

For detailed fixes, READ: references/troubleshooting.md

Testing

Help Check

Rscript scripts/main.R --help

Full Test Run

Rscript tests/run_tests.R

Direct Test Command

Rscript scripts/main.R \
  --input_file tests/data/expression_matrix.csv \
  --group_file tests/data/group_info.csv \
  --case_group AR \
  --control_group Control \
  --output_dir tests/output/manual-test \
  --seed 42 \
  --svm_k 4 \
  --svm_max_features_cap 6 \
  --svm_rank_top_n 6 \
  --timeout_seconds 300