Input File Format
This document describes the xml input file for ccruncher-1.8.
In the distribution package you can find the DTD, the XSD and some XML
samples into the $CCRUNCHER/samples directory. The xml used as
example in this section can be found here.
The XML input file structure is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<ccruncher>
<title>your simulation title here</title>
<description>your simulation description here</description>
<paramaters> ... </parameters>
<interest> ... </interest>
<ratings> ... </ratings>
<mtransitions> ... </mtransitions>
<sectors> ... </sectors>
<mcorrels> ... </mcorrels>
<segmentations> ... </segmentations>
<portfolio> ... </portfolio>
</ccruncher>
The encoding attribute can be one of these values: UTF-8, UTF-16, ISO-8859-1, US-ASCII. Take into account that XML is case-sensitive. Title and description tags are optional.
Some configuration options are mutually exclusive. For the configuration options for which this occurs, please see the additional notes for suggestions of use.
Section Parameters
This section shows the properties of the problem that needs to be solved. The list can be delivered in any order.
Example
<parameters>
<property name="time.0" value="18/10/2009"/>
<property name="time.T" value="15/07/2015"/>
<property name="stopcriteria.maxiterations" value="30000"/>
<property name="stopcriteria.maxseconds" value="3600"/>
<property name="copula.type" value="t(5)"/>
<property name="copula.seed" value="0"/>
<property name="montecarlo.antithetic" value="true"/>
<property name="portfolio.onlyActiveObligors" value="true"/>
</parameters>
Property Attributes
| Name | Description | Type |
|---|---|---|
| time.0 | Starting date of the simulation. Initial obligors credit ratings, transition matrix and survival functions are relative to this date. The format of this attribute is: DD/MM/YYYY. | date |
| time.T | Ending date of the simulation. Portfolio credit risk is computed at this date. The format of this attribute is: DD/MM/YYYY. | date |
| stopcriteria.maxiterations | Maximum number of iterations performed by the Monte Carlo algorithm. If it has value 0, this stop criteria is not considered. ccruncher stops when a stop criteria is achieved. | int |
| stopcriteria.maxseconds | Maximum number of seconds that the current execution can last. If it has value 0, this stop criteria is not considered. ccruncher stops when a stop criteria is achieved. | int |
| copula.type | Type of copula used to generate correlated variables. Two families of copulas are implemented: the gaussian copula ('gaussian') and the t-Student copula ('t(n)' where n > 0 is the number of degrees of freedom). | string |
| copula.seed | Seed used to initialize a random number generator. If it has value 0 then a random number based on the current time will be used. This property is optional. Default value is 0. | long |
| montecarlo.antithetic | Specifies whether or not to use a variance reduction technique named antithetic. If you have doubts about setting this parameter then set it to 'false', otherwise set it to 'true'. | boolean |
| portfolio.onlyActiveObligors | If you want to simulate all the obligors, including obligors without risk along the time range, type 'false'. If you want to simulate only active obligors along the simulation period type 'true'. We suggest writing always 'true'. | boolean |
Section Interest
This section shows how to define the interest rates curve used to compute the Current Net Value of simulated losses. If you are in the euro area you can obtain these values from ECB.
Example
<interest type="compound">
<rate t="0" r="0.0%"/>
<rate t="1" r="4.0%"/>
<rate t="2" r="4.1%"/>
<rate t="3" r="4.5%"/>
<rate t="6" r="4.55%"/>
<rate t="12" r="4.8%"/>
<rate t="24" r="4.9%"/>
<rate t="60" r="5.0%"/>
<rate t="120" r="5.2%"/>
</interest>
Interest attributes
| Name | Description | Type |
|---|---|---|
| type | Determine how to apply interest curve. Allowed values are: simple, compound and continuous. The formulas used in each case are described in the Technical Document. This attribute is optional. Default value is compound. | string |
Rate attributes
| Name | Description | Type |
|---|---|---|
| t | Increment (in months) from the initial date of the interest rate curve. If a value between two given dates is needed, the value will be linearly interpolated. | int |
| r | Interest rate at time t. It is a value between -0.5 and 1.0. The value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053). | double |
Section Ratings
This section shows how to define the credit ratings. A minimum of two credit ratings is required: a non-default rating and a default rating.
Example
<ratings>
<rating name="AAA" description="prime"/>
<rating name="AA" description="high grade"/>
<rating name="A" description="upper medium grade"/>
<rating name="BBB" description="lower medium grade"/>
<rating name="BB" description="non investment grade speculative"/>
<rating name="B" description="highly speculative"/>
<rating name="CCC" description="extremely speculative"/>
<rating name="D" description="in default"/>
</ratings>
Rating Attributes
| Name | Description | Type |
|---|---|---|
| name | Credit rating identifier. All references to a credit rating, eg. obligor rating, are made using this field. Includes default rating in this list. | string |
| description | Credit rating description. This value is only used in reports. This description must be unique. | string |
Section Transition Matrix
This section shows how to define the transition matrix. ccruncher always checks that the sum of elements of each row is 1.0. Also, ccruncher checks that only one row with all probability concentrated in a unique element exists. The number of elements to be established is NxN, where N is the number of credit ratings. Alternatively, you can define the survival functions instead of a transition matrix. See additional notes for more information.
Example
<mtransitions period="12">
<transition from="AAA" to="AAA" value="92.83%" />
<transition from="AAA" to="AA" value="6.5%" />
<transition from="AAA" to="A" value="0.56%" />
<transition from="AAA" to="BBB" value="0.06%" />
<transition from="AAA" to="BB" value="0.05%" />
<transition from="AAA" to="B" value="0.0%" />
<transition from="AAA" to="CCC" value="0.0%" />
<transition from="AAA" to="D" value="0.0%" />
<transition from="AA" to="AAA" value="0.63%" />
<transition from="AA" to="AA" value="91.87%" />
<transition from="AA" to="A" value="6.64%" />
<transition from="AA" to="BBB" value="0.65%" />
<transition from="AA" to="BB" value="0.06%" />
<transition from="AA" to="B" value="0.11%" />
<transition from="AA" to="CCC" value="0.04%" />
<transition from="AA" to="D" value="0.0%" />
<transition from="A" to="AAA" value="0.08%" />
<transition from="A" to="AA" value="2.26%" />
<transition from="A" to="A" value="91.65%" />
<transition from="A" to="BBB" value="5.11%" />
<transition from="A" to="BB" value="0.61%" />
<transition from="A" to="B" value="0.23%" />
<transition from="A" to="CCC" value="0.02%" />
<transition from="A" to="D" value="0.04%" />
<transition from="BBB" to="AAA" value="0.05%" />
<transition from="BBB" to="AA" value="0.27%" />
<transition from="BBB" to="A" value="5.84%" />
<transition from="BBB" to="BBB" value="87.76%" />
<transition from="BBB" to="BB" value="4.74%" />
<transition from="BBB" to="B" value="0.98%" />
<transition from="BBB" to="CCC" value="0.15%" />
<transition from="BBB" to="D" value="0.21%" />
<transition from="BB" to="AAA" value="0.04%" />
<transition from="BB" to="AA" value="0.11%" />
<transition from="BB" to="A" value="0.64%" />
<transition from="BB" to="BBB" value="7.85%" />
<transition from="BB" to="BB" value="81.13%" />
<transition from="BB" to="B" value="8.27%" />
<transition from="BB" to="CCC" value="0.89%" />
<transition from="BB" to="D" value="1.07%" />
<transition from="B" to="AAA" value="0.0%" />
<transition from="B" to="AA" value="0.11%" />
<transition from="B" to="A" value="0.3%" />
<transition from="B" to="BBB" value="0.42%" />
<transition from="B" to="BB" value="6.75%" />
<transition from="B" to="B" value="83.08%" />
<transition from="B" to="CCC" value="3.86%" />
<transition from="B" to="D" value="5.48%" />
<transition from="CCC" to="AAA" value="0.19%" />
<transition from="CCC" to="AA" value="0.0%" />
<transition from="CCC" to="A" value="0.38%" />
<transition from="CCC" to="BBB" value="0.75%" />
<transition from="CCC" to="BB" value="2.44%" />
<transition from="CCC" to="B" value="12.03%" />
<transition from="CCC" to="CCC" value="60.71%" />
<transition from="CCC" to="D" value="23.5%" />
<transition from="D" to="AAA" value="0.0%" />
<transition from="D" to="AA" value="0.0%" />
<transition from="D" to="A" value="0.0%" />
<transition from="D" to="BBB" value="0.0%" />
<transition from="D" to="BB" value="0.0%" />
<transition from="D" to="B" value="0.0%" />
<transition from="D" to="CCC" value="0.0%" />
<transition from="D" to="D" value="100%" />
</mtransitions>
The above matrix is the S&P 1-year transition matrix which is adjusted for unrated bonds and covers the period between 01-Jan-1981 and 31-Dec-1998. It has been extracted from Estimating Credit Rating Transition Probabilities for Corporate Bonds.
MTransitions Attributes
| Name | Description | Type |
|---|---|---|
| period | Number of months covered by the transition matrix. Usually the transition matrix covers 1 year, and in such case, set the value to 12. | int |
Transition Attributes
| Name | Description | Type |
|---|---|---|
| from | Initial credit rating. This value must be a credit rating identifier, see name attribute in the credit rating tag. | string |
| to | Final credit rating. This value must be a credit rating identifier, see name attribute in the credit rating tag. | string |
| value | Probability for credit rating migration and must have a value between 0 and 1. The value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053). | double |
Section Sectors
This section shows how to define the sectors. A minimum of one sector is required.
Example
<sectors>
<sector name="S1" description='Consumer/service sector'/>
<sector name="S2" description='Forest/building products'/>
<sector name="S3" description='High technology'/>
<sector name="S4" description='Utilities'/>
<sector name="S5" description="Other sectors"/>
</sectors>
Sector Attributes
| Name | Description | Type |
|---|---|---|
| name | Sector identifier. All references to a sector, eg. obligor sector, are made using this field. | string |
| description | Sector description. This value is only used in reports. This description must be unique. | string |
Section Correlations
This section shows how to define the default correlation matrix between sectors. The correlation matrix must be symmetric and you only need to set up the upper triangle elements. Ccruncher checks that all the elements are in the range [-100%,+100%]. The number of elements to set up is (numsectors+1) x numsectors / 2.
Example
<mcorrels>
<sigma sector1="S1" sector2="S1" value="15.1%"/>
<sigma sector1="S1" sector2="S2" value="6.2%"/>
<sigma sector1="S1" sector2="S3" value="8.6%"/>
<sigma sector1="S1" sector2="S4" value="3.9%"/>
<sigma sector1="S1" sector2="S5" value="9.1%"/>
<sigma sector1="S2" sector2="S2" value="17.9%"/>
<sigma sector1="S2" sector2="S3" value="6.3%"/>
<sigma sector1="S2" sector2="S4" value="10.2%"/>
<sigma sector1="S2" sector2="S5" value="8.8%"/>
<sigma sector1="S3" sector2="S3" value="17.5%"/>
<sigma sector1="S3" sector2="S4" value="7.3%"/>
<sigma sector1="S3" sector2="S5" value="7.1%"/>
<sigma sector1="S4" sector2="S4" value="12.8%"/>
<sigma sector1="S4" sector2="S5" value="6.4%"/>
<sigma sector1="S5" sector2="S5" value="15.0%"/>
</mcorrels>
Sigma Attributes
| Name | Description | Type |
|---|---|---|
| sector1 | First sector involved in correlation value. This value must be a sector identifier, see name attribute in sector tag. | string |
| sector2 | second sector involved in correlation value. This value must be a sector identifier, see name attribute in sector tag. | string |
| value | Correlation of defaults times between sector1 and sector2. Correlation(defaults(S1), defaults(S2)). The value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053). | double |
Section Segmentations
This section shows how to define portfolio segmentations. Segmentations allow you to analyze your portfolio's risk according to a hierarchical organization or another type of segmentation. A segmentation is composed of segments. There are 2 types of segmentations:
- obligor segmentations, eg. sector, obligor size, initial credit rating, etc.
- asset segmentations, eg. products, branch where the contract is made, etc.
All segmentations must be complete, so that an element belongs to only one segment and the union of all segments constitutes the whole portfolio. Every segmentation must have a segment named 'unassigned' defined in an implicit way. If a obligor (or an asset) does not belong to any segment, then it is considered part of the 'unassigned' segment. Finally, there are 2 special segmentations: 'obligors' (one segment per obligor) and 'assets' (one segment per asset), and in these cases you don't need to specify all the segments, because these are defined implicitly.
Example
<segmentations>
<segmentation name="portfolio" components="asset"/>
<segmentation name="obligors" components="obligor">
<segment name="*"/>
</segmentation>
<segmentation name="assets" components="asset">
<segment name="*"/>
</segmentation>
<segmentation name="sectors" components="obligor">
<segment name="S1"/>
<segment name="S2"/>
<segment name="S3"/>
<segment name="S4"/>
<segment name="S5"/>
</segmentation>
<segmentation name="size" components="obligor">
<segment name="large"/>
<segment name="medium"/>
<segment name="small"/>
</segmentation>
<segmentation name="products" components="asset">
<segment name="bond"/>
<segment name="loan"/>
<segment name="lease"/>
<segment name="mortgage"/>
<segment name="line of credit"/>
<segment name="bank guarantee"/>
</segmentation>
<segmentation name="offices" components="asset">
<segment name="0001"/>
<segment name="0002"/>
<segment name="0003"/>
<segment name="0004"/>
</segmentation>
</segmentations>
Segmentation Attributes
| Name | Description | Type |
|---|---|---|
| name | Segmentation identifier. All references to a segmentation, eg. belongs-to tag, are made using this field. | string |
| components | Type of segments. Accepted values are 'obligor' and 'asset'. | string |
Segment Attributes
| Name | Description | Type |
|---|---|---|
| name | Segment name. Different segmentations can have segments with the same name. All references to a segment, eg. belongs-to tag, are made using this field and always in conjunction with the segmentation. If a segmentation doesn't have any segments, all the elements belong to the 'unassigned' segment. The 'obligors' and 'assets' segmentations allow defining the '*' segment. The '*' segment contains an implicit definition of a segment to every asset and obligor. | string |
Section Portfolio
This section shows how to define the portfolio. A portfolio is a set of assets. The description of assets is done by listing the expected exposures and recovery rates in case of default. Assets are grouped by obligor.
Recovery can be defined at 3 different levels: obligor, asset and data value. When a default occurs at time t, we get the recovery at time t (or the closest date above). If this recovery is not reported, we get the asset recovery. If this recovery is not reported, we get the obligor recovery.When a default occurs at time t, in the beta distribution case, a new sample is drawn. In the obligor level, this drawn is shared by all assets that have not defined a recovery at t.
Example
<portfolio>
<obligor rating="A" sector="S1" id="000001">
<belongs-to segmentation="sectors" segment="S1"/>
<belongs-to segmentation="size" segment="medium"/>
<asset id="op1" date="01/01/2005" recovery="80%">
<belongs-to segmentation="products" segment="bond"/>
<belongs-to segmentation="offices" segment="0001"/>
<data>
<values at="01/06/2005" exposure="2000.0" />
<values at="01/06/2006" exposure="1900.0" />
<values at="01/06/2007" exposure="1800.0" />
<values at="01/06/2008" exposure="1700.0" />
<values at="01/06/2009" exposure="1600.0" />
<values at="01/06/2010" exposure="1500.0" />
<values at="01/06/2011" exposure="1400.0" />
<values at="01/06/2012" exposure="1300.0" />
<values at="01/06/2013" exposure="1200.0" />
<values at="01/06/2014" exposure="1100.0" />
</data>
</asset>
<asset id="op2" date="01/06/2008">
<belongs-to segmentation="offices" segment="0004"/>
<belongs-to segmentation="products" segment="bond"/>
<data>
<values at="01/07/2009" exposure="4400.0" recovery="75%" />
<values at="01/07/2011" exposure="3920.0" recovery="70%" />
<values at="01/07/2013" exposure="3340.0" recovery="65%" />
<values at="01/07/2015" exposure="2960.0" recovery="60%" />
<values at="01/07/2017" exposure="2480.0" recovery="55%" />
</data>
</asset>
</obligor>
<obligor rating="B" sector="S2" id="000002" recovery="20%">
<belongs-to segmentation="sectors" segment="S2"/>
<belongs-to segmentation="size" segment="large"/>
<asset id="op3" date="01/06/2003">
<belongs-to segmentation="offices" segment="0003"/>
<belongs-to segmentation="products" segment="bond"/>
<data>
<values at="01/01/2005" exposure="1750.0" />
<values at="01/06/2007" exposure="1600.0" />
<values at="01/01/2009" exposure="1450.0" />
<values at="01/06/2011" exposure="1300.0" />
<values at="01/01/2013" exposure="1150.0" />
</data>
</asset>
</obligor>
<obligor rating="CCC" sector="S2" id="000003">
<belongs-to segmentation="sectors" segment="S2"/>
<belongs-to segmentation="size" segment="medium"/>
<asset id="op4" date="01/01/1999" recovery="beta(2.5,2.7)">
<belongs-to segmentation="offices" segment="0003"/>
<belongs-to segmentation="products" segment="bond"/>
<data>
<values at="01/01/2000" exposure="2400.0" />
<values at="01/01/2001" exposure="2300.0" />
<values at="01/01/2002" exposure="2200.0" />
<values at="01/01/2003" exposure="2100.0" />
<values at="01/01/2004" exposure="lognormal(6.5,1.0)" />
<values at="01/01/2005" exposure="1900.0" />
<values at="01/01/2006" exposure="exponential(1800.0)" />
<values at="01/01/2007" exposure="1700.0" />
<values at="01/01/2008" exposure="uniform(1500.0,1700.0)" />
<values at="01/01/2009" exposure="1500.0" />
<values at="01/01/2010" exposure="gamma(2800.0,0.5)" />
<values at="01/01/2011" exposure="1300.0" />
<values at="01/01/2012" exposure="normal(1200.0,100.0)" />
<values at="01/01/2013" exposure="1100.0" />
</data>
</asset>
</obligor>
</portfolio>
Note how the obligor does not have any 'belongs-to segmentation=obligor' defined. This definition is made implicitly and the same is done for 'asset'. If you try to assign a obligor to a segmentation of asset components or vice versa, the input file will be rejected.
Portfolio Attributes
| Name | Description | Type |
|---|---|---|
| include |
Indicates the filepath to portfolio file relative to the main input file location.
The format of the portfolio file is exactly the same of the section
portfolio where the root tag of this file is portfolio. This attribute is optional.
If your portfolio is large and you plan to simulate it multiple times using distinct
parameters use this feature, otherwise this attribute can be omitted.
|
string |
Obligor Attributes
| Name | Description | Type |
|---|---|---|
| id | Unique obligor identifier. Used by implicit obligor segmentation. | string |
| rating | Initial obligor credit rating at time t0, see attribute time.0 at the parameters section. This value must be a credit rating identifier, see name attribute in rating tag. | string |
| sector | Sector where this obligor is included. This value must be a sector identifier, see name attribute in sector tag. | string |
| recovery |
Default recovery used in absence of recovery in the description of assets.
Recovery can be a fixed value or a probability distribution. In the first case,
the fixed value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053).
In the second case, you can model recovery using the following distributions: • beta(α,β), where α > 0 and β > 0 • uniform(a,b), where 0 ≤ a < b ≤ 1 This attribute is optional. |
double |
Belongs-To Attributes
| Name | Description | Type |
|---|---|---|
| segmentation | Segmentation identifier. This value must be a segmentation identifier, see name attribute in segmentation tag. | string |
| segment | Segment identifier. This value must be a segment identifier, see name attribute in segment tag. | string |
Asset Attributes
| Name | Description | Type |
|---|---|---|
| id | Unique asset identifier. Used by implicit asset segmentation. | string |
| date | Date (in format DD/MM/YYYY) from wich there is credit risk, eg. bond buy date or loan signature. | date |
| recovery |
Default recovery used in absence of recovery in the description of assets.
Recovery can be a fixed value or a probability distribution. In the first case,
the fixed value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053).
In the second case, you can model recovery using the following distributions: • beta(α,β), where α > 0 and β > 0 • uniform(a,b), where 0 ≤ a < b ≤ 1 This attribute is optional. |
double |
Values Attributes
| Name | Description | Type |
|---|---|---|
| at | Date (in format DD/MM/YYYY) where the values take place. | date |
| exposure |
Esposure at date "at". Amount that lender can lose in case of obligor's default
on the indicated date. Exposure can be a fixed value or a probability distribution.
In the first case, set the numeric value that represents the exposure (eg. 50000).
In the second case, you can model recovery using the folowing distributions: • lognormal(μ,σ), where μ > 0 and σ > 0 • exponential(β), where β > 0 is the survival parameter • uniform(a,b), where a > 0 and b > 0 • gamma(k,ρ), where k > 0 and ρ > 0 • normal(μ,σ), where μ > 0 and σ > 0. Values less than 0 are truncated to 0. |
double |
| recovery |
The portion of loss that will be recovered in case of default at date
"at". This value takes into account guarantees, the cost to take legal actions,
recovery rate based on historical data, etc.
Recovery can be a fixed value or a probability distribution. In the first case,
the fixed value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053).
In the second case, you can model recovery using the following distributions: • beta(α,β), where α > 0 and β > 0 • uniform(a,b), where 0 ≤ a < b ≤ 1 |
double |
Additional Notes
Section Survival Function
The survival data is often not available, and where it is available, it is often inconsistent or not representative. For this reason it is better to work with the transition matrix. Ccruncher will take care to convert the transition matrix in the corresponding survival functions. This implies that the credit rating transitions follow a Markov model. Sometimes this asumption is not acceptable because we desire that transition probabilities change over the simulation period or we plan to do stress tests over the default probabilites. In these cases it recommended to define the survival functions explicitely.
You must define either a mtransitions matrix or a survival function, but not both. This section contains the survival function for each credit rating. If this section is non provided, the survival function will be computed using the transition matrix. You don't need to fill all time values. The survival function is monotonously decreasing and has a value of 1 when time is 0 for all credit ratings other than default. The survival function of the default rating is always 0.
Example
<survival>
<svalue rating="AAA" t="0" value="100.0%"/>
<svalue rating="AA" t="0" value="100.0%"/>
<svalue rating="A" t="0" value="100.0%"/>
<svalue rating="BBB" t="0" value="100.0%"/>
<svalue rating="BB" t="0" value="100.0%"/>
<svalue rating="B" t="0" value="100.0%"/>
<svalue rating="CCC" t="0" value="0.0%"/>
<svalue rating="D" t="0" value="0.0%"/>
<svalue rating="AAA" t="6" value="99.96%"/>
<svalue rating="AA" t="6" value="98.54%"/>
<svalue rating="A" t="6" value="97.19%"/>
<svalue rating="BBB" t="6" value="95.98%"/>
<svalue rating="BB" t="6" value="92.63%"/>
<svalue rating="B" t="6" value="85.72%"/>
<svalue rating="CCC" t="6" value="78.88%"/>
<svalue rating="D" t="6" value="0.0%"/>
...
</survival>
Svalue Attributes
| Name | Description | Type |
|---|---|---|
| rating | This value must be a credit rating identifier, see name attribute in the rating tag. | string |
| t | Time (in months) from starting date time.0. | int |
| value | Probability that a obligor with initial rating rating survives (or: does not default) at time t. It must have a value between 0 and 1. The value can be set as percentage (eg. 5.3%) or absolute value (eg. 0.053). | double |