Xgboost Analysis

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

XGBoost Modeling And Feature Importance Ranking

Use this skill to train an XGBoost model from a tabular dataset and export both feature importance ranking tables and feature importance plots.

Use This Skill When

• You need a command-line XGBoost workflow in R for tabular data.
• You need a reproducible train-test split, model training, and evaluation.
• You need feature importance ranking outputs as both a table and a figure.
• You need automatic one-hot encoding for categorical predictors.
• Your data may contain a first unnamed sample ID column such as V1 that should not enter the model.

Do Not Use This Skill When

• Your classification target has more than 2 classes.
• Your input is not tabular CSV, TXT, or TSV data.
• You need causal interpretation, mechanism claims, or policy, business, or clinical conclusions.
• You only need narrative interpretation or triage of an existing result rather than model training.

Primary Command

Rscript scripts/main.R \
  --data_file  \
  --target_var  \
  --task_type  \
  --output_dir 

Prerequisites

• Rscript is available in the shell.
• Required R packages: optparse, data.table, Matrix, xgboost.
• Install missing packages with Rscript -e 'install.packages(c("optparse", "data.table", "Matrix", "xgboost"), repos="https://cloud.r-project.org")'.

Core Arguments

| Argument | Required | Description | |----------|----------|-------------| | --data_file | Yes | Input CSV, TXT, or TSV file | | --target_var | Yes | Target column used for modeling | | --task_type | No | auto, classification, or regression. Default auto | | --output_dir | No | Output directory, default ./XGBoost_Results | | --ignore_vars | No | Comma-separated columns to exclude from predictors | | --positive_class | No | Positive class label for binary classification | | --test_size | No | Test set proportion between 0 and 1, default 0.2 | | --seed | No | Random seed, default 123 | | --nrounds | No | Maximum boosting rounds, default 300 | | --max_depth | No | Tree depth, default 6 | | --eta | No | Learning rate, default 0.1 | | --subsample | No | Row sampling ratio, default 0.8 | | --colsample_bytree | No | Column sampling ratio, default 0.8 | | --min_child_weight | No | Minimum child weight, default 1 | | --gamma | No | Minimum split loss reduction, default 0 | | --lambda | No | L2 regularization, default 1 | | --alpha | No | L1 regularization, default 0 | | --early_stopping_rounds | No | Early stopping rounds, default 20 | | --importance_metric | No | gain, cover, or frequency. Default gain | | --top_n | No | Number of features to plot, default 20 | | --output_format | No | Table format: csv or txt, default csv | | --output_prefix | No | Output filename prefix, default xgboost |

Input Requirements

• The input file must contain the target column.
• Predictor columns can be numeric, integer, logical, character, or factor-like text.
• Character and factor predictors are one-hot encoded automatically.
• A first unnamed identifier column such as V1 is automatically excluded when it contains unique sample IDs.
• Rows with missing target values are removed before training.
• For classification, exactly 2 classes are required.
• For regression, the target column must be numeric.
• Each class should have at least 2 rows so both training and test sets can be created.

Example input:

,fustat,CAMK2N2,GGT6,GPR161,RAB26,RIBC2
TCGA-C5-A1M5,1,2.248291938,5.274690305,2.825215762,3.121114894,5.35318565
TCGA-EA-A5O9,0,3.346176843,5.404368414,2.604616977,0.629473197,4.429314674
TCGA-C5-A3HL,0,3.363100974,5.363314779,4.124799581,4.127228806,4.916596068

Minimal Workflow

1. Confirm the input file exists and the target column name is correct.
2. Run scripts/main.R with --data_file and --target_var.
3. Check the output directory for table/feature_importance_* and figure/feature_importance_*.

If you omit --data_file or --target_var, the script exits with SKILL_MISSING_INPUT.

Outputs

Expected output structure:

/
├── table/
├── figure/
└── data/

Primary outputs:

• table/_feature_importance.csv
• table/_model_performance.csv
• figure/_feature_importance_.png

Additional outputs:

• session_info.txt

Feature importance table fields include:

• Rank
• Feature
• Gain
• Cover
• Frequency
• SelectedMetric
• SelectedValue

Feature Importance Metrics

• gain: Average contribution to loss reduction. Recommended for most ranking use cases.
• cover: Relative sample coverage contributed by a feature.
• frequency: How often the feature is used in splits.

Read These Files When Needed

| Need | File | |------|------| | XGBoost method details and importance interpretation | references/algorithm.md | | More CLI examples | references/cli-guide.md | | Error diagnosis | references/troubleshooting.md | | Main execution entry point | scripts/main.R | | Bundled test data | tests/data/ |

Quick Examples

Auto-detected binary classification on dt_sample1.csv:

Rscript scripts/main.R \
  --data_file tests/data/dt_sample1.csv \
  --target_var fustat \
  --task_type auto \
  --output_dir tests/output_binary

Binary classification on dt_sample2.csv:

Rscript scripts/main.R \
  --data_file tests/data/dt_sample2.csv \
  --target_var fustat \
  --task_type classification \
  --importance_metric gain \
  --output_dir tests/output_gain

Character-label classification on dt_sample3.txt:

Rscript scripts/main.R \
  --data_file tests/data/dt_sample3.txt \
  --target_var Group \
  --task_type classification \
  --positive_class high \
  --top_n 15 \
  --output_dir tests/output_group

Validation

Rscript scripts/main.R --help

Rscript scripts/main.R \
  --data_file tests/data/dt_sample1.csv \
  --target_var fustat \
  --task_type classification \
  --output_dir tests/validation_output

After running analysis, verify that these files exist:

• tests/validation_output/table/xgboost_feature_importance.csv
• tests/validation_output/table/xgboost_model_performance.csv
• tests/validation_output/figure/xgboost_feature_importance_gain.png

Common Errors

• SKILL_FILE_NOT_FOUND: Input file path is wrong or inaccessible.
• SKILL_MISSING_COLUMNS: The target column is missing.
• SKILL_INVALID_DATA: Data is malformed, the target type is unsuitable, classification has more or fewer than 2 classes, or too few usable rows remain.
• SKILL_INVALID_PARAMETER: An argument value is invalid.
• SKILL_DEPENDENCY_MISSING: A required R package such as xgboost is unavailable.

If the issue is not obvious, read references/troubleshooting.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aipoch
• Source: aipoch/medical-research-skills
• License: MIT
• Homepage: https://aipoch.com/agent-skills

Install and usage instructions live in the source repository linked above.