# fitctree

Fit classification tree

## Syntax

• `tree = fitctree(X,Y)` example
• `tree = fitctree(X,Y,Name,Value)` example

## Description

example

````tree = fitctree(X,Y)` returns a classification tree based on the input variables (also known as predictors, features, or attributes) `X` and output (response or labels) `Y`. The returned tree is a binary tree, where each branching node is split based on the values of a column of `X`.```

example

````tree = fitctree(X,Y,Name,Value)` fits a tree with additional options specified by one or more name-value pair arguments. For example, you can specify the algorithm used to find the best split on a categorical predictor, grow a cross-validated tree, or hold out a fraction of the input data for validation.```

## Examples

collapse all

### Grow a Classification Tree

Grow a classification tree using the `ionosphere` data set.

```load ionosphere tc = fitctree(X,Y) ```
```tc = ClassificationTree PredictorNames: {1x34 cell} ResponseName: 'Y' ClassNames: {'b' 'g'} ScoreTransform: 'none' CategoricalPredictors: [] NumObservations: 351 ```

### Control Tree Depth

You can control the depth of the trees using the `MaxNumSplits`, `MinLeafSize`, or `MinParentSize` name-value pair parameters. `fitctree` grows deep decision trees by default. You can grow shallower trees to reduce model complexity or computation time.

Load the `ionosphere` data set.

```load ionosphere ```

The default values of the tree depth controllers for growing classification trees are:

• `n - 1` for `MaxNumSplits`. `n` is the training sample size.

• `1` for `MinLeafSize`.

• `10` for `MinParentSize`.

These default values tend to grow deep trees for large training sample sizes.

Train a classification tree using the default values for tree depth control. Cross validate the model using 10-fold cross validation.

```rng(1); % For reproducibility MdlDefault = fitctree(X,Y,'CrossVal','on'); ```

Draw a histogram of the number of imposed on the trees. Also, view one of the trees.

```numBranches = @(x)sum(x.IsBranch); mdlDefaultNumSplits = cellfun(numBranches, MdlDefault.Trained); figure; histogram(mdlDefaultNumSplits) view(MdlDefault.Trained{1},'Mode','graph') ```

The average number of splits is around 15.

Suppose that you want a classification tree that is not as complex (deep) as the ones trained using the default number of splits. Train another classification tree, but set the maximum number of splits at 7, which is about half the mean number of splits from the default classification tree. Cross validate the model using 10-fold cross validation.

```Mdl7 = fitctree(X,Y,'MaxNumSplits',7,'CrossVal','on'); view(Mdl7.Trained{1},'Mode','graph') ```

Compare the cross validation classification errors of the models.

```classErrorDefault = kfoldLoss(MdlDefault) classError7 = kfoldLoss(Mdl7) ```
```classErrorDefault = 0.1140 classError7 = 0.1254 ```

`Mdl7` is much less complex and performs only slightly worse than `MdlDefault`.

## Input Arguments

collapse all

### `X` — Predictor valuesmatrix of floating-point values

Predictor values, specified as a matrix of floating-point values.

`fitctree` considers `NaN` values in `X` as missing values. `fitctree` does not use observations with all missing values for `X` in the fit. `fitctree` uses observations with some missing values for `X` to find splits on variables for which these observations have valid values.

Data Types: `single` | `double`

### `Y` — Class labelsnumeric vector | categorical vector | logical vector | character array | cell array of strings

Class labels, specified as a numeric vector, categorical vector, logical vector, character array, or cell array of strings.

Each row of `X` represents the classification of the corresponding row of `X`. For numeric `Y`, consider using `fitrtree` instead. `fitctree` considers `NaN`, `''` (empty string), and `<undefined>` values in `Y` to be missing values.

`fitctree` does not use observations with missing values for `Y` in the fit.

Data Types: `single` | `double` | `char` | `logical` | `cell`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'CrossVal','on','MinLeafSize',40` specifies a cross-validated classification tree with a minimum of 40 observations per leaf.

### `'AlgorithmForCategorical'` — Algorithm for best categorical predictor split`'Exact'` | `'PullLeft'` | `'PCA'` | `'OVAbyClass'`

Algorithm to find the best split on a categorical predictor with C categories for data and K ≥ 3 classes, specified as the comma-separated pair consisting of `'AlgorithmForCategorical'` and one of the following.

 `'Exact'` Consider all 2C–1 – 1 combinations. `'PullLeft'` Start with all C categories on the right branch. Consider moving each category to the left branch as it achieves the minimum impurity for the K classes among the remaining categories. From this sequence, choose the split that has the lowest impurity. `'PCA'` Compute a score for each category using the inner product between the first principal component of a weighted covariance matrix (of the centered class probability matrix) and the vector of class probabilities for that category. Sort the scores in ascending order, and consider all C – 1 splits. `'OVAbyClass'` Start with all C categories on the right branch. For each class, order the categories based on their probability for that class. For the first class, consider moving each category to the left branch in order, recording the impurity criterion at each move. Repeat for the remaining classes. From this sequence, choose the split that has the minimum impurity.

`fitctree` automatically selects the optimal subset of algorithms for each split using the known number of classes and levels of a categorical predictor. For K = 2 classes, `fitctree` always performs the exact search. Use the `'AlgorithmForCategorical'` name-value pair argument to specify a particular algorithm.

Example: `'AlgorithmForCategorical','PCA'`

### `'CategoricalPredictors'` — Categorical predictors listnumeric or logical vector | cell array of strings | character matrix | `'all'`

Categorical predictors list, specified as the comma-separated pair consisting of `'CategoricalPredictors'` and one of the following:

• A numeric vector with indices from `1` through `p`, where `p` is the number of columns of `X`.

• A logical vector of length `p`, where a `true` entry means that the corresponding column of `X` is a categorical variable.

• A cell array of strings, where each element in the array is the name of a predictor variable. The names must match entries in `PredictorNames` values.

• A character matrix, where each row of the matrix is a name of a predictor variable. The names must match entries in `PredictorNames` values. Pad the names with extra blanks so each row of the character matrix has the same length.

• `'all'`, meaning all predictors are categorical.

Example: `'CategoricalPredictors','all'`

Data Types: `single` | `double` | `char`

### `'ClassNames'` — Class namesnumeric vector | categorical vector | logical vector | character array | cell array of strings

Class names, specified as the comma-separated pair consisting of `'ClassNames'` and an array representing the class names. Use the same data type as the values that exist in `Y`.

Use `ClassNames` to order the classes or to select a subset of classes for training. The default is the class names that exist in `Y`.

Data Types: `single` | `double` | `char` | `logical` | `cell`

### `'Cost'` — Cost of misclassificationsquare matrix | structure

Cost of misclassification of a point, specified as the comma-separated pair consisting of `'Cost'` and one of the following:

• Square matrix, where `Cost(i,j)` is the cost of classifying a point into class `j` if its true class is `i` (i.e., the rows correspond to the true class and the columns correspond to the predicted class). To specify the class order for the corresponding rows and columns of `Cost`, additionally specify the `ClassNames` name-value pair argument.

• Structure `S` having two fields: `S.ClassNames` containing the group names as a variable of the same data type as `Y`, and `S.ClassificationCosts` containing the cost matrix.

The default is `Cost(i,j)=1` if `i~=j`, and `Cost(i,j)=0` if `i=j`.

Data Types: `single` | `double` | `struct`

### `'CrossVal'` — Flag to grow cross-validated decision tree`'off'` (default) | `'on'`

Flag to grow a cross-validated decision tree, specified as the comma-separated pair consisting of `'CrossVal'` and `'on'` or `'off'`.

If `'on'`, `fitctree` grows a cross-validated decision tree with 10 folds. You can override this cross-validation setting using one of the `'KFold'`, `'Holdout'`, `'Leaveout'`, or `'CVPartition'` name-value pair arguments. Note that you can only use one of these four arguments at a time when creating a cross-validated tree.

Alternatively, cross validate `tree` later using the `crossval` method.

Example: `'CrossVal','on'`

### `'CVPartition'` — Partition for cross-validated tree`cvpartition` object

Partition to use in a cross-validated tree, specified as the comma-separated pair consisting of `'CVPartition'` and an object created using `cvpartition`.

If you use `'CVPartition'`, you cannot use any of the `'KFold'`, `'Holdout'`, or `'Leaveout'` name-value pair arguments.

### `'Holdout'` — Fraction of data for holdout validation`0` (default) | scalar value in the range `[0,1]`

Fraction of data used for holdout validation, specified as the comma-separated pair consisting of `'Holdout'` and a scalar value in the range `[0,1]`. Holdout validation tests the specified fraction of the data, and uses the rest of the data for training.

If you use `'Holdout'`, you cannot use any of the `'CVPartition'`, `'KFold'`, or `'Leaveout'` name-value pair arguments.

Example: `'Holdout',0.1`

Data Types: `single` | `double`

### `'KFold'` — Number of folds`10` (default) | positive integer value

Number of folds to use in a cross-validated tree, specified as the comma-separated pair consisting of `'KFold'` and a positive integer value.

If you use `'KFold'`, you cannot use any of the `'CVPartition'`, `'Holdout'`, or `'Leaveout'` name-value pair arguments.

Example: `'KFold',8`

Data Types: `single` | `double`

### `'Leaveout'` — Leave-one-out cross-validation flag`'off'` (default) | `'on'`

Leave-one-out cross-validation flag, specified as the comma-separated pair consisting of `'Leaveout'` and `'on'` or `'off'`. Specify `'on'` to use leave-one-out cross-validation.

If you use `'Leaveout'`, you cannot use any of the `'CVPartition'`, `'Holdout'`, or `'KFold'` name-value pair arguments.

Example: `'Leaveout','on'`

### `'MaxNumCategories'` — Maximum category levels`10` (default) | nonnegative scalar value

Maximum category levels, specified as the comma-separated pair consisting of `'MaxNumCategories'` and a nonnegative scalar value. `fitctree` splits a categorical predictor using the exact search algorithm if the predictor has at most `MaxNumCategories` levels in the split node. Otherwise, `fitctree` finds the best categorical split using one of the inexact algorithms.

Passing a small value can lead to loss of accuracy and passing a large value can increase computation time and memory overload.

Example: `'MaxNumCategories',8`

### `'MaxNumSplits'` — Maximal number of decision splits`size(X,1) - 1` (default) | positive integer

Maximal number of decision splits (or branch nodes), specified as the comma-separated pair consisting of `'MaxNumSplits'` and a positive integer. `fitctree` splits `MaxNumSplits` or fewer branch nodes. For more details on splitting behavior, see Algorithms.

Example: `'MaxNumSplits',5`

Data Types: `single` | `double`

### `'MergeLeaves'` — Leaf merge flag`'on'` (default) | `'off'`

Leaf merge flag, specified as the comma-separated pair consisting of `'MergeLeaves'` and `'on'` or `'off'`.

If `MergeLeaves` is `'on'`, then `fitctree`:

• Merges leaves that originate from the same parent node, and that yields a sum of risk values greater or equal to the risk associated with the parent node

• Estimates the optimal sequence of pruned subtrees, but does not prune the classification tree

Otherwise, `fitctree` does not merge leaves.

Example: `'MergeLeaves','off'`

### `'MinLeafSize'` — Minimum number of leaf node observations`1` (default) | positive integer value

Minimum number of leaf node observations, specified as the comma-separated pair consisting of `'MinLeafSize'` and a positive integer value. Each leaf has at least `MinLeafSize` observations per tree leaf. If you supply both `MinParentSize` and `MinLeafSize`, `fitctree` uses the setting that gives larger leaves: `MinParentSize = max(MinParentSize,2*MinLeafSize)`.

Example: `'MinLeafSize',3`

Data Types: `single` | `double`

### `'MinParentSize'` — Minimum number of branch node observations`10` (default) | positive integer value

Minimum number of branch node observations, specified as the comma-separated pair consisting of `'MinParentSize'` and a positive integer value. Each branch node in the tree has at least `MinParentSize` observations. If you supply both `MinParentSize` and `MinLeafSize`, `fitctree` uses the setting that gives larger leaves: `MinParentSize = max(MinParentSize,2*MinLeafSize)`.

Example: `'MinParentSize',8`

Data Types: `single` | `double`

### `'NumVariablesToSample'` — Number of predictors to select at random for each split`'all'` | positive integer value

Number of predictors to select at random for each split, specified as the comma-separated pair consisting of `'NumVariablesToSample'` and a positive integer value. You can also specify `'all'` to use all available predictors.

Example: `'NumVariablesToSample',3`

Data Types: `single` | `double`

### `'PredictorNames'` — Predictor variable names`{'x1','x2',...}` (default) | cell array of strings

Predictor variable names, specified as the comma-separated pair consisting of `'PredictorNames'` and a cell array of strings containing the names for the predictor variables, in the order in which they appear in `X`.

### `'Prior'` — Prior probabilities`'empirical'` (default) | `'uniform'` | vector of scalar values | structure

Prior probabilities for each class, specified as the comma-separated pair consisting of `'Prior'` and one of the following.

• A string:

• `'empirical'` determines class probabilities from class frequencies in `Y`. If you pass observation weights, `fitctree` uses the weights to compute the class probabilities.

• `'uniform'` sets all class probabilities equal.

• A vector (one scalar value for each class). To specify the class order for the corresponding elements of `Prior`, additionally specify the `ClassNames` name-value pair argument.

• A structure `S` with two fields:

• `S.ClassNames` containing the class names as a variable of the same type as `Y`

• `S.ClassProbs` containing a vector of corresponding probabilities

If you set values for both `weights` and `prior`, the weights are renormalized to add up to the value of the prior probability in the respective class.

Example: `'Prior','uniform'`

### `'Prune'` — Flag to estimate optimal sequence of pruned subtrees`'on'` (default) | `'off'`

Flag to estimate the optimal sequence of pruned subtrees, specified as the comma-separated pair consisting of `'Prune'` and `'on'` or `'off'`.

If `Prune` is `'on'`, then `fitctree` grows the classification tree without pruning it, but estimates the optimal sequence of pruned subtrees. Otherwise, `fitctree` grows the classification tree without estimating the optimal sequence of pruned subtrees.

To prune a trained `ClassificationTree` model, pass it to `prune`.

Example: `'Prune','off'`

### `'PruneCriterion'` — Pruning criterion`'error'` (default) | `'impurity'`

Pruning criterion, specified as the comma-separated pair consisting of `'PruneCriterion'` and `'error'` or `'impurity'`.

Example: `'PruneCriterion','impurity'`

### `'ResponseName'` — Response variable name`'Y'` (default) | string

Response variable name, specified as the comma-separated pair consisting of `'ResponseName'` and a string representing the name of the response variable `Y`.

Example: `'ResponseName','Response'`

### `'ScoreTransform'` — Score transform function`'none'` | `'symmetric'` | `'invlogit'` | `'ismax'` | function handle | ...

Score transform function, specified as the comma-separated pair consisting of `'ScoreTransform'` and a function handle for transforming scores. Your function should accept a matrix (the original scores) and return a matrix of the same size (the transformed scores).

Alternatively, you can specify one of the following strings representing a built-in transformation function.

StringFormula
`'doublelogit'`1/(1 + e–2x)
`'invlogit'`log(x / (1–x))
`'ismax'`Set the score for the class with the largest score to `1`, and scores for all other classes to `0`.
`'logit'`1/(1 + ex)
`'none'`x (no transformation)
`'sign'`–1 for x < 0
0 for x = 0
1 for x > 0
`'symmetric'`2x – 1
`'symmetriclogit'`2/(1 + ex) – 1
`'symmetricismax'`Set the score for the class with the largest score to `1`, and scores for all other classes to `-1`.

Example: `'ScoreTransform','logit'`

### `'SplitCriterion'` — Split criterion`'gdi'` (default) | `'twoing'` | `'deviance'`

Split criterion, specified as the comma-separated pair consisting of `'SplitCriterion'` and `'gdi'` (Gini's diversity index), `'twoing'` for the twoing rule, or `'deviance'` for maximum deviance reduction (also known as cross entropy).

Example: `'SplitCriterion','deviance'`

### `'Surrogate'` — Surrogate decision splits flag`'off'` | `'on'` | `'all'` | positive integer value

Surrogate decision splits flag, specified as the comma-separated pair consisting of `'Surrogate'` and `'on'`, `'off'`, `'all'`, or a positive integer value.

• When set to `'on'`, `fitctree` finds at most 10 surrogate splits at each branch node.

• When set to `'all'`, `fitctree` finds all surrogate splits at each branch node. The `'all'` setting can use considerable time and memory.

• When set to a positive integer value, `fitctree` finds at most the specified number of surrogate splits at each branch node.

Use surrogate splits to improve the accuracy of predictions for data with missing values. The setting also lets you compute measures of predictive association between predictors.

Example: `'Surrogate','on'`

### `'Weights'` — Observation weights`ones(size(x,1),1)` (default) | vector of scalar values

Vector of observation weights, specified as the comma-separated pair consisting of `'Weights'` and a vector of scalar values. The length of `Weights` equals the number of rows in `X`. `fitctree` normalizes the weights in each class to add up to the value of the prior probability of the class.

Data Types: `single` | `double`

## Output Arguments

collapse all

### `tree` — Classification treeclassification tree object

Classification tree, returned as a classification tree object.

Using the `'CrossVal'`, `'KFold'`, `'Holdout'`, `'Leaveout'`, or `'CVPartition'` options results in a tree of class `ClassificationPartitionedModel`. You cannot use a partitioned tree for prediction, so this kind of tree does not have a `predict` method. Instead, use `kfoldpredict` to predict responses for observations not used for training.

Otherwise, `tree` is of class `ClassificationTree`, and you can use the `predict` method to make predictions.

collapse all

### Impurity and Node Error

`ClassificationTree` splits nodes based on either impurity or node error.

Impurity means one of several things, depending on your choice of the `SplitCriterion` name-value pair argument:

• Gini's Diversity Index (`gdi`) — The Gini index of a node is

$1-\sum _{i}{p}^{2}\left(i\right),$

where the sum is over the classes i at the node, and p(i) is the observed fraction of classes with class i that reach the node. A node with just one class (a pure node) has Gini index `0`; otherwise the Gini index is positive. So the Gini index is a measure of node impurity.

• Deviance (`'deviance'`) — With p(i) defined the same as for the Gini index, the deviance of a node is

$-\sum _{i}p\left(i\right)\mathrm{log}p\left(i\right).$

A pure node has deviance `0`; otherwise, the deviance is positive.

• Twoing rule (`'twoing'`) — Twoing is not a purity measure of a node, but is a different measure for deciding how to split a node. Let L(i) denote the fraction of members of class i in the left child node after a split, and R(i) denote the fraction of members of class i in the right child node after a split. Choose the split criterion to maximize

$P\left(L\right)P\left(R\right){\left(\sum _{i}|L\left(i\right)-R\left(i\right)|\right)}^{2},$

where P(L) and P(R) are the fractions of observations that split to the left and right respectively. If the expression is large, the split made each child node purer. Similarly, if the expression is small, the split made each child node similar to each other, and hence similar to the parent node, and so the split did not increase node purity.

• Node error — The node error is the fraction of misclassified classes at a node. If j is the class with the largest number of training samples at a node, the node error is

1 – p(j).

### Tips

By default, `Prune` is `'on'`. However, this specification does not prune the classification tree. To prune a trained classification tree, pass the classification tree to `prune`.

### Algorithms

• If `MergeLeaves` is `'on'` and `PruneCriterion` is `'error'` (which are the default values for these name-value pair arguments), then the software applies pruning only to the leaves and by using classification error. This specification amounts to merging leaves that share the most popular class per leaf.

• To accommodate `MaxNumSplits`, `fitctree` splits all nodes in the current layer, and then counts the number of branch nodes. A layer is the set of nodes that are equidistant from the root node. If the number of branch nodes exceeds `MaxNumSplits`, `fitctree` follows this procedure:

1. Determine how many branch nodes in the current layer must be unsplit so that there are at most `MaxNumSplits` branch nodes.

2. Sort the branch nodes by their impurity gains.

3. Unsplit the number of least successful branches.

4. Return the decision tree grown so far.

This procedure produces maximally balanced trees.

• The software splits branch nodes layer by layer until at least one of these events occurs:

• There are `MaxNumSplits` branch nodes.

• A proposed split causes the number of observations in at least one branch node to be fewer than `MinParentSize`.

• A proposed split causes the number of observations in at least one leaf node to be fewer than `MinLeafSize`.

• The algorithm cannot find a good split within a layer (i.e., the pruning criterion (see `PruneCriterion`), does not improve for all proposed splits in a layer). A special case is when all nodes are pure (i.e., all observations in the node have the same class).

`MaxNumSplits` and `MinLeafSize` do not affect splitting at their default values. Therefore, if you set `'MaxNumSplits'`, splitting might stop due to the value of `MinParentSize`, before `MaxNumSplits` splits occur.

• For dual-core systems and above, `fitctree` parallelizes training decision trees using Intel® Threading Building Blocks (TBB). For details on Intel TBB, see https://software.intel.com/en-us/intel-tbb.

## References

[1] Coppersmith, D., S. J. Hong, and J. R. M. Hosking. "Partitioning Nominal Attributes in Decision Trees." Data Mining and Knowledge Discovery, Vol. 3, 1999, pp. 197–217.

[2] Breiman, L., J. Friedman, R. Olshen, and C. Stone. Classification and Regression Trees. Boca Raton, FL: CRC Press, 1984.