Lightgbm Analysis

Source: 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

Rscript scripts/main.R \
  --data_file <input_file> \
  --target_var <target_column> \
  --output_dir <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

Modeling Arguments

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:

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:

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

Primary result files:

• table/lightgbm_feature_importance.<output_format>
• table/lightgbm_model_metrics.<output_format>
• table/lightgbm_remediation.<output_format>
• figure/lightgbm_feature_importance_<importance_type>.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.<output_format> and table/lightgbm_feature_importance.<output_format> should exist.
• table/lightgbm_remediation.<output_format> and data/lightgbm_run_summary.txt should exist.
• figure/lightgbm_feature_importance_<importance_type>.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.