# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# ClassificationTree class

Superclasses: CompactClassificationTree

Binary decision tree for classification

## Description

A `ClassificationTree` object represents a decision tree with binary splits for classification. An object of this class can predict responses for new data using the `predict` method. The object contains the data used for training, so it can also compute resubstitution predictions.

## Construction

`tree = fitctree(TBL,ResponseVarName)` returns a fitted binary classification decision tree based on the input variables (also known as predictors, features, or attributes) contained in the table `TBL` and output (response or labels) contained in `ResponseVarName`. The returned binary tree splits branching nodes based on the values of a column of `TBL`.

`tree = fitctree(TBL,formula)` returns a fitted binary classification decision tree based on the input variables contained in the table `TBL`. `formula` is a formula that identifies the response and predictor variables in `TBL` used to fit `tree`. The returned binary tree splits branching nodes based on the values of a column of `TBL`.

`tree = fitctree(TBL,Y)` returns a fitted binary classification decision tree based on the input variables contained in the table `TBL` and output in vector `Y`. The returned binary tree splits branching nodes based on the values of a column of `TBL`.

`tree = fitctree(X,Y)` returns a fitted binary classification decision tree based on the input variables contained in matrix `X` and output `Y`. The returned binary tree splits branching nodes based on the values of a column of `X`.

`tree = fitctree(___,Name,Value)` fits a tree with additional options specified by one or more name-value pair arguments, using any of the previous syntaxes. For example, you can specify the algorithm used to find the best split on a categorical predictor or grow a cross-validated tree.

### Input Arguments

expand all

Sample data used to train the model, specified as a table. Each row of `Tbl` corresponds to one observation, and each column corresponds to one predictor variable. Optionally, `Tbl` can contain one additional column for the response variable. Multi-column variables and cell arrays other than cell arrays of character vectors are not allowed.

If `Tbl` contains the response variable, and you want to use all remaining variables in `Tbl` as predictors, then specify the response variable using `ResponseVarName`.

If `Tbl` contains the response variable, and you want to use only a subset of the remaining variables in `Tbl` as predictors, then specify a formula using `formula`.

If `Tbl` does not contain the response variable, then specify a response variable using `Y`. The length of response variable and the number of rows of `Tbl` must be equal.

Data Types: `table`

Predictor data, specified as a numeric matrix.

`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`

Response variable name, specified as the name of a variable in `Tbl`.

You must specify `ResponseVarName` as a character vector. For example, if the response variable `Y` is stored as `Tbl.Y`, then specify it as `'Y'`. Otherwise, the software treats all columns of `Tbl`, including `Y`, as predictors when training the model.

The response variable must be a categorical or character array, logical or numeric vector, or cell array of character vectors. If `Y` is a character array, then each element must correspond to one row of the array.

It is good practice to specify the order of the classes using the `ClassNames` name-value pair argument.

Data Types: `char`

Response and predictor variables to use in model training, specified as a character vector in the form of `'Y~X1+X2+X3'`. In this form, `Y` represents the response variable, and `X1`, `X2`, and `X3` represent the predictor variables.

To specify a subset of variables in `Tbl` as predictors for training the model, use a formula. If you specify a formula, then any variables in `Tbl` that do not appear in `formula` are not used to train the model.

Data Types: `char`

Class labels, specified as a numeric vector, categorical vector, logical vector, character array, or cell array of character vectors. Each row of `X` represents the classification of the corresponding row of `X`.

When fitting the tree, `fitctree` considers `NaN`, `''` (empty character vector), and `<undefined>` values in `Y` to be missing values. `fitctree` does not use observations with missing values for `Y` in the fit.

For numeric `Y`, consider fitting a regression tree using `fitrtree` instead.

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`.

expand all

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 values.

ValueDescription
`'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. To specify a particular algorithm, use the `'AlgorithmForCategorical'` name-value pair argument.

Example: `'AlgorithmForCategorical','PCA'`

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 character vectors, 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.

By default, if the predictor data is in a matrix (`X`), the software assumes that none of the predictors are categorical. If the predictor data is in a table (`Tbl`), the software assumes that a variable is categorical if it contains, logical values, values of the unordered data type `categorical`, or a cell array of character vectors.

Example: `'CategoricalPredictors','all'`

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

Names of classes to use for training, specified as the comma-separated pair consisting of `'ClassNames'` and a categorical or character array, logical or numeric vector, or cell array of character vectors. `ClassNames` must be the same data type as `Y`.

If `ClassNames` is a character array, then each element must correspond to one row of the array.

Use `ClassNames` to:

• Order the classes during training.

• Specify the order of any input or output argument dimension that corresponds to the class order. For example, use `ClassNames` to specify the order of the dimensions of `Cost` or the column order of classification scores returned by `predict`.

• Select a subset of classes for training. For example, suppose that the set of all distinct class names in `Y` is `{'a','b','c'}`. To train the model using observations from classes `'a'` and `'c'` only, specify `'ClassNames',{'a','c'}`.

The default is the set of all distinct class names in `Y`.

Example: `'ClassNames',{'b','g'}`

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

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`, also 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`

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. 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'`

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.

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`

Number of folds to use in a cross-validated classifier, specified as the comma-separated pair consisting of `'KFold'` and a positive integer value greater than 1. If you specify, e.g., `'KFold',k`, then the software:

1. Randomly partitions the data into k sets

2. For each set, reserves the set as validation data, and trains the model using the other k – 1 sets

3. Stores the `k` compact, trained models in the cells of a `k`-by-1 cell vector in the `Trained` property of the cross-validated model.

To create a cross-validated model, you can use one of these four options only: `CVPartition`, `Holdout`, `KFold`, or `Leaveout`.

Example: `'KFold',8`

Data Types: `single` | `double`

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'`

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`

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

Example: `'MaxNumSplits',5`

Data Types: `single` | `double`

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

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

• 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, `ClassificationTree` does not merge leaves.

Example: `'MergeLeaves','off'`

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`

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`

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`

Predictor variable names, specified as the comma-separated pair consisting of `'PredictorNames'` and a cell array of unique character vectors. The functionality of `'PredictorNames'` depends on the way you supply the training data.

• If you supply `X` and `Y`, then you can use `'PredictorNames'` to give the predictor variables in `X` names.

• The order of the names in `PredcitorNames` must correspond to the column order of `X`. That is, `PredictorNames{1}` is the name of `X(:,1)`, `PredictorNames{2}` is the name of `X(:,2)`, and so on. Also, `size(X,2)` and `numel(PredictorNames)` must be equal.

• By default, `PredictorNames` is `{x1,x2,...}`.

• If you supply `Tbl`, then you can use `'PredictorNames'` to choose which predictor variables to use in training. That is, `ClassificationTree` uses the predictor variables in `PredictorNames` and the response only in training.

• `PredictorNames` must be a subset of `Tbl.Properties.VariableNames` and cannot include the name of the response variable.

• By default, `PredictorNames` contains the names of all predictor variables.

• It good practice to specify the predictors for training using one of `'PredictorNames'` or `formula` only.

Example: `'PredictorNames',{'SepalLength','SepalWidth','PedalLength','PedalWidth'}`

Data Types: `cell`

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

• A character vector:

• `'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`, also 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'`

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 `ClassificationTree` grows the classification tree without pruning it, but estimates the optimal sequence of pruned subtrees. Otherwise, `ClassificationTree` 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'`

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

Example: `'PruneCriterion','impurity'`

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

This name-value pair is not valid when using the `ResponseVarName` or `formula` input arguments.

Example: `'ResponseName','IrisType'`

Score transform function, specified as the comma-separated pair consisting of `'ScoreTransform'` and a function handle for transforming scores. Your function must 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 character vectors representing a built-in transformation function.

ValueFormula
`'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'` or `'identity'`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'`

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 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. For more details, see Node Splitting Rules.

Example: `'Surrogate','on'`

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

Observation weights, specified as the comma-separated pair consisting of `'Weights'` and a vector of scalar values. The software weights the observations in each row of `X` or `Tbl` with the corresponding value in `Weights`. The size of `Weights` must equal the number of rows in `X` or `Tbl`.

If you specify the input data as a table `Tbl`, then `Weights` can be the name of a variable in `Tbl` that contains a numeric vector. In this case, you must specify `Weights` as a character vector. For example, if weights vector `W` is stored as `Tbl.W`, then specify it as `'W'`. Otherwise, the software treats all columns of `Tbl`, including `W`, as predictors when training the model.

`fitctree` normalizes the weights in each class to add up to the value of the prior probability of the class.

Data Types: `single` | `double`

## Properties

 `CategoricalPredictors` List of categorical predictors, a numeric vector with indices from `1` to `p`, where `p` is the number of columns of `X`. `CategoricalSplit` An n-by-2 cell array, where n is the number of categorical splits in `tree`. Each row in `CategoricalSplits` gives left and right values for a categorical split. For each branch node with categorical split `j` based on a categorical predictor variable `z`, the left child is chosen if `z` is in `CategoricalSplits(j,1)` and the right child is chosen if `z` is in `CategoricalSplits(j,2)`. The splits are in the same order as nodes of the tree. Find the nodes for these splits by selecting `'categorical'` cuts from top to bottom in the `CutType` property. `Children` An n-by-2 array containing the numbers of the child nodes for each node in `tree`, where n is the number of nodes. Leaf nodes have child node `0`. `ClassCount` An n-by-k array of class counts for the nodes in `tree`, where n is the number of nodes and k is the number of classes. For any node number `i`, the class counts `ClassCount(i,:)` are counts of observations (from the data used in fitting the tree) from each class satisfying the conditions for node `i`. `ClassNames` List of the elements in `Y` with duplicates removed. `ClassNames` can be a categorical array, cell array of character vectors, character array, logical vector, or a numeric vector. `ClassNames` has the same data type as the data in the argument `Y`. `ClassProbability` An n-by-k array of class probabilities for the nodes in `tree`, where n is the number of nodes and k is the number of classes. For any node number `i`, the class probabilities `ClassProbability(i,:)` are the estimated probabilities for each class for a point satisfying the conditions for node `i`. `Cost` 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). The order of the rows and columns of `Cost` corresponds to the order of the classes in `ClassNames`. The number of rows and columns in `Cost` is the number of unique classes in the response. This property is read-only. `CutCategories` An n-by-2 cell array of the categories used at branches in `tree`, where n is the number of nodes. For each branch node `i` based on a categorical predictor variable `X`, the left child is chosen if `X` is among the categories listed in `CutCategories{i,1}`, and the right child is chosen if `X` is among those listed in `CutCategories{i,2}`. Both columns of `CutCategories` are empty for branch nodes based on continuous predictors and for leaf nodes. `CutPoint` contains the cut points for `'continuous'` cuts, and `CutCategories` contains the set of categories. `CutPoint` An n-element vector of the values used as cut points in `tree`, where n is the number of nodes. For each branch node `i` based on a continuous predictor variable `X`, the left child is chosen if `X=CutPoint(i)`. `CutPoint` is `NaN` for branch nodes based on categorical predictors and for leaf nodes. `CutPoint` contains the cut points for `'continuous'` cuts, and `CutCategories` contains the set of categories. `CutType` An n-element cell array indicating the type of cut at each node in `tree`, where n is the number of nodes. For each node `i`, `CutType{i}` is: `'continuous'` — If the cut is defined in the form `X < v` for a variable `X` and cut point `v`.`'categorical'` — If the cut is defined by whether a variable `X` takes a value in a set of categories.`''` — If `i` is a leaf node. `CutPoint` contains the cut points for `'continuous'` cuts, and `CutCategories` contains the set of categories. `CutPredictor` An n-element cell array of the names of the variables used for branching in each node in `tree`, where n is the number of nodes. These variables are sometimes known as cut variables. For leaf nodes, `CutPredictor` contains an empty character vector. `CutPoint` contains the cut points for `'continuous'` cuts, and `CutCategories` contains the set of categories. `ExpandedPredictorNames` Expanded predictor names, stored as a cell array of character vectors. If the model uses encoding for categorical variables, then `ExpandedPredictorNames` includes the names that describe the expanded variables. Otherwise, `ExpandedPredictorNames` is the same as `PredictorNames`. `HyperparameterOptimizationResults` Description of the cross-validation optimization of hyperparameters, stored as a `BayesianOptimization` object or a table of hyperparameters and associated values. Nonempty when the `OptimizeHyperparameters` name-value pair is nonempty at creation. Value depends on the setting of the `HyperparameterOptimizationOptions` name-value pair at creation: `'bayesopt'` (default) — Object of class `BayesianOptimization``'gridsearch'` or `'randomsearch'` — Table of hyperparameters used, observed objective function values (cross-validation loss), and rank of observations from lowest (best) to highest (worst) `IsBranchNode` An n-element logical vector that is `true` for each branch node and `false` for each leaf node of `tree`. `ModelParameters` Parameters used in training `tree`. To display all parameter values, enter `tree.ModelParameters`. To access a particular parameter, use dot notation. `NumObservations` Number of observations in the training data, a numeric scalar. `NumObservations` can be less than the number of rows of input data `X` when there are missing values in `X` or response `Y`. `NodeClass` An n-element cell array with the names of the most probable classes in each node of `tree`, where n is the number of nodes in the tree. Every element of this array is a character vector equal to one of the class names in `ClassNames`. `NodeError` An n-element vector of the errors of the nodes in `tree`, where n is the number of nodes. `NodeError(i)` is the misclassification probability for node `i`. `NodeProbability` An n-element vector of the probabilities of the nodes in `tree`, where n is the number of nodes. The probability of a node is computed as the proportion of observations from the original data that satisfy the conditions for the node. This proportion is adjusted for any prior probabilities assigned to each class. `NodeRisk` An n-element vector of the risk of the nodes in the tree, where n is the number of nodes. The risk for each node is the measure of impurity (Gini index or deviance) for this node weighted by the node probability. If the tree is grown by twoing, the risk for each node is zero. `NodeSize` An n-element vector of the sizes of the nodes in `tree`, where n is the number of nodes. The size of a node is defined as the number of observations from the data used to create the tree that satisfy the conditions for the node. `NumNodes` The number of nodes in `tree`. `Parent` An n-element vector containing the number of the parent node for each node in `tree`, where n is the number of nodes. The parent of the root node is `0`. `PredictorNames` Cell array of character vectors containing the predictor names, in the order which they appear in `X`. `Prior` Numeric vector of prior probabilities for each class. The order of the elements of `Prior` corresponds to the order of the classes in `ClassNames`. The number of elements of `Prior` is the number of unique classes in the response. This property is read-only. `PruneAlpha` Numeric vector with one element per pruning level. If the pruning level ranges from 0 to M, then `PruneAlpha` has M + 1 elements sorted in ascending order. `PruneAlpha(1)` is for pruning level 0 (no pruning), `PruneAlpha(2)` is for pruning level 1, and so on. `PruneList` An n-element numeric vector with the pruning levels in each node of `tree`, where n is the number of nodes. The pruning levels range from 0 (no pruning) to M, where M is the distance between the deepest leaf and the root node. `ResponseName` A character vector that specifies the name of the response variable (`Y`). `RowsUsed` An n-element logical vector indicating which rows of the original predictor data (`X`) were used in fitting. If the software uses all rows of `X`, then `RowsUsed` is an empty array (`[]`). `ScoreTransform` Function handle for transforming predicted classification scores, or character vector representing a built-in transformation function. `none` means no transformation, or `@(x)x`. To change the score transformation function to, e.g., `function`, use dot notation.For available functions (see `fitctree`), enter`Mdl.ScoreTransform = 'function';`You can set a function handle for an available function, or a function you define yourself by entering`tree.ScoreTransform = @function;` `SurrogateCutCategories` An n-element cell array of the categories used for surrogate splits in `tree`, where n is the number of nodes in `tree`. For each node `k`, `SurrogateCutCategories{k}` is a cell array. The length of `SurrogateCutCategories{k}` is equal to the number of surrogate predictors found at this node. Every element of `SurrogateCutCategories{k}` is either an empty character vector for a continuous surrogate predictor, or is a two-element cell array with categories for a categorical surrogate predictor. The first element of this two-element cell array lists categories assigned to the left child by this surrogate split, and the second element of this two-element cell array lists categories assigned to the right child by this surrogate split. The order of the surrogate split variables at each node is matched to the order of variables in `SurrogateCutPredictor`. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, `SurrogateCutCategories` contains an empty cell. `SurrogateCutFlip` An n-element cell array of the numeric cut assignments used for surrogate splits in `tree`, where n is the number of nodes in `tree`. For each node `k`, `SurrogateCutFlip{k}` is a numeric vector. The length of `SurrogateCutFlip{k}` is equal to the number of surrogate predictors found at this node. Every element of `SurrogateCutFlip{k}` is either zero for a categorical surrogate predictor, or a numeric cut assignment for a continuous surrogate predictor. The numeric cut assignment can be either –1 or +1. For every surrogate split with a numeric cut C based on a continuous predictor variable Z, the left child is chosen if Z

## Methods

 compact Compact tree crossval Cross-validated decision tree cvloss Classification error by cross validation prune Produce sequence of subtrees by pruning resubEdge Classification edge by resubstitution resubLoss Classification error by resubstitution resubMargin Classification margins by resubstitution resubPredict Predict resubstitution response of tree

### Inherited Methods

 compareHoldout Compare accuracies of two classification models using new data edge Classification edge loss Classification error margin Classification margins predict Predict labels using classification tree predictorImportance Estimates of predictor importance surrogateAssociation Mean predictive measure of association for surrogate splits in decision tree view View tree

## Definitions

### 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).

## Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB® documentation.

## Examples

expand all

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

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

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 splits 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`.

## References

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