--- name: lightgbm-analysis description: Use when training a LightGBM model on tabular data in R and returning model metrics, feature importance ranking tables, and feature importance plots. license: MIT author: AIPOCH --- > **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills) # LightGBM Analysis Use this skill to build a LightGBM model on tabular data and export feature importance ranking results as both a table and a figure. ## Use This Skill When - You need a command-line LightGBM workflow written in R. - You need classification or regression on structured tabular data. - You need ranked feature importance outputs for reporting or interpretation. - You need standardized outputs under `table/`, `figure/`, and `data/`. ## Primary Command ```bash Rscript scripts/main.R \ --data_file \ --target_var \ --output_dir ``` ## Prerequisites - `Rscript` is available in the shell. - Required R packages: `optparse`, `data.table`, `lightgbm`. - Install basic dependencies with `Rscript -e 'install.packages(c("optparse", "data.table"), repos="https://cloud.r-project.org")'`. - Install the R `lightgbm` package from the LightGBM project because it is usually not available from CRAN. ## Core Arguments | Argument | Required | Description | |----------|----------|-------------| | `--data_file` | Yes | Input data file in CSV format or tab-delimited TXT/TSV format | | `--target_var` | Yes | Target column used for modeling | | `--output_dir` | No | Output directory, default `./LightGBM_Results` | | `--fail_if_output_exists` | No | Stop instead of overwriting when `output_dir` already contains files | | `--task_type` | No | `auto`, `regression`, `binary`, or `multiclass`. Default `auto` | | `--feature_cols` | No | Comma-separated feature columns. Default uses all columns except target and dropped columns | | `--drop_cols` | No | Comma-separated columns to exclude before modeling | | `--importance_type` | No | `gain` or `split`. Default `gain` | | `--top_n` | No | Number of features to show in the importance plot. Default `20` | | `--output_format` | No | `csv` or `txt` table export. Default `csv` | ## Modeling Arguments | Argument | Default | Description | |----------|---------|-------------| | `--metric` | `auto` | Evaluation metric matched to task type | | `--test_size` | `0.2` | Test-set proportion | | `--valid_size` | `0.2` | Validation proportion taken from the training partition | | `--nrounds` | `500` | Maximum boosting rounds | | `--learning_rate` | `0.05` | Shrinkage rate | | `--num_leaves` | `31` | Maximum leaf count per tree | | `--max_depth` | `-1` | Maximum tree depth, `-1` means no explicit limit | | `--min_data_in_leaf` | `5` | Minimum samples per leaf | | `--feature_fraction` | `0.8` | Column sampling ratio | | `--bagging_fraction` | `0.8` | Row sampling ratio | | `--bagging_freq` | `1` | Bagging frequency | | `--lambda_l1` | `0` | L1 regularization | | `--lambda_l2` | `0` | L2 regularization | | `--early_stopping_rounds` | `50` | Early stopping patience | | `--seed` | `42` | Random seed | ## Input Requirements - The input file must include the target column. - Prefer `.csv` or `.tsv` inputs. `.txt` files must be tab-delimited. - The skill expects at least 20 rows after removing missing target values. - Features may be numeric, integer, logical, character, or factor-like text. - Character features are label-encoded internally for LightGBM. - Missing target values are removed before modeling. - Missing feature values are left for LightGBM to handle. - If `task_type=auto`, the script infers regression or classification from the target values. Bundled test data examples: ```csv V1,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. Remove identifier or sensitive columns such as `id`, `sample_id`, `patient_id`, accession numbers, or the bundled sample identifier column `V1` before training. 3. Set `--drop_cols` and optionally `--feature_cols` so the model only sees intended predictors. 4. If you need overwrite protection, add `--fail_if_output_exists` or choose a fresh `--output_dir`. 5. Run `scripts/main.R`. 6. Check `table/` for the importance table, model metrics, and remediation guidance. 7. Check `figure/` for the feature importance ranking plot and `data/` for the run summary. Avoid ambiguous text exports. If a `.txt` file is parsed as one column, re-export it as tab-delimited text or CSV before rerunning. For quick validation in small audit environments, prefer the bundled `dt_sample3.txt` smoke test shown below with reduced `--nrounds` and `--early_stopping_rounds`. The full binary example on `dt_sample1.csv` is still useful as a complete workflow example, but it can exceed short runtime budgets. If you omit `--data_file` or `--target_var`, the script exits with `SKILL_MISSING_INPUT`. ## Outputs Expected output structure: ```text / ├── table/ ├── figure/ └── data/ ``` Primary result files: - `table/lightgbm_feature_importance.` - `table/lightgbm_model_metrics.` - `table/lightgbm_remediation.` - `figure/lightgbm_feature_importance_.pdf` - `data/lightgbm_run_summary.txt` - `data/lightgbm_categorical_levels.txt` when categorical or character predictors were encoded Feature importance table fields include: - `feature` - `gain` - `split` - `cover` - `importance_type` - `importance_value` - `rank` - `gain_share` - `split_share` Model metrics include: - `task_type` - `metric_primary` - `best_iteration` - `train_rows` - `valid_rows` - `test_rows` - `prediction_collapse_flag` - `model_quality_flag` - `interpretation_status` - `primary_issue` - `model_quality_issues` - `rerun_hint` - `model_quality_note` - task-specific evaluation metrics such as `rmse`, `mae`, `accuracy`, `auc`, or `logloss` Remediation table fields include: - `task_type` - `model_quality_flag` - `interpretation_status` - `issue_code` - `issue_detail` - `recommended_action` - `suggested_rerun_change` Run summary file includes the task type, best iteration, primary quality fields, top features, and artifact paths for the completed run. ## Overwrite Behavior - Rerunning into an existing `output_dir` replaces prior result files with the new metrics, importance table, remediation table, figure, and session metadata. - Set `--fail_if_output_exists` when you want the run to stop instead of replacing prior artifacts. - If you need an audit trail, prefer a timestamped or per-run `output_dir`. - The script now warns when `output_dir` already contains files. ## Success And Failure Contract Success: - Console output should end with `LightGBM analysis completed successfully`. - `table/lightgbm_model_metrics.` and `table/lightgbm_feature_importance.` should exist. - `table/lightgbm_remediation.` and `data/lightgbm_run_summary.txt` should exist. - `figure/lightgbm_feature_importance_.pdf` should exist. - The importance table should contain at least one non-zero `gain` or `split` value. Failure or caution: - If parsing fails, expect a `SKILL_*` message instead of a raw stack trace. - If `best_iteration <= 1`, predictions collapse to one class, `recall` is `0`, `f1` is `NA`, or the selected importance values are mostly zero, do not treat the ranking as reliable. - Review `model_quality_flag` and `model_quality_note` in `table/lightgbm_model_metrics.csv` before interpreting the exported ranking. - Use `interpretation_status` to decide whether the run is report-ready: `eligible` means interpretation-ready, `eligible_with_caveats` means the ranking may still be usable with caveats, and `caution_only` means diagnostic-only. - Review `table/lightgbm_remediation.csv` and `rerun_hint` for the exact failure mode and recommended rerun changes. - Recheck delimiter choice, identifier leakage, and `--min_data_in_leaf` before trusting the outputs. ## Caution Remediation - `best_iteration<=1`: lower `--min_data_in_leaf` and verify that the selected predictors have usable signal. - `single_predicted_class`: review class balance and feature selection before using the ranking downstream. - `recall=0` or `no_positive_predictions`: revisit `--feature_cols` and the target balance before treating the run as report-ready. - `_importance_sparse`: compare against the alternate importance type and review whether the retained predictors have enough signal. ## Agent Response Contract When this skill completes, the agent should report: - resolved `task_type` - `best_iteration` - primary evaluation metrics from `table/lightgbm_model_metrics.` - top ranked features from `table/lightgbm_feature_importance.` - `model_quality_flag` and `interpretation_status` - artifact paths for the metrics table, importance table, remediation table, figure, and run summary file If `model_quality_flag` is not `ok`, the agent must explicitly say the run is diagnostic-only or caveat-limited and include the recommended rerun changes from `rerun_hint` or `table/lightgbm_remediation.`. ## Feature Importance Guidance - Use `gain` when you care about overall contribution to loss reduction. - Use `split` when you care about how often a feature is used in tree splits. - Prefer `gain` for most ranking summaries and reports. - Low importance does not imply no business value, especially under correlated features. ## Read These Files When Needed | Need | File | |------|------| | LightGBM method details and importance interpretation | `references/algorithm.md` | | CLI examples | `references/cli-guide.md` | | Error diagnosis | `references/troubleshooting.md` | | Main entry point | `scripts/main.R` | | Sample test data | `tests/data/` | ## Quick Examples Fast smoke test with `dt_sample3.txt`: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample3.txt \ --target_var Group \ --drop_cols V1 \ --task_type binary \ --nrounds 80 \ --early_stopping_rounds 20 \ --top_n 15 \ --output_dir tests/output_smoke_txt ``` Audit-friendly binary preset for short runtime budgets: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample1.csv \ --target_var fustat \ --drop_cols V1 \ --task_type binary \ --nrounds 120 \ --early_stopping_rounds 20 \ --output_dir tests/output_binary_fast ``` Full binary workflow example with `dt_sample1.csv`: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample1.csv \ --target_var fustat \ --drop_cols V1 \ --task_type binary \ --output_dir tests/output_binary ``` Split-based importance export example with `dt_sample2.csv`: Use this to verify split-based ranking output. Review `model_quality_flag` and `interpretation_status` before treating the bundled example as report-ready because this path can remain diagnostic-only on small test splits. ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample2.csv \ --target_var fustat \ --feature_cols CAMK2N2,GGT6,GPR161,RAB26,RIBC2 \ --drop_cols V1 \ --task_type binary \ --importance_type split \ --output_dir tests/output_binary_split ``` Audit-friendly regression preset with `dt_sample1.csv` and `RIBC2` as the target: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample1.csv \ --target_var RIBC2 \ --drop_cols V1 \ --task_type regression \ --nrounds 120 \ --early_stopping_rounds 20 \ --output_dir tests/output_regression_fast ``` Full regression workflow with `dt_sample1.csv` and `RIBC2` as the target: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample1.csv \ --target_var RIBC2 \ --drop_cols V1 \ --task_type regression \ --output_dir tests/output_regression ``` Tab-delimited TXT input with automatic binary target encoding from `Group`: ```bash Rscript scripts/main.R \ --data_file tests/data/dt_sample3.txt \ --target_var Group \ --drop_cols V1 \ --task_type binary \ --top_n 15 \ --output_dir tests/output_group_txt ``` ## Validation ```bash Rscript scripts/main.R --help ``` Use the smoke test under `## Quick Examples` for a fast validation pass. After a successful run, verify that these files exist under the selected `output_dir`: - `table/lightgbm_feature_importance.csv` - `table/lightgbm_model_metrics.csv` - `table/lightgbm_remediation.csv` - `figure/lightgbm_feature_importance_.pdf` - `data/lightgbm_run_summary.txt` - `data/lightgbm_categorical_levels.txt` if categorical or character predictors were encoded ## When Not To Use - The input file is an unstructured note, JSON blob, or free-text report. - The text file delimiter is unknown and you cannot inspect or re-export it. - The table still contains sample IDs, patient IDs, accession numbers, or similar identifiers that should not be model features. - The input still contains direct identifiers or sensitive fields that you have not reviewed and removed from modeling. ## Common Errors - `SKILL_FILE_NOT_FOUND`: Input file path is wrong or inaccessible. - `SKILL_MISSING_COLUMNS`: The target or requested feature columns are missing. - `SKILL_INVALID_DATA`: Data types, target encoding, or row count are unsuitable for LightGBM. - `SKILL_DEGENERATE_MODEL`: Training finished but the exported importance table is all zero and should not be interpreted. - `SKILL_INVALID_PARAMETER`: An argument value is invalid. - `SKILL_DEPENDENCY_MISSING`: Required package such as `lightgbm` is unavailable. - `SKILL_TRAINING_FAILED`: LightGBM training failed. Before sharing exported artifacts, verify that identifier-like columns such as `V1`, sample IDs, or patient IDs were excluded from modeling and from any published tables. If `model_quality_flag` is not `ok`, treat the run as a diagnostic result rather than an interpretable ranking. If the issue is not obvious, read `references/troubleshooting.md`.