classificationECOCComponent

Pipeline component for multiclass classification using error-correcting output codes (ECOC) model

Since R2026a

Description

classificationECOCComponent is a pipeline component that creates an error-correcting output codes (ECOC) classifier consisting of multiple binary learners. The component uses the functionality of the fitcecoc function during the learn phase to train the ECOC classification model. The component uses the functionality of the predict and loss functions during the run phase to perform classification.

Creation

Syntax

component = classificationECOCComponent

component = classificationECOCComponent(Name=Value)

Description

component = classificationECOCComponent creates a pipeline component for an ECOC classification model.

component = classificationECOCComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can set the type of coding design and specify different binary learners.

Properties

Structural Parameters

The software sets structural parameters when you create the component. You cannot modify structural parameters after creating the component.

UseWeights — Observation weights flag

false or 0 (default) | true or 1

This property is read-only after the component is created.

Observation weights flag, specified as 0 (false) or 1 (true). If UseWeights is true, the component adds a third input "Weights" to the Inputs component property, and a third input tag 3 to the InputTags component property.

Example: c = classificationECOCComponent(UseWeights=1)

Data Types: logical

Learn Parameters

The software sets learn parameters when you create the component. You can modify learn parameters using dot notation any time before you use the learn object function. Any unset learn parameters use the corresponding default values.

Coding — Coding design

"onevsone" (default) | "allpairs" | "binarycomplete" | "denserandom" | "onevsall" | "ordinal" | "sparserandom" | "ternarycomplete" | numeric matrix

Coding design, specified as a numeric matrix or a value in this table.

Value	Number of Binary Learners	Description
"allpairs" and "onevsone"	K(K – 1)/2	For each binary learner, one class is positive, another is negative, and the software ignores the rest. This design exhausts all combinations of class pair assignments.
"binarycomplete"	$$2^{(K-1)}-1$$	This design partitions the classes into all binary combinations, and does not ignore any classes. For each binary learner, all class assignments are –1 and 1 with at least one positive class and one negative class in the assignment.
"denserandom"	Random, but approximately 10 log2K	For each binary learner, the software randomly assigns classes into positive or negative classes, with at least one of each type.
"onevsall"	K	For each binary learner, one class is positive and the rest are negative. This design exhausts all combinations of positive class assignments.
"ordinal"	K – 1	For the first binary learner, the first class is negative and the rest are positive. For the second binary learner, the first two classes are negative and the rest are positive, and so on.
"sparserandom"	Random, but approximately 15 log2K	For each binary learner, the software randomly assigns classes as positive or negative with probability 0.25 for each, and ignores classes with probability 0.5.
"ternarycomplete"	$$\left(3^K-2^{(K+1)}+1\right)/2$$	This design partitions the classes into all ternary combinations. All class assignments are 0, –1, and 1 with at least one positive class and one negative class in each assignment.

To specify a custom coding design, use a K-by-L matrix, where K is the number of classes and L is the number of binary learners. For more information on custom coding matrices, see Coding.

Example: c = classificationECOCComponent(Coding="denserandom")

Example: c.Coding = "ordinal"

Data Types: single | double | int8 | int16 | int32 | int64 | char | string

Cost — Misclassification cost

square matrix | structure

Misclassification cost, specified as a square matrix or a structure.

• If Cost is a square matrix, Cost(i,j) is the cost of classifying a point into class j if its true class is i.

• If Cost is a structure S, it has two fields: S.ClassificationCosts, which contains the cost matrix; and S.ClassNames, which contains the group names and defines the class order of the rows and columns of the cost matrix.

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

Example: c = classificationECOCComponent(Cost=[0 1; 2 0])

Example: c.Cost = [0 2; 1 0]

Data Types: single | double | struct

Learners — Binary learner templates

"svm" (default) | "discriminant" | "ensemble" | "kernel" | "knn" | "linear" | "naivebayes" | "tree" | template object | cell array of template objects

Binary learner templates, specified as a template object, a cell array of template objects, or a value in this table.

Value	Description
"discriminant"	Discriminant analysis. For the default options, see templateDiscriminant.
"ensemble"	Ensemble learning model. By default, the ensemble uses an adaptive logistic regression ("LogitBoost") aggregation method, 100 learning cycles, and tree weak learners. For other default options, see templateEnsemble.
"kernel"	Kernel classification model. For the default options, see templateKernel.
"knn"	k-nearest neighbors. For the default options, see templateKNN.
"linear"	Linear classification model. For the default options, see templateLinear.
"naivebayes"	Naive Bayes. For the default options, see templateNaiveBayes.
"svm"	Support vector machine. For the default options, see templateSVM.
"tree"	Classification trees. For the default options, see templateTree.

If Learners is a built-in learner template name, the component trains each binary learner using the default values of the specified algorithm. To train binary learners using custom options, create a template object using the corresponding template function.

If Learners is a cell array of template objects, then:

• Cell j corresponds to binary learner j, and the cell array must have length L, where L is the number of columns in Coding.

• All binary learners must return a score in the same range when you use one of the built-in loss functions. Otherwise, you must provide a custom loss function.

• The array cannot contain any other type of template object when it contains a templateLinear object.

• The array cannot contain any other type of template object when it contains a templateKernel object.

Example: c = classificationECOCComponent(Learners="tree")

Example: c.Learners = "kernel"

Data Types: char | string | cell

NumBins — Number of bins for binning numeric predictors

[](empty) (default) | positive integer scalar

Number of bins for binning numeric predictors, specified as a positive integer scalar.

• If NumBins is empty ([]), the component does not bin any predictors.

• If NumBins is a positive integer scalar, the component bins every numeric predictor into at most NumBins equiprobable bins, and then grows trees on the bin indices instead of the original data.

This property is valid only when Learners is "tree", a template object created by using templateTree, or a template object created by using templateEnsemble with tree weak learners.

Example: c = classificationECOCComponent(NumBins=50)

Example: c.NumBins = 20

Data Types: single | double

Prior — Prior probabilities

"empirical" (default) | "uniform" | numeric vector | structure

Prior probabilities for each class, specified as a value in this table.

Value	Description
"empirical"	The class prior probabilities are the class relative frequencies. The class relative frequencies are determined by the second data argument of learn.
"uniform"	All class prior probabilities are equal to 1/K, where K is the number of classes.
numeric vector	A numeric vector with one value for each class. Each element is a class prior probability. The component normalizes the elements such that they sum to 1.
structure	A structure S with two fields: S.ClassNames contains a list of the class names. S.ClassProbs contains a vector of corresponding prior probabilities. The component normalizes the elements such that they sum to 1.

If you set UseWeights to true, the component renormalizes the weights to add up to the value of the prior probability in the respective class.

Example: c = classificationECOCComponent(Prior="uniform")

Example: c.Prior = "empirical"

Data Types: single | double | char | string | struct

Run Parameters

The software sets run parameters when you create the component. You can modify the run parameters using dot notation at any time. Any unset run parameters use the corresponding default values.

BinaryLoss — Binary learner loss function

"binodeviance" | "exponential" | "hamming" | "hinge" | "linear" | "logit" | "quadratic" | function handle

Binary learner loss function, specified as a built-in loss function name or a function handle.

This table lists the available built-in loss functions.

Value	Description
"binodeviance"	Binomial deviance
"exponential"	Exponential
"hamming"	Hamming
"hinge"	Hinge
"linear"	Linear
"logit"	Logistic
"quadratic"	Quadratic

To specify a custom loss function, use function handle notation. For more information on custom loss functions, see BinaryLoss.

The default value of BinaryLoss depends on the score ranges returned by the binary learners during the learn phase. To check the default value, use dot notation to display the BinaryLoss property of TrainedModel.

Example: c = classificationECOCComponent(BinaryLoss="quadratic")

Example: c.BinaryLoss = "hinge"

Data Types: char | string | function_handle

Decoding — Decoding scheme

"lossweighted" (default) | "lossbased"

Decoding scheme, specified as "lossweighted" or "lossbased".

• If Decoding is "lossweighted", the component determines the predicted class by minimizing the BinaryLoss across the learners for each class.

• If Decoding is "lossbased", the component determines the predicted class by minimizing BinaryLoss across all learners.

For more information, see BinaryLoss.

Example: c = classificationECOCComponent(Decoding="lossbased")

Example: c.Decoding = "lossweighted"

Data Types: char | string

LossFun — Loss function

"classiferror" (default) | "classifcost" | function handle

Loss function, specified as "classiferror", "classifcost", or a function handle.

• If you specify "classiferror", the component computes the proportion of misclassified observations.

• If you specify "classifcost", the component computes the observed misclassification cost.

• If you set Cost to the default cost matrix, the component returns the same loss value for both loss functions.

To specify a custom loss function, use function handle notation. For more information, see LossFun.

Example: c = classificationECOCComponent(LossFun="classifcost")

Example: c.LossFun = "classiferror"

Data Types: char | string | function_handle

Component Properties

The software sets component properties when you create the component. You can modify the component properties (excluding HasLearnables and HasLearned) using dot notation at any time. You cannot modify the HasLearnables and HasLearned properties directly.

Name — Component identifier

"ClassificationECOC" (default) | character vector | string scalar

Component identifier, specified as a character vector or string scalar.

Example: c = classificationECOCComponent(Name="ECOC")

Example: c.Name = "ECOCClassifier"

Data Types: char | string

Inputs — Names of input ports

["Predictors","Response"] (default) | character vector | string array | cell array of character vectors

Names of the input ports, specified as a character vector, string array, or cell array of character vectors. If UseWeights is true, the component adds the input port "Weights" to Inputs.

Example: c = classificationECOCComponent(Inputs=["X","Y"])

Example: c.Inputs = ["In1","In2"]

Data Types: char | string | cell

Outputs — Names of output ports

["Predictions","Scores","Loss"] (default) | character vector | string array | cell array of character vectors

Names of the output ports, specified as a character vector, string array, or cell array of character vectors.

Example: c = classificationECOCComponent(Outputs=["Class","ClassScore","LossVal"])

Example: c.Outputs = ["X","Y","Z"]

Data Types: char | string | cell

InputTags — Tags that enable automatic connection of component inputs

[1 2] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component inputs with other components or pipelines, specified as a nonnegative integer vector. If you specify InputTags, the number of tags must match the number of inputs in Inputs. If UseWeights is true, the component adds a third input tag to InputTags.

Example: c = classificationECOCComponent(InputTags=[1 0])

Example: c.InputTags = [0 1]

Data Types: single | double

OutputTags — Tags that enable automatic connection of component outputs

[1 0 0] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component outputs with other components or pipelines, specified as a nonnegative integer vector. If you specify OutputTags, the number of tags must match the number of outputs in Outputs.

Example: c = classificationECOCComponent(OutputTags=[1 0 4])

Example: c.OutputTags = [1 2 0]

Data Types: single | double

HasLearnables — Indicator for learnables

Read-only: 1 (true) (default)

This property is read-only.

Indicator for learnables, returned as 1 (true). A value of 1 indicates that the component contains Learnables.

Data Types: logical

HasLearned — Indicator showing learning status of component

Read-only: 0 (false) (default) | 1 (true)

This property is read-only.

Indicator showing the learning status of the component, returned as 0 (false) or 1 (true). A value of 1 indicates that the learn object function has been applied to the component, and the Learnables are nonempty.

Data Types: logical

Learnables

The software sets learnables when you use the learn object function. You cannot modify learnables directly.

TrainedModel — Trained model

Read-only: CompactClassificationECOC model object

This property is read-only.

Trained model, returned as a CompactClassificationECOC model object.

Object Functions

learn	Initialize and evaluate pipeline or component
run	Execute pipeline or component for inference after learning
reset	Reset pipeline or component
series	Connect components in series to create pipeline
parallel	Connect components or pipelines in parallel to create pipeline
view	View diagram of pipeline inputs, outputs, components, and connections

Examples

Create and Train Pipeline Component for ECOC Classification

Create a classificationECOCComponent pipeline component.

component = classificationECOCComponent

component = 
  classificationECOCComponent with properties:

            Name: "ClassificationECOC"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Scores"    "Loss"]
      OutputTags: [1 0 0]

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a classificationECOCComponent object that contains one learnable, TrainedModel. This property remains empty until you pass data to the component during the learn phase.

To use a complete binary coding design, set the Coding property of the component to "binarycomplete".

component.Coding = "binarycomplete";

Read the fisheriris data set into a table. Store the predictor and response data in the tables X and Y, respectively.

fisheriris = readtable("fisheriris.csv");
X = fisheriris(:,1:end-1);
Y = fisheriris(:,end);

Use the learn object function to train the classificationECOCComponent using the entire data set.

component = learn(component,X,Y)

component = 
  classificationECOCComponent with properties:

            Name: "ClassificationECOC"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Scores"    "Loss"]
      OutputTags: [1 0 0]

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 classreg.learning.classif.CompactClassificationECOC]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
          Coding: 'binarycomplete'


Show all parameters

Note that the HasLearned property is set to true, which indicates that the software trained the ECOC model TrainedModel. You can use component to classify new data using the run object function.

.

Version History

Introduced in R2026a