creditMigrationCopula Simulation Workflow

This example shows a common workflow for using a creditMigrationCopula object for a portfolio of counterparty credit ratings.

Step 1. Create a creditMigrationCopula object with a 4-factor model

Load the saved portfolio data.

load CreditMigrationData.mat;

Scale the bond prices for portfolio positions for each bond.

migrationValues = migrationPrices .* numBonds;

Create a creditMigrationCopula object with a 4-factor model using creditMigrationCopula.

cmc = creditMigrationCopula(migrationValues,ratings,transMat,...
lgd,weights,'FactorCorrelation',factorCorr)

cmc = 
  creditMigrationCopula with properties:

            Portfolio: [250x5 table]
    FactorCorrelation: [4x4 double]
         RatingLabels: [8x1 string]
     TransitionMatrix: [8x8 double]
             VaRLevel: 0.9500
          UseParallel: 0
      PortfolioValues: []

Step 2. Set the VaRLevel to 99%.

Set the VarLevel property for the creditMigrationCopula object to 99% (the default is 95%).

 cmc.VaRLevel = 0.99;

Step 3. Display the Portfolio property for information about migration values, ratings, LGDs, and weights.

Display the Portfolio property containing information about migration values, ratings, LGDs, and weights. The columns in the migration values are in the same order of the ratings, with the default rating in the last column.

 head(cmc.Portfolio)

ans=8×5 table
    ID    MigrationValues    Rating     LGD                    Weights              
    __    _______________    ______    ______    ___________________________________

    1      [1x8 double]      "A"       0.6509      0       0       0     0.5     0.5
    2      [1x8 double]      "BBB"     0.8283      0    0.55       0       0    0.45
    3      [1x8 double]      "AA"      0.6041      0     0.7       0       0     0.3
    4      [1x8 double]      "BB"      0.6509      0    0.55       0       0    0.45
    5      [1x8 double]      "BBB"     0.4966      0       0    0.75       0    0.25
    6      [1x8 double]      "BB"      0.8283      0       0       0    0.65    0.35
    7      [1x8 double]      "BB"      0.6041      0       0       0    0.65    0.35
    8      [1x8 double]      "BB"      0.4873    0.5       0       0       0     0.5

Step 4. Display migration values for a counterparty.

For example, you can display the migration values for the first counterparty. Note that the value for default is higher than some of the non-default ratings. This is because the migration value for the default rating is a reference value (for example, face value, forward value at current rating, or other) that is multiplied by the recovery rate during the simulation to get the value of the asset in the event of default. The recovery rate is 1-LGD when the LGD input to creditMigrationCopula is a constant LGD value (the LGD input has one column). The recovery rate is a random quantity when the LGD input to creditMigrationCopula is specified as a mean and standard deviation for a beta distribution (the LGD input has two columns).

bar(cmc.Portfolio.MigrationValues(1,:))
xticklabels(cmc.RatingLabels)
title('Migration Values for First Company')

Step 5. Run a simulation.

Use the simulate function to simulate 100,000 scenarios.

 cmc = simulate(cmc,1e5)

cmc = 
  creditMigrationCopula with properties:

            Portfolio: [250x5 table]
    FactorCorrelation: [4x4 double]
         RatingLabels: [8x1 string]
     TransitionMatrix: [8x8 double]
             VaRLevel: 0.9900
          UseParallel: 0
      PortfolioValues: [1x100000 double]

Step 6. Generate a report for the portfolio risk.

Use the portfolioRisk function to obtain a report for risk measures and confidence intervals for EL, Std, VaR, and CVaR.

[portRisk,RiskConfidenceInterval] = portfolioRisk(cmc)

portRisk=1×4 table
      EL       Std      VaR     CVaR 
    ______    _____    _____    _____

    4573.9    13039    56515    84463

RiskConfidenceInterval=1×4 table
           EL                Std               VaR               CVaR     
    ________________    ______________    ______________    ______________

    4493.1    4654.7    12982    13096    55043    58038    82485    86441

Step 7. Visualize the distribution.

View a histogram of the portfolio values.

figure
h = histogram(cmc.PortfolioValues,125);
title('Distribution of Portfolio Values');

Step 8. Overlay the value if all counterparties maintain current credit ratings.

Overlay the value that the portfolio object (cmc) takes if all counterparties maintain their current credit ratings.

CurrentRatingValue = portRisk.EL + mean(cmc.PortfolioValues);
 
hold on
plot([CurrentRatingValue CurrentRatingValue],[0 max(h.Values)],'LineWidth',2);
grid on

Step 9. Generate a risk contributions report.

Use the riskContribution function to display the risk contribution. The risk contributions, EL and CVaR, are additive. If you sum each of these two metrics over all the counterparties, you get the values reported for the entire portfolio in the portfolioRisk table.

rc = riskContribution(cmc);
disp(rc(1:10,:))

    ID      EL       Std       VaR       CVaR 
    __    ______    ______    ______    ______

     1    16.397    40.977    192.11    254.12
     2    9.1179    21.417      83.3    134.31
     3    5.7873    24.887    99.573    236.84
     4    6.4235     57.71    192.06    338.23
     5    22.739    72.371    289.12    544.69
     6    10.776    111.12    327.96    704.29
     7    2.9046     88.98    324.91     551.4
     8    12.152    42.123    189.38    265.97
     9    2.1567    4.0432    3.2359    26.112
    10    1.7495    2.4593    11.003    15.933

Step 10. Simulate the risk exposure with a t copula.

To use a t copula with 10 degrees of freedom, use the simulate function with optional input arguments. Save the results to a new creditMigrationCopula object (cmct).

cmct = simulate(cmc,1e5,'Copula','t','DegreesOfFreedom',10)

cmct = 
  creditMigrationCopula with properties:

            Portfolio: [250x5 table]
    FactorCorrelation: [4x4 double]
         RatingLabels: [8x1 string]
     TransitionMatrix: [8x8 double]
             VaRLevel: 0.9900
          UseParallel: 0
      PortfolioValues: [1x100000 double]

Step 11. Generate a report for the portfolio risk for the t copula.

Use the portfolioRisk function to obtain a report for risk measures and confidence intervals for EL, Std, VaR, and CVaR.

[portRisk2,RiskConfidenceInterval2] = portfolioRisk(cmct)

portRisk2=1×4 table
      EL       Std      VaR        CVaR   
    ______    _____    _____    __________

    4553.6    17158    72689    1.2545e+05

RiskConfidenceInterval2=1×4 table
           EL                Std               VaR                    CVaR          
    ________________    ______________    ______________    ________________________

    4447.2    4659.9    17083    17233    70834    75063    1.2144e+05    1.2947e+05

Step 12. Visualize the distribution for the t copula.

View a histogram of the portfolio values.

figure
h = histogram(cmct.PortfolioValues,125);
title('Distribution of Portfolio Values for t Copula');

Step 13. Overlay the value if all counterparties maintain current credit ratings for t copula.

Overlay the value that the portfolio object (cmct) takes if all counterparties maintain their current credit ratings.

CurrentRatingValue2 = portRisk2.EL + mean(cmct.PortfolioValues);

hold on
plot([CurrentRatingValue2 CurrentRatingValue2],[0 max(h.Values)],'LineWidth',2);
grid on