CompactClassificationNeuralNetwork

Compact neural network model for classification

Since R2021a

Description

CompactClassificationNeuralNetwork is a compact version of a ClassificationNeuralNetwork model object. The compact model does not include the data used for training the classifier. Therefore, you cannot perform some tasks, such as cross-validation, using the compact model. Use a compact model for tasks such as predicting the labels of new data.

Creation

Create a CompactClassificationNeuralNetwork object from a full ClassificationNeuralNetwork model object by using compact.

Properties

expand all

Neural Network Properties

`LayerSizes` — Sizes of fully connected layers
positive integer vector

This property is read-only.

Sizes of the fully connected layers in the neural network model, returned as a positive integer vector. The ith element of LayerSizes is the number of outputs in the ith fully connected layer of the neural network model.

LayerSizes does not include the size of the final fully connected layer. This layer always has K outputs, where K is the number of classes in the response variable.

Data Types: single | double

`LayerWeights` — Learned layer weights
cell array

This property is read-only.

Learned layer weights for the fully connected layers, returned as a cell array. The ith entry in the cell array corresponds to the layer weights for the ith fully connected layer. For example, Mdl.LayerWeights{1} returns the weights for the first fully connected layer of the model Mdl.

LayerWeights includes the weights for the final fully connected layer.

Data Types: cell

`LayerBiases` — Learned layer biases
cell array

This property is read-only.

Learned layer biases for the fully connected layers, returned as a cell array. The ith entry in the cell array corresponds to the layer biases for the ith fully connected layer. For example, Mdl.LayerBiases{1} returns the biases for the first fully connected layer of the model Mdl.

LayerBiases includes the biases for the final fully connected layer.

Data Types: cell

`Activations` — Activation functions for fully connected layers
`'relu'` | `'tanh'` | `'sigmoid'` | `'none'` | cell array of character vectors

This property is read-only.

Activation functions for the fully connected layers of the neural network model, returned as a character vector or cell array of character vectors with values from this table.

Value	Description
`"relu"`	Rectified linear unit (ReLU) function — Performs a threshold operation on each element of the input, where any value less than zero is set to zero, that is, $f (x) = {\begin{matrix} x, & x \geq 0 \\ 0, & x < 0 \end{matrix}$
`"tanh"`	Hyperbolic tangent (tanh) function — Applies the `tanh` function to each input element
`"sigmoid"`	Sigmoid function — Performs the following operation on each input element: $f (x) = \frac{1}{1 + e^{- x}}$
`"none"`	Identity function — Returns each input element without performing any transformation, that is, f(x) = x

If Activations contains only one activation function, then it is the activation function for every fully connected layer of the neural network model, excluding the final fully connected layer. The activation function for the final fully connected layer is always softmax (OutputLayerActivation).
If Activations is an array of activation functions, then the ith element is the activation function for the ith layer of the neural network model.

Data Types: char | cell

`OutputLayerActivation` — Activation function for final fully connected layer
`'softmax'`

This property is read-only.

Activation function for the final fully connected layer, returned as 'softmax'. The function takes each input x_i and returns the following, where K is the number of classes in the response variable:

$f (x_{i}) = \frac{\exp (x_{i})}{\sum_{j = 1}^{K} \exp (x_{j})} .$

The results correspond to the predicted classification scores (or posterior probabilities).

Data Properties

`PredictorNames` — Predictor variable names
cell array of character vectors

This property is read-only.

Predictor variable names, returned as a cell array of character vectors. The order of the elements of PredictorNames corresponds to the order in which the predictor names appear in the training data.

Data Types: cell

`CategoricalPredictors` — Categorical predictor indices
vector of positive integers | `[]`

This property is read-only.

Categorical predictor indices, returned as a vector of positive integers. Assuming that the predictor data contains observations in rows, CategoricalPredictors contains index values corresponding to the columns of the predictor data that contain categorical predictors. If none of the predictors are categorical, then this property is empty ([]).

Data Types: double

`ExpandedPredictorNames` — Expanded predictor names
cell array of character vectors

This property is read-only.

Expanded predictor names, returned 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.

Data Types: cell

`ClassNames` — Unique class names
numeric vector | categorical vector | logical vector | character array | cell array of character vectors

This property is read-only.

Unique class names used in training, returned as a numeric vector, categorical vector, logical vector, character array, or cell array of character vectors. ClassNames has the same data type as the class labels in the response variable used to train the model. (The software treats string arrays as cell arrays of character vectors.) ClassNames also determines the class order.

`Mu` — Predictor means
numeric vector | `[]`

Since R2023b

This property is read-only.

Predictor means, returned as a numeric vector. If you set Standardize to 1 or true when you train the neural network model, then the length of the Mu vector is equal to the number of expanded predictors (see ExpandedPredictorNames). The vector contains 0 values for dummy variables corresponding to expanded categorical predictors.

If you set Standardize to 0 or false when you train the neural network model, then the Mu value is an empty vector ([]).

Data Types: double

`ResponseName` — Response variable name
character vector

This property is read-only.

Response variable name, returned as a character vector.

Data Types: char

`Sigma` — Predictor standard deviations
numeric vector | `[]`

Since R2023b

This property is read-only.

Predictor standard deviations, returned as a numeric vector. If you set Standardize to 1 or true when you train the neural network model, then the length of the Sigma vector is equal to the number of expanded predictors (see ExpandedPredictorNames). The vector contains 1 values for dummy variables corresponding to expanded categorical predictors.

If you set Standardize to 0 or false when you train the neural network model, then the Sigma value is an empty vector ([]).

Data Types: double

Other Classification Properties

`Cost` — Misclassification cost
numeric square matrix

Misclassification cost, returned as a numeric square matrix, where Cost(i,j) is the cost of classifying a point into class j if its true class is i. The cost matrix always has this form: Cost(i,j) = 1 if i ~= j, and Cost(i,j) = 0 if i = j. 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 software uses the Cost value for prediction, but not training. You can change the Cost property value of the trained model by using dot notation.

Data Types: double

`Prior` — Prior class probabilities
numeric vector

This property is read-only.

Prior class probabilities, returned as a numeric vector. The order of the elements of Prior corresponds to the elements of ClassNames.

Data Types: double

`ScoreTransform` — Score transformation
character vector | function handle

Score transformation, specified as a character vector or function handle. ScoreTransform represents a built-in transformation function or a function handle for transforming predicted classification scores.

To change the score transformation function to function, for example, use dot notation.

For a built-in function, enter a character vector.

Mdl.ScoreTransform = 'function';

This table describes the available built-in functions.

Value	Description
`'doublelogit'`	1/(1 + e^–2x)
`'invlogit'`	log(x / (1 – x))
`'ismax'`	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to 0
`'logit'`	1/(1 + e^–x)
`'none'` or `'identity'`	x (no transformation)
`'sign'`	–1 for x < 0 0 for x = 0 1 for x > 0
`'symmetric'`	2x – 1
`'symmetricismax'`	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to –1
`'symmetriclogit'`	2/(1 + e^–x) – 1

For a MATLAB^® function or a function that you define, enter its function handle.
```
Mdl.ScoreTransform = @function;
```
function must accept a matrix (the original scores) and return a matrix of the same size (the transformed scores).

Data Types: char | function_handle

Object Functions

expand all

Create `dlnetwork`

dlnetwork (Deep Learning Toolbox) Deep learning neural network

Interpret Prediction

`lime`	Local interpretable model-agnostic explanations (LIME)
`partialDependence`	Compute partial dependence
`plotPartialDependence`	Create partial dependence plot (PDP) and individual conditional expectation (ICE) plots
`shapley`	Shapley values

Assess Predictive Performance on New Observations

`edge`	Classification edge for neural network classifier
`loss`	Classification loss for neural network classifier
`margin`	Classification margins for neural network classifier
`predict`	Classify observations using neural network classifier

Compare Accuracies

`compareHoldout`	Compare accuracies of two classification models using new data
`testckfold`	Compare accuracies of two classification models by repeated cross-validation

Gather Properties of Compact Classification Neural Network Model

gather Gather properties of Statistics and Machine Learning Toolbox object from GPU

Examples

collapse all

Reduce Size of Neural Network Classifier

Open Live Script

Reduce the size of a full neural network classifier by removing the training data from the model. You can use a compact model to improve memory efficiency.

Load the patients data set. Create a table from the data set. Each row corresponds to one patient, and each column corresponds to a diagnostic variable. Use the Smoker variable as the response variable, and the rest of the variables as predictors.

load patients
tbl = table(Diastolic,Systolic,Gender,Height,Weight,Age,Smoker);

Train a neural network classifier using the data. Specify the Smoker column of tbl as the response variable. Specify to standardize the numeric predictors.

Mdl = fitcnet(tbl,"Smoker","Standardize",true)

Mdl = 
  ClassificationNeuralNetwork
           PredictorNames: {'Diastolic'  'Systolic'  'Gender'  'Height'  'Weight'  'Age'}
             ResponseName: 'Smoker'
    CategoricalPredictors: 3
               ClassNames: [0 1]
           ScoreTransform: 'none'
          NumObservations: 100
               LayerSizes: 10
              Activations: 'relu'
    OutputLayerActivation: 'softmax'
                   Solver: 'LBFGS'
          ConvergenceInfo: [1x1 struct]
          TrainingHistory: [36x7 table]

Mdl is a full ClassificationNeuralNetwork model object.

Reduce the size of the model by using compact.

compactMdl = compact(Mdl)

compactMdl = 
  CompactClassificationNeuralNetwork
               LayerSizes: 10
              Activations: 'relu'
    OutputLayerActivation: 'softmax'

compactMdl is a CompactClassificationNeuralNetwork model object. compactMdl contains fewer properties than the full model Mdl.

Display the amount of memory used by each neural network model.

whos("Mdl","compactMdl")

  Name            Size            Bytes  Class                                                           Attributes

  Mdl             1x1             18790  ClassificationNeuralNetwork                                               
  compactMdl      1x1              6527  classreg.learning.classif.CompactClassificationNeuralNetwork

The full model is larger than the compact model.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

The predict object function supports code generation.

For more information, see Introduction to Code Generation.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2024b)

Usage notes and limitations:

The following object functions fully support GPU arrays:
The object functions execute on a GPU if at least one of the following applies:
- The model was fitted with GPU arrays.
- The predictor data that you pass to the object function is a GPU array.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2021a

expand all

R2024b: Specify GPU arrays (requires Parallel Computing Toolbox)

You can fit a CompactClassificationNeuralNetwork object with GPU arrays by using fitcnet to fit a ClassificationNeuralNetwork object to gpuArray data, and then passing the object to compact. Most CompactClassificationNeuralNetwork object functions now support GPU array input arguments so that the functions can execute on a GPU. The object functions that do not support GPU array inputs are lime and shapley.

R2024b: Convert to `dlnetwork`

Convert a CompactClassificationNeuralNetwork object to a dlnetwork (Deep Learning Toolbox) object using the dlnetwork function. Use dlnetwork objects to make further edits and customize the underlying neural network of a CompactClassificationNeuralNetwork object and retrain it using the trainnet (Deep Learning Toolbox) function or a custom training loop.

R2023b: Neural network models include standardization properties

Neural network models include Mu and Sigma properties that contain the means and standard deviations, respectively, used to standardize the predictors before training. The properties are empty when the fitting function does not perform any standardization.

R2023a: Neural network classifiers support misclassification costs and prior probabilities

fitcnet supports misclassification costs and prior probabilities for neural network classifiers. Specify the Cost and Prior name-value arguments when you create a model. Alternatively, you can specify misclassification costs after training a model by using dot notation to change the Cost property value of the model.

Mdl.Cost = [0 2; 1 0];

CompactClassificationNeuralNetwork

Description

Creation

Properties

Neural Network Properties

`LayerSizes` — Sizes of fully connected layers
positive integer vector

`LayerWeights` — Learned layer weights
cell array

`LayerBiases` — Learned layer biases
cell array

`Activations` — Activation functions for fully connected layers
`'relu'` | `'tanh'` | `'sigmoid'` | `'none'` | cell array of character vectors

`OutputLayerActivation` — Activation function for final fully connected layer
`'softmax'`

Data Properties

`PredictorNames` — Predictor variable names
cell array of character vectors

`CategoricalPredictors` — Categorical predictor indices
vector of positive integers | `[]`

`ExpandedPredictorNames` — Expanded predictor names
cell array of character vectors

`ClassNames` — Unique class names
numeric vector | categorical vector | logical vector | character array | cell array of character vectors

`Mu` — Predictor means
numeric vector | `[]`

`ResponseName` — Response variable name
character vector

`Sigma` — Predictor standard deviations
numeric vector | `[]`

Other Classification Properties

`Cost` — Misclassification cost
numeric square matrix

`Prior` — Prior class probabilities
numeric vector

`ScoreTransform` — Score transformation
character vector | function handle

Object Functions

Create `dlnetwork`

Interpret Prediction

Assess Predictive Performance on New Observations

Compare Accuracies

Gather Properties of Compact Classification Neural Network Model

Examples

Reduce Size of Neural Network Classifier

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2024b)

Version History

R2024b: Specify GPU arrays (requires Parallel Computing Toolbox)

R2024b: Convert to `dlnetwork`

R2023b: Neural network models include standardization properties

R2023a: Neural network classifiers support misclassification costs and prior probabilities

See Also

Topics

CompactClassificationNeuralNetwork

Description

Creation

Properties

Neural Network Properties

LayerSizes — Sizes of fully connected layers positive integer vector

LayerWeights — Learned layer weights cell array

LayerBiases — Learned layer biases cell array

Activations — Activation functions for fully connected layers 'relu' | 'tanh' | 'sigmoid' | 'none' | cell array of character vectors

OutputLayerActivation — Activation function for final fully connected layer 'softmax'

Data Properties

PredictorNames — Predictor variable names cell array of character vectors

CategoricalPredictors — Categorical predictor indices vector of positive integers | []

ExpandedPredictorNames — Expanded predictor names cell array of character vectors

ClassNames — Unique class names numeric vector | categorical vector | logical vector | character array | cell array of character vectors

Mu — Predictor means numeric vector | []

ResponseName — Response variable name character vector

Sigma — Predictor standard deviations numeric vector | []

Other Classification Properties

Cost — Misclassification cost numeric square matrix

Prior — Prior class probabilities numeric vector

ScoreTransform — Score transformation character vector | function handle

Object Functions

Create dlnetwork

Interpret Prediction

Assess Predictive Performance on New Observations

Compare Accuracies

Gather Properties of Compact Classification Neural Network Model

Examples

Reduce Size of Neural Network Classifier

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2024b)

Version History

R2024b: Specify GPU arrays (requires Parallel Computing Toolbox)

R2024b: Convert to dlnetwork

R2023b: Neural network models include standardization properties

R2023a: Neural network classifiers support misclassification costs and prior probabilities

See Also

Topics

`LayerSizes` — Sizes of fully connected layers
positive integer vector

`LayerWeights` — Learned layer weights
cell array

`LayerBiases` — Learned layer biases
cell array

`Activations` — Activation functions for fully connected layers
`'relu'` | `'tanh'` | `'sigmoid'` | `'none'` | cell array of character vectors

`OutputLayerActivation` — Activation function for final fully connected layer
`'softmax'`

`PredictorNames` — Predictor variable names
cell array of character vectors

`CategoricalPredictors` — Categorical predictor indices
vector of positive integers | `[]`

`ExpandedPredictorNames` — Expanded predictor names
cell array of character vectors

`ClassNames` — Unique class names
numeric vector | categorical vector | logical vector | character array | cell array of character vectors

`Mu` — Predictor means
numeric vector | `[]`

`ResponseName` — Response variable name
character vector

`Sigma` — Predictor standard deviations
numeric vector | `[]`

`Cost` — Misclassification cost
numeric square matrix

`Prior` — Prior class probabilities
numeric vector

`ScoreTransform` — Score transformation
character vector | function handle

Create `dlnetwork`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2024b)

R2024b: Convert to `dlnetwork`