π DecisionTreeRegressor
The DecisionTreeRegressor
class implements a decision tree regressor that
supports numerical and categorical features, by default using MSE (minimum
squared error) to choose which feature to split on. The class offers several
template parameters and runtime options that can be used to control the behavior
of the tree.
The DecisionTreeRegressor
class is useful for regressions; i.e., predicting
continuous values (0.3
, 1.2
, etc.). For predicting discrete labels
(classification), see DecisionTree
.
Simple usage example:
Train a decision tree regressor on random numeric data and make predictions on a test set:
// Train a decision tree regressor on random numeric data and make predictions.
// All data and responses are uniform random; this uses 10 dimensional data.
// Replace with a data::Load() call or similar for a real application.
arma::mat dataset(10, 1000, arma::fill::randu); // 1000 points.
arma::rowvec responses = arma::randn<arma::rowvec>(1000);
arma::mat testDataset(10, 500, arma::fill::randu); // 500 test points.
mlpack::DecisionTreeRegressor tree; // Step 1: create tree.
tree.Train(dataset, responses); // Step 2: train model.
arma::rowvec predictions;
tree.Predict(testDataset, predictions); // Step 3: use model to predict.
// Print some information about the test predictions.
std::cout << arma::accu(predictions > 0.7) << " test points predicted to have"
<< " responses greater than 0.7." << std::endl;
std::cout << arma::accu(predictions < 0) << " test points predicted to have "
<< "negative responses." << std::endl;
Quick links:
 Constructors: create
DecisionTreeRegressor
objects. Train()
: train model.Predict()
: predict values with a trained model. Other functionality for loading, saving, and inspecting.
 Examples of simple usage and links to detailed example projects.
 Template parameters for custom behavior.
See also:
DecisionTree
 Random forests
 mlpack regression techniques
 Decision tree on Wikipedia
 Decision tree learning on Wikipedia
π Constructors
tree = DecisionTreeRegressor()
tree = DecisionTreeRegressor(data, responses, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
tree = DecisionTreeRegressor(data, responses, weights, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
 Train on numericalonly data (optionally with instance weights).
tree = DecisionTreeRegressor(data, datasetInfo, responses, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
tree = DecisionTreeRegressor(data, datasetInfo, responses, weights, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
 Train on mixed categorical data (optionally with instance weights).
Constructor parameters:
name  type  description  default 

data 
arma::mat 
Columnmajor training matrix.  (N/A) 
datasetInfo 
data::DatasetInfo 
Dataset information, specifying type information for each dimension.  (N/A) 
responses 
arma::rowvec 
Training responses (e.g. values to predict). Should have length data.n_cols . 
(N/A) 
weights 
arma::rowvec 
Weights for each training point. Should have length data.n_cols . 
(N/A) 
numClasses 
size_t 
Number of classes in the dataset.  (N/A) 
minLeafSize 
size_t 
Minimum number of points in each leaf node.  10 
minGainSplit 
double 
Minimum gain for a node to split.  1e7 
maxDepth 
size_t 
Maximum depth for the tree. (0 means no limit.)  0 
 Setting
minLeafSize
too small (e.g.1
) may cause the tree to overfit to its training data, and may create a very large tree. However, setting it too large may cause the tree to be very small and underfit. minGainSplit
has similar behavior: if it is too small, the tree may overfit; if too large, it may underfit.
Note: different types can be used for data
, responses
, and weights
(e.g., arma::fmat
, arma::sp_mat
). However, the element type of data
,
responses
, and weights
all must match; for example, if data
has type
arma::fmat
, then responses
and weights
must have type arma::frowvec
.
π Training
If training is not done as a part of the constructor call, it can be done with
one of the following versions of the Train()
member function:
tree.Train(data, responses, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
tree.Train(data, responses, weights, minLeafSize=10, minGainSplit=1e7, maxDepth=0)
 Train on numericalonly data (optionally with instance weights).
tree.Train(data, datasetInfo, responses)
tree.Train(data, datasetInfo, responses, weights)
tree.Train(data, datasetInfo, responses, minLeafSize, minGainSplit, maxDepth)
tree.Train(data, datasetInfo, responses, weights, minLeafSize, minGainSplit, maxDepth)
 Train on mixed categorical data (optionally with instance weights).
Types of each argument are the same as in the table for constructors above.
Notes:

Training is not incremental. A second call to
Train()
will retrain the decision tree from scratch. 
Train()
returns adouble
with the final gain of the tree (the Gini gain, unless a differentFitnessFunction
template parameter is specified.
π Prediction
Once a DecisionTreeRegressor
is trained, the Predict()
member function can
be used to make class predictions for new data.
double predictedValue = tree.Predict(point)
 (Singlepoint)
 Predict and return the value for a single point.
tree.Predict(data, predictions)
 (Multipoint)
 Predict and return values for every point in the given matrix
data
.  The predictions for each point are stored in
predictions
, which is set to lengthdata.n_cols
.  The prediction for data point
i
can be accessed withpredictions[i]
.
Prediction Parameters:
usage  name  type  description 

singlepoint  point 
arma::vec 
Single point for prediction. 
Β  Β  Β  Β 
multipoint  data 
arma::mat 
Set of columnmajor points for prediction. 
multipoint  predictions 
arma::rowvec& 
Vector to store predictions into. 
Note: different types can be used for data
and point
(e.g.
arma::fmat
, arma::sp_mat
, arma::sp_vec
, etc.). However, the element type
that is used should be the same type that was used for training.
π Other Functionality

A
DecisionTreeRegressor
can be serialized withdata::Save()
anddata::Load()
. 
tree.NumChildren()
will return asize_t
indicating the number of children in the nodetree
. 
tree.NumLeaves()
will return the total number of leaf nodes that are descendants of the nodetree
. 
tree.Child(i)
will return aDecisionTreeRegressor
object representing thei
th child of the nodetree
. 
tree.SplitDimension()
returns asize_t
indicating which dimension the nodetree
splits on.
For complete functionality, the source code can be consulted. Each method is fully documented.
π Simple Examples
See also the simple usage example for a trivial use of
DecisionTreeRegressor
.
Train a decision tree regressor on mixed categorical data and save the model to disk.
// Load a categorical dataset.
arma::mat data;
mlpack::data::DatasetInfo info;
// See https://datasets.mlpack.org/telecom_churn.arff.
mlpack::data::Load("telecom_churn.arff", data, info, true);
arma::rowvec responses;
// See https://datasets.mlpack.org/telecom_churn.responses.csv.
mlpack::data::Load("telecom_churn.responses.csv", responses, true);
// Split data into training set (80%) and test set (20%).
arma::mat trainData, testData;
arma::rowvec trainResponses, testResponses;
mlpack::data::Split(data, responses, trainData, testData, trainResponses,
testResponses, 0.2);
// Create the tree.
mlpack::DecisionTreeRegressor tree;
// Train on the given dataset, specifying a minimum gain of 1e6 and keeping the
// default minimum leaf size.
const double mse = tree.Train(trainData, info, trainResponses,
10 /* minimum leaf size */, 1e6 /* minimum gain */);
// Print the MSE of the trained tree.
std::cout << "MSE of trained tree is " << mse << "." << std::endl;
// Compute prediction on the first test point.
const double firstPrediction = tree.Predict(testData.col(0));
std::cout << "Predicted value for first test point is " << firstPrediction
<< "." << std::endl;
// Compute predictions on test data.
arma::rowvec testPredictions;
tree.Predict(testData, testPredictions);
// Compute the average error on the test set.
const double testAverageError = arma::mean(testResponses  testPredictions);
std::cout << "Average error on test set: " << testAverageError << "."
<< std::endl;
// Save the tree to "tree.bin" with the name "tree".
mlpack::data::Save("tree.bin", "tree", tree);
Load a tree and print some information about it.
mlpack::DecisionTreeRegressor tree;
// This call assumes a tree called "tree" has already been saved to `tree.bin`
// with `data::Save()`.
mlpack::data::Load("tree.bin", "tree", tree, true);
std::cout << "Information about the DecisionTreeRegressor in `tree.bin`:"
<< std::endl;
std::cout << " * The root node has " << tree.NumChildren() << " children."
<< std::endl;
std::cout << " * The tree has " << tree.NumLeaves() << " leaves." << std::endl;
if (tree.NumChildren() > 0)
{
for (size_t i = 0; i < tree.NumChildren(); ++i)
{
std::cout << " * Child " << i << " of the root has "
<< tree.Child(i).NumLeaves() << " leaves in its subtree." << std::endl;
}
}
π Advanced Functionality: Template Parameters
Using different element types.
DecisionTreeRegressor
βs constructors, Train()
, and Predict()
functions
support any data type, so long as it supports the Armadillo matrix API. So, for
instance, learning can be done on singleprecision floatingpoint data:
// 1000 random points in 10 dimensions.
arma::fmat dataset(10, 1000, arma::fill::randu);
// Random responses for each point, with a normal distribution.
arma::frowvec responses = arma::randn<arma::frowvec>(1000);
// Train in the constructor.
mlpack::DecisionTreeRegressor tree(dataset, responses, 5);
// Create test data (500 points).
arma::fmat testDataset(10, 500, arma::fill::randu);
arma::frowvec predictions;
tree.Predict(testDataset, predictions);
// Now `predictions` holds predictions for the test dataset.
// Print some information about the test predictions.
std::cout << arma::accu(predictions > 1) << " test points predicted to have "
<< "value greater than 1." << std::endl;
Fully custom behavior.
The DecisionTreeRegressor
class also supports several template parameters,
which can be used for custom behavior during learning. The full signature of
the class is as follows:
DecisionTreeRegressor<FitnessFunction,
NumericSplitType,
CategoricalSplitType,
DimensionSelectionType,
NoRecursion>
FitnessFunction
: the measure of goodness to use when deciding on tree splitsNumericSplitType
: the strategy used for finding splits on numeric data dimensionsCategoricalSplitType
: the strategy used for finding splits on categorical data dimensionsDimensionSelectionType
: the strategy used for proposing dimensions to attempt to split onNoRecursion
: a boolean indicating whether to build a tree or a stump (one level tree)
Below, details are given for the requirements of each of these template types.
FitnessFunction
 Specifies the fitness function to use when learning a decision tree.
 The
MSEGain
(default) andMADGain
classes are available for dropin usage.  A custom class must implement three functions:
// You can use this as a starting point for implementation.
class CustomFitnessFunction
{
// Compute the gain for the given vector of values, where `values[i]` has an
// associated instance weight `weights[i]`.
//
// `RowType` and `WeightVecType` will be vector types following the Armadillo
// API. If `UseWeights` is `false`, then the `weights` vector should be
// ignored (e.g. the responses are not weighted).
//
// In the version with `begin` and `end` parameters, only the subset between
// `labels[begin]` and `labels[end]` (inclusive) should be considered.
template<bool UseWeights, typename RowType, typename WeightVecType>
double Evaluate(const RowType& labels,
const WeightVecType& weights);
template<bool UseWeights, typename RowType, typename WeightVecType>
double Evaluate(const RowType& labels,
const WeightVecType& weights,
const size_t begin,
const size_t end);
// Return the output value for prediction for a leaf node whose training
// values are made up of the values in the vector `responses` (optionally with
// associated instance weights `weights`).
//
// `ResponsesType` and `WeightsType` will be vector types following the
// Armadillo API. If `UseWeights` is `false`, then the `weights` vector
// should be ignored (e.g. the responses are not weighted).
template<bool UseWeights, typename ResponsesType, typename WeightsType>
double OutputLeafValue(const ResponsesType& responses,
const WeightsType& weights);
};
Note: this API differs from the FitnessFunction
API required for
DecisionTree
!
NumericSplitType
 Specifies the strategy to be used during training when splitting a numeric feature.
 The
BestBinaryNumericSplit
(default) class is available for dropin usage and finds the best binary (twoway) split among all possible binary splits.  The
RandomBinaryNumericSplit
class is available for dropin usage and will select a split randomly between the minimum and maximum values of a dimension. It is very efficient but does not yield splits that maximize the gain. (Used by theExtraTrees
variant ofRandomForest
.)  A custom class must take a
FitnessFunction
as a template parameter, implement three functions, and have an internal structureAuxiliarySplitInfo
that is used at classification time:
class CustomNumericSplit
{
public:
// If a split with better resulting gain than `bestGain` is found, then
// information about the new, better split should be stored in `splitInfo` and
// `aux`. Specifically, a split is better than `bestGain` if the sum of the
// gains that the children will have (call this `sumChildrenGains`) is
// sufficiently better than the gain of the unsplit node (call this
// `unsplitGain`):
//
// split if `sumChildrenGains  unsplitGain > bestGain`, and
// `sumChildrenGains  unsplitGain > minGainSplit`, and
// each child will have at least `minLeafSize` points
//
// The new best split value should be returned (or anything greater than or
// equal to `bestGain` if no better split is found).
//
// If a new best split is found, then `splitInfo` and `aux` should be
// populated with the information that will be needed for
// `CalculateDirection()` to successfully choose the child for a given point.
// `splitInfo` should be set to a vector of length 1. The format of `aux` is
// arbitrary and is detailed more below.
//
// If `UseWeights` is false, the vector `weights` should be ignored.
// Otherwise, they are instance weighs for each value in `data` (one dimension
// of the input data).
template<bool UseWeights, typename VecType, typename ResponsesType,
typename WeightVecType>
double SplitIfBetter(const double bestGain,
const VecType& data,
const ResponsesType& responses,
const WeightVecType& weights,
const size_t minLeafSize,
const double minGainSplit,
arma::vec& splitInfo,
AuxiliarySplitInfo& aux,
FitnessFunction& function);
// Return the number of children for a given split. If there was no split,
// return zero. `splitInfo` and `aux` contain the split information, as set
// in `SplitIfBetter`.
size_t NumChildren(const arma::vec& splitInfo,
const AuxiliarySplitInfo& aux);
// Given a point with value `point`, and split information `splitInfo` and
// `aux`, return the index of the child that corresponds to the point. So,
// e.g., if the split type was a binary split on the value `splitInfo`, you
// might return `0` if `point < splitInfo`, and `1` otherwise.
template<typename ElemType>
static size_t CalculateDirection(
const ElemType& point,
const double& splitInfo,
const AuxiliarySplitInfo& /* aux */);
// This class can hold any extra data that is necessary to encode a split. It
// should only be nonempty if a single `double` value cannot be used to hold
// the information corresponding to a split.
class AuxiliarySplitInfo { };
};
Note: this API differs from the NumericSplitType
API required for
DecisionTree
!
CategoricalSplitType
 Specifies the strategy to be used during training when splitting a categorical feature.
 The
AllCategoricalSplit
(default) andBestBinaryCategoricalSplit
are~ available for dropin usage. AllCategoricalSplit
, the default ID3 split algorithm, splits all categories into their own node. This variant is simple, and has complexityO(n)
, wheren
is the number of samples.BestBinaryCategoricalSplit
is the preferred algorithm of the CART system. It will find the the best (entropyminimizing) binary partition of the categories. This algorithm has complexityO(n lg n)
in the case of binary outcomes, but is exponential in the number of categories when there are more than two classes. Note:
BestBinaryCategoricalSplit
should not be chosen when there are multiple classes and many categories.  Note: for regression tasks,
W. Fisherβs proof of correctness
only applies to when
FitnessFunction
isMSEGain
; therefore,BestBinaryCategoricalSplit
requires the use ofMSEGain
.
 Note:
 A custom class must take a
FitnessFunction
as a template parameter, implement three functions, and have an internal structureAuxiliarySplitInfo
that is used at classification time:
class CustomCategoricalSplit
{
public:
// If a split with better resulting gain than `bestGain` is found, then
// information about the new, better split should be stored in `splitInfo` and
// `aux`. Specifically, a split is better than `bestGain` if the sum of the
// gains that the children will have (call this `sumChildrenGains`) is
// sufficiently better than the gain of the unsplit node (call this
// `unsplitGain`):
//
// split if `sumChildrenGains  unsplitGain > bestGain`, and
// `sumChildrenGains  unsplitGain > minGainSplit`, and
// each child will have at least `minLeafSize` points
//
// The new best split value should be returned (or anything greater than or
// equal to `bestGain` if no better split is found).
//
// If a new best split is found, then `splitInfo` and `aux` should be
// populated with the information that will be needed for
// `CalculateDirection()` to successfully choose the child for a given point.
// `splitInfo` should be set to a nonempty vector. The format of `aux` is
// arbitrary and is detailed more below.
//
// If `UseWeights` is false, the vector `weights` should be ignored.
// Otherwise, they are instance weighs for each value in `data` (one
// categorical dimension of the input data, which takes values between `0` and
// `numCategories  1`).
template<bool UseWeights, typename VecType, typename ResponsesType,
typename WeightVecType>
static double SplitIfBetter(
const double bestGain,
const VecType& data,
const size_t numCategories,
const ResponsesType& labels,
const WeightVecType& weights,
const size_t minLeafSize,
const double minGainSplit,
arma::vec& splitInfo,
AuxiliarySplitInfo& aux,
FitnessFunction& fitnessFunction);
// Return the number of children for a given split. If there was no split,
// return zero. `splitInfo` and `aux` contain the split information, as set
// in `SplitIfBetter`.
size_t NumChildren(const arma::vec& splitInfo,
const AuxiliarySplitInfo& aux);
// Given a point with (categorical) value `point`, and split information
// `splitInfo` and `aux`, return the index of the child that corresponds to
// the point. So, e.g., for `AllCategoricalSplit`, which splits a categorical
// dimension into one child for each category, this simply returns `point`.
template<typename ElemType>
static size_t CalculateDirection(
const ElemType& point,
const double& splitInfo,
const AuxiliarySplitInfo& /* aux */);
// This class can hold any extra data that is necessary to encode a split. It
// should only be nonempty if a single `double` value cannot be used to hold
// the information corresponding to a split.
class AuxiliarySplitInfo { };
};
Note: this API differs from the CategoricalSplitType
API required for
DecisionTree
!
DimensionSelectionType
 When splitting a decision tree,
DimensionSelectionType
proposes possible dimensions to try splitting on. AllDimensionSplit
(default) is available for dropin usage and proposes all dimensions for splits.MultipleRandomDimensionSelect
proposes a different random subset of dimensions at each decision tree node. By default each random subset is of size
sqrt(d)
whered
is the number of dimensions in the data.  If constructed as
MultipleRandomDimensionSelect(n)
and passed to the constructor ofDecisionTree<>
or theTrain()
function, each random subset will be of sizen
.
 By default each random subset is of size
 Each
DecisionTreeRegressor
constructor and each version of theTrain()
function optionally accept an instantiatedDimensionSelectionType
object as the very last parameter (aftermaxDepth
), in case some internal state in the dimension selection mechanism is required.  A custom class must implement three simple functions:
class CustomDimensionSelect
{
public:
// Get the first dimension to try.
// This should return a value between `0` and `data.n_rows`.
size_t Begin();
// Get the next dimension to try. Note that internal state can be used to
// track which candidate dimension is currently being looked at.
// This should return a value between `0` and `data.n_rows`.
size_t Next();
// Get a value indicating that all dimensions have been tried.
size_t End() const;
// The usage pattern of `DimensionSelectionType` by `DecisionTree` is as
// follows, assuming that `dim` is an instantiated `DimensionSelectionType`
// object:
//
// for (size_t dim = dim.Begin(); dim != dim.End(); dim = dim.Next())
// {
// // ... try to split on dimension `dim` ...
// }
};
NoRecursion
 A
bool
value that indicates whether a decision tree should be constructed recursively.  If
true
, only the root node will be split (producing a decision stump).  If
false
(default), a full decision tree will be built.