Main Content

creditscorecard

Create creditscorecard object to build credit scorecard model

expand all in page

Description

Build a credit scorecard model by creating a creditscorecard object and specify input data in a table format.

After creating a creditscorecard object, you can use the associated object functions to bin the data and perform logistic regression analysis to develop a credit scorecard model to guide credit decisions. This workflow shows how to develop a credit scorecard model.

  1. Use screenpredictors (Risk Management Toolbox) from Risk Management Toolbox™ to pare down a potentially large set of predictors to a subset that is most predictive of the credit score card response variable. Use this subset of predictors when creating the creditscorecard object.

  2. Create a creditscorecard object (see Create creditscorecard and Properties).

  3. Bin the data using autobinning.

  4. Fit a logistic regression model using fitmodel or fitConstrainedModel.

  5. Review and format the credit scorecard points using displaypoints and formatpoints. At this point in the workflow, if you have a license for Risk Management Toolbox, you have the option to create a compactCreditScorecard object (csc) using the compact function. You can then use the following functions displaypoints (Risk Management Toolbox), score (Risk Management Toolbox), and probdefault (Risk Management Toolbox) from the Risk Management Toolbox with the csc object.

  6. Score the data using score.

  7. Calculate the probabilities of default for the data using probdefault.

  8. Validate the quality of the credit scorecard model using validatemodel.

For more detailed information on this workflow, see Credit Scorecard Modeling Workflow.

Creation

Syntax

sc = creditscorecard(data)
sc = creditscorecard(___,Name,Value)

Description

example

sc = creditscorecard(data) creates a creditscorecard object by specifying data. The credit scorecard model, returned as a creditscorecard object, contains the binning maps or rules (cut points or category groupings) for one or more predictors.

example

sc = creditscorecard(___,Name,Value) sets Properties using name-value pairs and any of the arguments in the previous syntax. For example, sc = creditscorecard(data,'GoodLabel',0,'IDVar','CustID','ResponseVar','status','PredictorVars',{'CustAge','CustIncome'},'WeightsVar','RowWeights','BinMissingData',true). You can specify multiple name-value pairs.

Note

To use observation (sample) weights in the credit scorecard workflow, when creating a creditscorecard object, you must use the optional name-value pair WeightsVar to define which column in the data contains the weights.

Input Arguments

expand all

Data for the creditscorecard object, specified as a MATLAB® table, where each column of data can be any one of the following data types:

  • Numeric

  • Logical

  • Cell array of character vectors

  • Character array

  • Categorical

  • String

In addition, the table must contain a binary response variable. Before creating a creditscorecard object, perform a data preparation task to have appropriately structured data as input to a creditscorecard object. The data input sets the Data property.

Data Types: table

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 quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: sc = creditscorecard(data,'GoodLabel',0,'IDVar','CustAge','ResponseVar','status','PredictorVars',{'CustID','CustIncome'},'WeightsVar','RowWeights','BinMissingData',true)

Indicator for which of the two possible values in the response variable correspond to “Good” observations, specified as the comma-separated pair consisting of 'GoodLabel' and a numeric scalar, logical, or character vector. The GoodLabel name-value pair argument sets the GoodLabel property.

When specifying GoodLabel, follow these guidelines.

If Response Variable is...GoodLabel Must be...
numericnumeric
logicallogical or numeric
cell array of character vectorscharacter vector
character arraycharacter vector
categoricalcharacter vector

If not specified, GoodLabel is set to the response value with the highest count. However, if the optional WeightsVar argument is provided when creating the creditscorecard object, then counts are replaced with weighted frequencies. For more information, see Credit Scorecard Modeling Using Observation Weights.

GoodLabel can only be set when creating the creditscorecard object. This parameter cannot be set using dot notation.

Data Types: char | double

Variable name used as ID or tag for the observations, specified as the comma-separated pair consisting of 'IDVar' and a character vector. The IDVar data could be an ordinal number (for example, 1,2,3...), a Social Security number. This is provided as a convenience to remove this column from the predictor variables. IDVar is case-sensitive. The IDVar name-value pair argument sets the IDVar property.

You can set this optional parameter using the creditscorecard function or by using dot notation at the command line, as follows.

Example: sc.IDVar = 'CustID'

Data Types: char

Response variable name for the “Good” or “Bad” indicator, specified as the comma-separated pair consisting of 'ResponseVar' and a character vector. The response variable data must be binary. The ResponseVar name-value pair argument sets the ResponseVar property.

If not specified, ResponseVar is set to the last column of the data input. ResponseVar can only be set when creating the creditscorecard object using the creditscorecard function. ResponseVar is case-sensitive.

Data Types: char

Weights variable name, specified as the comma-separated pair consisting of 'WeightsVar' and a character vector to indicate which column name in the data table contains the row weights. WeightsVar is case-sensitive. The WeightsVar name-value pair argument sets the WeightsVar property, and this property can only be set at the creation of a creditscorecard object. If the name-value pair argument WeightsVar is not specified when creating a creditscorecard object, then observation weights are set to unit weights by default.

The WeightsVar values are used in the credit scorecard workflow by autobinning, bininfo, fitmodel, and validatemodel. For more information, see Credit Scorecard Modeling Using Observation Weights.

Data Types: char

Indicates if missing data is removed or displayed in a separate bin, specified as the comma-separated pair consisting of 'BinMissingdata' and a logical scalar with a value of true or false. If BinMissingData is true, the missing data for a predictor is displayed in a separate bin labeled <missing>.

Data Types: logical

Properties

expand all

Data used to create the creditscorecard object, specified as a table when creating a creditscorecard object. In the Data property, categorical predictors are stored as categorical arrays.

Example: sc.Data(1:10,:)

Data Types: table

Name of the variable used as ID or tag for the observations, specified as a character vector. This property can be set as an optional parameter when creating a creditscorecard object or by using dot notation at the command line. IDVar is case-sensitive.

Example: sc.IDVar = 'CustID'

Data Types: char

This property is read-only.

VarNames is a cell array of character vectors containing the names of all variables in the data. The VarNames come directly from the data input to the creditscorecard object. VarNames is case-sensitive.

Data Types: cell

Name of the response variable, “Good” or “Bad” indicator, specified as a character vector. The response variable data must be binary. If not specified, ResponseVar is set to the last column of the data input. This property can only be set with an optional parameter when creating a creditscorecard object. ResponseVar is case-sensitive.

Data Types: char

Name of the variable used as ID or tag to indicate which column name in the data table contains the row weights, specified as a character vector. This property can be set as an optional parameter (WeightsVar) when creating a creditscorecard object. WeightsVar is case-sensitive.

Data Types: char

Indicator for which of the two possible values in the response variable correspond to “Good” observations. When specifying GoodLabel, follow these guidelines:

If Response Variable is...GoodLabel must be:
numericnumeric
logicallogical or numeric
cell array of character vectorscharacter vector
character arraycharacter vector
categoricalcharacter vector

If not specified, GoodLabel is set to the response value with the highest count. This property can only be set with an optional parameter when creating a creditscorecard object. This property cannot be set using dot notation.

Data Types: char | double

Predictor variable names, specified using a cell array of character vectors containing names. By default, when you create a creditscorecard object, all variables are predictors except for IDVar and ResponseVar. This property can be modified using a name-value pair argument for the fitmodel function or by using dot notation. PredictorVars is case-sensitive and the predictor variable name cannot be the same as the IDVar or ResponseVar.

Example: sc.PredictorVars = {'CustID','CustIncome'}

Data Types: cell

Name of numeric predictors, specified as a character vector. This property cannot be set by using dot notation at the command line. It can only be modified using the modifypredictor function.

Data Types: char

Name of categorical predictors, specified as a character vector. This property cannot be set by using dot notation at the command line. It can only be modified using the modifypredictor function.

Data Types: char

Indicates if missing data is removed or displayed in a separate bin, specified as the comma-separated pair consisting of 'BinMissingdata' and a logical scalar with a value of true or false. If BinMissingData is true, the missing data for a predictor is displayed in a separate bin labeled <missing>. For more information on working with missing data, see Credit Scorecard Modeling with Missing Values.

Data Types: logical

creditscorecard PropertySet/Modify Property from Command Line Using creditscorecard FunctionModify Property Using Dot NotationProperty Not User-Defined and Value Is Defined Internally
DataNoNoYes, copy of data input
IDVarYesYesNo, but the user specifies this
VarNamesNoNoYes
ResponseVarYesNoIf not specified, set to last column of data input
WeightsVarNoNoYes
GoodLabelYesNoIf not specified, set to response value with highest count
PredictorVarsYes (also modifiable using fitmodel function)YesYes, but the user can modify this
NumericPredictorsNo (can only be modified using modifypredictor function)NoYes, but the user can modify this
CategoricalPredictorsNo (can only be modified using modifypredictor function)NoYes, but the user can modify this
BinMissingDataYesNoFalse by default, but the user can modify this

Object Functions

autobinningPerform automatic binning of given predictors
bininfoReturn predictor’s bin information
predictorinfoSummary of credit scorecard predictor properties
modifypredictorSet properties of credit scorecard predictors
fillmissingReplace missing values for credit scorecard predictors
modifybinsModify predictor’s bins
bindataBinned predictor variables
plotbinsPlot histogram counts for predictor variables
fitmodelFit logistic regression model to Weight of Evidence (WOE) data
fitConstrainedModelFit logistic regression model to Weight of Evidence (WOE) data subject to constraints on model coefficients
setmodelSet model predictors and coefficients
displaypointsReturn points per predictor per bin
formatpointsFormat scorecard points and scaling
scoreCompute credit scores for given data
probdefaultLikelihood of default for given data set
validatemodelValidate quality of credit scorecard model
compactCreate compact credit scorecard

Examples

collapse all

Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the data (using a dataset from Refaat 2011). 

load CreditCardData 
sc = creditscorecard(data)
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x7 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: ''
            PredictorVars: {1x10 cell}
                     Data: [1200x11 table]

This example uses:

Open Live Script

Use the CreditCardData.mat file to load the data (dataWeights) that contains a column (RowWeights) for the weights (using a dataset from Refaat 2011). 

load CreditCardData

Create a creditscorecard object using the optional name-value pair argument for 'WeightsVar'. 

sc = creditscorecard(dataWeights,'WeightsVar','RowWeights')
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: 'RowWeights'
                 VarNames: {1x12 cell}
        NumericPredictors: {1x7 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: ''
            PredictorVars: {1x10 cell}
                     Data: [1200x12 table]
Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the data (using a dataset from Refaat 2011). 

load CreditCardData 
sc = creditscorecard(data)
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x7 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: ''
            PredictorVars: {1x10 cell}
                     Data: [1200x11 table]

To display the creditscorecard object properties, use dot notation. 

sc.PredictorVars
ans = 1x10 cell
  Columns 1 through 4

    {'CustID'}    {'CustAge'}    {'TmAtAddress'}    {'ResStatus'}

  Columns 5 through 8

    {'EmpStatus'}    {'CustIncome'}    {'TmWBank'}    {'OtherCC'}

  Columns 9 through 10

    {'AMBalance'}    {'UtilRate'}


sc.VarNames
ans = 1x11 cell
  Columns 1 through 4

    {'CustID'}    {'CustAge'}    {'TmAtAddress'}    {'ResStatus'}

  Columns 5 through 8

    {'EmpStatus'}    {'CustIncome'}    {'TmWBank'}    {'OtherCC'}

  Columns 9 through 11

    {'AMBalance'}    {'UtilRate'}    {'status'}
Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the data (using a dataset from Refaat 2011). 

load CreditCardData 
sc = creditscorecard(data)
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x7 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: ''
            PredictorVars: {1x10 cell}
                     Data: [1200x11 table]

Since the IDVar property has public access, you can change its value at the command line. 

sc.IDVar = 'CustID'
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x6 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: 'CustID'
            PredictorVars: {1x9 cell}
                     Data: [1200x11 table]
Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the data (using a dataset from Refaat 2011). 

load CreditCardData 
sc = creditscorecard(data)
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x7 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: ''
            PredictorVars: {1x10 cell}
                     Data: [1200x11 table]

In this example, the default values for the properties ResponseVar, PredictorVars and GoodLabel are assigned when this object is created. By default, the property ResponseVar is set to the variable name that is in the last column of the input data ('status' in this example). The property PredictorVars contains the names of all the variables that are in VarNames, but excludes IDVar and ResponseVar. Also, by default in the previous example, GoodLabel is set to 0, since it is the value in the response variable (ResponseVar) with the highest count.

Display the creditscorecard object properties using dot notation. 

sc.PredictorVars
ans = 1x10 cell
  Columns 1 through 4

    {'CustID'}    {'CustAge'}    {'TmAtAddress'}    {'ResStatus'}

  Columns 5 through 8

    {'EmpStatus'}    {'CustIncome'}    {'TmWBank'}    {'OtherCC'}

  Columns 9 through 10

    {'AMBalance'}    {'UtilRate'}


sc.VarNames
ans = 1x11 cell
  Columns 1 through 4

    {'CustID'}    {'CustAge'}    {'TmAtAddress'}    {'ResStatus'}

  Columns 5 through 8

    {'EmpStatus'}    {'CustIncome'}    {'TmWBank'}    {'OtherCC'}

  Columns 9 through 11

    {'AMBalance'}    {'UtilRate'}    {'status'}

Since IDVar and PredictorVars have public access, you can change their values at the command line. 

sc.IDVar = 'CustID'
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x6 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: 'CustID'
            PredictorVars: {1x9 cell}
                     Data: [1200x11 table]


sc.PredictorVars = {'CustIncome','ResStatus','AMBalance'}
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {'CustIncome'  'AMBalance'}
    CategoricalPredictors: {'ResStatus'}
           BinMissingData: 0
                    IDVar: 'CustID'
            PredictorVars: {'ResStatus'  'CustIncome'  'AMBalance'}
                     Data: [1200x11 table]


disp(sc)
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {'CustIncome'  'AMBalance'}
    CategoricalPredictors: {'ResStatus'}
           BinMissingData: 0
                    IDVar: 'CustID'
            PredictorVars: {'ResStatus'  'CustIncome'  'AMBalance'}
                     Data: [1200x11 table]
Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the data (using a dataset from Refaat 2011). Then use name-value pair arguments for creditscorecard to define GoodLabel and ResponseVar. 

load CreditCardData 
sc = creditscorecard(data,'IDVar','CustID','GoodLabel',0,'ResponseVar','status')
sc = 
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x6 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 0
                    IDVar: 'CustID'
            PredictorVars: {1x9 cell}
                     Data: [1200x11 table]

GoodLabel and ResponseVar can only be set (enforced) when creating a creditscorecard object using creditscorecard.

Open Live Script

Create a creditscorecard object using the CreditCardData.mat file to load the dataMissing with missing values.

load CreditCardData 
head(dataMissing,5)
ans=5×11 table
    CustID    CustAge    TmAtAddress     ResStatus     EmpStatus    CustIncome    TmWBank    OtherCC    AMBalance    UtilRate    status
    ______    _______    ___________    ___________    _________    __________    _______    _______    _________    ________    ______

      1          53          62         <undefined>    Unknown        50000         55         Yes       1055.9        0.22        0   
      2          61          22         Home Owner     Employed       52000         25         Yes       1161.6        0.24        0   
      3          47          30         Tenant         Employed       37000         61         No        877.23        0.29        0   
      4         NaN          75         Home Owner     Employed       53000         20         Yes       157.37        0.08        0   
      5          68          56         Home Owner     Employed       53000         14         Yes       561.84        0.11        0   


fprintf('Number of rows: %d\n',height(dataMissing))
Number of rows: 1200

fprintf('Number of missing values CustAge: %d\n',sum(ismissing(dataMissing.CustAge)))
Number of missing values CustAge: 30

fprintf('Number of missing values ResStatus: %d\n',sum(ismissing(dataMissing.ResStatus)))
Number of missing values ResStatus: 40

Use creditscorecard with the name-value argument 'BinMissingData' set to true to bin the missing data in a separate bin. 

sc = creditscorecard(dataMissing,'IDVar','CustID','BinMissingData',true);
sc = autobinning(sc);
disp(sc)
  creditscorecard with properties:

                GoodLabel: 0
              ResponseVar: 'status'
               WeightsVar: ''
                 VarNames: {1x11 cell}
        NumericPredictors: {1x6 cell}
    CategoricalPredictors: {'ResStatus'  'EmpStatus'  'OtherCC'}
           BinMissingData: 1
                    IDVar: 'CustID'
            PredictorVars: {1x9 cell}
                     Data: [1200x11 table]

Display bin information for numeric data for 'CustAge' that includes missing data in a separate bin labelled <missing>. 

bi = bininfo(sc,'CustAge');
disp(bi)
         Bin         Good    Bad     Odds       WOE       InfoValue 
    _____________    ____    ___    ______    ________    __________

    {'[-Inf,33)'}     69      52    1.3269    -0.42156      0.018993
    {'[33,37)'  }     63      45       1.4    -0.36795      0.012839
    {'[37,40)'  }     72      47    1.5319     -0.2779     0.0079824
    {'[40,46)'  }    172      89    1.9326    -0.04556     0.0004549
    {'[46,48)'  }     59      25      2.36     0.15424     0.0016199
    {'[48,51)'  }     99      41    2.4146     0.17713     0.0035449
    {'[51,58)'  }    157      62    2.5323     0.22469     0.0088407
    {'[58,Inf]' }     93      25      3.72     0.60931      0.032198
    {'<missing>'}     19      11    1.7273    -0.15787    0.00063885
    {'Totals'   }    803     397    2.0227         NaN      0.087112

plotbins(sc,'CustAge')

Display bin information for categorical data for 'ResStatus' that includes missing data in a separate bin labelled <missing>. 

bi = bininfo(sc,'ResStatus');
disp(bi)
         Bin          Good    Bad     Odds        WOE       InfoValue 
    ______________    ____    ___    ______    _________    __________

    {'Tenant'    }    296     161    1.8385    -0.095463     0.0035249
    {'Home Owner'}    352     171    2.0585     0.017549    0.00013382
    {'Other'     }    128      52    2.4615      0.19637     0.0055808
    {'<missing>' }     27      13    2.0769     0.026469    2.3248e-05
    {'Totals'    }    803     397    2.0227          NaN     0.0092627

plotbins(sc,'ResStatus')

References

[1] Anderson, R. The Credit Scoring Toolkit. Oxford University Press, 2007.

[2] Refaat, M. Data Preparation for Data Mining Using SAS. Morgan Kaufmann, 2006.

[3] Refaat, M. Credit Risk Scorecards: Development and Implementation Using SAS. lulu.com, 2011.

See Also

Functions

Apps

Topics

External Websites

Introduced in R2014b

Financial Toolbox Documentation

Support

A Practical Guide to Modeling Financial Risk with MATLAB

A Practical Guide to Modeling Financial Risk with MATLAB

Download ebook