001/*
002 * Copyright (c) 2015-2020, Oracle and/or its affiliates. All rights reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.tribuo.classification.xgboost;
018
019import com.oracle.labs.mlrg.olcut.config.Option;
020import org.tribuo.Trainer;
021import org.tribuo.classification.ClassificationOptions;
022import org.tribuo.common.xgboost.XGBoostTrainer;
023
024import java.util.logging.Level;
025import java.util.logging.Logger;
026
027/**
028 * CLI options for training an XGBoost classifier.
029 */
030public class XGBoostOptions implements ClassificationOptions<XGBoostClassificationTrainer> {
031    private static final Logger logger = Logger.getLogger(XGBoostOptions.class.getName());
032
033    /**
034     * Weak learning algorithm.
035     */
036    @Option(longName = "xgb-booster-type", usage = "Weak learning algorithm.")
037    public XGBoostTrainer.BoosterType xgbBoosterType = XGBoostTrainer.BoosterType.GBTREE;
038    /**
039     * Tree building algorithm.
040     */
041    @Option(longName = "xgb-tree-method", usage = "Tree building algorithm.")
042    public XGBoostTrainer.TreeMethod xgbTreeMethod = XGBoostTrainer.TreeMethod.AUTO;
043    /**
044     * Number of trees in the ensemble.
045     */
046    @Option(longName = "xgb-ensemble-size", usage = "Number of trees in the ensemble.")
047    public int xgbEnsembleSize = -1;
048    /**
049     * L1 regularization term for weights.
050     */
051    @Option(longName = "xgb-alpha", usage = "L1 regularization term for weights.")
052    public float xbgAlpha = 0.0f;
053    /**
054     * Minimum sum of instance weights needed in a leaf (range [0,Infinity]).
055     */
056    @Option(longName = "xgb-min-weight", usage = "Minimum sum of instance weights needed in a leaf (range [0,Infinity]).")
057    public float xgbMinWeight = 1;
058    /**
059     * Max tree depth (range (0,Integer.MAX_VALUE]).
060     */
061    @Option(longName = "xgb-max-depth", usage = "Max tree depth (range (0,Integer.MAX_VALUE]).")
062    public int xgbMaxDepth = 6;
063    /**
064     * Step size shrinkage parameter (range [0,1]).
065     */
066    @Option(longName = "xgb-eta", usage = "Step size shrinkage parameter (range [0,1]).")
067    public float xgbEta = 0.3f;
068    /**
069     * Subsample features for each tree (range (0,1]).
070     */
071    @Option(longName = "xgb-subsample-features", usage = "Subsample features for each tree (range (0,1]).")
072    public float xgbSubsampleFeatures = 0.0f;
073    /**
074     * Minimum loss reduction to make a split (range [0,Infinity]).
075     */
076    @Option(longName = "xgb-gamma", usage = "Minimum loss reduction to make a split (range [0,Infinity]).")
077    public float xgbGamma = 0.0f;
078    /**
079     * L2 regularization term for weights.
080     */
081    @Option(longName = "xgb-lambda", usage = "L2 regularization term for weights.")
082    public float xgbLambda = 1.0f;
083    /**
084     * Deprecated, use xgb-loglevel.
085     */
086    @Option(longName = "xgb-quiet", usage = "Deprecated, use xgb-loglevel.")
087    public boolean xgbQuiet;
088    /**
089     * Make the XGBoost training procedure quiet.
090     */
091    @Option(longName = "xgb-loglevel", usage = "Make the XGBoost training procedure quiet.")
092    public XGBoostTrainer.LoggingVerbosity xgbLogLevel = XGBoostTrainer.LoggingVerbosity.WARNING;
093    /**
094     * Subsample size for each tree (range (0,1]).
095     */
096    @Option(longName = "xgb-subsample", usage = "Subsample size for each tree (range (0,1]).")
097    public float xgbSubsample = 1.0f;
098    /**
099     * Number of threads to use (range (1, num hw threads)). The default of 0 means use all hw threads.
100     */
101    @Option(longName = "xgb-num-threads", usage = "Number of threads to use (range (1, num hw threads)). The default of 0 means use all hw threads.")
102    public int xgbNumThreads = 0;
103    @Option(longName = "xgb-seed", usage = "Sets the random seed for XGBoost.")
104    private long xgbSeed = Trainer.DEFAULT_SEED;
105
106    @Override
107    public XGBoostClassificationTrainer getTrainer() {
108        if (xgbEnsembleSize == -1) {
109            throw new IllegalArgumentException("Please supply the number of trees.");
110        }
111        if (xgbQuiet) {
112            logger.log(Level.WARNING, "Silencing XGBoost, overriding logging verbosity. Please switch to the 'xgb-loglevel' argument.");
113            xgbLogLevel = XGBoostTrainer.LoggingVerbosity.SILENT;
114        }
115        return new XGBoostClassificationTrainer(xgbBoosterType, xgbTreeMethod, xgbEnsembleSize, xgbEta, xgbGamma, xgbMaxDepth, xgbMinWeight, xgbSubsample, xgbSubsampleFeatures, xgbLambda, xbgAlpha, xgbNumThreads, xgbLogLevel, xgbSeed);
116    }
117}