Python API

Data Structure API

class lightgbm.Dataset(data, label=None, max_bin=None, reference=None, weight=None, group=None, init_score=None, silent=False, feature_name='auto', categorical_feature='auto', params=None, free_raw_data=True)

Bases: object

Dataset in LightGBM.

Constract Dataset.

Parameters:
data (string__, numpy array or scipy.sparse) – Data source of Dataset. If string, it represents the path to txt file.
label (list__, numpy 1-D array or None__, optional (__default=None__)) – Label of the data.
max_bin (int or None__, optional (__default=None__)) – Max number of discrete bins for features. If None, default value from parameters of CLI-version will be used.
reference (Dataset or None__, optional (__default=None__)) – If this is Dataset for validation, training data should be used as reference.
weight (list__, numpy 1-D array or None__, optional (__default=None__)) – Weight for each instance.
group (list__, numpy 1-D array or None__, optional (__default=None__)) – Group/query size for Dataset.
init_score (list__, numpy 1-D array or None__, optional (__default=None__)) – Init score for Dataset.
silent (bool__, optional (__default=False__)) – Whether to print messages during construction.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
params (dict or None__, optional (__default=None__)) – Other parameters.
free_raw_data (bool__, optional (__default=True__)) – If True, raw data is freed after constructing inner Dataset.

construct()

Lazy init.

Returns:
self – Returns self.
Return type:
Dataset

create_valid(data, label=None, weight=None, group=None, init_score=None, silent=False, params=None)

Create validation data align with current Dataset.

Parameters:
data (string__, numpy array or scipy.sparse) – Data source of Dataset. If string, it represents the path to txt file.
label (list or numpy 1-D array__, optional (__default=None__)) – Label of the training data.
weight (list__, numpy 1-D array or None__, optional (__default=None__)) – Weight for each instance.
group (list__, numpy 1-D array or None__, optional (__default=None__)) – Group/query size for Dataset.
init_score (list__, numpy 1-D array or None__, optional (__default=None__)) – Init score for Dataset.
silent (bool__, optional (__default=False__)) – Whether to print messages during construction.
params (dict or None__, optional (__default=None__)) – Other parameters.
Returns:
self – Returns self
Return type:
Dataset

get_field(field_name)

Get property from the Dataset.

Parameters:
field_name (string) – The field name of the information.
Returns:
info – A numpy array with information from the Dataset.
Return type:
numpy array

get_group()

Get the group of the Dataset.

Returns:
group – Group size of each group.
Return type:
numpy array

get_init_score()

Get the initial score of the Dataset.

Returns:
init_score – Init score of Booster.
Return type:
numpy array

get_label()

Get the label of the Dataset.

Returns:
label – The label information from the Dataset.
Return type:
numpy array

get_ref_chain(ref_limit=100)

Get a chain of Dataset objects, starting with r, then going to r.reference if exists, then to r.reference.reference, etc. until we hit ref_limit or a reference loop.

Parameters:
ref_limit (int__, optional (__default=100__)) – The limit number of references.
Returns:
ref_chain – Chain of references of the Datasets.
Return type:
set of Dataset

get_weight()

Get the weight of the Dataset.

Returns:
weight – Weight for each data point from the Dataset.
Return type:
numpy array

num_data()

Get the number of rows in the Dataset.

Returns:
number_of_rows – The number of rows in the Dataset.
Return type:
int

num_feature()

Get the number of columns (features) in the Dataset.

Returns:
number_of_columns – The number of columns (features) in the Dataset.
Return type:
int

save_binary(filename)

Save Dataset to binary file.

Parameters:
filename (string) – Name of the output file.

set_categorical_feature(categorical_feature)

Set categorical features.

Parameters:
categorical_feature (list of int or strings) – Names or indices of categorical features.

set_feature_name(feature_name)

Set feature name.

Parameters:
feature_name (list of strings) – Feature names.

set_field(field_name, data)

Set property into the Dataset.

Parameters:
field_name (string) – The field name of the information.
data (list__, numpy array or None) – The array of data to be set.

set_group(group)

Set group size of Dataset (used for ranking).

Parameters:
group (list__, numpy array or None) – Group size of each group.

set_init_score(init_score)

Set init score of Booster to start from.

Parameters:
init_score (list__, numpy array or None) – Init score for Booster.

set_label(label)

Set label of Dataset

Parameters:
label (list__, numpy array or None) – The label information to be set into Dataset.

set_reference(reference)

Set reference Dataset.

Parameters:
reference (Dataset) – Reference that is used as a template to consturct the current Dataset.

set_weight(weight)

Set weight of each instance.

Parameters:
weight (list__, numpy array or None) – Weight to be set for each data point.

subset(used_indices, params=None)

Get subset of current Dataset.

Parameters:
used_indices (list of int) – Indices used to create the subset.
params (dict or None__, optional (__default=None__)) – Other parameters.
Returns:
subset – Subset of the current Dataset.
Return type:
Dataset

class lightgbm.Booster(params=None, train_set=None, model_file=None, silent=False)

Bases: object

Booster in LightGBM.

Initialize the Booster.

Parameters:
params (dict or None__, optional (__default=None__)) – Parameters for Booster.
train_set (Dataset or None__, optional (__default=None__)) – Training dataset.
model_file (string or None__, optional (__default=None__)) – Path to the model file.
silent (bool__, optional (__default=False__)) – Whether to print messages during construction.

add_valid(data, name)

Add validation data.

Parameters:
data (Dataset) – Validation data.
name (string) – Name of validation data.

attr(key)

Get attribute string from the Booster.

Parameters:
key (string) – The name of the attribute.
Returns:
value – The attribute value. Returns None if attribute do not exist.
Return type:
string or None

current_iteration()

Get the index of the current iteration.

Returns:
cur_iter – The index of the current iteration.
Return type:
int

dump_model(num_iteration=-1)

Dump Booster to json format.

Parameters:
num_iteration (int__, optional (__default=-1__)) – Index of the iteration that should to dumped. If <0, the best iteration (if exists) is dumped.
Returns:
json_repr – Json format of Booster.
Return type:
dict

eval(data, name, feval=None)

Evaluate for data.

Parameters:
data (Dataset) – Data for the evaluating.
name (string) – Name of the data.
feval (callable or None__, optional (__default=None__)) – Custom evaluation function.
Returns:
result – List with evaluation results.
Return type:
list

eval_train(feval=None)

Evaluate for training data.

Parameters:
feval (callable or None__, optional (__default=None__)) – Custom evaluation function.
Returns:
result – List with evaluation results.
Return type:
list

eval_valid(feval=None)

Evaluate for validation data.

Parameters:
feval (callable or None__, optional (__default=None__)) – Custom evaluation function.
Returns:
result – List with evaluation results.
Return type:
list

feature_importance(importance_type='split', iteration=-1)

Get feature importances.

Parameters:
importance_type (string__, optional (__default="split"__)) – How the importance is calculated. If “split”, result contains numbers of times the feature is used in a model. If “gain”, result contains total gains of splits which use the feature.
Returns:
result – Array with feature importances.
Return type:
numpy array

feature_name()

Get names of features.

Returns:
result – List with names of features.
Return type:
list

free_dataset()

Free Booster’s Datasets.

free_network()

Free Network.

get_leaf_output(tree_id, leaf_id)

Get the output of a leaf.

Parameters:
tree_id (int) – The index of the tree.
leaf_id (int) – The index of the leaf in the tree.
Returns:
result – The output of the leaf.
Return type:
float

num_feature()

Get number of features.

Returns:
num_feature – The number of features.
Return type:
int

predict(data, num_iteration=-1, raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False, is_reshape=True, pred_parameter=None)

Make a prediction.

Parameters:
data (string__, numpy array or scipy.sparse) – Data source for prediction. If string, it represents the path to txt file.
num_iteration (int__, optional (__default=-1__)) – Iteration used for prediction. If <0, the best iteration (if exists) is used for prediction.
raw_score (bool__, optional (__default=False__)) – Whether to predict raw scores.
pred_leaf (bool__, optional (__default=False__)) – Whether to predict leaf index.
pred_contrib (bool__, optional (__default=False__)) – Whether to predict feature contributions.
data_has_header (bool__, optional (__default=False__)) – Whether the data has header. Used only if data is string.
is_reshape (bool__, optional (__default=True__)) – If True, result is reshaped to [nrow, ncol].
pred_parameter (dict or None__, optional (__default=None__)) – Other parameters for the prediction.
Returns:
result – Prediction result.
Return type:
numpy array

reset_parameter(params)

Reset parameters of Booster.

Parameters:
params (dict) – New parameters for Booster.

rollback_one_iter()

Rollback one iteration.

save_model(filename, num_iteration=-1)

Save Booster to file.

Parameters:
filename (string) – Filename to save Booster.
num_iteration (int__, optional (__default=-1__)) – Index of the iteration that should to saved. If <0, the best iteration (if exists) is saved.

set_attr(**kwargs)

Set the attribute of the Booster.

Parameters:
kwargs – The attributes to set. Setting a value to None deletes an attribute. |

set_network(machines, local_listen_port=12400, listen_time_out=120, num_machines=1)

Set the network configuration.

Parameters:
machines (list__, set or string) – Names of machines.
local_listen_port (int__, optional (__default=12400__)) – TCP listen port for local machines.
listen_time_out (int__, optional (__default=120__)) – Socket time-out in minutes.
num_machines (int__, optional (__default=1__)) – The number of machines for parallel learning application.

set_train_data_name(name)

Set the name to the training Dataset.

Parameters:
name (string) – Name for training Dataset.

update(train_set=None, fobj=None)

Update for one iteration.

Parameters:
- train_set (Dataset or None__, optional (__default=None__)) – Training data. If None, last training data is used.
- fobj (callable or None__, optional (__default=None__)) – Customized objective function. For multi-class task, the score is group by class_id first, then group by row_id. If you want to get i-th row score in j-th class, the access way is score[j * num_data + i] and you should group grad and hess in this way as well.
Returns:
- is_finished – Whether the update was successfully finished.
Return type:
- bool

Training API

lightgbm.train(params, train_set, num_boost_round=100, valid_sets=None, valid_names=None, fobj=None, feval=None, init_model=None, feature_name='auto', categorical_feature='auto', early_stopping_rounds=None, evals_result=None, verbose_eval=True, learning_rates=None, keep_training_booster=False, callbacks=None)

Perform the training with given parameters.

Parameters:
- params (dict) – Parameters for training.
- train_set (Dataset) – Data to be trained.
- num_boost_round (int__, optional (__default=100__)) – Number of boosting iterations.
- valid_sets (list of Datasets or None__, optional (__default=None__)) – List of data to be evaluated during training.
- valid_names (list of string or None__, optional (__default=None__)) – Names of valid_sets.
- fobj (callable or None__, optional (__default=None__)) – Customized objective function.
- feval (callable or None__, optional (__default=None__)) – Customized evaluation function. Note: should return (eval_name, eval_result, is_higher_better) or list of such tuples.
- init_model (string or None__, optional (__default=None__)) – Filename of LightGBM model or Booster instance used for continue training.
- feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
- categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
- early_stopping_rounds (int or None__, optional (__default=None__)) – Activates early stopping. The model will train until the validation score stops improving. Requires at least one validation data and one metric. If there’s more than one, will check all of them. If early stopping occurs, the model will add best_iteration field.
- evals_result (dict or None__, optional (__default=None__)) – This dictionary used to store all evaluation results of all the items in valid_sets. Example With a valid_sets = [valid_set, train_set], valid_names = [‘eval’, ‘train’] and a params = (‘metric’:’logloss’) returns: {‘train’: {‘logloss’: [‘0.48253’, ‘0.35953’, …]}, ‘eval’: {‘logloss’: [‘0.480385’, ‘0.357756’, …]}}.
- verbose_eval (bool or int__, optional (__default=True__)) – Requires at least one validation data. If True, the eval metric on the valid set is printed at each boosting stage. If int, the eval metric on the valid set is printed at every verbose_eval boosting stage. The last boosting stage or the boosting stage found by using early_stopping_rounds is also printed. Example With verbose_eval = 4 and at least one item in evals, an evaluation metric is printed every 4 (instead of 1) boosting stages.
- learning_rates (list__, callable or None__, optional (__default=None__)) – List of learning rates for each boosting round or a customized function that calculates learning_rate in terms of current number of round (e.g. yields learning rate decay).
- keep_training_booster (bool__, optional (__default=False__)) – Whether the returned Booster will be used to keep training. If False, the returned value will be converted into _InnerPredictor before returning. You can still use _InnerPredictor as init_model for future continue training.
- callbacks (list of callables or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
- booster – The trained Booster model.
Return type:
- Booster

lightgbm.cv(params, train_set, num_boost_round=10, folds=None, nfold=5, stratified=True, shuffle=True, metrics=None, fobj=None, feval=None, init_model=None, feature_name='auto', categorical_feature='auto', early_stopping_rounds=None, fpreproc=None, verbose_eval=None, show_stdv=True, seed=0, callbacks=None)

Perform the cross-validation with given paramaters.

Parameters:
params (dict) – Parameters for Booster.
train_set (Dataset) – Data to be trained on.
num_boost_round (int__, optional (__default=10__)) – Number of boosting iterations.
folds (a generator or iterator of (__train_idx__, test_idx__) tuples or None__, optional (__default=None__)) – The train and test indices for the each fold. This argument has highest priority over other data split arguments.
nfold (int__, optional (__default=5__)) – Number of folds in CV.
stratified (bool__, optional (__default=True__)) – Whether to perform stratified sampling.
shuffle (bool__, optional (__default=True__)) – Whether to shuffle before splitting data.
metrics (string__, list of strings or None__, optional (__default=None__)) – Evaluation metrics to be monitored while CV. If not None, the metric in params will be overridden.
fobj (callable or None__, optional (__default=None__)) – Custom objective function.
feval (callable or None__, optional (__default=None__)) – Custom evaluation function.
init_model (string or None__, optional (__default=None__)) – Filename of LightGBM model or Booster instance used for continue training.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
early_stopping_rounds (int or None__, optional (__default=None__)) – Activates early stopping. CV error needs to decrease at least every early_stopping_rounds round(s) to continue. Last entry in evaluation history is the one from best iteration.
fpreproc (callable or None__, optional (__default=None__)) – Preprocessing function that takes (dtrain, dtest, params) and returns transformed versions of those.
verbose_eval (bool__, int__, or None__, optional (__default=None__)) – Whether to display the progress. If None, progress will be displayed when np.ndarray is returned. If True, progress will be displayed at every boosting stage. If int, progress will be displayed at every given verbose_eval boosting stage.
show_stdv (bool__, optional (__default=True__)) – Whether to display the standard deviation in progress. Results are not affected by this parameter, and always contains std.
seed (int__, optional (__default=0__)) – Seed used to generate the folds (passed to numpy.random.seed).
callbacks (list of callables or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
eval_hist – Evaluation history. The dictionary has the following format: {‘metric1-mean’: [values], ‘metric1-stdv’: [values], ‘metric2-mean’: [values], ‘metric1-stdv’: [values], …}.
Return type:
dict

Scikit-learn API

class lightgbm.LGBMModel(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000, objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

Bases: object

Implementation of the scikit-learn API for LightGBM.

Construct a gradient boosting model.

Parameters:
- boosting_type (string__, optional (__default="gbdt"__)) – ‘gbdt’, traditional Gradient Boosting Decision Tree. ‘dart’, Dropouts meet Multiple Additive Regression Trees. ‘goss’, Gradient-based One-Side Sampling. ‘rf’, Random Forest.
- num_leaves (int__, optional (__default=31__)) – Maximum tree leaves for base learners.
- max_depth (int__, optional (__default=-1__)) – Maximum tree depth for base learners, -1 means no limit.
- learning_rate (float__, optional (__default=0.1__)) – Boosting learning rate.
- n_estimators (int__, optional (__default=10__)) – Number of boosted trees to fit.
- max_bin (int__, optional (__default=255__)) – Number of bucketed bins for feature values.
- subsample_for_bin (int__, optional (__default=50000__)) – Number of samples for constructing bins.
- objective (string__, callable or None__, optional (__default=None__)) – Specify the learning task and the corresponding learning objective or a custom objective function to be used (see note below). default: ‘regression’ for LGBMRegressor, ‘binary’ or ‘multiclass’ for LGBMClassifier, ‘lambdarank’ for LGBMRanker.
- min_split_gain (float__, optional (__default=0.__)) – Minimum loss reduction required to make a further partition on a leaf node of the tree.
- min_child_weight (float__, optional (__default=1e-3__)) – Minimum sum of instance weight(hessian) needed in a child(leaf).
- min_child_samples (int__, optional (__default=20__)) – Minimum number of data need in a child(leaf).
- subsample (float__, optional (__default=1.__)) – Subsample ratio of the training instance.
- subsample_freq (int__, optional (__default=1__)) – Frequence of subsample, <=0 means no enable.
- colsample_bytree (float__, optional (__default=1.__)) – Subsample ratio of columns when constructing each tree.
- reg_alpha (float__, optional (__default=0.__)) – L1 regularization term on weights.
- reg_lambda (float__, optional (__default=0.__)) – L2 regularization term on weights.
- random_state (int or None__, optional (__default=None__)) – Random number seed. Will use default seeds in c++ code if set to None.
- n_jobs (int__, optional (__default=-1__)) – Number of parallel threads.
- silent (bool__, optional (__default=True__)) – Whether to print messages while running boosting.
- *kwargs* (other parameters) – Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters. Note kwargs is not supported in sklearn, it may cause unexpected issues.

n_features_

int – The number of features of fitted model.

classes_

array of shape = [n_classes] – The class label array (only for classification problem).

n_classes_

int – The number of classes (only for classification problem).

best_score_

dict or None – The best score of fitted model.

best_iteration_

int or None – The best iteration of fitted model if early_stopping_rounds has been specified.

objective_

string or callable – The concrete objective used while fitting this model.

booster_

Booster – The underlying Booster of this model.

evals_result_

dict or None – The evaluation results if early_stopping_rounds has been specified.

feature_importances_

array of shape = [n_features] – The feature importances (the higher, the more important the feature).

Note

A custom objective function can be provided for the objective parameter. In this case, it should have the signature objective(y_true, y_pred) -> grad, hess or objective(y_true, y_pred, group) -> grad, hess:

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The predicted values.

group: array-like

Group/query data, used for ranking task.

grad: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the gradient for each sample point.

hess: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the second derivative for each sample point.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i] and you should group grad and hess in this way as well.

apply(X, num_iteration=0)

Return the predicted leaf every tree for each sample.

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input features matrix.
num_iteration (int__, optional (__default=0__)) – Limit number of iterations in the prediction; defaults to 0 (use all trees).
Returns:
X_leaves – The predicted leaf every tree for each sample.
Return type:
array-like of shape = [n_samples, n_trees]

best_iteration_

Get the best iteration of fitted model.

best_score_

Get the best score of fitted model.

booster_

Get the underlying lightgbm Booster of this model.

evals_result_

Get the evaluation results.

feature_importances_

Get feature importances.

Note

Feature importance in sklearn interface used to normalize to 1, it’s deprecated after 2.0.4 and same as Booster.feature_importance() now.

fit(X, y, sample_weight=None, init_score=None, group=None, eval_set=None, eval_names=None, eval_sample_weight=None, eval_init_score=None, eval_group=None, eval_metric=None, early_stopping_rounds=None, verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None)

Build a gradient boosting model from the training set (X, y).

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input feature matrix.
y (array-like of shape = [__n_samples__]) – The target values (class labels in classification, real numbers in regression).
sample_weight (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Weights of training data.
init_score (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Init score of training data.
group (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Group data of training data.
eval_set (list or None__, optional (__default=None__)) – A list of (X, y) tuple pairs to use as a validation sets for early-stopping.
eval_names (list of strings or None__, optional (__default=None__)) – Names of eval_set.
eval_sample_weight (list of arrays or None__, optional (__default=None__)) – Weights of eval data.
eval_init_score (list of arrays or None__, optional (__default=None__)) – Init score of eval data.
eval_group (list of arrays or None__, optional (__default=None__)) – Group data of eval data.
eval_metric (string__, list of strings__, callable or None__, optional (__default=None__)) – If string, it should be a built-in evaluation metric to use. If callable, it should be a custom evaluation metric, see note for more details.
early_stopping_rounds (int or None__, optional (__default=None__)) – Activates early stopping. The model will train until the validation score stops improving. Validation error needs to decrease at least every early_stopping_rounds round(s) to continue training.
verbose (bool__, optional (__default=True__)) – If True and an evaluation set is used, writes the evaluation progress.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
callbacks (list of callback functions or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
self – Returns self.
Return type:
object Note Custom eval function expects a callable with following functions: func(y_true, y_pred), func(y_true, y_pred, weight) or func(y_true, y_pred, weight, group). Returns (eval_name, eval_result, is_bigger_better) or list of (eval_name, eval_result, is_bigger_better)

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class)

The predicted values.

weight: array-like of shape = [n_samples]

The weight of samples.

group: array-like

Group/query data, used for ranking task.

eval_name: str

The name of evaluation.

eval_result: float

The eval result.

is_bigger_better: bool

Is eval result bigger better, e.g. AUC is bigger_better.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].

n_features_

Get the number of features of fitted model.

objective_

Get the concrete objective used while fitting this model.

predict(X, raw_score=False, num_iteration=0)

Return the predicted value for each sample.

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input features matrix.
raw_score (bool__, optional (__default=False__)) – Whether to predict raw scores.
num_iter ation (int__, optional (__default=0__)) – Limit number of iterations in the prediction; defaults to 0 (use all trees).
Returns:
predicted_result – The predicted values.
Return type:
array-like of shape = [n_samples] or shape = [n_samples, n_classes]

class lightgbm.LGBMClassifier(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000, objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

Bases: lightgbm.sklearn.LGBMModel, object

LightGBM classifier.

Construct a gradient boosting model.

Parameters:
- boosting_type (string__, optional (__default="gbdt"__)) – ‘gbdt’, traditional Gradient Boosting Decision Tree. ‘dart’, Dropouts meet Multiple Additive Regression Trees. ‘goss’, Gradient-based One-Side Sampling. ‘rf’, Random Forest.
- num_leaves (int__, optional (__default=31__)) – Maximum tree leaves for base learners.
- max_depth (int__, optional (__default=-1__)) – Maximum tree depth for base learners, -1 means no limit.
- learning_rate (float__, optional (__default=0.1__)) – Boosting learning rate.
- n_estimators (int__, optional (__default=10__)) – Number of boosted trees to fit.
- max_bin (int__, optional (__default=255__)) – Number of bucketed bins for feature values.
- subsample_for_bin (int__, optional (__default=50000__)) – Number of samples for constructing bins.
- objective (string__, callable or None__, optional (__default=None__)) – Specify the learning task and the corresponding learning objective or a custom objective function to be used (see note below). default: ‘regression’ for LGBMRegressor, ‘binary’ or ‘multiclass’ for LGBMClassifier, ‘lambdarank’ for LGBMRanker.
- min_split_gain (float__, optional (__default=0.__)) – Minimum loss reduction required to make a further partition on a leaf node of the tree.
- min_child_weight (float__, optional (__default=1e-3__)) – Minimum sum of instance weight(hessian) needed in a child(leaf).
- min_child_samples (int__, optional (__default=20__)) – Minimum number of data need in a child(leaf).
- subsample (float__, optional (__default=1.__)) – Subsample ratio of the training instance.
- subsample_freq (int__, optional (__default=1__)) – Frequence of subsample, <=0 means no enable.
- colsample_bytree (float__, optional (__default=1.__)) – Subsample ratio of columns when constructing each tree.
- reg_alpha (float__, optional (__default=0.__)) – L1 regularization term on weights.
- reg_lambda (float__, optional (__default=0.__)) – L2 regularization term on weights.
- random_state (int or None__, optional (__default=None__)) – Random number seed. Will use default seeds in c++ code if set to None.
- n_jobs (int__, optional (__default=-1__)) – Number of parallel threads.
- silent (bool__, optional (__default=True__)) – Whether to print messages while running boosting.
- *kwargs* (other parameters) – Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters. Note kwargs is not supported in sklearn, it may cause unexpected issues.

n_features_

int – The number of features of fitted model.

classes_

array of shape = [n_classes] – The class label array (only for classification problem).

n_classes_

int – The number of classes (only for classification problem).

best_score_

dict or None – The best score of fitted model.

best_iteration_

int or None – The best iteration of fitted model if early_stopping_rounds has been specified.

objective_

string or callable – The concrete objective used while fitting this model.

booster_

Booster – The underlying Booster of this model.

evals_result_

dict or None – The evaluation results if early_stopping_rounds has been specified.

feature_importances_

array of shape = [n_features] – The feature importances (the higher, the more important the feature).

Note

A custom objective function can be provided for the objective parameter. In this case, it should have the signature objective(y_true, y_pred) -> grad, hess or objective(y_true, y_pred, group) -> grad, hess:

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The predicted values.

group: array-like

Group/query data, used for ranking task.

grad: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the gradient for each sample point.

hess: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the second derivative for each sample point.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i] and you should group grad and hess in this way as well.

classes_

Get the class label array.

fit(X, y, sample_weight=None, init_score=None, eval_set=None, eval_names=None, eval_sample_weight=None, eval_init_score=None, eval_metric='logloss', early_stopping_rounds=None, verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None)

Build a gradient boosting model from the training set (X, y).

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input feature matrix.
y (array-like of shape = [__n_samples__]) – The target values (class labels in classification, real numbers in regression).
sample_weight (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Weights of training data.
init_score (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Init score of training data.
group (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Group data of training data.
eval_set (list or None__, optional (__default=None__)) – A list of (X, y) tuple pairs to use as a validation sets for early-stopping.
eval_names (list of strings or None__, optional (__default=None__)) – Names of eval_set.
eval_sample_weight (list of arrays or None__, optional (__default=None__)) – Weights of eval data.
eval_init_score (list of arrays or None__, optional (__default=None__)) – Init score of eval data.
eval_group (list of arrays or None__, optional (__default=None__)) – Group data of eval data.
eval_metric (string__, list of strings__, callable or None__, optional (__default="logloss"__)) – If string, it should be a built-in evaluation metric to use. If callable, it should be a custom evaluation metric, see note for more details.
early_stopping_rounds (int or None__, optional (__default=None__)) – Activates early stopping. The model will train until the validation score stops improving. Validation error needs to decrease at least every early_stopping_rounds round(s) to continue training.
verbose (bool__, optional (__default=True__)) – If True and an evaluation set is used, writes the evaluation progress.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
callbacks (list of callback functions or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
self – Returns self.
Return type:
object

Note

Custom eval function expects a callable with following functions: func(y_true, y_pred), func(y_true, y_pred, weight) or func(y_true, y_pred, weight, group). Returns (eval_name, eval_result, is_bigger_better) or list of (eval_name, eval_result, is_bigger_better)

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class)

The predicted values.

weight: array-like of shape = [n_samples]

The weight of samples.

group: array-like

Group/query data, used for ranking task.

eval_name: str

The name of evaluation.

eval_result: float

The eval result.

is_bigger_better: bool

Is eval result bigger better, e.g. AUC is bigger_better.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].

n_classes_

Get the number of classes.

predict_proba(X, raw_score=False, num_iteration=0)

Return the predicted probability for each class for each sample.

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input features matrix.
raw_score (bool__, optional (__default=False__)) – Whether to predict raw scores.
num_iteration (int__, optional (__default=0__)) – Limit number of iterations in the prediction; defaults to 0 (use all trees).
Returns:
predicted_probability – The predicted probability for each class for each sample.
Return type:
array-like of shape = [n_samples, n_classes]

class lightgbm.LGBMRegressor(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000, objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

Bases: lightgbm.sklearn.LGBMModel, object

LightGBM regressor.

Construct a gradient boosting model.

Parameters:
- boosting_type (string__, optional (__default="gbdt"__)) – ‘gbdt’, traditional Gradient Boosting Decision Tree. ‘dart’, Dropouts meet Multiple Additive Regression Trees. ‘goss’, Gradient-based One-Side Sampling. ‘rf’, Random Forest.
- num_leaves (int__, optional (__default=31__)) – Maximum tree leaves for base learners.
- max_depth (int__, optional (__default=-1__)) – Maximum tree depth for base learners, -1 means no limit.
- learning_rate (float__, optional (__default=0.1__)) – Boosting learning rate.
- n_estimators (int__, optional (__default=10__)) – Number of boosted trees to fit.
- max_bin (int__, optional (__default=255__)) – Number of bucketed bins for feature values.
- subsample_for_bin (int__, optional (__default=50000__)) – Number of samples for constructing bins.
- objective (string__, callable or None__, optional (__default=None__)) – Specify the learning task and the corresponding learning objective or a custom objective function to be used (see note below). default: ‘regression’ for LGBMRegressor, ‘binary’ or ‘multiclass’ for LGBMClassifier, ‘lambdarank’ for LGBMRanker.
- min_split_gain (float__, optional (__default=0.__)) – Minimum loss reduction required to make a further partition on a leaf node of the tree.
- min_child_weight (float__, optional (__default=1e-3__)) – Minimum sum of instance weight(hessian) needed in a child(leaf).
- min_child_samples (int__, optional (__default=20__)) – Minimum number of data need in a child(leaf).
- subsample (float__, optional (__default=1.__)) – Subsample ratio of the training instance.
- subsample_freq (int__, optional (__default=1__)) – Frequence of subsample, <=0 means no enable.
- colsample_bytree (float__, optional (__default=1.__)) – Subsample ratio of columns when constructing each tree.
- reg_alpha (float__, optional (__default=0.__)) – L1 regularization term on weights.
- reg_lambda (float__, optional (__default=0.__)) – L2 regularization term on weights.
- random_state (int or None__, optional (__default=None__)) – Random number seed. Will use default seeds in c++ code if set to None.
- n_jobs (int__, optional (__default=-1__)) – Number of parallel threads.
- silent (bool__, optional (__default=True__)) – Whether to print messages while running boosting.
- *kwargs* (other parameters) – Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters. Note kwargs is not supported in sklearn, it may cause unexpected issues.

n_features_

int – The number of features of fitted model.

classes_

array of shape = [n_classes] – The class label array (only for classification problem).

n_classes_

int – The number of classes (only for classification problem).

best_score_

dict or None – The best score of fitted model.

best_iteration_

int or None – The best iteration of fitted model if early_stopping_rounds has been specified.

objective_

string or callable – The concrete objective used while fitting this model.

booster_

Booster – The underlying Booster of this model.

evals_result_

dict or None – The evaluation results if early_stopping_rounds has been specified.

feature_importances_

array of shape = [n_features] – The feature importances (the higher, the more important the feature).

Note

A custom objective function can be provided for the objective parameter. In this case, it should have the signature objective(y_true, y_pred) -> grad, hess or objective(y_true, y_pred, group) -> grad, hess:

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The predicted values.

group: array-like

Group/query data, used for ranking task.

grad: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the gradient for each sample point.

hess: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the second derivative for each sample point.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i] and you should group grad and hess in this way as well.

fit(X, y, sample_weight=None, init_score=None, eval_set=None, eval_names=None, eval_sample_weight=None, eval_init_score=None, eval_metric='l2', early_stopping_rounds=None, verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None)

Build a gradient boosting model from the training set (X, y).

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input feature matrix.
y (array-like of shape = [__n_samples__]) – The target values (class labels in classification, real numbers in regression).
sample_weight (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Weights of training data.
init_score (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Init score of training data.
group (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Group data of training data.
eval_set (list or None__, optional (__default=None__)) – A list of (X, y) tuple pairs to use as a validation sets for early-stopping.
eval_names (list of strings or None__, optional (__default=None__)) – Names of eval_set.
eval_sample_weight (list of arrays or None__, optional (__default=None__)) – Weights of eval data.
eval_init_score (list of arrays or None__, optional (__default=None__)) – Init score of eval data.
eval_group (list of arrays or None__, optional (__default=None__)) – Group data of eval data.
eval_metric (string__, list of strings__, callable or None__, optional (__default="l2"__)) – If string, it should be a built-in evaluation metric to use. If callable, it should be a custom evaluation metric, see note for more details.
early_stopping_rounds (int or None__, optional (__default=None__)) – A ctivates early stopping. The model will train until the validation score stops improving. Validation error needs to decrease at least every early_stopping_rounds round(s) to continue training.
verbose (bool__, optional (__default=True__)) – If True and an evaluation set is used, writes the evaluation progress.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
callbacks (list of callback functions or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
self – Returns self.
Return type:
object

Note

Custom eval function expects a callable with following functions: func(y_true, y_pred), func(y_true, y_pred, weight) or func(y_true, y_pred, weight, group). Returns (eval_name, eval_result, is_bigger_better) or list of (eval_name, eval_result, is_bigger_better)

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class)

The predicted values.

weight: array-like of shape = [n_samples]

The weight of samples.

group: array-like

Group/query data, used for ranking task.

eval_name: str

The name of evaluation.

eval_result: float

The eval result.

is_bigger_better: bool

Is eval result bigger better, e.g. AUC is bigger_better.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].

class lightgbm.LGBMRanker(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000, objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

Bases: lightgbm.sklearn.LGBMModel

LightGBM ranker.

Construct a gradient boosting model.

Parameters:
- boosting_type (string__, optional (__default="gbdt"__)) – ‘gbdt’, traditional Gradient Boosting Decision Tree. ‘dart’, Dropouts meet Multiple Additive Regression Trees. ‘goss’, Gradient-based One-Side Sampling. ‘rf’, Random Forest.
- num_leaves (int__, optional (__default=31__)) – Maximum tree leaves for base learners.
- max_depth (int__, optional (__default=-1__)) – Maximum tree depth for base learners, -1 means no limit.
- learning_rate (float__, optional (__default=0.1__)) – Boosting learning rate.
- n_estimators (int__, optional (__default=10__)) – Number of boosted trees to fit.
- max_bin (int__, optional (__default=255__)) – Number of bucketed bins for feature values.
- subsample_for_bin (int__, optional (__default=50000__)) – Number of samples for constructing bins.
- objective (string__, callable or None__, optional (__default=None__)) – Specify the learning task and the corresponding learning objective or a custom objective function to be used (see note below). default: ‘regression’ for LGBMRegressor, ‘binary’ or ‘multiclass’ for LGBMClassifier, ‘lambdarank’ for LGBMRanker.
- min_split_gain (float__, optional (__default=0.__)) – Minimum loss reduction required to make a further partition on a leaf node of the tree.
- min_child_weight (float__, optional (__default=1e-3__)) – Minimum sum of instance weight(hessian) needed in a child(leaf).
- min_child_samples (int__, optional (__default=20__)) – Minimum number of data need in a child(leaf).
- subsample (float__, optional (__default=1.__)) – Subsample ratio of the training instance.
- subsample_freq (int__, optional (__default=1__)) – Frequence of subsample, <=0 means no enable.
- colsample_bytree (float__, optional (__default=1.__)) – Subsample ratio of columns when constructing each tree.
- reg_alpha (float__, optional (__default=0.__)) – L1 regularization term on weights.
- reg_lambda (float__, optional (__default=0.__)) – L2 regularization term on weights.
- random_state (int or None__, optional (__default=None__)) – Random number seed. Will use default seeds in c++ code if set to None.
- n_jobs (int__, optional (__default=-1__)) – Number of parallel threads.
- silent (bool__, optional (__default=True__)) – Whether to print messages while running boosting.
- *kwargs* (other parameters) – Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters. Note kwargs is not supported in sklearn, it may cause unexpected issues.

n_features_

int – The number of features of fitted model.

classes_

array of shape = [n_classes] – The class label array (only for classification problem).

n_classes_

int – The number of classes (only for classification problem).

best_score_

dict or None – The best score of fitted model.

best_iteration_

int or None – The best iteration of fitted model if early_stopping_rounds has been specified.

objective_

string or callable – The concrete objective used while fitting this model.

booster_

Booster – The underlying Booster of this model.

evals_result_

dict or None – The evaluation results if early_stopping_rounds has been specified.

feature_importances_

array of shape = [n_features] – The feature importances (the higher, the more important the feature).

Note

A custom objective function can be provided for the objective parameter. In this case, it should have the signature objective(y_true, y_pred) -> grad, hess or objective(y_true, y_pred, group) -> grad, hess:

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The predicted values.

group: array-like

Group/query data, used for ranking task.

grad: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the gradient for each sample point.

hess: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)

The value of the second derivative for each sample point.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i] and you should group grad and hess in this way as well.

fit(X, y, sample_weight=None, init_score=None, group=None, eval_set=None, eval_names=None, eval_sample_weight=None, eval_init_score=None, eval_group=None, eval_metric='ndcg', eval_at=[1], early_stopping_rounds=None, verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None)

Build a gradient boosting model from the training set (X, y).

Parameters:
X (array-like or sparse matrix of shape = [__n_samples__, n_features__]) – Input feature matrix.
y (array-like of shape = [__n_samples__]) – The target values (class labels in classification, real numbers in regression).
sample_weight (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Weights of training data.
init_score (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Init score of training data.
group (array-like of shape = [__n_samples__] or None__, optional (__default=None__)) – Group data of training data.
eval_set (list or None__, optional (__default=None__)) – A list of (X, y) tuple pairs to use as a validation sets for early-stopping.
eval_names (list of strings or None__, optional (__default=None__)) – Names of eval_set.
eval_sample_weight (list of arrays or None__, optional (__default=None__)) – Weights of eval data.
eval_init_score (list of arrays or None__, optional (__default=None__)) – Init score of eval data.
eval_group (list of arrays or None__, optional (__default=None__)) – Group data of eval data.
eval_metric (string__, list of strings__, callable or None__, optional (__default="ndcg"__)) – If string, it should be a built-in evaluation metric to use. If callable, it should be a custom evaluation metric, see note for more details.
eval_at (list of int__, optional (__default=__[__1__]__)) – The evaluation positions of NDCG.
early_stopping_rounds (int or None__, optional (__default=None__)) – Activates early stopping. The model will train until the validation score stops improving. Validation error needs to decrease at least every early_stopping_rounds round(s) to continue training.
verbose (bool__, optional (__default=True__)) – If True and an evaluation set is used, writes the evaluation progress.
feature_name (list of strings or 'auto'__, optional (__default="auto"__)) – Feature names. If ‘auto’ and data is pandas DataFrame, data columns names are used.
categorical_feature (list of strings or int__, or 'auto'__, optional (__default="auto"__)) – Categorical features. If list of int, interpreted as indices. If list of strings, interpreted as feature names (need to specify feature_name as well). If ‘auto’ and data is pandas DataFrame, pandas categorical columns are used.
callbacks (list of callback functions or None__, optional (__default=None__)) – List of callback functions that are applied at each iteration. See Callbacks in Python API for more information.
Returns:
self – Returns self.
Return type:
object

Note

Custom eval function expects a callable with following functions: func(y_true, y_pred), func(y_true, y_pred, weight) or func(y_true, y_pred, weight, group). Returns (eval_name, eval_result, is_bigger_better) or list of (eval_name, eval_result, is_bigger_better)

y_true: array-like of shape = [n_samples]

The target values.

y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class)

The predicted values.

weight: array-like of shape = [n_samples]

The weight of samples.

group: array-like

Group/query data, used for ranking task.

eval_name: str

The name of evaluation.

eval_result: float

The eval result.

is_bigger_better: bool

Is eval result bigger better, e.g. AUC is bigger_better.

For multi-class task, the y_pred is group by class_id first, then group by row_id. If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].

Callbacks

lightgbm.early_stopping(stopping_rounds, verbose=True)

Create a callback that activates early stopping.

Note

Activates early stopping. Requires at least one validation data and one metric. If there’s more than one, will check all of them.

Parameters:
stopping_rounds (int) – The possible number of rounds without the trend occurrence.
verbose (bool__, optional (__default=True__)) – Whether to print message with early stopping information.
Returns:
callback – The callback that activates early stopping.
Return type:
function

lightgbm.print_evaluation(period=1, show_stdv=True)

Create a callback that prints the evaluation results.

Parameters:
period (int__, optional (__default=1__)) – The period to print the evaluation results.
show_stdv (bool__, optional (__default=True__)) – Whether to show stdv (if provided).
Returns:
callback – The callback that prints the evaluation results every period iteration(s).
Return type:
function

lightgbm.record_evaluation(eval_result)

Create a callback that records the evaluation history into eval_result.

Parameters:
eval_result (dict) – A dictionary to store the evaluation results.
Returns:
callback – The callback that records the evaluation history into the passed dictionary.
Return type:
function

lightgbm.reset_parameter(**kwargs)

Create a callback that resets the parameter after the first iteration.

Note

The initial parameter will still take in-effect on first iteration.

Parameters:
kwargs (value should be list or function) – List of parameters for each boosting round or a customized function that calculates the parameter in terms of current number of round (e.g. yields learning rate decay). If list lst, parameter = lst[current_round]. If function func, parameter = func(current_round).
Returns:
callback – The callback that resets the parameter after the first iteration.
Return type:
function

Plotting

lightgbm.plot_importance(booster, ax=None, height=0.2, xlim=None, ylim=None, title='Feature importance', xlabel='Feature importance', ylabel='Features', importance_type='split', max_num_features=None, ignore_zero=True, figsize=None, grid=True, **kwargs)

Plot model’s feature importances.

Parameters:
booster (Booster or LGBMModel) – Booster or LGBMModel instance which feature importance should be plotted.
ax (matplotlib.axes.Axes or None__, optional (__default=None__)) – Target axes instance. If None, new figure and axes will be created.
height (float__, optional (__default=0.2__)) – Bar height, passed to ax.barh().
xlim (tuple of 2 elements or None__, optional (__default=None__)) – Tuple passed to ax.xlim().
ylim (tuple of 2 elements or None__, optional (__default=None__)) – Tuple passed to ax.ylim().
title (string or None__, optional (__default="Feature importance"__)) – Axes title. If None, title is disabled.
xlabel (string or None__, optional (__default="Feature importance"__)) – X-axis title label. If None, title is disabled.
ylabel (string or None__, optional (__default="Features"__)) – Y-axis title label. If None, title is disabled.
importance_type (string__, optional (__default="split"__)) – How the importance is calculated. If “split”, result contains numbers of times the feature is used in a model. If “gain”, result contains total gains of splits which use the feature.
max_num_features (int or None__, optional (__default=None__)) – Max number of top features displayed on plot. If None or <1, all features will be displayed.
ignore_zero (bool__, optional (__default=True__)) – Whether to ignore features with zero importance.
figsize (tuple of 2 elements or None__, optional (__default=None__)) – Figure size.
grid (bool__, optional (__default=True__)) – Whether to add a grid for axes.
**kwargs (other parameters) – Other parameters passed to ax.barh().
Returns:
ax – The plot with model’s feature importances.
Return type:
matplotlib.axes.Axes

lightgbm.plot_metric(booster, metric=None, dataset_names=None, ax=None, xlim=None, ylim=None, title='Metric during training', xlabel='Iterations', ylabel='auto', figsize=None, grid=True)

Plot one metric during training.

Parameters:
booster (dict or LGBMModel) – Dictionary returned from lightgbm.train() or LGBMModel instance.
metric (string or None__, optional (__default=None__)) – The metric name to plot. Only one metric supported because different metrics have various scales. If None, first metric picked from dictionary (according to hashcode).
dataset_names (list of strings or None__, optional (__default=None__)) – List of the dataset names which are used to calculate metric to plot. If None, all datasets are used.
ax (matplotlib.axes.Axes or None__, optional (__default=None__)) – Target axes instance. If None, new figure and axes will be created.
xlim (tuple of 2 elements or None__, optional (__default=None__)) – Tuple passed to ax.xlim().
ylim (tuple of 2 elements or None__, optional (__default=None__)) – Tuple passed to ax.ylim().
title (string or None__, optional (__default="Metric during training"__)) – Axes title. If None, title is disabled.
xlabel (string or None__, optional (__default="Iterations"__)) – X-axis title label. If None, title is disabled.
ylabel (string or None__, optional (__default="auto"__)) – Y-axis title label. If ‘auto’, metric name is used. If None, title is disabled.
figsize (tuple of 2 elements or None__, optional (__default=None__)) – Figure size.
grid (bool__, optional (__default=True__)) – Whether to add a grid for axes.
Returns:
ax – The plot with metric’s history over the training.
Return type:
matplotlib.axes.Axes

lightgbm.plot_tree(booster, ax=None, tree_index=0, figsize=None, graph_attr=None, node_attr=None, edge_attr=None, show_info=None)

Plot specified tree.

Parameters:
booster (Booster or LGBMModel) – Booster or LGBMModel instance to be plotted.
ax (matplotlib.axes.Axes or None__, optional (__default=None__)) – Target axes instance. If None, new figure and axes will be created.
tree_index (int__, optional (__default=0__)) – The index of a target tree to plot.
figsize (tuple of 2 elements or None__, optional (__default=None__)) – Figure size.
graph_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for the graph.
node_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for all nodes.
edge_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for all edges.
show_info (list or None__, optional (__default=None__)) – What information should be showed on nodes. Possible values of list items: ‘split_gain’, ‘internal_value’, ‘internal_count’, ‘leaf_count’.
Returns:
ax – The plot with single tree.
Return type:
matplotlib.axes.Axes

lightgbm.create_tree_digraph(booster, tree_index=0, show_info=None, name=None, comment=None, filename=None, directory=None, format=None, engine=None, encoding=None, graph_attr=None, node_attr=None, edge_attr=None, body=None, strict=False)

Create a digraph representation of specified tree.

Note

For more information please visit http://graphviz.readthedocs.io/en/stable/api.html#digraph.

Parameters:
booster (Booster or LGBMModel) – Booster or LGBMModel instance.
tree_index (int__, optional (default=0)) – The index of a target tree to convert.
- show_info (list or None__, optional (__default=None__)) – What information should be showed on nodes. Possible values of list items: ‘split_gain’, ‘internal_value’, ‘internal_count’, ‘leaf_count’.
name (string or None__, optional (__default=None__)) – Graph name used in the source code.
comment (string or None__, optional (__default=None__)) – Comment added to the first line of the source.
filename (string or None__, optional (__default=None__)) – Filename for saving the source. If None, name + ‘.gv’ is used.
directory (string or None__, optional (__default=None__)) – (Sub)directory for source saving and rendering.
format (string or None__, optional (__default=None__)) – Rendering output format (‘pdf’, ‘png’, …).
engine (string or None__, optional (__default=None__)) – Layout command used (‘dot’, ‘neato’, …).
encoding (string or None__, optional (__default=None__)) – Encoding for saving the source.
graph_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for the graph.
node_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for all nodes.
edge_attr (dict or None__, optional (__default=None__)) – Mapping of (attribute, value) pairs set for all edges.
body (list of strings or None__, optional (__default=None__)) – Lines to add to the graph body.
strict (bool__, optional (__default=False__)) – Whether rendering should merge multi-edges.
Returns:
graph – The digraph representation of specified tree.
Return type:
graphviz.Digraph