02-run-stress-test.RmdThis vignette describes in detail, how to run a climate transition
risk stress test, using the function run_trisk() to
calculate the credit risk. Additionally, the function
run_lrisk() is elaborated upon, which can be used to run
the climate litigation stress test.
In order to keep this vignette concise, we assume the following has been set up:
r2dii.climate.stress.test. Note that this may require
installing additional packages. You will be prompted to install these in
case any are missing.The climate transition risk stress test can be run for a single set of parameters with one value per input argument or as a sensitivity analysis, where one of the input arguments is iterated over and gets a vector of parameters and all other arguments get one input value each. We will look at both cases.
Use library() to attach the package
File paths must always be specified in the arguments of run_trisk() or run_lrisk(). They are the only arguments which do not have a default value and must be set by the user.
run_trisk(
input_path = "/example_project/project_input/",
output_path = "/example_project/output"
)
run_lrisk(
input_path = "/example_project/project_input/",
output_path = "/example_project/output",
return_results = TRUE
)This will calculate the transition or litigation risk stress test and write the results, along with a log file, into the designated output directory, using the default values for all detail arguments.
NOTE: The default mode will not
return any objects within the R session. We find this is the
easiest and most user friendly way to obtain results. We alternatively
provide the option that the function returns a list holding the result
objects by setting the argument return results to TRUE .
This allows the user to inspect and further analyze the data directly in
R.
The r2dii.climate.stress.test currently supports a number of scenario geographies and four of the PACTA for Banks sectors of company production. They are the following:
scenario_geography_x_ald_sector <- get_scenario_geography_x_ald_sector("/example_project/project_input/")
sectors <- unique(scenario_geography_x_ald_sector$ald_sector)
print(sectors)Note that the supported sectors do depend on the
scenario_geography (i.e. the geographical region
(concerning asset location) results shall be calculated for). All
supported scenario geographies are the following:
scenario_geographies <- unique(scenario_geography_x_ald_sector$scenario_geography)
print(scenario_geographies)One can use a helper function to obtain the supported scenario_geographies for a sector as follows:
geographies_for_sector("/example_project/project_input/", "Coal")Specifications on the detail arguments are summarized in the
following overview. The defaults that are used if the argument is not
adjusted when calling run_trisk() or
run_lrisk() can be found in column default.
The user may change any detail argument by explicitly passing it to the
function. Note that there are allowed values for each of the inputs. For
logical or character variables refer to column allowed, for
numeric variables the allowed values are the range from min
(inclusive) to max (inclusive).
stress_test_argumentsNote that special special rules apply for the variables
baseline_scenario and shock_scenario. Baseline
and shock scenarios can in principle be selected from the following:
Which scenarios are supported however depends on the analysed
sector and scenario_geography.
NOTE: It is strongly recommended to
select a baseline_scenario and a
shock_scenario from the same scenario source, as indicated
by the part of the scenario name in front of the underscore symbol.
The meaning of each of the detail arguments is as follows:
baseline_scenario holds the name of the baseline
scenario to be used in the stress test. We use a business-as-usual
scenario for the baseline.shock_scenario holds the name of the scenario that
companies are forced to transition to via a late and sudden shock. We
use an ambitious transition scenario as the shock scenario.
(NOTE: In almost all use cases, it is advisable to use
baseline and shock scenarios from the same scenario source. We do not
recommend deviating from that, if you do not have a very particular
reason to do so.)lgd is the loss given default used in the expected loss
calculation.risk_free_rate the risk free interest rate. Input
parameter to the Merton credit risk model.discount_rate the annual rate at which future cash
flows are discounted when calculating the net present value of companies
in the loan book. Since the net present values are indirect inputs into
the Merton credit risk model, this parameter my be relevant.growth_rate the perpetual ‘economic’ growth rate used
in the discounted cash flow model for the calculation of terminal value
of each firm in end_year + 1. Must be positive and strictly smaller than
discount_rate.div_netprofit_prop_coef coefficient that indicates what
share of the net present value should be considered to derive the equity
value of a company.shock_year year in which the policy is introduced, that
adjusts the production values of companies to stay in line with carbon
budgets.fallback_term indicates which maturity the loans in the
loan book are assumed to have. At this point we assume these are rolled
over every year.scenario_geography indicates which geographical
region(s) (concerning asset location) results shall be calculated
for.use_company_terms_arg logical parameter, indicating if
individually provided terms for companies as configured in
company_terms.csv shall be used instead of fallback as provided in
fallback_term. The default is FALSE. For more details
compare “Advanced
data settings”.return_results Logical parameter that indicates if the
outputs of the analysis should be directly written to the indicated
output path or simply returned as a list of results within the running
session. The default is FALSE, which writes the outputs to the target
directory and does not return them as a list object in R.lrisk holds the following three additional arguments:
scc, describes the social cost of carbon per excess ton
of CO2 emitted. It is the price for each surplus ton of CO2 that goes
into the calculation of the carbon liability of a company.settlement_factor is a catch all factor (ratio) that
can be used to adjust the expected payout of the settlement due to
further data gaps.exp_share_damages_paid is the ratio that defines the
expected share of the calculated social cost of carbon that is
considered in the liability.This can follow historical precedents such
as the Tobacco Master Settlement that had a an expected share of 2.7% of
the damages paid.The user may want to run a stress test that is tailored to their
assumptions about a plausible transition risk shock scenario. For
example, the user could decide to set a lower
risk_free_rate and shock the companies earlier than by
default, using:
run_trisk(
input_path = "/example_project/project_input/",
output_path = "/example_project/output",
risk_free_rate = 0.01,
shock_year = 2028
)NOTE: One important input argument that affects the behavior of where the results are written, is the argument return_results. Per default it is set to FALSE, which means that results are written as csv files to a sub directory in the output_path and the user must open these files to view the results. If the user wants to view the results directly in R, they can set the argument to TRUE which will return them as a list of data frames in the R session. This means they are not written to the designated output_path however, so the user must do this by themselves if the results ought to be kept. In this case, the user must still provide an output path though, as every calculation will write a log file.
The output files are written into a sub directory of the path
indicated as output_path in the function call. The name of
the sub directory is created from the time stamp of the analysis and a
suffix. The suffix _standard is used when each argument
uses a single parameter value. If a sensitivity analysis (see below) is
run the name of the varied detail variable is used. The sub directory
will be generated automatically, this way we ensure that no existing
results are overwritten.
log_file_standard.txtcrispy_output_standard.csvcompany_trajectories_standard.csvIn case the user wants to understand the sensitivities of the model to the input parameters mentioned above, it is straight forward to run a sensitivity analysis that does exactly that.
In order to do that, one simply passes a vector of allowed values for one (and only one) of the detail arguments when running the stress test function. This will lead to the model iterating over the set of values passed for the chosen argument, while keeping all other input arguments constant.
If the user wishes to understand the impact of the
shock_year on the results for example, they can run the
following:
run_trisk(
input_path = "/example_project/project_input/",
output_path = "/example_project/output",
shock_year = c(2025, 2028, 2032, 2035)
)This will yield outputs with four versions of the stress test, one for each of the shock years indicated. All the results will be written into one file per output type for ease of use, e.g.:
company_trajectories_shock_year.csvcrispy_output_shock_year.csvlog_file_shock_year.txtNOTE: The suffix of the files is now changed to mirror which variable was iterated over. This enables the user to run multiple different sensitivity analyses for a project and easily navigate these.
When running a sensitivity analysis on one input, the user can still use other values than the default parameters for the other input arguments.
For example, when iterating over the shock_year, it is
still possible to use a risk_free_rate lower than the
default like so:
run_trisk(
input_path = "/example_project/project_input/",
output_path = "/example_project/output",
risk_free_rate = 0.01,
shock_year = c(2025, 2028, 2032, 2035)
)NOTE that the selected detail arguments will be written to the result files so that it is always possible to understand which parameters were used in any given calculation.
Detailed explanations of the result files can be found in the vignette: Understand the output files of the transition risk stress test.