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
1---2name: svm-model-importance-analysis3description: Use when you need a standardized R CLI workflow to run two-class SVM-RFE feature ranking on an expression-like matrix, choose an informative feature count from cross-validated error, and generate reproducible ranking and error plots. NOT for regression, multi-class classification, missing-value imputation, or remote data fetching.4license: MIT5---6> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
7
8# SVM Model Importance Analysis
9
10## When to Read External Files
11
12| Situation | File to Read | Purpose |
13|-----------|--------------|---------|
14| Need algorithm details | `references/algorithm.md` | Explain SVM-RFE ranking, cross-validation logic, assumptions, and interpretation |
15| Need to execute the analysis | `scripts/main.R` | Run the CLI entry point with a complete `Rscript` command |
16| Encounter an error | `references/troubleshooting.md` | Map standardized error codes to causes and fixes |
17| Need CLI examples | `references/cli-guide.md` | Review installation steps and runnable CLI examples |
18| Need a runnable smoke test | `tests/data/` | Use the bundled small dataset for verification |
19
20## Usage
21
22```bash
23Rscript scripts/main.R \
24 --input_file ./input/expression_matrix.csv \
25 --group_file ./input/group_info.csv \
26 --case_group Case \
27 --control_group Control \
28 --output_dir output/basic-run \
29 --seed 42 \
30 --timeout_seconds 600
31```
32
33## Arguments
34
35| Short | Long | Type | Default | Required | Description |
36|-------|------|------|---------|----------|-------------|
37| `-i` | `--input_file` | character | none | yes, unless `--plot_only TRUE` | Expression matrix file with samples in rows and features in columns |
38| `-g` | `--group_file` | character | none | yes, unless `--plot_only TRUE` | Group file with sample IDs in the first column |
39| `-c` | `--case_group` | character | none | yes, unless `--plot_only TRUE` | Case group label |
40| `-r` | `--control_group` | character | none | yes, unless `--plot_only TRUE` | Control group label |
41| `-o` | `--output_dir` | character | `output` | yes | Output directory inside the skill root |
42| `-p` | `--plot_only` | logical | `FALSE` | no | Reuse `output_dir/data/svm_result.rds` and regenerate plots without rerunning SVM-RFE |
43| `-s` | `--seed` | integer | `42` | no | Random seed for reproducibility |
44| `-t` | `--timeout_seconds` | integer | `600` | no | Elapsed time limit for the run |
45| | `--svm_k` | integer | `10` | no | Number of stratified outer folds used for SVM-RFE and validation |
46| | `--svm_halve_above` | integer | `50` | no | If surviving features exceed this count, remove half per iteration |
47| | `--svm_max_features_cap` | integer | `30` | no | Maximum feature count evaluated on the error curve |
48| | `--svm_select_rule` | character | `min` | no | Feature-count rule: `min` or `tolerance` |
49| | `--svm_tol` | numeric | `0.01` | no | Tolerance used when `--svm_select_rule tolerance` is selected |
50| | `--svm_error_height` | numeric | `5` | no | SVM error plot height in inches |
51| | `--svm_error_width` | numeric | `6` | no | SVM error plot width in inches |
52| | `--svm_error_xlab` | character | `Number of Features` | no | X-axis label for the SVM error plot |
53| | `--svm_error_ylab` | character | `Classification Error Rate` | no | Y-axis label for the SVM error plot |
54| | `--svm_error_main_line_color` | character | `black` | no | Main line color for the SVM error plot |
55| | `--svm_error_second_line_color` | character | `#2BA2DE` | no | Baseline line color for the SVM error plot |
56| | `--svm_error_best_point_color` | character | `red` | no | Highlight color for the best feature-count point |
57| | `--svm_error_noinfo_lty` | integer | `3` | no | Line type for the no-information baseline |
58| | `--svm_error_label_cex` | numeric | `0.75` | no | Label size for the best-point annotation |
59| | `--svm_error_label_pos` | integer | `4` | no | Label position for the best-point annotation |
60| | `--svm_rank_top_n` | integer | `20` | no | Maximum number of ranked features shown in the ranking plot |
61| | `--svm_rank_width` | numeric | `7` | no | Ranking plot width in inches |
62| | `--svm_rank_height` | numeric | `6` | no | Ranking plot height in inches |
63| | `--svm_rank_color` | character | `#2BA2DE` | no | Bar color for the ranking plot |
64| | `--svm_rank_title` | character | `SVM-RFE Feature Ranking` | no | Title for the ranking plot |
65
66## Input Format
67
68### Expression Matrix
69
70- CSV or TSV.
71- First column: sample IDs.
72- Remaining columns: numeric features.
73- Samples must be rows.
74- Missing or non-numeric feature values are not allowed.
75
76Example:
77
78```csv
79sample,HIF1A,NR4A1,SOCS1
80S1,6.21,-1.34,2.01
81S2,6.57,0.37,3.62
82S3,7.05,2.12,5.01
83```
84
85### Group File
86
87- CSV or TSV.
88- First column: sample IDs.
89- One additional column must contain both the case and control labels.
90- Exactly two groups are supported.
91
92Example:
93
94```csv
95sample,group
96S1,Case
97S2,Case
98S3,Control
99```
100
101## Output Files
102
103| File | Format | Description |
104|------|--------|-------------|
105| `data/svm_result.rds` | RDS | Serialized SVM-RFE bundle with ranking results and metadata |
106| `table/svm_rfe_features.csv` | CSV | Selected ranked features using the chosen feature-count rule |
107| `table/svm_rfe_full_ranking.csv` | CSV | Full ranking table across all input features |
108| `plot/svm_rfe_error_plot.pdf` | PDF | Cross-validated classification error across feature counts |
109| `plot/svm_rfe_ranking_plot.pdf` | PDF | Bar plot of the highest-ranked SVM-RFE features |
110| `session_info.txt` | TXT | R version, platform, and package version information |
111
112## Error Handling
113
114- Successful runs exit with status code `0`.
115- Failed runs exit with status code `1`.
116- Error messages use standardized names such as `SKILL_FILE_NOT_FOUND` and `SKILL_INVALID_PARAMETER`.
117- Output paths are validated so that `--output_dir` cannot write outside the skill root.
118- The analysis never performs network requests and never executes user input through `eval()`, `exec()`, or `system()`.
119
120Common codes:
121
122| Error Code | Meaning |
123|------------|---------|
124| `SKILL_FILE_NOT_FOUND` | An input file or required plot-only artifact does not exist |
125| `SKILL_MISSING_COLUMNS` | The input file does not contain the required columns |
126| `SKILL_EMPTY_DATA` | An input file is empty or a required ranking table is unavailable |
127| `SKILL_INVALID_PARAMETER` | A CLI argument, group setting, numeric constraint, or path is invalid |
128| `SKILL_SAMPLE_MISMATCH` | Sample IDs do not match between the expression matrix and group file |
129| `SKILL_PACKAGE_NOT_FOUND` | One or more required CRAN packages are missing |
130
131For detailed fixes, READ: `references/troubleshooting.md`
132
133## Testing
134
135### Help Check
136
137```bash
138Rscript scripts/main.R --help
139```
140
141### Full Test Run
142
143```bash
144Rscript tests/run_tests.R
145```
146
147### Direct Test Command
148
149```bash
150Rscript scripts/main.R \
151 --input_file tests/data/expression_matrix.csv \
152 --group_file tests/data/group_info.csv \
153 --case_group AR \
154 --control_group Control \
155 --output_dir tests/output/manual-test \
156 --seed 42 \
157 --svm_k 4 \
158 --svm_max_features_cap 6 \
159 --svm_rank_top_n 6 \
160 --timeout_seconds 300
161```
gabrielmoreira