creditscorecard

Create creditscorecard object to build credit scorecard model

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

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.

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

data — Data for creditscorecard object

table

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

GoodLabel — Indicator for which of two possible values in response variable correspond to “Good” observations

set to the response value with the highest count (default) | character vector | numeric scalar | logical

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...
numeric	numeric
logical	logical or numeric
cell array of character vectors	character vector
character array	character vector
categorical	character 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

IDVar — Variable name used as ID or tag for observations

empty character vector '' (default) | character vector

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

ResponseVar — Response variable name for “Good” or “Bad” indicator

last column of the data input (default) | character vector

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

WeightsVar — Weights variable name

empty character vector '' (default) | character vector

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

BinMissingData — Indicates if missing data is removed or displayed in a separate bin

false (missing data removed) (default) | logical with value true or false

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

Data — Data used to create the creditscorecard object

table

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

IDVar — Name of the variable used as ID or tag for the observations

empty character vector '' (default) | character vector

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

VarNames — All variable names from the data input

VarNames come directly from data input to creditscorecard object (default)

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

ResponseVar — Name of the response variable, “Good” or “Bad” indicator

last column of the data input (default) | character vector

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

WeightsVar — Name of the variable used as ID or tag for weights

empty character vector '' (default) | character vector

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

GoodLabel — Indicator for which of the two possible values in the response variable correspond to “Good” observations

set to the response value with the highest count (default) | character vector | numeric scalar | logical

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:
numeric	numeric
logical	logical or numeric
cell array of character vectors	character vector
character array	character vector
categorical	character 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

PredictorVars — Predictor variable names

set difference between VarNames and {IDVar,ResponseVar} (default) | cell array of character vectors containing names

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

NumericPredictors — Name of numeric predictors

empty character vector '' (default) | character vector

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

CategoricalPredictors — Name of categorical predictors

empty character vector '' (default) | character vector

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

BinMissingData — Indicates if missing data is removed or displayed in a separate bin

false (missing data removed) (default) | logical with value true or false

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 Property	Set/Modify Property from Command Line Using creditscorecard Function	Modify Property Using Dot Notation	Property Not User-Defined and Value Is Defined Internally
Data	No	No	Yes, copy of data input
IDVar	Yes	Yes	No, but the user specifies this
VarNames	No	No	Yes
ResponseVar	Yes	No	If not specified, set to last column of data input
WeightsVar	No	No	Yes
GoodLabel	Yes	No	If not specified, set to response value with highest count
PredictorVars	Yes (also modifiable using fitmodel function)	Yes	Yes, but the user can modify this
NumericPredictors	No (can only be modified using modifypredictor function)	No	Yes, but the user can modify this
CategoricalPredictors	No (can only be modified using modifypredictor function)	No	Yes, but the user can modify this
BinMissingData	Yes	No	False by default, but the user can modify this

Object Functions

autobinning	Perform automatic binning of given predictors
bininfo	Return predictor’s bin information
predictorinfo	Summary of credit scorecard predictor properties
modifypredictor	Set properties of credit scorecard predictors
fillmissing	Replace missing values for credit scorecard predictors
modifybins	Modify predictor’s bins
bindata	Binned predictor variables
plotbins	Plot histogram counts for predictor variables
fitmodel	Fit logistic regression model to Weight of Evidence (WOE) data
fitConstrainedModel	Fit logistic regression model to Weight of Evidence (WOE) data subject to constraints on model coefficients
setmodel	Set model predictors and coefficients
displaypoints	Return points per predictor per bin
formatpoints	Format scorecard points and scaling
score	Compute credit scores for given data
probdefault	Likelihood of default for given data set
validatemodel	Validate quality of credit scorecard model
compact	Create compact credit scorecard

Examples

Create a creditscorecard Object

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]

Create a creditscorecard Object Containing Weights

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]

Display creditscorecard Object Properties

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

Change a Property Value for a creditscorecard Object

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]

Create a creditscorecard Object

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]

Create a creditscorecard Object and Set GoodLabel and ResponseVar

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.

Create a creditscorecard Object and Set the 'BinMissingData' Property

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

load CreditCardData 
head(dataMissing,5)

    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.

Version History

Introduced in R2014b