AGENT SKILL

xgboost-analysis

Use when building XGBoost models on tabular data and returning feature importance ranking outputs. Supports binary classification and regression with automatic task detection, train-test split, performance tables, feature importance ranking tables, and PNG importance plots.

License 许可
MIT
最近更新
2026-10-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
xgboost-analysis
author
AIPOCH
license
MIT
description
Use when building XGBoost models on tabular data and returning feature importance ranking outputs. Supports binary classification and regression with automatic task detection, train-test split, performance tables, feature importance ranking tables, and PNG importance plots.

02 资源文件 10

03 SKILL.md 正文

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 <input_file> \
  --target_var <target_column> \
  --task_type <auto|classification|regression> \
  --output_dir <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:

<output_dir>/
├── table/
├── figure/
└── data/

Primary outputs:

  • table/<output_prefix>_feature_importance.csv
  • table/<output_prefix>_model_performance.csv
  • figure/<output_prefix>_feature_importance_<importance_metric>.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.

04 同仓库更多 Skills

mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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.

★ 2