Input File Reference
This document describes the xml input file for CCruncher-1.1.
In the distribution package you can find the DTD, the XSD and some XML
samples into the $CCRUNCHER/samples directory.
The main XML file structure is like this:
<?xml version="1.0" encoding="ISO-8859-1"?>
<ccruncher>
<!-- put sections here (see below) -->
</ccruncher>
where 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.
Section Params
This section shows the properties of the problem that need to
be solved. The list can be unordered.
Example
<params>
<property name="time.begindate" value="18/02/2003"/>
<property name="time.steps" value="12"/>
<property name="time.steplength" value="2"/>
<property name="stopcriteria.maxiterations" value="3000"/>
<property name="stopcriteria.maxseconds" value="30000000"/>
<property name="copula.type" value="gaussian"/>
<property name="copula.seed" value="387650932874"/>
<property name="montecarlo.antithetic" value="false"/>
<property name="portfolio.onlyActiveBorrowers" value="true"/>
</params>
Property Attributes
| Name |
Description |
Type |
| time.begindate |
Starting date of the simulation. Initial borrowers ratings are referred to this
date. The format of this attribute is: DD/MM/YYYY.
|
date |
| time.steps |
Number of time steps. The simulation date is:
time.begindate + time.steps x time.steplength
|
int |
| time.steplength |
Specifies how long the time step in natural months is. We suggest to set
low values (eg. 1, 3 o 6). In doubt, set 1.
|
int |
| stopcriteria.maxiterations |
Maximum number of iterations performed by the Monte Carlo algorithm.
If 0, this stop criteria is not considered. ccruncher stops when a
stop criteria is achieved.
|
long |
| stopcriteria.maxseconds |
Maximum number of seconds that the current execution can last.
If 0, this stop criteria is not considered. ccruncher stops when
a stop criteria is achieved.
|
long |
| copula.type |
Type of copula used to generate correlated variables. Nowadays
only one implementation exists, the gaussian copula.
accepted values: 'gaussian'.
|
string |
| copula.seed |
Seed used to initialize a random number generator. Value 0
indicate that a random number based on current time will be used.
This property is optional. Default value is 0.
|
long |
| montecarlo.antithetic |
Specifies whether to use or not a variance reduction technique
named antithetic. If you have doubts about establishing this
setting then set it to 'false', otherwise set it to 'true'.
|
boolean |
| portfolio.onlyActiveBorrowers |
If you want to simulate all the borrowers, even borrowers without
risk along the time range, type 'false'. If you want to simulate
only active borrowers along the simulation period type 'true'. We
suggest writing always 'true'.
|
boolean |
Section Interests
This section shows how to define the interest rates curves used to
compute the Current Net Value. The curve named 'spot' is required.
Example
<interests>
<interest name="spot" date="18/11/2004">
<rate t="0" r="0.0"/>
<rate t="1" r="0.04"/>
<rate t="2" r="0.041"/>
<rate t="3" r="0.045"/>
<rate t="6" r="0.0455"/>
<rate t="12" r="0.048"/>
<rate t="24" r="0.049"/>
<rate t="60" r="0.05"/>
<rate t="120" r="0.052"/>
</interest>
</interests>
Interest attributes
| Name |
Description |
Type |
| name |
Name of the interest rate type
|
string |
| date |
Initial date of the interest curve. Usually this value matches
the initial simulation date. The format of this field is: DD/MM/YYYY.
|
date |
Rate attributes
| Name |
Description |
Type |
| t |
Increment (in months) from the initial date of the interest curve.
If a value between two given dates is needed, the value will be
interpolated (linear).
|
int |
| r |
Interest rate at time t. It is a value between -0.5 and 1.0. (for
example, a rate of 2.5% will be represented as 0.025).
|
double |
Section Ratings
This section shows how to define the ratings. A minimum of two ratings
are required (a non-default rating and the default rating).
Example
<ratings>
<rating name="A" desc="excelent"/>
<rating name="B" desc="good"/>
<rating name="C" desc="medium"/>
<rating name="D" desc="bad"/>
<rating name="E" desc="default"/>
</ratings>
Rating Attributes
| Name |
Description |
Type |
| name |
Rating identifier. All references to a rating (eg. borrower rating)
are made using this field. Includes default rating in this list.
|
string |
| desc |
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 used by ccruncher. ccruncher always
checks that the sum of elements of each row is 1.0. Also, ccruncher checks
that only one row with all probability concentred in a unique
element exists. The number of elements to be established is NxN, where N is the
number of ratings.
Example
<mtransitions period="12" epsilon="1e-12">
<transition from="A" to="A" value="0.80"/>
<transition from="A" to="B" value="0.10"/>
<transition from="A" to="C" value="0.07"/>
<transition from="A" to="D" value="0.02"/>
<transition from="A" to="E" value="0.01"/>
<transition from="B" to="A" value="0.05"/>
<transition from="B" to="B" value="0.75"/>
<transition from="B" to="C" value="0.10"/>
<transition from="B" to="D" value="0.07"/>
<transition from="B" to="E" value="0.03"/>
<transition from="C" to="A" value="0.03"/>
<transition from="C" to="B" value="0.07"/>
<transition from="C" to="C" value="0.70"/>
<transition from="C" to="D" value="0.14"/>
<transition from="C" to="E" value="0.06"/>
<transition from="D" to="A" value="0.05"/>
<transition from="D" to="B" value="0.05"/>
<transition from="D" to="C" value="0.15"/>
<transition from="D" to="D" value="0.60"/>
<transition from="D" to="E" value="0.15"/>
<transition from="E" to="A" value="0.00"/>
<transition from="E" to="B" value="0.00"/>
<transition from="E" to="C" value="0.00"/>
<transition from="E" to="D" value="0.00"/>
<transition from="E" to="E" value="1.00"/>
</mtransitions>
MTransitions Attributes
| Name |
Description |
Type |
| period |
Number of months covered by the transition matrix. Usually
transition matrix cover 1 year, in this case, set 12.
|
int |
| epsilon |
Value used as threshold to determine if a value is equal to 0.0 or not.
It must be a value near to 0 like 1E-12. This attribute is optional.
|
double |
Transition Attributes
| Name |
Description |
Type |
| from |
Initial rating. This value must be a rating identifier (see name
attribute in the rating tag)
|
string |
| to |
Final rating. This value must be a rating identifier (see name
attribute in the rating tag).
|
string |
| value |
Probability for rating migration (a value between 0 and 1)
|
double |
Section Survival Function
This section contains the survival function for each rating. If this
section is non informed, the survival function will be computed using
transition matrix. You don't need to fill all time values. Survival
function is monotone decreasing and has a value of 1 when time is 0
for all ratings distincts than default. The survival function of default
rating is always 0.
Example
<survival maxmonths="2500" epsilon="1e-12">
<svalue rating="A" t="0" value="1.0"/>
<svalue rating="B" t="0" value="1.0"/>
<svalue rating="C" t="0" value="1.0"/>
<svalue rating="D" t="0" value="1.0"/>
<svalue rating="E" t="0" value="0.0"/>
<svalue rating="A" t="6" value="0.999621298"/>
<svalue rating="B" t="6" value="0.925452791"/>
<svalue rating="C" t="6" value="0.879896024"/>
<svalue rating="D" t="6" value="0.789845972"/>
<svalue rating="E" t="6" value="0.0"/>
...
</survival>
Survival Attributes
| Name |
Description |
Type |
| maxmonths |
Number of months where is considered that survival function is 0
for all ratings. Set a high value (eg. 6000).
|
int |
| epsilon |
Value used as threshold to determine if a value is equal to 0.0 or not.
It must be a value near to 0 like 1E-12. This attribute is optional.
|
double |
Svalue Attributes
| Name |
Description |
Type |
| rating |
This value must be a rating identifier (see name attribute in the
rating tag)
|
string |
| t |
Time (in months) from begin date.
|
int |
| value |
Probability that a borrower with initial rating rating
survives (non-defaulted) at time t. It is a value between
0 and 1.
|
double |
Section Sectors
This section shows how to define the sectors. A minimum of one sector
is required.
Example
<sectors>
<sector name="S1" desc="oil and gas"/>
<sector name="S2" desc="other sectors"/>
</sectors>
Sector Attributes
| Name |
Description |
Type |
| name |
Sector identifier. All references to a sector (eg. borrower
sector) are made using this field.
|
string |
| desc |
Sector description. This value is only used in reports.
This description must be unique.
|
string |
Section Correlations
This section shows how to define the correlation matrix between sectors.
The correlation matrix must be a simmetric. You only need to set up the
upper triangle's elements. ccruncher checks that all the elements are in
[-1.0, +1.0]. The number of elements to set up is (numsectors+1) x numsectors / 2.
Example
<mcorrels epsilon="1e-12">
<sigma sector1="S1" sector2="S1" value="0.2"/>
<sigma sector1="S1" sector2="S2" value="0.1"/>
<sigma sector1="S2" sector2="S2" value="0.25"/>
</mcorrels>
MCorrels Attributes
| Name |
Description |
Type |
| epsilon |
Value used as threshold to determine if a value is equal to 0.0 or not.
It must be a value near to 0 like 1E-12. This attribute is optional.
|
double |
Sigma Attributes
| Name |
Description |
Type |
| sector1 |
Firt 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 between sector1 and sector2.
Correlation(defaults(S1), defaults(S2))
|
double |
Section Segmentations
This section shows how to define segmentations. Segmentations
allow you to analyze your portfolio's risk according to a hierarchical organization
or another type of segmentation. A segmentation is composed by segments.
There are 2 types of segmentations depending on the class of elements
which a segmentation contains; borrower segmentations (eg. sector, borrower size, initial
rating, etc.) and asset segmentations (eg. products, branch where the
contract is made, etc.). All segmentations must be complete (one
element only belongs to one segment and the union of all segments
results in the total portfolio). Every segmentation must have a segment named 'rest' defined (in a
implicit way). If a borrower (or an asset)
belongs nowhere, then it belongs to the 'rest' segment. Finally, there are 2
special segmentations, 'borrower' (one segment per borrower) and 'asset'
(one segment per asset), in these cases you don't need to specify all the segments,
these are defined in a implicit way.
Example
<segmentations>
<segmentation name="portfolio" components="asset"/>
<segmentation name="borrower" components="borrower">
<segment name="*"/>
</segmentation>
<segmentation name="asset" components="asset">
<segment name="*"/>
</segmentation>
<segmentation name="sector" components="borrower">
<segment name="S1"/>
<segment name="S2"/>
</segmentation>
<segmentation name="size" components="borrower">
<segment name="big"/>
<segment name="medium"/>
</segmentation>
<segmentation name="product" components="asset">
<segment name="bond"/>
</segmentation>
<segmentation name="office" 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 'borrower'
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 (always in conjunction with the segmentation).
If a segmentation doesn't have any segments, all the elements belong to
the 'rest' segment. The 'borrower' and 'asset' segmentations allow
the to define the '*' segment. The '*' segment contains a implicit
definition of a segment to every asset and borrower.
|
string |
Section Portfolio
This section shows how to define the portfolio. For each defined asset
indicate all the remaining events from initial date.
Example
<portfolio>
<borrower rating="A" sector="S1" name="Repsol" id="000001">
<belongs-to segmentation="sector" segment="S1"/>
<belongs-to segmentation="size" segment="medium"/>
<asset name="bond" id="op1" date="01/01/2001">
<belongs-to segmentation="product" segment="bond"/>
<belongs-to segmentation="office" segment="0001"/>
<data>
<values at="01/06/2002" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2003" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2003" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2004" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2004" cashflow="10.0" recovery="2000.0" />
</data>
</asset>
<asset name="bond" id="op2" date="01/06/1999">
<belongs-to segmentation="office" segment="0004"/>
<belongs-to segmentation="product" segment="bond"/>
<data>
<values at="01/01/2000" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2000" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2001" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2001" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2002" cashflow="10.0" recovery="2000.0" />
</data>
</asset>
</borrower>
<borrower rating="B" sector="S2" name="ATT" id="000002">
<belongs-to segmentation="sector" segment="S2"/>
<belongs-to segmentation="size" segment="big"/>
<asset name="bond" id="op3" date="01/06/1999">
<belongs-to segmentation="office" segment="0003"/>
<belongs-to segmentation="product" segment="bond"/>
<data>
<values at="01/01/2000" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2000" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2001" cashflow="10.0" recovery="2000.0" />
<values at="01/06/2001" cashflow="10.0" recovery="2000.0" />
<values at="01/01/2002" cashflow="10.0" recovery="2000.0" />
</data>
</asset>
</borrower>
</portfolio>
Look how the borrower haven't a 'belongs-to segmentation=borrower defined.
This is done implicitly (the same occurs with 'asset').
If you try to assign a borrower to a segmentation of asset components
(or viceversa), the input file will be rejected.
Borrower Attributes
| Name |
Description |
Type |
| rating |
Initial borrower rating at time t0 (see time.begindate at params section).
This value must be a rating identifier (see name attribute in rating tag).
|
string |
| sector |
Sector where this borrower is included.
This value must be a sector identifier (see name attribute in sector tag).
|
string |
| name |
A descriptive name of the borrower. Doesn't need to be unique. Currently
not used. Can be used in reports.
|
string |
| id |
Unique borrower identifier. Used by implicit borrower segmentation.
|
string |
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 |
| name |
A descriptive name of the asset. Doesn't need to be unique. Currently
not used. Can be used in reports.
|
string |
| 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 |
Values Attributes
| Name |
Description |
Type |
| at |
Date (in format DD/MM/YYYY) where the values take place
|
date |
| cashflow |
Cashflow at date "at". Positive values = borrower pays, negative
values = borrower receive money
|
double |
| recovery |
Recovery at date "at" in case of default. Positive values = borrower
pays, negative values = borrower earns
|
double |
