config.h 34.2 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
143
144
145
  // alias = test, valid_data, test_data, valid_filenames
  // 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
366
367
368
369
370
  std::string forcedsplits_filename = "";

  #pragma endregion

  #pragma region IO Parameters

  // 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 max_bin.
  // desc=For example, LightGBM will use uint8_t for feature value if max_bin = 255
371
  int max_bin = 255;
Guolin Ke's avatar
Guolin Ke committed
372
373
374
375
376
377

  // check=>0
  // desc=min number of data inside one bin,use this to avoid one-data-one-bin (may over-fitting)
  int min_data_in_bin = 3;

  // desc=random seed for data partition in parallel learning (not include feature parallel)
Guolin Ke's avatar
Guolin Ke committed
378
  int data_random_seed = 1;
Guolin Ke's avatar
Guolin Ke committed
379
380
381

  // alias=model_output,model_out
  // desc=file name of output model in training
Guolin Ke's avatar
Guolin Ke committed
382
  std::string output_model = "LightGBM_model.txt";
Guolin Ke's avatar
Guolin Ke committed
383
384
385
386
387

  // alias = model_input, model_in
  // desc=file name of input model
  // desc=for prediction task,this model will be used for prediction data
  // desc=for train task,training will be continued from this model
Guolin Ke's avatar
Guolin Ke committed
388
  std::string input_model = "";
389

Guolin Ke's avatar
Guolin Ke committed
390
391
392
393
394
395
396
397
398
399
400
  // alias=predict_result,prediction_result
  // desc=file name of prediction result in prediction task
  std::string output_result = "LightGBM_predict_result.txt";

  // alias = is_pre_partition
  // desc=used for parallel learning (not include feature parallel)
  // desc=true if training data are pre-partitioned,and different machines use different partitions
  bool pre_partition = false;

  // alias = is_sparse, enable_sparse
  // desc = used to enable / disable sparse optimization.Set to false to disable sparse optimization
Guolin Ke's avatar
Guolin Ke committed
401
  bool is_enable_sparse = true;
Guolin Ke's avatar
Guolin Ke committed
402
403
404
405

  // check=>0
  // check=<=1
  // desc=the threshold of zero elements precentage for treating a feature as a sparse feature.
406
  double sparse_threshold = 0.8;
Guolin Ke's avatar
Guolin Ke committed
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431

  // alias=two_round_loading,use_two_round_loading
  // desc = by default, LightGBM will map data file to memory and load features from memory.
  // desc = This will provide faster data loading speed.But it may run out of memory when the data file is very big
  // desc = set this to true if data file is too big to fit in memory
  bool two_round = false;

  // alias = is_save_binary, is_save_binary_file
  // desc = if true LightGBM will save the dataset(include validation data) to a binary file.
  // desc = Speed up the data loading for the next time
  bool save_binary = false;

  // alias=verbose
  // desc= <0 = Fatal, =0 = Error(Warn), >0 = Info
  int verbosity = 1;

  // alias = has_header
  // desc=set this to true if input data has header
  bool header = false;


  // alias=label
  // desc=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
432
  std::string label_column = "";
Guolin Ke's avatar
Guolin Ke committed
433
434
435
436
437
438

  // alias=weight
  // desc=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 Index,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
439
  std::string weight_column = "";
Guolin Ke's avatar
Guolin Ke committed
440
441
442
443
444
445

  // alias = query_column, group, query
  // desc=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. Index starts from 0. And it doesn't count the label column when passing type is Index,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
446
  std::string group_column = "";
Guolin Ke's avatar
Guolin Ke committed
447
448
449
450
451
452
453

  // alias = ignore_feature, blacklist
  // desc=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
Guolin Ke's avatar
Guolin Ke committed
454
  std::string ignore_column = "";
455

Guolin Ke's avatar
Guolin Ke committed
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
  // alias=categorical_column,cat_feature,cat_column
  // desc=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. Index starts from 0. And it doesn't count the label column
  // desc=**Note**: the negative values will be treated as **missing values**
  std::string categorical_feature = "";

  // alias=raw_score,is_predict_raw_score,predict_rawscore
  // desc=only used in prediction task
  // desc=set to true to predict only the raw scores
  // desc=set to false to predict transformed scores
  bool predict_raw_score = false;

  // alias=leaf_index,is_predict_leaf_index
  // desc=only used in prediction task
  // desc=set to true to predict with leaf index of all trees
  bool predict_leaf_index = false;

  // alias=contrib,is_predict_contrib
  // desc=only used in prediction task
  // desc=set to true to estimate `SHAP values`_,which represent how each feature contributs to each prediction.
  // desc=Produces number of features + 1 values where the last value is the expected value of the model output over the training data
  bool predict_contrib = false;

  // desc=only used in prediction task
  // desc=use to specify how many trained iterations will be used in prediction
  // desc=<= 0 means no limit
  int num_iteration_predict = -1;

  // desc=if true will use early-stopping to speed up the prediction. May affect the accuracy
487
  bool pred_early_stop = false;
Guolin Ke's avatar
Guolin Ke committed
488
489
  
  // desc=the frequency of checking early-stopping prediction
490
  int pred_early_stop_freq = 10;
Guolin Ke's avatar
Guolin Ke committed
491
492

  // desc = the threshold of margin in early - stopping prediction
Guolin Ke's avatar
Guolin Ke committed
493
  double pred_early_stop_margin = 10.0;
Guolin Ke's avatar
Guolin Ke committed
494
495
496
497
498
499
500
501
502

  // alias=subsample_for_bin
  // check=>0
  // desc=number of data that sampled to construct histogram bins
  // desc=will give better training result when set this larger,but will increase data loading time
  // desc=set this to larger value if data is very sparse
  int bin_construct_sample_cnt = 200000;

  // desc=set to false to disable the special handle of missing value
Guolin Ke's avatar
Guolin Ke committed
503
  bool use_missing = true;
Guolin Ke's avatar
Guolin Ke committed
504

Guolin Ke's avatar
Guolin Ke committed
505
506
507
508
509
510
511
512
513
  // desc=set to true to treat all zero as missing values (including the unshown values in libsvm/sparse matrics)
  // desc=set to false to use na to represent missing values
  bool zero_as_missing = false;

  // alias=init_score_filename,init_score_file,init_score
  // desc = path to training initial score file, "" will use train_data_file + .init(if exists)
  std::string initscore_filename = "";

  // alias=valid_data_init_scores,valid_init_score_file,valid_init_score
514
  // default=""
Guolin Ke's avatar
Guolin Ke committed
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
  // desc=path to validation initial score file,"" will use valid_data_file + .init (if exists)
  // desc=separate by ,for multi-validation data
  std::vector<std::string> valid_data_initscores;
  
  // desc=max cache size(unit:MB) for historical histogram. < 0 means no limit
  double histogram_pool_size = -1.0;

  // desc=set to true to enable auto loading from previous saved binary datasets
  // desc=set to false will ignore the binary datasets
  bool enable_load_from_binary_file = true;

  // desc=set to false to disable Exclusive Feature Bundling (EFB), which is described in LightGBM NIPS2017 paper
  // desc=disable this may cause the slow training speed for sparse datasets
  bool enable_bundle = true;
  
  // check=>=0
  // check=<1
  // desc=max conflict rate for bundles in EFB
  // desc=set to zero will diallow the conflict, and provide more accurace results
  // desc=the speed may be faster if set it to a larger value
  double max_conflict_rate = 0.0;

  // desc=frequency of saving model file snapshot
  // desc=set to positive numbers will enable this function
  // desc=for example, the model file will be snopshoted at each iteration if set it to 1 
  int snapshot_freq = -1;

  // desc=only cpp is supported yet
  // desc=if convert_model_language is set when task is set to train,the model will also be converted
  std::string convert_model_language = "";

  // desc=output file name of converted model
  std::string convert_model = "gbdt_prediction.cpp";
  #pragma endregion


  #pragma region Objective Parameters
  
  // alias=num_classes
  // desc=need to specify this in multi-class classification
  int num_class = 1;

  // check=>0
  // desc=parameter for sigmoid function. Will be used in binary and multiclassova classification and in lambdarank
Guolin Ke's avatar
Guolin Ke committed
559
  double sigmoid = 1.0;
Guolin Ke's avatar
Guolin Ke committed
560
561
562
563
564

  // desc=parameter for `Huber loss`_ and `Quantile regression`_. Will be used in regression task
  double alpha = 0.9;

  // desc=parameter for `Fair loss`_. Will be used in regression task
Guolin Ke's avatar
Guolin Ke committed
565
  double fair_c = 1.0;
Guolin Ke's avatar
Guolin Ke committed
566
567

  // desc=parameter for `Poisson regression`_ to safeguard optimization
Guolin Ke's avatar
Guolin Ke committed
568
  double poisson_max_delta_step = 0.7;
Guolin Ke's avatar
Guolin Ke committed
569
570
571
572
573
574
575
576

  // desc=only used in regression task
  // desc=adjust initial score to the mean of labels for faster convergence
  bool boost_from_average = true;

  // alias=unbalanced_sets
  // desc=used in binary classification
  // desc=set this to true if training data are unbalance
Guolin Ke's avatar
Guolin Ke committed
577
  bool is_unbalance = false;
Guolin Ke's avatar
Guolin Ke committed
578
579
580

  // check=>0
  // desc=weight of positive class in binary classification task
Guolin Ke's avatar
Guolin Ke committed
581
  double scale_pos_weight = 1.0;
Guolin Ke's avatar
Guolin Ke committed
582
583
584

  // desc=only used in regression, usually works better for the large-range of labels
  // desc=will fit sqrt(label) instead and prediction result will be also automatically converted to pow2(prediction)
585
  bool reg_sqrt = false;
Guolin Ke's avatar
Guolin Ke committed
586

Guolin Ke's avatar
Guolin Ke committed
587
588
589
590
  // desc=only used in tweedie regression
  // desc=controls the variance of the tweedie distribution
  // desc=set closer to 2 to shift towards a gamma distribution
  // desc=set closer to 1 to shift towards a poisson distribution
Guolin Ke's avatar
Guolin Ke committed
591
  double tweedie_variance_power = 1.5;
Guolin Ke's avatar
Guolin Ke committed
592

Guolin Ke's avatar
Guolin Ke committed
593
594
595
596
597
  // default = 0, 1, 3, 7, 15, 31, 63, ..., 2 ^ 30 - 1
  // desc=used in lambdarank
  // desc=relevant gain for labels. For example,the gain of label 2 is 3 if using default label gains
  // desc=separate by ,
  std::vector<double> label_gain;
Guolin Ke's avatar
Guolin Ke committed
598

Guolin Ke's avatar
Guolin Ke committed
599
600
601
602
  // check=>0
  // desc=used in lambdarank
  // desc=will optimize `NDCG`_ at this position
  int max_position = 20;
Guolin Ke's avatar
Guolin Ke committed
603

Guolin Ke's avatar
Guolin Ke committed
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
  #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
646
  bool is_provide_training_metric = false;
647

Guolin Ke's avatar
Guolin Ke committed
648
649
650
651
  // 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
652

Guolin Ke's avatar
Guolin Ke committed
653
654
655
656
657
658
659
  #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
660
  int num_machines = 1;
Guolin Ke's avatar
Guolin Ke committed
661
662
663
664

  // 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
665
  int local_listen_port = 12400;
Guolin Ke's avatar
Guolin Ke committed
666
667

  // desc=socket time-out in minutes
Guolin Ke's avatar
Guolin Ke committed
668
  int time_out = 120;  // in minutes
Guolin Ke's avatar
Guolin Ke committed
669
670
671
672

  // 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
673
  std::string machine_list_filename = "";
Guolin Ke's avatar
Guolin Ke committed
674
675
676

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

Guolin Ke's avatar
Guolin Ke committed
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
  #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
697
698
699

  bool is_parallel = false;
  bool is_parallel_find_bin = false;
Guolin Ke's avatar
Guolin Ke committed
700
701
702
  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
703
704
private:
  void CheckParamConflict();
Guolin Ke's avatar
Guolin Ke committed
705
706
  void GetMembersFromString(const std::unordered_map<std::string, std::string>& params);
  std::string SaveMembersToString() const;
Guolin Ke's avatar
Guolin Ke committed
707
708
};

Guolin Ke's avatar
Guolin Ke committed
709
inline bool Config::GetString(
Guolin Ke's avatar
Guolin Ke committed
710
711
712
713
714
715
716
717
718
  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
719
inline bool Config::GetInt(
Guolin Ke's avatar
Guolin Ke committed
720
721
722
  const std::unordered_map<std::string, std::string>& params,
  const std::string& name, int* out) {
  if (params.count(name) > 0) {
723
    if (!Common::AtoiAndCheck(params.at(name).c_str(), out)) {
724
      Log::Fatal("Parameter %s should be of type int, got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
725
                 name.c_str(), params.at(name).c_str());
726
    }
Guolin Ke's avatar
Guolin Ke committed
727
728
729
730
731
    return true;
  }
  return false;
}

Guolin Ke's avatar
Guolin Ke committed
732
inline bool Config::GetDouble(
Guolin Ke's avatar
Guolin Ke committed
733
  const std::unordered_map<std::string, std::string>& params,
734
  const std::string& name, double* out) {
Guolin Ke's avatar
Guolin Ke committed
735
  if (params.count(name) > 0) {
736
    if (!Common::AtofAndCheck(params.at(name).c_str(), out)) {
737
      Log::Fatal("Parameter %s should be of type double, got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
738
                 name.c_str(), params.at(name).c_str());
739
    }
Guolin Ke's avatar
Guolin Ke committed
740
741
742
743
744
    return true;
  }
  return false;
}

Guolin Ke's avatar
Guolin Ke committed
745
inline bool Config::GetBool(
Guolin Ke's avatar
Guolin Ke committed
746
747
748
749
  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
750
    std::transform(value.begin(), value.end(), value.begin(), Common::tolower);
751
    if (value == std::string("false") || value == std::string("-")) {
Guolin Ke's avatar
Guolin Ke committed
752
      *out = false;
753
    } else if (value == std::string("true") || value == std::string("+")) {
Guolin Ke's avatar
Guolin Ke committed
754
      *out = true;
755
    } else {
756
      Log::Fatal("Parameter %s should be \"true\"/\"+\" or \"false\"/\"-\", got \"%s\"",
Guolin Ke's avatar
Guolin Ke committed
757
                 name.c_str(), params.at(name).c_str());
Guolin Ke's avatar
Guolin Ke committed
758
759
760
761
762
763
764
765
766
767
    }
    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
768
769
770
      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
771
        if (alias_set != tmp_map.end()) { // alias already set
Guolin Ke's avatar
Guolin Ke committed
772
                                          // set priority by length & alphabetically to ensure reproducible behavior
wxchan's avatar
wxchan committed
773
774
          if (alias_set->second.size() < pair.first.size() ||
            (alias_set->second.size() == pair.first.size() && alias_set->second < pair.first)) {
775
            Log::Warning("%s is set with %s=%s, %s=%s will be ignored. Current value: %s=%s",
Guolin Ke's avatar
Guolin Ke committed
776
777
                         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
778
          } else {
779
            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
780
781
                         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
782
783
784
785
786
            tmp_map[alias->second] = pair.first;
          }
        } else { // alias not set
          tmp_map.emplace(alias->second, pair.first);
        }
Guolin Ke's avatar
Guolin Ke committed
787
      } else if (Config::parameter_set.find(pair.first) == Config::parameter_set.end()) {
wxchan's avatar
wxchan committed
788
        Log::Warning("Unknown parameter: %s", pair.first.c_str());
Guolin Ke's avatar
Guolin Ke committed
789
790
791
      }
    }
    for (const auto& pair : tmp_map) {
wxchan's avatar
wxchan committed
792
793
794
795
796
      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
797
798
799
        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
800
801
802
803
804
805
806
      }
    }
  }
};

}   // namespace LightGBM

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