config.h 36.9 KB
Newer Older
1
2
/// desc and descl2 fields must be written in reStructuredText format

Guolin Ke's avatar
Guolin Ke committed
3
4
5
6
7
8
#ifndef LIGHTGBM_CONFIG_H_
#define LIGHTGBM_CONFIG_H_

#include <LightGBM/utils/common.h>
#include <LightGBM/utils/log.h>

Guolin Ke's avatar
Guolin Ke committed
9
#include <LightGBM/meta.h>
10
#include <LightGBM/export.h>
Guolin Ke's avatar
Guolin Ke committed
11

Guolin Ke's avatar
Guolin Ke committed
12
13
14
#include <vector>
#include <string>
#include <unordered_map>
wxchan's avatar
wxchan committed
15
#include <unordered_set>
Guolin Ke's avatar
Guolin Ke committed
16
#include <algorithm>
Guolin Ke's avatar
Guolin Ke committed
17
#include <memory>
Guolin Ke's avatar
Guolin Ke committed
18
19
20

namespace LightGBM {

Guolin Ke's avatar
Guolin Ke committed
21
22
23
24
/*! \brief Types of tasks */
enum TaskType {
  kTrain, kPredict, kConvertModel, KRefitTree
};
25
const int kDefaultNumLeaves = 31;
Guolin Ke's avatar
Guolin Ke committed
26

Guolin Ke's avatar
Guolin Ke committed
27
struct Config {
Guolin Ke's avatar
Guolin Ke committed
28
public:
Guolin Ke's avatar
Guolin Ke committed
29
  std::string ToString() const;
Guolin Ke's avatar
Guolin Ke committed
30
31
32
33
  /*!
  * \brief Get string value by specific name of key
  * \param params Store the key and value for params
  * \param name Name of key
Hui Xue's avatar
Hui Xue committed
34
  * \param out Value will assign to out if key exists
Guolin Ke's avatar
Guolin Ke committed
35
36
  * \return True if key exists
  */
Guolin Ke's avatar
Guolin Ke committed
37
  inline static bool GetString(
Guolin Ke's avatar
Guolin Ke committed
38
39
40
41
42
43
44
    const std::unordered_map<std::string, std::string>& params,
    const std::string& name, std::string* out);

  /*!
  * \brief Get int value by specific name of key
  * \param params Store the key and value for params
  * \param name Name of key
Hui Xue's avatar
Hui Xue committed
45
  * \param out Value will assign to out if key exists
Guolin Ke's avatar
Guolin Ke committed
46
47
  * \return True if key exists
  */
Guolin Ke's avatar
Guolin Ke committed
48
  inline static bool GetInt(
Guolin Ke's avatar
Guolin Ke committed
49
50
51
52
    const std::unordered_map<std::string, std::string>& params,
    const std::string& name, int* out);

  /*!
53
  * \brief Get double value by specific name of key
Guolin Ke's avatar
Guolin Ke committed
54
55
  * \param params Store the key and value for params
  * \param name Name of key
Hui Xue's avatar
Hui Xue committed
56
  * \param out Value will assign to out if key exists
Guolin Ke's avatar
Guolin Ke committed
57
58
  * \return True if key exists
  */
Guolin Ke's avatar
Guolin Ke committed
59
  inline static bool GetDouble(
Guolin Ke's avatar
Guolin Ke committed
60
    const std::unordered_map<std::string, std::string>& params,
61
    const std::string& name, double* out);
Guolin Ke's avatar
Guolin Ke committed
62
63
64
65
66

  /*!
  * \brief Get bool value by specific name of key
  * \param params Store the key and value for params
  * \param name Name of key
Hui Xue's avatar
Hui Xue committed
67
  * \param out Value will assign to out if key exists
Guolin Ke's avatar
Guolin Ke committed
68
69
  * \return True if key exists
  */
Guolin Ke's avatar
Guolin Ke committed
70
  inline static bool GetBool(
Guolin Ke's avatar
Guolin Ke committed
71
72
    const std::unordered_map<std::string, std::string>& params,
    const std::string& name, bool* out);
73

wxchan's avatar
wxchan committed
74
  static void KV2Map(std::unordered_map<std::string, std::string>& params, const char* kv);
75
  static std::unordered_map<std::string, std::string> Str2Map(const char* parameters);
Guolin Ke's avatar
Guolin Ke committed
76

Guolin Ke's avatar
Guolin Ke committed
77
  #pragma region Parameters
78

Guolin Ke's avatar
Guolin Ke committed
79
80
81
  #pragma region Core Parameters

  // [doc-only]
82
83
  // alias = config_file
  // desc = path of config file
84
  // desc = **Note**: can be used only in CLI version
Guolin Ke's avatar
Guolin Ke committed
85
86
87
  std::string config = "";

  // [doc-only]
88
89
90
91
92
93
94
95
  // type = enum
  // default = train
  // options = train, predict, convert_model, refit
  // alias = task_type
  // desc = ``train``, for training, aliases: ``training``
  // desc = ``predict``, for prediction, aliases: ``prediction``, ``test``
  // desc = ``convert_model``, for converting model file into if-else format, see more information in `IO Parameters <#io-parameters>`__
  // desc = ``refit``, for refitting existing models with new data, aliases: ``refit_tree``
96
  // desc = **Note**: can be used only in CLI version
Guolin Ke's avatar
Guolin Ke committed
97
98
99
  TaskType task = TaskType::kTrain;

  // [doc-only]
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
  // type = enum
  // options = regression, regression_l1, huber, fair, poisson, quantile, mape, gammma, tweedie, binary, multiclass, multiclassova, xentropy, xentlambda, lambdarank
  // alias = objective_type, app, application
  // desc = regression application
  // descl2 = ``regression_l2``, L2 loss, aliases: ``regression``, ``mean_squared_error``, ``mse``, ``l2_root``, ``root_mean_squared_error``, ``rmse``
  // descl2 = ``regression_l1``, L1 loss, aliases: ``mean_absolute_error``, ``mae``
  // descl2 = ``huber``, `Huber loss <https://en.wikipedia.org/wiki/Huber_loss>`__
  // descl2 = ``fair``, `Fair loss <https://www.kaggle.com/c/allstate-claims-severity/discussion/24520>`__
  // descl2 = ``poisson``, `Poisson regression <https://en.wikipedia.org/wiki/Poisson_regression>`__
  // descl2 = ``quantile``, `Quantile regression <https://en.wikipedia.org/wiki/Quantile_regression>`__
  // descl2 = ``mape``, `MAPE loss <https://en.wikipedia.org/wiki/Mean_absolute_percentage_error>`__, aliases: ``mean_absolute_percentage_error``
  // descl2 = ``gamma``, Gamma regression with log-link. It might be useful, e.g., for modeling insurance claims severity, or for any target that might be `gamma-distributed <https://en.wikipedia.org/wiki/Gamma_distribution#Applications>`__
  // descl2 = ``tweedie``, Tweedie regression with log-link. It might be useful, e.g., for modeling total loss in insurance, or for any target that might be `tweedie-distributed <https://en.wikipedia.org/wiki/Tweedie_distribution#Applications>`__
  // desc = ``binary``, binary `log loss <https://en.wikipedia.org/wiki/Cross_entropy>`__ classification (or logistic regression). Requires labels in {0, 1}; see ``xentropy`` for general probability labels in [0, 1]
  // desc = multi-class classification application
  // descl2 = ``multiclass``, `softmax <https://en.wikipedia.org/wiki/Softmax_function>`__ objective function, aliases: ``softmax``
  // descl2 = ``multiclassova``, `One-vs-All <https://en.wikipedia.org/wiki/Multiclass_classification#One-vs.-rest>`__ binary objective function, aliases: ``multiclass_ova``, ``ova``, ``ovr``
  // descl2 = ``num_class`` should be set as well
  // desc = cross-entropy application
  // descl2 = ``xentropy``, objective function for cross-entropy (with optional linear weights), aliases: ``cross_entropy``
  // descl2 = ``xentlambda``, alternative parameterization of cross-entropy, aliases: ``cross_entropy_lambda``
  // descl2 = label is anything in interval [0, 1]
  // desc = ``lambdarank``, `lambdarank <https://papers.nips.cc/paper/2971-learning-to-rank-with-nonsmooth-cost-functions.pdf>`__ application
  // descl2 = label should be ``int`` type in lambdarank tasks, and larger number represents the higher relevance (e.g. 0:bad, 1:fair, 2:good, 3:perfect)
  // descl2 = `label_gain <#objective-parameters>`__ can be used to set the gain (weight) of ``int`` label
  // descl2 = all values in ``label`` must be smaller than number of elements in ``label_gain``
Guolin Ke's avatar
Guolin Ke committed
126
127
128
  std::string objective = "regression";

  // [doc-only]
129
130
  // type = enum
  // alias = boosting_type, boost
131
132
133
  // options = gbdt, gbrt, rf, random_forest, dart, goss
  // desc = ``gbdt``, traditional Gradient Boosting Decision Tree, aliases: ``gbrt``
  // desc = ``rf``, Random Forest, aliases: ``random_forest``
134
135
  // desc = ``dart``, `Dropouts meet Multiple Additive Regression Trees <https://arxiv.org/abs/1505.01866>`__
  // desc = ``goss``, Gradient-based One-Side Sampling
Guolin Ke's avatar
Guolin Ke committed
136
137
  std::string boosting = "gbdt";

138
139
  // alias = train, train_data, data_filename
  // desc = training data, LightGBM will train from this data
Guolin Ke's avatar
Guolin Ke committed
140
141
  std::string data = "";

142
  // alias = test, valid_data, valid_data_file, test_data, valid_filenames
143
144
145
  // default = ""
  // desc = validation/test data, LightGBM will output metrics for these data
  // desc = support multiple validation data, separated by ``,``
Guolin Ke's avatar
Guolin Ke committed
146
147
  std::vector<std::string> valid;

148
149
150
  // alias = num_iteration, num_tree, num_trees, num_round, num_rounds, num_boost_round, n_estimators
  // check = >=0
  // desc = number of boosting iterations
151
  // desc = **Note**: for Python/R-package, **this parameter is ignored**, use ``num_boost_round`` (Python) or ``nrounds`` (R) input arguments of ``train`` and ``cv`` methods instead
152
  // desc = **Note**: internally, LightGBM constructs ``num_class * num_iterations`` trees for multi-class classification problems
Guolin Ke's avatar
Guolin Ke committed
153
  int num_iterations = 100;
Guolin Ke's avatar
Guolin Ke committed
154

155
  // alias = shrinkage_rate
156
  // check = >0.0
157
158
  // desc = shrinkage rate
  // desc = in ``dart``, it also affects on normalization weights of dropped trees
Guolin Ke's avatar
Guolin Ke committed
159
160
  double learning_rate = 0.1;

161
  // default = 31
Guolin Ke's avatar
Guolin Ke committed
162
  // alias = num_leaf
163
164
  // check = >1
  // desc = max number of leaves in one tree
Guolin Ke's avatar
Guolin Ke committed
165
166
167
  int num_leaves = kDefaultNumLeaves;

  // [doc-only]
168
169
  // type = enum
  // options = serial, feature, data, voting
Guolin Ke's avatar
Guolin Ke committed
170
  // alias = tree, tree_learner_type
171
172
173
174
175
  // desc = ``serial``, single machine tree learner
  // desc = ``feature``, feature parallel tree learner, aliases: ``feature_parallel``
  // desc = ``data``, data parallel tree learner, aliases: ``data_parallel``
  // desc = ``voting``, voting parallel tree learner, aliases: ``voting_parallel``
  // desc = refer to `Parallel Learning Guide <./Parallel-Learning-Guide.rst>`__ to get more details
Guolin Ke's avatar
Guolin Ke committed
176
177
178
179
  std::string tree_learner = "serial";

  // alias = num_thread, nthread, nthreads
  // desc = number of threads for LightGBM
180
181
182
183
184
  // desc = ``0`` means default number of threads in OpenMP
  // desc = for the best speed, set this to the number of **real CPU cores**, not the number of threads (most CPUs use `hyper-threading <https://en.wikipedia.org/wiki/Hyper-threading>`__ to generate 2 threads per CPU core)
  // desc = do not set it too large if your dataset is small (for instance, do not use 64 threads for a dataset with 10,000 rows)
  // desc = be aware a task manager or any similar CPU monitoring tool might report that cores not being fully utilized. **This is normal**
  // desc = for parallel learning, do not use all CPU cores because this will cause poor performance for the network communication
Guolin Ke's avatar
Guolin Ke committed
185
186
187
  int num_threads = 0;

  // [doc-only]
188
189
  // type = enum
  // options = cpu, gpu
190
  // alias = device
191
192
193
194
  // desc = device for the tree learning, you can use GPU to achieve the faster learning
  // desc = **Note**: it is recommended to use the smaller ``max_bin`` (e.g. 63) to get the better speed up
  // desc = **Note**: for the faster speed, GPU uses 32-bit float point to sum up by default, so this may affect the accuracy for some tasks. You can set ``gpu_use_dp=true`` to enable 64-bit float point, but it will slow down the training
  // desc = **Note**: refer to `Installation Guide <./Installation-Guide.rst#build-gpu-version>`__ to build LightGBM with GPU support
Guolin Ke's avatar
Guolin Ke committed
195
196
197
  std::string device_type = "cpu";

  // [doc-only]
198
199
200
  // alias = random_seed
  // desc = this seed is used to generate other seeds, e.g. ``data_random_seed``, ``feature_fraction_seed``
  // desc = will be overridden, if you set other seeds
Guolin Ke's avatar
Guolin Ke committed
201
202
203
204
205
206
  int seed = 0;

  #pragma endregion

  #pragma region Learning Control Parameters

207
208
  // desc = limit the max depth for tree model. This is used to deal with over-fitting when ``#data`` is small. Tree still grows leaf-wise
  // desc = ``< 0`` means no limit
Guolin Ke's avatar
Guolin Ke committed
209
210
211
  int max_depth = -1;

  // alias = min_data_per_leaf, min_data, min_child_samples
212
213
  // check = >=0
  // desc = minimal number of data in one leaf. Can be used to deal with over-fitting
Guolin Ke's avatar
Guolin Ke committed
214
215
  int min_data_in_leaf = 20;

216
217
218
  // alias = min_sum_hessian_per_leaf, min_sum_hessian, min_hessian, min_child_weight
  // check = >=0.0
  // desc = minimal sum hessian in one leaf. Like ``min_data_in_leaf``, it can be used to deal with over-fitting
Guolin Ke's avatar
Guolin Ke committed
219
220
  double min_sum_hessian_in_leaf = 1e-3;

221
222
223
224
225
226
227
  // alias = sub_row, subsample, bagging
  // check = >0.0
  // check = <=1.0
  // desc = like ``feature_fraction``, but this will randomly select part of data without resampling
  // desc = can be used to speed up training
  // desc = can be used to deal with over-fitting
  // desc = **Note**: to enable bagging, ``bagging_freq`` should be set to a non zero value as well
Guolin Ke's avatar
Guolin Ke committed
228
229
  double bagging_fraction = 1.0;

230
231
232
233
  // alias = subsample_freq
  // desc = frequency for bagging
  // desc = ``0`` means disable bagging; ``k`` means perform bagging at every ``k`` iteration
  // desc = **Note**: to enable bagging, ``bagging_fraction`` should be set to value smaller than ``1.0`` as well
Guolin Ke's avatar
Guolin Ke committed
234
235
236
237
238
239
240
  int bagging_freq = 0;

  // alias = bagging_fraction_seed
  // desc = random seed for bagging
  int bagging_seed = 3;

  // alias = sub_feature, colsample_bytree
241
242
243
244
245
  // check = >0.0
  // check = <=1.0
  // desc = LightGBM will randomly select part of features on each iteration if ``feature_fraction`` smaller than ``1.0``. For example, if you set it to ``0.8``, LightGBM will select 80% of features before training each tree
  // desc = can be used to speed up training
  // desc = can be used to deal with over-fitting
Guolin Ke's avatar
Guolin Ke committed
246
247
  double feature_fraction = 1.0;

248
  // desc = random seed for ``feature_fraction``
Guolin Ke's avatar
Guolin Ke committed
249
250
  int feature_fraction_seed = 2;

251
252
253
  // alias = early_stopping_rounds, early_stopping
  // desc = will stop training if one metric of one validation data doesn't improve in last ``early_stopping_round`` rounds
  // desc = ``<= 0`` means disable
Guolin Ke's avatar
Guolin Ke committed
254
255
  int early_stopping_round = 0;

256
257
258
259
  // alias = max_tree_output, max_leaf_output
  // desc = used to limit the max output of tree leaves
  // desc = ``<= 0`` means no constraint
  // desc = the final max output of leaves is ``learning_rate * max_delta_step``
Guolin Ke's avatar
Guolin Ke committed
260
261
  double max_delta_step = 0.0;

262
263
264
  // alias = reg_alpha
  // check = >=0.0
  // desc = L1 regularization
Guolin Ke's avatar
Guolin Ke committed
265
266
267
  double lambda_l1 = 0.0;

  // alias = reg_lambda
268
  // check = >=0.0
Guolin Ke's avatar
Guolin Ke committed
269
270
271
  // desc = L2 regularization
  double lambda_l2 = 0.0;

272
273
274
  // alias = min_split_gain
  // check = >=0.0
  // desc = the minimal gain to perform split
Guolin Ke's avatar
Guolin Ke committed
275
276
  double min_gain_to_split = 0.0;

277
278
279
280
  // check = >=0.0
  // check = <=1.0
  // desc = used only in ``dart``
  // desc = dropout rate
Guolin Ke's avatar
Guolin Ke committed
281
282
  double drop_rate = 0.1;

283
284
285
  // desc = used only in ``dart``
  // desc = max number of dropped trees on one iteration
  // desc = ``<=0`` means no limit
Guolin Ke's avatar
Guolin Ke committed
286
287
  int max_drop = 50;

288
289
290
291
  // check = >=0.0
  // check = <=1.0
  // desc = used only in ``dart``
  // desc = probability of skipping drop
Guolin Ke's avatar
Guolin Ke committed
292
293
  double skip_drop = 0.5;

294
295
  // desc = used only in ``dart``
  // desc = set this to ``true``, if you want to use xgboost dart mode
Guolin Ke's avatar
Guolin Ke committed
296
297
  bool xgboost_dart_mode = false;

298
299
  // desc = used only in ``dart``
  // desc = set this to ``true``, if you want to use uniform drop
Guolin Ke's avatar
Guolin Ke committed
300
301
  bool uniform_drop = false;

302
303
  // desc = used only in ``dart``
  // desc = random seed to choose dropping models
Guolin Ke's avatar
Guolin Ke committed
304
305
  int drop_seed = 4;

306
307
308
309
  // check = >=0.0
  // check = <=1.0
  // desc = used only in ``goss``
  // desc = the retain ratio of large gradient data
Guolin Ke's avatar
Guolin Ke committed
310
311
  double top_rate = 0.2;

312
313
314
315
  // check = >=0.0
  // check = <=1.0
  // desc = used only in ``goss``
  // desc = the retain ratio of small gradient data
Guolin Ke's avatar
Guolin Ke committed
316
317
  double other_rate = 0.1;

318
319
  // check = >0
  // desc = minimal number of data per categorical group
Guolin Ke's avatar
Guolin Ke committed
320
321
  int min_data_per_group = 100;

322
323
324
  // check = >0
  // desc = used for the categorical features
  // desc = limit the max threshold points in categorical features
Guolin Ke's avatar
Guolin Ke committed
325
326
  int max_cat_threshold = 32;

327
328
329
330
  // check = >=0.0
  // desc = used for the categorical features
  // desc = L2 regularization in categorcial split
  double cat_l2 = 10.0;
Guolin Ke's avatar
Guolin Ke committed
331

332
333
334
335
  // check = >=0.0
  // desc = used for the categorical features
  // desc = this can reduce the effect of noises in categorical features, especially for categories with few data
  double cat_smooth = 10.0;
Guolin Ke's avatar
Guolin Ke committed
336
  
337
338
  // check = >0
  // desc = when number of categories of one feature smaller than or equal to ``max_cat_to_onehot``, one-vs-other split algorithm will be used
Guolin Ke's avatar
Guolin Ke committed
339
340
341
  int max_cat_to_onehot = 4;

  // alias = topk
342
343
344
  // check = >0
  // desc = used in `Voting parallel <./Parallel-Learning-Guide.rst#choose-appropriate-parallel-algorithm>`__
  // desc = set this to larger value for more accurate result, but it will slow down the training speed
Guolin Ke's avatar
Guolin Ke committed
345
346
347
  int top_k = 20;

  // type = multi-int
348
349
350
351
352
  // alias = mc, monotone_constraint
  // default = None
  // desc = used for constraints of monotonic features
  // desc = ``1`` means increasing, ``-1`` means decreasing, ``0`` means non-constraint
  // desc = you need to specify all features in order. For example, ``mc=-1,0,1`` means decreasing for 1st feature, non-constraint for 2nd feature and increasing for the 3rd feature
Guolin Ke's avatar
Guolin Ke committed
353
354
  std::vector<int8_t> monotone_constraints;
  
355
356
357
358
359
  // alias = fs, forced_splits_filename, forced_splits_file, forced_splits
  // desc = path to a ``.json`` file that specifies splits to force at the top of every decision tree before best-first learning commences
  // desc = ``.json`` file can be arbitrarily nested, and each split contains ``feature``, ``threshold`` fields, as well as ``left`` and ``right`` fields representing subsplits
  // desc = categorical splits are forced in a one-hot fashion, with ``left`` representing the split containing the feature value and ``right`` representing other values
  // desc = see `this file <https://github.com/Microsoft/LightGBM/tree/master/examples/binary_classification/forced_splits.json>`__ as an example
Guolin Ke's avatar
Guolin Ke committed
360
361
362
363
364
365
  std::string forcedsplits_filename = "";

  #pragma endregion

  #pragma region IO Parameters

366
367
368
369
370
371
372
373
374
  // alias = verbose
  // desc = controls the level of LightGBM's verbosity
  // desc = ``< 0``: Fatal, ``= 0``: Error (Warn), ``> 0``: Info
  int verbosity = 1;

  // check = >1
  // desc = max number of bins that feature values will be bucketed in
  // desc = small number of bins may reduce training accuracy but may increase general power (deal with over-fitting)
  // desc = LightGBM will auto compress memory according to ``max_bin``. For example, LightGBM will use ``uint8_t`` for feature value if ``max_bin=255``
375
  int max_bin = 255;
Guolin Ke's avatar
Guolin Ke committed
376

377
378
379
  // check = >0
  // desc = minimal number of data inside one bin
  // desc = use this to avoid one-data-one-bin (potential over-fitting)
Guolin Ke's avatar
Guolin Ke committed
380
381
  int min_data_in_bin = 3;

382
383
384
385
386
387
388
389
390
391
392
393
  // alias = subsample_for_bin
  // check = >0
  // desc = number of data that sampled to construct histogram bins
  // desc = setting this to larger value will give better training result, but will increase data loading time
  // desc = set this to larger value if data is very sparse
  int bin_construct_sample_cnt = 200000;

  // desc = max cache size in MB for historical histogram
  // desc = ``< 0`` means no limit
  double histogram_pool_size = -1.0;

  // desc = random seed for data partition in parallel learning (excluding the ``feature_parallel`` mode)
Guolin Ke's avatar
Guolin Ke committed
394
  int data_random_seed = 1;
Guolin Ke's avatar
Guolin Ke committed
395

396
397
  // alias = model_output, model_out
  // desc = filename of output model in training
Guolin Ke's avatar
Guolin Ke committed
398
  std::string output_model = "LightGBM_model.txt";
Guolin Ke's avatar
Guolin Ke committed
399

400
401
402
403
  // desc = frequency of saving model file snapshot
  // desc = set this to positive value to enable this function. For example, the model file will be snapshotted at each iteration if ``snapshot_freq=1``
  int snapshot_freq = -1;

Guolin Ke's avatar
Guolin Ke committed
404
  // alias = model_input, model_in
405
406
407
408
  // desc = filename of input model
  // desc = for ``prediction`` task, this model will be applied to prediction data
  // desc = for ``train`` task, training will be continued from this model
  // desc = **Note**: can be used only in CLI version
Guolin Ke's avatar
Guolin Ke committed
409
  std::string input_model = "";
410

411
412
  // alias = predict_result, prediction_result
  // desc = filename of prediction result in ``prediction`` task
Guolin Ke's avatar
Guolin Ke committed
413
414
  std::string output_result = "LightGBM_predict_result.txt";

415
416
417
418
419
420
421
422
423
424
425
426
  // alias = init_score_filename, init_score_file, init_score, input_init_score
  // desc = path of file with training initial score
  // desc = if ``""``, will use ``train_data_file`` + ``.init`` (if exists)
  std::string initscore_filename = "";

  // alias = valid_data_init_scores, valid_init_score_file, valid_init_score
  // default = ""
  // desc = path(s) of file(s) with validation initial score(s)
  // desc = if ``""``, will use ``valid_data_file`` + ``.init`` (if exists)
  // desc = separate by ``,`` for multi-validation data
  std::vector<std::string> valid_data_initscores;

Guolin Ke's avatar
Guolin Ke committed
427
  // alias = is_pre_partition
428
429
  // desc = used for parallel learning (excluding the ``feature_parallel`` mode)
  // desc = ``true`` if training data are pre-partitioned, and different machines use different partitions
Guolin Ke's avatar
Guolin Ke committed
430
431
  bool pre_partition = false;

432
433
434
435
436
437
438
439
440
441
442
443
444
445
  // alias = is_enable_bundle, bundle
  // desc = set this to ``false`` to disable Exclusive Feature Bundling (EFB), which is described in `LightGBM: A Highly Efficient Gradient Boosting Decision Tree <https://papers.nips.cc/paper/6907-lightgbm-a-highly-efficient-gradient-boosting-decision-tree>`__
  // desc = **Note**: disabling this may cause the slow training speed for sparse datasets
  bool enable_bundle = true;

  // check = >=0.0
  // check = <1.0
  // desc = max conflict rate for bundles in EFB
  // desc = set this to ``0.0`` to disallow the conflict and provide more accurate results
  // desc = set this to a larger value to achieve faster speed
  double max_conflict_rate = 0.0;

  // alias = is_sparse, enable_sparse, sparse
  // desc = used to enable/disable sparse optimization
Guolin Ke's avatar
Guolin Ke committed
446
  bool is_enable_sparse = true;
Guolin Ke's avatar
Guolin Ke committed
447

448
449
450
  // check = >0.0
  // check = <=1.0
  // desc = the threshold of zero elements precentage for treating a feature as a sparse one
451
  double sparse_threshold = 0.8;
Guolin Ke's avatar
Guolin Ke committed
452

453
454
455
456
457
458
459
460
461
462
  // desc = set this to ``false`` to disable the special handle of missing value
  bool use_missing = true;

  // desc = set this to ``true`` to treat all zero as missing values (including the unshown values in libsvm/sparse matrics)
  // desc = set this to ``false`` to use ``na`` for representing missing values
  bool zero_as_missing = false;

  // alias = two_round_loading, use_two_round_loading
  // desc = set this to ``true`` if data file is too big to fit in memory
  // desc = by default, LightGBM will map data file to memory and load features from memory. This will provide faster data loading speed, but may cause run out of memory error when the data file is very big
Guolin Ke's avatar
Guolin Ke committed
463
464
465
  bool two_round = false;

  // alias = is_save_binary, is_save_binary_file
466
  // desc = if ``true``, LightGBM will save the dataset (including validation data) to a binary file. This speed ups the data loading for the next time
Guolin Ke's avatar
Guolin Ke committed
467
468
  bool save_binary = false;

469
470
471
472
  // alias = load_from_binary_file, binary_load, load_binary
  // desc = set this to ``true`` to enable autoloading from previous saved binary datasets
  // desc = set this to ``false`` to ignore binary datasets
  bool enable_load_from_binary_file = true;
Guolin Ke's avatar
Guolin Ke committed
473
474

  // alias = has_header
475
  // desc = set this to ``true`` if input data has header
Guolin Ke's avatar
Guolin Ke committed
476
477
  bool header = false;

478
479
480
481
482
  // type = int or string
  // alias = label
  // desc = used to specify the label column
  // desc = use number for index, e.g. ``label=0`` means column\_0 is the label
  // desc = add a prefix ``name:`` for column name, e.g. ``label=name:is_click``
Guolin Ke's avatar
Guolin Ke committed
483
  std::string label_column = "";
Guolin Ke's avatar
Guolin Ke committed
484

485
486
487
488
489
490
  // type = int or string
  // alias = weight
  // desc = used to specify the weight column
  // desc = use number for index, e.g. ``weight=0`` means column\_0 is the weight
  // desc = add a prefix ``name:`` for column name, e.g. ``weight=name:weight``
  // desc = **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``, e.g. when label is column\_0, and weight is column\_1, the correct parameter is ``weight=0``
Guolin Ke's avatar
Guolin Ke committed
491
  std::string weight_column = "";
Guolin Ke's avatar
Guolin Ke committed
492

493
494
495
496
497
498
499
  // type = int or string
  // alias = group, group_id, query_column, query, query_id
  // desc = used to specify the query/group id column
  // desc = use number for index, e.g. ``query=0`` means column\_0 is the query id
  // desc = add a prefix ``name:`` for column name, e.g. ``query=name:query_id``
  // desc = **Note**: data should be grouped by query\_id
  // desc = **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``, e.g. when label is column\_0 and query\_id is column\_1, the correct parameter is ``query=0``
Guolin Ke's avatar
Guolin Ke committed
500
  std::string group_column = "";
Guolin Ke's avatar
Guolin Ke committed
501

502
  // type = multi-int or string
Guolin Ke's avatar
Guolin Ke committed
503
  // alias = ignore_feature, blacklist
504
505
506
507
508
  // desc = used to specify some ignoring columns in training
  // desc = use number for index, e.g. ``ignore_column=0,1,2`` means column\_0, column\_1 and column\_2 will be ignored
  // desc = add a prefix ``name:`` for column name, e.g. ``ignore_column=name:c1,c2,c3`` means c1, c2 and c3 will be ignored
  // desc = **Note**: works only in case of loading data directly from file
  // desc = **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``
Guolin Ke's avatar
Guolin Ke committed
509
  std::string ignore_column = "";
510

511
512
513
514
515
516
517
518
519
  // type = multi-int or string
  // alias = cat_feature, categorical_column, cat_column
  // desc = used to specify categorical features
  // desc = use number for index, e.g. ``categorical_feature=0,1,2`` means column\_0, column\_1 and column\_2 are categorical features
  // desc = add a prefix ``name:`` for column name, e.g. ``categorical_feature=name:c1,c2,c3`` means c1, c2 and c3 are categorical features
  // desc = **Note**: only supports categorical with ``int`` type
  // desc = **Note**: index starts from ``0`` and it doesn't count the label column when passing type is ``int``
  // desc = **Note**: all values should be less than ``Int32.MaxValue`` (2147483647)
  // desc = **Note**: the negative values will be treated as **missing values**
Guolin Ke's avatar
Guolin Ke committed
520
521
  std::string categorical_feature = "";

522
523
524
525
  // alias = is_predict_raw_score, predict_rawscore, raw_score
  // desc = used only in ``prediction`` task
  // desc = set this to ``true`` to predict only the raw scores
  // desc = set this to ``false`` to predict transformed scores
Guolin Ke's avatar
Guolin Ke committed
526
527
  bool predict_raw_score = false;

528
529
530
  // alias = is_predict_leaf_index, leaf_index
  // desc = used only in ``prediction`` task
  // desc = set this to ``true`` to predict with leaf index of all trees
Guolin Ke's avatar
Guolin Ke committed
531
532
  bool predict_leaf_index = false;

533
534
535
536
  // alias = is_predict_contrib, contrib
  // desc = used only in ``prediction`` task
  // desc = set this to ``true`` to estimate `SHAP values <https://arxiv.org/abs/1706.06060>`__, which represent how each feature contributs to each prediction
  // desc = produces ``#features + 1`` values where the last value is the expected value of the model output over the training data
Guolin Ke's avatar
Guolin Ke committed
537
538
  bool predict_contrib = false;

539
540
541
  // desc = used only in ``prediction`` task
  // desc = used to specify how many trained iterations will be used in prediction
  // desc = ``<= 0`` means no limit
Guolin Ke's avatar
Guolin Ke committed
542
543
  int num_iteration_predict = -1;

544
545
  // desc = used only in ``prediction`` task
  // desc = if ``true``, will use early-stopping to speed up the prediction. May affect the accuracy
546
  bool pred_early_stop = false;
547
548
549

  // desc = used only in ``prediction`` task
  // desc = the frequency of checking early-stopping prediction
550
  int pred_early_stop_freq = 10;
Guolin Ke's avatar
Guolin Ke committed
551

552
553
  // desc = used only in ``prediction`` task
  // desc = the threshold of margin in early-stopping prediction
Guolin Ke's avatar
Guolin Ke committed
554
  double pred_early_stop_margin = 10.0;
Guolin Ke's avatar
Guolin Ke committed
555

556
557
558
  // desc = used only in ``convert_model`` task
  // desc = only ``cpp`` is supported yet
  // desc = if ``convert_model_language`` is set and ``task=train``, the model will be also converted
Guolin Ke's avatar
Guolin Ke committed
559
560
  std::string convert_model_language = "";

561
562
563
  // alias = convert_model_file
  // desc = used only in ``convert_model`` task
  // desc = output filename of converted model
Guolin Ke's avatar
Guolin Ke committed
564
565
  std::string convert_model = "gbdt_prediction.cpp";

566
  #pragma endregion
Guolin Ke's avatar
Guolin Ke committed
567
568
569

  #pragma region Objective Parameters

570
571
572
573
  // check = >0
  // alias = num_classes
  // desc = used only in ``multi-class`` classification application
  int num_class = 1;
Guolin Ke's avatar
Guolin Ke committed
574

575
576
577
578
579
  // alias = unbalanced_sets
  // desc = used only in ``binary`` application
  // desc = set this to ``true`` if training data are unbalance
  // desc = **Note**: this parameter cannot be used at the same time with ``scale_pos_weight``, choose only **one** of them
  bool is_unbalance = false;
Guolin Ke's avatar
Guolin Ke committed
580

581
582
583
584
585
  // check = >0.0
  // desc = used only in ``binary`` application
  // desc = weight of labels with positive class
  // desc = **Note**: this parameter cannot be used at the same time with ``is_unbalance``, choose only **one** of them
  double scale_pos_weight = 1.0;
Guolin Ke's avatar
Guolin Ke committed
586

587
588
589
590
  // check = >0.0
  // desc = used only in ``binary`` and ``multiclassova`` classification and in ``lambdarank`` applications
  // desc = parameter for the sigmoid function
  double sigmoid = 1.0;
Guolin Ke's avatar
Guolin Ke committed
591

592
593
  // desc = used only in ``regression``, ``binary`` and ``cross-entropy`` applications
  // desc = adjusts initial score to the mean of labels for faster convergence
Guolin Ke's avatar
Guolin Ke committed
594
595
  bool boost_from_average = true;

596
597
598
599
  // desc = used only in ``regression`` application
  // desc = used to fit ``sqrt(label)`` instead of original values and prediction result will be also automatically converted to ``prediction^2``
  // desc = might be useful in case of large-range labels
  bool reg_sqrt = false;
Guolin Ke's avatar
Guolin Ke committed
600

601
602
603
604
605
  // check = >0.0
  // check = <1.0
  // desc = used only in ``huber`` and ``quantile`` ``regression`` applications
  // desc = parameter for `Huber loss <https://en.wikipedia.org/wiki/Huber_loss>`__ and `Quantile regression <https://en.wikipedia.org/wiki/Quantile_regression>`__
  double alpha = 0.9;
Guolin Ke's avatar
Guolin Ke committed
606

607
608
609
610
  // check = >0.0
  // desc = used only in ``fair`` ``regression`` application
  // desc = parameter for `Fair loss <https://www.kaggle.com/c/allstate-claims-severity/discussion/24520>`__
  double fair_c = 1.0;
Guolin Ke's avatar
Guolin Ke committed
611

612
613
614
615
  // check = >0.0
  // desc = used only in ``poisson`` ``regression`` application
  // desc = parameter for `Poisson regression <https://en.wikipedia.org/wiki/Poisson_regression>`__ to safeguard optimization
  double poisson_max_delta_step = 0.7;
Guolin Ke's avatar
Guolin Ke committed
616

617
618
619
620
621
622
623
  // check = >=1.0
  // check = <2.0
  // desc = used only in ``tweedie`` ``regression`` application
  // desc = used to control the variance of the tweedie distribution
  // desc = set this closer to ``2`` to shift towards a **Gamma** distribution
  // desc = set this closer to ``1`` to shift towards a **Poisson** distribution
  double tweedie_variance_power = 1.5;
Guolin Ke's avatar
Guolin Ke committed
624

625
626
627
  // check = >0
  // desc = used only in ``lambdarank`` application
  // desc = optimizes `NDCG <https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG>`__ at this position
Guolin Ke's avatar
Guolin Ke committed
628
  int max_position = 20;
Guolin Ke's avatar
Guolin Ke committed
629

630
631
632
633
634
635
636
  // type = multi-double
  // default = 0,1,3,7,15,31,63,...,2^30-1
  // desc = used only in ``lambdarank`` application
  // desc = relevant gain for labels. For example, the gain of label ``2`` is ``3`` in case of default label gains
  // desc = separate by ``,``
  std::vector<double> label_gain;

Guolin Ke's avatar
Guolin Ke committed
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
  #pragma endregion

  #pragma region Metric Parameters
  
  // [doc-only]
  // alias=metric_types
  // default=''
  // type=multi-enum
  // desc=metric to be evaluated on the evaluation sets **in addition** to what is provided in the training arguments
  // descl2='' (empty string or not specific),metric corresponding to specified objective will be used (this is possible only for pre - defined objective functions, otherwise no evaluation metric will be added)
  // descl2='None' (string,**not** a None value),no metric registered,alias=na
  // descl2=l1,absolute loss,alias=mean_absolute_error,mae,regression_l1
  // descl2=l2,square loss,alias=mean_squared_error,mse,regression_l2,regression
  // descl2=l2_root,root square loss,alias=root_mean_squared_error,rmse
  // descl2=quantile,`Quantile regression`_
  // descl2=mape,`MAPE loss`_,alias=mean_absolute_percentage_error
  // descl2=huber,`Huber loss`_
  // descl2=fair,`Fair loss`_
  // descl2=poisson,negative log-likelihood for `Poisson regression`_
  // descl2=gamma,negative log-likelihood for Gamma regression
  // descl2=gamma_deviance,residual deviance for Gamma regression
  // descl2=tweedie,negative log-likelihood for Tweedie regression
  // descl2=ndcg,`NDCG`_
  // descl2=map,`MAP`_,alias=mean_average_precision
  // descl2=auc,`AUC`_
  // descl2=binary_logloss,`log loss`_,alias=binary
  // descl2=binary_error,for one sample: 0 for correct classification,1 for error classification
  // descl2=multi_logloss,log loss for mulit-class classification,alias=multiclass,softmax,multiclassova,multiclass_ova,ova,ovr
  // descl2=multi_error,error rate for mulit-class classification
  // descl2=xentropy,cross-entropy (with optional linear weights),alias=cross_entropy
  // descl2=xentlambda,"intensity-weighted" cross-entropy,alias=cross_entropy_lambda
  // descl2=kldiv,`Kullback-Leibler divergence`_,alias=kullback_leibler
  // desc=support multiple metrics,separated by ,
  std::vector<std::string> metric;

  // check=>0
  // alias = output_freq
  // desc = frequency for metric output
  int metric_freq = 1;

  // alias=training_metric,is_training_metric,train_metric
  // desc=set this to true if you need to output metric result over training dataset
679
  bool is_provide_training_metric = false;
680

Guolin Ke's avatar
Guolin Ke committed
681
682
683
684
  // default=1,2,3,4,5
  // alias=ndcg_eval_at,ndcg_at
  // desc=`NDCG`_ evaluation positions,separated by ,
  std::vector<int> eval_at;
Guolin Ke's avatar
Guolin Ke committed
685

Guolin Ke's avatar
Guolin Ke committed
686
687
688
689
690
691
692
  #pragma endregion

  #pragma region Network Parameters

  // alias=num_machine
  // desc=used for parallel learning,the number of machines for parallel learning application
  // desc=need to set this in both socket and mpi versions
Guolin Ke's avatar
Guolin Ke committed
693
  int num_machines = 1;
Guolin Ke's avatar
Guolin Ke committed
694
695
696
697

  // alias = local_port
  // desc=TCP listen port for local machines
  // desc=you should allow this port in firewall settings before training
Guolin Ke's avatar
Guolin Ke committed
698
  int local_listen_port = 12400;
Guolin Ke's avatar
Guolin Ke committed
699
700

  // desc=socket time-out in minutes
Guolin Ke's avatar
Guolin Ke committed
701
  int time_out = 120;  // in minutes
Guolin Ke's avatar
Guolin Ke committed
702
703
704
705

  // alias=mlist
  // desc=file that lists machines for this parallel learning application
  // desc=each line contains one IP and one port for one machine. The format is ip port,separate by space
Guolin Ke's avatar
Guolin Ke committed
706
  std::string machine_list_filename = "";
Guolin Ke's avatar
Guolin Ke committed
707
708
709

  // alias=works,nodes
  // desc=list of machines, format: ip1:port1,ip2:port2
710
  std::string machines = "";
Guolin Ke's avatar
Guolin Ke committed
711

Guolin Ke's avatar
Guolin Ke committed
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
  #pragma endregion

  #pragma region GPU Parameters

  // desc=OpenCL platform ID. Usually each GPU vendor exposes one OpenCL platform
  // desc=default value is -1,means the system-wide default platform
  int gpu_platform_id = -1;

  // desc=OpenCL device ID in the specified platform. Each GPU in the selected platform has a unique device ID
  // desc=default value is -1,means the default device in the selected platform
  int gpu_device_id = -1;

  // desc=set to true to use double precision math on GPU (default using single precision)
  bool gpu_use_dp = false;

  #pragma endregion

  #pragma endregion
Guolin Ke's avatar
Guolin Ke committed
730
731
732

  bool is_parallel = false;
  bool is_parallel_find_bin = false;
Guolin Ke's avatar
Guolin Ke committed
733
734
735
  LIGHTGBM_EXPORT void Set(const std::unordered_map<std::string, std::string>& params);
  static std::unordered_map<std::string, std::string> alias_table;
  static std::unordered_set<std::string> parameter_set;
Guolin Ke's avatar
Guolin Ke committed
736
737
private:
  void CheckParamConflict();
Guolin Ke's avatar
Guolin Ke committed
738
739
  void GetMembersFromString(const std::unordered_map<std::string, std::string>& params);
  std::string SaveMembersToString() const;
Guolin Ke's avatar
Guolin Ke committed
740
741
};

Guolin Ke's avatar
Guolin Ke committed
742
inline bool Config::GetString(
Guolin Ke's avatar
Guolin Ke committed
743
744
745
746
747
748
749
750
751
  const std::unordered_map<std::string, std::string>& params,
  const std::string& name, std::string* out) {
  if (params.count(name) > 0) {
    *out = params.at(name);
    return true;
  }
  return false;
}

Guolin Ke's avatar
Guolin Ke committed
752
inline bool Config::GetInt(
Guolin Ke's avatar
Guolin Ke committed
753
754
755
  const std::unordered_map<std::string, std::string>& params,
  const std::string& name, int* out) {
  if (params.count(name) > 0) {
756
    if (!Common::AtoiAndCheck(params.at(name).c_str(), out)) {
757
      Log::Fatal("Parameter %s should be of type int, got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
758
                 name.c_str(), params.at(name).c_str());
759
    }
Guolin Ke's avatar
Guolin Ke committed
760
761
762
763
764
    return true;
  }
  return false;
}

Guolin Ke's avatar
Guolin Ke committed
765
inline bool Config::GetDouble(
Guolin Ke's avatar
Guolin Ke committed
766
  const std::unordered_map<std::string, std::string>& params,
767
  const std::string& name, double* out) {
Guolin Ke's avatar
Guolin Ke committed
768
  if (params.count(name) > 0) {
769
    if (!Common::AtofAndCheck(params.at(name).c_str(), out)) {
770
      Log::Fatal("Parameter %s should be of type double, got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
771
                 name.c_str(), params.at(name).c_str());
772
    }
Guolin Ke's avatar
Guolin Ke committed
773
774
775
776
777
    return true;
  }
  return false;
}

Guolin Ke's avatar
Guolin Ke committed
778
inline bool Config::GetBool(
Guolin Ke's avatar
Guolin Ke committed
779
780
781
782
  const std::unordered_map<std::string, std::string>& params,
  const std::string& name, bool* out) {
  if (params.count(name) > 0) {
    std::string value = params.at(name);
Guolin Ke's avatar
Guolin Ke committed
783
    std::transform(value.begin(), value.end(), value.begin(), Common::tolower);
784
    if (value == std::string("false") || value == std::string("-")) {
Guolin Ke's avatar
Guolin Ke committed
785
      *out = false;
786
    } else if (value == std::string("true") || value == std::string("+")) {
Guolin Ke's avatar
Guolin Ke committed
787
      *out = true;
788
    } else {
789
      Log::Fatal("Parameter %s should be \"true\"/\"+\" or \"false\"/\"-\", got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
790
                 name.c_str(), params.at(name).c_str());
Guolin Ke's avatar
Guolin Ke committed
791
792
793
794
795
796
797
798
799
800
    }
    return true;
  }
  return false;
}

struct ParameterAlias {
  static void KeyAliasTransform(std::unordered_map<std::string, std::string>* params) {
    std::unordered_map<std::string, std::string> tmp_map;
    for (const auto& pair : *params) {
Guolin Ke's avatar
Guolin Ke committed
801
802
803
      auto alias = Config::alias_table.find(pair.first);
      if (alias != Config::alias_table.end()) { // found alias
        auto alias_set = tmp_map.find(alias->second);
wxchan's avatar
wxchan committed
804
        if (alias_set != tmp_map.end()) { // alias already set
Guolin Ke's avatar
Guolin Ke committed
805
                                          // set priority by length & alphabetically to ensure reproducible behavior
wxchan's avatar
wxchan committed
806
807
          if (alias_set->second.size() < pair.first.size() ||
            (alias_set->second.size() == pair.first.size() && alias_set->second < pair.first)) {
808
            Log::Warning("%s is set with %s=%s, %s=%s will be ignored. Current value: %s=%s",
Guolin Ke's avatar
Guolin Ke committed
809
810
                         alias->second.c_str(), alias_set->second.c_str(), params->at(alias_set->second).c_str(),
                         pair.first.c_str(), pair.second.c_str(), alias->second.c_str(), params->at(alias_set->second).c_str());
wxchan's avatar
wxchan committed
811
          } else {
812
            Log::Warning("%s is set with %s=%s, will be overridden by %s=%s. Current value: %s=%s",
Guolin Ke's avatar
Guolin Ke committed
813
814
                         alias->second.c_str(), alias_set->second.c_str(), params->at(alias_set->second).c_str(),
                         pair.first.c_str(), pair.second.c_str(), alias->second.c_str(), pair.second.c_str());
wxchan's avatar
wxchan committed
815
816
817
818
819
            tmp_map[alias->second] = pair.first;
          }
        } else { // alias not set
          tmp_map.emplace(alias->second, pair.first);
        }
Guolin Ke's avatar
Guolin Ke committed
820
      } else if (Config::parameter_set.find(pair.first) == Config::parameter_set.end()) {
wxchan's avatar
wxchan committed
821
        Log::Warning("Unknown parameter: %s", pair.first.c_str());
Guolin Ke's avatar
Guolin Ke committed
822
823
824
      }
    }
    for (const auto& pair : tmp_map) {
wxchan's avatar
wxchan committed
825
826
827
828
829
      auto alias = params->find(pair.first);
      if (alias == params->end()) { // not find
        params->emplace(pair.first, params->at(pair.second));
        params->erase(pair.second);
      } else {
Guolin Ke's avatar
Guolin Ke committed
830
831
832
        Log::Warning("%s is set=%s, %s=%s will be ignored. Current value: %s=%s",
                     pair.first.c_str(), alias->second.c_str(), pair.second.c_str(), params->at(pair.second).c_str(),
                     pair.first.c_str(), alias->second.c_str());
Guolin Ke's avatar
Guolin Ke committed
833
834
835
836
837
838
839
      }
    }
  }
};

}   // namespace LightGBM

Guolin Ke's avatar
Guolin Ke committed
840
#endif   // LightGBM_CONFIG_H_