fit

R2026b

Fit shocked probability model

Since R2026b

collapse all in page

Syntax

spm = fit(spm)
spm = fit(spm,Name=Value)

Description

spm = fit(spm) runs the group- and subgroup-level optimizations in the shockedProbabilityModel object spm to determine the sensitivity coefficients. The function uses all variables in the Data property of spm, except for those variables denoted in the IDVar, GroupVar, SubGroupVar, BaselineProbabilityVar, and TargetProbabilityVar properties, as predictor variables.

example

spm = fit(spm,Name=Value) specifies options using one or more name-value arguments in addition to the input argument in the previous syntax. For example, spm = fit(spm,PredictorVars=["TempChange" "GDPChange"],Link="logistic") fits the model using specific predictor variables and a logistic link function.

example

Examples

collapse all

Open Live Script

Load sample climate data data from the sample file sampleClimateData.mat. Then use the sample data to create a shockedProbabilityModel object.

load sampleClimateData.mat data
spm = shockedProbabilityModel(data);

Use the fit object function to determine the sensitivity coefficients for the model.

spm = fit(spm)
spm = 
  shockedProbabilityModel with properties:

                              Data: [230×5 table]
                             IDVar: [0×0 string]
                          GroupVar: "Group"
                       SubGroupVar: "SubGroup"
            BaselineProbabilityVar: "BaselineProbability"
              TargetProbabilityVar: "TargetProbability"
                           ModelID: [0×0 string]
                       Description: [0×0 string]
                     PredictorVars: "ID"
          GroupSensitivityBaseline: [9×2 table]
        GroupSensitivityLowerBound: [9×2 table]
        GroupSensitivityUpperBound: [0×0 table]
      SubGroupSensitivityBaselines: [23×2 table]
    SubGroupSensitivityLowerBounds: [0×0 table]
    SubGroupSensitivityUpperBounds: [0×0 table]
                   LinearRelations: [0×0 table]
                              Link: "normal"
              ObjectiveFormulation: "inverse-cdf"
                      OptimOptions: [1×1 optim.options.Lsqlin]
                GroupSensitivities: dictionary (string ⟼ double) with 9 entries
             SubGroupSensitivities: dictionary (string ⟼ cell) with 23 entries
Open Live Script

Load sample data from samplePortfolioClimateData.mat. The sample data includes portolio-level climate data, lower and upper bounds for subgroup-level optimization, and linear relations data.

load samplePortfolioClimateData.mat calibrationPortfolioClimateData lowerSensitivityBounds upperSensitivityBounds linearRelations

The data in the table is organized according to these specifications:

  • ID: LoanID

  • Group: Sector

  • Subgroup: Segment

  • Baseline probability: TTCPD

  • Target probability: ExpertImmediatePD

Use these specifications with the data to create a shocked probability model.

spm = shockedProbabilityModel(calibrationPortfolioClimateData,IDVar="LoanID",GroupVar="Sector",SubGroupVar="Segment",BaselineProbabilityVar="TTCPD",TargetProbabilityVar="ExpertImmediatePD");

Use the linear relations data as well as the lower and upper bounds for subgroup-level optimization to determine the sensitivity coefficients for the model.

spm = fit(spm,GroupSensitivityBaseline=0,LinearRelations=linearRelations, ...
          SubGroupSensitivityLowerBounds=lowerSensitivityBounds,SubGroupSensitivityUpperBounds=upperSensitivityBounds, ...
          PredictorVars=["ShockedCapitalExpenditure" "ShockedDirectEmissionsCosts" "ShockedIndirectCosts" "ShockedRevenue"], ...
          SubGroupSensitivityBaselines=[-1 -1 -1 1],ObjectiveFormulation="cdf")
spm = 
  shockedProbabilityModel with properties:

                              Data: [230×13 table]
                             IDVar: "LoanID"
                          GroupVar: "Sector"
                       SubGroupVar: "Segment"
            BaselineProbabilityVar: "TTCPD"
              TargetProbabilityVar: "ExpertImmediatePD"
                           ModelID: [0×0 string]
                       Description: [0×0 string]
                     PredictorVars: ["ShockedCapitalExpenditure"    "ShockedDirectEmissionsCosts"    "ShockedIndirectCosts"    "ShockedRevenue"]
          GroupSensitivityBaseline: [9×2 table]
        GroupSensitivityLowerBound: [9×2 table]
        GroupSensitivityUpperBound: [0×0 table]
      SubGroupSensitivityBaselines: [23×5 table]
    SubGroupSensitivityLowerBounds: [23×5 table]
    SubGroupSensitivityUpperBounds: [23×5 table]
                   LinearRelations: [18×5 table]
                              Link: "normal"
              ObjectiveFormulation: "cdf"
                      OptimOptions: [1×1 optim.options.Lsqnonlin]
                GroupSensitivities: dictionary (string ⟼ double) with 9 entries
             SubGroupSensitivities: dictionary (string ⟼ cell) with 23 entries

Input Arguments

collapse all

Shocked probability model object, specified as a shockedProbabilityModel object.

Name-Value Arguments

expand all

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.

Example: spm = fit(spm,PredictorVars=["TempChange" "GDPChange"],Link="logistic",ObjectiveFormulation="cdf") fits the model with specific predictors, a logistic link function, and a CDF-based objective formulation.

Model

expand all

Model identifier, specified as a string scalar. Use this name-value argument to assign a label that distinguishes the model from other fitted models.

Model description, specified as a string scalar. Use this name-value argument to attach a description to the fitted model.

Names of predictor variables, specified as a string vector. By default, the predictor variables include all columns in spm.Data except those columns denoted by spm.IDVar, spm.GroupVar, spm.SubGroupVar, spm.BaselineProbabilityVar, and spm.TargetProbabilityVar columns.

Group-Level Optimization

expand all

Initial point for the group-level optimization, specified as a numeric scalar or a table.

  • If you specify GroupSensitivityBaseline as a numeric scalar, then the function applies that scalar to all groups.

  • If you specify GroupSensitivityBaseline as a table, then the table must have a column whose name matches the value of spm.GroupVar and a column whose name is "Sensitivity".

Data Types: double | table

Lower bound for the group-level optimization, specified as a numeric scalar or a table.

  • If you specify GroupSensitivityLowerBound as a numeric scalar, then the function applies that scalar to all groups.

  • If you specify GroupSensitivityLowerBound as a table, then the table must have a column whose name matches the value of spm.GroupVar and a column whose name is "Sensitivity".

Data Types: double | table

Upper bound for the group-level optimization, specified as [], a numeric scalar, or a table.

  • If you specify GroupSensitivityUpperBound as [], then the function does not apply an upper bound to any groups.

  • If you specify GroupSensitivityUpperBound as a numeric scalar, then the function applies that scalar to all groups.

  • If you specify GroupSensitivityUpperBound as a table, then the table must have a column whose name matches the value of spm.GroupVar and a column whose name is "Sensitivity".

Data Types: double | table

Subgroup-Level Optimization

expand all

Initial points for the subgroup-level optimization, specified as a numeric scalar or vector or a table.

  • If you specify SubGroupSensitivityBaseline as a numeric scalar, then the function applies that scalar to all subgroup/predictor pairs.

  • If you specify SubGroupSensitivityBaseline as a numeric vector, then the number of entries in the vector must match the number of entries in spm.PredictorVars.

  • If you specify SubGroupSensitivityBaseline as a table, then the table must have a column whose name matches the value of spm.SubGroupVar and columns whose names match those specified in the PredictorVars name-value argument.

Data Types: double | table

Lower bounds for the subgroup-level optimization, specified as [], a numeric scalar or vector, or a table.

  • If you specify SubGroupSensitivityLowerBounds as [], then the function does not apply a lower bound to any subgroup/predictor pairs.

  • If you specify SubGroupSensitivityLowerBounds as a numeric scalar, then the function applies that scalar to all subgroup/predictor pairs.

  • If you specify SubGroupSensitivityLowerBounds as a numeric vector, then the number of entries in the vector must match the number of entries in spm.PredictorVars.

  • If you specify SubGroupSensitivityLowerBounds as a table, then the table must have a column whose name matches the value of spm.SubGroupVar and columns whose names match those specified in the PredictorVars name-value argument.

Data Types: double | table

Upper bounds for the subgroup-level optimization, specified as [], a numeric scalar or vector, or a table.

  • If you specify SubGroupSensitivityUpperBounds as [], then the function does not apply an upper bound to any subgroup/predictor pairs.

  • If you specify SubGroupSensitivityUpperBounds as a numeric scalar, then the function applies that scalar to all subgroup/predictor pairs.

  • If you specify SubGroupSensitivityUpperBounds as a numeric vector, then the number of entries in the vector must match the number of entries in spm.PredictorVars.

  • If you specify SubGroupSensitivityUpperBounds as a table, then the table must have a column whose name matches the value of spm.SubGroupVar and columns whose names match those specified in the PredictorVars name-value argument.

Data Types: double | table

Linear relations between the predictor variables in the subgroup-level optimization, specified as a table. Use this name-value argument to impose linear constraints between the sensitivities of different predictor variables during the subgroup-level optimization. If you specify LinearRelations as a nonempty table, then the table must have a column whose name matches the value of spm.SubGroupVar and columns whose names match those specified in the PredictorVars name-value argument.

Optimization Settings

expand all

Link function, specified as "normal" or "logistic". The link function defines the main probability equation and corresponding objective function used in the optimization.

Objective function formulation, specified as "inverse-cdf" or "cdf".

  • "inverse-cdf" — The optimization relies on the lsqlin function in Optimization Toolbox™.

  • "cdf" — The optimization relies on the lsqnonlin function in Optimization Toolbox.

Optimization options, specified as an optimization options object.

  • If you specify ObjectiveFormulation as "inverse-cdf", then the object must be an lsqlin options object and the default value is optimoptions("lsqlin",Display="off").

  • If you specify ObjectiveFormulation as "cdf", then the object must be an lsqnonlin options object and the default value is optimoptions("lsqnonlin",Display="off").

Output Arguments

collapse all

Shocked probability model object, returned as a shockedProbabilityModel object. The function sets these properties in the object:

  • ModelID

  • Description

  • PredictorVars

  • GroupSensitivityBaseline

  • GroupSensitivityLowerBound

  • GroupSensitivityUpperBound

  • SubGroupSensitivityBaseline

  • SubGroupSensitivityLowerBound

  • SubGroupSensitivityUpperBound

  • LinearRelations

  • Link

  • ObjectiveFormulation

  • OptimOptions

  • GroupSensitivities

  • SubGroupSensitivities

Data Types: object

Version History

Introduced in R2026b

See Also

Objects

Functions

Topics