margin

Classification margins for XGBoost classification model

Since R2026a

collapse all in page

    Syntax

    m = margin(mdl,tbl,ResponseVarName)
    m = margin(mdl,tbl,Y)
    m = margin(mdl,X,Y)
    m = margin(___,UseParallel=UseParallel)

    Description

    m = margin(mdl,tbl,ResponseVarName) returns the classification margins m for the trained XGBoost classification model mdl using the predictor data in table tbl and the true class labels in tbl.ResponseVarName.

    The classification margin is the difference between the classification score for the true class and the maximal classification score for the false classes. m is a column vector with the same number of rows as in tbl.

    example

    m = margin(mdl,tbl,Y) returns the classification margins using the predictor data in table tbl and the true class labels in Y.

    m = margin(mdl,X,Y) returns the classification margins using the predictor data in matrix X and the true class labels in Y.

    m = margin(___,UseParallel=UseParallel) specifies whether to perform computations in parallel.

    Examples

    collapse all

    Open Live Script

    Find the margin for classifying an average sample from the ionosphere dataset as 'g'.

    This example provides a pretrained XGBoost classification model trained using the ionosphere dataset.

    load ionosphere
modelfile = "trainedXGBoostModel.json";
Mdl = importModelFromXGBoost(modelfile)
    Mdl = 
  CompactClassificationXGBoost
               ResponseName: 'Y'
                 ClassNames: [0 1]
             ScoreTransform: 'logit'
                 NumTrained: 30
    ImportedModelParameters: [1×1 struct]


  Properties, Methods

    The imported model has the classes encoded as 0 and 1 for "b" and "g" respectively.

    Classify an average sample and find the classification margin.

    averageSample = mean(X);
predict(Mdl,averageSample)
    ans = 
1

    margin(Mdl,averageSample,1)
    ans = single

0.6572

    Input Arguments

    collapse all

    Compact classification XGBoost model, specified as a CompactClassificationXGBoost model object created with importModelFromXGBoost.

    Sample data, specified as a table. Each row of tbl corresponds to one observation, and each column corresponds to one predictor variable. tbl must contain all of the predictors used to train the model. Multicolumn variables and cell arrays other than cell arrays of character vectors are not allowed.

    Data Types: table

    Response variable name, specified as the name of a variable in tbl. If mdl.ResponseName is the response variable name, then you do not need to specify ResponseVarName.

    If you specify ResponseVarName, you must specify it as a character vector or string scalar. 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.

    The response variable must be a logical or numeric vector.

    Data Types: char | string

    Class labels, specified as a logical or numeric vector. Y must have the same data type as tbl or X.

    Y must be of the same type as the classification used to train mdl, and its number of elements must equal the number of rows of tbl or X.

    Data Types: logical | single | double

    Predictor data, specified as a numeric matrix.

    Each row of X corresponds to one observation, and each column corresponds to one variable. The number of rows in X must equal the number of rows in Y.

    The variables that make up the columns of X must have the same order as the predictor variables used to train mdl.

    Data Types: double | single

    Flag to run in parallel, specified as a numeric or logical 1 (true) or 0 (false). If you specify UseParallel=true, the margin function executes for-loop iterations by using parfor. The loop runs in parallel when you have Parallel Computing Toolbox™.

    Example: UseParallel=true

    Data Types: logical

    More About

    collapse all

    Extended Capabilities

    expand all

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

    Version History

    Introduced in R2026a

    See Also

    | |