Value at Risk and Vardelta

Value at Risk and VaRdelta
Version 7.1
Financial Engineering Associates, Inc.
The Financial Engineering team at FEA Information in this document is subject

wrote this manual. to change without notice. Companies,
names, and data used in examples
© 2013 Financial Engineering herein are fictitious unless otherwise
Associates, Inc. All rights reserved. noted.
Financial Engineering Associates, Inc. is
registered and conducts business in FEA, an MSCI Barra company
Texas under the name "FEA, Inc." 2100 Milvia Street,
Berkeley, CA 94704-1113
This product includes software USA
developed by the Apache Software Tel : +1-510-548-6200
Foundation. A copy of the Apache Fax : +1-510-548-8798
source code and the applicable license Email: fea_info@fea.com
can be downloaded from http://www.fea.com
http://www.apache.org/. Printed in the United States of America.
Printed: September 10, 2013
| VaRworks User’s Guide
Types of Lines in Text Files ......................................... 84

Manual Organization ...................................................... 1 Creating Text Files ........................................................ 85
How to Proceed ............................................................... 1
Other FEA Products ........................................................ 1
About Headers .............................................................. 88
Contact FEA ..................................................................... 2
CPNTYPEDATE Header .............................................. 89
DATEROLL Header ..................................................... 90
VaRworks Features ......................................................... 3 DATEORDER Header .................................................. 90
What’s New? .................................................................... 6 DECIMALSEP Header ................................................. 91
Conventions ................................................................... 12 DELTAGAMMA Header ............................................. 91
DRIVER Header ............................................................ 91
Value at Risk .................................................................. 14 FIELDDELIM Header................................................... 92
Analytic VaR .................................................................. 17 INTERPOLATION Header .......................................... 92
Monte Carlo Simulation ............................................... 25 MEANREVERSION Headers ...................................... 93
Historical Simulation .................................................... 32 MESHPOINTS Header ................................................. 93
Using Primary and Secondary Sources of Risk ......... 34 MODEL Header ............................................................ 94
Historical Data Window and Data Filtering .............. 35 SCENARIO Header ...................................................... 95
Backtesting ..................................................................... 37 SMILEMODEL Header ................................................ 96
Extreme-Value Theory .................................................. 40 TREESTEPS Header ...................................................... 96
Stress Testing ................................................................. 42 TYPE Header ................................................................. 97
VaRdelta ......................................................................... 45 UNWINDPERIOD Header .......................................... 98
Component VaR and VaRbeta ..................................... 49 UNWINDTYPE Header ............................................... 99
Commodity Instruments .............................................. 51 VOLATILITY Headers ................................................. 99
Volatility as a Risk Factor ............................................. 54 VOLMODEL Header .................................................. 100
RiskMetrics ..................................................................... 59
The Euro ......................................................................... 59 About Record Layouts ............................................... 101
Data Representation/Data Files ................................... 61 Assets ............................................................................ 103
Rebasing the Market Data ............................................ 63 Asian Options .............................................................. 108
Average Caps and Floors ........................................... 111
About this Tutorial ........................................................ 64 Barrier Caps and Floors ............................................. 114
1. Install VaRworks ....................................................... 66 Barrier Caps and Floors (type II) .............................. 116
2. Open the VaRworks template .................................. 67 Barrier Options ............................................................ 120
3. Load the VaRworks add-in ...................................... 69 Best-Of Options ........................................................... 123
4. Activate the Inputs worksheet ................................. 70 Bonds ............................................................................ 127
5. Specify the Market and Portfolio files ..................... 71 Bond Forwards ............................................................ 130
6. Specify the general VaR parameters ....................... 74 Bond Futures ............................................................... 132
7. Specify the Monte Carlo inputs ............................... 75 Bond Futures Options ................................................ 134
8. Specify the Historical Simulation inputs ................ 76 Bond Options ............................................................... 136
9. Specify the Extreme-Value Theory inputs.............. 76 Brady Bonds ................................................................ 138
10. Specify the Stress Test inputs ................................. 77 Calendar Spread options............................................ 141
11. Specify the Advanced Inputs ................................. 77 Caps and Floors........................................................... 143
12. Calculate the VaRworks template ......................... 77 Caps and Floors (type II)............................................ 145
13. Examine the results ................................................. 78 Cash Flows ................................................................... 148
14. Examine the error log .............................................. 80 Commodity Futures ................................................... 150
15. Archive the results................................................... 80 Commodity Index Swaps .......................................... 152
Commodity Index Swap Options ............................. 154
Commodity Physicals................................................. 157
How Data Are Input ..................................................... 82 Commodity Swaps ..................................................... 159
Entering Dates................................................................ 83 Convertible Bonds ...................................................... 161
Entering Numbers ......................................................... 84 Correlations ................................................................. 164
Entering Text .................................................................. 84
VaRworks User’s Guide |
Crack Options .............................................................. 165 CFDATA ...................................................................... 293

Credit Default Swaps .................................................. 168 COMPONENTVAR .................................................... 295
Currency Swap Options ............................................. 171 COMPONENTVAR2 .................................................. 296
Differential Swaps ....................................................... 173 EXTREMEVALUE ...................................................... 298
Digital Options............................................................. 175 HDATA ........................................................................ 301
Discrete Barrier Options ............................................. 179 HISTORICALPANDL ................................................ 306
Distribution Data ......................................................... 182 HISTORICALVAR ...................................................... 311
Dual-asset Options ...................................................... 182 INCREMENTALVAR................................................. 319
Equities ......................................................................... 186 LOADMARKETDATA............................................... 319
Equity Average-price Options ................................... 191 MARGINALVAR ........................................................ 321
Equity Options ............................................................. 193 PORTVARANL ........................................................... 322
Equities (type II) .......................................................... 197 ROLLINGWINDOWVAR.......................................... 325
Equity Futures (type II)............................................... 199 SDATA ......................................................................... 328
Equity Options (type II) .............................................. 200 SIMBACKTEST ........................................................... 330
Equity Proxy................................................................. 203 STRESSTEST ................................................................ 334
Eurocurrency Futures ................................................. 204 VARANL ...................................................................... 336
Eurocurrency Futures Options .................................. 206 VARANLU................................................................... 338
Exchange Rates ............................................................ 207 VARCARLO ................................................................ 339
Forwards ....................................................................... 208 VARCOMPARE .......................................................... 347
Forward-start Options ................................................ 209 VARDELTA ................................................................. 350
FRAs .............................................................................. 211 VCDATA ...................................................................... 351
FRNs .............................................................................. 212 VWVERSION .............................................................. 354
Historical Data ............................................................. 215
Money Markets ............................................................ 218
The Error Log .............................................................. 355
Options ......................................................................... 220
Error Log Error Messages .......................................... 356
Overnight Index Swaps .............................................. 225
Microsoft Excel Error Messages ................................ 358
Portfolios....................................................................... 227
Answers to Common Questions ............................... 360
Range Accruals ............................................................ 228
Repos ............................................................................. 232
Sensitivity Instruments ............................................... 235 About Utilities ............................................................. 362
Smile Data..................................................................... 240 VaRworks Macros ....................................................... 362
Spread Options ............................................................ 242 GENRATES .................................................................. 363
Strip of Options ............................................................ 245
Strip of Spread Options .............................................. 249 Credit rating Codes .................................................... 365
Stress Data .................................................................... 251 Vertex names ............................................................... 365
Swaps ............................................................................ 255 Riskmetrics Asset Classes and Maturity Codes ...... 366
Swap Options ............................................................... 261
Swap Options (type II) ................................................ 263
Introduction ................................................................. 367
Variable Quantity Cash Flows ................................... 267
Tutorial ......................................................................... 367
Swing Contracts ........................................................... 268
Volatilities ..................................................................... 272
Yield and Price Curves ............................................... 274 Introduction ................................................................. 378
Tutorial ......................................................................... 378
Frequently Asked Questions ..................................... 386
About Excel Worksheet Functions ............................ 277
Keyboard Shortcuts ..................................................... 278
Range Names ............................................................... 280 About VaRLib .............................................................. 388
Array Formulas............................................................ 282
Controlling Calculation .............................................. 284
Value at Risk ................................................................ 389
VaRdelta and Component VaR ................................. 390
VaRworks Function List ............................................. 287 Regulation .................................................................... 390
BACKTEST ................................................................... 288 Finance ......................................................................... 390
CASHFLOWMAP ....................................................... 291 Backtesting ................................................................... 393
Programming and Microsoft Excel ........................... 393

This manual provides complete documentation for VaRworks, a Microsoft Excel add-in for calculating cash
flow maps, analytic and Monte Carlo value at risk (VaR), VaRdelta, and Component VaR. (If you’re a VaRlib
library user, you will also need the VaRlib Function Reference.) The manual is organized in sections as
follows.
Section Contents
About This Manual Describes this document, how to proceed with using VaRworks, and
how to contact FEA.
Introduction VaRworks features, what’s new, and documentation conventions.
Technical Reference A technical discussion of cash flow mapping, analytic and Monte Carlo
VaR, VaRdelta, Component VaR, and other topics.
Tutorial Everything you need to know to begin using VaRworks.
Entering Data How to input trades and volatility-correlation datasets.
Headers How to specify parameters that apply only to certain trades or types of
trades.
Record Layouts The data items you need to specify when you enter a trade.
Using Microsoft Excel Tips for using Microsoft Excel.
Worksheet Functions VaRworks worksheet function reference.
Troubleshooting What to do when a VaRworks function returns an error.
Utilities Describes the utilities included with VaRworks.
References Bibliography of works cited in the text and suggestions for further
reading.
Codes A reference for many of the common codes used in VaRworks.
Read Introduction. To learn more about cash flow mapping, VaR and VaRdelta, read Technical Reference
(the mathematical details can be skipped). The Tutorial introduces you to VaRworks.
After the tutorial, you will want to:

 Calculate VaR for your own portfolio—read Entering Data, Headers, and Record Layouts.
 Design your own templates—read Worksheet Functions.
 Learn more about VaR—read References.
 If you want to create your own volatility and correlation datasets instead of using RiskMetrics
datasets, contact FEA about MakeVC.
Contact FEA and ask for Client Services when you are ready to create a custom VaRworks template for your
own portfolio. We can help you specify new function calls and change the layout to fit your needs.
FEA products are listed below.

 @ENERGY for valuing energy and power derivatives.
 @STRUCTURE for valuing <
 @EQUITY for valuing equity derivatives.

 @GLOBAL for valuing single-commodity and cross-commodity exotic options.
 @INTEREST for valuing interest-rate derivatives.
 StructureTool for valuing complex instruments using Monte Carlo simulation.
 MakeVC for creating volatility-correlation (VaR) datasets from historical data.
 MakeCMF for creating constant-maturity historical data time series.
 VaRworks for calculating analytic and Monte Carlo value at risk (VaR).
All of these products are available as both Microsoft Excel add-ins and C/C++ programming libraries for
Unix and Windows. You can incorporate the libraries into custom applications written in C, C++, Visual
Basic, and SQL databases. Contact FEA for more information.
FEA, an MSCI Barra company

2100 Milvia Street,
Berkeley, CA 94704-1113
USA
Tel: +1-510-548-6200
Fax: +1-510-548-8798
Email: fea_info@fea.com
http://www.fea.com
VaRworks is a Microsoft Excel-based risk management application for stress testing, cash flow mapping,
Value at Risk (VaR), VaRdelta, and Component VaR calculations. This product calculates analytic, Monte
Carlo and Historical VaR, complies with the RiskMetrics specification, and can read RiskMetrics, MakeVC,
and custom volatility-correlation datasets. Additionally, VaRworks provides an Extreme-Value Theory
calculator for VaR and Shortfall Risk.
VaRworks offers corporations, investment funds, financial institutions, insurance companies, commodities
firms, utilities, and other users the primary benefit of convenient and standardized assessment of VaR. The
capability of measuring VaR is of critical importance under capital adequacy requirements, government
regulations, and prudent risk management practice.
VaRworks is written completely in C and C++, provides extremely rapid calculations, and includes Excel
add-in functions (XLL file), customizable Excel templates, a sample portfolio, a daily volatility-correlation
dataset, and documentation. When installed, the VaRworks XLL adds functions to Excel that are used like
the built-in worksheet functions, so you can customize the VaRworks templates or create new ones.
VaRworks incorporates pricing routines from other FEA products.
VaRworks contains the functions that perform the following calculations (function names in parentheses).
 Map a portfolio into cash flows (CASHFLOWMAP)
 Returns cash flow data (CFDATA)
 Calculate a portfolio’s component VaR (COMPONENTVAR)
 Calculate VaR and Shortfall Risk using Extreme-Value Theory (EXTREMEVALUE)
 Retrieves the cached historical returns of a specified vertex (HDATA)
 Calculate a portfolio’s diversified historical VaR and Shortfall (HISTORICALVAR)
 Calculate a candidate trade’s incremental VaR (INCREMENTALVAR)
 Calculate a candidate trade’s incremental VaR (MARGINALVAR)
 Calculate a portfolio’s diversified and undiversified analytic VaR (PORTVARANL)
 Returns stress-induced values of risk factors (SDATA)
 Calculates a portfolio’s response to stress scenarios (STRESSTEST)
 Calculate a portfolio’s diversified analytic VaR (VARANL)
 Calculate a portfolio’s undiversified analytic VaR array (VARANLU)
 Calculate a portfolio’s diversified Monte Carlo VaR (VARCARLO)
 Compare histograms and tails for different methodologies (VARCOMPARE)
 Calculate VaR without portfolio or dataset decomposition (HISTORICALPANDL,
ROLLINGWINDOWVAR)
 Perform backtesting analysis (BACKTEST, SIMBACKTEST)
 Calculate the VaRdelta array of a portfolio’s cash flow map (VARDELTA)
 Return volatility and correlation file data (VCDATA)
 Return version information (VWVERSION)
There’s no need to generate your own cash flow maps. VaRworks reads the output of your portfolio
management system and shreds each instrument into component cash flows, then allocates those cash flows
into currency, commodity, asset class, and maturity buckets.
VaR is the minimum expected loss on a position given a time horizon, confidence level (probability), and
home currency. For example, suppose you have a daily VaR of US$10MM with 95% probability, then over
the next 24-hour period there is a 5% chance your loss will exceed US$10MM.
With VaR you can adhere to existing and impending regulatory guidelines, comply with internal and
external directives from risk management committees and outside auditors, evaluate traders’ and investors’
return/risk performance, and set trader risk limits in terms of VaR in addition to maximum outright
exposure.
Shortfall Risk is the mean loss beyond VaR, i.e. the expected value of the loss given that a loss event
beyond VaR has occurred. It represents an extra measure of value-at-risk to complement the reported
portfolio VaR number. In particular, the RiskMetrics-compliant VaR estimate tends to be more heavily
weighted by sample points that tend to cluster about the mean of a P&L distribution. This tends to be
acceptable if your profits and losses are more or less normally distributed, but can be problematic when
your P&L distribution is characteristically fat-tailed.
With Shortfall Risk you can quantify fat-tailed distributions, particularly those constructed from historical
data, which are not limited by underlying statistical assumptions. Normally distributed profits and losses
correspond to a Shortfall Risk close to VaR, so a Shortfall Risk departing from VaR is a particularly useful
indicator of the extent of tail contributions to your overall value-at-risk.
FEA created VaRdelta to extend VaR measurement into VaR improvement. VaRdelta rapidly evaluates
candidate trades for their VaR-improving qualities, without requiring firm-wide VaR recalculations. You
can easily determine portfolio ‚hot spots,‛ assign real-time, VaR-based trading limits, and compare the cost
of putting on a hedge with its reduction in VaR. Component VaR is an extension of VaRdelta that measures
the exact contribution to VaR of each trade or cash flow.
The VaRworks VARCARLO function supports Monte Carlo simulation for portfolios containing non-linear
instruments such as options and callable bonds. It calculates Monte Carlo VaR, VaR standard error, mark-to-
market, the profit-and-loss (P&L) distribution, the expected (mean) P&L, and the P&L standard deviation.
The distribution is easily displayed as a histogram.
The VaRworks HISTORICALVAR function supports historical simulation for portfolios containing non-
linear instruments such as options and callable bonds. It calculates Historical VaR, VaR standard error,
Shortfall Risk, mark-to-market, the profit-and-loss (P&L) distribution, the expected (mean) P&L, and the
P&L standard deviation. The distribution is easily displayed as a histogram. Also, users can output raw
simulation returns, sorted according to observation date or P&L amount. Sorted output can be applied to
the EXTREMEVALUE function, discussed below. The functions HISTORICALPANDL and
ROLLINGWINDOWVAR support calculation of VaR without requiring portfolio or dataset decompositions.
The VaRworks EXTREMEVALUE function provides an additional and alternative procedure for calculating
VaR and Shortfall Risk, using the principals of Extreme-Value Theory. This approach is inspired by the
concern that profit-and-loss distributions constructed from sample data are often inadequate
representations of distribution tails because of the scarcity of tail points in these samples, relative to points
clustered about the mean. A set of historical data, which you might suspect to be representative of a fat-
tailed distribution, is a particular case in point. What information can you extract about the tail, and thus
your value-at-risk, when there are a limited number of points available? In such cases, Extreme-Value
Theory can be used to characterize the distribution tail in terms of a particular functional form. Specifically,
the VaRworks Extreme-Value Theory calculator fits a portfolio loss (or profit) tail to a Generalized Pareto
distribution, from which estimates of VaR and Shortfall Risk are then made.
The VaRworks STRESSTEST function enables stress testing of portfolios. Scenarios can be created and
saved that define how asset prices, exchange rates, and interest rates are to be shocked, both
individually and collectively. Each stress scenario is applied to the underlying assets of a given
portfolio, and the portfolio is fully revalued for each scenario specified, providing a set of profits and
losses as a function of scenario. (You can view the effect of a set of stress scenarios on a given asset via
the SDATA function, which calculates the return on the asset for each scenario.) VaRworks scenario
modeling consists of an easy-to-follow syntax. Shocks can be constructed in terms of absolute value,
percentage of market value, or number of standard deviations (as specified within the volatility data
file). Assets can be shocked individually or one can apply parallel, curvature, or twist shocks to entire
asset classes. Driver assets can be defined that dictate shocks applied to peripheral assets, which are
portfolio assets not shocked directly. Shocks can be superimposed in order to create more complex
scenarios. Shocks are specified in text files that can be generated easily using a simple application
included with your distribution.
Backtesting tools allow the user to assess the accuracy and performance of different VaR models.
In VaRworks’ two new functions, BACKTEST and SIMBACKTEST, FEA implemented several popular
backtests that enable the user to evaluate and compare different methodologies used to generate VaR
results, including, but not limited to, the methodologies supported by VaRworks. In addition,
HISTORICALPANDL and ROLLINGWINDOWVAR functions allow the user to visually analyze arbitrary
time series of profit and losses, and to generate VaR results without the need for portfolios and datasets
decomposition. A new template, backtests.xls, provides examples on how to use these functions.
VaRworks supports the following financial instruments.

 Bonds Forwards, futures, options, futures options, floating-rate, coupon, zero-coupon, odd-
coupon, callable, amortizing, when-issued, and Brady bonds.
 Interest Rates Eurocurrency futures and futures options, FRAs, swaps, swaptions, caps, floors,
repos, money markets, deposits, barrier caps and floors, and currency swaps and swaptions.
 Currencies and Commodities Spot, forward, futures, options, swaps, and exotic options such as
average-price, average-strike, spread, crack, best-of options, and swing contracts.
 Equities Shares, indices, index futures, index options, stock options, and average-price
options.
Instrument coverage is expanded continually by incorporating FEA’s large library of financial functions. For
instruments not directly supported, you can provide your own cash flow maps.
With FEA’s separately-available MakeVC. you can create volatility-correlation datasets with your own
historical price data. This is especially useful for traders of energy, power, equities, exotic currencies, and
other assets not found in RiskMetrics datasets.
VaRworks is based on VaRlib, the FEA C/C++ programming library for Unix and Windows. You can
incorporate VaRlib into C, C++, Visual Basic, and SQL database applications. Contact FEA for more
information.
Maintenance is available for an annual fee, entitling the user to product upgrades, documentation
enhancements, and telephone, fax, and email support.
Here is an overview of the new and changed features since Version 7.0. See varnote.txt for additional details
and a list of bug fixes.
An extended, multi-horizon extension of PFE (Potential Future Exposure) has been implemented. For a
portfolio containing instruments with multiple settlements or changing exposures (ostensibly due to
counterparty defaults), the new output generates the maximum exposure, at a given percentile, for a given
sub-portfolio. This generalizes the prior implementation of PFE, which just gave the exposure at a single,
fixed horizon. A new output format giving the time-dependent schedule of Exposures is available via the
VARCARLO2 function. Drilldown and ‚Component‛ PFE (e.g. for a counterparty subportfolio) are enabled
and can be generated with the VaRAnalysis template (RiskAnalyst interface).
A Primary-Secondary risk model has been implemented in which the user can distinguish between primary
sources of risk that are modeled by a full covariance matrix, and secondary sources of risk, each of which is
linked by a beta coefficient to a single primary source of risk. See page 34 for details on the methodology. To
generate the dataset appropriate for this risk model MakeVC version 2.9 (or a more recent version) should
be used.
To enable this model the volatility file should include information specifying the relation between primary
and secondary sources of risk, and the corresponding beta coefficients, see page 272. The correlation file for
this model only needs specification of correlations among primary sources of risk.
Full documentation on this model will be provided in the official release.
New features. The VaRAnalysis.xls workflow has been considerably improved to allow for much faster
calculations of large portfolios with a large number of risk factors. The performance improvement for a
portfolio with 5,000 trades and a dataset of more than 2,000 factors is dramatic, about 25 times faster
compared to previous versions when both parametric and Monte Carlo analysis are performed. In addition,
the workflow for drill-down analysis has also been substantially improved, and allows users to perform
drill-down analysis of large portfolios in real time. The VaRAnalysis interface has also been enhanced to
provide Potential Future Exposure data, and corresponding drill-down analysis, in a user friendly way.
The functionality of the COMPONENTVAR2 function has been extended to allow for the performance
improvements mentioned above.
New features. Calculation of a liquidity-adjusted extension of VaR called Profit at Risk (PaR), see page 15,
is now supported. Risk decomposition of PaR can also be obtained, in a way similar to the traditional
Component VaR decomposition. PaR is supported via Parametric, see page 25, and Monte Carlo, see page
29, methodologies. This new feature supports a trade by trade specification of the holding period (horizon),
and thus allows the estimate of risk of portfolios comprised of trades with different liquidity characteristics.
Two new headers have been introduced to support the feature: UNWINDPERIOD and UNWINDTYPE, see
page 98.
New features. Implied volatilities used to price certain fixed income intruments can now be treated as risk
factors. Instruments currently supporting this feature are: CAPFLOOR2, BARRIERCAP2,
RANGEACCRUAL, AVERAGECAP, and SWAPTION2. See Dataset Requirements for Implied Volatility
Risk on page 58 for a discussion on how to incorporate the risk associated to the implied volatilities in the
VaR calculation.
Irregular first and last coupons are now supported in CAPFLOOR2 instruments. See the CPNTYPEDATE
header for more details.
Cashflow instruments defining future flow of a currency now supports cubic sline interpolation of interest
rates. See the Interpolation Header for more details.
New features. New functionality has been added allowing users to update Monte Carlo and Historical
simulation results in an efficient way. The functionality allows for the creation of a database (stored in flat
files) that facilitates slicing the portfolio and re-aggregating results in a very efficient way, even for
otherwise lengthy Monte Carlo and Historical simulations. See the description of the new input
(aggregate_flag) in the function HISTORICALVAR and VARCARLO2, and the new function
COMPONENTVAR2.
A specific implementation of this new functionality is now available through the RiskAnalyst interface. In
previous versions, RiskAnalyst could perform the attribution of the overall portfolio VaR to arbitrary
subportfolios or trades, via the Component VaR methodology (see page 49). The attribution could only be
obtained within the Analytic VaR approximation. RiskAnalyst can now perform the same decomposition
using the more general Monte Carlo methodology. Use the RiskAnalyst toolbar in Excel and select
VarAnalysisSubPortfolio Analysis to see an implementation of this new functionality.
When Monte Carlo is used to estimate Potential Future Exposures, see the pv_flag input of the
VARCARLO2 function, the expected value of the Potential Future Exposure is now generated.
New features. Functionality of the Monte Carlo simulation has been extended to allow for Potential Future
Exposure quantile calculations, i.e. for calculation of the histogram of possible future portfolio values, and
related statistical measures. See the pv_flag input of the VARCARLO2 function for details.
The risk of Commodity Futures contracts and Options on Commodity Futures can now be analyzed in
terms of spot and carry rate risk, in addition to futures price risk. See the carry_credit_rating input in the
Commodity Futures instrument for details.
The maximum number of assets and maturities in the CASHFLOWMAP (and related functions) has been
increased to 4096 each, with the constraint that the product of the two numbers must be less than
256512=131072.
Here is an overview of the new and changed features since Version 5.3. See varnote.txt for additional details.
New features. Two new instruments have been added: SENSITIVITY and SENSITIVITYPAIR. They can be
used to represent a generic instrument through its sensitivities to risk factors, and thus provide useful
proxies when coverage of particular instruments is missing. First order sensitivities and diagonal gamma
sensitivities are specified in SENSITIVITY trades, cross gamma sensitivities in SENSITIVITYPAIR trades.
For a description of the methodology supporting Sensitivity trades, see page 236.
Instruments valued via ErgLib now support a new header DELTAGAMMA. This allows users performing a
Monte Carlo/Historical simulation to replace the full revaluation of an instrument for each simulated market
scenario by a Delta-Gamma based estimate of its value. The instruments affected are: ASIAN, BESTOF,
CRACK, CALSPREAD, DIFFSWAP, DIGITALOPT, DBARRIEOPT, FWDOPT, INDEXSWAP,
OPTINDEXSWAP, OPTION2, SPREAD, STRIPSPREADOPT, STRIPOPT.
Here is an overview of the new and changed features since Version 5.2. See varnote.txt for additional details.
New features. Implied volatilities used to price option intruments can now be treated as risk factors.
Instruments currently supporting this feature are: EQUITYOPTION, EQUITYOPTION2, OPTION, and
STRIPOPT. See Volatility as a Risk Factor on page 54 for a discussion of the methodology used. See Dataset
Requirements for Implied Volatility Risk on page 58 for a discussion on how to incorporate the risk
associated to the implied volatilities in the VaR calculation.
Volatility smile adjustments can now be applied when valuing the following instruments: EQUITYOPTION,
EQUITYOPTION2, OPTION, and STRIPOPT. See the SMILEMODEL header section on page 96 for the
description of the implemented moneyness choices for the sticky moneyness model. See Smile Data section
on page 240 for the record layout of the volatility data in the smile file.
The correlation file is no longer a required input for historical VaR and stress testing. HISTORICALVAR
and HDATA can now be used with or without the correlation file input, whereas STRESSTEST and SDATA
do require a correlation file only when performing a correlated stress test.
An extension to the OPTION type called OPTION2 is implemented. It uses functions from ErgLib for the
valuation rather than functions from GlobLib as OPTION does. See the OPTION section on page 220 for
more details.
The Slovenian Tolar has been added to the list of Euro currencies.
Here’s an overview of the new and changed features since Version 5.1. See varnote.txt for additional details.
This release changes the conversion of dates to times in years (‚tenors‛). Previously, VaRworks converted a
date to a time in years by dividing the number of days between the effective date and the date by 365.25. In
this release, the denominator is 365. See Day Count Basis on page 24.
Here’s an overview of the new and changed features since Version 5.0. See varnote.txt for other changes and
bug fixes.
New features. Commodity risk factors can now be associated to Fixed Expiration date Futures prices, in
addition to Constant Maturity Futures prices. See page 54 for details. To support this new feature, the
LOADMARKETDATA function now accepts an effective date argument, see page 319.
Custom credit ratings, beyond the ordinary credit ratings categories, are now supported. See Credit Ratings
on page 365, and Assets on page 103 for more details. Support for inputing spread data with respect to the
risk free Government curve, has also been added. Instruments currently supporting both spread and full
yield input are: BOND, BONDFORWARD, BONDFUTURE, BONDFUTOPT, BONDOPTION.
Cashflow mapping now provides additional user choices for allocating cashflows to adjacent risk factors,
see Allocating Cash Flows to a Single Vertex on page 22.
Instruments valued via ErgLib now support an interpolation header allowing the user to select different
price interpolation schemes. The instruments affected are: ASIAN, BESTOF, CRACK, CALSPREAD,
DIFFSWAP, DIGITALOPT, DBARRIEOPT, FWDOPT, INDEXSWAP, INDEXSWAPOPT, SPREAD,
STRIPSPREADOPT, STRIPOPT.
Credit default swap instruments (CDS) are now supported, see page 168.
bug fixes.
New features. BARRIEROPT now support more flexible monitoring of the barrier, including the case when
monitoring begins at a future date or ends before option expiration. Even more complex window setups can
be obtained by using Discrete Barrier Options (DBARRIEROPT). Digital options (DIGITALOPT) are now
supported. A new trade (VQCASHFLOW) has been added that describes the flow of an uncertain principal
of currency/commodity on a specified date.
At the money currency forward agreements (FORWARD) can now be specified by omitting the
exchange_rate trade input. The delivery_price of commodity futures contracts (COMMODITYFUT) can also
be omitted to specify futures with zero Mark to Market. Bond options and bond future options (BONDOPT
and BONDFUTOPT) now allow specification of the volatility input directly within the trade record.
A number of interest-rate instruments have been updated to use analytics from the latest version of FEA’s
@INTEREST product. These include BARRIERCAP, CAPFLOOR, SWAPTION, and FRN.
There are two new interest-rate instruments: AVERAGECAP and RANGEACCRUAL.
Users can now input implied volatility smiles using the Smile Data File, and use volatility smile data when
valuing a number of fixed income instruments, i.e. CAPFLOOR2, BARRIERCAP2, RANGEACCRUAL,
AVERAGECAP, and SWAPTION2.
The Monte Carlo simulation has been multi-threaded, and, if run on a multi-processor machine, is
correspondingly faster. Depending on portfolio size and composition and if N is the number of processors,
one can expect the Monte Carlo simulation to be up to N time faster than previous versions.
Documentation has been added describing how to use rebased market data that does not require a USD
exchange rate. See Rebasing the Market Data for more information.
bug fixes.
New features. BARRIEROPT, FWDOPT, SPREAD, and BESTOF instruments now support equity
underlyings, in addition to commodities and exchange rates. The RiskAnalyst interface now provides
support for six additional markets: Brazil, Indonesia, Malaysia, Mexico, New Zealand, and South Africa.
bug fixes.
New features. A new instrument, covering overnight index swaps, has been added. The corresponding
trade type is OIS. Cap and floor instruments, and their barrier counterparts, have now increased
functionality. To maintain backward compatibility new trade types have been added: CAPFLOOR2 and
BARRIERCAP2.
bug fixes.
New features. Input to some equity trades has been streamlined. To maintain backward compatibility new
equity trade types have been added: EQUITY2, EQUITYOPTION2, and EQUITYFUTURES2. A new equity
proxy instrument has been added, that allows modeling of an equity in terms of a maximum of three user
selected proxies. EQUITYOPTION and EQUITYOPTION2 now support options on equity futures.
Simulation VaR calculations (Monte Carlo, Historical, and Stress Test) can now be performed even when
interest rate and exchange rate data is missing from the volatilty and correlation dataset, if the relevant data
is provided via the appropriate file input (see yield curves on page 274, and exchange rates on page 207). In
order to make the data available to the relevant functions, that might not accept such files as a direct input,
a new addin function, LOADMARKETDATA, as been added.
Shortfall VaR is now generated also for Monte Carlo and analytic methodologies, see VARCARLO2 and
PORTVARANL. VARCARLO2 supports calculation of mark to market at horizon, which can be used to
generate ‚clean‛ P&L’s, useful for backtesting.
Essential information generated by historical simulation, as well as by the analytic VaR and Extreme Value
Theory analysis, can now be output also to flat files. See HISTORICALVAR , PORTVARANL,
EXTREMEVALUE. A new function, VARCOMPARE , uses these files to perform a comparative analysis of
the results of different methodologies, and to obtain a composite picture combining the results in a user
specified way.
The function HDATA can now be used to extract summary statistics and to construct flexible visualization
tools to analyze the historical data being used.
The function CFDATA and VCDATA have been enhanced to allow the display of information, pertaining to
equities, contained in the modified asset file.
Backtesting functionality has been greatly improved by the addition of two new functions, BACKTEST and
SIMBACKTEST. These functions allow you to evaluate and compare different methodologies used to
generate VaR results, including, but not limited to, the methodologies supported by VaRworks. A new
template, backtests.xls, provide examples on how to use these functions.
Two new functions, HISTORICALPANDL and ROLLINGWINDOWVAR, allow the user to visually analyze
arbitrary time series of profit and losses, and to generate VaR results without the need for portfolios and
datasets decomposition. A new template, backtests.xls, provide examples on how to use these functions.
Finally a new interface, RiskAnalyst, has been made available and can be accessed through the RiskAnalyst
toolbar in Excel.
bug fixes.
New templates. Three new templates provide you with Excel based tools that greatly enhance reporting and
drill-down capabilities of VaRworks. The first template generates portfolio files, while allowing you to
specify additional, customizable, trade-specific tags that can be used for drill-down analysis. The second
and third template perform customizable drill-down analysis on your portfolio with emphasis on VaR and
stress measures, respectively. See the tutorial on page 367 for additional information. The portfolio
generating template (portfolio_builder.xls) replaces the utility template (portman.xls) distributed in
previous releases.
New instrument. Strips of options and strips of spread options are now supported.
New features. Forward starting instruments can now be valued when the valuation date is past the
forward starting date. Analytic VaR calculation can now be performed even if interest rate data is missing
from the volatilty and correlation dataset, provided the relevant data is input via the yield curve file input.
bug fixes.
New instrument. Convertible bonds are now supported.
Additional Asset Classes. The default set of Asset Classes now includes support for additional credit
ratings for interest rate instruments. See CODES.
Changes to Asset Class and Maturity interpretation. It is now possible to specify arbitrary maturities for
vertices of any asset class. This allows more control over the yield curves used for each asset class if you are
using datasets you generate yourself using FEA’s separately-available MakeVC. See CODES.
Here’s an overview of the new and changed features since Version 3.0.
User-defined equities. You can now define your own equity assets in a manner similar to the way in which
VaRworks allows the specification of user-defined commodity assets. Thus, VaRworks now supports value-
at-risk for multiple stocks and indices of a given market.
Stress testing. To complement its extensive VaR analyis features, VaRworks now supports stress testing of
portfolios via the STRESSTEST and SDATA functions. With the introduction of stress testing, VaRworks
provides a truly comprehensive set of utilities for market risk analysis.
Historical VaR changes to accommodate weekend data. The HISTORICALVAR and HDATA functions
have changed, via the introduction of the argument skip_weekends, to accommodate the option of including
weekend historical data points. Previously, weekend data was ignored. The change is backward compatible.
To maintain the same functionality as in the previous release of VaRworks, set skip_weekends to TRUE, the
default value.
Real time incremental VaR is now easier to perform because of the introduction of the MARGINALVAR
function. See the ‘Incremental VaR’ sheet of the template provided with the distribution.
Automatic generation of asset and maturity lists. Asset and maturity lists specific to your own portfolio
and volatility/correlation data files can now be generated automatically, and the VaRworks template
provided with the distribution thus adjusts to your specific needs. See the new CFDATA function.
In this documentation, the following regional settings are used.
Regional setting Value

Decimal separator .
Negative sign symbol -
Currency symbol $
Time separator :
AM symbol (12-hour clock) AM
PM symbol (12-hour clock) PM
Date order Month-day-year (MDY)
Date separator /
For example, 22-June-1998, 1800 hours is given as 6/22/1998 6:00:00 PM. When you enter dates and numbers
in a spreadsheet, use the settings specified by your computer’s regional settings.
To check your regional settings

1. Click Start, and then point to Settings.
2. Click Control Panel.
3. Double-click Regional Settings.
VaRworks function arguments are not case sensitive. Text arguments are neither padded nor trimmed; do
not specify more or fewer characters than required.
Value at Risk—VaR—is a technique for measuring exposure to market-based financial risk, asking the
question ‚How much money could this portfolio lose because of normal market fluctuations?‛ Because the
question is not quite complete, however, we must qualify our answer by providing three additional pieces
of information:
1. Over what period of time (horizon)?
2. With what probability (confidence)?
3. Using what accounting (or home) currency?
In addition, the phrase ‚normal market fluctuations‛ must be reduced to substantive data about these
fluctuations, by providing the variance-covariance data for same.
Thus, VaR is the minimum expected loss, in home currency units, on a position given some time horizon
and confidence level (probability). For example, suppose you have a daily VaR of US$10MM with 95%
probability, then over the next 24-hour period there is a 5% chance your loss will exceed US$10MM. Think
of VaR not as a ‚worst case,‛ but rather as a regularly occurring event with which you should be
comfortable.
Use VaR because it:

 is an industry standard,
 is a regulatory requirement,
 is a common language for talking about risk,
 is a consistent measure of risk,
 offers comfort to senior management concerning potential losses,
 can be part of the capital allocation process, and
 can be used for bonus allocations.
As a measure of market risk, VaR has several uses. You can measure and compare market risks, check
valuation and risk models, evaluate the performance of risk takers on a return/risk basis, and estimate
capital levels required to support risk taking. Here are a few specific examples:
 Adhere to impending and existing regulatory pressures, including the European Union’s
Capital Adequacy directive (EEC 93/6), which requires banks and investment firms to set
capital aside to cover market risks, Basle Committee on Banking Supervision of the Bank for
International Settlements (BIS) market risk capital requirements, the Security and Exchange
Commission’s amendments requiring registered corporations to compute market risk
measures.
 Comply with internal and external directives from risk management committees and outside
auditors.
 Evaluate traders’ and investors’ return/risk performance. For example, measure the
cumulative trading revenues over time of traders in similar markets and compare them on the
basis of the Sharpe ratio (P&L/volatility(P&L)), Risk ratio (P&L/VaR), or Efficiency ratio
(VaR/volatility(P&L)).
 Set trader risk limits in terms of VaR in addition to maximum outright exposure.
 Track an index. For example, compute the VaR of the components of the index you are trying
to track and compare it to the VaR of your portfolio.
 Validate underlying mapping and risk models. For example, compare one-day VaR estimates
with realized daily profit-and-loss over time and plot the results on a control chart. See the
Control chart worksheet in the varworks.xls template for an example.
VaR of a portfolio is often characterized as the worst possible loss that can be achieved due to market
movements, under normal market conditions, over a given horizon; equivalently it can be defined as the
minimum loss that can be achieved under stressed market conditions, over the same horizon. What defines
normal and stressed market conditions is the confidence level used to define VaR, e.g. 95% VaR implies that
‚normal‛ markets conditions happens 95% of the time (and correspondingly the 5% of days with worst
returns defines ‚stressed‛ conditions).
The horizon for the calculation is often thought of as the holding period of the portfolio positions, i.e. the
time it would be required to liquidate the portfolio, without incurring substantial liquidity costs. By
liquidity costs we are thinking here of the potential market impact of closing a position, i.e. the fact that the
market price of a security is likely to be different after the position is closed, not only because of market
volatility, but because the action of buying or selling the security has affected its price. From this
persepective theVaR number can be interpreted as a measure of the profit at risk (PaR) over the liquidation
horizon, i.e. the amount that could be lost, corresponding to a given confidence level, due to the fact that
liquidation of positions is not instantaneous (with consequently higher liquidity costs), but it is subject to
market risk over the liquidation period, the risk being higher for positions that cannot be promptly
liquidated.
The calculation of VaR typically assumes that all positions in a portfolio can be unwound over a single
holding period. From a PaR perspective, this assumes that all positions have a similar degree of liquidity.
While the assumption of uniform liquidity across a portfolio might be appropriate for some equity
investments, the appropriate unwinding period required to minimize liquidiy costs usually depends on the
characteristics of a particular position, typically on the amount invested and its relation to the average daily
traded volume corresponding to that position.
A more fruitful approach to computing PaR is therefore one where each trade can be associated with its
specific unwinding period, and more illiquid positions are not unwound on a single horizon date, but
(nimbly) over a period of days up to a position-dependent horizon. From this point of view the difference
between PaR (computed with trade specific holding periods) and VaR (computed with the minimum
possible holding period), give us a measure of the liquidity risk associated to the most illiquid portion of a
portfolio (implicit in this modeling approach is that liquidity costs are negligible if a trade is liquidated over
the appropriate horizon and the unknown liquidity costs we would incur if we liquidated instantaneously
are modeled indirectly through the higher market risk incurred by an illiquid trade.) A simplified risk
measure associated to PaR is sometimes referred to as ‚liquidity-adjusted VaR‛.
As we will clarify below it is possible to extend the parametric and the MC simulation approaches to non-
uniform unwinding across a portfolio. The new methodology is a straightforward generalization of the VaR
calculation in the parametric case, see page 25, while it requires extending the single-step simulation
framework typically used when estimating Monte Carlo VaR, to a more flexible a multi-step simulation
approach, see page 29.
The specification of a trade specific unwinding horizon can be achieved in VaRworks by using the headers
UNWINDTYPE and UNWINDPERIOD.
Another useful risk measure that helps to quantify potential losses due to counterparty default is called
Potential Future Exposure or PFE. While VaR gives you a measure of the potential losses you might incur
when the value of your overall portfolio (MtM) decreases due to market risk, PFE gives you information
about potential losses if a counterparty you have open positions with were to default. Assume that positions
in a portfolio are grouped in terms of different counterparties or, more appropriately, in terms of the
different netting sets that you have set up with all your counterparties. Thus, VaR for positions in a given
netting set measures the loss tail of the P&L distribution over a given horizon, while PFE measures your
exposure to the net (within a given netting set) positive MtM, hence subject to default risk, you would be
owed by a counterparty at a certain point in time in the future.
PFE is useful because it provides a way to quantify the potential losses due to default. In particular, let’s
assume that 1) we have a way to sample default events, and 2) that default events and market scenarios are
only weakly correlated (this assumption would be inappropriate if systemic risk, driving both market and
defaults, needs to be accounted for in the analysis, but taking this correlation into account is outside of the
scope of a product like VaRworks). If defaults are monitored at discrete times denoted by Ti , and if dα,i is
the probability that counterparty α will default between T i and Ti+1, we can derive the expected loss due to
default as
DefaultLoss  ∑ i,α dα,i PFE(α,i) (1-R α)
where, for simplicity of notation, we assume there is a one-to-one correspondence between counterparties
and netting sets, and R α denotes the recovery rate associated to counterparty α.
The expected value of future potential losses at horizon,t, (not present valued), due to the counterparty
failing to deliver a positive MtM(t), i.e.
DefaultLoss(t) = max(MtM(t), 0)
We compute EFE(t) as the average over all the simulated DefaultLoss for a given t:
EFE(t) = <DefaultLoss(t)>
Given a user provided probability of default over the horizon D(h), and an estimate of the recovery rate R,
the actual expected loss due to default would be equal to PFED(h)(1-R), i.e PFE gives an estimate of the
maximum possible loss.
Given the series of EFE(t) for all settlement dates {t} of the portfolio, the definition of PFE is arbitrary, with a
common definition being:
PFE(N) = MAX over t { EFE(t) + N x sigma(t)}
where N is some specified number of sigma(t) (standard deviations) of the EFE(t) distribution. Alternatively,
one might take an Average instead of the MAX, or use a percentile (e.g. 95th) of the EFE(t) distribution rather
than some fixed number of standard deviations:
PFE(p) = MAX over t { Percentil(DefaultLoss(t))}
VaRworks allows for the calculation of PFE, within a Monte Carlo simulation framework, see VARCARLO2
and the description of the pv_flag input.
The technique for calculating analytic VaR is based upon multiple steps: 1) estimate the variance-covariance
matrix of market values for a set of specified, benchmark cash flows made at specified future time intervals
from now (‚maturities‛) where the flow-maturity combination is termed a vertex; 2) decompose, or shred,
financial instruments into their component cash flows; 3) distribute, or allocate, the shredded cash flows to
the given vertices while preserving some of their financial characteristics; and finally 4) calculate the
variance of the portfolio of mapped cash flows. Collectively, the process of shredding an instrument and
allocating the shredded cash flows to vertices (steps 2 and 3 above) is termed cash flow mapping.
For a concrete example, the financial instrument known as a currency swap consists of, for instance, the
promise to pay certain amounts of Deutsche marks in return for receiving certain amounts of U.S. dollars, at
certain times. The shredding step reduces the currency swap into perhaps a dozen or so cash flows, for
example, $1 received (or paid) in 6 months, 12 months, 18 months, 24 months, and so forth., and similarly
for 1DM received (or paid) at the same times. The shredded cash flows of the original swap do not
necessarily lie exactly upon these vertices where the risks were measured—measuring variances and
covariances for all possible cash flows would be an impossibly large task—so the shredded cash flows must
be allocated to the vertices in amounts that behave equivalently in terms of risk. Thus, in our currency swap
example, the dozen or so original cash flows are allocated to ‚equivalent-sized‛ flows lying at the vertices.
As a final step, the risk portfolio of all mapped asset flows is calculated together, accounting for the risk
offsets of low covariance, and resulting in a single number: VaR.
Cash flow mapping attempts to answer the question: What set of cash flows provides the ‚best‛ surrogate of a
financial instrument for the purpose of measuring the instrument’s risk within a portfolio?
A cash flow map is the representation of a financial instrument as a stream of one or more zero-coupon
instruments marked to market at current market rates and prices. Prior to calculating analytic VaR, financial
instruments must be decomposed into their component cash flows and allocated to a pre-determined set of
asset class and maturity vertices for which volatilities, correlations, and other statistics have been measured.
Cash flow mapping takes a trade description and produces a series of home currency present values of cash
flows marked by 1) a currency, 2) an asset class (which may be indicative of credit rating), 3) a maturity in
years, and 4) a signed amount.
This process has four steps:
1. Shred the instruments into cash flows

Take a description of the trade and shred it into a series of times and signed cash flows in the local
currencies. The local currency is the currency the cash flow is paid in. The method for doing this varies from
one instrument type to another (but this is the only step that varies).
2. Take present values

Present value the cash flows to the effective date (usually today). The effective date is the date that the VaR
will be calculated for—zero time compared with the times of the cash flows.
This step results in a series of times and cash flows: t and Ct. Present value these cash flows as follows
PV  Ct e  rt
where PV is the present value of Ct, Ct is the cash flow occurring at time t, t is the maturity in years, and rt is
the local currency interest rate at time t (interpolating on the local currency yield curve if necessary).
3. Convert the cash flows to the home currency

The home currency is the currency for which VaR is calculated. All cash flows and risks are expressed in the
home currency.
Multiply the present value of the cash flow by the spot exchange rate of the home currency units per local
currency units. Spot exchange rates are used since present values of cash flows are converted. Use the cross
exchange rate if the home currency is not U.S. dollars
Xh
PVh  PVl 
Xl
where PVh is the present value of the cash flow converted to the home currency, PVl is the present value of
the cash flow in the local currency (from step 2), Xh is the exchange rate home currency/U.S. dollar, and Xl is
the exchange rate local currency/U.S. dollar.
4. Allocate the cash flows to vertices

Distribute the shredded cash flows to pre-determined asset class-maturity buckets for which volatilities and
other time series statistics have been measured.
Note that this step typically includes adding a cashflow equal to PVh at the spot exchange rate vertex of the
local currency that measures the exchange-rate risk of the instrument.
This section describes cash flow mapping methods for some specific instruments.
There are two approaches to the shredding and allocation described in steps 1 and 4 above. In the first, the
instrument is decomposed into its payouts of cash and assets at the times they will occur (or, sometimes, as
in the case of options, delta cashflows at the times they are expected to occur—see below for details on
specific instruments), and these flows are distributed to the risk vertices. In the second approach, the
instrument price’s sensitivity to the risk vertices is measured directly.
The first approach is used for interest-rate instruments. This is because a map to the payment/reset times has
two attractive properties: 1) for fixed cashflow instruments, such as bonds, the map is the cashflows of the
instrument, and 2) the present values of the cashflow map amounts sum to the value of the instrument. The
second property remains true even for instruments like options and floating-rate instruments, where the
cashflow amounts are deltas. The direct risk-vertex map does not have this property unless the yield curve
is interpolated linearly on the discount factors, which would produce prices inconsistent with FEA’s
@INTEREST and other interest-rate pricing tools.
The second approach, mapping directly to risk vertices, is used for instruments that are priced using FEA’s
@ENERGY.
Average-price options
The settlement-currency exposure is mapped to the expiration of the contract while the exposure to the
currency of the underlying is mapped to the start time of the averaging (or today, if the start time is in the
past). If the underlying is a commodity, there is additional commodity exposure—placed at the tenor of the
underlying currency. (See Currency and commodity options below.)
Dual options
These are mapped in the same way as an option on a single asset, except there are two underlying assets
instead of one. (See also Currency and commodity options below.)
Bond forwards
There are two cash flows on the expiration date: 1) the agreed strike price of the forward contract is paid,
and 2) the then present value of the bond is received.
Bond futures
Because margin settlements are made continually, only the receipt of the contracted bond is mapped on the
expiration date. This means that the risk of the contract, from the VaR calculation, will be the change in the
contract value, disregarding any accumulated value in- or out-of-the-money the contract may have accrued.
Bond options, swaptions, caps, and floors

These instruments are delta-mapped to the coupon (or payment) dates. This means 1) the option is valued
with the input yield curve; 2) the yield curve is shifted at each coupon date in succession and the option is
revalued; 3) the first number is subtracted from the second and the result is divided by the change in the
discount factor at that point.
If the option is deep in-the-money then the resulting cash flows will be similar to the cash flows of the
underlying instrument. If the option is deep out-of-the-money then the resulting cash flows all will be near
zero.
Bonds with embedded call

Bond and option deltas are calculated using the method above and then the option deltas are subtracted
from the bond deltas.
Bond futures options

A bond futures options is mapped as an option on a bond that starts paying coupons after the expiration of
the futures contract. The strike on the futures contract is discounted from the futures expiration time to the
option expiration time (strictly speaking this approximation is exactly correct for European options only).
Note that there is no conversion factor in the trade record. The conversion factor can be taken into account
by multiplying the strike of the option by the conversion factor for the bond in the record.
Brady bonds
A Brady Bond is mapped to the spot of the local currency of the country of issue. Foreign exchange risk, if
applicable, is associated with the currency in which the bond is denominated.
Cash flows
Cash flows are mapped to the specified tenor unless the specified asset implies otherwise.
Commodity futures
The underlying commodity exposure, interest-rate risk of its currency of denomination, and interest-rate
risk of the settlement currency are mapped to the tenor of the expiration date of the futures contract, as a
forward contract. The commodity exposure is reported in terms of its value in the home currency.
Commodity swaps
The underlying commodity exposure, interest-rate risk of its currency of denomination, and interest-rate
risk of the settlement currency are mapped to the tenors of the specified swap dates of the contract. The
commodity exposures are reported in terms of their values in the home currency.
Convertible bonds
Convertible bonds are mapped to three kinds of exposures. The bond is delta mapped like a regular coupon
bond (see above) to the corporate credit rating yield curve. The equity exposure is delta mapped at spot. The
third exposure is the difference between the value of the convertible bond and the sum of the first two
exposures. It is mapped to the spot government interest rate and represents the equity dividend payments.
Currency swaps
Fixed-for-floating currency swaps are mapped in the same way as interest-rate swaps. Fixed-for-fixed are
mapped as a long and short bond. Floating-for-floating are mapped as a long and short FRN.
Currency and commodity options

Delta risk measures of currency and cross-commodity options are used to construct cash flows for the buy
and sell sides of a given contract. Given the value of an underlying asset or settlement price (strike), such a
cash flow takes the form
absolute delta  value  underlying amount
where absolute delta is a dimensionless number, the derivative of the present value of the contract with
respect to value, and underlying amount is the number of units of asset or settlement exchanged. If the option
is on the spot price, and of American (European)-style exercise, the settlement and underlying asset are
mapped to the spot (expiration of the option). If the option is on a futures price, and of American
(European)-style exercise, the settlement is mapped to the spot (expiration of the option) while the
underlying asset is mapped to the expiration of the futures contract. If the underlying asset is a commodity,
then the commodity and its corresponding interest-rate exposure are mapped to the same tenor, with the
commodity cash flow reported in terms of its value in the home currency.
If the implied volatilities are included as risk factors, additional cashflows related to vega sensitivities are
accounted for. See Analytic VaR with the Implied Volatility Risk on page 57 for more details.
Equities and equity futures

Equity risk is mapped as market_value  beta and equity foreign exchange risk (where applicable) is mapped
as market_value. The equity price is calculated as [1 + beta  (index – 1)]. The mark-to-market size of index is
normalized to be equal to one. If a futures contract, the value of the equity and settlement, as denominated
in the settlement currency, are mapped to the futures expiration date, as a forward contract. Constant
dividends paid out before expiration are mapped to their respective tenors.
Equity options
These incur equity and constant-dividend exposure, as above (see Equities and equity futures above), as
well as the exposures of an option on the spot (see Currency and commodity options above).
If the implied volatilities are included as risk factors, additional cashflows related to vega sensitivities are
accounted for. See Analytic VaR with the Implied Volatility Risk on page 57 for more details.
Eurocurrency futures
Eurocurrency futures are delta mapped. There are two cash flows separated by a time interval equal to the
rate term. The first cash flow occurs on the expiration of the contract while the second occurs at the maturity
of the underlying deposit.
Eurocurrency futures options

A Eurocurrency futures option is delta-mapped (using the delta method described above) as an option on a
forward on a zero-coupon bond where the bond maturity is the expiration date of the forward plus the time
to maturity of the Eurocurrency future.
Floating rate notes (FRNs)

Only the first, fixed payment (principal  first_reset_rate / 100) and principal are mapped. Both are mapped on
the first, fixed payment date (no cash flows are mapped to maturity_date).
Forwards
The two currencies are mapped to the tenor of the expiration date of the forward
contract.
Forward rate agreements (FRAs)

FRAs are mapped as -principal on settlement_date, and principal  (1 + rate / 100) on the settlement_date +
rate_term.
Money market instruments

For Bankers Acceptances and Commercial Paper the cash flow occurs on maturity date and equals the
principal amount. For Certificates of Deposit the cash flow occurs on maturity date and equals principal  (1
+ cd_rate  365 / 360  cd_rate_term / 12) where cd_rate is the rate of the CD as a decimal number and
cd_rate_term is the original term of the CD expressed in months.
Interest-rate swaps
Interest-rate swaps are mapped as a combination of a bond (fixed leg) and an FRN (floating leg). The
principal is mapped on the floating side at the earliest reset date. For a currently paying swap, the first,
already known, floating interest payment is also mapped on that date. For a forward-starting swap, only the
principal is mapped on the forward_start_date. For more information see Mapping and estimating VaR in
interest-rate swaps in RiskMetrics Monitor, third quarter 1995, available at http://www.riskmetrics.com.
Swing contracts
Swing contracts are delta mapped. There are three potential cash flows: one at the start of delivery (or today
if the start of delivery was in the past), in the currency of the underlying; a second at the expiration of the
contract, also in the currency of the underlying; and a spot cash flow corresponding to the settlement
currency. If the underlying is a commodity, then there is exposure to the commodity at the two delivery
times. The commodity exposures are reported in terms of their value in the home currency.
Asset-backed securities
These instruments are generally very complicated and not supported directly—they must be input as a
group of cash flows that are the output of a prepayment model. If they are high-rated tranches they can
probably be given as bond (if there’s a fixed rate) or FRN (if floating).
Unsupported instruments
VaRworks supports most of the common financial instruments. If your portfolio contains an instrument not
directly supported, you can either decompose the instrument into simpler, supported instruments (for
example, a structured note might be decomposed into a swap and a bond) or map the instrument yourself
as zero-coupon bonds (or dated cash flows) and enter the cash flows as BOND or CASHFLOW trades.
After shredding instruments into cash flows, the CASHFLOWMAP function allocates, or distributes, them to
vertices—the pre-determined asset class-maturity buckets for which volatilities and other time series
statistics have been measured. If a cash flow occurs on a vertex then the entire cash flow is allocated to that
vertex. If a cash flow falls between two vertices, as is usually the case, then it is split between the two closest
vertices. For example, a cash flow occurring in six years can be represented as a combination of a five-year
and a seven-year cash flow. The diagram below illustrates a cash flow C occurring at time T allocated to
vertices of cash flows C1 at time T1 and C2 at time T2. The actual amounts C1 and C2 depend on the allocation
method, described below.
Allocating a Cash Flow to Vertices
Amount
Original cash
C flow
T Time
Amount
Allocated
cash flows
C1 C2
T1 T2 Time
If only a single appropriate vertex exists for a cash flow (as in the case of spot foreign exchange and equity
indexes) then the entire cash flow is allocated to that vertex preserving present value only. If a cash flow
occurs before the shortest vertex or after the longest vertex then the entire cash flow is allocated to the
nearest vertex preserving only present value. With version 5.1, the additional choice of allocating to the
vertex just preceding or following the time of the original cashflow can be made for commodity vertices: see
the preserve_var argument of the CASHFLOWMAP function.
If preserve_var is TRUE (or is equal to 1), CASHFLOWMAP returns risk-preserving cash flow allocations,
which preserve present value (PV) and market risk (VaR). If a cash flow C occurring at time T is mapped to
vertices at times T1 (< T) and T2 (> T) then the PV-conserving, VaR-conserving cash flow sizes C1 and C2 will
be
C1   C , and
C2  1   C
where  is some number between zero and one, inclusive, and is determined by solving the equation
 C2   2 C2  (1   ) 2  C2  2  (1   ) C  C
1 2 1 2
where i is the price volatility of cash flow i, and  is the correlation between vertex cash flows C1 and C2.
In particular, C is the price volatility of the original cash flow C. In practice, this is obtained from
knowledge of the yield volatility Y of C, viz.
C  Y  y  T
where Y and the yield y are interpolated from the values provided for C1 and C2, and T is the duration
(maturity) of C. Generally speaking, when C1, C2, and C are commodity cash flows, yield volatilities, and
sometimes yields themselves, are not provided for C1 and C2. Thus, for commodity cash flows, C is
interpolated directly from the price volatilities of C1 and C2, which are always present in the data set.
A transformation yields the quadratic equation
a 2  b  c  0
where
a   C21   C22  2  C1  C2
b  2  C1  C2  2 C22
c   C2   C22
with the two solutions

- b  b 2  4ac - b  b 2  4ac
1  , 2 
2a 2a
A solution  is chosen so that the signs of the allocated cash flows both have the same sign as the original
cash flow.
When solving the quadratic equation a2 + b + c for interest-rate cash flows on or near a vertex, imaginary
roots are sometimes generated (that is, the discriminant b2 – 4ac is negative). This problem is discussed in
RiskMetrics Monitor (fourth quarter 1995), A solution to the standard cash flow mapping algorithm which sometimes
leads to imaginary roots. During interest-rate cash flow allocation, VaRworks checks for imaginary roots and
other unreasonable results by performing the following steps:
1. Linearly interpolate the yield volatility.
2. Linearly interpolate the yield at the cash flow maturity.
3. Calculate the cash flow’s duration from the maturity and the yield.
4. Calculate the price volatility from the yield volatility, yield, and duration.
5. Perform a sanity check: does the calculated price volatility fall between the price volatilities of
the two vertices adjacent to the cash flow? (This is a common problem with RiskMetrics
datasets since money market yields are not present in the datasets and must be estimated.)
6. If the calculated price volatility is not sane, then linearly interpolate it directly from the vertex
price volatilities.
7. Solve the quadratic and get the two roots.
8. If there is a real root in the range [0,1] then use it. Otherwise put the entire cash flow in the
closest vertex.
Occasionally, the VaR-preserving allocation methodology will allocate most of a cash flow that lies close to a
given vertex to some ‚distant‛ vertex, rather than the close one. For example, suppose we have a cash flow
with a maturity slightly less than two years, one can still find that the one-year vertex gets the majority of
the allocation. This behavior is a direct result of the RiskMetrics methodology. What’s happening is that one
root is slightly negative, and is therefore rejected in favor of the second root (which falls between zero and
one—close to one). As the cash flow maturity approaches two years, the smaller root approaches zero and
the second root approaches one. The smaller root becomes the chosen solution only when it is precisely
zero—a maturity of exactly two years. What we find is that the one-year vertex gets more and more of the
allocation until, finally, at the exact limit of two years, the solution jumps to the lower root—giving the two-
year vertex all of the allocation. This discontinuous behavior is an artifact of the methodology, which
requires the allocated cash flows to have the same sign as the original cash flow.
If preserve_var is FALSE (or has value equal to zero), CASHFLOWMAP returns duration-preserving cash
flow allocations, which preserve present value (PV) and duration. A cashflow is a zero-coupon bond, and its
duration with respect to the continuously compounded yield is its payment time. So the PV-conserving,
duration-conserving mapping is a time-weighted mapping. For a cash flow C occurring at time T the
mapping to vertices at times T1 (< T) and T2 (> T) is
T2  T DFT
C1  C  , and
T2  T1 DFT1
T  T1 DFT
C2  C 
T2  T1 DFT2
where
DFt is the discount factor for time t.
VaRworks uses FEA-developed routines for valuing financial instruments. While these routines have been
thoroughly tested in real-world trading environments (and are available from FEA separately), it is
important to realize that VaRworks implements statistical risk management methodologies and is not a
valuation tool. While marking positions to market is a necessary first step in mapping, it is not imperative to
be perfectly precise since risk estimation represents the potential for change in a position’s value (the first
derivative). For example, using 95 as a marked to market for a position worth 100 will not affect the risk
estimate significantly (2% of 95 is not very different from 2% of 100). Also, the VaR methodology
necessitates multiplying very large numbers (cash flows) by very small ones (daily volatilities), further
mitigating the need for precision.
When converting dates into years, an actual/365 day count basis is used. Prior to release 5.2, actual/365.25
was used. The actual/365 basis allows placement of instrument dates exactly on some risk vertex times,
facilitates testing of cashflow maps generated by VaRworks, and improves consistency with the way tenors
are defined by the underlying FEA pricing libraries.
Analytic VaR calculation is a two step process.
1. Calculate the position risk vector. Take the incoming mapped position vector (a cash flow map
calculated by CASHFLOWMAP) and convert it into an intermediate position risk vector using the
volatility vector
position _ risk _ vector  position _ vector  volatility _ vector
The sum of the elements in the position risk vector is also called the undiversified VaR since it does not
account for correlations.
Note that this is a matrix block-multiplication, that is, Cij = Aij  Bij. So each cash flow in the 1  n
position_vector is multiplied by its corresponding volatility in the 1  n volatility_vector to obtain a 1  n
position_risk_vector of undiversified VaRs.
2. Calculate the diversified VaR. Multiply the position risk vector times the correlation matrix times the
transpose of the position risk vector, then take the square root
VaR  VCV 
where V = position_risk_vector and C = correlation_matrix
VARANLU calculates the position risk vector (or undiversified VaR) (step 1 above); VARANL calculates
diversified VaR (step 2 above).
The VaR calculation question can be posed the following way: given a normal distribution centered at zero
with standard deviation , how far away from the center is a tail with 1 – x percent in it? Answer: the
distance equals VaR. Graphically, VaR can be interpreted as follows:
Graphical Depiction of VaR
Probability of gain or
loss from future value
Prob{ X < –v } = z (Prob{X = x})
z
X
– Loss –v 0 + Gain
VaR
Consistent with previous notation let p be the N-dimensional position vector describing the (linear)
decomposition of the portfolio along the dataset risk vertices, and let Q be the daily NxN covariance matrix
corresponding to the dataset. p is obtained by summing over the position vectors corresponding to each
trade (), i.e. p= p. The VaR calculation for a uniform horizon of h days is carried out under the
assumption that Q is constant, the position vector returns are serially uncorrelated over the horizon period,
and p is held for h days. The variance over each day is computed as p Q p and, since the position vector is
held for h days, the total variance is simply h p Q p.
In the more general case of a PaR calculation we need to keep track of the unwinding over time of each p .
Let fi denote the fraction of p that has not been liquidated before day i, i =1, 2, <, h . Note that 0 ≤ fi ≤ 1 ,
f 1 = 1, fi = 0 for i > h . In the case of the VaR calculation described above fi =1 for i=1, 2, <, h, indicating
that all positions are kept whole for h days and liquidated at the end the horizon period. Under the
assumptions stated above we can write:
PaR =   i
p'i Q p'i (PaR.1)
where  is the constant transforming volatility into PaR (VaR)( 1.65 for 95% PaR), and p’ i =  fi p ,
i.e. p’ i represents the position vector adjusted on each day to account for the partial liquidation of trades.
Note that the sum over i goes from 1 to hmax , the maximum unwinding period among all trades in the
portfolio.
The VARCARLO function calculates Monte Carlo VaR. Monte Carlo simulation provides a method of
valuing something that depends on the uncertain future state of the world. In the financial context, this
could be an equity, a portfolio of investments, or, as befits our special interest, the VaR of a portfolio. The
method is simple—many possible futures for the world are randomly chosen using statistical knowledge of
the present, the value of the object of interest is calculated for each of the possible futures, and the probable
future value of the object is estimated by averaging all the futures. This method is computationally intensive
and produces only a statistical estimate of the value of the object. That is, we don’t know the exact value of
the object; rather, we know that the value of the object lies in a known range with a known degree of
certainty. The Monte Carlo method is slow to converge. Halving the range of certainty requires considering
four times as many alternate futures. On the other hand, the Monte Carlo method is robust, free of
assumptions, and provides an answer when other methods fail. It is widely used to solve technical and
scientific problems.
Here’s how the Monte Carlo method applies to VaR. Suppose we have a portfolio of financial instruments
whose value depends in a known manner on assets for which we know the present and historical values.
These assets could be equities, interest rates, foreign exchange rates, commodities, and the like. From our
historical knowledge of asset price behavior, we can construct a distribution of past price changes over a
given time interval. We construct a possible future by randomly selecting price changes from the known
distributions of past price changes and adding them to the present asset prices. These future asset prices are
then used to obtain the change in value of the portfolio in this possible future. This random process is
repeated many times and results in a list of portfolio price changes. These price changes are then ordered
and, for say a 5% VaR, we select the particular price change in the list for which 5% of the changes are worse
and 95% are better. The selected price change is the value at risk.
The analytic variance-covariance method of calculating VaR is based on a number of assumptions—the most
important of which is that the distribution of price changes in a portfolio is normally distributed. If a
portfolio contains non-linear instruments, for example, callable bonds and options (or other instruments for
which a price change in an underlying asset does not produce a proportional price change in the derivative
instrument), then a more robust method should be used to accurately calculate VaR. In practice, however,
variance-covariance VaR provides a good approximation to the true VaR unless the portfolio is strongly
non-linear. Indeed, even when the portfolio has non-linear instruments, corrections based on option deltas
and gammas can be used to improve the estimate of VaR.
Monte Carlo simulation may be used to calculate VaR even when a portfolio is strongly non-linear. If
computationally intensive, this simple procedure provides a great deal of information since the actual
distribution of results is calculated. From this distribution, you can deduce the expected value of the
portfolio, the spread in returns, the measures of the non-normality of the distribution, as well as the VaR.
More insight is imparted by viewing the distribution of results than by consideration of a single number like
VaR which, simply speaking, is a measure of the extent of the tail of the distribution.
Consider tradeoffs between desired accuracy and available computing time. First, note that if a portfolio
contains only financial instruments whose prices vary linearly with respect to asset prices, both methods
give comparable results. In this case the analytic method is preferred because it is calculated faster.
When the portfolio contains nonlinear instruments, the accuracy of the analytic method becomes
questionable while the Monte Carlo method is unaffected. Suppose that our portfolio P depends nonlinearly
on one asset A. In the Monte Carlo approach, the price change is calculated exactly
 PMonteCarlo  P( Anew )  P( Aold )
In the analytic method, the nonlinear price change is estimated by a linear (delta) or quadratic (delta-
gamma) power series approximation

 PAnalytic  (A)  (A) 2
2
where A = Anew – Aold. In the case where P depends linearly on the asset A,  = 1 and  = 0. Thus, when we
know that PAnalytic is a bad approximation to PMonte Carlo, we should use the Monte Carlo method to
calculate VaR. For a more accurate description of non-linear approximations for non-linear instruments, see
page 236.
In practice, this type of error judgment is difficult to make. There might be many nonlinear instruments in
the portfolio that could collectively lead to large errors. On the other hand, the Monte Carlo result depends
on the number of possible future outcomes that are considered and the inherent uncertainty of the Monte
Carlo method may be larger than the errors associated with the analytic method’s estimate of price change.
A consideration for large portfolios is the number of asset and maturity vertices: variance-covariance
matrices tend to become unstable (mathematically, non-positive definite) as they grow.
A prudent approach is to use the analytic method to calculate VaR because of its timeliness and ease of
computation but to suspect the results when the portfolio has significant nonlinearity. The analytic results
should be checked with occasional Monte Carlo calculations of the VaR. If the Monte Carlo results converge
(for increasing numbers of iterations) to a value different than that of the analytic method, then place your
higher trust in the Monte Carlo calculation.
Notice that for a number of non-linear instruments supported by VaRworks, see page 91, full revaluation
can be replaced by revaluation based on a delta-gamma approximation. If calculation time is a concern, such
Monte Carlo delta-gamma approximation can provide a powerful alternative to a full Monte Carlo
simulation.
The VaRworks Monte Carlo procedure follows.

1. Identify the basic underlying financial instruments on which the portfolio depends.
2. Using historical information about the volatilities and correlations of these instruments,
randomly generate a possible set of future values for these instruments and calculate the new
value of the portfolio.
3. Repeat step 2 for many possible future outcomes and accumulate the distribution of portfolio
price changes. From this distribution of price changes, VaR and other statistical quantities may
be deduced.
Three things are needed to carry out this procedure:

1. Historical knowledge about the statistics of the underlying financial instruments. For example,
RiskMetrics and MakeVC datasets.
2. Pricing models for instruments whose values derive from the underlying assets—such pricing
models are built into VaRworks for many types of options and other financial instruments.
3. A method of randomly generating possible financial future outcomes consistent with historical
knowledge.
To generate future price outcomes we assume that all of the underlying assets are stochastic and follow
geometric Brownian motion. For incorporating implied volatility as a risk factor in the Monte Carlo VaR
calculation, see Implied Volatility as a Risk Factor section. Thus, the change in price of an asset follows the
process
dSi (t )
 i dt   i dBi (t ) (1)
Si (t )
where S is the asset price, i is the drift, i is the volatility, and Bi(t) is a standard Brownian motion whose
mean is zero and whose variance is t. This is a stochastic differential equation which, using Ito’s formula,
can be immediately integrated to yield
Si (t )  Si (0) exp[( i  i2 / 2)t  ii t ] (2)
where i is a random number drawn from the standard normal distribution function. As it stands, equation
(2) suggests that each of the assets Si evolves independently of each other. However, we can make the
various Si evolve consistently with the historical correlations by choosing the i to be correlated.
The correlation of the i is accomplished by means of a Cholesky decomposition of the correlation matrix. If
we are given that the matrix describing the various correlations between Si and Sj is
1 12 ...
  12 1 ... (3)
... ... ...
and we find the matrix A such that
AAT   (4)
where T denotes matrix transpose, then a correlated vector of random numbers can be generated from an
uncorrelated vector of random numbers by means of the operation
 corr  AT   uncorr (5)
Finally, note that the drifts, i, of the various assets are much more difficult to accurately estimate than are
the volatilities and correlations. Indeed, they are generally not available when the horizon time is short (say
of the order of one day). Fortunately in this case their contribution to the exponent in equation (2) is
negligible and their value can safely be taken to be zero. For longer simulation horizons (say one month or
longer), drifts can become important and their market expected values are inferred by an analysis of the
corresponding futures price structure, at least in the case when futures prices belong to the dataset of the
basic underlying financial instruments. When futures prices are not available the drifts are assumed to be
zero.
To recapitulate, examine the portfolio to determine which vertices are needed, then construct the covariance
matrix (4) C = [cij] where cij = ijij for these vertices using available historical data (this step is done for you
by MakeVC). Choose a vector of independent random numbers, one random number for each vertex, and
transform this vector into a vector of correlated random numbers by means of equation (5). These correlated
random numbers are used in equation (2) to calculate future values of the Si(t). The change of the portfolio
value is then calculated according to
N
Vportfolio   Pj ( S (t ))  Pj ( S (0)) (6)
j 1
where Pj represents the price of the j-th financial instrument in the portfolio. Note that the price of a given
financial instrument may depend on several of the underlying assets S. The calculation of the change in the
portfolio value is then repeated many times and a list of the outcomes, {V1, V2, V3, ...}, is constructed.
From this list the distribution of results f(V) may be constructed and a variety of statistical information
may be deduced. For example, if a 95% VaR is required, the list is sorted in ascending order and the value
Vi that is 5% of the way through the list is the loss corresponding to VaR. If N is the number of simulated
scenarios, c is the confidence interval used to define VaR (e.g. 95%), and o(i) maps each market scenario to
its ordering number after the portfolio P&L’s (Vi ) have been ordered from highest loss to highest gain, we
then have
VaR= Vo(i)=(1-c)N (7)
Component VaR Calculation via Monte Carlo

To estimate the VaR attribution to individual components (representing individual trades or subportfolios)
defining a disjoint decomposition of the overall portfolio we first write the P&L associated to each simulated
market scenario i, Vi, as a sum of contributions coming from the individual components, i.e. Vi = j pj
Cj, i, where Cj, i represents the P&L of component j, for unit notional, within market scenario i.
Following the notation introduced with Eq. (7) and computing pjVaR/pj we find that
CVaR j = p j C j, o(i)=(1-c)N . (8)

Simply computing this formula, however, introduces a large error in the estimate of CVaR j . To improve
the estimate we introduce averaging over a number of market scenarios that are in a neighborhood of the
scenario i such that o(i)=(1-c)N. We thus replace the estimator in (8) with
CVaR j = 
(1c ) N  k o ( i ) (1c ) N  k
p j C j, o(i) (9)
where we have chosen k= N . Note that, with this choice of k, the number of points in the interval
increases with N, but, in the limit of large N, the quantile range spanned by the sum reduces to the desired
quantile (1-c). We have compared the expected analytic result and the estimate obtained through Eq. (9), for
a number of linear portfolios for which CVaR j can be computed analytically, and we found convergence to
be quite good even for N=1,000 iterations.
The estimate of VaR via Monte Carlo simulation is typically obtained by simulating a large number of
possible market conditions at the horizon time, and by revaluing the portfolio at horizon according to these
simulated conditions. This is done via a single step simulation, i.e. given today market conditions,
scenarios are generated for a single future point in time corresponding to the horizon time. If a trade expires
(and/or has cashflows) between value date and the horizon time, the value of the trade at expiration (and/or
the value of the intervening cashflows) is estimated by using information about the trade on value date and
the horizon time only. A simplified approach, embodied by the no_analytic_limit input in the VARCARLO
function, assumes that although market conditions change consistently with the specified horizon and
volatility/correlation dataset, instruments at horizon are revalued with the same terms and conditions they
have on value date, including time to expiration. The advantage of this approach is that no special treatment
or estimate is required for cashflows occurring between value date and horizon, because no such cashflows
exist within this approximation. The drawback of the approach is that the risk of instruments with short
maturities (like options close to expiration) might be misrepresented.
Estimating PaR via Monte Carlo simulation requires instead a multi-step simulation framework: market
scenarios, consistent with a given covariance matrix, are obtained for a number of dates in the future,
typically for all the dates when the different portfolio trades are (partially or completely) liquidated. A
multi-step simulation framework is also useful to properly account for trades with uncertain cashflows
before horizon (for instance expiring trades), as market scenarios for those dates can be explicitely
simulated, and the instrument revalued on those dates.
VaRworks performs a multi step simulation when at least one trade defines an unwind period via the
UNWINDPERIOD header. If no trade explicitely defines a value for the header, the single step framework is
used instead. In multi-step simulations, market scenarios are generated for each weekday (i.e. excluding
Saturday and Sunday) until the longest (considering all trades within the portfolio) unwinding period is
covered. If tk denotes the time corresponding to the kth step in the simulation, with t0 representing time 0,
prices for each asset are generated by repeatedly using Eq (2) above:
S i (t k )  S i (t k 1 ) exp[(  i (t k 1 )   i2 / 2)(t k 1  t k )   i (t k 1 ) i t k  t k 1 ]
where the volatility parameter is kept constant, but the total drift coefficient ( i (tk 1 )   i / 2)(tk 1  tk ) ,
2
is allowed to change based on market expectation at time t0 of the drift to be applied between tk-1 and tk
(see the remarks on the drift input in the VARCARLO function, see page 343.) The  i are regenerated at
each time step, hence the notation  i (tk 1 ) used in the equation above.
The equation above requires specification of how to convert a daily or monthly volatility input (see
Volatilities on page 272) to the appropriate volatility to be applied between tk-1 and tk , i.e. we need to define
the daycount convention specifying the length of the tk  tk 1 period. The following table specifies the
convention adopted by VaRworks, and assumes that  in the above formula has been annualized by
multiplying by 252 or 12 depending on whether one is using daily or monthly vols (the custom volatility
format cannot be used in a multi-step framework):
Daycount convention used in single-step

framework
Daily volatility input Horizon ≤ 5 days: Actual/252
Horizon > 5 days: Business Days/252
Monthly volatility input Horizon ≤ 5 days: Actual/252
Horizon > 5 days: Actual/360
Daycount convention used in multi-step

framework
Daily volatility input Horizon ≤ 5 days: Weekdays/252
Monthly volatility input Horizon ≤ 5 days: Weekdays/252
where VaRworks counts business days by counting the number of weekdays (i.e. excluding Saturday and
Sunday) and adjusting it by substracting a prorated measure of the number of holidays, assuming there are
eight holidays during the whole year.
Full revaluation of an instrument is done only on days when the instrument position is either unwound or
the instrument expires. When a trade position is liquidated over several days, the value on each day i is
multiplied by the fraction of the trade that is unwound on that date. For day i =1, 2, <, h this is equal to
(using the notation introduced on page 25), f,i - f,i+1, where f,i denotes the fraction of the trade that has
not been liquidated at the beginning of day i.
Trades of type included in the table below support the multi-step framework described above, whether or
not uncertain cashflows occur before the final unwinding date. Instruments not included in this list also
support the multi-step framework only when no uncertain cashflows occur before their final unwinding
date. Instruments not included in this list with uncertain cashflows before their final unwinding date, and
portfolios where no trade specific unwinding period is defined via headers, are valued only at horizon time,
and uncertain cashflows are estimated within the single-step simulation framework.
TYPE supporting multi-step framework

ASIAN
BARRIEROPT
BESTOF
BOND
CALSPREAD
CAPFLOOR2
CASHFLOW
COMMODITYFUT
COMMODITYPHYS
COMMODITYSWAP
CRACK
DBARRIEROPT
DUAL
EQUITY2
EQUITYFUTURES2
EQUITYOPTION
EQUITYOPTION2
FRN
INDEXSWAP
OPTINDEXSWAP
OPTION
OPTION2
STRIPOPT
STRIPSPREADOPT
SWAP
SPREAD
A Monte Carlo simulation is often amenable to parallel computation, since the bulk of the calculation is
composed of independent simulation runs, whose results can be computed in parallel and reassembled for
final analysis. The current availability of cheap multi-processor computers makes parallel computing within
reach of a relatively modest budget, provided the application is designed to be run in parallel. Starting with
version 5.0, the Value at Risk Monte Carlo simulation has been multi-threaded, and substantial speed
enhancements can be achieved when running the application on a multi-processor computer, on UNIX and
Windows platforms.
By default the Monte Carlo simulation is not multi-threaded. The user can introduce threading by setting
the environment variable FEATHREADS to the desired number of threads. As a general rule, this number
should equal the number of processors available, e.g. for a two-processor machine, set FEATHREADS to 2,
but the optimal setting can also depend on the composition of the portfolio: see the discussion below on
instruments that are not thread safe. The user can also determine the optimal thread number given a system
configuration and portfolio composition by running VaRworks with different values of FEATHREADS.
Setting of environment variables depends on the operating system. In Windows XP use Start->Control
Panel->System->Advanced->Environment variables to set FEATHREADS.
Currently parallel calculation is achieved by running the simulation iterations in parallel.

At the moment some of the VaRworks instruments will not benefit from multi-threading, since their original
design was not thread safe. These instruments are Bonds, Bond Forwards, Bond Futures, Bond Futures
Options, Bond Options, Brady Bonds, Eurocurrency Futures, Eurocurrency Futures Options, Caps and
Floors (Type I), and Swaptions (Type I). A portfolio composed only of these instruments will not run any
faster on a multi-processor computer.
VaRworks HISTORICALVAR function calculates Historical VaR, Shortfall Risk, mark-to-market,

distribution statistics, and raw simulation results.
Like Monte Carlo simulation, historical simulation provides a method of estimating the risk of a portfolio,
which depends on the uncertain future state of the world. In this method, many possible futures for the
world are chosen using information about market changes in the past. The market value of the portfolio is
calculated for each of these possible futures. Comparing each future market value to the value of the
portfolio today, an estimate of the hypothetical profit or loss is determined. Historical simulation is a robust
method of value-at-risk estimation. Unlike Monte Carlo simulation, it is free of statistical assumptions about
market returns, and provides an answer when other methods fail. Historical simulation is becoming a
standard VaR methodology.
The simulation procedure of the historical approach is in some ways analogous to that of Monte Carlo
simulation. These similarities can be discerned from the following description. Suppose we have a portfolio
of financial instruments whose value depends in a known manner on assets for which we know the present
and historical values. These assets could be equities, interest rates, foreign exchange rates, commodities, and
the like. From our historical knowledge of asset price changes, we can construct a time series of past price
changes over a given time interval, or data window. This can be done for each asset on which our portfolio
depends. In other words, each asset can be associated with a time series of price changes that falls within a
single (common-to-all-assets) data window. From this window of historical samples, we can construct a
possible future for an asset by selecting a past price change corresponding to a particular observation date of
the data window. The asset price change can be applied to the current price of the asset to obtain a
simulated new value for the asset. (More precisely, each price return is computed from the historical price
series, and is applied to the current price of the asset to generate the historically simulated new value of the
asset.) When this is done for each asset, full revaluation provides a new value for the portfolio. One can
repeat this process for all the dates in the data window, from the start date of the window to its end date,
obtaining a new set of hypothetical portfolio values. Comparing these historically simulated portfolio values
to the current portfolio market value, we can obtain portfolio P&L’s that can be ordered to form a simulated
profit-and-loss distribution. Thus, for say a VaR corresponding to 95% confidence, we can select the
particular price change in the distribution for which 5% of the changes are worse and 95% are better. The
selected price change is the value at risk.
As with Monte Carlo simulation, historical simulation may be used to calculate VaR even when a portfolio
is strongly non-linear. From the historically simulated profit-and-loss distribution, you can deduce the
expected value of the portfolio, the spread in returns, statistical measures of the non-normality of the
distribution, and the VaR. In particular, because of the lack of statistical assumptions about the returns of
the underlying assets, historically simulated distributions are especially amenable to analysis via Extreme-
Value Theory, a topic discussed in a subsequent section.
For non-linear instruments and portfolios, the arguments for using Monte Carlo simulation also apply to
historical simulation. The main advantage of the historical simulation approach is that it does not make any
assumptions about the distribution of asset returns. Therefore, if asset returns are not normally distributed,
historical simulation can provide us with a more realistic view of our portfolio risk, depending on the
validity of using past prices to current market conditions. Also, historical simulation is conceptually simple
and therefore easy to interpret and communicate in risk management reports.
When we use historical simulation, we do not need to estimate volatilities and correlations. In other VaR
methods, such as the variance-covariance (analytic) method and Monte Carlo simulation, we summarize all
the historical data into volatilities and correlations, under the assumption that the price returns of
underlying assets are normally distributed. One problem with this assumption is that many asset returns
exhibit skewness (asymmetry) and kurtosis (fat tails), behavior that cannot be captured by the statistics of a
normal distribution. Another problem with this assumption is that it corresponds to price-return dynamics
that do not apply during conditions of severe market fluctuations. In these cases, the normality assumption
could lead us to inaccurate VaR estimates.
A caveat of historical simulation is that it estimates value-at-risk using only market events that have actually
occurred. Market events that have not occurred cannot be assumed to have zero probability of occurrence
simply because they have not been observed in the past. For this reason, it is ideal to supplement historical
simulation approaches with stress testing, so that the effect of various heretofore unobserved ‚what if‛
scenarios can be considered.
HISTORICALVAR calculates VaR by following these steps:
1. It identifies the basic underlying assets on which the portfolio depends.

2. Using historical information about price changes of these assets, it generates a set of possible
future values for these assets and then calculates the new value of the portfolio.
3. It repeats step 2 for each future outcome and accumulates the distribution of portfolio price
changes. From this distribution of price changes, VaR, Expected Shortfall, and other statistical
quantities are deduced.
Three things are needed to carry out this procedure:
1. Historical knowledge about returns of the underlying financial instruments—this means that
you need to provide the price history for every asset on which your portfolio depends.
2. A pricing model for each instrument of your portfolio—many types of pricing models are built
into VaRworks, for options and other financial instruments.
3. A method of generating possible financial future outcomes using historical returns and current
market prices—VaRworks provides a method, the mathematics of which is described below.
Suppose our portfolio depends on i=1,2,…,M assets. In order to perform historical simulation, we need to
provide a time series of N+1 historical prices {S i (t n ) | t 0  ...  t n  ...  t N  0} for each asset, where
tn is an observation date, expressed in days, relative to the effective (current) date, t=0. Without loss of
generality, we can suppose each asset’s time series to be of the same commensurate length N+1. If this is not
the case, we can use the intersection of all time series to arrive at a common observation-date sequence t0
<…< tn <…< tN. If there are missing dates, we interpolate as follows. For time series of asset prices the data
is interpolated linearly, while for time series of asset returns, the missing returns are set to zero (equivalent
to prices being unchanged from the previous value).
To generate future prices for each asset, we first need to select the time horizon h, expressed here as an
integral number of days. Then we need to determine the current market price Si (0) of each asset. Putting
this information together with the historical time series, the simulated future price Si (tn )* for asset i,
corresponding to the scenario n > 0 of observation date tn, is then
Si (t n )
Si (t n )*  Si (0)  (1)
Si (t n  h)
The above equation defines a set {Si (tn )
*
| t1  ...  tn  ...  tI  0}of simulated futures prices for each of
the i=1,2,…,M assets. Each set is generated from the same observation-date sequence t1 <…< tn <…< tI, where
I  N / h . For example, if N=11 and h=2, then I=5. The number I is the number of historical simulations;
it is a function of the available historical data, which may include the affect of windowing and filtering, as
described in the next subsection.
Thus, the change in the value of the portfolio corresponding to the single scenario n can be expressed as
Pn  P[Si (t n )* ]  P[Si (0)] (2)
where P gives the value of the portfolio, and P[Si] means P(S1, S2, …, SM). Repeating the calculation of the
change in the value of the portfolio for each of the dates tn in the data window, we can obtain the set of
simulated profits and losses {P1, P2, P3, ...}, which we estimate, with increasing I, to be representative of
the portfolio profit-and-loss distribution. From this distribution, we can deduce a VaR, and other statistical
measures.
A common issue users with large portfolios face, is related to the overall size of the risk factor covariance
matrix. Additionally, the transparency needed to identify key sources of risk and how to offset them is
difficult for a portfolio exposed to a large number of correlated but essentially independent risk factors.
To address this issue VaRworks allows users to explicitly identify primary and secondary risk factors in a
portfolio, and to compute risk by making certain technical assumptions about the relations between the two
types of factors. Briefly, primary risk factors are factors that are correlated amongst themselves in the usual
sense; secondary factors are related, through a ‚beta‛ coefficient, to an associated primary factor (and by the
primary factors’ covariance structure, to all other primary factors). Secondary factors, in addition, have their
own (‚specific‛) risk (characterized by a volatility parameter), but we assume them to be uncorrelated to all
other factors.
Note that the primary/secondary model estimation is supported via the FEA MakeVC product.
Let denote the return of a secondary factor and the return of a primary factor.
The returns of a primary factor will be driven by a normalized factor, :
Eq. (PS1)
with the variance of the primary factor. Correlation between two primary factors is defined in the
usual way in terms of the expectation of the product of normalized risk factors:
.
The returns of a secondary factor is related through a beta parameter, , to a single primary factor, with a
residual return characterized by a normalized specific risk factor, , and specific variance :
. Eq. (PS2)
where the specific risk factors is assumed to be uncorrelated to all other model factors.
From these relations, all the model covariances can be derived.

In general, VaR from the primary/secondary model is a straightforward derivation given the rules for
variance and covariance of the primary and secondary risk factors. For example, if denotes a primary
position vector (i.e. the portfolio has been decomposed according to the rules specified in the Analytic VaR
section above, see page 17, and all cashflows associated with each of the primary risk factors have been
aggregated) and is a secondary position vector, then the primary and secondary return vectors are given
by
The overall correlation matrix for n-ordered primary risk vertices and m-ordered secondary risk vertices is
C=
and VaR is given, as usual, by VaR   VCV   with
Note that VaR can be expressed in terms of , , , and as (k(i) below is the unique primary index
associated to the secondary index i):
VaR = + + Eq. (PS3)
Again, the extension of the standard Monte Carlo VaR methodology to the primary/secondary risk model is
straightforward. Random draws for all the primary and secondary risk factors, and are drawn
(consistent with to the correlation matrix C specified above). The price scenarios for the primary and
secondary vertices are computed following their definition above (see Eq. PS1-2), and Eq. (2) in the
Mathematics of Monte Carlo Simulation section (see page 27). They are given by:
S pi (t )  S pi (0) exp[(  pi   pi2 / 2)t   pi pi t ]

S si (t )  S si (0) exp[  si, pk (i ) ( pk (i )   pk
2
( i ) / 2)t  ( si / 2)t  (  si, pk ( i ) pk ( i ) pk ( i )   si si ) t ]
2
where we have neglected the risk neutral drift term associated with the residual return in Eq. (PS2).
Before running the simulation, we need to determine the price history that we will use to generate historical
scenarios. Using HISTORICALVAR, you can select the beginning and ending date, otherwise known as the
"historical data window," for which price returns will be used. Additionally, you can select data according
to the season of the year. Finally, you can screen out, or filter, outlying price returns corresponding to values
present in the data that are statistical or mechanical anomalies. Historical VaR results depend on the
historical window of data used, the season selected, and the extent of anomalous-data filtering. In particular,
all things remaining the same, the historical VaR of a 400 day window can be radically different from the
VaR of a 3000 day window. Depending on the nature of the market, the historical VaR of data selected from
summer months can be radically different from data selected from winter months.
The choice of data window and season depends on the past observations considered relevant for the risk
analysis being performed. For example, in energy markets it may be important to introduce seasonality
effects. We should select the relevant months of the historical data window that best resemble the expected
future. Some issues to take into account when choosing the relevant history to be applied to the analysis are:
 Ideally we would like to have as many historical observations as possible, in order to capture a
representative ensemble of simulated futures. On the other hand, we would like our risk
estimates to change as markets change. The longer the historical window used, the more
"sticky" our VaR estimates. For example, if we use the last 10 years of data, our VaR will likely
be insensitive to the arrival of new information about price changes.
 For assets for which we do not have enough price history (e.g. emerging markets, IPOs, <),
we may need to use a proxy to determine the way that they would have fluctuated in the past
by looking at similar markets for which we have historical information.
 The data in our window period should reflect expected market conditions.
 If some of the markets have experienced or could experience a structural change (e.g. a
deregulation process for certain energy markets, devaluation of a currency, etc.) we need to
choose the window period with caution. For example, if our portfolio has foreign exchange
risk, and some of the currencies have fixed-exchange rates, but we anticipate that there are
risks that the currency could suffer a devaluation, using historical information with fixed-
exchange rate data will not help us to measure our real risks.
 If our historical window period contains market events that we do not consider plausible for
the near future (e.g. time series observed during the October 1987 market correction), our
forecasts of VaR will probably overestimate risk.
 If our historical window does not incorporate any substantial market moves (e. devaluations,
large power spikes, changes in the curvature of the yield curve, etc) that we would expect to
see from today through the horizon, the historical simulation will give zero probability weight
to these events.
HISTORICALVAR returns the entire historical profit-and-loss distribution of our portfolio sorted in any one
of three ways: by observation date, from largest loss to largest profit, or from largest profit to largest loss.
When we use HISTORICALVAR to output the entire set of profits and losses according to observation date,
we can think of a historical simulation as a way to perform historical stress tests on our portfolio, for each
date in the data window. The results, output in this way, represent a dated list of the worst losses or best
gains for the portfolio, corresponding to the historical data window selected. This is illustrated in the figure
below.
Portfolio P&L History

0.3
0.2
0.1
Portfolio P&L
-0.1
-0.2
-0.3
99
99
99
99
99
99
9
0
/9
/9
/9
/9
/9
/9
/9
/9
/0
/0
/0
4/
1/
9/
4/
2/
6/
26
20
15
29
23
17
/6
/1
20
14
10
2/
3/
6/
7/
/1
/2
11
12
3/
4/
5/
7/
8/
9/
1/
2/
3/
10
12
How can one assess the accuracy and performance of a VaR model used? To answer this question, we first
need to define what we mean by ‚accuracy.‛ By accuracy, we could mean:
 How well does the model measure a particular percentile of the profit-and-loss distribution?
 How well does the model predict the size and frequency of losses?
Backtesting results produced by the VaR model allows us to answer these questions. Many standard
backtests of VaR models compare the actual portfolio losses for a given horizon vs. the estimated VaR
numbers. In its simplest form, the backtesting procedure consists of calculating the number or percentage of
times that the actual portfolio returns fall outside the VaR estimate, and comparing that number to the
confidence level used. For example, if the confidence level were 95%, we would expect portfolio returns to
exceed the VaR numbers on about 5% of the days.
Backtesting can be as much an art as a science. It is important to incorporate rigorous statistical tests with
other visual and qualitative ones.
Quantitative tests
Statistical tests help us check whether the risk model is accurately capturing the frequency, independence or
magnitude of exceptions, which are defined as losses (gains) exceeding the VaR estimate for that period.
When we test a certain hypothesis in statistics, we can make two types of errors: ‚ type I ‛ errors occur when
we reject the model which is correct, while ‚ type II ‛ errors occur when we fail to reject (that is incorrectly
accept) the wrong model. In risk management, it can be much more costly to incur in ‚ type II ‛ errors, and
therefore we should impose a high threshold in order to accept the validity of any risk model.
The implications for the choice of the confidence level for the VaR calculations, is that the larger the
confidence level for the VaR estimates, the fewer the number of ‚exceptions‛ and, therefore, it will be more
difficult to validate the model. If we choose a 95% level, that means that we will be able to observe more
‚exception‛ points than the 99% level, and therefore we will have a better test of the model accuracy.
Many statistical tests are based on the frequency and time dynamics of exceptions. We briefly describe
several tests that are implemented in the BACKTEST and SIMBACKTEST functions.
Test of frequency of exceptions (Kupiec test).

Kupiec’s (1995) test attempts to determine whether the observed frequency of exceptions is consistent with
the frequency of expected exceptions according to the VaR model and chosen confidence interval. Under
the null hypothesis that the model is ‚correct‛, the number of exceptions follows a binomial distribution.
The probability 1 of experiencing x or more exceptions if the model is correct is given by:
 n k
Prx n, p      p 1  p 
nk
xk  N  k 
where x is the number of exceptions, p is the probability of an exception for a given confidence level, and n
is the number of trials.
If the estimated probability is above the desired ‚null‛ significance level (usually 5% - 10%), we accept the
model. If the estimated probability is below the significance level, we reject the model and conclude that it is
not correct. We can conduct this test for loss and gain exceptions to determine how well the model predicts
the frequency of losses and gains beyond VaR numbers.
Conditional coverage test of frequency and independence of exceptions (Christoffersen test).

The Kupiec test focuses only on the frequency of exceptions, and ignores the time dynamics of those
exceptions. VaR models assume that exceptions should be independently distributed over time. If
exceptions exhibited some type of ‚clustering‛, then the VaR model may fail to capture profit and loss
variability under certain conditions, which could represent a potential problem. The main contribution of
this approach is its ability to test sub-hypothesis regarding the frequency and independence of exceptions,
and the joint hypothesis that the VaR model has the right frequency of independent exceptions.
An added benefit of conducting this test is that it generates some additional useful information such as
conditional probabilities of experiencing an exception followed by another exception, and the average
number of days between exceptions.
Tests based on the entire distribution or the tail of the distribution

In addition to backtesting the traditional interval and point risk measures such as VaR and ETL, one could
also be interested in backtesting how well the model predicts the entire distribution of profits and losses.
This has an added benefit of further rejecting bad models. In this approach, forecasts at many quantiles are
compared to the realized data and the probability of observing a return below the actual is calculated. A
sample of these so-called transform probabilities (pt+1 , pt+2 , < , pt+N ) is obtained by observing the return
on the portfolio at times t+1, t+2, < , t+N, and by computing the transform probability by using the
probability distribution available at times t, t+1, t+2, < , t+N-1, respectively.
If the risk model is correct, then the time series of observed probabilities p t+1 should be independent and
identically distributed (i.i.d.) as a uniform (0,1) variable. One can then perform a graphical analysis by
simply constructing a histogram of these probabilities and checking that it looks reasonably flat.
1 This probability, also known as p-value, is the probability of getting a sample, which is even less
likely than the sample we actually have, given that the null hypothesis is true.
Distribution Tests
0.1
0.09 Analytic
0.08 Historical
0.07
0.06
0.05
0.04
0.03
0.02
0.01
0
3% 8% 13% 18% 23% 28% 33% 38% 43% 48% 53% 58% 63% 68% 73% 78% 83% 88% 93% 98%
In risk management, it is usually important that the model forecasts the tail of the distribution correctly and
not its interior, which characterizes small return disturbances. However, the approach described above can
easily be generalized to testing only the tails of the distribution see Berkowitz (2000).
This information about the distribution of pt+1 can be converted from qualitative, graphical analysis into
statistically testable hypotheses. Berkowitz (2000) describes two powerful Likelihood Ratio (LR) tests for
testing the full distribution and the tail of the distribution that are based on this approach. See the
SIMBACKTEST function description for more details on the implemantation of these tests.
Problems with statistical tests and possible solutions

The standard tests that focus on frequency and independence of exceptions have the problem that they are
weak and often fail to properly exclude the null hypothesis and therefore incur in a Type II error. Besides
the low power of the standard tests, there is another issue: the ‚true‛ null probability is not known.
Therefore when we use a test we do not know if we may be accepting a wrong model or rejecting a good
one because we may be using the wrong null probability.
However, there is a possible solution suggested by Dowd (2002-2). We can use a bootstrapping mechanism
to construct a sample of null hypothesis probabilities that can then be used as a back-testing input.
Bootstrapping involves creating alternative samples by drawing observations from our original sample of
VaR and P&Ls, and replacing the observation in the sample pool after it has been drawn. We can repeat this
process as many times as we wish, and create alternative samples from which we can estimate the p-values
for the Kupiec and Christoffersen tests. That way, we have a ‚sample of sample estimates‛ from which we
can construct confidence intervals for those parameters. This approach is implemented in the BACKTEST
function.
The bootstrapped values can provide a confidence band around the results of the statistical tests, and as
Dowd (2002-2) points out, ‚it is better to conclude that we are not confident enough about the model one
way or another, and be right, than to come to the confident conclusion that we are wrong‛.
An alternative framework for backtesting: Forecast Evaluation Approaches

A more general framework involves specifying a set of rules that will define the ‚accuracy‛ of the model
according to a risk manager, and design method of evaluating the model’s performance according to those
rules.
These type of approaches are not formal hypothesis tests, but instead involve specifying a loss function that
reflects model preferences held by an institution. This ‚loss function‛ approach can be a useful supplement
to more formal statistical methods and can provide a way to define the institution’s criteria to define an
‚accurate‛ model. For example, we can design a loss function in which the modeler can weight the penalties
to assign to exceptions given their frequency, magnitude, or time dependencies, and compare them with
expected tail loss numbers. The main benefit of this type of analysis is that it provides a measure of relative
performance that can be used for backtesting different models. For more information on these approaches,
see Dowd (2002-1).
The BACKTEST function provides a metric to compare exception sizes vs. expected tail loss and gains to
determine whether the model is accurate in predicting the size of expected losses and gains.
VaRworks EXTREMEVALUE function returns the VaR and Shortfall Risk from an input P&L distribution
tail using Extreme Value Theory (EVT), as well as error bounds and regression-fitted distribution
parameters. VaRworks provides a simple way of applying EVT to historical data by generating the required
P&L distribution tail input via the HISTORICALVAR function.
Risk managers are primarily concerned with the risk of low-probability events that could lead to
catastrophic losses. Yet traditional VaR methods tend to ignore extreme events and focus on risk measures
that accommodate the whole empirical distribution of returns. For example, it is often assumed that returns
are normally distributed, while little attention is paid to the fact that the tail of such distribution often poorly
represents the distribution of the extreme returns that are observed in the marketplace. The danger then is
that our model is prone to fail just when we need it most – with large market moves, when we can suffer
very large losses.
One response to this problem is to use stress tests and scenario analyses, i.e. to simulate the changes in the
value of our portfolio under hypothesized extreme market conditions. These methodologies are certainly
very useful. However, they are inevitably limited – one cannot explore all possible scenarios – and by
definition they give us no indication of the likelihood of the scenarios considered.
These issues are not unique to risk management, but also occur in other disciplines as well, particularly in
hydrology and structural engineering, where the failure to take proper account of extreme events can have
devastating consequences. Researchers and practitioners in these areas handle this problem by using
Extreme Value Theory – a specialist branch of statistics that derives general properties of the tail of a
distribution by making the best possible use of a limited set of realized extreme values of such distribution.
Since EVT focuses on the extreme tail of a distribution, it is especially useful when estimating VaR and
Shortfall Risk for high confidence intervals (typically higher than 95%).
Traditional approaches to VaR estimation are sometimes inadequate because they do not take proper
account of the more extreme observations in our data set. This shortcoming can be rectified by using
Extreme Value (EV) theory, which provides a tailor-made approach to the estimation of low frequency
events with limited data. The EV approach to VaR has certain advantages over traditional parametric and
non-parametric approaches to VaR.
Parametric approaches estimate VaR by fitting some distribution to a set of observed returns. However,
since most observations lie close to the center of any empirical distribution, traditional parametric
approaches tend to fit curves that accommodate the mass of central observations, rather than accommodate
the tail observations that are more important for VaR purposes. By comparison, the EV approach is
specifically designed for tail estimation.
Non-parametric or historical simulation approaches estimate VaR from an histogram of returns generated
through analysis of historical data. However, they lead to less efficient VaR estimates than EV approaches,
because they do not make optimal use of the tail observations. These approaches have also the serious
limitation that they can tell us nothing at all about VaR beyond our sample range.
EV-VaR vs. Normal VaR

1.6%
1.4%
1.2% Historical Simulation

Cumulative Probability
Results
1.0%
0.8%
0.6% VaR based on

VaR based on Extreme
Normal
0.4% Value Distribution distribution
0.2%
0.0%
-35% -30% -25% -20% -15% -10% -5% 0%
Loss
The difference EVT makes to the VaR estimates is illustrated in the Figure above, showing the tail of the
West Texas Intermediate (WTI) daily return distribution from 1983 to 1999. The dots indicate the actual
extreme return observations, the continuous line by the right vertical axis represents the tail assuming that
logarithmic returns follow a normal distribution, and the other continuous line represents the tail of an EV
distribution fitted to these data. The message from this Figure is unmistakable: EV-VaR corresponding to a
high confidence level can be much larger than normal VaR. Assuming normality can thus lead to a major
underestimate of our risk. As a rough rule of thumb, VaR corresponding to higher than 95% are best
estimated using EVT.
When estimating VaR for high confidence intervals we are probing very low probability events. EVT deals
with the frequency and magnitude of such events, which by nature always come in small data sets.
Statistical estimates are inevitably going to be very imprecise. However, EVT makes the best out of an
inherently difficult problem, and therefore marks a significant step forward in VaR estimation.
Of course, as with every other tool in risk management, the successful use of EVT requires an appreciation
of its strengths and limitations. A lot depends on judgement and experience, and EVT is not an exercise in
mechanical number crunching. If carefully used, EVT can be very useful indeed.
The key to EVT is a theorem – a cousin of the better-known central limit theorem – which provides us with
the limiting form of the distribution of excess losses beyond a certain high threshold for an arbitrary
underlying parent distribution (for a more precise mathematical statement see McNeil (1999)). Suppose we
have return observations but do not know the density function from which they are drawn. Subject to
certain relatively innocuous conditions, EVT tell us that the distribution of excess returns beyond a
threshold u, converges asymptotically to a Generalized Pareto distribution:
1  (1   x /  )1 /  )   0
G ,  ( x)    if 
1  exp(  x /  )    0
The parameter  also called the scaling parameter of the distribution, gives an indication of the standard
deviation of the distribution. The parameter , also called the shape parameter, gives an indication of the
heaviness of the tails: the larger , the heavier the tail.  is known as the tail index, and the case of most
interest in finance is when > 0, which corresponds to the fat tails commonly founded in financial return
data. x represents the excess return beyond the threshold u.
EVT tells us that the limiting distribution of extreme returns always has the same form – whatever the
distribution of the parent returns from which our extreme returns are drawn. It is important because it
allows us to estimate extreme probabilities and extreme quantiles, including VaRs, without having to make
strong assumptions about the full shape of the unknown parent distribution.
When using the EXTREMEVALUE function, the user inputs the threshold u by explicitly providing data
corresponding to the tail of interest, while the function uses regression to obtain a best fit estimate for  and
The function HISTORICALVAR can be used to obtain the required tail data. For the formulas used to
obtain VaR and Shorfall risk measures using EVT see McNeil (1999).
The existing literature on EV-VaR has tended to focus on applications to a particular risk factor (e.g., to an
individual equity index, commodity price, etc.). This is a serious limitation because risk managers are
interested not so much in different risk factors taken in isolation, but in how risk factors interact to affect the
risk of the portfolio as a whole. If we are to apply EV-VaR to portfolios, we must therefore take these
interactions into account. Unfortunately, this is easier said than done, because risk factors can interact in
complex ways, particularly under extreme market conditions.
A natural solution is to make use of multivariate extreme-value theory (M-EVT), which is concerned with
modeling the tails of multivariate distributions in a theoretically supported fashion. However, M-EVT
models are only viable in a small number of dimensions, see McNeil (1999).
Our approach is to mix the historical simulation (HS) and the single-factor EV analysis to estimate EV-VaR
on the historical series of P&L of the whole portfolio. In effect, we use the HS histogram to estimate the
parameters of our EV distribution, and then use the EV theory to project the tail out beyond our sample,
thereby allowing us to estimate extreme VaRs and the probabilities associated with them.
The VaRworks STRESSTEST function performs Stress Testing of portfolios. Like Analytic VaR, Monte Carlo
Simulation and Historical Simulation, Stress Testing provides a method of estimating the risk of a portfolio
by subjecting the portfolio to a set of potential future states of the world, which incur a set of potential
profits and losses. Unlike these VaR methods, Stress Testing absolves itself of any assumptions about these
future states by deferring the assumptions about future states to the user.
When users construct these future states, or stress scenarios, they typically draw from three main categories
of design:
1. Historical Stress Testing. This category of scenarios involves looking at recent history, such as
the 1987 equity crash, the ERM crises of 1992-3, the bond market crash of 1994, the 1994 peso
crisis, and the 1997 east Asian crisis and its aftermath. Stress Testing implemented with these
types of scenarios assumes historical events will repeat themselves. In VaRworks, users can
construct scenarios based on their knowledge of recent market events, and apply them to the
STRESSTEST function.
2. Proven Stress Testing. This category involves predefined scenarios that have proven to be
useful in practice. In the design of this type of scenario, the user determines portfolio profits
and losses incurred by specific changes to specific underlying risk factors. For example, what
profit or loss is incurred if: (i) a particular stock index falls by x standard deviations, (ii) an
exchange rate increases by y percentage points, or (iii) an entire yield curve shifts down by z
basis points? Again, these types of questions can be addressed within VaRworks via Stress
Testing scenarios applied to the STRESSTEST function.
3. Mechanical Stress Testing. This category involves automated routines that cover a prospective
set of changes to risk factors, evaluate profits and losses for each set of risk-factor changes,
then report the worst-case results (see for example, Dowd, 1998, pp. 126-129). While VaRworks
does not supply automated routines to select particular simulation results, users can use
VaRworks to create prospective scenarios, run all such scenarios via a single STRESSTEST
function simulation, then extract extreme results via the sorted output of profits and losses.
Analytic VaR and Monte Carlo Simulation obtain possible future states of the world via a variance-
covariance matrix, which implies very specific statistical assumptions about market returns. Historical
Simulation obviates the need to rely on these statistical assumptions by constructing its potential futures
states via the returns of actual, previously observed market data.
However, while Historical Simulation circumvents the problems of the previous two methods, its Achilles’
Heal is its assumption that all potential future states of the world can be inferred by looking at past states.
While philosophers and pundits may argue over the validity and scope of the old saying: ‚history repeats
itself,‛ it is sometimes the case that what lies in store for market players is best left to the imagination.
Herein is the value offered by the Stress Testing method. It allows the user to imagine any number of
scenarios that might befall a portfolio, including severe market corrections – a class of future states whose
risk: (i) cannot be captured by variance-covariance methods, and (ii) may never have been observed in the
past.
The bottom line is that Stress Testing can provide useful information about a firm’s risk exposure that VaR
methods can easily miss, particularly if VaR models focus on (statistically) normal market risks rather than
the risks associated with rare or extreme events. Such information can be fed into strategic planning, capital
allocation, hedging and other major decisions.
Stress Testing, like Monte Carlo Simulation and Historical Simulation, involves perturbing the risk factors
that underlie a portfolio. As mentioned previously, unlike these VaR methods, the perturbations of Stress
Testing are defined explicitly by the user. Each set of perturbations applied to a portfolio to induce a specific
profit or loss is referred to as a stress scenario. In About Stress Testing, we described briefly the three main
categories of scenario design. In this subsection, we describe the types of risk-factor perturbations that
comprise a scenario, and how they are applied within a Stress Test simulation to form portfolio profits and
losses.
Core and Peripheral Risk Factors

When you define a stress scenario to apply to your portfolio, you first need to select a set of underlying
assets, or risk factors, and their respective changes, or stress shocks. In selecting assets to shock, you should
distinguish between core and peripheral assets. Core, or salient, risk factors are those underlying assets
deemed by the user to be central to a Stress Test scenario. These are the risk factors whose engineered
shocks are most closely tied to the definition of the scenario. On the other hand, peripheral risk factors are
those underlying assets whose shocks are deemed less significant to the definition of the scenario.
VaRworks allows you to distinguish between core and peripheral risk factors, and it allows you to define
the shocks applicable to these risk factors in terms of standard deviations, percentage or absolute changes.
You can shock your risk factors individually or collectively, by specifying asset classes. VaRworks stress
scenarios are specified in text files that can be conveniently generated through a simple application included
with your VaRworks distribution.
Once you have identified the assets that will comprise your scenario, you will need to decide if you want the
peripheral assets to remain fixed. A common assumption is to shock only the core assets and leave the
peripheral assets unchanged. This type of stress test is often called the ‚zeroed-out‛ stress test. An
alternative, and one supported by VaRworks, is to use the variance-covariance matrix of risk factors to
estimate the correlated moves in the peripheral assets, given a shock to a core asset designated as the main
driver of the scenario. Here is how it is defined for the n-th scenario: Given a correlation x,j between a driver
asset x and a peripheral asset j (a value between –1 and +1), we define a beta coefficient
j
 x, j   x, j ,
x
where x (i) is the variance of the driver (peripheral) asset. The stress-induced return of the peripheral
asset, corresponding to scenario n, is then
r j( n )   x, j  rx( n ) ,
where rx(n) is the return of the driver corresponding to scenario n. Thus, for example, if the return of the core
asset designated the scenario driver is 5%, and the peripheral asset has a beta of 1.5 with respect to the
driver, then the return of the peripheral asset for scenario n will be 7.5% (5% x 1.5).
There are caveats to the use of the variance-covariance matrix to determine correlated changes amongst
peripheral assets. Our earlier comments contrasting Stress Testing with VaR methods are of particular note.
Additionally, and in particular, some authors argue that correlations between assets break down in the
presence of market stress, and therefore, should not be used to perform stress analyses, even amongst
peripheral assets. However, Kupiec (Kupiec 1997, pp. 24) comments:
‚While market experiences have convinced many practitioners that stress events are often
accompanied by shifts in factor correlation structures, it remains an open (and difficult)
question whether correlations undergo systematic changes in stress environments, and
whether these changes can be identified, anticipated, and incorporated effectively into
stress test exposure measures.‛
For more information about constructing scenarios, see Stress Data on Page 251.
Collective Shocks
VaRworks allows for changes in the level, slope and curvature of yield curves and commodity forward-
price curves. We refer to these collective shocks by the following names:
1. Parallel Shift. Here the same shock is applied to all points in a curve.
2. Twist. Here a single shock value is applied to both the short and long endpoints of a curve, but
with opposite signs. All points of the curve that lie between the short and long endpoints
receive shocks that are linear interpolations of the shocks received by the endpoints.
3. Curvature. Here a single shock value is applied to the short and long endpoints of a curve,
with equal sign. The point of the curve midway between the endpoints recieves the same
shock as the endpoints, but with opposite sign. All other points of the curve receive shocks
that are linear interpolations of the shocks received by these three points.
For more information about collective shocks and how to construct them within scenarios, see Stress Data
on Page 251.
Stress Testing Procedure

Once scenarios have been defined, the remainder of the Stress Testing procedure is similar to that of Monte
Carlo Simulation and Historical Simulation, except that there is no explicit dependence on a horizon time. In
other words, asset shocks carry no explicit time information. The set of scenarios is applied to the portfolio,
and the portfolio is fully revalued for each scenario, which consists of a set of returns computed from the
specified shocks, resulting in a profit or loss corresponding to each scenario. No statistical analyses are
returned regarding the set of profits and losses since this would presuppose that the set of profits and losses
are distributed according to a particular statistical assumption.
The VARDELTA function calculates VaRdelta. A natural outgrowth of the calculation of VaR is the question
‚How can VaR be improved (decreased)?‛ This question is now quite important because some regulatory
bodies have suggested that VaR should be tied to disclosure and capital adequacy, that is, the amount of
capital that ought to be required to support certain types and amounts of trading. The difficulty with
answering the question is the fact that VaR is a one-directional calculation—much information is lost in the
course of reducing a portfolio of trades into a single VaR number, and the process is not reversible. For
example, many trades might produce a given pattern of mapped cash flows; many mapped cash flow
patterns might produce a given VaR, and so on. There is really no direct means of recovering trade-related
information from the final VaR. Consequently, there is no obvious means of calculating which trades should
be done in order to improve VaR—we cannot recover cash flows from VaR numbers, nor trades from cash
flows. In sum, the VaR methodology, being unidirectional in its approach, cannot directly give us
information in the opposite direction, that is, directly tell us which trades will reduce the VaR.
The VaRdelta approach employs the unidirectional nature of VaR analysis by commencing with a list of
suggested, or candidate, trades. This list is created by enumerating all types of trades which may be
performed, in a given notional amount, or may be generated by other arbitrary means. The exact list
generation process itself is not germane to the method. However, given the list, the shredding and allocation
steps are applied to each trade in the list, one at a time. The approach then involves applying the mapped
cash flows of each candidate trade to an intermediate structure called the VaRdelta array. The VaRdelta array
may be computed quite efficiently (as described later). As a result of the calculation involving the VaRdelta
array and the mapped cash flows of the individual candidate trade, an incremental VaR change amount can
be computed, showing the amount by which VaR will change in adding the trade to the portfolio of trades.
With VaRdelta you can:
 Provide an incremental analysis of a trader’s proposed trade(s) without re-examining the
firm’s entire portfolio.
 Assign real-time, VaR-based trading limits.
 Compare the cost of putting on a hedge with its reduction in VaR.
 Rank each asset class and maturity vertex in terms of its influence in the overall VaR.
The obvious and brute-force alternative method of determining an incremental VaR change amount is to
simply add a trade to a given portfolio and repeat the entire VaR analysis for the new, augmented portfolio.
If there are many trades in the original portfolio, or many candidate trades to be analyzed, this will be a
cumbersome process.
In terms of its origins, the VaRdelta name was created as an analogue to the delta used in options pricing
theory, since a rather similar role is played. (Option price is to option delta as VaR is to VaRdelta, namely a
rate of change of each respective quantity.)
VaRdelta involves an approximation, and there are conditions under which this approximation becomes less
valid; however, in such circumstances, a full recalculation of VaR and VaRdelta will often correct the
situation. See Mathematics of VaRdelta below for more information.
The problem of dealing with VaR on a real-time basis is a serious issue for most trading institutions. With
the current state of the art, the only means of evaluating the incremental effect on VaR of a new trade is to
re-perform the entire VaR analysis on the new combined portfolio. This is because VaR is a non-linear risk
measurement that depends not only on the incremental trade, but on how this trade interacts and offsets
with the existing portfolio of trades. This joint-causality seriously limits the potential feedback to individual
traders and risk managers, who ideally should be informed on whether their proposed trades are VaR-
improving or not. It would be very useful to calculate incremental VaR for each potential trade, without
having to re-examine the institution’s entire portfolio. The VaRdelta method described later creates a
mechanism by which any new proposed trade may be quickly examined for this quantity, without further
reference to the existing portfolio held by the institution.
For example, suppose you have 250,000 trades on your books and that it correspondingly takes 15 minutes
to do a complete portfolio VaR calculation. An incremental VaR calculation would therefore take at least this
period to perform (since a before and after VaR is calculated for each incremental trade). By contrast, the
VaRdelta method can compute a very close approximation to that same incremental VaR in just a few
microseconds. This high speed allows the incremental VaR calculation to ‚keep up‛ in real-time with your
actual institutional trading activities, which may occur every few minutes (or even seconds). In fact,
VaRdelta technology enables the application of real-time, VaR-based trading limits, whereas before the
advent of VaRdelta that phrase had no practical meaning.
The elements of the VaRdelta array (returned by the VARDELTA function) represent the cash flow direction
in which VaR is increasing the fastest. For example, suppose there are only three vertices and that your
VaRdelta array is (+3, -2, +1). (It is okay to compare VaRdelta elements.) The +3 value of the first vertex
element is largest, so your exposure is ‚most sensitive‛ to additional cash flows at this vertex. To put it
another way, if you were forced to accept another marginal cash flow, its occurrence at the first vertex
would change your VaR exposure the most.
Next, the sign of the VaRdelta array elements is also important. In the example above, the first vertex
element +3 means that risk will increase by adding positive first-vertex cash flows, whereas risk will
diminish by adding second-vertex (with -2 VaRdelta value) cash flows.
There is another way to think of the VaRdelta array: it is an array representing the marginal contribution to
VaR of adding another incremental cash flow at any vertex. If a trade is mapped into a set of vertex cash
flows, each cash flow then makes a marginal contribution to VaR, so the sums represent the marginal
contribution to VaR of the trade itself.
Therefore, there are two benefits of VaRdelta: the first is the direct information provided by the VaRdelta
array, as to which cash flows will change VaR the most; the second is the evaluation of candidate trades to
determine what marginal contribution to VaR the entire proposed trade will achieve.
The key quantity to be computed in the method is the VaRdelta quantity. Suppose that
P is the existing portfolio of trades.
Ai is portfolio consisting of only the i-th candidate trade.

p = m(s(P)) is a (column) vector of cash flow amounts, where (1) m() is a mapping (allocation) function, (2) s()
is a shredding (decomposition) function, and (3) the index set of the vector is a set of vertices.
ai = m(s(Ai)) is a (column) vector of cash flow amounts for the i-th candidate trade.
Q is a variance-covariance matrix scaled by the square of the VaR probability standard deviations (typically
1.65), the indices of the matrix also being the vertex index set.
Under the definitions above, the VaR calculation of the portfolio P would be given as
v p Qp
where the prime means transpose. The analysis to this point represents the existing art. Thus applying this
approach to a new portfolio Ri = P + Ai obtained after the i-th candidate trade is added, this ‚brute-force‛
method requires a recalculation of VaR, namely
wi  ri Qri
where ri = m(s(Ri)) and the comparison to evaluate whether VaR improvement occurs is thus the quantity v –
wi: when positive, the candidate trade will improve VaR.
The incremental method, involving calculation of the intermediate VaRdelta quantity, offers a more
economical approach to evaluating VaR improvement. The mathematical basis of VaRdelta follows.
Consider the cash flow vector of a candidate trade, but scaled by the small positive quantity , so that the
VaR is now given by
wi ( )  ri( )Qri ( )
where ri = p +  ai. We now perform a Taylor series expansion of the VaR around  = 0. Thus we have
wi ( )  wi (0)   wi (0)  ai  o( 2 )
 v    (VaRdelta  ai )  o( 2 )
where  refers to the usual ‚del‛ operator, or derivative vector (where the vector index is again vertices).
From the latter equation, we see that if  is sufficiently small (and positive, since we are adding a positive
amount of the new trade to our portfolio), the improvement of VaR will be governed by the sign and
magnitude of the second term of the last equation above; the higher-order terms (o(2)) can reasonably be
ignored, since  is small. (It is of course the case that most notional amounts of proposed new trades in an
institution will be small relative to the size of their existing portfolio.)
Note that the incremental VaR, as calculated by VaRdelta, is an approximation from ignoring the higher-
order terms. Therefore, the incremental method and the brute force approach will result in slightly different
values.
Direct calculation shows that

VaRdelta  wi (0)  v  pQ / v
We note that the VaRdelta depends only upon the current portfolio, not upon choice of candidate trade. (The
sole singularity might occur only when both numerator and denominator are zero, but a zero-denominator-
only case can occur only in another error condition, when the correlation matrix is not positive definite. A
positive definite matrix Q is one such that x'Qx > 0 for all x. All the eigenvalues of a positive definite matrix
are positive.)
The incremental effect of any new trade is calculated as

[ pQ / v]  ai
which does not require recalculation of the new total portfolio; it is simply an inner product of the VaRdelta
quantity with the cash flow vector of the proposed trade. Note also that the same VaRdelta quantity works
for all candidate trades. For example, the quantity does not have to be calculated more than once for the
given portfolio P.
The following diagram shows the data flow in VaRworks, from trade files to cash flow mapping to VaRdelta
calculation (see Tutorial for a tutorial).
Flow of Data in VaRdelta Calculation
Existing CASHFLOWMAP VARDELTA VaRdelta

portfolio existing portfolio function array
Incremental
Candidate CASHFLOWMAP INCREMENTALVAR
VaR of cand-
trade(s) candidate trade(s) function
idate trade(s)
Legend
Inputs.
VaRworks functions and results.
VaRdelta is a trademark of Financial Engineering Associates, Inc. (FEA), referring to its software and
technology for computing incremental value at risk (VaR). Please acknowledge the trademark when you use
it in published materials. If you need a generic name for the VaRdelta concept, we suggest ‚DelVaR,‛
‚Gradient VaR,‛ or ‚GradVaR.‛ FEA uses ‚DelVaR‛ for such generic usage.
VaRdelta is a patented (U.S. patent 5,819,237) system and method of calculating approximate incremental
VaR. The standard method for computing incremental VaR is to calculate portfolio VaR, add a new trade to
a portfolio, and then recalculate the new portfolio VaR. A ‚before-and-after‛ comparison is then made
between the two VaR numbers: if the VaR is lowered, that new trade is risk-reducing, otherwise it is risk-
increasing. Unfortunately, this before-and-after method can be very slow with a large portfolio. The
VaRdelta method computes both VaR and the VaRdelta vector at the same time (with virtually the same
speed) as a single VaR calculation. Thereafter, the VaRdelta vector is used to evaluate the approximate
incremental VaR of each new candidate trade—but this is accomplished with great speed and without
requiring a complete VaR recalculation.
VaRworks contains full VaRdelta capability. VaRdelta technology is also incorporated into the VaRlib
programming library. To program your own VaRdelta methods, FEA also offers a technology licensing and
support program.
Under its current policies (which may change at any time) FEA intends to disclose VaRdelta technology in
both public and private forums. See the April 1996 issue of Derivatives Strategy and the May 1996 issue of
RISK for these disclosures. These disclosures do not constitute any transfer of FEA’s intellectual property
rights.
See VaRdelta and Component VaR in References for citations.

Component VaR is a method of decomposing total portfolio VaR into additive parts. It allows us to ‚slice
and dice‛ risk into its various components. This capability is also known as ‚drill down‛ because it allows
us to successively isolate the ‚hot spots‛ of our market risk exposures. Analytic Component VaR is based
upon the VaRdelta technology. (See Mathematics of VaR decomposition below.)
The definition of Component VaR is based upon two fundamental properties: 1) the Component VaR
associated with a portfolio component should be equal, to a first order of approximation, to the VaR lost or
gained when the component is deleted from, or added to, the portfolio (the ‚incremental property‛); and 2)
the sum of the Component VaR, when accumulated over all portfolio components, should equal the total
analytic VaR of the portfolio (the ‚additive property‛). The definition of Component VaR used by
VaRworks conforms to both properties. Consequently, note that Component VaR can be a negative number,
as would happen when the deletion of a component would cause VaR to increase. A negative Component
VaR means that the corresponding component is a ‚hedge‛ within the portfolio.
If the Component VaR array is expressed in percentage terms, rather than cash flow terms, the array is
termed the portfolio’s VaRbeta array. The elements of the VaRbeta array sum to one.
There are two levels of granularity in Component VaR calculations: cash flow-level granularity and trade-
level granularity.
Under cash flow-level granularity, the portfolio components are represented by aggregates of cash flows. Of
course, the finest granularity in this approach is represented by the cash flow amount located at a single
vertex. The COMPONENTVAR function provides a complete set of such numbers. That is, the
COMPONENTVAR reports Component VaR for each vertex. Due to the additive property, the sum of this
array (over all vertices) will equal the total analytic VaR. The Component VaR Array marginal sums are also
quite important. The column sums report the risk associated with each asset over all maturities and asset
classes; the row sums report the risk associated with each maturity and asset class over all assets. Series can
be further aggregated by either asset class or maturity. Note that a component VaR decomposition at the
level of risk vertices can only be accomplished when the portfolio can be accurately represented by a linear
combination of the cashflows associated to those vertices. Because of this, the COMPONENTVAR function
calculates Component VaR and VaRbeta by using the Analytic VaR methodology.
The other granularity, trade-level granularity, means that portfolios are not decomposed down to the cash
flow level, but only down to the trade level. This implies that trade-level granularity always involves
aggregations of trades, that is, sub-portfolios. The Component VaR array is not directly used for trade-level
granularity. Instead, we equivalently determine the Component VaR of a sub-portfolioby taking the inner
product of the cash flow map associated with the sub-portfolio and the VaRdelta Array associated with the
larger portfolio. In practice, this can be accomplished by using the INCREMENTALVAR or the
MARGINALVAR functions. VaR decomposition performed by these two functions uses the the Analytic
VaR methodology.
VaR decomposition along trade-level granularity, however, does not require use of the Analytic VaR
approximation. The function COMPONENTVAR2, used in conjunction with the VARCARLO2 and
HISTORICALVAR functions, generates a VaR decomposition along subportfolios consistent with Monte
Carlo and Historical methodologies.
The decomposition of VaR employed by INCREMENTALVAR, MARGINALVAR, COMPONENTVAR and

COMPONENTVAR2 functions is based on a simple property of any homogeneous function of several
variables: if f(x) is a function of N variables, homogeneous of degree k, i. e. if f(x)= kf(x ) for any number ,
and any value of the N dimensional vector x, then f(x)=k n=1,N (xn f/xn). This result, known as Euler’s
theorem, is the basis for Component VaR decomposition when we realize that, under the cashflow
decomposition employed by the Analytic VaR methodology, VaR is a homogeneous function of degree one
in the position vector giving the exposures of the portfolio to each of the cashflow vertices. We can then
write:
VaR(p)= n=1,N (pn VaR/pn) CVAR (1)
where, see Mathematics of VaRdelta, VaR/pn=VaRdeltan.
In other words, the inner product of a portfolio’s VaRdelta vector with its own cash flow map is equal to its
VaR. Since, by definition, VaR(p)= n=1,N ComponentVaRn we can identify
Component VaR for a given risk vertex with the product between VaRdelta and the portfolio cashflow
associated with that vertex. This demonstrates the additive property. The incremental property of
Component VaR is already established by the VaRdelta quantity itself (see Mathematics of VaRdelta), or
could be simply verified by performing a first order Taylor expansion of Var(p), i.e. Var(p - pn)= Var(p)- pn
VaR/pn + <, where pn represents the exposures of the portfolio corresponding to the nth cashflow,
assumed here to be small. From the formula we see that ComponentVaR(n) is equal, to a first order
approximation, to the VaR change (a decrease if pn VaR/pn is positive, an increase if it is negative) when
the exposure to the nth cashflow is removed.
In an analogous way, if we are interested in trade-level granularity, we do not need to use a cashflow
decomposition approximation to derive the decomposition formula CVAR (1). Let’s assume that the
portfolio is decomposed into individual trades (the argument applies as well for a decomposition in terms
of disjoint subportfolios). We can then interpret pn in CVAR (1) as the notional amount corresponding to
trade n. The MtM of trade n and any P&L associated with it is proportional to pn, hence CVAR (1) applies,
and the calculation of Component Var to trade-level granularity can be achieved by computing the
sensitivity of the VaR estimate to a change in the notional amount of the nth trade. For more details on how
this is done in the context of a Monte Carlo simulation, see page 29.
Extension to decomposition of the PaR measure to trade level granularity is straightforward, and can be
achieved by applying Eq. CVaR.1 to Eq. PaR.1, i.e.:
PaR =  (p PaR/p) =  ComponentPaR CVAR (2)

Where the sum over  denotes some over the trades (following the notation on page 25), and
ComponentPaR= ( p i=1,h_max fi Q p’i )/PaR CVAR (3)
with p’ i =  fi p .
Extension to the decomposition of the PFE measure to trade level granularity, is also simple.
The following diagram shows the flow of data in VaRworks: from trade files, to cash flow mapping, to the
analytic Component VaR calculation.
Flow of Data in VaRdelta Calculation
CASHFLOWMAP
Portfolio function
VARDELTA VaRdelta
function array
Cash flow map
array
COMPONENTVAR Component
function VaR array
Legend
Inputs.
See VaRdelta and Component VaR in References for citations.
In this example, we generate the cash flows of a commodity forward contract and show where all of the
potential exposures originate. Use this same systematic approach to determine the exposures of any trade.
See Analytic VaR with the Implied Volatility Risk section on page 57 for the description of exposures to
changes in the implied volatility.
The most general formula for the present value of a simple commodity forward contract, expressed in the
home currency is
P  u   X 1  F  exp( rF T1 )  X 2  K  exp( rK T2 )
where
u = the amount (num_contracts * contract_size), which is positive (negative) for a long (short) position.
X1 = the spot exchange rate, converting the local (or base) currency of F into the home currency.
F = the forward price of the commodity at T1.
rF = the interest rate at tenor T1, corresponding to the local (base) currency, that is, an interest rate of this
(base) market (Note: this is related to the rebase currency of MakeVC, which represents the currency from
which the commodity’s market factor movements (volatilities and correlations) are measured. The rF
therefore corresponds to an exposure that is data set dependent.)
T1 = a tenor corresponding to the time of delivery of the commodity.

X2 = the spot exchange rate, converting the accounting currency of K into the home currency.
K = the delivery price, in accounting currency terms.
rK = the interest rate at tenor T2, corresponding to the accounting currency, that is, an interest rate of the
market in which the contract is settled.
T2 = a tenor corresponding to the time of settlement of the contract.
Finding delta exposures is a matter of (i) taking derivatives of P, and (ii) knowing how the trade is hedged.
(i) determines the asset and amount of the cash flow vertex, and usually determines (ii), the tenor. In the
case of options, (ii)—ultimately the choice of tenor—needs to be thought through more carefully. It often
requires an understanding of the underlying pricing model and, in particular, the model’s limitations.
So, with an explicit linear pricing formula in hand, it’s easy to take the derivatives of all stochastic variables
F, rF, rK, X1, and X2; keeping in mind that you want to take the derivative of the ‚price-equivalent‛ form of
the variable. In other words, for interest rates rF and rK, you take the derivative with respect to exp(-rT)
instead of r. (It’s a bond that has value, not r.)
So, the commodity exposure on a commodity vertex, written as a cash flow amount, is obtained by taking
the derivative of P with respect to F, multiplying by F, then taking the value of this product at mark-to-
market
P
 F  u  X 1  F  exp( rF T ) at MTM and at T1
F
where we’re implying that this is a mark-to-market value.
Similarly, the interest-rate (market) exposures are
P
 exp( rF T1 )  u  X 1  F  exp( rF T1 ) at MTM and at T1
 exp( rF T1 )
and
P
 exp( rK T2 )  u  X 2  K  exp( rK T2 ) at MTM and at T2
 exp( rK T2 )
Depending on T1 and T2, these are money market (LIBOR) or swap exposures.
The implied foreign exchange exposures are
P
 X 1  u  X 1  F  exp( rF T1 ) at MTM and at spot
X 1
and
P
 X 2  u  X 2  K  exp( rK T2 ) at MTM and at T2
X 2
Note that:
1. The above are all present valued, in home currency terms.
2. The commodity monetary value is the same amount as its interest-rate exposure; however, the
interest-rate volatility is typically much smaller than the commodity volatility, so the rF
contribution to VaR is usually much smaller than that of F.
3. The interest-rate exposures have the same amount as their implied foreign exchange
exposures.
4. The sum of the interest-rate or foreign exchange exposures gives back the value P.
5. If any of F, rF, rK, X1, and X2 is a constant w. r. t. the home currency, then omit it as an exposure.
These rules of thumb should hold for all trades, so they’re a good test to see if you’ve got things working
correctly.
Also, one practical problem with extracting interest-rate deltas from FEA pricing models is that you can
calculate a rho, but not an exp(-rT). The workaround is to realize that a delta w. r. t. a spot (or forward)
price, or a delta w. r. t. the strike price (that is, the counter-delta), is equivalent to a derivative w. r. t. exp(-
rT). So, rule 1 can be exploited to get an interest-rate cash flow amount for a spot or forward price.
Also (rule 5), it’s usually true that
P P

K  exp( rK T )
Pricing commodity futures, options, swaps, swaptions, and swing contracts usually requires the underlying
commodity’s price curve and volatility term structure. If you are using RiskMetrics datasets then you may
be unable to price commodity instruments because of inadequate information—RiskMetrics datasets contain
either forward curves or spot prices, but not both, and for only a few commodities. If a significant part of
your portfolio contains commodities, we recommend you create your own volatility-correlation datasets
from historical price data (you can use MakeVC to create such datasets).
When pricing commodity instruments, VaRworks determines the price and volatility information needed
for valuation: a spot maturity, forward curve, or both will be required. If VaRworks cannot find a required
maturity in the volatility-correlation dataset, then prices and vols are estimated using the method described
in the table below.
Interpolation and Extrapolation Methods for Commodity Curves
Instrument requires
You supply Spot Forward curve
Spot only No estimation needed. Flat-curve extrapolation: set the

entire forward curve equal to the
spot observation.
Warning This estimation
method is unreliable, particularly
in volatile markets; you should
always supply a forward curve
when required.
Forward curve Flat-curve extrapolation: set the Use linear interpolation between
only spot observation equal to the available maturities. Use flat-

youngest available forward curve extrapolation for other
maturity. maturities.
Interpolation is estimation between known points. Extrapolation is estimation by projection beyond known points.
VaRworks 5.1 supports two approaches to risk for commodity prices. The traditional treatment, and the
only one supported by previous versions of VaRworks, assumes that the source of risk associated to
commodity prices is really linked to constant maturity prices. These are prices corresponding to possibly
artificial contracts expiring not on a fixed date, but on a date which is a fixed time interval from the effective
date of the calculation: as the effective date changes day after day, the expiration date also change, while
keeping the time to maturity constant, hence the Constant Maturity label. For more details on Constant
Maturity Commodity prices see the MakeVC User’s Guide. The Constant Maturity approach is particularly
relevant for commodity prices that do not exhibit strong seasonal patterns, i.e. metals.
While constant maturity prices are a very useful construct when the volatility/correlation dataset is
generated, their drawback is that often they do not correspond to tradable prices, and hence risk
decomposition along the constant maturity price dimension does not provide hedging recommendations
which can be directly implemented.
An alternative approach, preferred by some practioners, is to directly use market Futures prices (we will
refer to them as Fixed Expiration prices in the following) as the source of risk. This approach complicates the
volatility/correlation dataset generation, since the time series of daily prices that can be used to create the
dataset are much shorter than when constant maturity prices are used. For instance if N monthly contract
prices are available every day, the daily time series corresponding to the farthest expiration date will have
about 20 data points available. However, since volatility/correlation datasets are often generated using an
exponential moving average with a fast decay factor (a typical value of =0.94 corresponds to a halving of
the weight after about 11 days), this lack of data is not necessarily a serious issue.
The advantage of this second approach is that risk decomposition can be easily interpreted in terms of
exposures to tradable assets, and that the risk associated with the price of any futures contract is estimated
by using that futures contract price history only, without any mixing from adjacent futures contracts.
To select the Constant Maturity approach, the maturity corresponding to commodity vertices entering the
dataset must be specified as an integer plus a time unit, see Vertex Names on page 365. To select the Fixed
Expiration price approach the maturity must be specified as a date, formatted according to the
DATEORDER header. Commodity spot prices can be specified by using a maturity equal to zero, or a date
equal to the effective date associated with the dataset, as specified through the LOADMARKETDATA
function.
Note that the two approaches can be mixed within the same dataset, but not within the same commodity,
i.e. all the vertices of a commodity must be either constant maturity or fixed expiration, but, for instance,
GAS can have fixed expiration vertices and GOLD constant maturity vertices.
In this section we provide the motivation for why, depending on the composition of a user’s portfolio, it is
important to incorporate the risk associated to market changes of the implied volatility (IV) input when
calculating VaR. We also give details of the stochastic volatility model used in VaRworks, and on how the
volatility/correlation dataset should be generated to enable this functionality.
In general, out-of-money, close to expiry options are very sensitive to changes in the implied volatility used
in their valuation. If a portfolio contains such instruments, it seems important to take into account the risk
connected with the stochastic changes of the implied volatility input when valuing these options. In this
introduction we quantify more precisely the level of risk associated with the implied volatility risk factors,
its importance compared to other relevant risk factors, and the importance of using Monte Carlo vs.
Analytic methodologies in this context.
We found that useful insights could be gained by performing a simple analysis of the VaR of a single option
on the S&P500, for the distinct cases of out-the-money, at-the-money, and in-the-money options, and by
comparing the VaR number obtained with and without the risk associated to the implied volatility input.
The effective date for our analysis was set to 9/1/2005. We set the horizon time to one day, and the
confidence level to 95%. We considered options with 1 month (9/30/2005), 3 months (12/1/2005), and 6
months (3/1/2006) maturities. The price of the S&P500 index was around $1222 on 9/1/2005. The implied
volatility used to value these option was set to 12%. The implied volatility risk was derived by using four
months of data from May 2, 2005 to September 1, 2005, and including risk vertices associated to strikes equal
to 1000, 1100, 1150, 1200, 1250, 1300, and 1400, and option maturities equal to 9/17/2005, 12/17/2005,
3/18/2006, and 6/17/2006.
For the out-the-money case we considered the case of calls with strike equal to $1272.
Monte Carlo VaR Comparison for Out-of-Money Option

(S=1222, K=1272)
4.5 4.38 4.37
3.5
3.21
3 2.92
VaR in millions
VaR without IV risk

2.5
VaR with IV risk
1.5 1.32
1.1
1
0.5
0
1 3 6
maturity in months
Analytic VaR Comparison for Out-of-Money Option

(S=1222, K=1272)
4.44 4.42
4.5
3.5 3.33
3
3
VaR in millions
VaR without IV risk

2.5
VaR with IV risk
1.49
1.5
1.15
0.5
0
1 3 6
maturity in months
We see that the effect of taking into account IV risk is considerable and should not be neglected for out-of-
money close to expiry options, with consistent results holding for both Monte Carlo and Analytic VaR
calculation. Also notice that VaR decreases when IV risk is included in the analysis, consistent with the often
observed negative correlation between the implied volatility level and the S&P price level for out-the-money
option.
The IV risk is small in comparison with the risk connected with changes in the underlying for at-the-money
options. Below are the results for at-the-money S&P500 portfolio when the strike is set to $1222 and all other
parameters are the same as above.
Monte Carlo VaR Comparison for At-the-Money Option
(S=K=1222)
7
6.44
6.18
6.02
6 5.83
5.55
5.42
5
VaR in millions
4
VaR without IV risk
VaR with IV risk
3
0
1 3 6
maturity in months
Analytic VaR Comparison for At-the-Money Option

(S=K=1222)
7
6.48
6.27
6.13
5.95
6 5.8 5.71
5
VaR in millions
4
VaR without IV risk
VaR with IV risk
3
0
1 3 6
maturity in months
Finally, for in-the-money options, the effect of taking into account the implied volatility risk factor is
negligible.
Note that the inclusion of implied volatilities as risk factors can lead to an even bigger change in VaR (of
order of 50%) if the options are very close to expiry (less than two weeks to maturity). In that case, the
change in VaR caused by the implied volatility changes should not be discarded even for at-the-money
options.
To understand how to incorporate the implied volatility risk factors, let’s recall that in the Monte Carlo
simulation all the underlying prices are stochastic and follow geometric Brownian motion, see equation (1)
in the Monte Carlo Simulations section. To incorporate the IV risk in the Monte Carlo VaR calculation, we
extend the Monte Carlo simulations to the horizon time by assuming that all IV vertices are stochastic and
follow driftless geometric Brownian motion
d j (t )
  j dW j (t ),
 j (t )
where j is the volatility,  j is the volatility of volatility, and Wj (t) is the standard Brownian motion with
zero mean and variance t. Integrating the given stochastic differential equation by applying Ito’s formula,
we have
 j (t )   j (0) exp[  2j t / 2   j j t ],
where j is a random number drawn from the standard normal distribution function. Random numbers j
are correlated with random numbers  j from the equation (2) in the Monte Carlo Simulations section and
with each other. These correlations are imposed by the Cholesky matrix obtained from the Cholesky
decomposition of the correlation matrix specified in the dataset
   
   AT  uncorr .
  uncorr 
Notice that the particular choice of the IV vertices used as risk factors is left to the user and depends on
option data availability that might be different for various underlyings. In general, for each option
underlying (equity, currency, or commodity), the IV risk factors form a table of volatilities with respect to
the values of strikes and maturities specified in the dataset, see page 58 for how to specify this table. This
volatility table is sometimes called a volatility surface.
It is important to realize that the implied volatilities (and their volatilities) that are specified in the volatility
file (j(0) and  j in the formula above), are distinct from the implied volatility number specified in an
option record. The latter, when specified, is used to compute the mark-to-market of a specific option, and
can be set to reproduce an observed market price for that option. The former values are used instead to
compute the risk for any option that supports IV as risk factors on the same underlying, in the following
way. First we find the volatility value on the volatility surface corresponding to the maturity and strike of
the option under consideration (linear interpolation in strike and maturity is used if necessary). If the option
record contains a volatility input, the delta-volatility , equal to the ratio of this volatility input and the
interpolated volatility from the volatility surface, is computed. Otherwise,  is set to one. Then, for each
simulation run, we simulate a new volatility surface (using the equation above), and compute a new
volatility value on the surface for the maturity and strike of the option. We finally multiply this new
volatility value by the initially computed  and use this derived volatility in the valuation of the option at
the VaR horizon.
The advantage of this approach is that it gives flexibility to the user to control the mark-to-market value of
all the options in the portfolio, even if a small number of risk factors are used to describe the implied
volatility risk.
To include implied volatility as a risk factor in the calculation of Analytic VaR, we add the vega sensitivities
of the options in the portfolio to the list of portfolio cashflows used to compute VaR. For each option in the
portfolio, we compute its sensitivities to the change of volatilities on the IV surface and construct the
cashflows as
P
  i   ,
 i
where P is the price of the option,  i is the volatility of one of the IV vertices, and  is the delta-volatility
defined in the section above on Monte Carlo VaR.
Notice that in general, because of linear interpolation, there will be one to four non-zero IV sensitivities for
each option.
To include the implied volatility risk in the calculation of Historical VaR, the history file should contain the
time series of historical implied volatility of the IV risk factors in addition to the time series of historical
prices
{ i ( K j , Tk , tl ) | t0  ...  tl  ...  t N  0},
where i=1,2,...,n; n equals the total number of underlyings in the portfolio with IV risk, j enumerates strikes,
and k enumerates maturities for the ith underlying, respectively.
Let h be the time horizon expressed as an integral number of days. The ‚historically simulated‛ volatility
surfaces are computed by the following formula:
 i ( K j , Tk , tl )
 i ( K j , Tk , tl )*   i ( K j , Tk ,0)  .
 i ( K j , Tk , tl  h)
From the simulated implied volatility surface, the implied volatility used for option valuation is then
obtained in the same way as described in the Monte Carlo VaR with Implied Volatility Risk section above,
by adding the precomputed  value.
Note that for fixed income instruments, which support stochastic implied volatility, the implied volatility
will also depend on the term of the underlying interest rate, but analogous formulas apply.
For more details on the Historical VaR calculations, see the Historical Simulation section.
Stress testing of the implied volatility inputs has also been enabled in VaRworks. One can apply the usual
VaRworks shock types (e.g. PERCENT, ABSOLUTE, and SDEV), as well as the shock models (PARALLEL,
TWIST and CURVATURE), see STRESSDATA on page 251. If the strike entry in the implied volatility name
is omitted, all vertices for different strikes but for the specified name and maturity will be included in the
stress test. Analogously, if the maturity entry is omitted, all IV vertices for different maturities but with the
specified name and strike will be included. If both strike and maturity in the IV vertex name are omitted, all
IV vertices with the specified name will be included in the stress test. For specific usage examples see
STRESSDATA on page 251.
Note that one can use the TWIST or CURVATURE shock models to modify the volatility surface along either
one of the strike or maturity directions.
In the case of stress testing of implied volatility risk for the fixed income instruments supporting the
methodology, the supported shocks are the usual VaRworks shock types (e.g. PERCENT, ABSOLUTE, and
SDEV), and the PARALLEL shock model (for instance, if the moneyness entry is omitted, all
IV vertices with the specified name, term and maturity will be shocked.)
In order to include the risk associated to implied volatilities into the VaR calculation the dataset must
include information about implied volatility risk factors: a) the asset file must specify the IV risk factors for
the desired underlyings, see Assets on page 103; b) volatility and correlation files must specify the level of
the volatility risk factors, their volatilities, and corresponding correlations; c) the history file should include
historical time series of the IV factors, if Historical VaR is to be computed.
For fixed income instruments, which support stochastic implied volatility, the implied volatility should be
obtained from the market data for caplets/caps, if the term of the underlying rate is less than 1 year;
otherwise, the implied volatility should be obtained from the market data for swaptions. Datasets
supporting this functionality can be generated with MakeVC 2.8. The implied volatility should be specified
as a function of moneyness, expiry, and term of the underlying rate. The moneyness is defined as the ratio of
the strike and the forward rate at expiry. Note that for other asset classes, i.e. equities, currencies and
commodities, the implied volatility should be specified as the function of strike and expiry, see Assets on
page 103 for more detail on the order and format of parameters.
Note that the dataset must include data for at least one IV vertex per underlying, in order for a minimal
assessment of IV risk to be accomplished.
Finally, notice that a limited set of instruments support calculation of implied volatility risk, currently
EQUITYOPTION, EQUITYOPTION2, OPTION, and STRIPOPT for equity, FX, and commodity underliers,
CAPFLOOR2, BARRIERCAP2, RANGEACCRUAL, AVERAGECAP, and SWAPTION2 for fixed income
instruments. The *VOLMODEL header should be set to SV (Stochastic Volatility) to enable this feature.
RiskMetrics is managed by The RiskMetrics Group, previously the J.P. Morgan Risk Management Products
Department.
RiskMetrics is a methodology developed to quantify risk. This risk quantification, or VaR, measures
maximum estimated losses in market value of a given position that can be expected to be incurred until the
position can be neutralized or is reassessed. In RiskMetrics, risk is your maximum loss, given a time horizon
and confidence level. RiskMetrics uses a confidence level of 95% and horizons of one day (24 hours) and one
month (25 days).
The RiskMetrics products provided by The RiskMetrics Group are the VaR methodology and daily updates
of price and yield volatilities and correlations for one-day and one-month horizons. This data covers
government bond, money market, swap, foreign exchange, equity index, and commodity instruments.
The RiskMetrics methodology is documented in Introduction to RiskMetrics, RiskMetrics—Technical Document,

and RiskMetrics Monitor, all available at http://www.riskmetrics.com/
Updated RiskMetrics datasets are published every U.S. business day at http://www.riskmetrics.com/
This section describes the effect of the Euro on instrument specification. Certain trade fields have been
added or modified to accommodate the specific needs of instruments with European Monetary Union
(EMU) dependencies.
While the in-Euro currencies ceased to exist January 1, 2002, the behavior described in the following section
will be maintained in this release. This allows the continued use of historical datasets.
This includes all instruments with ccy, credit_rating, and amount/principal fields. The affected trades are
BARRIERCAP, BOND, BONDFORWARD, BONDFUTURE, BONDFUTOPT, BONDOPTION, CAPFLOOR,
CASHFLOW, FRA, FRN, MONEYMARKET, SWAP, SWAPOPTION, and REPO.
If you use Euro-compliant RiskMetrics datasets and the ccy field contains the Euro or an in-Euro currency
code, it is possible to specify an in-Euro currency code within the credit_rating field, in addition to the usual
credit_rating choices. As always, the ccy field specifies the currency in which the amount/principal is
denominated. For example, a long position involving a zero-coupon bond issued by the German
government, with a face value of 10 million Euros and a maturity of 12 January 2008, may be entered
*TYPE=BOND
EUR,DEM,10,1/12/2008
Another example: If the same bond had a face value of 20 million French francs, you would enter
*TYPE=BOND
FRF,DEM,20,1/12/2008
If the credit_rating field does not denote the Government sector ‚Z‛ (See Codes, on page 365, for a list of
credit ratings), and the ccy field specifies an in-Euro currency code, the corresponding credit curve for the
Euro currency code will be used, and the volatility/correlation dataset should contain such data. For
example
*TYPE=BOND
FRF,AAA,20,1/12/2008
denotes a AAA bond with a face value of 20 million French francs. Proper valuation and mapping of this
bond requires specification of the Euro AAA yield curve.
All trades involving an underlying equity (EQUITY, EQUITYOPTION, and EQUITYAPO), allow for the
specification of an equity denomination currency ccy, in addition to the currency code underlying_ccy that
defines the index.
If you use Euro-compliant RiskMetrics datasets, the ccy and underlying_ccy fields may contain any
combination of Euro or an in-Euro currency codes. Otherwise, the two fields must be identical. For example,
a long position involving the (German) DAX, with a market value of 5 million French francs and a beta of
one, may be entered
*TYPE=EQUITY
FRF,DEM,5,1
Another example: A long position involving the (Japanese) Nikkei 225, with a market value of 2500 million
Japanese yen and a beta of one, must be entered
*TYPE=EQUITY
JPY,JPY,2500,1
Note that the ccy field does not imply a quanto equity trade.
We recommend that you use Euro-compliant RiskMetrics datasets. If you use the ‚old‛ pre-Euro
RiskMetrics datasets, be aware of the following:
 ‚Pseudo‛ exposures in your cash flow maps may appear, for example, DEM foreign exchange
(the DEM.XS vertex) when your home currency is ESP. However, these won’t contribute to
VaR. For example, the Component VaR map will show a zero component VaR for DEM.XS.
 Euro exposure (EUR.XS) may be distributed among in-Euro XS vertices.
 VARCARLO may invoke its fallback method for dealing with bad correlation matrices. This
will happen if its correlation matrix includes correlations involving the in-Euro XS vertices,
which are all identical. (The simple remedy is to use the new-format RiskMetrics datasets.)
This section discusses at a high level how VaRworks organizes data from files into collections.
VaRworks takes several types of data files.
Market Data (sometimes collectively called the dataset)

 Volatility file
 Correlation file
 Asset file
 Historical files
 Yield and Price curve file
 Exchange rate file
 Smile file
Portfolio Data
 Portfolio file
 Trade file(s)
Other files
 Stress-test scenario files
 Candidate trade files
VaRworks also outputs two types of files.
Output files
 Error log file
 Distribution data files
The data type of a file is specified with the TYPE header.
A volatility file contains time series statistics. Each record (a vertex) contains a series name, price or yield,
exponential decay factor, price volatility, and yield volatility (if applicable) for a particular asset. You may
use RiskMetrics volatility files or create your own with MakeVC. See Volatility for more information.
A correlation file contains correlations for the series (vertices) listed in the volatility file. Each record
contains two series names (vertices) and the correlation. You may use RiskMetrics correlation files or create
your own with MakeVC. See Correlations for more information.
An asset file contains information about user-defined currency, commodity, equity, and implied volatilities
as risk factors, and is only required if you are using MakeVC or custom volatility and correlation files. See
Asset files for more information.
A historical file contains historical time series of constant-maturity vertices, which are needed for historical
simulation. The record layout of time series is the same as output by MakeVC. Thus, you can use MakeVC
to generate historical time series to be used by VaRworks. When calculating historical VaR, you may input a
single time-series file in this format. Alternatively, you can construct a file, each of whose records is a file
path to a time-series file. This later type of file allows you to concatenate time-series files within one
historical simulation. See Historical Data for more information.
This file contains commodity market prices and market interest rates that, if specified, superseed the values
specified in the Volatility file. See Yield and Price Curves on page 274 for more information.
This file contains foreign exchange rates that, if specified, superseed the data specified in the Volatility file.
See Exchange Rates on page 207 for more information.
This file contains volatility smile data, currently supported by a number of fixed income instruments. See
Smile Data on page 240 for additional information.
A portfolio file specifies a list of individual trade files. Each record in a portfolio file contains a path to a
different trade file. Portfolio files make it convenient to analyze subsets of your entire portfolio or to access
trades that reside on different network volumes. See Portfolios for more information.
Trade files contain trade information. Each record in a trade file contains the terms of a single financial
instrument specified in sufficient detail that all future cash flows can be generated at runtime. Different
types of financial instruments can be stored in different files or in the same file, separated by a TYPE header.
See Record Layouts for a list of supported financial instruments.
You need to create stress-test scenario files if you plan to perform stress testing on your portfolio. This type
of file allows you to define the various scenarios. See Stress Data for further details.
If you want to calculate the incremental effects on VaR of new, candidate trades using VaRdelta then you
also need trade file(s) containing the candidate trades. Candidate trade files have the same format as the
trade files that make up the original portfolio (described above).
The error log file contains diagnostic information VaRworks generates while running. See Error Log for
more information.
Distribution data files are generated by the VaR calculation functions VARCARLO2, HISTORICALVAR,
and PORTVARANL. These files contain information about P&L distributions and are used by the
VARCOMPARE function. See Distribution Data for further details.
Some market data files have an implicit base currency that exchange rates and commodity prices (asset
classes XS and C) are expressed in. If the user does not specify the base currency, it is assumed to be USD. If
you are producing market data for use with VaRworks, and you do not wish to express these prices in USD,
you can use a different base currency in these market data files. FEA calls this rebasing the market data.
Market data rebasing is one feature that is provided by the default output format mode of MakeVC: see the
separate MakeVC documentation for more information about rebasing.
The files that contain rebased data are Volatility, Correlation, Asset, and Exchange Rate files. If the data is
rebased, the files must contain the REBASE_CCY header specifying the base currency used.
If rebased market data is used, all the instances in this manual where USD is used in the context of a
currency denominating foreign exchange rates or commodity prices should be interpreted to mean that USD
is representing the rebasing currency for the market data.
This tutorial introduces you to VaRworks and assumes you have installed VaRworks in the default
installation directory \fea\varworks. You will calculate cash flow maps, VaR, VaRdelta, and Component
VaR using the data in the sample files in the installation directory.
All input files are text files consisting of lines of text. Each line is a data record; each record is made up of one
or more fields. The sample files use the following regional settings: fields are separated by commas, dates are
given in month-day-year order, and the dot character ‘.’ is the decimal separator in numbers. When you
input your own trades you can change these settings using the FIELDDELIM, DATEORDER, and
DECIMALSEP headers described in Headers.
When you specify an input file name, VaRworks always searches the current directory for that file unless you
specify a complete file path, which explicitly describes the location of the file. To change the current
directory in Microsoft Excel choose Open (File menu), change to the \fea\varworks directory (or wherever
VaRworks is installed), and then click Cancel.
The current directory is the directory in which your documents appear when you use either the Open or
Save As command (File menu). If you select another directory when opening or saving a document, that
location becomes the current directory. You can specify a current directory if you open or save documents
by using a particular directory.
Change the current directory in Microsoft Excel

1. Choose Open (File menu).
2. Change to c:\fea\varworks (or wherever your files are located).
3. Click Cancel.
Automatically set the current directory every time you start Microsoft Excel
1. Choose Options (Tools menu).
Excel displays the Options dialog box.
2. Click the General tab.
3. In the Default File Location box enter c:\fea\varworks (or wherever your files are located).
4. Click OK.
Alternatively, you may include a path with the file name. A Windows file name consists of a path of zero or
more directory names separated by backslashes, followed by the actual file name:
Drive:\DirName\DirName\...\DirName\FileName
If the path begins with a backslash, it starts in the root directory; otherwise, it starts in the current directory.
Drive is a disk drive identifier (A-Z). If Drive and the colon are omitted, the default drive is used.
\DirName\...\DirName is the root directory and subdirectory path to the file name. For example, if the
current drive and directory are c:\fea\varworks then the following three paths are equivalent:
c:\fea\varworks\bond.txt
\fea\varworks\bond.txt
bond.txt
The following diagram shows the flow of calculations in VaRworks, from trade files to cash flow mapping,
VaR, VaRdelta, Component VaR, and Incremental VaR.
Flow of Data in VaRworks
Trades Monte Carlo

VARCARLO
Bonds VaR and mark-
Volatilities function
Interest Rates to-market
FX
Equities Correlations
Commodities Portfolio CASHFLOWMAP Errors (if any)
Options logged to
function
... varworks.log
Portfolio cash Candidate

flow map trade(s) portfolio
(in vertices) file
VARANLU VARANL VARDELTA CASHFLOWMAP

function function function function
Candidate
Undiversified Diversified
VaRdelta array trade(s) cash
analytic VaR analytic VaR flow map
COMPONENTVAR INCREMENTALVAR
function function
Incremental
Component VaR
Legend analytic VaR
array
of candidate trade(s)
Inputs
HS VaR, Expected
Historical Data File Shortfall, and other
Statistics
HISTORICALVAR
Portfolio and General function
VaR Parameters Sorted P&L array
(date, ascending,
descending)
Extreme Value VaR, EXTREMEVALUE

EV Expected function
Shortfall, GDP
parameters
To calculate VaR, VaRdelta, Component VaR, and Incremental VaR for the sample portfolio, perform the
following steps:
1. Install VaRworks.
2. Open the VaRworks template.
3. Load the VaRworks add-in.
4. Activate the Inputs worksheet.
5. Specify the Market and Portfolio files.
6. Specify the General VaR inputs.
7. Specify the Monte Carlo inputs.
8. Specify the Historical Simulation Inputs.
9. Specify the Extreme Value Theory Inputs.
10. Specify Stress Testing inputs.
11. Specify advanced user inputs (optional).
12. Calculate the VaRworks template.
13. Examine the results.
14. Examine the error log.
15. Archive the results.
Warning When installing over a previous installation of VaRworks, files with the same name as files in the
distribution will be overwritten, and previously installed optional components may be removed. FEA
suggests that prior installations be backed up before a new version is installed over them. Files with names
different than the distribution files are not changed.
Windows NT/2000 Users The installation procedure requires you to be a member of the Administrators
group or have permission to change the registry. See your system administrator.
1. Close all open applications.

2. Insert the CD-ROM.
3. If auto-insert notification is enabled then the program installation will start automatically.
Otherwise click the Start button, click Run, type d:\setup (where ‚d‛ is the letter of your CD-
ROM drive), and then press ENTER.
4. Follow the Setup instructions on the screen.
5. If you are using Windows NT/2000 then reboot after installation.
6. Contact FEA for a license key to enable VaRworks.
1. Close all open applications.

2. Copy the file to a temporary directory.
3. In Windows Explorer, double-click the file.
4. Click Unzip to decompress the file. The Setup program will start automatically.
5. Follow the Setup instructions on the screen.
6. If you are using Windows NT/2000 then reboot after installation.
7. Contact FEA for a license key to enable VaRworks.
The VaRworks template is a Excel 95 workbook containing sample VaRworks worksheet function calls and
results in a logical layout.
Microsoft Excel 97/2000 Users The VaRworks template contains a Visual Basic macro module. If you have
enabled Macro virus protection (Tools|Options|General), you will receive a warning about macro viruses.
Click Enable Macros to use the VaRworks Macros. If you click Disable Macros you will not be able to use the
VaRworks Macros and buttons (but VaRworks will still run). You may also receive a warning telling you
that Visual Basic macro modules are now edited in the Visual Basic Editor, not the workbook. Click OK.
A convenient way to access FEA templates and automatically load FEA Add-Ins is to use the FEA menu on
the Excel toolbar. If the FEA menu is not on your Excel toolbar, follow the instructions in
\fea\xlutil\readme.xls to create it. Once you have the FEA menu available in Excel, choose Open Template
(FEA menu), select Varworks as the product, and the template-sheet you want to open. Click OK. This will
open the desired template, load the VarWorks Add-Ins and set the current directory appropriately.
Alternatively:
1. Start Microsoft Excel.
2. Choose Open (File menu).
3. Change to the VaRworks installation directory \fea\varworks.
4. Double-click varworks.xls.
When you open the VaRworks template, you also set the current directory. VaRworks searches the current
directory for input files unless you specify a file path. To change the current directory in Excel choose Open
(File menu), change to the desired directory, and then click Cancel.
The VaRworks template contains the following worksheets.
Worksheet name Description

Inputs User-specified VaRworks worksheet function arguments and
system information. It uses CFDATA to extract asset, and asset-
class information from the user specified portfolio and
volatility/correlation files.
Cash flow map The portfolio’s trades shredded into cash flows and allocated to
vertices, calculated with CASHFLOWMAP.
Cash flow map chart 3-D graphical representation of the cash flow map.
Analytic VaR The portfolio’s diversified and undiversified analytic VaR,
calculated with the VARANL and VARANLU respectively.
Monte Carlo VaR The portfolio’s mark-to-market, Monte Carlo VaR and
accompanying statistics, calculated with VARCARLO.
Historical VaR The portfolio’s mark-to-market, historical VaR, Shortfall Risk, and
accompanying statistics, calculated with HISTORICALVAR.
VaR Compare Histograms and tail analysis of different methodologies.
Historical Data Histogram and history of any vertex in historical text file, using
HDATA.
Extreme-Value Theory VaR VaR and Shortfall Risk, calculated with EXTREMEVALUE.
Stress Test The portfolio’s P&L associated with each user specified stress
scenario, calculated with STRESSTEST.
Stress Data Market information corresponding to each stress scenario, using
HDATA.
VaRdelta The portfolio’s VaRdelta array, calculated with VARDELTA.
VaRdelta chart 3-D graphical representation of the VaRdelta array.
Component VaR The portfolio’s Component VaR array, calculated with
COMPONENTVAR.
Component VaR chart 3-D graphical representation of the Component VaR array.
Incremental VaR Cash flow map and incremental VaR of candidate trade(s),
calculated with CASHFLOWMAP and MARGINALVAR
respectively.
Summary A handy summary of the results.
VaR history Stores VaR calculations over time.
Control chart A control chart of the historical VaR data.
VCDATA Examples of the VCDATA function.
To navigate, use the dropdown navigation control or the << and >> buttons located at the upper-left corner
of each sheet. Or use the sheet tabs near the bottom of a workbook window that display the worksheet
names. To make a sheet active, click its tab. To scroll through the sheet tabs, use the tab scrolling buttons to
the left of the tabs or press CTRL+PAGE UP or CTRL+PAGE DOWN. If the sheet tabs are not visible choose
Options (Tools menu), click the View tab, and then select Sheet Tabs under Window Options.
The VaRworks template contains the buttons listed in the table below. When clicked, a button runs a Visual
Basic macro (see VaRworks Macros for more information).
Button Function (Macro)
>> Activate the next worksheet (NextSheet).

Button Function (Macro)
<< Activate the previous worksheet (PrevSheet).
 Display a file in Notepad (ViewFileToLeft).
Calculate All Recalculate the entire workbook* (CalcAll).
Calculate Sheet Recalculate the current sheet* (CalcSheet).
User’s Guide Opens the VaRworks User’s Guide in Adobe Acrobat (ShowUsersGuide).
View Error Log Display the VaRworks error log in Notepad (ViewErrorLog).
Www.fea.com Display the FEA home page in your Browser (GotoWebPage).
Reset Template In Inputs sheet. Reconfigure all the sheets to adjust to new portfolio or
volatility/correlation inputs (ReconfigureSheets).
Restore Template In Inputs sheet. Restore all the sheets to the same format of the template
included in the distribution (RestoreSheets).
Change 3D View Toggle the top-down and default chart camera angles.
Print Print the active sheet.
Clear History Clear the VaR history range; not undo-able (ClearVarHistory).
Update History Append data to the VaR history range (UpdateVarHistory).
<sheet name> Activate the named worksheet (GotoSheet).
Clicking Calculate is equivalent to pressing CTRL+ALT+F9. To recalculate only the active worksheet, press
*
SHIFT+F9.
Add-ins are files that can be installed to add commands and functions to your spreadsheet. The VaRworks
add-in is varworks32.xll.
If you have used the FEA Menu to open the template, the add-in is automatically loaded and no further
steps need to be taken. If you want to load the add-in so that it is automatically loaded every time you open
excel, then:
1. Choose Add-ins (Tools menu).
2. If this is the first time you’ve installed VaRworks, click Browse and locate the add-in in
\fea\varworks, then click OK.
3. In the Add-ins Available box, select the VaRworks check box, then click OK.
The first time you load an FEA add-in, a banner screen appears showing the FEA product name, version,
and licensing type. This banner will not appear in subsequent uses, but you can obtain the same information
using VWVERSION.
The VaRworks add-in adds the following functions to Excel.
VaRworks function Returns

BACKTEST Test validity of VaR methodology used.
CASHFLOWMAP VaR-preserving or duration-preserving cash flow map of a
portfolio, converted to the home currency.
CFDATA Cash flow data.
COMPONENTVAR Cash flow-based Component VaR array of a portfolio, expressed
in home currency or percentage (VaRbeta) terms.
EXTREMEVALUE VaR and Shortfall Risk, using Extreme-Value Theory.
HDATA Historical returns of risk factors.
HISTORICALPANDL Simple VaR calculation without portfolio or risk decomposition.
HISTORICALVAR Historical VaR, standard error, Shortfall Risk, mark-to-market,
and distribution statistics.
INCREMENTALVAR Incremental VaR of candidate trades, expressed in the home
currency.
LOADMARKETDATA Makes volatility, correlation, and additional market data files
available to other add-in functions.
MARGINALVAR Incremental VaR of candidate trades.
PORTVARANL Analytic diversified VaR, undiversified VaR, and sum of the
allocated cash flows of a portfolio, converted to the home
currency.
ROLLINGWINDOWVAR Simple VaR analysis without portfolio or risk decomposition.
SDATA Stress-induced risk factor market values.
SIMBACKTEST Test validity of VaR methodology used.
STRESSTEST Stress-induced portfolio profits and losses.
VARANL Diversified analytic VaR of a cash flow map.
VARANLU Undiversified analytic VaR of a cash flow map.
VARCARLO Monte Carlo VaR, standard error, mark-to-market, and
distribution statistics.
VARCOMPARE Comparison of different VaR methodologies.
VARDELTA VaRdelta of a portfolio’s cash flow map.
VCDATA Volatility and correlation data for given vertices.
VWVERSION Version of the installed VaRworks add-in, as text.
1. In Microsoft Excel, choose Function (Insert menu).

2. Choose FEA VaRworks in the Function category box.
A list of functions will appear in the Function name box.
3. Click Cancel or press ESC.
Activate the Inputs sheet. The arguments already contain the correct values for this tutorial, so you won’t
have to change them. When you want to experiment with the argument values or calculate VaR for your
own portfolio, enter values in the light gray cells shown in the figure below.
Arguments Area on the Inputs Sheet
Required. Specify either RiskMetrics, MakeVC, or custom volatility-correlation dataset. A dataset is

comprised of a volatility file and a correlation file. You may include a directory and drive if the files are not in
the current directory. In this tutorial we use the daily RiskMetrics dataset from 2/2/1999: 19990202.dvf
(volatility file) and 19990202.dcf (correlation file). See LOADMARKETDATA for the most general
specification of a dataset.
Note If you create your own dataset with MakeVC, make sure the MakeVC output format setting is ‚FEA‛.
If
The volatility-correlation dataset also defines the vertices. A vertex is a pre-determined asset class-maturity
bucket for which volatilities and other time series statistics have been measured. It consists of an asset (a
currency or commodity), an asset class (such as commodity or interest-rate instrument, which may also
indicate of the credit quality of the payor), and a maturity (a payment time measured from today). In
VaRworks, vertices are represented using the notation asset.asset_class[maturity]. For example, the U.S.
Government Bond 30-year vertex is USD.Z30 and spot USD/EUR rate vertex is EUR.XS. See Volatilities and
Correlations for more information.
Volatility files define:

 Vertices onto which cash flows are mapped.
 Price volatilities.
 Yield volatilities (where applicable).
 Yield curves.
 Foreign exchange rates.
 Commodity, equity, and Brady bond prices.
 Forecast horizon of the volatilities (and correlations).
 Overall decay factor used to make forecasts.
Correlation files define:

 A pair of vertices.
 Their correlation.
The information in these files is used to:

 Value financial instruments.
 Shred instruments into cash flows.
 Allocate cash flows to vertices.
 Calculate VaR, VaRdelta, Component VaR, and Incremental VaR.
Here are the answers to some common questions about volatility and correlation datasets:
Can I change the interest rates and exchange rates in the volatility file?
Yes. You can specify interest rates and exchange rates to be used in mark-to-market calculations, that are
different from the one contained in the volatility file, by using the Yield Curve and Exchange Rate input
files.
Can I change the volatilities in the volatility file?

Yes.
Can I change the correlations in the correlation file?

No. Correlation matrices are quite sensitive to changes. Even small changes would probably result in an
unstable (non-positive definite) covariance matrix.
Can I add my own observations for new assets and maturities to an existing volatility-correlation
dataset?
No. Adding observations would probably result in an unstable (non-positive definite) covariance matrix. If
you want to create custom datasets then you should not augment existing ones. Instead, create them from
historical price and interest-rate data with FEA’s MakeVC utility. Contact FEA for more information.
Optional. Enter the name of an asset file. Leave this argument blank if you are using RiskMetrics files but
specify it if you are using MakeVC files. You may include a directory and drive if the file is not in the
current directory. Several VaRworks functions read asset codes files to determine the valid set of asset codes
in the volatility-correlation dataset. The currency and commodity codes in volatility and correlation files
must be a proper subset of the codes listed in asset codes file. Asset codes files allow you to use custom
volatility and correlation datasets with user-defined currency and commodity codes. You can create custom
datasets from historical price and interest-rate data with MakeVC. See Assets for more information. If
omitted, a default set of currency and commodity codes is used (the default set includes all the RiskMetrics
codes). See also LOADMARKETDATA.
Required. A portfolio file is a text file that describes the financial instruments in a portfolio. You may include a
directory and drive if the file is not in the current directory. Each record in a portfolio file specifies either:
 the terms of a single trade, or
 a path ‚pointing‛ to another file containing trades.
See Record Layouts for more information. The VaRworks sample portfolio file port.txt contains the names of
files containing different types of trades.
Note that the file names in the sample portfolio file do not include paths, meaning they must all be located
in the current directory.
Sample Trade Files
File Instruments
asian.txt Average-price and average-strike options
barcap.txt Interest rate barrier caps and floors
baropt.txt Barrier options
bestof.txt Options on combinations of up to three assets
File Instruments
bond.txt Bonds
bondfut.txt Bond futures
bondfuto.txt Options on bond futures
bondfwd.txt Bond forwards
bondopt.txt Bond options
brady.txt Brady bonds (not included in sample portfolio file port.txt)
capfloor.txt Caps and floors
cashflow.txt Individual dated cash flows
commfut.txt Commodity futures
commphys.txt Commodity physical positions
commswap.txt Commodity swaps
crack.txt Crack options
cspread.txt Calendar spread commodity options
cswapopt.txt Currency swap options
diffswap.txt Differential and Basis commodity swaps
dual.txt Dual-asset options
eqapo.txt Equity average-price options
eqopt.txt Equity options
equity.txt Equity shares and indices
eurodepo.txt Eurocurrency futures
euroopt.txt Options on Eurocurrency futures
forward.txt FX spot and forward deals
fra.txt Forward rate agreements
Frn.txt Floating rate notes
fwdopt.txt Forward-start options
iswap.txt Commodity index swaps
iswapopt.txt Commodity index swap options
mm.txt Money market instruments
option.txt Currency and commodity options
repo.txt Repurchase agreements
spread.txt Spread options
swap.txt Interest-rate and currency swaps
swaption.txt Options on interest-rate swaps
swing.txt Swing contracts
vqcashflow.txt Individual dated cash flows, with uncertain principal
When you create your own portfolio, we recommend you make copies of the sample files and modify them.
(Your files need not have the same file names as the sample files—it is the TYPE header, not the file name,
that determines the type of instrument.) You can edit the sample files using a text editor such as Notepad or
Wordpad or word processor such as Microsoft Word. See Entering Data for more information on creating
your own portfolio.
Some of the trade files listed in the sample portfolio file have been commented out to speed VARCARLO
execution. You can include them again by deleting the ‚#‛ comment character at the beginning of the line.
To suppress VARCARLO calculation, set Iterations equal to zero.
Required. Specify the VaR horizon in days. VaR is the expected change in the portfolio’s value under adverse
circumstances in the VaR horizon. The forecast horizon is the horizon of the volatility and correlation
estimates, in days.
Analytic VaRs are scaled using the square root of the VaR horizon. For Monte Carlo and Historical
Simulation, we revalue the portfolio at horizon.
Choice of VaR horizon

The VaR horizon can be a function either of the position or the investor. In the former case, the longer
horizon for estimating risk can be the result of the time it takes for the position to be liquidated or
neutralized. In less liquid markets, it can take up to a week or longer to significantly modify the market risk
profile of a portfolio. In the latter case, it is the investor who defines the horizon. Risk is measured over the
period until investment objectives are reviewed and reassessed.
When choosing a horizon, consider:

 Unwind period—how long, on average, does it take to reverse a market position or individual
trade?
 Attention period—how often, on average, do you re-examine your portfolio and its mark-to-
market or hedging trades?
 Accounting period—how long until the next financial reporting must be done?
Recommendations
A long period is merely the sequence of several short periods of risk. You cannot expect to manage risk over
long periods unless you are able to manage it over short periods; there is no ‚catching up later‛ in risk
management. We recommend that you make the VaR horizon as short as you can, but no shorter than the
actual trading decisions or VaR recalculations can be done. This implies that almost all users should use a
one-day horizon.
Required. Enter a number between 0.5 and 1, exclusive, specifying the size of the one-tailed VaR confidence
level. For a probability level of x, about 1 – x percent of the losses during the horizon period should exceed
the resulting VaR. For example, enter 0.95 for a 95% confidence level (5% one-tail level).
Confidence level selection

Common choices for a confidence level are 95% (RiskMetrics) and 99% (Basle).
 With a 95% level and a one-day horizon, losses in excess of the VaR will occur about once in
every 20 days.
 With a 99% level and a one-day horizon, losses in excess of the VaR will occur about once in
every 100 days.
If the probability of loss is normally distributed, the 5% one-tail level is about 1.645 standard deviations
from the mean; the 1% one-tail level is about 2.33 standard deviations.
Recommendations
Confidence levels should be established for solid statistical reasons, not wishful thinking. No choice is more
‚conservative‛ than the other: it is nonsense to say, ‚We want to experience a serious loss infrequently, so we use
a confidence level which involves a small probability of loss in computing our VaR.‛ The tail distributions of most
finite-variance distributions are highly similar in shape, leading to the observation that all choices are
roughly equal in distributional accuracy. But the less-extreme order statistics have higher significance.
Therefore, choose 95% or 92.5%, not 97.5% or 99%.
Put another way, say you have these two situations:

 You’ve selected a 99.5% confidence level, and you notice VaR outliers in two of the last 200
days. Should you worry?
 You’ve selected a 95% confidence level, and you notice VaR outliers in 20 of the last 200 days.
Should you worry?
Therefore, we recommend you choose a confidence level sufficiently large to get one outlier a month.
Required. Enter text specifying the currency in which cash flows and market risk are measured. Use a three-
character ISO-4217 (or SWIFT) currency code: USD, EUR, JPY, and so forth. If you are a U.S.-based investor
or want to measure your risk in U.S. dollars then set home currency to USD. You can set the home currency
to any currency code included in the volatility-correlation dataset. See Assets for information on currency
codes.
The home currency determines how volatilities and correlations are used. If the home currency is not USD
then VaRworks rebases cross-rate volatilities and correlations to the home currency prior to calculations. For
example, a EUR-based investor with USD exposure is interested in fluctuations in the currency USD/EUR
whereas the same investor with an exposure in Pounds Sterling is interested in fluctuations in the GBP/EUR.
Since RiskMetrics foreign exchange volatilities are expressed in U.S. dollars per foreign currency unit,
VaRworks calculates cross-rate volatilities and correlation using the USD/EUR and USD/GBP volatilities and
correlation.
Optional. Enter a date specifying the effective calculation date—zero time compared with the times of the
cash flows. If omitted, the system date (today) is assumed.
Optional. Iterations is a number specifying the number of simulations to run. iterations is an integer greater
than or equal to zero. If iterations is not passed as an integer then it is truncated. If iterations = 0 then no
simulation is performed and only the portfolio’s mark-to-market is returned. The paths of all the underlying
correlated variables are sampled on each run. Each simulation run samples paths for those variables on
which the portfolio value depends. The number of simulated variables is then always less or equal than the
number of basic financial assets for which volatility and correlation data are provided. Calculation time
increases approximately linearly with the number of iterations. If iterations is omitted then 1000 is used,
however some empirical experimentation is necessary to determine how many iterations will provide you
with a satisfactory standard error for your portfolio.
Optional. The seed is a number specifying the initial value used to generate a sequence of pseudo-random
numbers. The same seed produces the same sequence of pseudo-random numbers and therefore identical
results for a given set of inputs, which may be useful for testing and comparison purposes. seed must be an
integer greater than or equal to zero. If seed is zero or omitted then an internally-generated random seed is
used.
The other Monte Carlo settings are for advanced users and described in Monte Carlo VaR and VARCARLO.
Required. Specify the name of the file that contains the historical observations for the risk factors. You may
include a directory and drive if the files are not in the current directory. In this tutorial we use a hypothetical
data file with random observations.
Note If you have MakeVC, you can use the input file into MakeVC directly for the Historical Simulation
and Extreme Value Theory.
Optional. The start and end dates represent the first and last historical observation dates for which price
returns will be used. The historical data file should contain historical data that falls within the window
defined by start_date and end_date, inclusive of these dates. If omitted, loading of a given historical data
series from hist_data begins with the first observation and ends with the last date detected.
Optional The season start and season end arguments are dates whose month and day-of-month indicate the
start and end of a season window. The files of hist_data should contain historical data that falls within the
window defined by start_season and end_season, inclusive of these dates. Note that the year of both
arguments is ignored. If omitted, loading of a given historical data series from hist_data begins with 1
January and ends with 31 december. (A change in this input can force a reload of historical data if cache was
set to FALSE in the previous call.)
The other historical simulation settings are for advanced users and described in Historical Simulation and
HISTORICALVAR.
The HDATA function is a useful companion to your historical simulation analyses. It allows you to view the
implicit historical returns applied to any asset underlying your portfolio – the returns actually used in the
historical simulation of the VaR of your portfolio. It also provides additional useful statistics on the
historical data being used.
Required. The VaR quantile is a number greater than 0 and less than 1 specifying the size of the VaR
confidence level. (This is analogous to the confidence interval used as input for Analytic, Monte Carlo or
Historical VaR). If you are analyze the loss tail, tail_quantile cannot exceed var_quantile; for a profit
tail_array, var_quantile cannot exceed tail_quantile.)
Required. The error confidence is a number between 0 and 1 specifying the confidence interval for the fit of
the P&L distribution tail to a Generalized Pareto distribution.
Required. The Tail quantile determines the beginning of the tail. The tail quantile input is a number greater
than 0 and less than 1 specifying the percentile of the threshold (or start) value of the P&L distribution tail.
The other extreme-value VaR settings are for advanced users and described in Extreme-Value Theory and
EXTREMEVALUE.
Required. Specify the name of the file that contains either: (i) the stress test scenarios for the risk factors, or
(ii) the names of files that actually contain stress scenarios for the risk factors. You may include a directory
and drive if the files are not in the current directory. In this tutorial we use hypothetical scenarios.
The other stress-test simulation settings are for advanced users and described in Stress Testing and
STRESSTEST.
Activate the Inputs sheet. The arguments in the Advanced Input section contain the right values for this
tutorial, so you won’t have to change them. The different inputs are grouped by VaR methodology. The
Advanced Input Settings are described in the Function Reference section of the User's Guide under each
individual function.
Advanced Input Arguments Area on the Inputs Sheet
Click Calculate or press F9 to calculate the workbook (if you have not changed any cells in the workbook
then press CTRL+ALT+F9 instead). It will take a minute or two the first time you load a volatility-correlation
dataset. Large portfolios can take several minutes to map.
Calculation speed depends mainly on the:

 number of American options and interest-rate derivatives in the portfolio,

 number of Monte Carlo iterations,
 speed of your computer, and
 amount of memory available.
Observe calculation progress by watching the left side of the status bar in the lower portion of the
window—if the status bar is not visible choose Options (Tools menu), click the General tab, and then select
Status Bar under Show.
Important You must set calculation to Manual for the VaRworks template to calculate properly. Choose
Options (Tools menu), click the Calculation tab, select Manual under Calculation, clear the Recalculate
before Save check box, and then click OK.
Note In Microsoft Excel, pressing F9 updates only those cells affected by values you change. Pressing
CTRL+ALT+F9 forces recalculation of every cell in the entire workbook whether or not their precedent cells
(that is, cells directly or indirectly related to the formula in the cell) have been changed.
Click the Cash flow map sheet tab to view the results. If VaRworks returned numbers then proceed to the
next paragraph. If VaRworks returned #NAME? then load the VaRworks add-in with Add-ins (Tools
menu), then recalculate. If VaRworks returned #N/A then change the current directory to \fea\varworks
with Open (File menu), then recalculate. If these don’t work then skip to Examine the Error Log below.
The Cash flow map sheet displays the portfolio’s cash flows (in millions of home currency) calculated by the
CASHFLOWMAP worksheet function. CASHFLOWMAP decomposes each trade in the portfolio into its
component cash flows (each equivalent to a zero-coupon bond) and allocates these cash flows to the vertices
specified by the volatility-correlation dataset. CASHFLOWMAP returns VaR-preserving or duration-
preserving allocations, depending on the value of Preserve VaR/duration. The results are displayed in a
two-dimensional array with assets (currency or commodity) in columns and asset class and maturity in
rows. Positive numbers indicate cash inflows and negative numbers cash outflows. See Cash Flow Mapping
and CASHFLOWMAP for more information.
Click the Cash flow map chart sheet tab to view three-dimensional representation of the CASHFLOWMAP
cash flow array. You can reformat the chart using Excel commands.
Click the Analytic VaR sheet tab to view the portfolio’s diversified and undiversified analytic VaR (in
millions of home currency) calculated, respectively, by the VARANL and VARANLU functions. VARANL
and VARANLU use the array of cash flows returned by CASHFLOWMAP. The diversified VaR of a
portfolio is the exposure of its cash flows accounting for the correlations of their price movements, or, the
minimum expected loss on the portfolio over the given time horizon and confidence (probability). For
example, if the diversified VaR is US$10MM and you have set horizon to one day and confidence to 95%
then over the next 24-hour period there is a 5% chance your loss will exceed US$10MM. The undiversified
VaR of a portfolio is simply the sum of the VaRs of each cash flow (undiversified VaRs are additive because
they do not account for correlations—that is, as if all the correlations equal one). Subtracting the diversified
VaR from the undiversified VaR gives your gain from diversification. See Value at Risk, VARANL, and
VARANLU for more information.
Click the Monte Carlo VaR sheet tab to view the portfolio’s Monte Carlo VaR and standard error (in millions
of home currency) calculated by the VARCARLO function. VARCARLO is self-contained and does not
depend on the results of any of the other VaRworks functions. The output also includes the portfolio’s
mark-to-market, VaR as a percent of mark-to-market, and the mean, standard deviation, and chart of the
portfolio’s profit-and-loss distribution. If a portfolio does not contain options then the analytic and Monte
Carlo VaRs will be very close. See Monte Carlo VaR and VARCARLO for more information.
Click the Historical Simulation VaR sheet tab to view the portfolio’s Historical Simulation VaR, Expected
Shortfall, and standard error (in millions of home currency) calculated by the HISTORICALVAR function.
HISTORICALVAR is self-contained and does not depend on the results of any of the other VaRworks
functions. The output also includes the portfolio’s mark-to-market, VaR as a percent of mark-to-market, and
the mean, standard deviation, and chart of the portfolio’s profit-and-loss distribution. See Historical
Simulation VaR and HISTORICALVAR for more information. Historical Simulation also provides an array
with the P&L results for each historical scenario sorted by date, ascending or descending order.
Click the Extreme Value Theory tab to view the portfolio’s Extreme Value VaR, Extreme Value Expected
Shortfall and the parameters of the generalized Pareto Distribution calculated by the EXTREMEVALUE
function. Note that the tail_array input used by the EXTREMEVALUE function is generated as output by
the HISTORICALVAR function. A graphical representation of the tail of the P&L distribution and the
generalized Pareto Distribution fit can be observed as well. See Extreme Value VaR and EXTREMEVALUE
for more information.
Click the Stress Test sheet tab to view the portfolio’s P&L’s under stress scenarios specified in the stress data
file input.
Click the VaRdelta sheet tab to view the portfolio’s VaRdelta array. The elements of the VaRdelta array
represent the cash flow direction in which VaR is increasing the fastest—values greater than zero show risk-
increasing trades, values equal to zero show risk-neutral trades (or no vertex exists), and values less than
zero show risk-decreasing trades. For example, suppose that there are only three vertices and that the
VaRdelta array is (+3, -2, +1). The +3 value of the first vertex element is largest, so our exposure is ‚most
sensitive‛ to additional cash flows at this vertex. To put it another way, if we were forced to accept another
marginal cash flow, its occurrence at the first vertex will change our VaR exposure the most. The sign of the
VaRdelta array elements is also important. In the example above, the first vertex element +3 means that
adding positive first-vertex cash flows will increase risk, while adding second-vertex (with -2 VaRdelta
value) cash flows will diminish risk. See VaRdelta and VARDELTA for more information.
Click the VaRdelta chart sheet tab to view a three-dimensional representation of the portfolio’s VaRdelta
array. To change the angle at which you view the chart choose 3-D View (Format menu).
Click the Component VaR sheet tab to view the portfolio’s Component VaR array. The elements of the
Component VaR array represent a breakdown of the analytic VaR into additive parts. For example, suppose
that the analytic VaR is four and there are only three vertices. A possible Component VaR array is (+6, -4,
+2). The +6 value of the first vertex element is largest, so contributes the most risk. The sign of the
Component VaR array elements is also important. In the example above, the first vertex element +6 means
that these cash flows increase VaR, while the second vertex element cash flows (with -4 Component VaR
value) decrease VaR. The Component VaR array elements can also be displayed as percentages (which sum
to one)—called the VaRbeta—for example, (+1.5, -1, +0.5). See Component VaR and the COMPONENTVAR
worksheet function for more information.
Click the Component VaR chart sheet tab to view a three-dimensional representation of the portfolio’s
Component VaR array.
Click the Incremental VaR sheet tab to view the candidate portfolio’s cash flow map and incremental effect
on VaR calculated, respectively, by the CASHFLOWMAP and INCREMENTALVAR functions. The
incremental VaR shows the approximate amount (in millions of home currency) by which VaR will change
in adding the candidate trade(s) to the existing portfolio of trades. This permits, among other things,
incremental analysis of the trader’s next proposed trade without re-examining the entire portfolio,
assignment of real-time VaR-based trading limits, ranking each vertex in terms of how influential it is in the
overall VaR, and a comparison of the reduction in VaR with the cost of putting on a hedge. See VaRdelta
and INCREMENTALVAR for more information.
Click the Summary sheet tab to view a handy summary of the results.
If a VaRworks function returns #N/A then click View Error Log to open the VaRworks error log.
When an error is detected it is written to the error log. The error log is a text file, named varworks.log, that is
created (or appended to if it already exists) when you recalculate a worksheet containing a VaRworks
function. The error log is overwritten whenever you start a new VaRworks session (that is, quit Excel and
start again) but grows without bound during any particular session. Do not edit or delete the error log while
VaRworks is loaded or running.
There are two types of errors posted to the error log: warnings and fatal errors. Fatal errors halt calculations,
warnings do not. Even though warnings are not severe enough to halt calculations, you should examine
them anyway. For example, a warning is generated if your portfolio contains expired instruments. Fatal
errors require corrective action on your part (you must edit the text files or change the function arguments).
Examples of fatal error are invalid dates (for example, February 30, 1996), invalid numbers (for example,
12A45), and logic errors (for example, a bond with a maturity date falling before its issue date). The sample
portfolio files contain no fatal errors but may generate warnings, depending on the effective date you use.
See The Error Log more information.
Optional. The VaR history and Control chart worksheets and VaRworks Macros help you keep a record of
your historical VaRs. We recommend you examine how your VaR changes over time. You can use the cash
flow map and VaRdelta to answer the question: Do changes in VaR come from changes in the volatilities,
correlations, or the portfolio?
Click the VaR history sheet tab to view the historical VaR database. The worksheet contains sample data;
click Clear History to clear it. Click Update History to append the current VaR data to the bottom of the list,
where you can edit it. The profit-and-loss figure is calculated by subtracting yesterday’s mark-to-market
from today’s mark-to-market—you may replace it with your actual P&L.
Click the Control chart sheet tab to view the control chart. Click Update Chart to update the chart with the
new data. The top blue line is the Monte Carlo VaR and the bottom blue line is a reflection of the top line
about the horizontal axis, forming a symmetric VaR band. The red dots are the daily P&L figures. An
effective way to check the validity of the underlying valuation and VaR models is to compare one-day VaR
estimates with the realized daily profits and losses. The control chart illustrates the concept. By definition,
the +/- VaR lines should contain 90% of the P&L points.
Click the VCDATA sheet tab for examples of the VCDATA worksheet function, which returns volatility and
correlation data for given vertices. You can use it to retrieve and transform data in the volatility-correlation
dataset.
Most data (volatilities, correlations, trades, and market rates) are input as text files, also called ASCII files or
flat files. This section describes how to create properly-formatted text files.
Text files contain a sequence of characters formatted into lines, where each line is terminated by an end-of-
line marker (a linefeed character or a carriage-return—linefeed character combination). Characters are
standard ASCII (English-language) text characters with no formatting codes. The valid character set
includes all the printable characters (A, B, C,..., a, b, c,..., 1, 2, 3,..., ;, ., ,, #, *,...) plus some special characters,
such as the tab and carriage return.
The data in a text file is presented in columns, called fields, and rows, called records. A field is a category of
information. It could be a maturity date, coupon frequency, interest rate, asset code, or even the location of
another text file. A record is a collection of information about one item, such as a bond, cash flow, exchange
rate, or point on a yield curve.
DEM,USD,20,1.3704,2/1/1998
DEM,JPY,25,0.0152,6/1/1996 Records
Fields
Each record of a certain type contains the same set of fields and each field contains the same type of
information for each record.
For example, a record describing a coupon bond contains the following fields:
1. Currency code (see Assets for information on currency codes).
2. Credit rating code (see Codes for a list of credit rating codes).
3. Principal (in millions).
4. Maturity date.
5. Coupon rate (as a percent).
6. Coupon frequency (times per year).
For example, the record for a US$1,000,000 Treasury bond maturing December 15, 2020, paying a 6% semi-
annual coupon, is:
USD,Z,1,12/15/2020,6.00,2
The characters that separate each field in a record are field delimiters and are required for every record
containing more than one field. Field delimiters can be commas (the default) or semicolons as set by the
FIELDDELIM header. You cannot mix field delimiters within a single record or block of records. Some
example records:
aaa,bbb,ccc,ddd,eee Comma-delimited record
aaa;bbb;ccc;ddd;eee Semicolon-delimited record
For several record layouts, some fields are optional and can be omitted. Here’s an example record using
commas as field delimiters:
aaa,bbb,ccc,ddd,eee Example record.
To omit fields in the middle of a record, enter consecutive field delimiters (do not insert spaces between the
consecutive delimiters):
aaa,bbb,ccc,,eee Next-to-last field omitted from example record.
To omit fields from the beginning of a record, enter leading delimiters:

,,ccc,ddd,eee First two fields omitted from example record.
To omit fields from the end of a record, omit both the delimiters and the fields:
aaa,bbb,ccc Last two fields omitted from example record.
Extraneous trailing delimiters are ignored:

aaa,bbb,ccc,ddd,eee,,, Extraneous trailing delimiters are ignored.
Lines containing only delimiters are ignored:

,,, This entire line is ignored.
Enter the year, month, and day of a date as digits in the order specified by the DATEORDER header. For the
examples in this section, the date order is month, day, year (MDY).
When entering dates, keep in mind:

 Dates can contain only these characters: 0 1 2 3 4 5 6 7 8 9 . - /
 Dates cannot contain blanks.
 Separate day, month, and year by a single slash ‘/’, hyphen ‘-’, or dot ‘.’ character.
 You cannot mix date separators within dates.
 Leading zeroes are optional for single-digit days and months. For example, specify 6 or 06 for
June.
 The first two digits of the years 1950-2049 are optional. For example, specify 95 or 1995 for the
year 1995.
 Use all four digits of the years before 1950 and after 2049. For example, specify 2060 for the
year 2060. If you specify 60, it is interpreted as 1960.
 It is best to use four digit years for all date entries, regardless of the year. This avoids
ambiguity.
The following are examples of valid and invalid dates (the date order is month, day, year,
DATEORDER=MDY).
Valid dates Comments

04-03-94 Interpreted as 3-April-1994.
1.4.11 Interpreted as 4-Jan-2011.
12/23/2000 Interpreted as 23-Dec-2000.
6-22-50 Valid but probably wrong, the year is interpreted as 1950.
Invalid dates Comments

01011995 Missing date separators.
Invalid dates Comments

3-Apr-2010 Contains a non-numeric month.
2.30.96 Non-existent date.
12 / 25 / 2000 Contains blanks.
12/25-2000 Mixed date separators.
Enter numbers in decimal or scientific notation and use the decimal separator specified by the
DECIMALSEP header. For the examples in this section, the decimal separator is a dot character ‘.’. Numbers
can be entered in the following formats:
Number format Examples

Integer 1234, 01234, -1234, +1234, 0
Decimal 1.234, -.1234, 0.1234, -0.1234, 0.0
Scientific notation 1.23e+04, 1.23E-04, -1.23E-04
When entering numbers, keep in mind:

 Numbers must begin with one of these characters: 0 1 2 3 4 5 6 7 8 9 . , - +
 Numbers in decimal or scientific notation format are termed real numbers.
 A tolerance of 0.00000001 (1.0E-8) is used to distinguish between real numbers.
 Numbers can contain a single dot ‘.’ if DECIMALSEP=DOT or a single comma ‘,’ if
DECIMALSEP=COMMA.
 Numbers cannot use a comma as a decimal separator if the field separator character is also a
comma (that is, you may not set both the FIELDDELIM and DECIMALSEP headers to
COMMA).
 Numbers cannot contain currency signs ($, £, ¥, DM, Fr, and so forth.), percent signs (%),
parentheses [( )], or thousands separators (1.000.000,00 and 1,000,000.00 are invalid).
 Numbers cannot contain alphabetic characters unless they are typed in scientific notation. An
upper-case letter O cannot be substituted for zero (0). A lower-case L cannot be substituted for
the number one (1).
 To enter a negative number, precede it with a minus sign (-), do not enclose it in parentheses [(
)].
 Numbers cannot contain blanks.
Text, or string, fields can contain letters, digits, and any other English language characters that you can
produce on your printer. You can create text entries that include numbers and text or just numbers.
Each line in a text file can be a header, record, blank line, or comment, as described below.
Headers are lines preceding records that contain summary information about those records. See Headers and
Record Layouts for more information.
A record is a single line of data containing information about one item, such as the terms of a single swap or
a point on a yield curve. Records are comprised of one or more delimited fields.
The number and order of fields in a record is determined solely by the type of record it is, as specified by the
preceding TYPE header.
A blank line is a line consisting of only a carriage return and no other characters. They can occur anywhere in
a text file. All blank lines are ignored.
A comment is a descriptive note and can occur on any line in a text file. The pound or hash character ‘#’ at the
beginning of a line introduces a comment. For example:
#This is a comment
You cannot set the comment character to any other character. Comments always continue to the end of the
line; any data that follows a comment must go to a new line. In-line comments, or comments that occur on
the same line as data, are prohibited. For example:
USD,Z,0.5,0.042 #This comment is illegal
Comments do not occur within string literals (that is, a sequence of characters surrounded by double quotes).
Tip You can ‚comment out‛ records if you want to temporarily omit them from calculations.
All comments are ignored.
You can create and edit text files using a text editor such as Notepad or Wordpad in Windows or vi or
emacs in Unix. And, since virtually all major portfolio systems export text files, you can download trades
directly. You can also create and edit text files in other applications. This section shows how to create a
FORWARD file using Microsoft Office applications. A FORWARD file, which contains foreign exchange
forward trades, requires the header *TYPE=FORWARD followed by records. Each record requires five
fields: a buy currency, a sell currency, an amount in millions, an exchange rate, and a value date. See
Forwards for more information about FX forwards.
1. Enter the file headers in the few first rows of the worksheet.
2. Under the header rows, enter data records by typing each field in its own column.
3. Choose Save As (File menu).
4. Choose CSV (Comma delimited) (*.csv) from the Save as type box.
5. Click Save.
A Microsoft Excel Worksheet Ready to be Saved as a CSV File
A B C D E
1 *FIELDDELIM=COMMA
2 *DECIMALSEP=DOT
3 *DATEORDER=MDY
4 *TYPE=FORWARD
5
6 DEM USD 100 1.3704 1/1/1998
7 USD JPY 100 0.011123 1/1/1999
8 DEM JPY 100 0.015244 1/1/2000
9 JPY DEM 100 65.6013 1/1/2001
1. Enter the file headers in the few first lines of a document.

2. Under the header lines, enter data records separating each field by a comma.
3. Choose Save As (File menu).
4. Choose Text Only with Line Breaks (*.txt) from the Save as type box.
5. Click Save.
A Word Document Ready to be Saved as a TXT File
*FIELDDELIM=COMMA
*DECIMALSEP=DOT
*DATEORDER=MDY
*TYPE=FORWARD
EUR,USD,100,1.370400,2/1/1998
USD,JPY,100,0.011123,3/1/2000
EUR,JPY,100,0.015244,6/1/2001
JPY,EUR,100,65.60130,12/1/1998
1. First, create two tables, Header (to hold header records) and Forward (to hold data records),
with the following layouts:
Header Table Columns
Name Type (size)

Header Text (50)
Forward Table Columns
Name Type (size)

buy_ccy Text (3)
sell_ccy Text (3)
Amount Number (Double, 8)
exchange_rate Number (Double, 8)
value_date Date/Time (8)
2. Enter headers in the Header table (one per row) and forward records in the Forward table (one
per row).
3. Create a UNION query to combine fields from the two tables (for information on creating
UNION queries, search Access Help for union queries). The SQL statement is:
SELECT header, Null, Null, Null, Null From Header
UNION SELECT Forward.* FROM Forward;
4. To export the union query to a delimited-text file, choose Save As/Export (File menu), select
To an external File or Database, set Save as type to Text File, select Delimited, choose comma
as the field delimiter, set Text Qualifier to {none}, and clear the Include Field Names on First
Row check box. For more information on exporting text files, search Access Help for exporting
data.
All input files are self-describing, meaning they contain summary information about the records contained in
them. This includes information such as the type of records, the field delimiter character, the decimal
separator character, the order that dates are given, and so on. Each item of descriptive information is called
a header. The most important header is TYPE, which indicates what subsequent records describe. Other
important headers include the regional setting headers DATEORDER, DECIMALSEP, and FIELDDELIM
and the option evaluation headers, MODEL, MEANREVERSION, TREESTEPS, and VOLATILITY. The table
below lists common valid headers. Additional valid headers allowed by specific input files are described in
the section pertinent to those files (e.g. Distribution Data or Historical Data).
Headers
Header Required Default Description

?
CPNTYPEDATE No REGREG Specifies whether certain fixed income
instruments have irregular first and last
coupons, and the date when interest first starts
accruing.
DATEROLL No MODFOL Specifies how to roll dates in CAPFLOOR2 and
LOWING BARRIERCAP2.
DECIMALSEP No DOT Decimal separator character.
DELTAGAMMA No FALSE Allows Monte Carlo/Historical simulation to
use a delta-gamma approximation instead of a
full revaluation of the instrument.
DRIVER No <None> Defines a stress-testing driver vertex.
FIELDDELIM No COMMA Field separator character.
INTERPOLATION No LINEAR Specifies the interpolation scheme used in
CAPFLOOR2 and BARRIERCAP2.
MEANREVERSION No 0 (zero) Sets the mean-reversion rate for certain pricing
models.
MESHPOINTS No 50 Integration steps required by some instruments.
MODEL No HW Sets the interest-rate derivative valuation
model.
SCENARIO No <None> Labels a stress scenario with a text name.
SMILEMODEL No NONE Includes deterministic volatility corrections
when valuing options.
TREESTEPS No 35 Sets the number of tree steps in American
option evaluation.
TYPE Yes <None> Type of trade records.
UNWINDPERIOD No <None> Specifies the holding period for the trade.
UNWINDTYPE No <None> Specifies how the trade position is liquidated
over the specified period
VOLATILITY No <None> Volatility—context determined by TYPE and
MODEL headers.
VOLMODEL No DV Controls whether stochastic implied volatility
risk is included (SV) or not (DV) in theVaR
calculation.
Every header line must begin with the star character ‘*’ and come before the block of records it describes.
Headers are given in the form *HEADER=VALUE. For example, this header line indicates that fields are
separated by commas:
*FIELDDELIM=COMMA
Place each header on its own line, like this:

*FIELDDELIM=COMMA
*DECIMALSEP=DOT
*DATEORDER=MDY
*TYPE=BOND
Headers for each block of trade records must appear in the following order:
Header Order
Position Header
1 FIELDDELIM
2 DECIMALSEP
3 DATEORDER
4 TYPE
... Subsequent headers, if any, may come in any order.
Here are some examples of showing the headers for a file with one FX forward record.
If, as in the United States, commas separate field values within records, dots separate decimal digits from
whole numbers, and dates are given in month-day-year order then the headers and trade record are:
*FIELDDELIM=COMMA
*DECIMALSEP=DOT
*DATEORDER=MDY
*TYPE=FORWARD
EUR,JPY,25.5,0.015244,6/1/2001
or (since FIELDDELIM, DECIMALSEP, and DATEORDER use default values):

*TYPE=FORWARD
EUR,JPY,25.5,0.015244,6/1/2001
If, as is common outside the United States, semicolons separate field values within records, commas
separate decimal digits from whole numbers, and dates are given in day-month-year order then the headers
and trade record are:
*FIELDDELIM=SEMICOLON
*DECIMALSEP=COMMA
*DATEORDER=DMY
*TYPE=FORWARD
EUR;JPY;25,5;0,015244;1/6/2001
Optional.CPNTYPEDATE specifies whether certain fixed income instruments have irregular first and last
coupons, and the date when interest first starts accruing. This header is currently supported for
CAPFLOOR2 instruments only. Valid values are a string defining the type of irregular coupons, and a date,
separated by the appropriate field delimiter, for instance *CPNTYPEDATE=type,1/3/2009, where type can
take one of the following values:
type Description
REGREG (default) Regular first and last coupons.
REGSHORT Regular first, short last coupon.
REGLONG Regular first, long last coupon.
SHORTREG Short first, regular last coupon.
SHORTSHORT Short first, short last coupon.
SHORTLONG Short first, long last coupon.
LONGREG Long first, regular last coupon.
LONGSHORT Long first, short last coupon.
LONGLONG Long first, long last coupon.
Example: * CPNTYPEDATE =SHORTREG,1/3/2009
Optional. DATEROLL specifies how dates are rolled and time is counted in determining payments, when
valuing trades of type CAPFLOOR2, BARRIERCAP2, AVERAGECAP, RANGEACCRUAL, FRN, and
SWAPOPTION. The valid DATEROLL values are:
DATEROLL Dates are given in this order

FOLLOWING The payment is moved to the following business day.
MODFOLLOWING The payment is moved to the following business day unless that day is
in a different month, in which case it is moved to the preceding business
day (default).
PRECEDING The payment is moved to the preceding business day.
MODPRECEDING The payment is moved to the preceding business day unless that day is
in a different month, in which case it is moved to the following business
day.
If DATEROLL is omitted, the default value is MODFOLLOWING.
Example: * DATEROLL =FOLLOWING
Optional. DATEORDER specifies the order that the year, month, and day are given in dates. The valid
DATEORDER values are:
DATEORDER Dates are given in this order

MDY Month, day, year (default)
DMY Day, month, year
YMD Year, month, day
MYD Month, year, day
DYM Day, year, month
YDM Year, day, month
If DATEORDER is omitted, the default value is MDY.
Example: *DATEORDER=DMY
Optional. DECIMALSEP specifies the character separating decimal digits from whole numbers. The valid
DECIMALSEP values are:
DECIMALSEP Decimal separator

DOT Dot character ‘.’ (default)
COMMA Comma character ‘,’
Important DECIMALSEP and FIELDDELIM cannot be set to the same value. For example, they cannot
both be set to COMMA.
If DECIMALSEP is omitted, the default value is DOT.
Example: *DECIMALSEP=COMMA
Optional. The DELTAGAMMA header allow the user to choose between a full revaluation of the instrument,
or a revaluation based on a Delta-Gamma approximation, see page 236 for a description of the methodology.
Setting DELTAGAMMA=TRUE can considerably speed up the calculations for instruments requiring
intensive numerical computations, like SPREAD, ASIAN, BESTOF, CRACK, etc. This header is currently
supported for the following instruments: ASIAN, BESTOF, CRACK, CALSPREAD, DIFFSWAP,
DIGITALOPT, DBARRIEOPT, FWDOPT, INDEXSWAP, OPTINDEXSWAP, OPTION2, SPREAD,
STRIPSPREADOPT, STRIPOPT.
In most of the cases we considered the Monte Carlo VaR results obtained by using a Delta-Gamma
approximation and those obtained by full revaluation were in very good agreement for short term horizons
and the confidence level set to 95%. As an example of the gain in speed, Delta-Gamma Monte Carlo was
roughly 4 times faster than the full revaluation Monte Carlo for generic spread options and was roughly 8
times faster for generic forward-starting options. In our test cases we used the default number of tree steps.
The valid DELTAGAMMA values are:
DELTAGAMMA Description
FALSE A full revaluation of the instrument is performed for each scenario of a
Monte Carlo/Historical simulation
TRUE Revaluation of the instrument for each scenario of a Monte
Carlo/Historical simulation is obtained via a delta-gamma
approximation.
If DELTAGAMMA is omitted, the default value is FALSE.
Example: *DELTAGAMMA=TRUE
Optional. DRIVER specifies a driver vertex for stress testing purposes. It has the format:
*DRIVER=[asset,asset_class,maturity]
where asset, asset_class, and maturity define the market vertex designated as a driver of peripheral assets. To
specify no driver, omit these three fields; otherwise, you must specify all three fields.
Use this header within a STRESS_SCENARIOS file, only. Any number of drivers may be defined within a
STRESS_SCENARIOS file. When specified, a driver applies to the records that follow, unless superseded by
a new driver header. Drivers specified in files can be overridden by specifying a driver via a call to
STRESSTEST or SDATA.
30-day US interest rate driver example: *DRIVER=USD,R,30

Six-month GAS driver example: *DRIVER=GAS,C,6
Optional. FIELDDELIM specifies the character separating the fields of a record. The valid FIELDDELIM
values are:
FIELDDELIM Field separator

COMMA Comma character ‘,’ (default)
SEMICOLON Semicolon character ‘;’
Important DECIMALSEP and FIELDDELIM cannot be set to the same value. For example, they cannot
both be set to COMMA.
If FIELDDELIM is omitted, the default value is COMMA.
Example: *FIELDDELIM=SEMICOLON
Optional. INTERPOLATION specifies the rate interpolation scheme used when valuing trades of type
CAPFLOOR2 and BARRIERCAP2. The valid INTERPOLATION values are:
INTERPOLATION Field separator

LINEAR Linear interpolation (default).
LOGLINEAR LogLinear interpolation.
SPLINE Spline interpolation.
LOGSPLINE LogSpline interpolation.
If INTERPOLATION is omitted, the default value is LINEAR. Note that rates are always extrapolated at the
last available rate when beyond the bounds of the input curve.
Example: * INTERPOLATION =LOGLINEAR
Instruments valued via ErgLib also support an interpolation header whose valid values are:

NEXT Step interpolation, onto following value.
PRIOR Step interpolation, onto prior value.
CASHFLOW instruments defining currency flows (with credit rating or custom credit ratings determining
the discount curve) support an interpolation header whose valid values are:

SPLINE Cubic spline interpolation (on rates).
Optional. The MEANREVERSION headers set mean-reversion rates. Mean reversion controls the relation
between short-term and long-term volatility. Mean-reversion processes are modeling the observed historical
phenomenon that commodity prices and interest rates tend to pull back to a long-term average over time,
rather than rising or falling without limit.
The mean-reversion rate is the annualized rate at which prices and rates are pulled to forward rates. As with
all options models parameters, this rate should be calibrated.
MEANREVERSION applies to bonds and swaps with embedded derivatives (for example, callable bonds),
bond and swap derivatives (for example, bond options and swaptions), interest-rate options (for example,
caps and floors), and currency and commodity options (for example, Asian and spread options); it is
ignored otherwise.
MEANREVERSION2 applies to currency and commodity options with two or more underlying assets (for
example, crack and spread options); it is ignored otherwise.
MEANREVERSION3 applies to currency and commodity options with three or more underlying assets (for
example, crack options); it is ignored otherwise.
The minimum value is zero. Mean reversion is used only if the MODEL equals BK (Black-Karasinski), HW
(Hull-White), or MR (mean reversion); it is ignored otherwise.
Specify mean reversion as a percent; for example, for 10% specify 10, not 0.10.
If MEANREVERSION is omitted, the default value is 0 (zero).
Example: *MEANREVERSION=10
Optional. MESHPOINTS sets the number of mesh points used to perform numerical integration when
evaluating some exotic currency and commodity options.
MESHPOINTS applies to BESTOF, CALSPREAD, FWDOPT, SPREAD, CRACK, and BARRIEROPT (with
window) option records; it is ignored otherwise.
The minimum value is 3; the maximum value is 100. All values are truncated to integers. More mesh points
improves numerical convergence at increased calculation time.
If MESHPOINTS is omitted, the default value is 50.

Example: *MESHPOINTS=50
Optional. MODEL sets the model to use when mapping interest-rate options (including callable bonds) and
currency/commodity options.
MODEL applies to BOND, BONDFORWARD, BONDFUTURE, BONDFUTOPT, BONDOPTION,

CAPFLOOR, CCYSWAPOPT, EUROFUTOPT, REPO, SWAP, and SWAPTION records; it is ignored
otherwise.
The valid MODEL values are:
MODEL Model
BLACKP Black (1976) on the instrument price. Not supported for CAPFLOOR or
instruments with multiple calls.
BLACKY Black (1976) on the instrument rate (yield). Not supported for options on zero-
coupon bonds or instruments with multiple calls.
BLACKY-CS Black (1976) on the instrument yield, using a call-spread approach for digital
options in range accrual and barrier cap instruments.
BK Black and Karasinski (1991).
HW Hull and White (1993) (default).
BLACKP is more appropriate for bonds and bond derivatives: BARRIERCAP, BOND, BONDFORWARD,
BONDFUTURE, BONDFUTOPT, BONDOPTION, CCYSWAPOPT, and REPO.
BLACKY is more appropriate for swaps and interest-rate options: CAPFLOOR, EUROFUTOPT, SWAP, and
SWAPTION. BLACK and BLACKY can be used interchangeably.
If you specify MODEL=BLACKP or MODEL=BLACKY then you must also specify VOLATILITY. If you
specify MODEL=HW or MODEL=BK then you must also specify VOLATILITY and MEANREVERSION.
MODEL applies to ASIAN, BESTOF, CALSPREAD, CRACK, FWDOPT, OPTINDEXSWAP, and SPREAD
records; it is ignored otherwise.
The valid MODEL values are:
MODEL Model
BS Black-Scholes model (1973) (default).
MR FEA mean-reversion model (FEA @ENERGY model).
Black (1976)
Black ’76 call and put prices are
C  e  rt [ FN (d1 )  KN (d 2 )]
P  e  rt [ KN (d 2 )  FN (d1 )]
d1 

log F / K    2 t 2 
 t
d 2  d1   t
where C is the fair value of a call, P is the fair value of a put, F is the price of the underlying instrument, K is
the option’s strike price, t is the time remaining (in years) until the options expires, r is the current risk-free
interest rate (read from the volatility or yield curve file),  is the annualized volatility of the underlying
instrument (set with the VOLATILITY header), N(.) is the cumulative probability distribution function for a
standardized normal variable, and log denotes the natural logarithm.
Hull-White (1993)
The implemented Hull-White model for the process of the short rate is
dr  a (t )  r dt  r0 dz
where r is the short-term interest rate (read from the volatility or yield curve file), (t) is a function of time
determining the average direction in which r moves (chosen so that r movements are consistent with today’s
term structure of interest rates),  is the initial volatility of the short rate (set with the VOLATILITY header),
and a is the mean-reversion rate which governs the relationship between long-rate and short-rate volatilities.
a = 0 corresponds to the Ho-Lee model where all rates are equally variable; as a increases long rates become
less volatile. Set this value with the MEANREVERSION header.
Black and Karasinski (1991)

The implemented Black-Karasinski model for the process of the short rate is
r  r
d (log r )  a  (t )  r0 log dt  r0 dz
r0  r0 
where the variables are the same as described in the Hull-White model and log denotes the natural
logarithm.
Ho-Lee (1986)
The Hull-White model with a mean-reversion rate of zero is equivalent to the Ho-Lee model, that is, if you
set MEANREVERSION=0 and MODEL=HW then you get Ho-Lee.
For interest-rate options, if MODEL is omitted, the default value is HW.

For currency/commodity options, if MODEL is omitted, the default value is BS.
Example: *MODEL=BK
Optional. SCENARIO sets the name of the stress scenario specified in a stress-test data file of TYPE equal to
STRESS_SCENARIOS.
In a STRESS_SCENARIOS file, you define a sequence of stress scenarios. To begin the definition of a
scenario, you specify the SCENARIO header. The value of the header is a text name that distinguishes the
scenario from all others in the STRESS_SCENARIOS file. The text name is case-sensitive and it can include
white space. The records that immediately follow the SCENARIO header define the stresses, or shocks, to
apply to various assets. The description of the syntax for these records is given in Stress Data.
Example: *SCENARIO=The Gulf War

The SMILEMODEL header applies to EQUITYOPTION, EQUITYOPTION2, OPTION, OPTION2, and

STRIPOPT; it is ignored otherwise. The S and M0 smile models are enabled for EQUITYOPTION,
EQUITYOPTION2, and OPTION. All implemented smile models can be used for OPTION2 and STRIPOPT.
The valid SMILEMODEL values are:
MODEL Model
S Sticky strike model
M0 Sticky moneyness model with moneyness given by m  K / S for options on
m  K / F for options on commodities
equities and FX and
M1 Sticky moneyness model with moneyness given by m  N (d1 ) , where
d1  (ln( F / K )   2 ( K )(T  t ) / 2) /( ( K ) T  t )

M2 Sticky moneyness model with moneyness given by m  ln( F / K )
M3 Sticky moneyness model with moneyness given by m  e r (T t ) N (d1 )
NONE No volatility smile corrections are applied in the valuation.
The sticky strike and sticky moneyness models are the deterministic models of the dynamics of the implied
volatility surface in time.
The sticky strike model assume that the volatility surface profile does not change in time
 t  t ( K ,T )   t ( K ,T ) .
The sticky moneyness model assumes that the volatility surface with respect to the moneyness m and the
maturity T does not change in time
 t  t (m,T )   t (m,T ) ,
where the moneyness m is a function of strike, spot price, and possibly other parameters of the model. Note
that the sticky strike model is a special case of the sticky moneyness model when m=K.
The implemented models M0, M1, M2, and M3 are the sticky moneyness model with different moneyness
choices, which are described in the above table.
Optional. TREESTEPS sets the default number of tree steps used to evaluate the American option model.
TREESTEPS applies to American EQUITYOPTION, FWDOPT, OPTINDEXSWAP, and OPTION records,

and to CONVERTIBLES records; it is ignored otherwise.
The minimum value is 3; the maximum value is 300. All values are truncated to integers. A high number of
tree steps results in greater accuracy at the cost of decreased speed. TREESTEPS only applies to American
options, for example, options that can be exercised at any time up to the expiration date.
If TREESTEPS is omitted, the default value is 35.

Example: *TREESTEPS=100
Required. TYPE specifies what subsequent records describe (until the end of the file or next TYPE header,
whichever comes first). The valid TYPE values are:
TYPE Each subsequent record describes a

ASIAN European average-price or average-strike option
AVERAGECAP Average cap or floor
BARRIERCAP Barrier cap or floor
BARRIERCAP2 Barrier cap or floor, extended
BARRIEROPT Barrier option
BESTOF Best-of option (up to three assets)
BOND Bond
BONDFORWARD Bond forward
BONDFUTURE Bond future
BONDFUTOPT Bond futures option
BONDOPTION Bond option
BRADY Brady bond
CALSPREAD Calendar spread option
CAPFLOOR Interest-rate cap or floor
CAPFLOOR2 Interest-rate cap or floor, extended
CASHFLOW Dated cash flow
CCYSWAPOPT Currency swap option
CDS Credit default swap
COMMODITYFUT Commodity future or forward
COMMODITYPHYS Commodity physical
COMMODITYSWAP Commodity swap
CONVERTIBLEBOND Convertible bond
CRACK Crack option (three assets)
DBARRIEROPT Discretely monitored Barrier option, up to two barriers
DIGITALOPT Digital option
DIFFSWAP Differential swap
DISTRIBUTIONDATA File type containing the distribution of P&L’s
DUAL Dual-asset option
EQUITY Equity cash, futures, or forwards
EQUITY2 Equity cash, streamlined input
EQUITYFUTURES2 Equity futures, or forwards, streamlined input
EQUITYAPO Average-price equity option
EQUITYOPTION Equity option
EQUITYOPTION2 Equity option, streamlined input
EQUITYPROXY Equity via up to three equity proxies
EUROFUT Eurocurrency future
EUROFUTOPT Eurocurrency futures option
FORWARD Foreign exchange spot, futures, or forward
FWDOPT Forward-start option
FRA Forward rate agreement
FRN Floating rate note
HISTORICALDATA File type containing a list of historical data files
INDEXSWAP Commodity index swap
MONEYMARKET Money market instrument
OIS Overnight index swaps

OPTINDEXSWAP Commodity index swap option
OPTION Currency or commodity option
OPTION2 Currency or commodity option
PORTFOLIO Trade file name or multiple instruments
RANGEACCRUAL Range accrual instrument
REPO Repurchase agreement
STRIPOPT Strip of options
STRIPSPREADOPT Strip of spread options
SPREAD Spread option (two assets)
STRESS_FILES File type containing a list of scenarios data files
STRESS_SCENARIOS File type containing a list of stress scenarios.
SWAP Interest-rate or currency swap
SWAPTION Interest-rate swap option
SWAPTION2 Interest-rate swap option, extended
SWING Swing contracts
VQCASHFLOW Dated cashflow, with uncertain principal
XRATE Foreign exchange rates
YIELDCURVE Point along a zero-coupon yield curve
TYPE is required—there is no default value.
Example: *TYPE=BOND
Optional. UNWINDPERIOD specifies the holding period specific to a given trade (or set of trades). If
omitted the default holding period is set equal to the user specified horizon.
The value of UNWINDPERIOD is a number greater than zero specifying the holding period in weekdays
(currently VaRworks does not allow the user to specify a holiday schedule; hence the number of weekdays ,
i.e. the number of days excluding Saturday and Sunday, is not equal to the number of business days). If
unspecified, the holding period is assumed to have the same length as the horizon input, which is specified
in calendar days. For instance if value date is on Monday, horizon is seven days, and UNWINDPERIOD is
omitted, its default value is set to five. If value date is Monday, horizon is one day, and UNWINDPERIOD is
omitted, its default value is set to one.
The UNWINDPERIOD header can be specified for any trade.
By setting the UNWINDPERIOD value to any number, Monte Carlo simulation is performed using a multi-
step framework, see page 29. Hence, even when the holding period specified by this header matches the
horizon input and instruments are unwound at the end of the period (see UNWINDTYPE below) the results
of the MC simulation might differ from the standard single-step simulation, if some of the trades supporting
the multi-step framework expire before the horizon.
Note that use of a multi-step framework in the Monte Carlo simulation is activated by specifying UNWINDPERIOD
for at least one trade.
Example: * UNWINDPERIOD =20

Optional. UNWINDTYPE specifies how a trade position is liquidated over time. If omitted and
UNWINDPERIOD is specified, it defaults to LINEAR. If UNWINDPERIOD is unspecified for a trade, the
UNWINDTYPE for that trade is always set to END, even if a different value is specified thorugh this header.
UNWINDTYPE Description
LINEAR The position is liquidated over the specified period at a constant rate. For a
trade with a holding period equal to h, at the end of each day a fraction of the
overall position equal to 1/ h is liquidated.
END The position is liquidated at the end of the holding period.
Like the UNWINDPERIOD header, UNWINDTYPE can be specified for any trade. However, if
UNWINDTYPE is used within the Monte Carlo simulation framework, the full functionality of
UNWINDTYPE and UNWINDPERIOD is available only for the trades listed on page 31. Trades not
included in the list support this functionality only insofar no uncertain cashflows occur before the specified
holding period of the trade.
Example: * UNWINDTYPE =LINEAR
VOLATILITY is required for interest-rate derivatives; optional for currency, commodity, and equity options. The
meaning of VOLATILITY depends on the context in which it is used, determined by TYPE and MODEL.
VOLATILITY2 sets the default volatility for the second asset (asset2 or ccy2) in BESTOF, CALSPREAD,
CCYSWAPOPT, CRACK, DUAL and SPREAD records; it is ignored otherwise. The VOLATILITY2 value is
only a default value and is used only if the vol2 field is omitted from an individual BESTOF, CALSPREAD,
CCYSWAPOPT, CRACK, DUAL or SPREAD option record.
VOLATILITY3 sets the default volatility for the third asset (asset3) in BESTOF and CRACK records; it is
ignored otherwise. The VOLATILITY3 value is only a default value and is used only if the vol3 field is
omitted from an individual CRACK option record.
VOLATILITY applies to currency options, commodity options, equity options, callable bonds, and interest-
rate options; it is ignored otherwise.
If VOLATILITY is used for currency, commodity, or equity options then it sets the default volatility for the
Garman-Kohlhagen (European options) and Cox-Ross-Rubinstein (American options) pricing models. Use
the annualized standard deviation or implied volatility. For these options, the VOLATILITY value is only a
default value and is used only if the volatility field is omitted from an individual option record.
If VOLATILITY is used for a callable bond or interest-rate option then it sets the volatility for the model
specified by MODEL. The value of VOLATILITY for interest-rate instruments is interpreted as follows:
Interpretation of the VOLATILITY value for interest-rate derivatives
MODEL Interpretation of VOLATILITY header value

BLACKP The volatility term, , of the Black ’76 model. The volatility is a percent of the
bond price. For swaptions, the volatility is a percent of the price of a par bond
paying the swap rate coupon. (A swaption is priced as an option on a bond
paying the swap rate coupon, where the option is struck at par (100%).)
MODEL Interpretation of VOLATILITY header value

BLACKY The volatility term, , of the Black ’76 model. The volatility is a percent of the
interest rate.
BK or HW Initial volatility of the short-term rate, .
See MODEL Header for references on these models.
In some papers, Hull-White volatility is expressed as a standard deviation of the short rate. To convert that
to the percentage volatility used by VaRworks use
percentage = std_dev / short_rate
where
percentage = percentage volatility (what VaRworks uses).
std_dev = volatility expressed as a standard deviation.
short_rate = initial short-term interest rate (the shortest rate you have).
Note You can roughly convert yield volatility to price volatility using this equation
price volatility = yield volatility  yield  duration
For swaptions, duration is the duration of the swap you will receive when the option expires. You can
calculate it with the MDURATION worksheet function in the Analysis Toolpak in Microsoft Excel. For
Eurocurrency futures options, duration is the expiration of the underlying futures contract expressed in
years. For example, if the futures contract expires in three months, it is 0.25 years. It is assumed that the
option and the futures contract expire at the same time.
The minimum volatility must be greater than zero. Enter the volatility as a percent; for example, for 25%
specify 25, not 0.25.
Example: *VOLATILITY=25
Optional. VOLMODEL header is used to include the market risk associated to implied volatility in the VaR
calculation for trades of the following types: EQUITYOPTION, EQUITYOPTION2, OPTION, and STRIPOPT
with equity, commodity, or FX underliers; CAPFLOOR2, BARRIERCAP2, RANGEACCRUAL,
AVERAGECAP, and SWAPTION2 for interest rate underliers. The valid VOLMODEL values are:
VOLMODEL Volatility Model

SV Stochastic Volatility model. The model takes into account implied
volatility risk in the VaR calculation.
DV Deterministic Volatility model. The IV risk is not taken into account.
If VOLMODEL is omitted, the default value is DV. In this case, deterministic volatility model corrections
can be applied when valuing options, see the SMILEMODEL header for details.
If the VOLMODEL is set to SV, no deterministic volatility model corrections are added. Thus, the stochastic
volatility model corrections have priority over the deterministic volatility model corrections.
Example: *VOLMODEL = SV
Each trade record describes the terms of a single financial instrument. Instruments are specified in sufficient
detail that all future cash flows can be generated. Other information, such as security and counterparty
information, is not accepted. See TYPE Header for a list of supported instruments.
Choosing a Format
When inputting trades, you have a choice of formats: multiple-instrument, portfolio, or a combination of the
two. The choice you make will depend on several factors including the size of your portfolio, the number of
different instrument types in your portfolio, the export capabilities of your portfolio management system,
and if trades are located in a single place or dispersed over a network.
Multiple-instrument Format
The multiple-instrument format allows you to enter trades of all instrument types in a single file. Each
instrument type must be proceeded by a block of headers that includes a TYPE header and any other
optional or required headers for that particular instrument type. Every header block must contain a TYPE
header—you cannot change (non-TYPE) header settings by embedding headers lines between records of the
same instrument type. A header block applies to all the records that follow, until another header block is
encountered, which in turn applies to all the records that follow it, and so on. Here’s an example of a file
containing bonds, forwards, and options:
*TYPE=BOND
USD,Z,1,10/1/1998
USD,Z,1,12/1/2020,6.00,2
*TYPE=FORWARD
USD,JPY,10,0.011123,10/1/1998
EUR,JPY,25.5,0.015244,12/1/2001
*TYPE=OPTION
USD,EUR,10,E,C,0.2000,10/25/1998,5.0
If you specify a (non-TYPE) header value that is not the default for that header then you must repeat this
header in every header block, or it reverts to its default value. For example, suppose you enter the dates in
the above file in day-month-year order instead of the default month-day-year order. You must specify the
*DATEORDER=DMY header in every header block, or the date order will revert to its default value MDY
order as soon as a new header block missing the DATEORDER header is encountered:
*DATEORDER=DMY
*TYPE=BOND
USD,Z,1,1/10/1998
USD,Z,1,1/12/2020,6.00,2
*DATEORDER=DMY
*TYPE=FORWARD
USD,JPY,10,0.011123,1/10/1998
EUR,JPY,25.5,0.015244,1/12/2001
*DATEORDER=DMY
*TYPE=OPTION
USD,EUR,10,E,C,0.2000,25/10/1998,5.0
If the final DATEORDER header had been omitted then an error would have occurred because
DATEORDER would have reverted to MDY and the 25 in 25/10/1998 would have been interpreted as an
(illegal) month instead of a day.
The header-block behavior is consistent with the portfolio format: if a multiple-instrument file was split into
several files, each containing a different instrument TYPE, then these individual files are treated the same as
a portfolio file pointing to all the single files.
Portfolio Format
Since different types of financial instruments are specified with different terms, you may prefer to store
them in different files. Portfolio files ‚point‛ to individual trade files with records containing file names. For
example, suppose we store our bond, forward, and option trades in three separate files named bond.txt,
forward.txt, and option.txt, respectively. The portfolio file including these trades is:
*TYPE=PORTFOLIO
bond.txt
forward.txt
option.txt
You can include relative or absolute paths if files are in different directories:
*TYPE=PORTFOLIO
bond.txt
\trader_b\forward.txt
f:\trader_c\option.txt
Non-TYPE headers should not be specified in a portfolio file; they should be specified in the individual
trade files. See Portfolios for more information.
Combining Formats
You can combine multiple-instrument and portfolio files:
*TYPE=BOND
USD,Z,1,10/1/1998
USD,Z,1,12/1/2020,6.00,2
*TYPE=FORWARD
USD,JPY,10,0.011123,10/1/1998
EUR,JPY,25.5,0.015244,12/1/2001
*TYPE=PORTFOLIO
option.txt
Historical data files are constant-maturity time series corresponding to the prices, interest rates, or exchange
rates of market vertices. For convenience, the path names of historical data files may be grouped within a
single intermediate file headed by *TYPE=HISTORICALDATA, as in the example below:
*TYPE=HISTORICALDATA
hist_rates.txt
hist_prices.txt
hist_xrates.txt
Any intermediate file containing *TYPE=HISTORICALDATA cannot contain other header directives;
additional directives are ignored. You cannot place the HISTORICALDATA TYPE in the same file as other
TYPE declarations. For details regarding the format of historical data files, see the description provided in
HISTORICAL DATA.
Stress scenarios are defined in files of *TYPE=STRESS_SCENARIOS. Multiple scenarios are defined within a
single STRESS_SCENARIOS file, wherein each scenario is a set of records prefixed with the SCENARIO
header. Each record describes how one or more assets should be shocked, in accordance with the definition
of the scenario. The record layout is described in Stress Data.
Exchange rate files contain USD-based exchange rates used for currency conversions. Yield curve files
contain points on the zero-coupon yield curves for several currencies and credit ratings (for example,
government and swap curves). The curves are used for present value, future value, and forward rate
calculations.
Exchange rate and yield curve files can be used in the several VaRworks worksheet functions to override the
exchange rates and yield curves contained in the volatility file. You can create extract exchange rate and
yield curve files from volatility files using the GENRATES utility.
Volatility files contain price volatilities and other time-series statistics. Each volatility record specifies a
vertex. Correlation files contain correlations for the vertices specified in a corresponding volatility file. Each
record in a correlation file specifies two vertices and their correlation. Asset files contain user-defined
currency, commodity, and equity index codes and are only required if you are using MakeVC or custom
volatility and correlation files.
The headers in these files differ from the header records in other files in order to maintain compatibility
with RiskMetrics. See the Remarks section of Volatilities or separate MakeVC documentation for more
information.
*DATE=yyyymmdd,ROW=num_records,COL=2,CONTENT=ASSET
*REBASE_CCY=CCY
*ASSET,ASSET_CLASS
The REBASE_CCY header information is optional; if omitted, USD is assumed. See Rebasing the Market
Data for information about REBASE_CCY.
In order to accommodate the asset files produced by some versions of MakeVC, if the REBASE_CCY header
is missing, but the data records include a ccy field, the contents of the first ccy field is taken to be the
REBASE_CCY. This feature requires that some care be exercised when constructing asset files in order to
avoid unexpected results.
Asset files are used to specify the valid set of asset codes, equity index names, custom credit ratings, and
implied volatility identifiers in volatility and correlation datasets. Asset files allow you to use custom
volatility and correlation datasets with user-defined currency and commodity codes, multiple equity indices
per currency as well as individual equity names, customized credit ratings labels, and implied volatilities as
risk factors. You can create custom datasets from historical price, interest-rate data, and implied volatility
data with MakeVC. If you are specifying equity trades by using the streamlined record layout described on
page 197, the entry corresponding to equities must specify the price per share, and, optionally, the beta
coefficient with respect to an equity_index. (Additional information about the equities, like CUSIP, ticker,
descriptive name, liquidity and more, can be added after the beta entry. See VCDATA on page 351, and
CFDATA on page 293 for additional information).
asset_code, asset_class, ccy, price, equity_index, beta
1. asset_code Required. Text specifying a currency or commodity code, equity name, custom credit rating
label, or implied volatility (IV) identifier. If the credit rating label refers to interest rate data specified as a
spread with respect to the Government curve Z, the asset_code string must be expressed in the form
‚S:NAME‛, where ‚S:‛ identifies the label as a spread, and NAME is a user defined name, otherwise asset
code is an arbitrary name (the text corresponding to NAME should not contain the special characters ‚.‛,
‛,‛, ‚:‛, ‚;‛, or the substring‛_IV‛). When asset_code is equal to the reserved name ‚S‛, and asset class is a
Corporate Credit rating, the code identifies a generic Corporate Credit ratings specified as a spread.
Implied vol asset codes should be expressed as X_IV(K,T), where X is the name of the corresponding
option’s underlying equity, index, or commodity, and K and T are the numerical values of the strike price
and maturity of the implied volatility risk factor for which data is provided in the volatility, correlation, and
possibly history files. If the option’s underlying is a currency CC1, and the numeraire is CC2, then
asset_code should be expressed as CC1CC2_IV(K,T), e.g. GBPUSD_IV(1.7,7/31/2006) for a USD based
currency option on GBP. If the option’s underlying is an interest rate, then the implied vol asset codes
should be expressed as X_IV(m,T,τ), where X is the name of the credit rating of the underlying rate (X
should not contain the special characters ‚.‛, ‛,‛, ‚:‛, ‚;‛, or the substring‛_IV‛) , m is the moneyness
defined as K/F, i.e. the ratio of the strike and the forward rate at expiry T, and τ is the term of the underlying
interest rate.
When specifying the asset_code corresponding to FX rates in smile files, the asset can be expressed as CC1
or CC1CC2. In the first case the specified volatility corresponds to the exchange rate of CC1 in units of the
rebased currency (default USD), in the second case it corresponds to the exchange rate of CC1 in units of
CC2.
Note that for SWAP and LIBOR credit ratings, X can be set to the full name of the credit rating, e.g.
SWAP_IV(1.01,1,2) or LIBOR_IV(0.99,1,0.5), in addition to the abbreviated form corresponding to the credit
rating code (S_IV and R_IV respectively). For all other credit ratings the name coincides with the credit
rating code, see Credit Rating Codes on page 365 for more details. T can be input either as a date or as time
to maturity in years. If T is expressed as a date, the risk factor has fixed expiry, otherwise, it has constant
maturity (see the discussion on page 54 for details on fixed expiration vs. constant maturity risk factors). τ
should be specified in years. Note that one can use either . or , as decimal separator for K, T (if T is a tenor),
and τ. If . is the decimal separator for K, T, and τ, comma or semicolon can be used as the field delimiters
between K, T, and τ. If , is the decimal separator for K, T, and τ, semicolon must be used as the field
delimiter.
2. asset_class Required. Text specifying if asset_code is a currency, commodity, equity, a credit rating, or an
IV vertex. Specify XS if asset_code is a currency, C if asset_code is a commodity, SE if asset_code is an equity
index name, or one of the Corporate Credit Ratings (from AAA to CCC), see Credit Rating Codes on page
365. If asset_code is an IV, then asset_class should coincide with the asset class of the corresponding option’s
underlying, i.e. it can be SE, XS, or C.
3. ccy Optional. Text specifying a currency code. The entry must be specified for equities entering a
portfolio via the streamlined record layout described on page 197, for custom credit ratings, and for implied
volatilities. For implied volatility risk factors the currency should be set to the currency of the market in
which the corresponding options are traded.
4. price Optional. Number specifying the spot price per share, in units of ccy. The entry must be specified for
equities entering a portfolio via the streamlined record layout described on page 197.
5. equity_index Optional. Text specifying a reference equity_index to which the equity can be mapped, by
specifying an appropriate beta. The entry may be specified for equities entering a portfolio via the
streamlined record layout described on page 197.
6. beta Optional. Number specifying the beta of the underlying equity with respect to equity_index. The
entry may be specified for equities entering a portfolio via the streamlined record layout described on page
197. The market value of the equity at any time is related to a stochastic market index I (normalized to one)
using
market_value = price * (1 + beta * ( I – 1 ))
If omitted, beta is assumed to be one.
To maintain compatibility with RiskMetrics, header records in asset files differ from those in other files.
Asset codes are user-defined strings between one and 50 ASCII character long. For readability and speed we
recommend you limit code length to 15 characters or less. Leading and trailing spaces are stripped but
interior spaces are not. For example, ‚ USD ‛ is equivalent to ‚USD‛ but ‚U S D‛ is not and will be
interpreted as a different asset code. All codes are case-insensitive, so you can enter uppercase or lowercase
characters—they are converted to uppercase. For example, ‚USd‛ and ‚usd‛ are equivalent to ‚USD‛.
For currencies, standard SWIFT or ISO-4217 currency codes are recommended. For commodities, you can
create your own codes or use ones published by commodity information providers or exchanges such as
Reuters, Platt’s, or NYMEX. Examples: USD for U.S. dollars, COB for California-Oregon border electricity.
Equity index names, if provided, may not conflict with asset names. An equity index name, once defined in
an asset file, may be used with any currency, provided appropriate volatility and correlation data is
present in the dataset.
If the asset codes file is omitted then the following default set of currency and commodity codes is used.
If an Asset code file is provided, the definitions contained therein are used to supplement the default set of
currency, commodity, and equity index codes.
Default asset codes

If you are using RiskMetrics datasets you need to supplement the asset codes file with the RiskMetrics codes
not included in the list provided below.
Currency codes
Region Code Description RM

Americas ARS Argentinean peso x
BRL Brazilian real x
CAD Canadian dollar x
CLP Chilean peso
CUP Cuban peso
ECS Ecuadorian sucre
EMB J.P. Morgan Emerging Markets x
Bond Index Plus
MXN Mexican peso x
PAB Panama balboa
USD United States dollar x
VEB Venezuelan bolivar x

Asia Pacific AUD Australian dollar x
CNY Chinese renminbi x
HKD Hong Kong dollar x
IDR Indonesian rupiah x
JPY Japanese yen x
KRW Korean won x
MOP Macao pataca
MYR Malaysian ringgit x
NZD New Zealand dollar x
PHP Philippine peso x
PKR Pakistani rupee
RUR Russian rouble x
SGD Singapore dollar x
THB Thai baht x
TRL Turkish lira x
TWD Taiwan dollar x
VND Vietnam dong
Europe/Africa ATS Austrian schilling x
BEF Belgian franc x
BGL Bulgarian lev
BND Brunei dollar
CHF Swiss franc x
CZK Czech koruna
DEM Deutsche mark x
DKK Danish krone x
EGP Egyptian pound
ESP Spanish peseta x
EUR Euro x
FIM Finnish markka x
FRF French franc x
GBP British pound x
GRD Greek drachma x
HUF Hungarian forint x
IEP Irish pound x
ILS Israeli shekel x
ITL Italian lira x
JOD Jordanian dinar
KWD Kuwaiti dinar
LBP Lebanese pound
LUF Luxembourg franc
MTL Maltese lira
NGN Nigerian naira
NLG Dutch guilder x
NOK Norwegian krone x
PLN Polish zloty x
PTE Portuguese escudo x
SAR Saudi Arabian riyal
SEK Swedish krona x
SIT Slovenian Tolar
SKK Slovakian koruna x
XEU European Currency Unit (ECU)
ZAR South African rand x

Generic CC1 Generic code 1
CC2 Generic code 2
CC3 Generic code 3
CC4 Generic code 4
CC5 Generic code 5
(Note that the in-Euro currencies above only occur in historical datasets. See The Euro for Euro-related
issues.)
Commodity codes
Category Code Description RM

Energy BCO Brent Crude Oil
ELE Electricity
FUO Fuel Oil
GAS Natural Gas
GSO Gas Oil
HSO High Sulfur Fuel Oil
HTO Heating Oil
JET Jet Fuel
LSO Low Sulfur Fuel Oil
NAP Naphtha
PRO Propane
UNL Unleaded Gasoline
WTI West Texas Intermediate
Metals ALU Aluminum
COP Copper
GLD Gold x
LED Lead
NIC Nickel
PAL Palladium
PLA Platinum
SLV Silver
TIN Tin
ZNC Zinc
Softs/Agrics COC Cocoa
COF Coffee
CRN Corn
CTL Live Cattle
CTN Cotton
HOG Live Hogs
RUBB Rubber
SOY Soybeans
SUG Sugar
WHT Wheat
Equity Indices
Code Description RM
SE Default equity index x
*DATE=19990622,ROW=10,COL=3,CONTENT=ASSET
*ASSET,ASSET_CLASS
AUD,XS
CAD,XS
EUR,XS
GBP,XS
JPY,XS
ELE,C
GAS,C
GLD,C
WTI,C
ZNC,C
MYCREDIT, A,USD
INTC_IV(20,3/5/2007),SE,USD
GBP_IV(1,7;3/5/2007),SE,USD
GBPUSD_IV(1.7,0.25),XS,USD
NG_IV(7,5;0,5),C,USD
*TYPE=ASIAN
*MODEL=option-pricing-model
*MEANREVERSION=mean-reversion-rate [optional]
*VOLATILITY=volatility [optional]
*INTERPOLATION= interpolation [optional] (LINEAR, PRIOR, NEXT)
*DELTAGAMMA= use delta-gamma approximation in simulation [optional] (FALSE,TRUE)
Asian option’s include European average-price and average-strike options.
An average-price option (APO) is an option whose payoff is the difference between the strike price and the
average price of the underlying asset during an averaging period. The arithmetic average is calculated on
predetermined discrete fixings of an agreed reference price during the averaging period. The averaging
period may begin at any time and always ends at option expiry. If the averaging period began in the past
(that is, before the value date) then a running average must be specified. APOs are cheaper than ordinary
options because the volatility of an averaged price is lower than that of the constituent prices.
For example, suppose today (the value date) is 5/1/1998 and you own an APO expiring 6/30/1998 that has an
averaging period from 6/1/1998 to 6/30/1998, inclusive. If the average of the underlying asset is sampled
every business day then set the number of fixings equal to 22 (assuming there are no holidays). As time
passes, the value date will move into the averaging period (that is, on or after 6/1/1998) and you need to
specify a running average. As the number of fixings increases for an established averaging period, the
option’s value converges with that of one settling against a continuous average.
An average-strike option (ASO) is an option whose strike price is set to the average price of the underlying
asset at the end of an averaging period. The arithmetic average is calculated on predetermined discrete
fixings of an agreed reference price during the averaging period. The averaging period may begin at any
time and end at or before option expiry. If the averaging period began in the past (that is, before the value
date) then a running average must be specified. In a more general form, the ASO settles against the average
price multiplied by some constant, called the strike multiplier.
ASOs are cheaper than ordinary options because the volatility of an averaged price is lower than that of the
constituent prices.
Important Pricing commodity instruments requires the commodity’s price and volatility term structure. If
you are using RiskMetrics datasets you may be unable to price commodity instruments because of
inadequate information. If a significant part of your portfolio contains commodities, we recommend you
create your own volatility-correlation datasets from historical price data (you can use MakeVC to create
custom datasets). See Commodity Instruments for more information.
opt_type, ccy, asset, pc_type, opt_expiry, amount, avg_starts, num_fixings, strike, volatility, running_avg,
avg_ends, strike_multiplier, fut_expiry
1. opt_type Required. Text specifying the type of option. Specify one of the following:
‘A’ for an average-price option (APO).
‘S’ for an average-strike option (ASO).
2. ccy Required. Text specifying the contract’s local settlement currency. See Assets for information on
currency codes.
3. asset Required. Text specifying the underlying asset, which may be a currency or commodity. See Assets
for information on currency and commodity codes.
4. pc_type Required. Text specifying the option type. Specify one of the following:
‘C’ for call option (asset is bought).
‘P’ for put option (asset is sold).
‘S’ for a straddle (a put and a call with the same strike).
5. opt_expiry Required. Date specifying the option’s expiration date. For APOs, this is also the last sampling
point in the averaging period.
6. amount Required. Number specifying the underlying amount, in millions, used to calculate the total
value of the option. Specify a positive number for a long option position and negative number for a short
option position.
7. avg_starts Required. Date specifying when the averaging period starts. It is the first sampling point in the
averaging period.
8. num_fixings Required. Number greater than or equal to one specifying the number of evenly-spaced
sampling points during the averaging period. num_fixings is truncated to an integer.
9. strike Required for APOs, ignored for ASOs. Number specifying the option’s strike price expressed as ccy
per unit of asset.
10. volatility Optional if VOLATILITY header is specified, required otherwise. Number specifying the volatility
(annualized standard deviation) of the price of asset or the implied volatility, as a percent. If the
VOLATILITY header is omitted then you must specify the volatility in this field. If you provide both a
volatility value and a VOLATILITY header value then volatility prevails. Example: for 25%, specify 25.
11. running_avg Optional. Number greater than zero specifying the average price established up to the
effective calculation date by past price observations. running_avg applies only if the effective calculation date
falls after avg_starts and is ignored otherwise. If running_avg is omitted, it is assumed to be zero.
12. avg_ends Optional for ASOs, ignored for APOs. Date specifying when the averaging period ends. It is the
last sampling point in the averaging period. If avg_ends is omitted, it is assumed to be opt_expiry.
13. strike_multiplier Optional for ASOs, ignored for APOs. Number specifying the amount by which to
multiply the strike price. For example, if the option settles against 105% of the average, set strike_multiplier
equal to 1.05. If strike_multiplier is omitted, it is assumed to be one.
14. fut_expiry Optional. Date specifying the expiry date of the futures contract linked to the averaging
period’s initial fixing. fut_expiry, if specified, must be a date on (or near) a forward curve date, typically the
first date falling on or after avg_starts. The futures contract whose price is used in the average is the one
expiring on fut_expiry for averaging dates falling on or before fut_expiry. If some averaging dates fall after
fut_expiry, then subsequent forward curve futures are used until opt_expiry is reached. Omit fut_expiry if the
option settles against the average spot price of the underlying asset.
Specify volatility with respect to ccy, regardless of the base or local currency of asset in the volatility-
correlation dataset.
Interest rates are linearly interpolated about opt_expiry using the ccy swap (asset class S) interest rate curves
in the volatility-correlation dataset.
The payoff (to the holder) at expiration from an average-price option is
 1 n 
Call: max  0,  S t j  K 
 n  1 j 0 
 1 n 
Put: max  0, K   S t j 
n  1 j 0 

where K is the strike price, St(j) is the price of the underlying asset at time tj = ts + j(T – ts) / n, (n + 1) is the
number of fixings during the averaging period, T is the time to option expiration in years, and ts is the time
to the start of the averaging period in years.
The payoff (to the holder) at expiration from an average-strike option is
 1 n 
Call: max  0,  S t j  K 
 n  1 j 0 
 1 n 
Put: max  0, K   S t j 
n  1 j 0 

where St(j) is the price of the underlying asset at time tj = ts + j(te – ts) / n, (n + 1) is the number of fixings
during the averaging period, ts is the time to the start of the averaging period in years, te is the time to the
end of the averaging period in years, ST is the price of the underlying asset at option expiration, and M is a
strike multiplier.
Payoffs assume amount = 1, payoffs are proportional to amount.
Asian options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
commodity derivatives see the @ENERGY User’s Guide, available from FEA.
Also see Options.
APO—averaging starts in the future

USD average-price call option on 1000 barrels of crude oil. The averaging period starts one year before
expiration and crude prices are averaged weekly. This example assumes that today’s date is before 1/1/1997
(the averaging period start date) so averaging starts in the future.
A,USD,WTI,P,1/1/1998,0.001,1/1/1997,52,22.00,40.0
APO—averaging starts in the past

USD average-price put option on 1000 barrels of crude oil. The averaging period starts two years before
expiration. This example assumes that today’s date is after 1/1/1996 (the averaging period start date) so
averaging started in the past; the average price of crude between the starting date 1/1/1996 and today is
22.50 USD.
A,USD,WTI,P,1/1/1998,0.001,1/1/1997,52,22.00,40.0,22.50
ASO on a forward contract—averaging starts in the past

Assuming everything is the same as the previous example, except we have an average-strike option on a
forward contract. The forward expires the day before the option expires and the averaging period ends at
option expiry.
S,USD,WTI,P,1/1/1998,0.001,1/1/1997,52,22.00,40.0,22.50,1/1/1998,1,12/31/1997
*TYPE=AVERAGECAP
*MODEL=BLACKY
*VOLMODEL=stochastic volatility model [optional]
*VOLATILITY= volatility
*DATEROLL= date_convention
*INTERPOLATION= interpolation
An average cap is a contract that pays the difference between the average of an interest rate and a strike
when the rate is about the strike. A floor pays the difference when the rate is below the strike.
Average caps and floors are strips of options on forward interest rates that allow the purchaser to take
advantage of movements in interest rates. The cap or floor price is the sum of the individual options in the
strip, which are called caplets or floorlets.
The risk associated to stochastic changes of the implied volatility can be included in the VaR calculation by
setting the VOLMODEL header to SV. See, Volatility as a Risk Factor section on page 54 for more details.
cf_type, ccy, credit_rating, principal, maturity_date, strike_rate, pmt_freq, rate_mty, avg_freq,

running_avg, weight_type, rate_basis, first_pmt_date, cms_freq, cms_basis, rollday, amort_schedule <A,
date, amount,...>, strike_schedule <K, date, strike_rate,...>, vol_schedule <M1, date, vol,...>, fixings_schedule
<FIX, date, fixing_rate, weight,<>
1. cf_type Required. Text specifying the instrument type. Specify one of the following:
‘C’ for cap.
‘F’ for floor.
2. ccy Required. Text specifying the local currency. See Assets for information on currency codes. See The
Euro for Euro-related issues.
3. credit_rating Required. Text specifying the credit rating of the instrument, which determines which yield
curve is used to discount cash flows. See Codes for a list of the credit rating codes. See The Euro for Euro-
related issues. E.g., specify ‘S’ for a swap curve.
4. principal Required. Number specifying the principal in millions of local currency. Specify a positive
number for a long position or a negative number for a short position. See The Euro for Euro-related issues.
5. maturity_date Required. Date specifying the maturity date of the last capped rate, i.e., the time you
receive the last payment.
6. strike_rate Required. Number specifying the strike rate as a percent. E.g., specify 5.5 for 5.5%.
7. pmt_freq Required. Number specifying the payment frequency—the number of times per year the
instrument makes a payment. Typically 1, 2, 4, or 12.
8. rate_mty Optional. Number specify the maturity of the floating interest-rate in years. E.g., 0.5 means the
fixing rate is a six-month (0.5-year) rate; 3 means the fixing rate is the 3-year CMS rate. Defaults to 1/pmt_freq
if omitted.
9. avg_freq Optional. Number specify the number of times per year the instrument observes a floating rate
the calculate the average. The frequency may be 1, 2, 4, 6, 12, 52, or 365. You can either specify avg_freq or
use fixings_schedule. Past fixings can be specified in fixings_schedule in either case.
10.running_avg Optional. Number specifying the average rate observed so far in the current averaging
period. Past fixings can be specified by either a combination of avg_freq and running_avg or by specifying
a fixings_schedule.
11. weight_type Required. Text specifying how the observed floating rates are weighted in the average.
‚equal‛ The average is the average of the observed rates. Cannot be used with
fixings_schedule (instead, give equal weights in the curve).
‚calendar‛ The average is the average of the observed rates weighted by the length
of the periods from the fixing to the next fixing. Cannot be used with
fixings_schedule (instead, give days between fixings in the curve).
‚relative‛ Weights in the fixings_schedule are normalized to add to 1 by dividing
by the sum of all the weights. E.g., if the first point in the curve has
weight 1 and the second weight 3, then the normalized weights are 0.25
(1/4) and 0.75 (3/4). The normalization is done for each averaging period
(i.e., each caplet) separately.
‚absolute‛ Weights in the fixings_schedule are not normalized. Note that this use of
weights is rare.
12. rate_basis Required. Text specifying the rate basis of the underlying interest rate.
‘A0’ for Actual/360
‘AA’ for Actual/Actual (ISDA)
‘AAISMA’ for Actual/Actual (ISMA Rule 251)
‘B0’ for 30/360 (US NASD)
‘E0’ for 30E/360 (European ISMA)
‘F0’ for 30E+/360 (European ISMA)
13. first_pmt_date Optional. Date specifying the first payment date. This date can be more than one period
forward for forward-starting instruments.
14. cms_freq Optional. Number specifying the payment frequency of the CMS rate paid on the floating leg.
Defaults to pmt_freq, if omitted. Ignored if rate_term is less than one.
15. cms_basis Optional. Text specifying the quotation basis of the CMS rate paid on the floating leg.
Ignored if rate_term is less than one. Defaults to rate_basis, if omitted.
15. rollday Optional. Number specifying the day of the month the instrument pays. This is useful primarily
when an instrument matures on the 30th day of a month with only 30 days. You can choose whether to roll
back to the 31st of months with thirty-one days or to roll back to the 30th. If omitted, the date series will roll
back on the day of the maturity, but will treat the last day of the month as a special case and roll back from,
e.g., June 30th to December 31st.
16. amort_schedule Optional. List specifying the amortization schedule of the instrument. Required for
amortizing instruments only, leave blank otherwise. Each list element contains the following items:
1. Amortization indicator ‘A’.
2. Amortization date—must fall on a payment date.
3. Amortization amount (percent of original principal).
E.g., A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
17. strike_schedule Optional. List specifying the strike schedule of the instrument. Required for variable
strike instruments, leave blank otherwise. Each list element contains the following items:
1. Strike indicator ‘K’.
2. New strike effective date—must fall on a payment date.
3. New strike rate as a percent.
E.g., K,1/1/1997,5.0,K,1/1/1998,5.5
18. vol_schedule Optional. List specifying the volatility, as a percent, corresponding to the specified term.
Each list element contains the following items:
1. Volatility indicator, ‘M1’ for market (Black implied) volatilities.
2. Volatility date.
3. Volatility value (percent).
If you provide both a vol_schedule and a VOLATILITY header value, vol_schedule prevails. If you specify a
volatility smile through the LOADMARKETDATA function, volatilities in the smile file prevail, but
vol_schedule data is still used, if specified, to compute convexity adjustments when they are required by the
term of the instrument.
If the VOLMODEL header is set to SV and the model is BLACKY, the stochastic implied volatility model
will use the implied volatility data specified in the dataset. If vol_schedule or volatility in the VOLATILITY
header is specified, an adjustment will be made to match the mark-to-market of the instrument, see the
section on page 56 for more details.
E.g., M1,1/1/1997,15.0,M,1/1/1998,20
19. fixings_schedule Optional. List specifying the fixing dates for the floating rates, any fixing values set in
the past, and optional weights of the fixings in the average. Each list element contains the following items:
1. Fixings schedule indicator, ‘FIX’.
2. Fixing date.
3. Optional. Fixing value for fixings in the past expressed as a percent, e.g., for 5.5%, enter 5.5.
4. Optional. Weight of fixing in the average. Only used if weight_type is ‚relative‛ or ‚absolute.‛
E.g., FIX,6/1/2005,5.5,1
Important If the instrument has a strike schedule but no amortization schedule, do not insert an extra field
delimiter (comma or semicolon) where the amortization schedule would normally appear. Specify the strike
schedule fund immediately following rollday.
amort_schedule and strike_schedule dates must fall before maturity_date.
See the Remarks section of Swaps for information on rate basis conversions.
For a technical discussion of pricing interest-rate securities see the @INTEREST User’s Guide, available from
FEA.
Average Cap with averaging frequency and running average

C,EUR,S,100,1/1/2010,3.5,1,,12,3.2,calendar,B0,1/1/2004,,,,K,1/1/2007,5.75,K,1/1
/2008,6.0,M1,1/1/2006,15
Average Floor with fixing (averaging) schedule

F,USD,S,100,1/1/2010,4.25,1,,,,relative,B0,1/1/2004,,,,K,1/1/2007,3.25,K,1/1/200
8,3.0,M1,1/1/2006,15,FIX,7/1/2005,,1,FIX,1/1/2006,,1,FIX,7/1/2006,,1,FIX,1/1/200
7,,1,FIX,7/1/2007,,1,FIX,1/1/2008,,1,FIX,7/1/2008,,1,FIX,1/1/2009,,1,FIX,7/1/200
9,,1,FIX,1/1/2010,,1,FIX,7/1/2010,,1,FIX,1/1/2011,,1
*TYPE=BARRIERCAP
*MODEL=BLACKY
A barrier cap, or floor, is a cap or floor that is either activated (knocked-in) or terminated (knocked-out) if
the underlying rate reaches a specified barrier rate between inception and expiry. There are four types of
barriers: a up-and-in payoff occurs only if the underlying rate trades up through the barrier; and by analogy,
up-and-out, down-and-in, and down-and-out. See Caps and Floors for more information.
This is a deprecated trade instrument provided for backward compatibility. The trade instrument Barrier
Caps and Floors (type II) is a replacement for this trade instrument. The new trade type provides more
flexibility in specifying the terms of a barrier cap (floor) instrument.
cf_type, ccy, credit_rating, principal, maturity_date, strike_rate, rate_freq, rate_basis, first_pmt_date,

barrier_type, barrier_style, barrier, first_reset_rate, amort_schedule <A, date, amount,...>, strike_schedule
<K, date, strike_rate,...>, barrier_schedule <B, date, barrier_rate,...>
‘C’ for cap.
‘F’ for floor.
related issues. Example: For the swap curve, specify ‘S’.
5. maturity_date Required. Date specifying the maturity date of the last capped rate. That is, the time you
6. strike_rate Required. Number specifying the strike rate as a percent. Example: For 5.5%, specify 5.5.
7. rate_freq Required. Number specifying the rate reset frequency—the number of times per year the rate is
reset. Typically 1, 2, 4, or 12.
8. rate_basis Required. Text specifying the rate basis of first_reset_rate. This rate is converted to a bond
equivalent rate prior to cash flow mapping. Specify one of the following:
‘BE’ for Bond Equivalent (no conversion).
‘CD’ for Certificate of Deposit (or Libor).
‘D’ for Discount.
9. first_pmt_date Required. Date specifying the first payment date. This date can be for more than one
period forward for forward-starting instruments.
10. barrier_type Required. Text specifying the barrier type. Specify one of the following:
‘UPIN’ for an up-and-in barrier.
‘UPOUT’ for an up-and-out barrier.
‘DOWNIN’ for an down-and-in barrier.
‘DOWNOUT’ for an down-and-out barrier.
11. barrier_style Required. Text specifying the barrier exercise style. Specify one of the following:
‘EURO’ to evaluate the barrier once per caplet at the same time as the caplet is evaluated.
‘AMER’ to continuously monitor the barrier over the period before the caplet payout.
12. barrier Required. Number specifying the barrier level, as a percent. If you have a schedule of barriers,
enter the initial barrier here and the remainder in barrier_schedule below. Example: if the knock-in level is
3%, specify 3.
13. first_reset_rate Optional. Number specifying the floating rate set on the previous reset date, as a percent.
Required if the time to first_pmt_date is less than one period in the future. Example: For 5.5%, specify 5.5.
Example: A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
Example: K,1/1/1997,5.0,K,1/1/1998,5.5
16. barrier_schedule Optional. List specifying the barrier schedule of the instrument. Required for
instruments whose barrier changes over time, leave blank otherwise (this specifies a flat barrier curve at the
barrier level above). Each list element contains the following items:
1. Barrier indicator ‘B’.
2. Date the barrier changes—must fall on a payment date.
3. Barrier rate (as a percent) applying from this date until the next date.
Example: B,1/1/1997,5.0,B,1/1/1998,5.5
amort_schedule, strike_schedule, and barrier_schedule dates must fall before maturity_date.
FEA.
Plain barrier cap

C,USD,S,100,1/1/2005,5.5,1,BE,1/1/2001,DOWNOUT,EURO,1
*TYPE=BARRIERCAP2
*MODEL=BLACKY, or BLACKY-CS
This trade type provides more flexibility in specifying the terms of a Barrier Caps (floor) instrument. More
specifically: 1) the payment frequency of the instrument can be specified independently from the term of the
rate underlying the instrument (see pmt_term and rate_term), 2) if the floating leg rate is a CMS rate, a
distinct basis and payment frequency can be specified for such a rate (see cms_freq and cms_basis), 3) the
contract can pay in arrears of its reset or not (see arrears), 4) the user can specify how dates are rolled and
time is counted (see rollday and the new header DATEROLL), 5) the user has control over the interpolation
scheme used for the instrument valuation (see the new header INTERPOLATION), 6) a volatility curve can
be specified as input (see vol_schedule), or a whole smile surface can be used in pricing the instrument (see
Smile Data File on page 240). In addition, the choice of basis for the underlying rate now follows established
market conventions (see rate_basis).
cf_type, ccy, credit_rating, principal, maturity_date, strike_rate, pmt_term, rate_term, rate_basis,

first_pmt_date, barrier_type, barrier_style, barrier, first_reset_rate, cms_freq, cms_basis, arrears, rollday,
amort_schedule <A, date, amount,...>, strike_schedule <K, date, strike_rate,...>, barrier_schedule <B, date,
barrier_rate,...>, vol_schedule <M, date, vol,...>
‘C’ for cap.
‘F’ for floor.
7. pmt_term Required. String specifying the length of the accrual period between payments. It contains an
integer and a time unit indicator that is either ‚d‛ for business days, ‚m‛ for months, or ‚y‛ for years. E.g.,
‚5d‛ means five business days, ‚6m‛ means six months, ‚1y‛ means one year. For backward compatibility,
if the time unit indicator is not specified, the number is interpreted as the payment frequency: the number
of times per year that the cap (potentially) pays.
8. rate_term Optional. String specifying the maturity of the underlying rate in years. In the same format as
pmt_term, e.g., ‚5d‛ means five business days, ‚3y‛ means the three-year CMS rate. Defaults to pmt_term if
omitted. For backward compatibility, if the time unit indicator is not specified, the number is interpreted as
the maturity of the underlying interest rate in years, e.g., 0.25 for a 3-month rate, 3 for a 3-year CMS rate.
10. first_pmt_date Optional. Date specifying the first payment date. This date can be for more than one
12. barrier_style Required. Text specifying the barrier exercise style. Specify one of the following:
‘EURO’ to evaluate the barrier once per caplet at the same time as the caplet is evaluated.
‘AMER’ to continuously monitor the barrier over the period before the caplet payout.
13. barrier Required. Number specifying the barrier level, as a percent. If you have a schedule of barriers,
enter the initial barrier here and the remainder in barrier_schedule below. Example: if the knock-in level is
3%, specify 3.
15. cms_freq Optional. Number specifying the payment frequency (per year) of the CMS rate paid on the
floating leg. Defaults to the frequency corresponding to pmt_term, if omitted. Ignored if rate_term is less
than one.
Defaults to rate_basis, if omitted. Ignored if rate_term is less than one.
‘A0’ for Actual/360 (default)
17. arrears Optional. Text specifying whether the contract pays in arrears of its reset. The terminology to
describe this condition is ambiguous and varies between markets, so ours may appear intuitive in some
markets, and counter to convention in others.
‘TRUE’ The contract pays one reset period after the floating rate is set.
‘FALSE’ The contract resets the floating rate and pays at the same time.
Default value is TRUE.
Example: A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
Example: K,1/1/1997,5.0,K,1/1/1998,5.5
21. barrier_schedule Optional. List specifying the barrier schedule of the instrument. Required for
instruments whose barrier changes over time, leave blank otherwise (this specifies a flat barrier curve at the
barrier level above). Each list element contains the following items:
1. Barrier indicator ‘B’.
2. Date the barrier changes—must fall on a payment date.
3. Barrier rate (as a percent) applying from this date until the next date.
Example: B,1/1/1997,5.0,B,1/1/1998,5.5
1. Volatility indicator, ‘M’ for market (Black implied) volatilities.
2. Volatility date.
Example: M,1/1/1997,15.0,M,1/1/1998,20
If you provide both a vol_schedule and a VOLATILITY header value, vol_schedule prevails. If you specify a
volatility smile through the LOADMARKETDATA function, volatilities in the smile file prevail, but
vol_schedule data is still used, if specified, to compute convexity adjustments when they are required by the
term of the instrument.
amort_schedule, strike_schedule, and barrier_schedule dates must fall before maturity_date.
FEA.
Plain barrier cap

C,USD,S,100,1/1/2005,5.5,1Y,,A0,1/1/2001,DOWNOUT,EURO,1
*TYPE=BARRIEROPT
*MESHPOINTS=mesh-points [optional]
A barrier option is a European option that is either activated or terminated if the underlying asset price
reaches a specified barrier level.
There are four barrier conditions: up-and-in activation occurs if the underlying price moves above the barrier
price, an up-and-out termination occurs only if the underlying price stays below the barrier price, a down-and-
in activation occurs if the underlying price moves below the barrier price, and a down-and-out termination
occurs only if the underlying price stays above the barrier price. We call up-and-in and down-and-in options
knock-in options and up-and-out and down-and-out options knock-out options.
The barrier is monitored continuously through the life of the option, unless a monitoring time window is
specified in the trade record. After activation or before termination, barrier options behave identically to
ordinary European options. Since barrier options may never be activated or may be terminated, they carry a
lower initial fair value than ordinary European options.
barrier_type, ccy, asset, amount, pc_type, strike, opt_expiry, barrier, volatility, fut_expiry, risk_type,
dividend_yield, spot, beta, window_start, window_end, prew_vol, postw_vol
currency codes.
3. asset Required. Text specifying the underlying asset, which may be a currency, equity, or commodity. See
Assets for information on currency, equity, and commodity codes.
4. amount Required. Number specifying the amount of asset in millions of units. Specify a positive number if
you are long the contract or a negative number if you are short the contract. Examples: If the underlying of
amount is 100 million units of asset, specify 100. If a monthly on-peak power option calls for delivery of 100
MWh of power for 16 hours per day for 21 days then amount equals 0.0336 [= (100 * 16 * 21) / 1000000],
assuming that the prices in the volatility-correlation dataset are expressed per unit MWh. See Commodity
Futures for more information on the relation between amount and price.
6. strike Required. Number specifying the option’s strike price expressed as ccy per unit of asset.
7. opt_expiry Required. Date specifying the option’s expiration date.
8. barrier Required. Number specifying the barrier level, expressed in ccy terms.
volatility value and a VOLATILITY header value then volatility prevails. Example: for 25%, specify 25. If a
monitoring window is specified, see w_start and w_end below, the user is allowed to specify different
volatility inputs for the time period when the barrier is monitored, as well as for the periods preceding and
following monitoring of the barrier. The volatility input always applies to the time period when the barrier is
active. See prew_vol and postw_vol below for how to specify different volatilities over different periods.
10. fut_expiry Required if the option is on a futures contract, omit if the option is on a spot (physical) currency or
commodity. Date specifying the expiration date of the underlying future. fut_expiry must fall on or after
opt_expiry. See Remarks below for more information.
11. risk_type Required if the underlying is an equity. Text specifying the risk model to be used when
performing value at risk calculations. Specify one of the following:
‘S’ for a single factor model, using the individual equity as the source of risk.
‘B’ for a single factor model, using the specified equity_index as the source of risk.
12. dividend_yield Optional, only used if the underlying is an equity. Number specifying the annualized,
continuously-compounded dividend rate of the underlying equity, as a percent. If dividend_yield is omitted
then 0 (zero) is used. Example: for 5.5%, specify 5.5.
13. spot Optional, only used if the underlying is an equity. Number specifying the spot price of one share of the
underlying equity in ccy terms. For options on an equity futures, dividends and market interest rate
information are used to derive the futures price underlying the option. If the spot price of the equity is not
specified in the trade record, it must be contained in the appropriately defined asset file or volatility file.
14. beta Optional, only used if the underlying is an equity and risk_type=’B’. Number specifying the beta of the
underlying equity with respect to the market index. The market value of the equity at any time is related to
a stochastic market index I (normalized to one) using
market_value = spot * (1 + beta * ( I – 1 ))
15. w_start Optional. Date specifying when monitoring of the barrier starts. If omitted, it is assumed that the
barrier is monitored fromthe effective date of the calculation, i.e. from the date when the mark to market of
the instrument is computed.
16. w_end Optional. Date specifying when monitoring of the barrier ends. If omitted, it is assumed that the
barrier is monitored until option expiration.
17. prew_vol Optional. Number specifying the volatility of the underlying applying to the time period
preceding monitoring of the barrier. prew_vol only applies if w_start is specified. If omitted, it is assumed
that prew_vol is equal to the volatility input.
18. postw_vol Optional. Number specifying the volatility of the underlying applying to the time period
between w_end and expiry of the option. postw_vol only applies if w_end is specified. If omitted, it is
assumed that postw_vol is equal to the volatility input.
Specify volatility inputs with respect to ccy, regardless of the base or local currency of asset in the volatility-
For options on futures (fut_expiry specified), VaRworks calculates the underlying futures price by linearly
interpolating about fut_expiry using the asset forward price curve in the volatility-correlation dataset. For
options on a spot (physical) currency or commodity (fut_expiry omitted), the spot price of asset should be
present in the volatility-correlation dataset. See Commodity Instruments for more information.
The payoff (to the holder) from a continuously-monitored barrier call option is
Up-and-in: max(0, ST – K) if St > barrier for any t  T; zero otherwise.

Up-and-out: max(0, ST – K) if St < barrier for any t  T; zero otherwise.
Down-and-in: max(0, ST – K) if St < barrier for any t  T; zero otherwise.
Down-and-out: max(0, ST – K) if St > barrier for any t  T; zero otherwise.
The payoff (to the holder) from a continuously-monitored barrier put option is
Up-and-in: max(0, K – ST) if St > barrier for any t  T; zero otherwise.

Up-and-out: max(0, K – ST) if St < barrier for any t  T; zero otherwise.
Down-and-in: max(0, K – ST) if St < barrier for any t  T; zero otherwise.
Down-and-out: max(0, K – ST) if St > barrier for any t  T; zero otherwise.
where K is the strike price, barrier is the barrier price, time T is option expiry, S T is the underlying asset price
at option expiry.
The meshpoint header input is only used in the case of window barriers.
Barrier options are priced using FEA @GLOBAL models. For a technical discussion of pricing currency and
commodity derivatives see the @GLOBAL User’s Guide, available from FEA.
Also see Options.
US long call up-and-in WTI futures

UPIN,USD,WTI,25,C,14.5,8/1/2000,13.5,,12/1/2000
US long call up-and-in WTI futures, with barrier monitored before 7/1/2000
UPIN,USD,WTI,25,C,14.5,8/1/2000,13.5, ,12/1/2000, , , , , ,7/1/2000
US long call up-and-in WTI futures, with barrier monitored after 7/1/2000
UPIN,USD,WTI,25,C,14.5,8/1/2000,13.5, ,12/1/2000, , , , ,7/1/2000
Canadian short put down-and-in GAS

DOWNIN,CAD,GAS,-5,P,1.9,8/1/2000,2.2
GBP long call up-and-out EUR

UPOUT,GBP,EUR,2,C,2.3,1/1/2001,1.2
USD short put down-and-out GBP FX Forward

DOWNOUT,USD,GBP,-10,P,1.5,8/1/2000,1.6,,12/1/2000
USD short put down-and-out on USD index futures, 20% vol

DOWNOUT,USD,USD:SE,-10,P,1070,8/1/2004,1000,20,12/1/2004,S,2.2,1080
USD short put, down-and-out on equity (spot = 14) with 0.8 beta to USD index, no dividends, 40% vol
DOWNOUT,USD,USD:SE,-10,P,15,8/1/2004,10,40,12/1/2004,B,0,14,0.8
*TYPE=BESTOF
*MEANREVERSION=mean-reversion-rate1 [optional]
*MEANREVERSION2=mean-reversion-rate2 [optional]
*VOLATILITY=volatility1 [optional]
*VOLATILITY2=volatility2 [optional]
A best-of option, also known as a rainbow or outperformance option, is an option on the best performing (that
is, maximum or minimum) of a combination of assets. For example, suppose you own a best-of call option
struck at 50. If the price of asset 1 at expiry is 60 (weight1 = 1) and the price of asset 2 is 75 (weight2 = 1), the
option will pay out 75 - 50 = 25.
The prices of the n assets evolve according to a stochastic process where the n prices are lognormally
distributed and correlated. The correlations are described with a symmetric, positive-definite correlation
matrix.
ccy, asset1, asset2, asset3, pc_type, strike, opt_expiry, amount, weight1, weight2, weight3, corr12, corr13,
corr23, combo_type, strike1, strike2, strike3, vol1, vol2, vol3, risk_type, dividend_yield1, dividend_yield2,
dividend_yield3, spot1, spot2, spot3, beta1, beta2, beta3
currency codes.
2. asset1 Required. Text specifying the first underlying asset, which may be a currency, equity, or
commodity. See Assets for information on currency and commodity codes.
3. asset2 Optional. Text specifying the second underlying asset, which may be a currency, equity, or
4. asset3 Optional, ignored if asset2 not specified. Text specifying the third underlying asset, which may be a
currency, equity, or commodity. See Assets for information on currency and commodity codes.
‘C’ for call option (spread is bought).
‘P’ for put option (spread is sold).
6. strike Required. Number specifying the option’s strike price expressed in ccy units. The strike can be
positive, negative, or zero.
8. amount Optional. Number specifying the underlying amount, in millions, used to calculate the total
option position. If amount is omitted, it is assumed to be one.
9. weight1 Optional, ignored if asset1 not specified. Number specifying the weight of asset1. May be positive or
negative. If omitted, weight1 is assumed to be one.
10. weight2 Optional, ignored if asset2 not specified. Number specifying the weight of asset2. May be positive
or negative. If omitted, weight2 is assumed to be one.
11. weight3 Optional, ignored if asset3 not specified.. Number specifying the weight of asset3. May be positive
or negative. If omitted, weight3 is assumed to be one.
12. corr12 Required if asset2 is provided, ignored otherwise. Number between -1 and +1, inclusive, specifying
the correlation of asset1 and asset2.
13. corr13 Required if asset3 is provided, ignored otherwise. Number between -1 and +1, inclusive, specifying
the correlation of asset1 and asset3.
14. corr23 Required if asset2 and asset3 are provided, ignored otherwise. Number between -1 and +1, inclusive,
specifying the correlation of asset2 and asset3.
15. combo_type Optional, ignored if asset2 and asset3 not provided. Text specifying the combination of asset
prices defining the option’s payoff. The call payoff is max*0, combo(w1S1, w2S2, w3S3) - strike] and put payoff is
max[0, strike - combo(w1S1, w2S2, w3S3)] where wi is weight1, weight2, or weight3; Si is the spot price of asset1,
asset2, or asset3; and combo(w1S1, w2S2, w3S3) is determined by the value of combo_type, given in the table
below. If asset-specific strike prices are specified, replace the wiSi terms in the table below by wi(Si - ki) where
ki is strike1, strike2, or strike3. The table below indicates the valid combo_type values for a given set of n assets.
If combo_type is omitted, ‚MAX‛ is assumed.
No. Assets combo_type Combo(w1S1, w2S2, w3S3)
1 Ignored S1
2 ‚MIN‛ Min(w1S1, w2S2)
‚MAX‛ Max(w1S1, w2S2)
‚PROD‛ w1S1  w2S2
3 ‚MIN‛ Min(w1S1, w2S2, w3S3)
‚MAX‛ Max(w1S1, w2S2, w3S3)
‚MIN23‛ w1S1–min(w2S2, w3S3)
‚MAX23‛ w1S1–max(w2S2, w3S3)
‚MIN12‛ min(w1S1, w2S2)–w3S3
‚MAX12‛ max(w1S1, w2S2)–w3S3
16. strike1 Optional. Number specifying the asset-specific strike price of asset1, expressed in ccy terms. If
omitted, the value is assumed to be zero.
19. vol1 Optional if VOLATILITY header is specified, required otherwise. Number specifying the volatility
(annualized standard deviation) of the price of asset1 or the implied volatility, as a percent. If the
VOLATILITY header is omitted then you must specify the volatility in this field. If you provide both a vol1
value and a VOLATILITY header value then vol1 prevails. Example: for 25%, specify 25.
20. vol2 Ignored if asset2 omitted, optional if asset2 provided and VOLATILITY2 header is specified, required
otherwise. Number specifying the volatility (annualized standard deviation) of the price of asset2 or the
implied volatility, as a percent. If asset2 is provided and the VOLATILITY2 header is omitted then you must
specify the volatility in this field. If you provide both a vol2 value and a VOLATILITY2 header value then
vol2 prevails. Example: for 25%, specify 25.
21. vol3 Ignored if asset3 omitted, optional if asset3 provided and VOLATILITY3 header is specified, required
otherwise. Number specifying the volatility (annualized standard deviation) of the price of asset3 or the
implied volatility, as a percent. If asset3 is provided and the VOLATILITY3 header is omitted then you must
specify the volatility in this field. If you provide both a vol3 value and a VOLATILITY3 header value then
vol3 prevails. Example: for 25%, specify 25.
23. dividend_yield1 Optional, only used if asset1 is an equity. Number specifying the annualized, continuously-
compounded dividend rate of the first underlying equity (asset1), as a percent. If omitted then 0 (zero) is
used. Example: for 5.5%, specify 5.5.
compounded dividend rate of the second underlying equity (asset2), as a percent. If omitted then 0 (zero) is
25. spot1 Optional, only used if asset1 is an equity. Number specifying the spot price of one share of the equity
in ccy terms. If the spot price of the equity is not specified in the trade record, it must be contained in the
appropriately defined asset file or volatility file.
28. beta1 Optional, only used if asset1 is an equity and risk_type=’B’. Number specifying the beta of the equity
with respect to the market index. The market value of the equity at any time is related to a stochastic market
index I (normalized to one) using
29. beta2 Optional, only used if asset2 is an equity and risk_type=’B’. Number specifying the beta of the
underlying equity with respect to the market index.
Specify vol1, vol2, and vol3 with respect to ccy, regardless of the base or local currency of asset1, asset2, and
asset3 in the volatility-correlation dataset.
Interest rates are linearly interpolated about opt_expiry using the ccy swap (asset class S) interest-rate curves
The payoff (to the holder) at expiration from a best-of option (n assets) is
Call: 
max 0, combo w1S1,T , w2 S2,T ,, wn Sn,T   K 
Put: 
max 0, K  combo w1S1,T , w2 S2,T ,, wn Sn,T  
where K is the option’s strike price, wi is the weight of the i-th asset, Si,T is the spot price of the i-th asset at
option expiry. See the combo field for the definition of combo().
Also supported are asset-specific strike prices, which involve more general payoffs
Call: 
max 0, combo w1 ( S1,T  k1 ), w2 ( S2,T  k2 ),, wn ( Sn,T  kn )  K 
Put: 
max 0, K  combo w1 ( S1,T  k1 ), w2 ( S2,T  k2 ),, wn ( Sn,T  kn  
where ki is the asset-specific strike price of the i-th asset. For example, in fuel arbitrage the ki’s may be related
to fixed costs associated with using fuel i and wi’s may be related to the corresponding heat rates.
Examples of common asset combinations (the combo() function above) include the best-of payoff max(w1S1,T,
w2S2,T ,w3S3,T, w4S4,T), worst-of payoff min(w1S1,T, w2S2,T ,w3S3,T, w4S4,T), and spread payoff max(w1S1,T, w2S2,T) -
max(w3S3,T, w4S4,T). For asset-specific strike prices, replace each wiSi,T term with wi(Si,T - ki).
Above payoffs assume amount = 1, payoffs are proportional to amount.
Best-of options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
Also see Options.
Long call on minimum of WTI and GAS

USD,WTI,GAS,,C,5,1/1/2001,,1,7,,0.9,,,MIN
Short put on MAX23 of CAD,EUR,USD

USD,CAD,EUR,USD,P,0.2,1/1/2001,-100,1.2,,,0.9,0.8,0.7,MAX23
*TYPE=BOND
*MODEL=interest-rate-model
*VOLATILITY=short-term-rate-volatility
*MEANREVERSION=mean-reversion-rate
A bond is an instrument in which the issuer promises to repay the investor the amount borrowed, or
principal, plus interest over some specified period of time. The date on which the principal is required to be
repaid is the maturity date. Assuming the issuer does not default, the investor is assured of a known cash
flow pattern. The following types of bonds and enhancements supported:
Zero-coupon bonds pay no periodic interest. They are bought at a discount and pay face value at the
maturity date.
Coupon bonds pay an annual rate of interest on the bond’s face value called the coupon rate. Coupons are
certificates attached to the bond evidencing interest due on a payment date. The coupon frequency, or number
of times a year coupon interest is paid, is 2 for U.S. government bonds, typically 1 or 2 for European
government bonds, and frequently 4 for corporate bonds.
Typically there is a lag between the time a new bond is announced and sold (for an issue price) and the time
it is actually issued (on the issue date). During this interval, the security trades when-issued or ‚when, as,
and if issued.‛
The length of the first coupon period for coupon-bearing securities is sometimes other than the ‚normal‛
length for that security. The odd coupon can be either short (less than the normal length coupon) or long
(greater than the normal length coupon). Both short and long coupons are accounted for during cash flow
mapping.
The length of the last coupon period for coupon-bearing securities is sometimes other than the ‚normal‛
length for that security. The odd coupon can be either short (less than the normal length coupon) or long
(greater than the normal length coupon). Both short and long coupons are accounted for during cash flow
mapping.
One of the provisions in the contract between the issuer and bondholder might be that the issuer has the
right to retire or ‚call‛ all or part of the issue before the maturity date. Calls are often done at a call premium,
that is, a price higher than the face value of the bond. Call premiums diminish to zero as the bond
approaches maturity. Bonds are also occasionally puttable by the bondholder.
Indentures on corporate issues often require that the issuer make annual payments to a sinking fund, the
proceeds of which are used to retire randomly selected bonds in the issue.
ccy, credit_rating, principal, maturity_date, cpn_rate, cpn_freq, issue_date, issue_price, first_cpn_date,

last_cpn_date, call_schedule <C, date, price,...>, sinking_fund <S, date, prin_reduction,...>
2. credit_rating Required. Text specifying the bond issuer’s credit rating, which determines which yield
curve to use to discount cash flows. See Codes for a list of the credit rating codes. See The Euro for Euro-
related issues. Example: For a government bond, specify ‘Z’.
3. principal Required. Number specifying the bond’s principal in millions of local currency. Specify a
positive number for a long position or a negative number for a short position. See The Euro for Euro-related
issues. Examples: For a short position of 10 million, specify -10. For a long position of 500000, specify 0.5.
4. maturity_date Required. Date specifying the maturity date (not a call date) of the bond.
5. cpn_rate Required for coupon bonds. Number specifying the coupon rate as a percent. Example: For a 5.5%
coupon rate, specify 5.5.
6. cpn_freq Required for coupon bonds. Number specifying the coupon frequency—the number of times per
year a coupon is paid, typically 1, 2, 4, or 12.
7. issue_date Required for when-issued trades and odd-first coupon bonds. Date specifying the date of issue.
8. issue_price Required for when-issued trades and odd-first coupon bonds. Number specifying the issue price as
a percent of principal. Example: For 97%, specify 97.
9. first_cpn_date Required for odd-first coupon bonds. Date specifying the first coupon date—the ending date
of the first coupon’s interest period. Interest accrues from issue date until this date for the first coupon only.
Requires issue_date also.
10. last_cpn_date Required for odd-last coupon bonds. Date specifying the last coupon date—the starting date
of final coupon’s interest period. Interest accrues from this date until maturity for the last coupon only.
11. call_schedule Optional. List specifying the call schedule. Required for callable instruments only, leave
blank otherwise. Each list element contains the following items:
1. Call indicator ‚C‛.
2. Call date—must fall on a coupon date.
3. Price (percent of principal).
Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
Important Callable instruments take significantly more time to value than non-callable ones, particularly in
Monte Carlo simulation. You may want to consider omitting the call schedule. In many cases, this would
save considerable calculation time with only a small change in VaR.
12. sinking_fund Optional. List specifying the sinking fund (or amortization) schedule. Required for
instruments with sinking fund provisions only, leave blank otherwise. Each list element contains the
following items:
1. Sinking fund indicator ‚S‛.
2. Date—must fall on a coupon date.
3. Principal reduction (percent of original—not remaining—principal). Specify a positive number for
amortizing principal or negative number for accreting principal.
Example: A 5% and 10% sinking fund provision: S,1/1/2000,5,S,1/1/2005,10
Important If the instrument has a sinking fund but no call schedule, do not insert an extra field delimiter
(comma or semicolon) where the call schedule would normally appear. Specify the sinking fund
immediately following last_cpn_date.
Coupon dates are calculated by starting at maturity_date and working backwards in intervals of cpn_freq.
For callable bonds, do not specify the first call date in maturity_date. Specify a call schedule instead.
Call schedule dates and sinking fund dates cannot fall on or after maturity_date.
Sinking funds are not allowed for zero-coupon instruments.
For sinking funds, the percent principal reduction is a reduction of the original principal (not the remaining
principal) so all the reductions must sum to less than or equal to 100.
Zero-coupon bond
USD,Z,1,1/1/1997
Coupon bond
USD,Z,1,1/1/2020,7.5,2
When-issued zero-coupon bond

USD,Z,1,1/1/1999,,,1/1/1997,100
When-issued coupon bond

USD,Z,1,1/1/2020,7.5,2,1/1/1997,100
When-issued coupon bond, odd-first, odd-last coupon

USD,Z,1,1/1/2020,7.5,2,1/1/1997,100,4/1/1997,9/1/2019
Coupon bond with call schedule

USD,Z,1,1/1/2020,7.5,2,,,,,C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
Coupon bond with sinking fund but no call schedule

USD,Z,1,1/1/2020,7.5,2,,,,,S,1/1/2010,5,S,1/1/2012,10
Coupon bond with call schedule and sinking fund

USD,Z,1,1/1/2020,7.5,2,,,,,C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101,S,1/1/20
10,5,S,1/1/2012,10
*TYPE=BONDFORWARD
Bond forwards are forward contracts on bonds. As such, it is expected that underlying bond will be
delivered upon expiration of the forward contract. The deliverable bond is usually a specific issue, as
opposed to a bond futures contract, where the underlying is a usually a notional (theoretical) bond.
price, expiry_date, ccy, credit_rating, principal, maturity_date, cpn_rate, cpn_freq, issue_date, issue_price,
first_cpn_date, last_cpn_date, call_schedule <C, date, price,...>, sinking_fund <S, date, prin_reduction,...>
1. price Required. Number specifying the contract price paid as a percent of the face value of the underlying
bond. The price is always positive. Example: For a price of 108-16/32, specify 108.5.
2. expiry_date Required. Date specifying the forward’s expiration date.
3. ccy Required. Text specifying the local currency of the underlying bond. See Assets for information on
currency codes. See The Euro for Euro-related issues.
4. credit_rating Required. Text specifying the underlying bond issuer’s credit rating, which determines
which yield curve to use to discount cash flows. See Codes for a list of the credit rating codes. See The Euro
for Euro-related issues. Example: For a government bond, specify ‘Z’.
5. principal Required. Number specifying the underlying bond’s principal in millions of local currency.
Specify a positive number if you are buying the bond on expiry_date or a negative number if you are selling
the bond on expiry_date. See The Euro for Euro-related issues. Examples: If you are selling a bond with a face
value of 10 million, specify -10. If you are buying a bond with a face value of 500000, specify 0.5.
6. maturity_date Required. Date specifying the maturity date (not a call date) of the underlying bond.
7. cpn_rate Required for coupon bonds. Number specifying the coupon rate of the underlying bond as a
percent. Example: For a 5.5% coupon rate, specify 5.5.
8. cpn_freq Required for coupon bonds. Number specifying the coupon frequency of the underlying bond—
the number of times per year a coupon is paid, typically 1, 2, 4, or 12.
9. issue_date Required for when-issued trades and odd-first coupon bonds. Date specifying the date of issue of
the underlying bond.
10. issue_price Required for when-issued trades and odd-first coupon bonds. Number specifying the issue price
of the underlying bond as a percent of principal. Example: For 97%, specify 97.
11. first_cpn_date Required for odd-first coupon bonds. Date specifying the first coupon date of the underlying
bond—the ending date of the first coupon’s interest period. Interest accrues from issue date until this date
for the first coupon only. Requires issue_date also.
12. last_cpn_date Required for odd-last coupon bonds. Date specifying the last coupon date of the underlying
bond—the starting date of final coupon’s interest period. Interest accrues from this date until maturity for
the last coupon only.
Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
following items:
Fields 3–14 are identical to the fields for a bond record—they describe the contract’s underlying bond.
expiry_date must fall before maturity_date.
For bond futures use Bond Futures records.
Also see Remarks in Bonds.

FEA.
Coupon bond forward

99.125,1/1/1997,USD,Z,1,1/1/2020,8.00,2
*TYPE=BONDFUTURE
Bond futures are futures contracts on bonds. The underlying can be of two types. The first is a notional
(theoretical) bond, for example the CBOT 30-Year US Treasury Bond future or the MATIF Long-Term
Notional Government Bond future. The second type is a futures contract on a specific bond. The notional
type is more common.
When futures are based on notional bonds, the exchange has to specify which bonds are deliverable into the
futures contract. This changes periodically as outstanding issues get shorter and reach maturity. Because
bonds have different coupons, the exchange has to specify a conversion factor that allows those bonds to be
compared on equal basis to the notional underlying.
A bond’s conversion factor is the value of one unit if that bond were to trade at a yield-to-maturity equal to
that of the notional bond. Because of market conditions, some bonds are cheaper to deliver than others.
Accrued interest is also paid on the underlying bond.
num_contracts, price, fut_expiry, conversion_factor, ccy, credit_rating, size, maturity_date, cpn_rate,

cpn_freq, issue_date, issue_price, first_cpn_date, last_cpn_date, call_schedule <C, date, price,...>,
sinking_fund <S, date, prin_reduction,...>
1. num_contracts Required. Number specifying the number of futures contracts held. Specify a positive
number for a long position or a negative number for a short position. Examples: For a short position of 100
contracts, specify -100. For a long position of 500 contracts, specify 500.
2. price Required. Number specifying the futures contract purchase price as a percent of the face value of the
underlying notional bond. This is the agreed-upon exercise price of the contract to be paid or received on
fut_expiry. Example: For a price of 108-16/32, specify 108.5.
3. fut_expiry Required. Date specifying the future’s expiration date.
4. conversion_factor Required. Number specifying the conversion factor of the underlying bond. Conversion
factors are available from the exchange on which the contract is traded. If the underlying bond is a zero-
coupon bond or the contract is cash-settled, specify 1.
7. size Required. Number specifying the size of a single contract in millions of local currency, that is, the face
value of the underlying notional bond per contract. Specify a positive number regardless of whether you are
long or short futures contracts. See The Euro for Euro-related issues. Example: For a contract size of 100,000
specify 0.1.
9. cpn_rate Required for coupon bonds. Number specifying the coupon rate of the underlying bond as a
Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
following items:
Fields 5–16 are identical to the fields for a bond record—they describe the future’s underlying bond.
fut_expiry must fall before maturity_date.
price must be a decimal number, not 32nds.
Conversion factors are available from the exchange on which the contract is traded. If several bonds are
deliverable then there is a different conversion factor for each bond. Conversion factors don’t change over
the life of the contract.
The underlying bond specified should be the cheapest-to-deliver bond (unless you are holding a specific
bond to deliver against the contract, as in cash-and-carry arbitrage). If this information is unavailable specify
the underlying notional bond with a conversion factor of 1.0.
credit_rating is ‘Z’ (government) for all major bond futures contracts.
For bond forwards use Bond Forward records.
FEA.
CBOT US Bond future where the underlying is the notional bond

1,99.5,9/30/1996,1.00,USD,Z,0.1,1/1/2020,8.00,2
*TYPE=BONDFUTOPT
American and European options on bond futures are supported. See Bond Futures for more information.
ex_type, pc_type, strike, opt_expiry, num_contracts, fut_expiry, ccy, credit_rating, size, maturity_date,
cpn_rate, cpn_freq, volatility
1. ex_type Required. Text specifying the option exercise type. Specify one of the following:
‘A’ for American exercise.
‘E’ for European exercise.
Important American options take significantly more time to value than European options, particularly in
Monte Carlo simulation. You may want to consider specifying your American options as European. In many
cases, this would save considerable calculation time with only a small change in VaR.
‘C’ for call option (underlying future is bought).
‘P’ for put option (underlying future is sold).
3. strike Required. Number specifying the option’s strike price. The strike should be the quoted futures
strike times the conversion factor for the cheapest to deliver bond whose maturity and coupon are entered
below.
4. opt_expiry Required. Date specifying the option’s expiration date. This date must be on or before the
fut_expiry date.
5. num_contracts Required. Number specifying the number of option contracts held. Specify a positive
number for a long position or a negative number for a short position. Examples: For a short position of 100
contracts, specify -100. For a long position of 500 contracts, specify 500.
6. fut_expiry Required. Date specifying the underlying future’s expiration date.
9. size Required. Number specifying the size of a single contract in millions of local currency, that is, the face
value of the underlying notional bond per contract. Specify a positive number regardless of whether you are
long or short futures contracts. See The Euro for Euro-related issues. Example: For a contract size of 100,000
specify 0.1.
11. cpn_rate Required. Number specifying the coupon rate of the underlying bond as a percent. Example:
For a 5.5% coupon rate, specify 5.5.
12. cpn_freq Required. Number specifying the coupon frequency of the underlying bond—the number of
times per year a coupon is paid, typically 1, 2, 4, or 12.
13. volatility Optional if VOLATILITY header is specified, required otherwise. The volatility parameter used when
pricing the option. If you provide both a value in this field and a VOLATILITY header, this field prevails.
Example: for 25%, specify 25.
opt_expiry must fall on or before fut_expiry, which must fall before maturity_date.
For options on bonds, see Bond Options.
See Remarks in Bond Futures and Bonds for more information.

See the discussion of Bond Futures Options in the Technical Reference section for information on how this
instrument is valued.
FEA.
CBOT US Bond futures American call option where the underlying is the notional bond.
A,C,100,1/1/1999,1,1/1/1999,USD,Z,0.1,1/1/2020,8.00,2
*TYPE=BONDOPTION
American and European options on coupon and zero-coupon bonds are supported. The following
conventions are used for the receipt of coupons: 1) European call holders do not receive and put holders do
not pay the coupon if the option is exercised on a coupon date, 2) American options can be exercised at any
time so call holders can receive the coupon.
ex_type, pc_type, strike, opt_expiry, volatility, ccy, credit_rating, principal, maturity_date, cpn_rate,
cpn_freq, issue_date, issue_price, first_cpn_date, last_cpn_date, call_schedule <C, date, price,...>,
‘C’ for call option (underlying bond is bought).
‘P’ for put option (underlying bond is sold).
3. strike Required. Number specifying the option’s strike price as a percent of the underlying bond’s
principal.
5. volatility Optional if VOLATILITY header is specified, required otherwise. The volatility parameter used when
pricing the option. If you provide both a value in this field and a VOLATILITY header, this field prevails.
8. principal Required. Number specifying the underlying bond’s face value in millions of local currency.
Specify a positive number if you are long the option or a negative number if you are short the option. See
The Euro for Euro-related issues. Example: If you are long an option on a bond with a face value of 100000,
specify 0.1.
10. cpn_rate Required for coupon bonds. Number specifying the coupon rate of the underlying bond, as a
Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
following items:
Fields 6–17 are identical to the fields for a bond record—they describe the option’s underlying bond.
opt_expiry must fall before maturity_date.
Call schedules are not supported; if you specify a call schedule, it is ignored.
Include accrued interest in strike. For example, if the option’s strike price is 100 and three months have
passed since the previous, say, 6% annual coupon payment, then strike should be 100 + 0.06 * 0.25 = 100.015.
For options on bond futures, see Options on Bond Futures.
FEA.
European call on a coupon bond

E,C,100,1/1/1997,,USD,Z,100,1/1/2010,8,2
American put on a zero-coupon bond

A,P,101,1/1/1997,,GBP,Z,100,1/1/1998
*TYPE=BRADY
Important Brady bonds are not supported by the RiskMetrics dataset.
The Brady bond market was established in response to the developing country debt crisis of the 1980s. The
Brady plan, named for then-U.S. Treasury Secretary Nicholas Brady, allowed for the restructuring of
developing nation debt to foreign commercial banks into bond form, extending the maturity and in many
cases backing the principal of the new bonds with U.S. Treasury securities, ensuring that a Brady bond’s
principal would be repaid.
Terms of individual Brady packages vary. Individual countries have issued Brady bonds which vary with
respect to maturity, fixed or floating coupons, amortization schedules, and the degree to which principal
and interest payments are collateralized. Bonds issued by Mexico, Brazil, Argentina, and Venezuela account
for about 85% of the total face value of outstanding Brady bonds. Brady bonds are usually U. S. dollar-
denominated.
denomination_ccy, local_ccy, bond_type, market_value, face_value, market_price
1. denomination_ccy Required. Text specifying the currency the Brady Bond is denominated in—usually
USD.
2. local_ccy Required. Text specifying the local currency of the country issuing the Brady Bond. See Remarks
below for a list of Brady bond currencies. Examples: MXN, BRL, ARS, VEB.
3. bond_type Required. Text specifying the user-defined type of Brady bond. See Remarks below for a list of
suggested Brady bond types.
4. market_value Required if face_value is omitted. Number specifying the market value of the Brady bond in
millions of denomination_ccy. Specify a positive number for a long position or a negative number for a short
position. Examples: For a short position of 10 million, specify -10. For a long position of 500,000 specify 0.5.
5. face_value Required if market_value is omitted. Number specifying the face value of the Brady bond in
millions of denomination_ccy. Specify a positive number for a long position or a negative number for a short
position. Examples: For a short position of 10 million, specify -10. For a long position of 500,000 specify 0.5.
6. market_price Optional, applies only if face_value is specified, ignored otherwise. Number specifying the
market price of the Brady bond as a percent of the face value. Example: for a price of 85% of face value,
specify 85.
There are two ways to specify a Brady bond position: either specify market_value or face_value, not both. If
you specify both then market_value prevails.
If you specify face_value (and not market_value) then the market value of the position is calculated by
multiplying face_value by the bond price in the volatility file. You can override the volatility file bond price
by specifying market_price.
Cash flows are denominated in denomination_ccy and mapped to the local_ccy vertex in the bond_type asset
class.
The VaR of a Brady bond is calculated by multiplying its market (present) value in denomination_ccy by its
price volatility. local_ccy exchange rates and interest rates are not used.
Brady bond foreign exchange risk is generated if your home currency is not the denomination currency. For
example, a USD-based investor has foreign exchange risk investing in EUR-denominated Brady bonds but
no foreign exchange risk investing in USD-denominated Brady bonds. A MXN-based investor has foreign
exchange risk investing in USD- or EUR-denominated Brady bonds, even Mexican Brady bonds.
Suggestions for Brady Bonds
Country (local_ccy) bond_type Bond description

Argentina (ARS) G01 Floating Rate Bond (FRB)
G02 Par
G03 Discount
Country (local_ccy) bond_type Bond description

Brazil (BRL) G01 C
G02 Eligible Interest (EI)
G03 Par ZL
G04 Discount Z
G05 DCB L
Bulgaria (BGL) G01 Discount A

G02 IAB
G03 FLIR A
Ecuador (ECS) G01 Discount

G02 PDI
G03 Par
Mexico (MXN) G01 Par Series A

G02 Discount D
G03 Aztec
Nigeria (NGN) G01 Par

G02 Prom Note
Panama (PAB) G01 PDI

G02 IRB
G03 Par
Philippines (PHP) G01 Par B

G02 DCB B
G03 FLIRB B
G04 NMB
Poland (PLN) G01 PDI

G02 Discount
G03 Par
G04 RSTA
Russia (RUR) G01 Minfin 4

G02 Minfin 3
G03 Minfin 5
Venezuela (VEB) G01 Par W-A

G02 DCB DL
G03 FLIRB A
G04 Discount WA
Long USD 135 million (market value) Mexican Aztec bonds

USD,MXN,G03,135
Short USD 100 million (face value) Argentinean floating rate bonds (use volatility file price)
USD,ARS,G01,,-100
Long USD 100 million (face value) Venezuelan Discount WA bonds (priced at 67.250% of par)
USD,VEB,G04,,100,67.250
*TYPE=CALSPREAD
A spread option is an option on the price differential between two underlying assets. The net equivalent
positions, or weights, of the assets have opposite signs (for example, +1 and -1). Weights are netted together
for a single ‚basket‛ value, which settles against the option’s strike price. A positive weight indicates a long
position, a negative weight a short one.
For example, suppose you own a call spread option struck at 20. If the price of asset 1 at expiry is 100
(weight1 = 1) and the price of asset 2 at expiry is 30 (weight2 = -1), the spread option will pay out (100 - 30) -
20 = 50.
A calendar spread option is similar to an ordinary spread option except the price differential is between two
forward or futures contracts with different maturities on the same underlying asset.
The prices of the two assets evolve according to a stochastic process where the two prices are lognormally
distributed and correlated. The correlation is specified with a number between –1 and +1, exclusive.
ccy, asset, pc_type, strike, opt_expiry, fut_expiry1, fut_expiry2, amount, weight1, weight2, corr, vol1, vol2
currency codes.
4. pc_type Required. Text specifying if the option is a call or put. Specify one of the following:
5. strike Required. Number specifying the option’s strike price expressed in ccy units. The strike can be
7. fut_expiry1 Required. Date specifying when the first forward or futures contract expires. Note that
fut_expiry1 must fall strictly before fut_expiry2.
8. fut_expiry2 Required. Date specifying when the second forward or futures contract expires.
10. weight1 Optional. Number specifying the weight to be assigned to the first forward or futures contract.
May be positive or negative. If weight1 is omitted, it is assumed to be +1.
11. weight2 Optional. Number specifying the weight to be assigned to the second forward or futures
contract. May be positive or negative. If weight2 is omitted, it is assumed to be -1.
12. corr Required. Number between -1 and +1, inclusive, specifying the correlation between the spot (or
front-month) price and the fut_expiry2 - fut_expiry1 constant-maturity futures price. Example: If the spread is
between a six-month futures contract and a nine-month futures contract, enter the correlation between the
front-month and the three-month constant-maturity futures prices.
13. vol1 Optional if VOLATILITY header is specified, required otherwise. Number specifying the spot or implied
volatility (annualized standard deviation) corresponding to the first forward or futures contract, expressed
as a percent. If the VOLATILITY header is omitted, you must specify the volatility in this field. If you
provide both a vol1 value and a VOLATILITY header value, vol1 prevails. Example: for 25%, specify 25.
14. vol2 Optional if VOLATILITY2 header is specified, required otherwise. Number specifying the spot or
implied volatility (annualized standard deviation) corresponding to the second forward or futures contract,
expressed as a percent. If the VOLATILITY2 header is omitted, you must specify the volatility in this field. If
you provide both a vol2 value and a VOLATILITY2 header value, vol2 prevails. Example: for 25%, specify
25.
Specify vol1 and vol2 with respect to ccy, regardless of the base or local currency of asset1 and asset2 in the
volatility-correlation dataset. The volatilities must be entered as spot or implied volatilities.
Interest rates are linearly interpolated about opt_expiry, fut_expiry1, and fut_expiry2 using the ccy swap (asset
class S) interest-rate curves in the volatility-correlation dataset.
The payoff (to the holder) at expiration from a calendar spread option is
Call:   
max 0, w1FT ,t1  w2 FT ,t2  K 
Put:  
max 0, K  w1FT ,t1  w2 FT ,t2 
where T is the time of option expiry, t (> T) is the time of the forward or futures expiration, K is the strike
price, wi is the weight assigned to the forward or futures contract, FT,t(i) is the forward price observed at time
T, with expiration at time ti.
Spread options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
Also see Spread Options.
Short EUR call spread on 6-month, 12-month GAS futures (as of 1/1/2000)
EUR,GAS,C,0.5,4/1/2000,7/1/2000,1/1/2001,-10,1,-0.9,0.85
Long put spread on 6-month, 12-month USD/EUR exchange rate (as of 1/1/2000)
EUR,USD,P,0.1,4/1/2000,7/1/2000,1/1/2001,,-0.9,1,0.9
*TYPE=CAPFLOOR
A cap is a contract where the seller agrees to pay the purchaser, in return for a premium, the difference
between a reference rate (typically three- or six-month Libor) and a strike rate when the reference exceeds
the strike. A floor is a contract where the seller agrees to pay the purchaser, in return for a premium, the
difference between a reference rate and a strike rate when the strike exceeds the reference.
Caps and floors are strips of options on forward rate agreements that allow the purchaser to take advantage
of movements in interest rates. They are priced as the sum of the cost of individual options (called caplets or
floorlets).
This is a deprecated trade instrument provided for backward compatibility. The trade instrument Caps and
Floors (type II) is a replacement for this trade instrument. The new trade type provides more flexibility in
specifying the terms of a cap (floor) instrument.
cf_type, ccy, credit_rating, principal, maturity_date, strike_rate, rate_freq, rate_basis, first_pmt_date,

first_reset_rate, amort_schedule <A, date, amount,...>, strike_schedule <K, date, strike_rate,...>
‘C’ for cap.
‘F’ for floor.
7. rate_freq Required. Number specifying the rate reset frequency—the number of times per year the rate is
reset. Typically 1, 2, 4, or 12.
8. rate_basis Required. Text specifying the rate basis of first_reset_rate. This rate is converted to a bond
9. first_pmt_date Required. Date specifying the first payment date. This date can be for more than one
Example: A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
3. New strike rate or price.
Example: K,1/1/1997,5.0,K,1/1/1998,5.5
schedule fund immediately following first_reset_rate.
FEA.
Cap with amortization and strike schedules

C,USD,S,100,1/1/2005,5.5,2,BE,1/1/1997,5.8,A,1/1/1998,10,A,6/1/1999,10,K,1/1/200
0,5.75,K,1/1/2001,6.0
Floor
F,USD,S,-10,1/1/2000,8,1,CD,1/1/1997,7.75
*TYPE=CAPFLOOR2
*CORRELATION=correlation [optional]
*TREESTEPS=tree-steps
*CPNTYPEDATE=type,date
A cap is a contract where the seller agrees to pay the purchaser, in return for a premium, the difference
between a reference rate (typically three- or six-month Libor) and a strike rate when the reference exceeds
the strike. A floor is a contract where the seller agrees to pay the purchaser, in return for a premium, the
difference between a reference rate and a strike rate when the strike exceeds the reference.
Caps and floors are strips of options on forward rate agreements that allow the purchaser to take advantage
of movements in interest rates. They are priced as the sum of the cost of individual options (called caplets or
floorlets).
cf_type, ccy, credit_rating, principal, maturity_date, strike_rate, pmt_term, rate_term, rate_basis,

first_pmt_date, first_reset_rate, cms_freq, cms_basis, arrears, rollday, is_quanto, quanto_ccy,
quanto_credit_rating, amort_schedule <A, date, amount,...>, strike_schedule <K, date, strike_rate,...>,
vol_schedule <M1, date, vol,...>, vol2_schedule <M2, date, vol,...>, corr_schedule <CORR, date, vol,...>
‘C’ for cap.
‘F’ for floor.
6. strike_rate Required. Number specifying the strike rate as a percent. E.g., specify 5.5 for 5.5%.
Required if the time to first_pmt_date is less than one period in the future. E.g., specify 5.5 for 5.5%.
12. cms_freq Optional. Number specifying the payment frequency (per year) of the CMS rate paid on the
floating leg. Defaults to the frequency corresponding to pmt_term, if omitted. Ignored if rate_term is less than
one.
16. is_quanto Optional. Text specifying whether the swap is a quanto instrument.
‘TRUE’ The contract is a quanto instrument.
‘FALSE’ The contract is not a quanto instrument.
Default value is FALSE.
17. quanto_ccy Optional. Text specifying the foreign currency for the quanto swap. See Assets for
information on currency codes. See The Euro for Euro-related issues.
18. quanto_credit_rating Optional. Text specifying the credit rating of the foreign currency for the quanto
swap. See Codes for a list of the credit rating codes. See The Euro for Euro-related issues. E.g., specify ‘S’ for
a swap curve.
E.g., A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
E.g., K,1/1/1997,5.0,K,1/1/1998,5.5
21. vol_schedule Optional. List specifying the volatility of the underlying rate, as a percent. Each list
element contains the following items:
2. Volatility date.
If you provide both a vol_schedule and a VOLATILITY header value, and the model is BLACKY, vol_schedule
prevails. If you specify a volatility smile through the LOADMARKETDATA function, volatilities in the
smile file prevail, but vol_schedule data is still used, if specified, to compute convexity adjustments when
they are required by the term of the instrument. Vol_schedule and smile data are only used if the interest
rate model specified in the header is BLACKY.
E.g., M1,1/1/1997,15.0,M1,1/1/1998,20
22. vol2_schedule Optional. List specifying the volatility of the foreign exchange rate, as a percent. Used
only if the interest rate model specified in the header is BLACKY and if is_quanto is set to true. Each list
2. Volatility date.
If you provide both a vol_schedule and a VOLATILITY header value and if the interest rate model specified
in the header is BLACKY, vol_schedule prevails.
E.g., M2,1/1/1997,15,M2,1/1/1998,20
23. corr_schedule Optional. List specifying the correlation between the foreign exchange rate and the
underlying rate, between and including -1 and +1. Used only if the interest rate model specified in the
header is BLACKY and if is_quanto is set to true. Each list element contains the following items:
1. Correlation indicator, ‘CORR’ for market (Black implied) correlations.
2. Correlation date.
3. Correlation value.
E.g., CORR,1/1/1997,0.15,CORR,1/1/1998,0.20
schedule fund immediately following quanto_credit_rating.
FEA.
Cap with amortization and strike schedules

C,USD,S,100,1/1/2005,5.5,2,,A0,1/1/1997,5.8,,,,,A,1/1/1998,10,A,6/1/1999,10,K,1/
1/2000,5.75,K,1/1/2001,6.0
Floor
F,USD,S,-10,1/1/2000,8,1,,A0,1/1/1997,7.75
*TYPE=CASHFLOW
*INTERPOLATION= interpolation [optional] (LINEAR, SPLINE); Spline interpolation on rates is only
supported for credit_rating equal to R, S, Z, AGY, AAA, AA, A, BBB, BB, B, CCC, D, or custom ratings.
For instruments not directly supported, you can specify your own cash flow maps. This is useful for exotic
instruments and instruments with irregular payment schedules.
asset_code, credit_rating, value_date, amount
1. asset_code Required. Text specifying a currency or commodity code, or equity name. See Assets for
information on asset codes.
2. credit_rating Required. Text specifying the credit rating of the cash flow. This determines which yield
curve is used to discount cash flows. Valid credit_rating values follow:
credit_rating Asset class

XS Spot foreign exchange (spot only, value_date ignored)
R Money market
S Swap
Z Government
AGY Government Agency
AAA,AA,A,BBB,BB,B,C Corporate
CC,D
Cutom rating See Codes for how to specify a custom credit rating.
C Commodity
SE Spot equity index (spot only, value_date ignored)
G Brady bond (spot only, value_date ignored)
Any in-Euro ccy code See The Euro for more information.
3. value_date Required. Date specifying when the cash flow is going to take place.
4. amount Required. Number specifying the amount of the cash flow in millions of local currency. Specify
positive numbers for cash inflows (cash you receive) and negative numbers for cash outflows (cash you
pay). See The Euro for Euro-related issues. Examples: For a cash inflow of 10 million, specify 10. For a cash
outflow of 500,000 specify -0.5. If asset represents a commodity, amount is the number of units of that
commodity that are received (amount > 0) or paid (amount < 0) on value_date.
It is possible to describe any instrument as a series of dated cash flows.
If a cash flow has a spot credit rating (XS, SE, and G) then value_date is ignored and the cash flow is always
mapped to a spot vertex.
Commodity cash flows (asset class C) can also be specified as Commodity Futures records.
If the amount of the cashflow is uncertain, VQCASHFLOW can be used.
Short 100 million Japanese Yen (a zero-coupon bond)

JPY,S,01/01/1998,-100
*TYPE=COMMODITYFUT
Commodities risks arise both in the spot market (you purchase a product today and store it over time) and
the futures market (physical delivery of a product in the future). Commodity futures contracts enable
investors to trade products for future delivery and provide information about the term structure of
commodities prices. Commodities can therefore be evaluated as a sequence of cash flows.
ccy, commodity, num_contracts, delivery_price, contract_size, fut_expiry, carry_credit_rating
currency codes.
2. commodity Required. Text specifying the contract’s underlying commodity. See Assets for information on
commodity codes.
number for a long position or a negative number for a short position. Examples: If you are short 100
contracts, specify -100; if you are long 500 contracts, specify 500.
4. delivery_price Optional. Number specifying the delivery price of the contract. For forward contracts,
delivery_price is the price the holder is obliged to pay or receive on fut_expiry for one unit of commodity. For
futures contracts, delivery_price can be either the:
 price of the futures contract when it was purchased/sold (recommended), or the
 current price of the futures contract.
Specifying the futures purchase price accounts for margin payments. If you specify the current futures price
then you must enter day-to-day margin payments separately as cash flows. Express delivery_price as units of
ccy per one unit of commodity. This number is always positive. Example: If you bought a NYMEX light,
sweet crude oil future for $18.30/barrel, specify 18.3.
If omitted delivery_price is determined to make the Mark to Market of the trade equal to zero.
5. contract_size Required. Number specifying the size of a single futures contract in millions, that is, the
number of units of commodity the holder is obliged to take or make delivery of on fut_expiry, divided by
1,000,000. Specify a positive number regardless of whether you are long or short futures contracts. Do not
multiply contract_size by the number of contracts held. Examples: If you hold a NYMEX light, sweet crude
oil future (symbol CL) for 1,000 barrels of oil, specify 0.001 [= 1000 / 1000000]. If you hold a NYMEX Henry
Hub natural gas future (symbol NG) for 10,000 million British thermal units (MMBtu), specify 0.01 [= 10,000
/ 1000000].
6. fut_expiry Required. Date specifying the future’s expiration date.

7. carry_credit_rating Optiona l.Text specifying the custom credit rating identifying the rate curve used as
carry rate. See Codes for a list of the credit rating codes. Specify this input if you want to decompose risk in
terms of a spot price risk and carry_rate risk, instead of price risk associated to different points in the futures
price curve.
Commodity futures are discounted using the swap yield curve for ccy.
CASHFLOWMAP maps commodity futures cash flows to the vertices shown in the table below. (If
delivery_price is zero then the x cash flows are omitted.)
Asset Class (vertex code) ccy home_ccy commodity ccy commodity

Spot FX (XS) x+y
Interest rate(R,S,Z,AGY, x y
AAA,AA,A,BBB,BB,B,
CCC,D)
Commodity (C) y
num_contracts is the number of commodity futures contracts, N, multiplied by +1 or -1 to indicate a long or

short position.
delivery_price (K) and the quoted price, F, provided in the volatility-correlation dataset must refer to the
same unit of underlying commodity, referred to below as the quoted quantity. (If F and K are not of the
same currency, then VaRworks will automatically convert them into the same currency using prevailing
exchange rates contained within the volatility-correlation dataset.)
contract_size (Q) is the quoted contract in units of the quoted quantity.
So, if prevailing exchange rates are such that there are X1 units of home currency per settlement currency
and X2 units of settlement currency per quoted currency, then the future value at expiration (not the present
value) of a commodity futures (or forward) trade is
X1  num_contracts  contract_size  (X2  F – delivery_price).
In terms of N, K, and Q, this is
(+/-)  X1  N  Q  (X2  F – K)
For example, consider a long position of one NYMEX heating oil futures contract with quoted price of 0.5277
USD per gallon, struck at 0.5 USD per gallon. The contract size is 1,000 US barrels and expires three months
from the effective date 4/28/1998. Therefore, F = 0.5277, N = 1, K = 0.5, and X1 = X2 = 1. The contract size Q
must be given in the quoted units, that is, gallons Q = 42,000, and to express the trade in millions of unit of
curreny, it must be divided by 1,000,000. So
num_contracts = 1
delivery_price = 0.5
contract_size = 42,000 / 1,000,000 = 0.042
The trade would be specified with the following record:
USD,HTO,1,0.5,0.042,7/28/1998
where HTO is the user-defined designation for the commodity. In this case, the (above) future value would
be
1  1  0.042  (1  0.5277 – 0.5) = 0.00116
This is also the future value of the cash flow paid out at 7/28/1998, representing interest-rate exposure.
Exposure to the underlying commodity corresponds to a cash flow of 0.042  0.5277 = 0.02216, also paid out
at 7/28/1998, and also in future value terms.
Note that F, the futures price of the contract expiring on fut_expiry date, is either obtained from the futures
price curve specified in the dataset or, if a carry rate curve is specified via the carry_credit_rating input, by
the formula F=S exp(rcarryT), where T is the time to expiry, rcarry is the corresponding carry rate obtained
from the specified carry rate curve input, and S is the spot price obtained from the price of the
corresponding C00 commodity vertex.
For a technical discussion of pricing currency and commodity derivatives see the @GLOBAL User’s Guide,
available from FEA.
Short one NYMEX light, sweet crude oil future (1000 barrels) @ $18.30 expiring 1/20/1998
USD,WTI,-1,18.30,0.001,1/20/1998
Long one NYMEX Henry Hub natural gas future (10,000 MMBtu) @ $2.50 expiring 1/28/1998
USD,GAS,1,2.50,0.01,1/28/1998
*TYPE=INDEXSWAP
A commodity index swap is a series of forward contracts used to lock in a fixed price of a commodity. One
party (typically a commodity user) agrees to pay a fixed payment and receive a floating payment for a
specified amount of a commodity over a specified period of time. The counterparty (typically a commodity
supplier) pays a floating payment and receives a fixed payment. Swap settlements are made in cash at
(typically) regular intervals—usually monthly. Settlement equals the difference between the floating
payment and the fixed payment. The floating payment is often linked to the average of a reference price
over some predetermined averaging period.
When the market price falls, the swap’s cash outflows offset the reduction in the commodity user’s spot
purchase costs. When the market price rises, the swap’s cash inflows offset the increase in the commodity
user’s spot purchase costs. The net result is a fixed price for the commodity user.
Commmodity Index Swap
First average starts Settlement dates
Value date
t0 t1 t2 t3 t4
First settlement period

Averaging interval
ccy, asset, fixed_price, avg_interval, first_avg_starts, running_avg, first_fut_expiry, settle_curve
currency codes.
2. asset Required. Text specifying the underlying asset (usually a commodity). See Assets for information on
asset codes.
3. fixed_price Required. Number specifying the fixed-leg price of asset expressed in ccy units.
4. avg_interval Required. Number specifying the time interval in years between fixings during each
averaging period. For example, 1/365 for daily calendar-day fixings or about 1/250 for daily business-day
fixings.
5. first_avg_starts Required. Date specifying when the first fixing occurs. Averaging dates in the first
settlement period are derived by counting backwards from the first date in settle_curve in time intervals of
avg_interval years until first_avg_starts. first_avg_starts is rounded to coincide with the nearest valid
averaging date. Averaging dates in the i-th settlement period (i > 1) are derived by counting backwards from
the (i + 1)-th date in settle_curve in time intervals of avg_interval years until the first averaging date following
the i-th date in settle_curve is reached. first_avg_starts must fall on or before the first date in settle_curve.
6. running_avg Required if the effective_date falls on or after first_avg_starts. Number greater than zero
specifying the average price for the current settlement period established up to the effective calculation date
by past price observations. running_avg applies only if the effective date falls after first_avg_starts and is
ignored otherwise. Update running_avg as the swap nears maturity. If running_avg is omitted when required
then an error message is returned.
7. first_fut_expiry Optional. Date specifying the expiry date of the futures contract linked to the first
averaging period’s initial fixing. first_fut_expiry, if specified, is typically the first futures date falling on or
after first_avg_starts. The first floating payment is the arithmetic average of futures prices observed over an
averaging period beginning at first_avg_starts and ending on the first date in settle_curve, inclusive, with a
sampling interval of avg_interval years (for example, avg_interval equals 1/365 for a daily calendar-day
average or 1/12 for a monthly average). The futures contract whose price is used in the average is the one
expiring on first_fut_expiry for averaging dates falling on or before first_fut_expiry. If some averaging dates
fall after first_fut_expiry, then subsequent fwd_curve futures are used until the first date in settle_curve is
reached. Subsequent floating prices paid on remaining settlement dates, if any, are constructed analogously
by shifting first_avg_starts, the first date in settle_curve, and first_fut_expiry by the interval between the two
relevant settlement dates in settle_curve. If first_fut_expiry is omitted, the averaging dates are as defined
above but the floating price used on each averaging date is the spot price obtained by interpolating between
forward curve points.
8. settle_curve Required. List specifying the swap’s settlement dates and settlement amounts. Each list
element contains the following delimited items:
1. Settlement curve indicator ‚T‛.
2. Settlement date. Settlement dates must be in strictly increasing order. Typically these dates are
(approximately) evenly spaced, for example, monthly settlements, but arbitrarily spaced dates are
permitted. The last date specifies the swap’s maturity.
3. Settlement amount (millions of ccy). Amount of asset used to calculate the payment. Specify positive
amounts for a long swap position (pay fixed, receive floating) or negative amounts for a short swap position
(pay floating, receive fixed). Mixed signs are not permitted.
Example: T,1/1/1999,1,T,2/1/1999,1,T,3/1/1999,1
Commodity index swaps are discounted using the swap yield curve for ccy. Valuation is performed by
using the @ENERGY function INDEXSWAP.
For a precise definition of the average used to calculate the floating price, see the first_avg_starts and
first_fut_expiry fields.
Long (fixed) CAD for (floating) GAS swap

CAD,GAS,2.0,0.0027,4/1/1999,0,4/2/1999,T,5/1/1999,10,T,8/1/1999,100,T,2/1/2000,1
0
Short (fixed) GBP for (floating) EUR swap

GBP,EUR,0.6,0.08333,4/1/1999,0.6,,T,5/1/1999,-5,T,8/1/1999,-10,T,2/1/2000,-15
*TYPE=OPTINDEXSWAP
*TREESTEPS=tree-steps [optional]
A commodity index swap option, or commodity swaption, is an option to enter a commodity index swap
contract (See Commodity Index Swaps for more information). The underlying swap always begins when the
(user-specified) first fixing occurs, regardless of when the option is exercised.
ccy, asset, fixed_price, avg_interval, first_avg_starts, ex_type, pc_type, strike, opt_expiry, volatility,
first_fut_expiry, settle_curve
currency codes.
2. asset Required. Text specifying the underlying commodity. See Assets for information on commodity
codes.
3. fixed_price Required. Number specifying the fixed-leg price of asset expressed in ccy units.
4. avg_interval Required. Number specifying the time interval in years between fixings during each
fixings.
5. first_avg_starts Required. Date specifying when the first fixing occurs. Averaging dates in the first
settlement period are derived by counting backwards from the first date in settle_curve in time intervals of
avg_interval years until first_avg_starts. first_avg_starts is rounded to coincide with the nearest valid
the (i + 1)-th date in settle_curve in time intervals of avg_interval years until the first averaging date following
the i-th date in settle_curve is reached. first_avg_starts must fall on or before the first date in settle_curve.
6. ex_type Required. Text specifying the option exercise style. The underlying swap begins first_avg_starts,
regardless of when the (American) option is exercised. Specify one of the following:
7. pc_type Required. Text specifying if the option is a call, put, or straddle. Specify one of the following:
‘C’ for call option (underlying asset is bought).
‘P’ for put option (underlying asset is sold).
‘S’ for a straddle (a put and a call with the same strike).
8. strike Optional. Number specifying the option’s strike price per unit of asset expressed in ccy units. If
strike is omitted, it is assumed to be zero.
11. first_fut_expiry Optional. Date specifying the expiry date of the futures contract linked to the first
averaging period’s initial fixing. first_fut_expiry, if specified, is typically the first futures date falling on or
after first_avg_starts. The first floating payment is the arithmetic average of futures prices observed over an
averaging period beginning at first_avg_starts and ending on the first date in settle_curve, inclusive, with a
sampling interval of avg_interval years (for example, avg_interval equals 1/365 for a daily calendar-day
average or 1/12 for a monthly average). The futures contract whose price is used in the average is the one
expiring on first_fut_expiry for averaging dates falling on or before first_fut_expiry. If some averaging dates
fall after first_fut_expiry, then subsequent fwd_curve futures are used until the first date in settle_curve is
reached. Subsequent floating prices paid on remaining settlement dates, if any, are constructed analogously
by shifting first_avg_starts, the first date in settle_curve, and first_fut_expiry by the interval between the two
relevant settlement dates in settle_curve. If first_fut_expiry is omitted, the averaging dates are as defined
above but the floating price used on each averaging date is the spot price obtained by interpolating between
forward curve points.
3. Settlement amount (millions of ccy). Amount of asset used to calculate the payment. Amount of asset
used to calculate the underlying swap payment. Specify positive amounts for a long option position or
negative amounts for a short option position. Mixed signs are not permitted. The underlying swap is always
a pay fixed, receive floating swap. That is, if you are long (short) a call swap option and the option is
exercised then you are long (short) a pay-fixed swap; if you are long (short) a put swap option and the
option is exercised then you are short (long) a pay-fixed swap (equivalent to a long (short) receive-fixed
swap).
Example: T,1/1/1999,1,T,2/1/1999,1,T,3/1/1999,1
Commodity swaps options are discounted using the swap yield curve for ccy. Valuation is performed by
using the @ENERGY function OPTINDEXSWAP.
For a precise definition of the average used to calculate the floating price, see the first_avg_starts and
first_fut_expiry fields.
The payoff (to the holder) at expiration from a commodity index swap option is
Call: max(0, IT – K)
Put: max(0, K – IT)
where K is a user-specified strike price and IT is the price of the underlying index swap at option expiration.
Payoffs assume that the total amount of the underlying swap is one.
Long European call: (fixed) CAD for (floating) GAS swap

CAD,GAS,2.0,0.08333,4/1/1999,E,C,,3/1/1999,,,T,5/1/1999,10,T,8/1/1999,100
Short European put: (fixed) USD for (floating) WTI swap

USD,WTI,16.0,0.25,4/1/1999,E,P,,3/1/1999,,4/2/1999,T,5/1/1999,-10,T,8/1/1999,-10
0,T,2/1/2000,-10
*TYPE=COMMODITYPHYS
Commodity risk arises both in the spot market (you purchase a product today and store it over time) and
the futures market (physical delivery of a product in the future). Commodity physicals represent inventory
held, borrowed, or pending. These can be evaluated as a sequence of cash flows.
Physical assets are often traded in immature markets where price information is non-existent or limited to a
series of spot prices, which themselves may represent too small a set of historical data from which to extract
reliable statistical information. As in these cases, contracts may be quoted in terms of proxies, such as
NYMEX traded commodities, for which substantive price information, particularly forward price
information, is available. Quotes can be given in terms of basis spreads off of a proxy, which itself may be
defined in terms of a linear combination of exchange-traded commodities. The Remarks section, below,
describes the types of valuation schemes supported. Each payoff is described in terms of the type of basis
spread employed.
spread_type, asset, units, delivery_date, basis_spread, proxy1, proxy2, proxy3, weight1, weight2, weight3
1. spread_type Required. Text specifying the payoff spread type, as defined in the Remarks section, below.
Specify one of the following:
‘FIXED’ for a fixed forward spread.
‘FLOAT’ for a floating spot spread.
‘NONE’ for no spread.
2. asset Required. If spread_type is FIXED, text indicating the denomination currency of basis_spread, defined
below. If spread_type is FLOAT or NONE, text specifying underlying commodity. See Assets for information
on both currency and commodity codes.
3. units Required. Number specifying the size of the physical position in millions— the number of units of
commodity of which the holder is obliged to make or take delivery upon delivery_date, divided by 1,000,000.
Specify a positive number for a long position (as when in possession or obliged to take delivery) or a
negative number for a short position (as when borrowed or obliged to make delivery). Examples: If you
physically hold 1,000 barrels of NYMEX light, sweet crude oil (symbol CL), specify 0.001 [= 1000 / 1000000].
If you plan to deliver 10,000 million British thermal units (MMBtu) of NYMEX Henry Hub natural gas
(symbol NG) on delivery_date, specify -0.01 [= -10,000 / 1000000].
4. delivery_date Optional. The date the commodity is to be delivered. If omitted, the commodity is assumed
to be borrowed or in possession, depending on the sign of units.
5. basis_spread Required if spread_type is FIXED, ignored otherwise. The difference, in asset terms, between the
value of the underlying commodity and the representative proxy commodity (see proxy1, proxy2, and proxy3,
below) at delivery_date—a fixed difference incurring interest-rate risk, only. Enter a positive (negative) value
if the underlying commodity value is greater (less) than the proxy value.
6. proxy1 Optional, ignored if spread_type is NONE. Text specifying a commodity whose forward curve is in
whole or part (depending on weight1, weight2, and weight3) representative of the dynamics of the
underlying's future maturities, apart from a basis spread. Specify a proxy commodity if the underlying's
forward curve is missing or incomplete. See Assets for information on commodity codes.
9. weight1 Optional, ignored if spread_type is NONE. Number specifying the weight given to the proxy1
commodity. The representative proxy forward curve is the weighted sum of the forward curves of all
specified proxy commodities. If omitted, weight1 assumes the value 1.
There are three basic types of payoff defined for the commodity physical, which depend on the basis spread
used:
1. Fixed Forward Spread. A basis_spread  is specified and the commodity physical is present-valued in
millions of home currency using an optionally-specified average proxy forward curve, via the formula
 
Payoff  A X ccy e ccy  X base  wi Fi e  rbaseT  ,
r T
 i 
where wi represents weight1, weight2, or weight3; Fi represents the forward price (with maturity T) of
proxy1, proxy2, or proxy3; rccy (rbase) is a spot interest rate of maturity T, of the asset (base currency) market;
and T is the time between the effective date and delivery_date. The exchange rate Xccy (Xbase) is the spot
rate of exchange between asset (the base currency) and the home currency. (Note that the base currency is
the currency in which the volatilities and correlations of all commodity prices are measured. It is
intrinsic to the volatility and correlation data set.) The factor A represents the units of commodity; it
ensures that the present value can be expressed in millions of (home) currency.
2. Floating Spot Spread. A basis_spread is not specified but a proxy curve is provided. The commodity
physical is present-valued in millions of home currency using a floating spot basis spread, via the
formula
 
Payoff  AX base  S   wi S i   wi Fi e  rbaseT  .
 i i 
Here, S is the (required) spot price of the physical asset while Si is representative of the spot price of
proxy1, proxy2, or proxy3. (Note that if T=0, then PV=AXbaseS.)
3. No Spread. Neither basis_spread nor a proxy curve is provided. The commodity physical is present-
valued in millions of home currency using the forward curve of the underlying commodity, via the
formula
Payoff  AX base Fe rbaseT .
Here, F is the forward price, with maturity T, of the underlying asset. (Note that if T=0, then PV=AXbaseS.)
When asset is specified as a currency, interest rates are linearly interpolated about delivery_date using the
asset swap (asset class S) interest-rate curves in the volatility-correlation dataset.
Also see Commodity Futures.
1,000 barrels of WTI

NONE,WTI,0.001
10,000 MMBtu GAS to be received 6 months from 1/1/2000

NONE,GAS,0.01,7/1/2000
One million bales of local cotton, to be delivered 3 months from 1/1/2000, priced off of a fixed NYMEX
cotton spread.
FIXED,USD,-1,4/1/2000,0.5,CTN
One million bales of local cotton (whose spot-price statistics are provided via the user-defined asset code
COTTON), to be received 3 months from 1/1/2000, priced off of NYMEX cotton, with a floating spot spread.
FLOAT,COTTON,1,4/1/2000,,CTN
Ten million barrels of local crude oil priced off a fixed spread of the weighted sum of BCO and WTI.
FIXED,GBP,10,,1.5,BCO,WTI,,0.7,0.3
*TYPE=COMMODITYSWAP
A commodity swap entails a firm paying (or receiving) fixed amounts in exchange for receiving (or paying)
variable amounts based on an index (for example, the price of natural gas nearby futures contract).
The fixed leg of a commodity swap obliges the firm to make periodic cash outflows based upon a
predetermined, constant price (this side of the transaction is analogous to a short position in a coupon
bond). The floating leg provides cash inflows based upon the price of the nearby index price at each payment
date.
ccy, commodity, amount, fixed_price, swap_freq, maturity_date, start_date
currency codes.
2. commodity Required. Text specifying the contract’s underlying commodity. See Assets for information on
commodity codes.
3. amount Required. Number specifying the number of units of commodity, in millions, upon which swap
payments are based. Specify a positive number if you are paying a fixed price and receiving a floating price
or a negative number if you are paying a floating price and receiving a fixed price. Example: for an amount
of 10,000 MMBtu’s of gas, specify 0.01 *= 10,000 / 1,000,000].
4. fixed_price Required. Number specifying the price of the swap’s fixed leg, expressed as units of ccy per
one unit of commodity.
5. swap_freq Required. Number specifying the swap frequency—the number of payment dates per year,
typically 1, 2, 4, 6, or 12.
6. maturity_date Required. Date specifying the maturity date of the swap.
7. start_date Required for forward-starting commodity swaps only, omit otherwise. Date specifying the starting
date of the commodity swap, that is, the future date of the first exchange. Payments start after start_date. If
start_date falls on the effective calculation date (typically today) then the mark-to-market price and risk of
the swap will not include the exchange occurring on start_date.
Important When specifying start_date, the following relationship must be maintained: maturity_date –
start_date (expressed in years) must be evenly divisible by 1 / swap_freq. If this condition is not satisfied then
start_date will be reset to the nearest valid starting date.
Commodity swaps are discounted using the swap yield curve for ccy.
available from FEA.
Pay fixed, receive floating

This commodity swap requires the holder to pay a fixed price of US$2.00 and receive a floating price for gas
every month until maturity.
USD,GAS,0.01,2.00,12,1/1/1997
Pay floating, receive fixed

For the counterparty of the above example, who is paying floating and receiving fixed, the trade is the same
except the sign of amount is negative.
USD,GAS,-0.01,2.00,12,1/1/1997
Forward-starting pay fixed, receive floating

Suppose today is October 1, 2000 and we enter into a swap similar to the one described in the first example,
but with monthly payments starting on January 1, 2001 and ending on December 1, 2001., and a fixed price
of US$6.00
USD,GAS,0.01,6.00,12,12/1/2001,1/1/2001
*TYPE=CONVERTIBLEBOND
*VOLATILITY=equity price volatility [optional]
A convertible bond is a bond that may be converted, at the holder’s option, into stock of the issuing
company. Each 1 currency unit of notional principal of the bond can be converted into a specified number
of shares of stock. That number of shares may vary according to the price of the stock or the date. The bond
may be callable and/or puttable. If the bond is callable and puttable at the same time, the call has priority. If
the bond is called, the holder may convert rather than accepting the principal repayment. Such an
occurrence is called a forced conversion.
ccy, credit_rating, principal, maturity_date, cpn_rate, cpn_freq, issue_date, issue_price, first_cpn_date,

last_cpn_date, basis, underlying_ccy:equity_index, stockprice, beta, volatility, dividend_yield,
conversion_style, conversion_schedule_type, call_style, put_style, conversion_schedule <O, date,
#shares,…>, call_schedule <C, date, price,...>, put_schedule <U, date, price,...>, dividend_list <D, date,
dividend,<>, coupon_schedule <N, date, coupon,<>
2. credit_rating Required. Text specifying the bond issuer’s credit rating, which determines which yield
curve to use to discount cash flows. See Codes for a list of the credit rating codes. See The Euro for Euro-
related issues. Example: For a government bond, specify ‘Z’.
3. principal Required. Number specifying the bond’s principal in millions of local currency. Specify a
issues. Examples: For a short position of 10 million, specify -10. For a long position of 500000, specify 0.5.
5. cpn_rate Required for coupon bonds. Number specifying the coupon rate as a percent. Example: For a 5.5%
coupon rate, specify 5.5.
6. cpn_freq Required for coupon bonds. Number specifying the coupon frequency—the number of times per
year a coupon is paid, typically 1, 2, 4, or 12.
7. issue_date Required for when-issued trades and odd-first coupon bonds. Date specifying the date of issue.
8. issue_price Required for when-issued trades and odd-first coupon bonds. Number specifying the issue price as
a percent of principal. Example: For 97%, specify 97.
9. first_cpn_date Required for odd-first coupon bonds. Date specifying the first coupon date—the ending date
of the first coupon’s interest period. Interest accrues from issue date until this date for the first coupon only.
Requires issue_date also.
10. last_cpn_date Required for odd-last coupon bonds. Date specifying the last coupon date—the starting date
of final coupon’s interest period. Interest accrues from this date until maturity for the last coupon only.
11. basis Optional. Text specifying the accrual of interest for irregular coupons. If no basis is specified, AA
is implied.
12. underlying_ccy Required. Text specifying the currency code of the underlying equity. See Assets for
information on currency codes. For Euro-denominated currencies, ccy and underlying_ccy must be in-Euro
currencies (or EUR). In all other cases ccy and underlying_ccy must be identical. Note that this trade is not a
quanto. See The Euro for Euro-related issues.
The underlying_ccy may be optionally followed by a colon and a custom equity index name. See Assets for
information on custom equity index names. If no equity index name is specified, :SE is implied.
13. stock_price Required. Number specifying the current stock price in units of local currency.
14. beta Optional. Number specifying the beta of the instrument with respect to the selected equity index. If
you are using a RiskMetrics dataset, see Remarks below for the market index corresponding to each ccy. If
the equity position (or underlying position) is the same as the measured index listed below then specify 1.0.
Otherwise specify the beta of the equity position to the measured index.
(annualized standard deviation or implied volatility) of the price of the underlying equity or the implied
volatility, as a percent. If the VOLATILITY header is omitted you must specify the volatility in this field. If
you provide both a value in this field and a VOLATILITY header, this field prevails. Example: for 25%,
specify 25.
16. dividend_yield Optional. Number specifying the annualized, continuously-compounded dividend rate
of the underlying equity, as a percent. For broad-based equity indices (which pay a steady stream of
dividends), we recommend you only specify dividend_yield and not dividend_method and dividend_list. Only
the ‚lumpy‛ dividends in dividend_list apply until the last dividend payment date; thereafter, only
dividend_yield applies. If dividend_yield is omitted then 0 (zero) is used. Example: for 5.5%, specify 5.5.
17. conversion_style Required. Text specifying the bond conversion style. Specify one of the following:
‘B’ for Bermuda exercise.
18. conversion_schedule_type Required. Text specifying the conversion schedule table. Specify one of the
following:
‘D’ for date. The conversion ratio changes on the specified date.
‘S’ for stock price. The conversion ratio changes at the specified stock price level.
19. call_style Optional. Text specifying the bond call style. Specify one of the following:
20. put_style Optional. Text specifying the bond put style. Specify one of the following:
21. conversion_schedule Required. List specifying the conversion ratio schedule. This is the number of
shares of stock the holder will receive for each 1 currency unit of notional principal in the bond. Each list
1. Conversion schedule indicator ‚O‛.
2. Date—must fall on a coupon date— or stock price.
3. Number of shares.
Example using dates: O,1/1/2015,0.8,O,1/1/2017,0.7,O,1/1/2019,0.65
Example using stock prices: O,50,1,O,40,1.2,O,30,1.4
Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
Important If the instrument has a put schedule but no call schedule, do not insert an extra field delimiter
(comma or semicolon) where the call schedule would normally appear. Specify the put schedule
immediately following conversion_schedule. This applies for all optional schedules: do not insert an extra
comma for an omitted schedule.
23. put_schedule Optional. List specifying the put schedule. Required for puttable instruments only, leave
1. Put indicator ‚U‛.
2. Put date—must fall on a coupon date.
Example: U,1/1/2015,97,U,1/1/2017,98,U,1/1/2019,99
24. dividend_list Optional. List specifying the expected dividends. Each list element contains the following
items:
1. Dividend indicator ‘D’.
2. Dividend payment date.
3. Dividend (units of ccy—not a percent).
Example: D,3/1/1997,3.5,D,6/1/1997,3.5,D,9/1/1997,3.5
25. coupon_schedule Optional. Schedule specifying changing coupon rates. Each list element contains the
following items:
1. Coupon indicator ‘N’.
2. Date of change in coupon—must fall on a coupon date.
3. New coupon rate.
Example: N,1/1/2015,5,C,1/1/2017,4,C,1/1/2019,3
The conversion_style, call_style, and put_style fields determine the meaning of the corresponding
conversion_schedule, call_schedule, and put_schedule lists.
American (‚A‛) means the bond is convertible, callable, or puttable at any time after the first date in the
schedule and until maturity. So the schedules specify deferred start American exercise unless the first day is
the same as the value date. Multiple entries give changing strike American exercise.
Bermuda (‚B‛) exercise means the bond is convertible, callable, or puttable only on the dates in the schedule.
If the exercise can occur on any coupon date, all the coupon dates must be given in the schedule.
European (‚E‛) exercise means the bond is convertible, callable, or puttable only at maturity. The European
schedule must contain an entry for the bond maturity date. All other entries will be ignored.
If the conversion schedule is a table of conversion ratios for stock price levels, then American means
exercisable at any time between value date and maturity and European means exercisable only at maturity.
See also remarks on coupon bonds and equities. For details on convertible bond valuation, see the FEA
@INTEREST User Guide.
Convertible bond with dividend schedule

USD,A,1,12/15/2003,5,2,,,,,AA,USD:MYCOMP,0.8,,20,A,D,,,O,12/20/2002,1.2,D,12/15/
2002,0.0036
*DATE=yyyymmdd,ROW=num_records,COL=2,CONTENT=est_type
*REBASE_CCY=CCY
*NAME,CORRELATION
where est_type is DCF for daily (one-day), MCF for monthly (25-day), or CF for other correlation forecasts.
Correlation files contain daily or monthly correlations for the vertices specified in a corresponding volatility
file.
name, correlation
1. name Required. Text specifying two series’ names (vertices) in the format:
asset1.asset_class[maturity]1. asset2.asset_class[maturity]2 where asset1 and asset2 are asset codes, and
asset_class[maturity]1 and asset_class[maturity]2 are one of the Asset Class and Maturity Codes listed in
Codes. The asset_class[maturity] portion of the name has a special format for implied volatility vertices. See
the example below, or the description on page 103.
2. correlation Required. Number specifying the correlation estimate of the series.
To maintain compatibility with RiskMetrics, header records in correlation files differ from those in other
files.
Each series in the correlation file must have a corresponding series in the volatility file.
The correlation file comprises the lower half of the correlation matrix and must contain the diagonal
elements (these elements equal exactly 1). Therefore, if the volatility file contains n records then the
correlation file must contain exactly n(n + 1) / 2 records.
The correlation matrix should be positive definite (x'Cx > 0 for all x), guaranteeing a non-imaginary VaR—
this becomes increasingly unlikely as n grows. (All the eigenvalues of a positive definite matrix are positive.)
correlation must be between -1 and +1, inclusive.
Intra-asset class correlation

EUR.XS.AUD.XS,-0.163854
Inter-asset class correlation

SEK.Z02.DKK.SE,0.021988
Diagonal correlation matrix element

USD.Z30.USD.Z30,1.000000
Correlation between implied volatilities for identical strike but different maturities
USD.SP500_IV(1150;12/17/2005).USD.SP500_IV(1150;1/27/2006),0.8
*TYPE=CRACK
A crack option or crack spread option is an option on the price differential between three underlying assets.
The net equivalent positions, or weights, of the assets have mixed signs (for example, +3, -2, -1). Weights are
netted together for a single ‚basket‛ value, which settles against the option’s strike price. A positive weight
indicates a long position, a negative weight a short one.
For example, suppose you own a call crack option struck at 20. If the price of asset 1 at expiry is 100
(weight = 1), the price of asset 2 at expiry is 30 (weight = -2), and the price of asset 3 at expiry is 5
(weight = -3), the option will pay out (1  100 – 2  30 – 3  5) – 20 = 5.
The NYMEX crack spread involves the purchase (or sale) of crude oil against the sale (or purchase) of
refined petroleum products, such as gasoline and heating oil. The spread differentials represent refining
margins. Visit the NYMEX web site for an energy glossary, useful publications, and links to other energy
resources. The address is http://www.nymex.com.
Crack average-price options pay on the average price differential of three assets during an averaging period.
The prices of the three assets evolve according to a stochastic process where the three prices are lognormally
distributed and correlated. The correlations are described with a symmetric, positive-definite correlation
matrix.
opt_type, ccy, asset1, asset2, asset3, pc_type, strike, opt_expiry, weight1, weight2, weight3, corr12, corr13,
corr23, vol1, vol2, vol3, amount, [, avg_starts, num_fixings, [running_avg]]
‘O’ for an ordinary option.
currency codes.
3. asset1 Required. Text specifying the first underlying asset, which may be a currency or commodity. See
Assets for information on currency and commodity codes.
4. asset2 Required. Text specifying the second underlying asset, which may be a currency or commodity. See
5. asset3 Required. Text specifying the third underlying asset, which may be a currency or commodity. See
7. strike Required. Number specifying the option’s strike price expressed in ccy units. strike can be positive,
negative, or zero.
9. weight1 Required. Number specifying the weight of asset1. May be positive or negative.
12. corr12 Required. Number between -1 and +1, inclusive, specifying the correlation of asset1 and asset2.
VOLATILITY header is omitted then you must specify the volatility in this field. If you provide both a vol1
value and a VOLATILITY header value then vol1 prevails. Example: for 25%, specify 25.
16. vol2 Optional if VOLATILITY2 header is specified, required otherwise. Number specifying the volatility
VOLATILITY2 header is omitted then you must specify the volatility in this field. If you provide both a vol2
value and a VOLATILITY2 header value then vol2 prevails. Example: for 25%, specify 25.
VOLATILITY3 header is omitted then you must specify the volatility in this field. If you provide both a vol3
value and a VOLATILITY3 header value then vol3 prevails. Example: for 25%, specify 25.
19. avg_starts Required for APOs; ignored otherwise. Date specifying when the averaging period starts. It is
the first sampling point in the averaging period.
20. num_fixings Required for APOs; ignored otherwise. Number greater than or equal to one specifying the
number of evenly-spaced sampling points during the averaging period. num_fixings is truncated to an
integer.
21. running_avg Optional for APOs; ignored otherwise. Number greater than zero specifying the average price
established up to the effective calculation date by past price observations. running_avg applies only if the
effective calculation date falls after avg_starts and is ignored otherwise.
Specify vol1, vol2, and vol3 with respect to ccy, regardless of the base or local currency of asset1, asset2, and
asset3 in the volatility-correlation dataset.
The payoff (to the holder) at expiration from a crack option is
Call: max 0, w1 S1,T  w2 S 2,T  w3 S 3,T   K 

Put: max 0, K  w1 S1,T  w2 S 2,T  w3 S 3,T 
where K is the strike price, wi is the weight of the i-th asset, Si,T is the spot price of the i-th asset at option
expiration.
The payoff (to the holder) at expiration from a crack average-price option is
Call:

max  0,
1 n
   
w1 S1,t j  w2 S 2,t j  w3 S 3,t j  K 
 n  1 j 0 
Put:

max  0, K 
1 n

 w1 S1,t j  w2 S 2,t j  w3 S 3,t j
n  1 j 1

 
where K is the strike price, wi is the weight of the i-th asset, Si,t(j) is the price of the i-th asset at time
tj = ts + j(T – ts) / n, (n + 1) is the number of fixings during the averaging period, T is the time to option
expiration in years, and ts is the time to the start of the averaging period in years.
Crack options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
Short running APO put on GAS, WTI, USD

A,CAD,GAS,WTI,USD,P,80.0,5/1/99,7,-1,4,0.5,-0.4,-0.1,,,,-100,10/1/98,8,12
Long ordinary call on GAS, WTI, GBP

O,EUR,GAS,WTI,GBP,C,2.2,5/1/99,7,-1,4,0.5,-0.4,-0.1
Long forward-starting APO call on GAS, WTI, GBP

A,CAD,GAS,WTI,GBP,C,2.7,5/1/99,7,-1,4,0.5,-0.4,-0.1,,,,25,3/1/99,9
*TYPE=CDS
A Credit Default Swap (CDS) is the most basic of credit derivative contracts. It is an agreement to buy or sell
protection against the risk of default by an issuer known as the reference entity on an underlying asset
known as the reference asset (typically a bond). In case of a defined credit event (e.g. default), the buyer of
protection receives a payment from the seller of protection to compensate for the loss on the investment.
Typically, this transaction is settled financially: a recovery value of the reference asset is determined and the
payment equal to the difference between par and the recovery value is made by the protection seller to the
protection buyer. In return, the protection buyer pays a fee known as the CDS premium or spread to the
protection seller. The fee is paid in arrears at the regular time intervals over the life of the contract. If
default occurs, the premium leg terminates after one final accrued payment.
In addition to the plain vanilla CDS, the following CDS types and enhancements are supported.
In the case of a binary or fixed-recovery CDS, the payoff amount in the event of a default is a fixed percentage
of the notional specified in the contract.
A forward CDS is a bilateral agreement between the parties to enter into a CDS at a specified later date at a
specified CDS premium.
When a CDS is used to protect an amortizing reference asset, the CDS is also using a corresponding
amortizing notional.
ccy, credit_spread_rating, risk_free_rating, recovery, principal, maturity_date, cds_spread, pmt_freq,

fixed_recovery, start_date, basis, rollday, spread_curve <S, date, spread,...>, amortization_schedule <A, date,
prin_reduction,...>
2. credit_spread_rating Required. Text specifying the reference issuer’s credit spread rating. It is the spread
over the risk-free credit rating, which is used together with the recovery rate assumption to calculate default
probabilities. Data corresponding to the credit_spread_rating must be specified within the dataset. Example:
For a BB-rated bond, with a custom spread curve identified by the label CURVE1, specify ‘BB:S:CURVE1’.
The :S: in the label identifies the interest rate as a spread, and must be included in the label of the custom
credit rating wherever the name appears, i.e. in the volatility, correlation, yield curve, and asset files.
3. risk_free_rating Optional. Text specifying the ‚risk_free‛ credit rating, which is used to discount
cashflows. See Codes for a list of the credit rating codes. If omitted, the government curve, Z, will be used.
4. recovery Required. Number specifying the recovery rate assumption of the underlying asset. It is used in
calibrating the default probability termstructure as well as in computing the value of the CDS if fixed
recovery is not provided. Examples: For a 50% recovery rate assumption, specify 0.5.
5. principal Required. Number specifying the CDS notional amount, i.e. the principal amount of the
underlying asset in millions of local currency. Specify a positive number for a long position or a negative
number for a short position. Examples: For a short position of 10 million, specify -10. For a long position of
500000, specify 0.5.
6. maturity_date Required. Date specifying the maturity date of the CDS (not necessarily of the underlying
reference bond).
7. cds_spread Required unless spread_curve is provided. Number specifying the (annualized) CDS spread
payment. cds_spread is measured in basis points (bp), for example: for a 80bp spread rate, specify 80.
8. pmt_freq Required unless spread_curve is provided. Number specifying CDS spread payment
frequency per year. Possible values are 1, 2, 4 or 12.
9. fixed_recovery. Optional. Number specifying the fixed recovery rate to be used when valuing a
binary CDS. Examples: For a 60% recovery rate assumption, specify 0.6. If omitted it is assumed
that CDS is not binary.
10. start_date Optional. Date specifying the effective date of the CDS contract for forward CDS—the
beginning date of the first CDS spread accrual period. If omitted or in the past, it is assumed that it is equal
to valuation effective date.
11. basis Optional. Text string indicating the day count basis used when computing CDS payments. Default
value is ‚AA‛.

12. rollday Optional. Number specifying the day of the month the CDS payments are made. This is useful
primarily when the CDS matures on the 30th day of a month with only 30 days. You can choose whether to
roll back to the 31st of months with thirty-one days or to roll back to the 30th. If omitted, the date series will
roll back on the day of the maturity, but will treat the last day of the month as a special case and roll back
from, e.g., June 30th to December 31st.
13. spread_curve Optional. List specifying the spread payment schedule. This argument is optional as
payment schedule is usually specified by cds_spread and pmt_freq arguments. Using the spread curve, a
custom CDS payment schedule can be specified. The curve is specified as a list with each list element
contains the following items:
1. Spread curve indicator ‚K‛.
2. Spread payment date.
3. Spread (in basis points).
Example: K,1/1/2015,100,K,1/1/2016,100,K,1/1/2017,120
Spread curve overwrites the input given by pmt_freq and cds_spread arguments.
14. amortization_schedule Optional. List specifying the amortization schedule of the CDS notional. The
schedule is specified as a list, with each list element contains the following items:
1. Amortization schedule indicator ‚A‛.
2. Date—must fall on a spread payment date.
3. Principal reduction (percent of original—not remaining—principal).
Example: A 5% and 10% amortization provision: A,1/1/2000,5,A,1/1/2005,10
Payment dates are calculated by starting at maturity_date and working backwards in intervals of pmt_freq.
For amortization schedules, the percent principal reduction is a reduction of the original principal (not the
remaining principal) so all the reductions must sum to less than or equal to 100.
CDS valuation uses the Reduced Form Model and requires a term structure of default intensities
(probabilities). To value a CDS in VaRworks, we use the risk-free credit curve and the underlying market
risky bond spread curve together with a fixed recovery rate assumption to calibrate the default probability
term structure. The CDS valuation functions used by VaRworks are also available within the Barra Credit
product.
A plain-vanilla CDS with 40% recovery and semi-annual spread payments of 50bp
USD,BB:S:SPREAD,Z,.4,1,1/1/2012,50,2
A binary forward 5 year CDS with changing annual spread payment schedule
USD,BB:S:SPREAD,Z,.4,1,1/1/2012,,,.2,1/1/2007,AA,,K,1/1/2008,45,K,1/1/2009,50,K,
1/1/2010,55,K,1/1/2011,60,K,1/1/2012,65
*TYPE=CCYSWAPOPT
*VOLATILITY=short-term-rate-volatility1
*VOLATILITY2=short-term-rate-volatility2
A currency swap option, or currency swaption, is an option to enter a currency swap.
ccy, credit_rating, principal, principal2, swap_type, pc_type, option_maturity, swap_maturity,

first_pmt_date, ccy2, volx, corr1, corr2 corr3, rate, rate_freq, rate_basis, first_reset_rate, rate2, rate_basis2,
first_reset_rate2, amort_schedule <A, date, amount,...>, coupon_schedule <C, date, coupon_rate,...>,
coupon_schedule2 <E, date, coupon_rate,...>
1. ccy Required. Text specifying the first currency. See Assets for information on currency codes. See The
3. principal Required. Number specifying the notional principal in millions of ccy. See The Euro for Euro-
related issues.
4. principal2 Required. Number specifying the notional principal in millions of ccy2. See The Euro for Euro-
related issues.
5. swap_type Required. Text specifying the swap type. Specify one of the following:
‘fixfix’ for fixed for fixed.
‘fixfloat’ for fixed for floating.
‘floatfloat’ for floating for floating.
‘xfixfix’ fixed for fixed with exchange of principal.
‘xfixfloat’ fixed for floating with exchange of principal.
‘xfloatfloat’ floating for floating with exchange of principal.
‘C’ for call option (cap).
‘P’ for put option (floor).
7. option_maturity Required. Date specifying the maturity date of the option.
8. swap_maturity Required. Date specifying the maturity date of the underlying swap, when the last
exchange of payments occurs.
9. first_pmt_date Required. Date specifying when the first exchange of payments occurs or occurred. This
date might be in the past. It is used only in determining the payment dates.
10. ccy2 Required. Text specifying the second currency. See Assets for information on currency codes. See
The Euro for Euro-related issues.
11. volx Required. Number specifying the volatility of the exchange rate, as a percent. The exchange rate is
read from the volatility-correlation dataset. Example: for 15%, specify 15.
12. corr1 Required. Number between -1 and +1, inclusive, specifying the correlation of rate and rate2.
13. corr2 Required. Number between -1 and +1, inclusive, specifying the correlation of rate and the exchange
rate.
14. corr3 Required. Number between -1 and +1, inclusive, specifying the correlation of rate2 and the
exchange rate.
15. rate Required if swap_type is fixfix, fixfloat, xfixfix, or xfixfloat; ignored otherwise. Number specifying the ccy
fixed rate, as a percent. Example: for 5.5%, specify 5.5.
16. rate_freq Required. Number specifying the frequency (times per year) payments are exchanged.
Typically 1, 2, 4, or 12.
17. rate_basis Required if swap_type is floatfloat or xfloatfloat; ignored otherwise. Text specifying the rate basis
of the ccy floating rate. This rate is converted to a bond equivalent rate prior to cash flow mapping. Specify
one of the following:
18. first_reset_rate Required if swap_type is floatfloat or xfloatfloat; ignored otherwise. Number specifying the
ccy floating rate set on the previous reset date, as a percent. Example: For 5.5%, specify 5.5.
19. rate2 Required if swap_type is fixfix or xfixfix; ignored otherwise. Number specifying the ccy2 fixed rate, as
a percent. Example: for 5.5%, specify 5.5.
20. rate_basis2 Required if swap_type is fixfloat, floatfloat, xfixfloat, or xfloatfloat; ignored otherwise. Text
specifying the rate basis of the ccy2 floating rate. This rate is converted to a bond equivalent rate prior to
cash flow mapping. Specify one of the following:
21. first_reset_rate2 Required if swap_type is fixfloat, floatfloat, xfixfloat, or xfloatfloat; ignored otherwise.
Number specifying the ccy2 floating rate set on the previous reset date, as a percent. Example: For 5.5%,
specify 5.5.
Example: A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
23. coupon_schedule Optional. List specifying the fixed coupon schedule of ccy. Ignored if swap_type
indicates ccy pays a floating rate. Each list element contains the following items:
1. Coupon indicator ‘C’.

2. New coupon effective date—must fall on a payment date.
3. New coupon rate (as a percent).
Example: C,1/1/1997,5.0,C,1/1/1998,5.5
24. coupon_schedule2 Optional. List specifying the fixed coupon schedule of ccy2. Ignored if swap_type
indicates ccy2 pays a floating rate. Each list element contains the following items:
1. Coupon indicator ‘E’.
Example: E,1/1/1997,5.0,E,1/1/1998,5.5
FEA.
Plain currency swap option

USD,Z,100,50,FIXFIX,C,1/1/2001,1/1/2009,1/1/1998,EUR,0.1,0.8,0.8,0.8,10,2,,,8
*TYPE=DIFFSWAP
A differential swap is a series of forward contracts used to lock in the difference between two asset prices. One
party agrees to pay a floating spread and receive a fixed spread (the fixed spread may be zero) over a
specified period of time. The amounts of the two assets used to determine the spread may differ.
Swap settlements are made in cash at (typically) regular intervals—usually monthly. If F1 is the floating price
of the first asset, F2 is the floating price of the second asset, amount1 is the notional amount of the first asset,
amount2 is the notional amount of the second asset, and fixed_spread is the fixed spread then settlement
equals (amount1 × F1) – (amount2 × F2) – (amount1 × fixed_spread). The floating payments are often linked to
the average of reference prices over some predetermined averaging periods.
ccy, asset1, asset2, avg_interval1, avg_interval2, first_avg_starts1, first_avg_starts2, running_avg1,

running_avg2, amt_mult, fixed_spread, first_fut_expiry1, first_fut_expiry2, settle_curve
currency codes.
4. avg_interval1 Required. Number specifying the time interval in years between fixings during each asset1
fixings.
5. avg_interval2 Required. Number specifying the time interval in years between fixings during each asset2
fixings.
6. first_avg_starts1 Required. Date specifying when the first fixing of asset1 occurs. Averaging dates in the
first settlement period are derived by counting backwards from the first date in settle_curve in time intervals
of avg_interval1 years until first_avg_starts1. first_avg_starts1 is rounded to coincide with the nearest valid
the (i + 1)-th date in settle_curve in time intervals of avg_interval1 years until the first averaging date
following the i-th date in settle_curve is reached. first_avg_starts1 must fall on or before the first date in
settle_curve.
7. first_avg_starts2 Required. is a date specifying when the first fixing of asset2 occurs. first_avg_starts2
behaves analogously to first_avg_starts1.
8. running_avg1 Required. Number greater than zero specifying the average price of asset1 for the current
settlement period established up to the effective calculation date by past price observations. running_avg1
applies only if the effective date falls after first_avg_starts1 and is ignored otherwise. Update running_avg1 as
the swap nears maturity. If running_avg1 is omitted when required then an error message is returned.
9. running_avg2 Required. Number greater than zero specifying the average price of asset2 for the current
settlement period established up to the effective calculation date by past price observations. running_avg2
behaves analogously to running_avg1.
10. amt_mult Optional. Number greater than zero specifying the factor by which the settle_curve entries are
multiplied to determine the asset2 settlement amounts. If amt_mult is omitted, it is assumed to be one.
11. fixed_spread Optional. Number specifying the fixed amount subtracted from the asset1 floating price,
expressed in ccy terms, to determine each settlement payment. If amt_mult equals one, fixed_spread can be
interpreted as the spread locked by the swap. See About Differential Swaps for a definition of the settlement
payments. If fixed_spread is omitted, it is assumed to be zero.
12. first_fut_expiry1 Optional. Date specifying the expiration of the futures contract linked to the initial
fixing of asset1's first averaging period. first_fut_expiry1, if specified, is typically the first futures date falling
on or after first_avg_starts1. The first floating payment is the arithmetic average of futures prices observed
over an averaging period beginning at first_avg_starts1 and ending on the first date in settle_curve, inclusive,
with a sampling interval of avg_interval years1 (for example, avg_interval1 equals 1/365 for a daily calendar-
day average or 1/12 for a monthly average). The futures contract whose price is used in the average is the
one expiring on first_fut_expiry1 for averaging dates falling on or before first_fut_expiry1. If some averaging
dates fall after first_fut_expiry1, then subsequent asset1 forward curve futures are used until the first date in
settle_curve is reached. Subsequent floating prices paid on remaining settlement dates, if any, are constructed
analogously by shifting first_avg_starts1, the first date in settle_curve, and first_fut_expiry1 by the interval
between the two relevant settlement dates in settle_curve. If first_fut_expiry1 is omitted, the averaging dates
are as defined above but the floating price used on each averaging date is the spot price obtained by
interpolating between forward curve points of asset1.
13. first_fut_expiry2 Optional. Date specifying the expiration of the futures contract linked to the initial
fixing of asset2's first averaging period. Specification of first_fut_expiry2 is analogously to that of
first_fut_expiry1.
3. Settlement amount (millions of ccy). Amount of asset used to calculate the payment. See About
Differential Swaps for a definition of the settlement payments. Specify positive amounts for a long swap
position (pay floating asset2 + fixed_spread, receive floating asset1) or negative amounts for a short swap
position (pay floating asset1, receive floating asset2 + fixed_spread). Mixed signs are not permitted.
Example: T,1/1/1999,1,T,2/1/1999,1,T,3/1/1999,1
Specify volatility with respect to ccy, regardless of the base or local currency of asset1 and asset2 in the
volatility-correlation dataset.
For a precise definition of the average used to calculate the floating price, see the first_avg_starts1 and
first_fut_expiry1 fields, and the first_avg_starts2 and first_fut_expiry2 fields.
Also see Commodity Index Swaps.
Long GAS for WTI differential swap

USD,GAS,WTI,0.0027,0.0027,4/1/2000,4/1/2000,0,0,,5,,,T,5/1/2000,10,T,8/1/2000,100,T,2/1/2001,10
Short GBP for EUR differential swap

USD,GBP,EUR,0.0027,0.0027,4/1/2000,4/1/2000,0,0,,0.6,,,T,5/1/2000,-10,T,8/1/2000,-100,T,2/1/2001,-10
*TYPE=DIGITALOPT
A digital option, also called a binary or all-or-nothing option, is an option whose payoff is a fixed amount if the
underlying asset price satisfies a predetermined trigger condition but nothing otherwise. There are two
payoff types: a cash-or-nothing payoff is made in the accounting currency (a fixed amount); an asset-or-nothing
payoff is made in the underlying asset (whose value varies with the price of the asset).
There are four trigger conditions: an up-and-in payoff occurs if the underlying price moves above the trigger
price, an up-and-out payoff occurs only if the underlying price stays below the trigger price, a down-and-in
payoff occurs if the underlying price moves below the trigger price, and a down-and-out payoff occurs only if
the underlying price stays above the trigger price. We call up-and-in and down-and-in options knock-in
options and up-and-out and down-and-out options knock-out options.
The trigger can be monitored either at option expiry or continuously through the life of the option. If a knock-
in option’s trigger condition is satisfied, payoff can occur either immediately or at option expiry. Note that if
the trigger is monitored only at option expiry then up-and-in and down-and-out options are equivalent and
up-and-out and down-and-in options are equivalent. Continuously monitored options require and initial
underlying asset price below the trigger for up-and-in and up-and-out options and above the trigger for
down-and-in and down-and-out options.
is_fixed_payoff, trigger_type, monitor_type, ccy, asset, amount, opt_expiry, trigger, volatility, fut_expiry,
risk_type, dividend_yield, spot, beta
1. is_fixed_payoff Required. Logical value specifying whether the payoff is a fixed amont of settlemet
currency. If is_fixed_payoff is TRUE, the payoff is amount units of the accounting currency (cash-or-nothing
option). If is_fixed_payoff is FALSE, the payoff is amount units of the underlying asset (asset-or-nothing
option).
2. trigger_type Required. Text specifying the trigger condition. Specify one of the following:
‘UPIN’: Payoff occurs at opt_expiry if the underlying price moves above trigger.
‘UPOUT’: Payoff occurs only if the underlying price stays below trigger.
‘DOWNIN’: Payoff occurs at opt_expiry if the underlying price moves below trigger.
‘DOWNOUT’: Payoff occurs only if the underlying price stays above trigger.
‘IDOWNIN’: Payoff occurs immediately as soon as the underlying price moves below trigger.
‘IUPIN’: Payoff occurs immediately as soon as the underlying price moves above trigger.
3. monitor_type Required. Text specifying how the trigger is monitored to determine the trigger condition.
‘END’ : trigger is monitored only at opt_expiry.
‘CONT’ : trigger is monitored continuously up to and including opt_expiry.
currency codes.
6. amount Required. Number specifying the amount of either cash or asset to be paid if the trigger condition
is satisfied. Specify a positive number for a long option position, a negative number for a short option
position.
8. trigger Required. Number specifying the price per unit of underlying asset at or beyond which digital
payoff occurs. trigger is greater than zero and expressed in ccy currency units.
The payoff (to the holder) from a continuously-monitored cash-or-nothing digital option is
Up-and-in: 1 (paid at T) if St > trigger for some t  T; zero otherwise.

Up-and-out: 1 (paid at T) if St < trigger for all t  T; zero otherwise.
Down-and-in: 1 (paid at T) if St < trigger for some t  T; zero otherwise.
Down-and-out: 1 (paid at T) if St > trigger for all t  T; zero otherwise.
Immediate up-and-in:
1 (paid at ) if S = trigger for some   T and St < trigger for all t < ; zero otherwise.
Immediate down-and-in:
1 (paid at ) if S = trigger for some   T and St > trigger for all t < ; zero otherwise.
The payoff (to the holder) from a continuously-monitored asset-or-nothing digital option is
Up-and-in: ST (paid at T) if St > trigger for some t  T; zero otherwise.
Up-and-out: ST (paid at T) if St < trigger for all t  T; zero otherwise.
Down-and-in: ST (paid at T) if St < trigger for some t  T; zero otherwise.
Down-and-out: ST (paid at T) if St > trigger for all t  T; zero otherwise.
Immediate up-and-in:
trigger (paid at) if S = trigger for some   T and St < trigger for all t < ; zero otherwise.
Immediate down-and-in:
trigger (paid at) if S = trigger for some   T and St > trigger for all t < ; zero otherwise.
where T is option expiry, St is the underlying asset price at option t.
The payoff (to the holder) from a end-monitored cash-or-nothing digital option is
Up-and-in: 1 if ST > trigger; zero otherwise.
Up-and-out: 1 if ST < trigger; zero otherwise.
Down-and-in: 1 if ST < trigger; zero otherwise.
Down-and-out: 1 if ST > trigger; zero otherwise.
The payoff (to the holder) from a end-monitored asset-or-nothing digital option is
Up-and-in: ST if ST > trigger; zero otherwise.
Up-and-out: ST if ST < trigger; zero otherwise.
Down-and-in: ST if ST < trigger; zero otherwise.
Down-and-out: ST if ST > trigger; zero otherwise.
The treesteps header input is only used in the case of continuously monitored digital options.
Digital options are priced using FEA @ENERGY models.
Also see Options.
US cash digital up-and-in WTI August futures, end monitoring

TRUE,UPIN,END,USD,WTI,1,8/1/2006,80,20,8/1/2006
*TYPE=DBARRIEROPT
A discrete barrier option is a European option that is either activated or terminated if the underlying asset
price reaches specified barrier levels, as they are monitored at discrete points in time. Discrete Barrier
Options (DBARRIEROPT) are different from ordinary Barrier Options (BARRIEROPT) in that they may
monitor two distinct barrier levels, these levels might be time dependent, and the monitoring is not
continuous but it occurs at points in time separated by discrete time intervals. Through the possible time
dependence of the barrier level DBARRIEROPT can cover complex window barrier setups.
After activation or before termination, barrier options behave identically to ordinary European options.
Since barrier options may never be activated or may be terminated, they carry a lower initial fair value than
ordinary European options. Note that after a hit on the upper/lower barrier of the instrument, the trade
record of DBARRIEOPT allows the user to flag that such a hit occurred, thus allowing for the proper
accounting of a trade even when the underlying price subsequently moves away from the barrier in an
arbitrary way.
up_barrier_type, down_barrier_type, monitor_freq, ccy, asset, amount, pc_type, strike, opt_expiry,

fut_expiry, hit_up, hit_down, risk_type, dividend_yield, spot, beta, barrier_curve, vol_curve
1. up_barrier_type Required. Text specifying the up barrier type. Specify one of the following:
‘UPIN_END’ for an up-and-in barrier, monitored at option expiry only.
‘UPOUT_END’ for an up-and-out barrier, monitored at option expiry only.
2. down_barrier_type Required. Text specifying the down barrier type. Specify one of the following:
‘DOWNIN_END’ for an down-and-in barrier, monitored at option expiry only.
‘DOWNOUT_END’ for an down-and-out barrier, monitored at option expiry only.
3. monitor_freq Required. Text specifying how often the barrier is monitored.

monitor_freq Description
‘d5’ Five days a week, Monday through Friday.
‘d7’ or ‘d’ Seven days a week.
‘h’ Signal continuous monitoring of the barriers.
‘m’ Once a month, with monitoring dates 365/12 days apart.
‘cm’ Once every calendar month, each monitoring on the same day of the month as
the last active monitoring date.
‘w’ Once a week, each monitoring on the same day of the month as the last active
monitoring date.
‘q’ Once a quarter, with monitoring dates 365/4 days apart.
currency codes.
6. amount Required. Number specifying the amount of asset used to calculate the total value of the
instrument. Specify a positive number if you are long the contract or a negative number if you are short the
contract. Examples: If the underlying of amount is 100 million units of asset, specify 100. See Commodity
Futures for more information on the relation between amount and price.
10. fut_expiry Required if the option is on a futures contract, omit if the option is on a spot currency or commodity.
Date specifying the expiration date of the underlying future. fut_expiry must fall on or after opt_expiry. Note
that discrete barrier options on futures are not yet currently implemented.
11.hit_up Optional. Is a logical value specifying whether the upper barrier was touched up to the effective
date of the calculation. Enter TRUE if the barrier was touched, FALSE if not. If omitted it is assumed that the
barrier was not touched.
12. hit_down Optional. Is a logical value specifying whether the lower barrier was touched up to the effective
date of the calculation. Enter TRUE if the barrier was touched, FALSE if not. If omitted it is assumed that the
barrier was not touched.
17. barrier_curve Required. List specifying a single or combination barrier curve. Complex windows period
can be specified via the barrier curve input. Each list element contains the following items:
1. Barrier curve indicator, ‘B2’
2. Barrier start date, denoting the date when the barrier levels specified below begin to apply.
3. Upper barrier level, effective from the barrier start date until the next date in the list, or option
expiry if the date is the last in the list. A blank entry means that the barrier is not active till the
next date.
4. Lower barrier level, effective from the barrier start date until the next date in the list, or option
expiry if the date is the last in the list. A blank entry means that the barrier is not active till the
next date.
Example: B2,3/1/2003,5, 2,B2,6/1/2003, , ,B2,9/1/2003, 5, 2,

specifies a barrier curve with an upper and lower barrier active from 3/1/03 to 6/1/03, and then again from
9/1/03 until option expiry.
18. vol_curve Optional if VOLATILITY header is specified, required otherwise. List specifying the volatility
(annualized standard deviation) of the price of asset or the implied volatility, as a percent. Each list element
1. Volatility indicator, ‘F’ for forward structure, ‘M’ for market (Black implied) structure of
volatilities.
2. Volatility date.
Example: M,3/1/2003,50,M,6/1/2003,60,M,9/1/2003,70
specifies a volatility curve with three points, 50%, 60%, and 70% respectively.
If you provide both a vol_curve and a VOLATILITY header value, vol_curve prevails.
Discrete Barrier Options are priced using FEA @ENERGY (the BAROPT2 function, using an enhanced tree
methodology, is used). For a technical discussion of pricing currency and commodity derivatives see the
@ENERGY User’s Guide, available from FEA. See also the BARRIEROPT instrument.
The ‘F’ and ‘M’ volatility indicators directly corresponds to forward and market term stuctures of
volatilities. To use a constant volatility for the whole strip, omit vol_curve and specify the VOLATILITY
header.
*TYPE=DISTRIBUTIONDATA
*METHOD=method_type, ROW=number-of-records, COL=number-of-columns
*SORTED=sort_flag [optional]
*EVT_LOSS= , , n_points [optional]
*EVT_PROFIT= , , n_points [optional]
*ANALYTIC_VAR= var_number, confidence [optional]
method_type is either HISTORICAL, MONTECARLO, or ANALYTIC, and its value determines the record
layout.
If method_type=ANALYTIC, the ANALYTIC_VAR header, specifying the VaR number and the confidence
interval used to generate VaR, must be specified. No additional data is necessary (see the PORTVARANL
function for how to generate this file).
If method_type=HISTORICAL, number-of-columns is two or three, and the record layout is the following (see
the HISTORICALVAR function for how to generate this file, and for additional details)
date, portfolio_change, weight
1. date Required. Date specifying an historical observation date. The date must be formatted as yyyymmdd,
with no date separators.
2. portfolio_change Required. The change in the value of the portfolio, on the specified observation date.
3. weight Optional. The weight to be assigned to this historical observation.
If sort_flag=TRUE or missing, the data must be sorted from largest loss to largest profit.
If method_type=MONTECARLO, number-of-columns is two, and the record layout is the following (see the
VARCARLO2 function for how to generate this file, and for for additional details)
label, portfolio_change
1. label Required. Label specifying the simulation run (an integer between 1 and iterations, with iterations
equal to the number of simulations used to obtain the distribution).
2. portfolio_change Required. The change in the value of the portfolio, for the specified simulation run.
If sort_flag=TRUE or missing, the data must be sorted from largest loss to largest profit.
*TYPE=DUAL
Dual-asset options are characterized by a payoff that depends on some combination of exactly two assets.
The most common type of dual-asset option is a spread option, which pays off on the difference in price of
two assets. The payoffs at expiration for a dual-asset call and put options follow.
Call payoffs at expiration

Option type Payoff
maximum max(max(S1, S2)  K, 0)
minimum max(min(S1, S2)  K, 0)
sum max(S1 + S2  K, 0)
spread max(S1  S2  K, 0)
Put payoffs at expiration

Option type Payoff
maximum max(K  max(S1, S2), 0)
minimum max(K  min(S1, S2), 0)
sum max(K  (S1 + S2), 0)
spread max(K  (S1 – S2), 0)
where S1 is the price of the first asset at expiration, S2 is the price of the second asset at expiration, and K is
the strike price.
ccy, ex_type, pc_type, strike, opt_expiry, combo_type, asset1, asset2, amount1, amount2, corr, volatility1,
volatility2
currency codes.
4. strike Required. Number specifying the option’s strike price expressed as ccy per unit of the asset1 and
asset2 basket price.

6. combo_type Required. Text specifying the type of combination made between the two assets. Specify one
of the following:
‘X’ deliverable is the maximum of two values.
‘N’ deliverable is the minimum of two values.
‘A’ deliverable is the sum of two values.
‘S’ deliverable is the difference (‚spread‛) of two values (asset1 – asset2).
9. amount1 Required. Number specifying the amount of asset1 in millions of units. Specify a positive number
for a long position, or a negative number for a short position. Note that amount1 does not have to equal
amount2. Example: For a short position and 100 million units of asset1, specify -100.
10. amount2 Required. Number specifying the amount of asset2 in millions of units. Specify a positive
number. Note that amount1 does not have to equal amount2. Example: For a short position and 50 million
units of asset2, specify 50.
11. corr Required. Number specifying the correlation of the log of the price relatives (returns) of asset1 and
asset2. Specify a number between -1 and 1, inclusive.
12. volatility1 Optional if VOLATILITY header is specified, required otherwise. Number specifying the volatility
VOLATILITY header is omitted then you must specify the volatility of asset1 in this field. If you provide
both a value in this field and a VOLATILITY header then this field’s value is used. Example: for 25%, specify
25.
13. volatility2 Optional if VOLATILITY2 header is specified, required otherwise. Number specifying the
volatility (annualized standard deviation) of the price of asset2 or the implied volatility, as a percent. If the
VOLATILITY2 header is omitted then you must specify the volatility of asset2 in this field. If you provide
both a value in this field and a VOLATILITY2 header then this field’s value is used. Example: for 20%,
specify 20.
Specify volatility1, volatility2, and corr with respect to ccy, regardless of the base or local currencies of asset1
and asset2 in the volatility-correlation dataset.
The dual-asset option models involve two assets against a third counter-asset ccy. combo_type specifies how
the two assets are to be combined. Four types of combinations are permitted between the two asset values:
1) the maximum, 2) the minimum, 3) the sum, and 4) the difference. Each of these types has a different
application. The ‚maximum‛ allows the option holder to receive delivery (upon option exercise) of the best
of two asset values; the ‚minimum‛ allows the option holder to receive delivery (upon option exercise) of
the worst of two asset values. Alternatively, the ‚sum‛ reflects the value of a portfolio of the two
commodities. The ‚difference‛ is normally employed for so-called ‚spread options,‛ which involve the
spread, or numerical difference, between asset prices.
For a short position, specify the first amount field (amount1) as a negative number. The second amount field
(amount2) must always be a positive number.
A binomial tree methodology is used to value dual-asset options, based on an approach suggested by P.
Boyle, 1988, ‚A Lattice Framework for Option Pricing with Two State Variables,‛ Journal of Financial and
Quantitative Analysis, 23, pp. 1–12.
Whereas one-state-variable binomial algorithms are O(n2), their two-state-variable counterparts are O(n3),
requiring substantial computation time for even small problems. In other words, 35 binomial iterations
involves 35 repetitive calculations on a 35-by-35 array. For this reason, dual-asset option calculations are
relatively slow.
Dual-asset options are priced using the cross-commodity forms of the FEA EUDU and AMDU models.
Contact FEA for more information.
Interest rates are linearly interpolated about opt_expiry using the ccy swap (S) interest-rate curves in the
available from FEA.
Also see Options.
Spread option
In this example, an American ‚spread option‛ is specified. The spread is between West Texas Intermediate
(WTI) and Brent Crude Oil (BCO) crude oil futures prices. Four-month WTI futures are now trading at
$21.25 and four-month BCO futures are now trading at $19.90. The (four-month) spread now is WTI – BCO =
$21.25 – $19.90 = $1.35. A three-month call option on this spread is struck at $1.30, upon 100,000 barrels of
each. WTI volatility is 68% and BCO volatility is 64%. The WTI-BCO correlation coefficient is 0.93.
(Remember that amount1 and amount2 are expressed in millions.)
USD,A,C,1.30,1/1/1997,S,WTI,BCO,0.1,0.1,0.93,68.0,64.0
Another common energy-related spread trade is an option on the ‚spark‛ spread, or the spread between
natural gas and electricity prices.
There are several competing possibilities for modeling spread options. One alternative is to consider the
spread itself as an asset price and use a simple model like OPTION which calculates European or American
options. Such a single-risk approach does not work well when the spread can become zero or negative.
Another alternative is to consider the spread plus some constant K to be the asset price, where K is chosen
so that the spread + K cannot become zero or less; but then, how does one choose K? Moreover, both of these
single-risk methods will predict equal hedge ratios (but of opposite sign) for the two assets involved in the
spread. The true dual-asset models predict different hedge ratios, which is often more realistic. For example,
consider a spread between a $1 asset and a $5 asset; a 10% price move will clearly affect the spread more if it
occurs to the more expensive of the two assets.
Best-of option
In this example, a European ‚choose-the-best‛ at-the-money call option for a U. S.-based investor is
specified. On expiration, the holder may purchase 3 oz. of gold (GLD) or 190 oz. of silver (SLV) for $1050.
GLD volatility is 26% and SLV volatility is 18%, with the correlation coefficient between them equal to 0.45.
By ‚choose-the-best‛ we mean what is best to the holder of the option. (Remember that amount1 and amount2
are expressed in millions).
USD,E,C,1050,1/1/1997,X,GLD,SLV,0.000003,0.000190,0.45,26.0,18.0
See Equities (Type II) below, for an alternative way to input equity trades.
*TYPE=EQUITY
Equity cash and futures positions are supported.
Cash equity with no dividends

ccy, underlying_ccy:equity_index, market_value, beta
Cash equity with dividends

ccy, underlying_ccy:equity_index, market_value, beta,,,, dividend_yield, dividend_method, dividend_list
<D, date, dividend,...>
Equity future
ccy, underlying_ccy:equity_index, market_value, beta, num_contracts, delivery_amount, fut_expiry,
dividend_yield, dividend_method, dividend_list <D, date, dividend,...>
1. ccy Required. Text specifying the accounting currency code of the equity or equity futures contract. See
Assets for information on currency codes. See The Euro for Euro-related issues.
3. market_value Required. Number specifying the market value of the equity position in millions of local
currency.
For cash positions (for example, individual shares) specify the market value of the total position in millions.
I.e.,
(number of shares  market price per share  long/short indicator) / 1000000.
The long/short indicator is +1 for a long position or -1 for a short position.
For futures equity positions (for example, CME S&P 500 futures) specify the (positive) market value of a
single futures contract in millions. I.e.,
(market price of contract  multiplier) / 1000000.
The multiplier is determined by the futures exchange.
4. beta Required. Number specifying the beta of the instrument with respect to the selected equity index. If
you are using a RiskMetrics dataset, see Remarks below for the market index corresponding to each ccy. If
the equity position (or underlying position) is the same as the measured index listed below then specify 1.0.
Otherwise specify the beta of the equity position to the measured index.
5. num_contracts Required for equity futures. Number specifying the number of futures contracts held.
Specify a positive number for a long position or a negative number for a short position. Examples: If you are
short 100 contracts, specify -100; if you are long 500 contracts, specify 500.
6. delivery_amount Optional for equity futures. Positive number specifying the delivery amount of the
contract in millions. For forward contracts, delivery_amount is the amount the holder is obliged to pay or
receive on fut_expiry for one unit of equity. For futures contracts, delivery_amount is
(delivery price  multiplier) / 1000000
where the delivery price is the price of the futures contract when it was purchased (or sold) and the
multiplier is determined by the futures exchange. Specifying the delivery price accounts (roughly) for
margin payments. If delivery_amount is omitted the delivery price is internally computed to make the
mark to market of the futures position equal to zero (day-to-day margin payments should be entered
separately as cash flows, in this case). Examples: If you bought (or sold) CME S&P 500 futures for 1100,
specify 0.275 = 1100  250 / 1000000; for a Spanish IBEX-35 future for 8900, specify 0.089 =
8900  10 / 1000000.
7. fut_expiry Required for equity futures. Date specifying the future’s expiration date.
8. dividend_yield Optional. Number specifying the annualized, continuously-compounded dividend rate of

the underlying equity, as a percent. For broad-based equity indices (which pay a steady stream of
dividends), we recommend you only specify dividend_yield and not dividend_method and dividend_list. Only
the ‚lumpy‛ dividends in dividend_list apply until the last dividend payment date; thereafter, only
dividend_yield applies; dividend_yield is ignored if the last dividend payment date in dividend_list falls on or
after fut_expiry. If dividend_yield is omitted then 0 (zero) is used. Example: for 5.5%, specify 5.5.
9. dividend_method Required if dividend_list is specified, ignored otherwise. Text specifying the dividend
method. Specify one of the following:
‘P’ for proportional dividend method.
‘C’ for constant dividend method (recommended).
items:
Example: D,3/1/1997,3.5,D,6/1/1997,3.5,D,9/1/1997,3.5
A word of caution for those with pre-version-2.1 Equity trade records: the first field (ccy) should be the same
as the second field (underlying_ccy) if you want to reproduce the previous results. For example, if your
previous records started:
USD,JPY,...
you should now use:
JPY,JPY,...
Otherwise, VaRworks will think the market_value/spot is in USD instead of JPY. See The Euro for more
information.
For options on cash or futures equity positions, see Equity Options.
Equities futures are discounted using the swap yield curve of ccy.
The beta is a measure of the expected change in the return of a stock given a change in the return of the
market index. It is defined as the covariance between a security’s return and the return on the market
portfolio divided by the variance of the return on the market portfolio. Specify a beta of 1.0 for the equity
indices listed above. The beta is incorporated into the cash flow map of each equity position.
Equity market risk is defined as the market value of the investment in that stock multiplied by the price
volatility estimate of that stock’s returns. If volatility estimates for individual stocks are unavailable, equity
positions are mapped to their respective local stock market indices. This methodology is based upon the
principles of single-index models such as CAPM that relate the return of the stock to the return of a stock
index.
Equity risk is mapped as market_value  beta and equity foreign exchange risk (where applicable) is mapped
as market_value. The equity price is calculated as [1 + beta  (index – 1)]. The mark-to-market value of index is
defined to be equal to one.
Constant and proportional dividends are supported. The constant dividend method assumes that the value
of cash dividends at certain dates in the future is known, and is independent of the asset price value on that
date. Use the proportional dividend method if you anticipate, instead, that the dividend payout will depend
on the asset price. The payout of a proportional dividend is determined by first taking the ratio of the
specified dividend payment (of dividend_list) to the spot price of the equity. The payout is product of this
ratio and the future value of the equity at the time of the payout. Note that, at least for reasonable time
periods and dividends, the two methods give quantitatively very similar results.
Continuous (‚smooth‛) dividends are supported through the dividend_yield field. The total dividend payout
is determined by the discrete (‚lumpy‛) portion until the last dividend date, and by the continuously
compounding yield portion from that date to expiration. For example, a long-dated option on a dividend-
paying stock might be best represented by lumpy payouts over a relatively short time horizon, and by an
average dividend yield thereafter.
Only lumpy dividends apply until the last date in dividend_list; thereafter, only dividend_yield applies.
The appropriate dividend amount does not necessarily equal the expected stock payout, but equals the
expected drop in share price on the ex-dividend date.
VARCARLO (but not VARANL) takes advantage of the dividend schedule. For example, suppose you
specify a cash equity position with dividends and have a horizon long enough that dividends will be paid
out before the horizon. VARCARLO will account for these dividends when it calculates the mark-to-market
value at the horizon. They’ll be treated like any other event that occurs before the horizon—if paid to you,
then they’ll be converted into government zero-coupon bonds.
The following table lists the RiskMetrics equity indices and exchanges for each currency. Exchange-traded
index futures and multipliers are listed where applicable.
RiskMetrics Equity Indices
Ccy Stock Exchange Stock Index Futures multiplier and

exchange (if applicable)
ARS Buenos Aires SE Merval
ATS Vienna SE Creditanstalt 100 OTOB
AUD Australian SE All Ordinaries 25 Sydney FE
BEF Brussels SE BEL 20 1000 BELFOX
CAD Toronto SE TSE 100 500 Toronto FE
CHF Zurich SE SMI 50 SOFFEX
DEM Frankfurt SE DAX 100 DTB
Ccy Stock Exchange Stock Index Futures multiplier and

exchange (if applicable)
DKK Copenhagen SE KFX 100000 DOFE
ESP Madrid SE IBEX 35 10 MEFF RV
FIM Helsinki SE Hex General
FRF Paris Bourse CAC 40 200 MATIF
GBP London SE FT-SE 100 25 LIFFE
HKD Hong Kong SE Hang Seng 50 HKFE
IDR Jakarta SE JSE
IEP Irish SE Irish SE ISEQ 10 IFOE
ITL Milan SE MIB 30
JPY Tokyo SE Nikkei 225 1000 Osaka SE
KRW Seoul SE KOPSI
MXN Mexico SE IPC
MYR Kuala Lumpur SE KLSE
NLG Amsterdam SE AEX
NOK Oslo SE Oslo SE General 100 Oslo SE
NZD New Zealand SE Capital 40 25 NZFOE
PHP Manila SE MSE Com’l & Inu’l Price
PTE Lisbon SE Banco Totta SI
SEK Stockholm SE OMX 100 OM
SGD SE of Singapore Singapore All Share
THB Bangkok SE SET
TWD Taipei SE TSE
USD New York SE S&P 100 250 CME (S&P 500)
XEU
ZAR Johannesburg SE JSE
For a technical discussion of pricing equity derivatives see the @EQUITY User’s Guide, available from FEA.

Suppose we are long 100,000 shares of IBM @ US$125.00 per share. Assume IBM has a beta of 1.23 with
respect to the measured index. The values of each field are:
Field Value
ccy USD
underlying_ccy USD
market_value 12.5 = (100,000  125.00  +1) / 1000000
beta 1.23
The record is:

USD,USD,12.5,1.23
Cash equity with no dividends: In-Euro currency

(Note that this kind of transaction is only supported for historical calculations after January 1, 2002.)
Suppose we have a long cash position in a German equity with a market value of 68,000 Euros. Assume that
this equity has a beta of 1.29 relative to the DAX (or some other measured index of German equities). The
values of each field are:
Field Value
ccy EUR
underlying_ccy DEM
Field Value
market_value 0.068
beta 1.29
The record is:

EUR,DEM,0.068,1.29
Cash equity with no dividends: User-defined index

Suppose we have the same cash position in IBM as in the first example above, but instead of mapping the
position to an index using the beta, we prefer to define a vertex for IBM in our custom volatility-correlation
dataset. The values of each field are:
Field Value
ccy USD
underlying_ccy USD:IBM
market_value 12.5
beta 1
The record is:

USD,USD:IBM,12.5,1

Suppose have the same cash position in IBM as in the first example above but with a list of expected
dividends. The values of each field are:
Field Value
ccy USD
underlying_ccy USD
market_value 12.5 = (100,000  125.00  +1) / 1000000
beta 1.23
num_contracts <Null>
delivery_amount <Null>
fut_expiry <Null>
dividend_yield <Null>
dividend_method C
dividend_list D,3/1/1998,3.5,D,6/1/1998,3.5,D,9/1/1998,3.5
The record is:

USD,USD,12.5,1.23,,,,,C,D,3/1/1998,3.5,D,6/1/1998,3.5,D,9/1/1998,3.5
Cash equity with dividend yield

Suppose have the same cash position in IBM above but with an expected 3% dividend yield rather than a
dividend list. The values of each field are:
Field Value
ccy USD
underlying_ccy USD
market_value 12.5 = (100,000  125.00  +1) / 1000000
beta 1.23
num_contracts <Null>
delivery_amount <Null>
fut_expiry <Null>
dividend_yield 3.0
dividend_method <Null>
Field Value
dividend_list <Null>
The record is:

USD,USD,12.5,1.23,,,,3.0
Equity future
Suppose you are short 1000 CME S&P 500 futures contracts for delivery at 1089.74 on 1/1/1999. Assume the
market price is 1040.25 and the S&P 500 yields 3% and has a beta of 1.08 with respect to the measured index.
The multiplier of the contract is $250 times the index. The values of each field are:
Field Value
ccy USD
underlying_ccy USD
market_value 0.2600625 = (1040.25  250) / 1000000
beta 1.08
num_contracts -1000
delivery_amount 0.272435 = (1089.74  250) / 1000000
fut_expiry 1/1/1999
dividend_yield 3.0
The record is:

USD,USD,0.2600625,1.08,-1000,0.272435,1/1/1999,3.0
*TYPE=EQUITYAPO
European average-price options on dividend-paying equities are supported. See Equity Options for a
description of equities. See Asian Options for a description of average-price options.
ccy, underlying_ccy:equity_index, amount, ex_type, pc_type, strike, opt_expiry, spot, beta, volatility,
dividend_yield, start_date, old_average, num_periods
1. ccy Required. Text specifying the accounting currency code of the option. See Assets for information on
3. amount Required. Number specifying the amount of the underlying equity. Specify a positive number for
a long position or a negative number for a short position. See the amount field in Equity Options for more
information.
4. ex_type Required. Text specifying the option exercise type. Specify the following:
‘C’ for call option (underlying equity is bought).
‘P’ for put option (underlying equity is sold).
6. strike Required. Number specifying the option’s strike price (per share) in ccy terms.
8. spot Required. Number specifying the spot price of one share of the underlying equity in ccy terms.
9. beta Optional. Number specifying the beta of the underlying equity with respect to the market index. The
market value of the equity at any time is related to a stochastic market index I (normalized to one) using:
At mark-to-market, the normalized index I has a value of one. If omitted, beta is assumed to be one.
(annualized standard deviation or implied volatility) of the price of the underlying equity or the implied
volatility, as a percent. If the VOLATILITY header is omitted you must specify the volatility in this field. If
you provide both a value in this field and a VOLATILITY header, this field prevails. Example: for 25%,
specify 25.
of the equity, as a percent. If omitted, dividend_yield is assumed to be zero. Example: for 5.5%, specify 5.5.
12. start_date Optional. Date specifying when the underlying equity averaging period begins. (The
averaging period always ends on opt_expiry.) If start_date falls on the effective calculation date (typically
today), then the averaging period starts on the effective calculation date and old_average is ignored. If
start_date falls after the effective calculation date, then the averaging period is forward-starting
and old_average is ignored. If start_date falls before the effective calculation date, then old_average reflects the
average up to the effective calculation date, and averaging continues until opt_expiry.
13. old_average Optional if start_date falls before the effective calculation date; ignored otherwise. Number
specifying the average price of the underlying equity from start_date until the effective calculation date
(typically today), as determined by past price observations. If start_date falls before the effective calculation
date and old_average is omitted, then old_average is set to spot.
14. num_periods Required. Number specifying the number of equally-spaced time periods in the averaging
period, which must be an integer greater than or equal to one. For example, to specify weekly averaging
over a period of one month, specify four. If num_periods is omitted or zero, then num_periods is chosen to
reflect daily averaging.
See the Remarks section of Equity Options for more information.
USD call on monthly-averaged price of USD stock w/ yield 5%

USD,USD,0.01,E,C,50,12/1/1999,55.125,1,25,5,1/1/1999,52,12
JPY put on forward-starting daily-averaged price of JPY stock w/ yield 2%

JPY,JPY,0.1,E,P,5100,1/1/2000,5000,1,,2,7/1/1999
EUR-denominated put on forward-starting daily-averaged price of Nikkei 225

EUR,JPY,0.1,E,P,70,12/1/1999,66,1,,2,7/1/1999
*TYPE=EQUITYOPTION
*SMILEMODEL=deterministic volatility model [optional]
American and European options on dividend-paying equities are supported. An equity is a security or asset
which 1) possesses a broad-based market price that represents its sole source of uncertainty, 2) has ‚lumpy‛
payouts to ownership, and 3) has random-walk behavior in its price fluctuations, arising from a long-lived
quality. The underying can be a spot equity, or an equity futures.
The deterministic volatility model corrections can be included in the instrument valuation by specifying
either S or M0 as the value of the SMILEMODEL header. The risk connected with the stochastic changes of
the implied volatility is included in the VaR calculation if the VOLMODEL header is set to SV. See,
Volatility as a Risk Factor section on page 54 for more details.
ccy, underlying_ccy:equity_index, amount, ex_type, pc_type, strike, fut_expiry, opt_expiry, spot, beta,
volatility, dividend_yield, dividend_method, dividend_list <D, date, dividend,...>
3. amount Required. Number specifying the amount of the underlying equity. Specify a positive number if
you are long or a negative number if you are short.
For options on cash positions (for example, individual shares) specify the amount of the total position
(number_of_shares * long_short_flag) / 1000000
where long_short_flag is +1 for a long position or -1 for a short position.
For options on equity futures (for example, CME S&P 500 futures options) specify the amount of the futures
contract
(number_of_contracts * exchange_multiplier * long_short_flag) / 1000000
where exchange_multiplier is determined by the futures exchange and long_short_flag is +1 for a long position
or -1 for a short position.
The multiplier of 1/1000000 converts currency units to millions of currency units, where currency units are
specified in strike and spot.
7. fut_expiry Optional. Date specifying the equity futures expiration date. Specify fut_expiry if the option is
on an equity futures, not on spot equity. If specified, fut_expiry must fall on or after opt_expiry. If omitted,
it is assumed the option is on spot equity.
9. spot Required. Number specifying the spot price of one share of the underlying equity in ccy terms. For
options on an equity futures, dividends and market interest rate information are used to derive the futures
price underlying the option.
10. beta Optional. Number specifying the beta of the underlying equity with respect to the market index.
The market value of the equity at any time is related to a stochastic market index I (normalized to one) using
At mark-to-market, the normalized index I has a value of one. If omitted, beta is assumed to be one.
11. volatility Optional. Number specifying the volatility (annualized standard deviation or implied
volatility) of the price of the underlying equity or the implied volatility, as a percent . The actual volatility
used in valuing the option, however, depends on the risk model being used. In the case when the
SMILEMODEL header is specified and is not set to NONE, the volatility internally interpolated from the
smile surface is used in the valuation, and the volatility input is not used. If the smile surface for the
underlying is not specified, or the VOLMODEL is set to SV (Stochastic volatility) then the volatility input
from the trade record is used. If volatility is omitted, the volatility specified in the volatility header will be
used, unless a stochastic volatility model is being used in which case the implied volatility corresponding to
the underlying is extracted from the dataset and used. Finally, if no volatility input is specified in either
trade record, header, smile file, or implied vol dataset an error will be returned.
of the equity, as a percent. Only the ‚lumpy‛ dividends in dividend_list apply until the last dividend
payment date; thereafter, only dividend_yield applies; dividend_yield is ignored if the last dividend payment
date in dividend_list falls on or after opt_expiry. If dividend_yield is omitted then 0 (zero) is used. Example: for
5.5%, specify 5.5.
items:
3. Dividend (units of underlying_ccy—not a percent).
Example: D,3/1/1997,3.5,D,6/1/1997,3.5,D,9/1/1997,3.5
A word of caution for those with pre-version-2.1 Equity Option trade records: the first field (ccy) should be
the same as the second field (underlying_ccy) if you want to reproduce the previous results. For example, if
your previous records started:
USD,JPY,...
you should now use:
JPY,JPY,...
Otherwise, VaRworks will think the market_value/spot is in USD instead of JPY. See The Euro for more
information.
Since returns on many broad-based equity indices (for example, S&P 500) behave similarly to the returns of
commodities, you may enter equity-index options as OPTION records.
Equities are discounted using the swap yield curve of underlying_ccy.
See Remarks under Equities for a discussion of beta and dividends.
The cash flow positions of equity options are mapped like those of options on the spot foreign exchange (see
Options).
For American options on spot equities, shredded cash flows (see page 17) correspond to a spot equity
position and to an accounting currency cash position. For European options they correspond to a spot
equity position and to a series of cashflows in the accounting currency with terms determined by the expiry
date of the option and the timing of the discrete dividends.
In the case of American options on spot equity, the equivalent spot equity position is determined by the
delta of the option, i.e.
CFspot = S  V(S)/S
where V(S) is the present value of the option as a function of S, and S is the spot equity price. Further
mapping to the underlying index, via the relation
S = S0  (1 +   (I – 1))
where I is the equity index (by construction I is equal to one at value date), produces an equity index
cashflow as
CFindex=   CFspot 1)
The accounting currency cash position corresponding to the strike of the option is given by
CF ccy(t=0)= V – CFspot
In the case of European options on spot equity, it is convenient to equivalently think of the instrument as
an option on an equity futures contract expiring at a time T F , with TF equal to the expiration of the option
T. The mark to market of the option can then be expressed as a function of the forward value of the equity,
F,
F = (S – PVdividends)  exp(rTF)
where PVdividends represent the present value of dividends paid before the expiration of the futures
contract TF. Note that, if the continuous dividend yield (dividend_yield) is not zero, the formula for F must be
slightly modified to account for it.
The cash flows associated with the equity exposure can then be derived by using
CFequity = F  V(F)/F
where V(F) is the present value of the option as a function of F. By expanding F and defining
CFspot = S  exp(rTF)  V(F)/F
we can construct the equity index cash flow as in Eq. 1) above, and derive the (present valued) cash flow
associated to each dividend paid at a time t(i) < T, as
PV(CF ccy(t=t(i)) )= – CFspot / S  PV(divi)
where PV denotes present value and divi is the dividend paid at time t(i). The final cash flow associated
with the strike price is placed at the option expiry T, and its present value is given by
PV(CFccy(t=T) )= V(F) – CFequity
For options on equity futures, the derivation is similar to the one for European options on spot equity, but
TF (the futures expiration term) is now allowed to be different from T (the option term).
If the VOLMODEL header is set to SV, the risk associated with the implied volatility is included into the
VaR calculation. For the description of the additional cashflows used to describe vega risk, and for a
discussion on the relation between the market volatility input specified in the trade record and the vol levels
specified in the volatility file, see Analytic VaR with the Implied Volatility Risk on page 57. For dataset
requirements to include vega risk see page 58.
Option on an equity future

Suppose we are long a put on a CME S&P 500 futures contracts struck at 1089.74 expiring 1/1/1999. Assume
the S&P 500 yields 3% and has a beta of 1 with respect to the index measured in the volatility correlation
dataset (i.e. the index is the S&P 500 itself) . The multiplier of the contract is $250 times the index. The
implied volatility is 35%. The field values are:
Field Value
ccy USD
underlying_ccy USD
amount 0.00025 = (1  250  1) / 1000000
ex_type A
pc_type P
strike 1089.74
fut_expiry 1/1/1999
opt_expiry 1/1/1999
spot 1040.25
beta 1.0
volatility 35.0
dividend_yield 3.0
The record is:

USD,USD,0.00025,A,P,1089.74,1/1/1999,1/1/1999,1040.25,1.0,35.0,3.0
Option on cash equity with dividends

USD,USD,0.0001,E,C,50,1/1/1997,55.125,1.15,25,4.50,C,D,6/1/1996,4.00,D,9/1/1996,
4.50
Option on cash equity with dividend yield

JPY,JPY,0.01,A,P,5100,1/1/1997,5000,0.99,45,3
Nikkei 225 denominated in Euros

EUR,JPY,-10,E,P,70,1/1/2000,66
There are two ways in which equity trades can be specified in VaRworks: by using the header
*TYPE=EQUITY, see above, or by using the header *TYPE=EQUITY2. The EQUITY2 type provides an
equivalent description of equity cash positions through a more streamlined and somewhat more intuitive
record layout. With this alternative layout, some of the market information about the specific equity, like its
unit share price and its beta with respect to a particular equity index, is moved to an appropriate asset file.
In addition, the EQUITY2 type allows for a wider choice of modeling of the equity price when computing
VaR.
*TYPE=EQUITY2
Equity cash positions are supported.

ccy, equity_name, amount, risk_type

ccy, equity_name, amount, risk_type, dividend_yield, dividend_method, dividend_list <D, date,
dividend,...>
1. ccy Required. Text specifying the accounting currency code of the equity. See Assets for information on
currency codes.
2. equity_name Required. Text specifying the user defined name of the underlying equity.
See Assets for information on custom equity names. If alternative identifiers (like CUSIP, or TICKER
symbols) for the equity names are provided in the asset file, the underlying equity can be referred to by
using any of these identifiers. The equity name and the alternative identifiers must, in that case, uniquely
identify the equity.
3. amount Required. Number specifying the number of shares corresponding to the equity position divided
by 1,000,000. Specify a positive (negative) number for a long (short) position. By dividing by 1,000,000 we
are defining the units corresponding to the position value to be in millions of currency units.
4. risk_type Required. Text specifying the risk model to be used when performing value at risk
calculations. Specify one of the following:
Market information like the equity market value or its beta coefficient with respect to an equity index must
be contained in the appropriately defined asset file. Volatilities and correlations corresponding to all sources
of risk must be specified in the volatility and correlation files.

dividends), we recommend you only specify dividend_yield and not a dividend_list. The ‚lumpy‛ dividends
in dividend_list apply until the last dividend payment date; thereafter, only dividend_yield applies; If
dividend_yield is omitted then 0 (zero) is used. Example: for 5.5%, specify 5.5.
items:
3. Dividend (units of ccy—not a percent) per share.
Example: D,3/1/2004,3.5,D,6/1/2004,3.5,D,9/1/2004,3.5
The equity market risk of an investment in a stock, in the delta mapping approximation, is defined as the
market value of that investment multiplied by the price volatility estimate of that stock’s returns. If volatility
estimates for individual stocks are unavailable, equity positions may be mapped to appropriate stock
market indices, to which the equity are linked via the appropriate beta coefficient (use risk_type = ‘B’). This
methodology is based upon the principles of single-index models such as CAPM that relate the return of the
stock to the return of a stock index.
See Remarks under Equities for a discussion of dividends, or of how beta coefficients are used, if risk_type=
‘B’ is selected.
A portfolio containing several equity trades (*TYPE=EQUITY2, *TYPE=EQUITYOPTION2) may be analyzed

using any combination of single factor models.
There are two ways in which equity futures trades can be specified in VaRworks: by using the header
*TYPE=EQUITY, see above, or by using the header *TYPE=EQUITYFUTURES2. The EQUITYFUTURES2
type provides an equivalent description of equity futures positions through a more streamlined and
somewhat more intuitive record layout. With this alternative layout, some of the market information about
the specific equity, like its unit share price and its beta with respect to a particular equity index, is moved to
an appropriate asset file. In addition, the EQUITYFUTUES2 type allows for a wider choice of modeling of
the equity price when computing VaR.
*TYPE=EQUITYFUTURES2
Equity futures positions are supported.
Equity futures with no dividends

ccy, equity_name, amount, risk_type, strike_price, fut_expiry
Equity futures with dividends

ccy, equity_name, amount, risk_type, strike_price, fut_expiry, dividend_yield, dividend_method,
dividend_list <D, date, dividend,...>
currency codes.
See Assets for information on custom equity names. If alternative identifiers (like CUSIP, or TICKER
3. amount Required. Number specifying the number of shares the futures contract is on. This is the number
of contracts times the number of shares per contract. The number of shares per contract is set by the
exchange.
4. risk_type Required. Text specifying the risk model to be used when performing value at risk
calculations. Specify one of the following:
5. strike_price Optional. Number specifying the price at which the futures contract was entered into. If
omitted the strike price is internally computed to make the mark to market of the futures position equal to
zero.
6. fut_expiry Required. Date specifying the expiration of the futures contract.

dividends), we recommend you only specify dividend_yield and not a dividend_list. The ‚lumpy‛ dividends
in dividend_list apply until the last dividend payment date; thereafter, only dividend_yield applies; If
dividend_yield is omitted then 0 (zero) is used. Example: for 5.5%, specify 5.5.
items:
3. Dividend (units of ccy—not a percent) per share.
Example: D,3/1/2004,3.5,D,6/1/2004,3.5,D,9/1/2004,3.5
The equity market risk of an investment in a stock, in the delta mapping approximation, is defined as the
market value of that investment multiplied by the price volatility estimate of that stock’s returns. If volatility
estimates for individual stocks are unavailable, equity positions may be mapped to appropriate stock
market indices, to which the equity are linked via the appropriate beta coefficient (use risk_type = ‘B’). This
methodology is based upon the principles of single-index models such as CAPM that relate the return of the
stock to the return of a stock index.
A portfolio containing several equity trades (*TYPE=EQUITY2, *TYPE=EQUITYOPTION2) may be analyzed

using any combination of single factor models.
There are two ways in which equity option trades can be specified in VaRworks: by using the header
*TYPE=EQUITYOPTION, see above, or by using the header *TYPE=EQUITYOPTION2. The
EQUITYOPTION2 type provides an equivalent description of the option trade through a streamlined and
somewhat more intuitive record layout. With this alternative layout, some of the market information about
the specific equity, like its unit share price and its beta with respect to a particular equity index, is moved to
an appropriate asset file. In addition, the EQUITYOPTION2 type allows for a wider choice of modeling of
the equity price when computing VaR. The underying can be a spot equity, or an equity futures.
*TYPE=EQUITYOPTION2
American and European options on dividend-paying equities are supported. An equity is a security or asset
which 1) possesses a broad-based market price that represents its sole source of uncertainty, 2) has ‚lumpy‛
payouts to ownership, and 3) has random-walk behavior in its price fluctuations, arising from a long-lived
quality.
The deterministic volatility model corrections can be included in the valuation of the instrument by
specifying either S or M0 model in the SMILEMODEL header. The risk connected with the stochastic
changes of the implied volatility is included in the VaR calculation if the VOLMODEL header is set to SV.
See, Volatility as a Risk Factor section on page 54 for more details.
ccy, equity_name, amount, risk_type, ex_type, pc_type, strike, fut_expiry, opt_expiry, volatility,
dividend_yield, dividend_method, dividend_list <D, date, dividend,...>
currency codes.
2. equity_name Required. equity_name Required. Text specifying the user defined name of the underlying
equity. See Assets for information on custom equity names. If alternative identifiers (like CUSIP, or TICKER
3. amount Required. Number specifying the number of shares underlying the option, divided by 1,000,000.
Specify a positive (negative) number for a long (short) option position.
For options on cash positions (for example, individual shares) specify the amount of the total position
(number_of_shares * long_short_flag) / 1,000,000
where long_short_flag is +1 for a long position or -1 for a short position.
For options on equity futures (for example, CME S&P 500 futures options) specify the amount of the futures
contract
(number_of_contracts * exchange_multiplier * long_short_flag) / 1,000,000
where exchange_multiplier is determined by the futures exchange and long_short_flag is +1 for a long position
or -1 for a short position.
By dividing by 1,000,000 we are defining the units corresponding to the position value to be in millions of
currency units.
4. risk_type Required. Text specifying the model to be used when doing value at risk calculations. Specify

8. fut_expiry Optional. Date specifying the equity futures expiration date. Specify fut_expiry if the option is
on an equity futures, not on spot equity. If specified, fut_expiry must fall on or after opt_expiry. If omitted,
it is assumed the option is on spot equity.
10. volatility Optional. Number specifying the volatility (annualized standard deviation or implied
volatility) of the price of the underlying equity or the implied volatility, as a percent . The actual volatility
used in valuing the option, however, depends on the risk model being used. In the case when the
SMILEMODEL header is specified and is not set to NONE, the volatility internally interpolated from the
smile surface is used in the valuation, and the volatility input is not used. If the smile surface for the
underlying is not specified, or the VOLMODEL is set to SV (Stochastic volatility) then the volatility input
from the trade record is used. If volatility is omitted, the volatility specified in the volatility header will be
used, unless a stochastic volatility model is being used in which case the implied volatility corresponding to
the underlying is extracted from the dataset and used. Finally, if no volatility input is specified in either
trade record, header, smile file, or implied vol dataset an error will be returned.
of the equity, as a percent. Only the ‚lumpy‛ dividends in dividend_list apply until the last dividend
payment date; thereafter, only dividend_yield applies; dividend_yield is ignored if the last dividend payment
date in dividend_list falls on or after opt_expiry. If dividend_yield is omitted then 0 (zero) is used. Example: for
5.5%, specify 5.5.
items:
Example: D,3/1/2004,3.5,D,6/1/2004,3.5,D,9/1/2004,3.5
Equities are discounted using the swap yield curve of underlying_ccy.

When mapping equity options, the equity and strike cash flows are determined from their respective deltas.
Depending on the risk_type selected, the equity exposures for the option is either directly mapped onto the
equity (risk_type = ‘S’), or it is mapped to the appropriate equity_index (risk_type = ‘B’) using the beta
coefficient specified in the asset file. In the former case CFequity =   spot_price  amount, in the latter
case, CFequity_index =   spot_price  amount  beta. For options on equity futures, CFequity is
computed by using the delta with respect to the futures price (see the Remarks section in EQUITYOPTION
on page 193 for additional details).
*TYPE=EQUITYPROXY
The equity proxy trade allows the evaluation of the risk associated to a particular equity, when
price information for that equity is non-existent or limited to a series of spot prices, which themselves may
represent too small a set of historical data from which to extract reliable statistical information. The
Remarks section, below, describes the types of valuation schemes supported.
ccy, equity_name, amount, proxy1, weight1, proxy2, weight2, proxy3, weight3
currency codes.
See Assets for information on custom equity names.
3. amount Required. Number specifying the number of shares corresponding to the equity position divided
by 1,000,000. Specify a positive (negative) number for a long (short) position. By dividing by 1,000,000 we
are defining the units corresponding to the position value to be in millions of currency units.
4. proxy1 Required. Text specifying a proxy equity which is in whole or part (depending on weight1, weight2,
and weight3) representative of the dynamics of the underlying's equity. See Assets for information on
custom equity names.
5. weight1 Required. Number specifying the weight given to the proxy1 equity. The representative proxy for
the underlying equity is the weighted sum of all specified proxies.
6. proxy2 Optional. Text specifying a second proxy equity which is in whole or part (depending on weight1,
weight2, and weight3) representative of the dynamics of the underlying's equity. See Assets for information
on custom equity names. If omitted a second proxy, and its corresponding weight (weight2) will not be
used.
7. weight2 Optional unless proxy2 is specified. Number specifying the weight given to the proxy2 equity.
The representative proxy for the underlying equity is the weighted sum of all specified proxies. If proxy2 is
missing weight2 is assumed to have zero value.
8. proxy3 Text specifying a third proxy equity which is in whole or part (depending on weight1, weight2,
and weight3) representative of the dynamics of the underlying's equity. See Assets for information on
custom equity names. If omitted a third proxy, and its corresponding weight (weight3) will not be used.
9. weight3 Optional unless proxy3 is specified. Number specifying the weight given to the proxy3 equity.
The representative proxy for the underlying equity is the weighted sum of all specified proxies. If proxy3 is
missing weight3 is assumed to have zero value.
When mapping an equity proxy trade, the underlying equity cash flow is mapped onto cashflows of the
specified proxies, by using the specified weights, i.e.
CFequity = (w1 CFproxy1 + w2 CFproxy2+ w3 CFproxy3)/W, where W= w1+ w2+ w3 and CFproxyi
= spot_price  amount (i=1,2,3). spot_price is the unit price of the equity as specified in the asset file. For
simulation analysis we use the returns of the three proxies to define a proxy return for the underlying equity
requity = (w1 rproxy1 + w2 rproxy2+ w3 rproxy3)/W .
requity is then used to obtain the simulated price of the underlying equity.
*TYPE=EUROFUT
Eurocurrency futures and other short-term interest-rate futures are supported. This section describes U.S.
dollar Eurodeposits, or Eurodollars, but the concepts are analogous for other currencies, such as Euromarks
and Euroyen.
A Eurodollar is a U.S. dollar deposited in a U.S. or foreign bank outside the United States. The Eurodollar
rate is the rate of interest earned on Eurodollars deposited by one bank with another bank. This rate is also
known as the London Interbank Offer Rate (LIBOR). Eurodollar rates are generally higher than the
corresponding Treasury bill rates due to the spread between commercial lending and government
borrowing rates.
The Eurodollar futures contract is heavily traded on the International Monetary Market (IMM), Singapore
International Monetary Exchange (SIMEX), London International Futures Exchange (LIFFE), and other
exchanges.
ccy, num_contracts, purchase_price, fut_expiry, contract_size, rate_term
currency codes.
3. purchase_price Required. Number specifying the IMM-style contract purchase price, that is, the agreed-
upon exercise price of the contract to be paid or received on fut_expiry. See Remarks below for an
explanation of IMM-style prices. Example: For a rate of 4.55%, specify 95.45.
4. fut_expiry Required. Date specifying the futures contract’s expiration date.
5. contract_size Required. Number specifying the contract size (notional principal) in millions of local
currency. contract_size is always positive. For example, for a principal of 1,000,000 specify 1.
6. rate_term Required. Number specifying the rate term in months. rate_term must be greater than or equal
to 0.25 (one week) and less than or equal to 12 (one year). Example: For a three-month rate, specify 3.
IMM-style Eurodollar rates are quoted as percents subtracted from 100. For example a quote of 95.50
corresponds to a Eurodollar rate of 4.5% [= (100 – 95.50) / 100]. (This quote style is used so the bid is lower
than the ask.)
A Eurodollar rate is the actual 90-day rate on Eurodollar deposits compounded quarterly.
To understand how this instrument is mapped, consider a Eurocurrency futures contract on an underlying
deposit that matures at T2 = T1 + T, where T1 is the fut_expiry time and T is rate_term/12.
We define two bonds that mature at the beginning and at the end of the deposit period in terms of the
continuously compounded interest rates from the ccy SWAP yield curve.
B1 = exp(-r1  T1)
B2 = exp(-r2  T2).
The value of the futures contract is
PV = A  (R – Q)  T  B1
where
A = contract_size  num_contracts
Q = 1 – purchase_price / 100
T = rate_term / 12
T1 = fut_expiry
R = the forward rate from T1 to T2.
(Note that A  (R – Q)  T is the (expected) payoff of the futures contract on fut_expiry. So we discount to
today with B1 to get the present value.)
R is calculated this way:
R = c  (B1 /B2 – 1) / T
c = 360 / 365
Following the procedure described in the technical reference section on analytic VaR, the instrument will be
shredded into two present valued cashflows, identified by a (ccy, credit, time) triple
CF1 (ccy, SWAP, T1) = PV/B1× B1 = PV + c  A  B1  B1 / B2

CF2 (ccy, SWAP, T2) = PV/B2× B2 = -c  A  B1  B1 / B2.
(Note that PV = CF1 + CF2.)
These cashflows will then be allocated to standard risk vertices, e.g., if CF 1 is (USD, SWAP, 2.25), it would be
allocated to the standard vertices USD. S02, USD.S03 (and USD.XS if USD is not the home currency).
FEA.
IMM 3-Month Eurodollar future

USD,1,95.00,1/1/1997,1,3
*TYPE=EUROFUTOPT
European options on Eurocurrency futures are supported via the Black (1976) model, both on interest rate
(BLACKY), the preferred model, and price (BLACKP). See Eurocurrency Futures for more information.
opt_expiry, pc_type, ccy, num_contracts, strike, fut_expiry, contract_size, rate_term
‘C’ for call option (underlying future is bought).
‘P’ for put option (underlying future is sold).
currency codes.
4. num_contracts Required. Number specifying the number of option contracts held. Specify a positive
5. strike Required. Number specifying the option’s IMM-style strike price (see Remarks below). Example:
For a strike price of 4.55%, specify 95.45.
6. fut_expiry Required. Date specifying the expiration date of the underlying future.
7. contract_size Required. Number specifying the underlying futures contract size (notional principal) in
millions of local currency. For example, for a principal of 1000000, specify 1.
8. rate_term Required. Number specifying the rate term in months. Example: For a three-month rate, specify
3.
opt_expiry must fall on or before fut_expiry.
Specify the volatility of Eurocurrency futures options with the VOLATILITY header.
See Eurocurrency Futures for more information.
FEA.
Call option on an IMM 3-Month Eurodollar future

1/1/1997,C,USD,1,95.00,3/1/1997,1,3
*TYPE=XRATE
*REBASE_CCY=CCY
If you don’t want to use the exchange rates in the volatility file, you can specify your own. Exchange rate
files contain currency exchange rates. FX rates are used for home currency conversions during cash flow
mapping.
Tip You can create exchange rate files from volatility files using the GENRATES utility. See GENRATES
ccy, exchange_rate
1. ccy Required. Text specifying the counter-currency. See Assets for information on currency codes.
2. exchange_rate Required. Number specifying the exchange rate in terms of U.S. dollars per unit of ccy
(USD/ccy).
Currency exchange rates are always specified with U.S. dollars as the numerator. Even exchange rates that
are normally quoted as ccy/USD in the market must be specified as USD/ccy.
CAD,0.725847
CHF,0.867679
EUR,0.718339
GBP,1.604600
JPY,0.011853
*TYPE=FORWARD
A currency forward is an agreement to exchange a specified amount of one currency for another at a future
date at a certain exchange rate.
The Mark to Market of the contract in the accounting currency is determined by using the formula :
MtM= A  FX(bc) exp(-t(rbc  r))  A  X  FX(sc) exp(-t(rsc  r))
where
FX(bc)= spot exchange rate converting buy_ccy into accounting currency
FX(sc)= spot exchange rate converting sell_ccy into accounting currency
r = zero rate (accounting ccy) for term t, continuous compounding
rbc , rsc = zero rates (buy_ccy and sell_ccy) for term t, continuous compounding
t = time to maturity in years
X = contract exchange rate (exchange_rate below)
A discussion of forward prices can be found in Hull (1997).
buy_ccy, sell_ccy, amount, exchange_rate, value_date
1. buy_ccy Required. Text specifying the currency being bought. See Assets for information on currency
codes.
2. sell_ccy Required. Text specifying the currency being sold. See Assets for information on currency codes.
3. amount Required. Number specifying the amount in millions of buy_ccy being bought. Example: For 20
million, specify 20.
4. exchange_rate Optional. Number specifying the contract exchange rate in terms of units of buy_ccy per
unit of sell_ccy. If omitted, exchange_rate is determined as the ‚fair‛ MtM, i.e. as the value that makes the
MtM of the contract equal to zero.
5. value_date Required. Date specifying when the agreed upon currency exchange takes place.
If amount is positive then buy_ccy is a positive cash flow and sell_ccy is a negative cash flow, if it is negative
the signs of the cashflows are reversed.
For foreign currency deposits, use money market (CD) files.
USD,JPY,10,0.011123,1/1/1998
EUR,JPY,25,0.015244,1/1/2001
*TYPE=FWDOPT
Forward-start options are paid for now but will start some time in the future. The strike price is set on a
predetermined date—the forward-start date—after inception of the option, rather than when the option is
granted. The strike can be set to a predetermined price, the underlying asset’s spot price, the underlying
asset’s forward price (at the option’s expiration), or the fair price of a fixed-for-floating daily swap (to model
monthly index prices).
When the strike is set it may be adjusted up or down by a prearranged amount, called the markup.
ccy, asset, ex_type, pc_type, opt_expiry, amount, fwd_start_date, volatility, strike_type, strike, markup,
fut_expiry, risk_type, dividend_yield, spot, beta
currency codes.
3. ex_type Required. Text specifying the option exercise style. Specify one of the following:
4. pc_type Required. Text specifying the type of option. Specify one of the following:
‘S’ for a straddle (a put and a call with the same strike price).
6. amount Required. Number specifying the underlying amount, in millions, used to calculate the total
option position.
7. fwd_start_date Required. Date specifying when the option’s strike is set.

9. strike_type Optional. Text specifying how the strike price is set. The strike is always set on fwd_start_date.
If strike_type is omitted , it is assumed to be ‘S’. Specify one of the following:
strike_type Description
‘D’ Deferred start or defined strike. The strike is set to strike. ‘d’ is used with
American-style options that can only be exercised on or after fwd_start_date
rather than on or after the option’s inception (that is, the effective calculation
date). It is also used to price a forward starting option that has already
converted into a regular option (see Remarks below).
‘F’ Forward. The strike is set to the asset’s forward price (plus markup) for delivery
on opt_expiry. strike is ignored.
‘I’ Index. The strike is set to the fair fixed price (plus markup) of a swap on the asset
valued on fwd_start_date. The reference swap is a daily fixed-for-float index
swap that starts on fwd_start_date plus one day and matures 30 days later. strike
is ignored.
‘S’ or omitted Spot. The strike is set to the asset’s spot price (plus markup). strike is ignored.
10. strike Required for deferred-start options (strike_type ‘D’), or if fwd_start_date is in the past. Ignored
otherwise. Number specifying the option’s strike price expressed as ccy per unit of asset.
11. markup Optional. Number specifying how many accounting currency units to add to the strike price on
fwd_start_date. markup can be positive or negative. If markup is omitted, it is assumed to be zero.
12. fut_expiry Optional. Date specifying when the underlying futures contract expires. Omit fut_expiry if the
option calls for delivery of a physical asset or settles against the spot price of the underlying asset.
If the forward start date (fwd_start_date) is equal or precedes the valuation date the forward starting option
turns into a regular option. In this case make sure that strike_type is set to ‚D‛ and specify the strike price
as an input.
Forward-start options are priced using FEA @ENERGY models. For a technical discussion of pricing
currency and commodity derivatives see the @ENERGY User’s Guide, available from FEA.
Long European forward-start call option on GAS physical

USD,GAS,E,C,3/1/1999,1,2/1/1999,14,F
Short European deferred-start put option on GBP futures

EUR,GBP,E,P,3/1/1999,-125,2/1/1999,,D,0.6,,5/1/1999
Short European forward-start straddle on GAS futures struck against fair fixed index swap
GBP,GAS,E,S,3/1/1999,-25,2/1/1999,,I,,,5/1/1999
*TYPE=FRA
Forward rate agreements, or FRAs, allow the purchasers and sellers to fix the interest rate on a certain
principal for a specified period in advance. They are similar to Eurocurrency futures contracts but can be
customized for any maturity. One party pays fixed, the other an agreed-upon floating rate. FRAs typically
have maturities out to two years and are usually priced off the swap yield curve.
The transaction is done on a nominal amount and only the difference between the contracted and actual
rates is paid. If rates have risen by the time of the FRA’s maturity, the purchaser receives the difference in
rates from the seller and vice versa.
FRAs are typically quoted as n x m. Where the forward rate’s term is m minus n months starting n months
out. For example, a 3 x 9 FRA (spoken ‚three by nine‛ or ‚threes-nines‛) is the six-month forward rate
starting three months hence.
ccy, credit_rating, principal, settlement_date, rate, rate_term, rate_basis
2. credit_rating Required. Text specifying the credit rating code of the instrument, which determines which
yield curve is used to discount cash flows. See Codes for a list of credit rating codes. See The Euro for Euro-
3. principal Required. Number specifying the notional principal in millions of local currency. If you are
paying a floating rate and receiving a fixed rate then specify positive principal. If you are paying a fixed rate
and receiving a floating rate then specify negative principal. See The Euro for Euro-related issues.
4. settlement_date Required. Date specifying the settlement date.
5. rate Required. Number specifying the strike rate, as a percent. Example: For a 5.5% rate, specify 5.5.
6. rate_term Required. Number specifying the term of rate in months. rate_term must be greater than or
equal to 0.25 (one week) and less than or equal to 12 (one year). Example: For a three-month rate, specify 3.
7. rate_basis Required. Text specifying the rate basis of rate. Rate is converted to a bond equivalent rate
prior to cash flow mapping. Specify one of the following:
VaRworks uses the method described in Hull (1997) to price FRAs.
Forward rate terms begin on settlement_date.
FEA.
USD,S,10,1/1/1997,7,12,BE
*TYPE=FRN
*DATEROLL= date_convention [optional]
*INTERPOLATION= interpolation [optional]
A floating-rate note (FRN) pays periodic interest and principal. The interest rate is reset each period to the
then-prevailing rate for the payment period. An interest-rate swap can be decomposed into an FRN (the
floating leg) and a coupon bond (the fixed leg).
ccy, credit_rating, principal, maturity_date, pmt_term, rate_basis, first_reset_rate, rate_term,

first_pmt_date, spread, rate_multiplier, cms_freq, cms_basis, arrears, rollday, is_quanto, quanto_ccy,
quanto_credit_rating, amort_schedule <A, date, amount,...>, vol_schedule <M1, date, vol,...>, vol2_schedule
<M2, date, vol,...>, corr_schedule <CORR, date, vol,...>
4. maturity_date Required. Date specifying the maturity date, i.e., the last payment date of the instrument.
9. first_pmt_date Optional. Date specifying the first payment date. This date can be for more than one period
forward for forward-starting instruments.
10. spread Optional. Number specifying a spread to be added to the underlying rate, in basis points.
Defaults to zero.
11. rate_multiplier Optional. Number specifying the multiple of the floating rate used to calculate payments.
The payment is calculated using (rate*rate_multiplier + spread). Defaults to 1.
12. cms_freq Optional. Number specifying the payment frequency (per year) of the CMS rate. Defaults to the
frequency corresponding to pmt_term, if omitted. Ignored if rate_term is less than one.
13. cms_basis Optional. Text specifying the quotation basis of the CMS rate. Ignored if rate_term is less
than one. Defaults to rate_basis, if omitted.

a swap curve.
E.g., A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
Used only for convexity/quanto adjustments. Each list element contains the following items:
2. Volatility date.
E.g., M1,1/1/1997,15.0,M1,1/1/1998,20
21. vol2_schedule Optional. List specifying the volatility of the exhange rate, as a percent, corresponding to
the specified term. Used only if is_quanto is set to true. Each list element contains the following items:
2. Volatility date.
E.g., M2,1/1/1997,15.0,M2,1/1/1998,20
22. corr_schedule Optional. List specifying the correlation between the foreign rate and the exchange rate,
between and including -1 and +1. Used only if is_quanto is set to true. Each list element contains the
following items:
E.g., CORR,1/1/1997,0.15,CORR,1/1/1998,0.20
Important If the instrument has a volatility schedule but no amortization schedule, do not insert an extra
field delimiter (comma or semicolon) where the amortization schedule would normally appear. Specify the
volatility schedule fund immediately following quanto_credit_rating.
Schedule dates must fall before maturity_date.
FEA.
FRN with amortization schedule

USD,S,100,1/1/2005,2,,A0,1/1/1997,5.8,,,,,,,,,,,A,1/1/1998,10,A,6/1/1999,10
*TYPE=HISTORICALDATA
*RETURNTYPE=return_type(optional)
*NEGATIVERATES=negative_rates_OK(optional)
return_type is either SIMPLE, CONTINUOUS, or IGNORE (default value if omitted), see return below.
negative_rates_OK is either TRUE or FALSE (default value if omitted), and signals whether an error should
be flagged if negative interest rates are provided in the data.
Historical data is made available to VaRworks through files containing time series of past prices, interest
rates, and exchange rates. To input multiple files, which is often a necessity, users specify a single
intermediate file containing the *TYPE=HISTORICALDATA header at its beginning. Each record of this
intermediate file specifies the relative or absolute path of a historical data file. The time series data of the
listed files is amassed into a single cache of historical returns. The use of HISTORICALDATA is similar to
that of PORTFOLIO.
historical_data_file_path
1. historical_data_file_path Required. Text specifying the path (optional) and file name of a historical data
file. If no path (that is, only a file name) is specified, only the current directory is searched. The following
three examples all refer to the same file:
c:\history\rates.txt,
\history\rates.txt if C is the current drive, and
rates.txt if c:\history\ is the current directory.
You must have read permission for the intermediate file and for each listed historical-data file, and each file
must be located on a network drive or server accessible to you.
While commodity prices support both a constant maturity price and fixed expiration price approach, a
meaningful Historical VaR result can only be obtained if the dataset refers to constant maturity prices, or if
the decay factor used when estimating Historical VaR is such that only very recent data is used in practice.
Otherwise, the use of time series of fixed expiration Futures prices will tend to understate the volatility of
contracts, as their their time to maturity increases when the observation date moves further in the past.
You can control the caching of your historical data files by selectively adding, deleting, or commenting-out
records of the intermediate file. Comments prefixed by ‘#’ are permitted within the intermediate file.
Only the TYPE header should be specified in the intermediate file; other headers are specified in the
individual files containing historical time series.
Individual files of historical data can contain data records, comments, and blank lines. Each record specifies
a single price, interest-rate, or exchange-rate observation and is formatted as:
asset,asset_class,maturity,date,ccy,price
An additional optional field (return) is allowed in the case of equity asset class, see below.
Taken together, the asset, asset_class, maturity, and date fields of a data record form a composite primary key
that identifies a unique daily time series of observations. This key is synonymous with a RiskMetrics market
vertex (or bucket). The records corresponding to a given time series (market vertex) must be sorted in
ascending order, according to date. If multiple time series, corresponding to a single market vertex, are
encountered during file loading, the last time series is cached.
The field descriptions are as follows:
asset is text specifying a VaRworks-recognized currency or commodity asset. See Assets for information on
the types of asset codes recognized by VaRworks. See The Euro for Euro-related issues. Examples: USD for
U.S. dollars, COB for California-Oregon border electricity.
asset_class is text specifying the asset class code of asset. See Codes for a list of asset classes, including credit
rating codes. See The Euro for Euro-related issues.
maturity is a number specifying the maturity of the asset expressed as a spot or forward time period.
maturity is a positive integer whose measurement units depend on the asset class. If maturity is not passed as
an integer then it is truncated. The following maturity values are allowed.
Asset_class Valid values of maturity

XS Always zero (spot).
R,S,Z,AGY, An integer value. See Codes for a description of how maturities are interpreted
AAA,AA,A,BB for these asset classes.
B,BB,B,
CCC,D
SE Always zero (spot).
C Integer number of months greater than or equal to zero, to indicate Constant
Asset_class Valid values of maturity

Maturity prices. A date formatted according to the DATEORDER header, to
indicate Fixed Expiration prices, see Fixed Expiration date Futures prices on
page 54, but also remark above on the the relevance for Historical VaR. Zero
indicates spot (cash) prices.
G Integer greater than or equal to zero indicating a user-defined Brady bond type
for the ccy. Note that in this case maturity does not indicate a time period,
Brady bonds are always spot observations.
date is a date specifying the date that price was observed. The format of date is interpreted from the
DATEORDER header, contained in each historical data file. Dates should be specified with four-digit years;
however, dates with two-digit years will be accepted, and a warning message will be logged.
ccy is text specifying the local currency code of the price of asset. The local currency is the currency that price
is measured in. Since the volatility and correlation data loaded by VaRworks is based in a single currency,
usually USD, ccy should reflect the appropriate base currency. The following ccy values are allowed:
asset_class Valid values of ccy

All but SE Must be the same as the VaRworks base currency, typically USD.
SE Should be the currency corresponding to the index represented. Example:
JPY for the Nikkei 225.
price is a number specifying the price, interest rate, or exchange rate of asset observed on date, expressed in
ccy. Only one price is allowed for each date. If price is missing for a particular date, a price-equivalent (i.e.,
price, discount factor, or exchange rate) linear interpolation will be made between adjacent prices. The price
field is a real number strictly greater than zero (to allow for negative interest rates set
NEGATIVERATES=TRUE) and expressed as follows:
asset_class Express price as

XS Units of ccy per one unit of asset (ccy/asset).
R,S,Z,AGY Annualized percent. For example, 5.7 for 5.7%.
AAA,AA,A,BB
B,BB,B,
CCC,D
SE Units of ccy. For example, 953.17 (USD) for the S&P 500 index.
C Units of ccy. For futures, we recommend you specify constant-maturity futures
(CMF) prices, but see remarks above. (MakeCMF is a MakeVC utility that
converts futures prices to constant maturity equivalents.)
G Percent of face value. For example, specify 95.7 for 95.7%.
Remember to express all interest rates as percentages, not decimals. For example, specify
5.7 for 5.7%.
In the case of Asset Class=SE (Spot Equity), the user can choose to specify the historical returns directly via a
a return field (see below), by specifying a value for the RETURNTYPE header.
return is an optional field specifying the return of asset observed on date. The field is used only if the asset is
an equity (i.e. asset_class=SE) and the value of the RETURNTYPE header is different from IGNORE. If
RETURNTYPE = SIMPLE the return provided is interpreted as the simple return of the equity
corresponding to date (typically if d1 represent date, and d0 the preceding date, the return is defined as 100
 ((p(d1)/p(d0) –1), with p denoting the price of the equity). If RETURNTYPE = CONTINUOUS, the return is
defined as 100  log(p(d1)/p(d0)), with log denoting the natural logarithm of the price ratio. Note that, if a
return field is used, prices can be omitted and if entered they will be ignored. If return is missing for a
particular date, a zero return is used. Using returns instead of prices has the advantage that corporate events
like dividend and splits can be incorporated naturally into returns, and historical series of adjusted prices
can then be generated from any date by using returns and the market price of the equity on that date.
Example File Paths

irates.txt
\history\oil_prices.txt
g:\trader_a\history\xrates.txt
Example Historical Data Records

Spot Japanese yen price:
JPY,XS,0,01/02/1997,USD,0.007900
Six-month EUR money market interest rate:

EUR,R,180,01/02/1997,EUR,3.21391
Two-year GBP swap interest rate:

GBP,S,2,01/02/1997,GBP,7.277467
30-year USD government interest rate:

USD,Z,30,01/02/1997,USD,7.260000
Spot US S&P 500 equity index:

USD,SE,0,01/02/1997,USD,841.88
Spot US S&P 500 equity index, using a return of 1.2%:

USD,SE,0,01/02/1997,USD,,1.2
Spot Mexican Aztec Brady bond price (assuming ‚3‛ represents an Aztec bond):
MXN,G,3,01/02/1997,USD,97.6658
Three-month West Text Intermediate (WTI) crude oil price:

WTI,C,3,01/02/1997,USD,21.31
Spot WTI oil price record:

WTI,C,0,01/02/1997,USD,20.68
Missing spot-WTI-oil-price records:

WTI,C,0,01/02/1997,USD,
–or–
WTI,C,0,01/02/1997,USD,*
–or–
WTI,C,0,01/02/1997,USD,0
–or–
<Omit the entire record>
Sample records correctly time-sorted:

WTI,C,0,01/02/1997,USD,21.55
WTI,C,0,01/03/1997,USD,22.75
WTI,C,0,01/06/1997,USD,23.00
WTI,C,0,01/07/1997,USD,22.44
*TYPE=MONEYMARKET
Here are brief descriptions of supported money market instruments. See Stigum (1981) and Stigum (1990)
Bankers’ acceptances
A bankers’ acceptance is a bill of exchange, that is, an order to pay a specified amount at a specified time,
drawn on individuals, business firms, or financial institutions. When the drawee formally acknowledges his
obligation to honor the draft, it becomes an ‚acceptance‛. Interest is calculated on a discount basis.
Maturities are generally six months or less.
Certificates of deposit
A certificate of deposit (CD) is an interest-bearing time deposit with a specific maturity evidenced by a
certificate. They are issued at face value and pay interest at maturity.
Commercial paper
Commercial paper is unsecured short-term promissory notes issued in bearer form by businesses, sold at a
discount from face value.
ccy, mm_type, credit_rating, principal, maturity_date, cd_rate, cd_rate_term
2. mm_type Required. Text specifying the type of instrument. Specify one of the following:
‘BA’ for Bankers’ Acceptance
‘CD’ for Certificate of Deposit
‘CP’ for Commercial Paper.
4. principal Required. Number specifying the principal amount in millions of local currency. Specify a
issues.
5. maturity_date Required. Date specifying the maturity date.
6. cd_rate Required for CDs only. Number specifying the rate, as a percent. Example: for 5.5%, specify 5.5.
7. cd_rate_term Required for CDs only. Number specifying the original term of the CD rate in months (not the
remaining term). Example: For a three-month CD rate, specify 3.
Specify foreign currency deposits as CDs.
credit_rating should reflect the quality of the institution on which a money market instrument is drawn.
If cd_rate_term is less than the time to maturity_date, a forward-starting CD is assumed.

Bankers’ acceptances (BA) and commercial paper (CP) are assumed to be issued on a discount basis, that is,
they do not pay interest; instead they are sold at a discount from face value and redeemed at maturity for
face value.
FEA.
Commercial paper
USD,CP,S,1,1/1/1997
Certificate of deposit
USD,CD,S,1,1/1/1997,10,12
Bankers’ acceptance
USD,BA,S,1,1/1/1997
*TYPE=OPTION or OPTION2
*MEANREVERSION=mean-reversion-rate [optional, only used by OPTION2]
*DELTAGAMMA= use delta-gamma approximation in simulation [optional, only supported by OPTION2]
(FALSE,TRUE)
An option provides the holder with the right, but not the obligation, to exchange fixed amounts of two global
commodities by a fixed future point in time. A global commodity is characterized by 1) a broad-based market
price representing its sole source of uncertainty, 2) payouts to the owner which are relatively smooth, and 3)
price fluctuations which exhibit a ‚random-walk‛ behavior. Examples of global commodities are major
currencies, metals, energy products, agricultural commodities, and broad-based stock indices. One of the
commodities is designated the underlying asset.
There are two basic types of options. A call option gives the holder the right to buy the underlying asset by a
certain date for a certain price. A put option gives the holder the right to sell an underlying asset by a certain
date for a certain price. The payoff at expiration for an option is max(S – K, 0) for calls and max(K – S, 0) for
puts where S is the underlying asset price at expiration and K is the strike price (strike).
The price in the contract is known as the strike price; the date in the contract is known as the expiration date
(or maturity). An American option can be exercised at any time up to the expiration date. A European option
can only be exercised on the expiration date itself. (Note that the terms American and European do not refer
to the location of the option or exchange.)
The payoff at expiration for an option is max(S – K, 0) for calls and max(K – S, 0) for puts where S is the
underlying asset price at expiration and K is the strike price (strike).
The OPTION type uses functions from GlobLib for the valuation. OPTION2 uses functions from ErgLib
(Eopt). The main difference of the two implementations is in the case of American style options, where
OPTION uses a binomial tree while OPTION2 uses a trinomial tree with control variate. Notice that
OPTION2 also supports a mean reverting model for the underlying price. The record layout for OPTION2 is
the same as the record layout for OPTION.
The SMILEMODEL header can be set to any of the implemented models for OPTION2, i.e. all moneyness
choices can be used when valuing OPTION2 with the volatility smile corrections. The SMILEMODEL
header can be set either to S or M0 for OPTION. See the SMILEMODEL header for the description of
different moneyness choices on page 96.
ccy, asset, amount, ex_type, pc_type, strike, opt_expiry, volatility, fut_expiry, carry_credit_rating
currency codes.
3. amount Required. Number specifying the amount of asset in millions of units. Specify a positive number if
you are long the contract or a negative number if you are short the contract. Examples: If the underlying of
amount is 100 million units of asset, specify 100. If a monthly on-peak power option calls for delivery of 100
MWh of power for 16 hours per day for 21 days then amount equals 0.0336 [= (100 * 16 * 21) / 1000000],
assuming that the prices in the volatility-correlation dataset are expressed per unit MWh. See Commodity
Futures for more information the relation of amount and price.
8. volatility Optional. Number specifying the volatility (annualized standard deviation or implied volatility)
of the price of the underlying equity or the implied volatility, as a percent . The actual volatility used in
valuing the option, however, depends on the risk model being used. In the case when the SMILEMODEL
header is specified and is not set to NONE, the volatility internally interpolated from the smile surface is
used in the valuation, and the volatility input is not used. If the smile surface for the underlying is not
specified, or the VOLMODEL is set to SV (Stochastic volatility) then the volatility input from the trade record
is used. If volatility is omitted, the volatility specified in the volatility header will be used, unless a stochastic
volatility model is being used in which case the implied volatility corresponding to the underlying is
extracted from the dataset and used. Finally, if no volatility input is specified in either trade record, header,
smile file, or implied vol dataset, the volatility is extracted from the dataset.
10. carry_credit_rating Optiona l.Text specifying the custom credit rating identifying the rate curve used as
carry rate. See Codes for a list of the credit rating codes. Specify this input if you want to decompose the risk
of an option on a commodity underlying in terms of spot price risk and carry_rate risk, instead of price risk
associated to different points in the futures price curve. See the remarks under Commodity Futures for our
definition of carry rate. carry_credit_rating is only supported for options on commodity futures.
American options are priced using the Cox-Ross-Rubinstein binomial option pricing model (Cox, Ross, and
Rubinstein (1979)). European options are priced using the Garman-Kohlhagen option pricing model
(Garman and Kohlhagen (1983)).
When mapping currency options, the asset and strike (settlement currency) cash flows are determined from
their respective deltas, then mapped in the following way:
1. An Option on the Spot FX

(a) European exercise:
- asset and settlement cash flows are mapped to option maturity.
(b) American exercise:
- asset and settlement cash flows are mapped to the spot.
2. An Option on the Forward FX

(a) European exercise:
- settlement cash flow is mapped to the option maturity.
- asset cash flow is mapped to forward date.
(b) American exercise:
- settlement cash flow is mapped to the spot.
- asset cash flow is mapped to forward date.
If the implied volatility risk is included via the VOLMODEL header, then there are additional cash flows
which are the vega sensitivities of the option, see Volatility as a Risk Factor section on page 54 for more
details.
If PV is the present value of the option, the present-valued amounts of the two cash flows, in the ccy
currency terms, are
CFsettlement = (PV / strike)  strike

CFasset_price = (PV / asset_price)  asset_price
Input data should be expressed in the currency ccy. So strike must be ccy (for example, AUD) units of
currency per underlying asset (for example, USD). If currency exchange rate, xrate_ccy, is quoted ccy/USD—
‚how many U.S. dollars buys one unit of ccy?‛—and the asset exchange rate, xrate_asset, is quoted
asset/USD—‚how many U.S. dollars buys one unit of asset?‛—then asset_price (‚the spot‛) is
(a) when the asset cashflow is mapped to spot

asset_price = xrate_asset / xrate_ccy
(b) when the asset cashflow is mapped to the forward date

asset_price = xrate_asset / xrate_ccy 
exp((rate_ccy – rate_asset)  fut_expiry)
So, we must find the derivatives of PV = PV(asset_price, strike)—telling us the cash flows.
VaRworks and VaRlib use the cross-commodity forms of the FEA @GLOBAL option models because one
can readily obtain counter (strike) deltas when the option is viewed in this way. (For single-commodity
option models the strike delta could be derived from the value of the option and the asset delta)
For example, consider the option trade:
*TYPE=OPTION
AUD,USD,1.0,E,C,1.20,12/15/2005,15.0,12/15/2005
that describe an option, settled in Australian dollars, to purchase forward US dollars, at a prespecified
strike price.
The relevant parameters to derive the unallocated cash flows can be obtained from the trade records and
from the volatility file (as an example we are using the 20050323.dvf file provided with the distribution). The
appropriate interest rates quoted below can be obtained by using the GENRATES utility, and linearly
interpolating the rates for the appropriate tenors:
Volatility file: 20050323.dvf

Correlation file: 20050323.dcf
VaR horizon: 1
Confidence: 0.95
Home currency: USD
Effective date: 3/23/2005
VaRlib returns the (unallocated) cash flows:

Asset Credit Tenor Amount
USD SWAP 0.731507 0.776824
AUD SWAP 0.731507 -0.685489
Note that these number are somewhat artificial. They represent the future values in the respective currencies
multiplied by the spot exchange rate corresponding to the home currency. This means that to get their
proper present values in the home currency one must use the discount curve of the respective currency.
VaRworks and VaRlib return the duration-preserving cash flows allocated to vertices:
Asset Credit Tenor Amount
AUD SPOTFX 0 0.00827843
AUD LIBOR 0.5 5.5489e-005
AUD LIBOR 1 0.000110436
USD LIBOR 0.5 5.28605e-005
USD LIBOR 1 0.000149635
(Diversified VaR = 0.0082569477)
Replicating the answer with the FEA @GLOBAL EUROX function, the Microsoft Excel formula for a
European option on forward FX is:
=EUROX({‚bv‛;‚sv‛}, asset_price, 1, num_contracts, strike*num_contracts, maturity, volatility, rate_ccy, rate_ccy)
where
USD/AUD exchange rate (from 20050323.dvf) = 0.7754.
maturity = (12/15/2005 – 3/23/2005)/365 = 267/365 = 0.731507
rate_ccy = AUD_rate = 0.059294521 (linearly interpolated)
rate_asset = USD_rate = 0.035491626
asset_price = 1/0.7754 * exp(maturity×(AUD_rate– USD_rate)) = 1.31230907
num_contracts = 1
strike = 1.20
volatility = 0.15
The returned array is

bv = 0.976161783 (buy-side value delta)
sv = -0.846520862 (sell-side value delta)
Converting from AUD to the home currency USD, and further taking the future value in the respective
currencies
bv  0.7754  exp(0.731506849*0.035491626)= 0.776824493
sv  0.7754  exp(0.731506849*0.059294521)= -0.685489334
These match the unallocated VaRlib cash flows from above.
available from FEA.
USD European call option on 10,000 MMBtu spot gas with 40% volatility
USD,GAS,0.01,E,C,2.00,1/1/1998,40.0
USD European call option on 10,000 MMBtu gas futures contract with 25% volatility
USD,GAS,0.01,E,C,2.00,1/1/1998,25.0,1/15/1998
GBP American put option on spot EUR using the volatility specified in the VOLATILITY header
GBP,EUR,10,A,P,0.3000,1/1/1998
*TYPE=OIS
Overnight Index Swaps (including EONIA index swaps) are swap agreements where one side pays a term
money-market rate and the other side pays a compounded overnight index.
ccy, credit_rating, principal, maturity_date, swap_term, term_rate, term_rate_basis, overnight_rate_basis,

first_payment_date, running_accrual, overnight_reset_schedule <R, date, reset,<>
1. ccy Required. Text specifying a currency code. This is the settlement currency of the swap. See Assets for
information on currency codes. See The Euro for Euro-related issues. Examples: USD, EUR, JPY.
2. credit_rating Required. Text specifying the credit rating of the swap, which determines which yield curve
is used to discount cash flows and calculate forward floating rates. See Codes for a list of the credit rating
codes. See The Euro for Euro-related issues. Example: For the swap/LIBOR curve, specify ‘S’.
3. principal Required. Number specifying the notional principal in millions of ccy. Specify a positive number
to pay the term rate or a negative number to receive the term rate. See Remarks below for more information.
See The Euro for Euro-related issues. Example: For a swap principal of 10 million ccy, paying the
compounded overnight rate, specify -10.
4. maturity_date Required. Date specifying the final payment date of the swap.
5. swap_term Required. Text specifying the term of the swap. This can be a number of working days, a
number of weeks, or a number of months, followed by a term indicator: 5d = 5 working days, 2w = 2 weeks,
3m = 3 months.
6. term_rate Optional. Number specifying the annualized term rate paid on one leg of the swap. This
number is required if the swap is in the middle of an accrual period, since the rate reset is in the past. This
number is optional if the effective date is a reset date: the user can provide the rate or allow VaRworks to
calculate the rate from the yield curve. This number is ignored if the first reset date is in the future, i.e., if
first_payment_date is more than one swap_term in the future.
7. term_rate_basis Optional. Text specifying the basis of the term_rate.

8. overnight_rate_basis Optional. Text specifying the basis of the overnight resets provided in
overnight_resets.

9. first_payment_date Optional. Date specifying when the first payment on the swap occurs.
10. running_accrual Optional. Number specifying the overnight rate accruals observed so far as a percent. If
you do not want to calculate the running accrual, use overnight_reset_schedule instead to provide the history
of resets observed so far. running_accrual should include the accrual for the overnight rate observed today.
This number is calculated this way:
100**(1+r1*t1)*(1+r2*t2)*<*(1+rn*tn) – 1],
where r1, r2, <, rn are the overnight rates observed so far (expressed as fractions, e.g., 0.05 for 5%), and t1,
t2, <, tn are the daycount fractions for each of the rates, e.g., if overnight_rate_basis is A0, then t1 = d1/360,
where d1 is the number of days r1 accrues over (d1 is 1 for a rate that accrues over one day; d1 is 3 for a rate
observed on a Friday that accrues to the following Monday).
11. overnight_reset_schedule Optional. List specifying the history of resets of the overnight rate observed so
far. If you do not want to provide the history of resets, you can calculate the accrued amount manually and
provide it in running_accrual. The overnight_reset_schedule can include or omit the reset observation for the
effective date. Each overnight_reset_schedule element contains the following items.
1. Indicator for type of schedule ‚R‛.
2. Reset date.
3. Rate (as a percent).
Example: R,7/1/2004,1.02,R,7/2/2004,1.02,R,7/4/2004,1.01,R,7/5/2004,1.02.
Here we describe the mapping of the cashflows for OIS.
Consider first the case where the running accrual is specified. The present value of the instrument is given
by
 (1  R * b) * exp(r * T )  (1  a) * exp(r2 * T2 ) * exp( r1 * T1 ) * exp(r2 * T2 ),
where R is the fixed term rate of the swap, b is the day count basis (the ratio of the number of days between
payment periods divided by the number of days in the year according to the specified day count
convention), T is the maturity of the swap, T1 is one day, T2 is defined by T1+T2=T, a is the running accrual,
r, r1, and r2 are the spot interest rates corresponding to the time periods T, T1, and T2, respectively.
Shredded cashflows are computed as sensitivities to the discount factors at time T and T1 and are given by
time=T1 : 1+a,
time=T : -(1+R*b),
If the reset is taken from the market, the present value of the instrument is given by
 (1  R * b) * exp(r * T )  (1  a) * exp(r * T ) * exp(r * T ),
where a is the observed reset rate. In this case shredded cashflows are taken to be
time=0 : 1+a,
time=T: -(1+R*b),
These cashflows are allocated to the interest rate vértices specified in the loaded dataset, following the usual
VaRworks rules.
For a technical discussion of pricing interest-rate securities, see the @INTEREST User’s Guide, available
from FEA.
Forward OIS
USD,S,100,10/15/2004,3m,,,,10/15/2004
OIS with reset schedule

EUR,S,10,9/15/2004,3m,1.30,,,,,R,6/15/2004,1.00,R,6/16/2004,0.99,R,6/17/2004,1.0
1,R,6/18/2004,1.01,R,6/21/2004,1.00,R,6/22/2004,1.02
*TYPE=PORTFOLIO
Each record specifies the relative or absolute path of a trade file. Calculations are performed for every trade
file listed in the portfolio file.
trade_file_path
1. trade_file_path Required. Text specifying the path (optional) and file name of a trade file. If no path (that
is, only a file name) is specified, only the current directory is searched. The following three examples all
refer to the same file:
c:\trades\bond.txt ,
\trades\bond.txt if C is the current drive, and
bond.txt if c:\trades\ is the current directory.
You must have read permission for each trade file and each trade file must be located on a network drive or
server accessible to you.
You can perform analyses on different subsets of your portfolio’s trades by adding, deleting, or
commenting-out portfolio file records.
Only the TYPE header should be specified in a portfolio file; other headers are specified in individual trade
files.
swap.txt
\trades\bond.txt
g:\trader_a\trades\bondfut.txt
*TYPE=RANGEACCRUAL
*MODEL=interest-rate-model, or BLACKY-CS
*CORRELATION=correlation [optional]
A range accrual is a contract that makes periodic floating interest payments. The amount of interest is
determined by observing a reference rate between payments and accruing interest if the reference rate meets
a condition, such as being in a range between 3% and 6% or being less than 7%. How each accrual is
weighted and how the payment is determined from the weight accruals are specified as part of the contract.
ccy, credit_rating, principal, maturity_date, pmt_freq, rate_mty, rate_mty2, first_pmt_date, fix_freq,

fix_type, accrual_type, pmt_type, rate_basis, rate_basis2, is_note, ex_type, opt_type, cms_freq, cms_freq2,
cms_basis, cms_basis2, rollday, amort_schedule <A, date, amount,...>, coupon_schedule <C, date,
first_boundary_rate,...>, coupon_schedule2 <E, date, second_boundary_rate,<>, strike_schedule <K, date,
strike_rate,<>, fixed_amount_schedule <D, date, fixed_amount,<>, vol_schedule <M1, date, vol,...>,
fixings_schedule <FIX, date, vol,<>
5. pmt_freq Required. Number specifying the payment frequency—the number of times per year the
instrument makes a payment. Typically 1, 2, 4, or 12.
6. rate_mty Optional. Number specify the maturity of the floating interest-rate in years. E.g., 0.5 means the
fixing rate is a six-month (0.5-year) rate; 3 means the fixing rate is the 3-year CMS rate. Defaults to 1/pmt_freq
if omitted.
7. rate_mty2 Optional. Number specify the maturity in years of the second rate for a spread range accrual.
E.g., 0.5 means the rate is a six-month (0.5-year) rate; 3 means the rate is the 3-year CMS rate. If the number
is omitted, the instrument is a regular, rather than spread, range accrual.
8. first_pmt_date Optional. Date specifying when the first (potential) payment occurs. The first fixing is thus
one period earlier.
9. fix_freq Optional. Number specifying the fixing frequency—the number of times per year the instrument
fixes (observes) a floating rate. The frequency may be 1, 2, 4, 6, 12, 52, or 365. You can omit fix_freq and using
fixings_schedule instead.
10. fix_type Required. Text specifying whether interest accrues on non-business days.
‚business‛ Interest accrues on business days only.
‚calendar‛ Interest accrues on all days.
11. accrual_type Required. Text specifying how interest accrual is determined using the strike(s).
‚call‛ Interest accrues if the fixing is above the strike.
‚put‛ Interest accrues if the fixing is below the strike.
‚range‛ Interest accrues if the fixing is between strike and strike2.
‚reverse‛ Interest accrues if the fixing is not between strike and strike2.
Note that interest does not accrue for types call, put, and range if the fixing is exactly on a strike. That is, if F
is the fixing and S, S1, and S2 are strikes, interest accrues in these cases:
call: F>S
put: F<S
range: F>S1 and F<S2
reverse: F<=S1 or F>=S2
The choice of > vs. >= does not affect the valuation for future fixings, but it does affect the valuation when
past fixings are included in fixings_schedule. If you want to include fixings that are exactly on a strike, set the
strike slightly lower or higher. E.g., to include fixings on the strike for a call, enter the strike level minus 10 -8.
12. pmt_type Required. Text specifying how interest accrues if the fixing qualifies as an accrual according to
accrual_type. Payments are determined by calculating the ratio of accrual days to total days in the period.
Accrual days and total days are counted according to fix_type. The payment calculations are specified below,
where the daycount fraction for the period is determined by basis.
‚cash‛ The payment is the ratio times the daycount fraction.

‚fixedrate‛ The payment is a fixed rate (specified by fixed_amount_schedule) times
the ratio times the daycount fraction.
‚floatingarrears‛ The payment is the final fixing rate (plus a possible spread specified by
fixed_amount_schedule) times the ratio times the daycount fraction.
‚floatingadvance‛The payment is the initial fixing rate (plus a possible spread specified
by fixed_amount_schedule) times the ratio times the daycount fraction.
‚floating‛ The payment is the sum of the rates observed on accrual days (plus a
possible spread specified by fixed_amount_schedule) divided by the total
number of days times the daycount fraction.

14. rate_basis2 Optional. Text specifying the rate basis of the second rate for a spread range accrual.
15. is_note Optional. Boolean specifying whether the instrument is in note form. When it is a note, the
notional is usually paid out at maturity. Callable instruments are usually in note form with option strikes at
par.
16. ex_type. Optional. Text specifying the exercise style of the embedded option for callable/puttable
instruments. Enter ‘B’ for Bermudan, ‘E’ for European style. If omitted it is assumed the instrument has no
embedded option.
17. opt_type. Optional. Text specifying the type of the embedded option for callable/puttable instruments.
Enter ‘C’ for callable, ‘P’ for puttable. If omitted it is assumed the instrument has no embedded option.
18. cms_freq Optional. Number specifying the payment frequency of the CMS rate paid on the floating leg.
Defaults to pmt_freq, if omitted. Ignored if rate_term is less than one.
19. cms_freq2 Optional. Number specifying the payment frequency of the second CMS rate in a spread
range accrual. Defaults to pmt_freq, if omitted. Ignored if rate_term is less than one.
21. cms_bas2 Optional. Text specifying the quotation basis of the second CMS rate in a spread range accrual.
E.g., A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
24. coupon_schedule Required. List specifying the call or put strikes or the first edge of the range. Each list
1. Schedule indicator ‘C’.
2. New strike effective date.
E.g., C,1/1/1997,5.0,C,1/1/1998,5.5
25. coupon_schedule2 Optional. List specifying the second edge of the range. Only used by accrual_type
‚range‛ and ‚reverse.‛ Each list element contains the following items:
1. Schedule indicator ‘E’.
2. New strike effective date.
E.g., E,1/1/1997,5.0,E,1/1/1998,5.5
26. strike_schedule Optional. List specifying the strike schedule of the instrument. Only used by callable
range accrual instruments. The presence of this curve indicates that the instrument is callable or putable.
E.g., K,1/1/1997,1.01,K,1/1/1998,1.0
27. fixed_amount_schedule Optional. List specifying the fixed rates or spreads used to calculate payoffs. See
payment_type for how this schedule is used. Each list element contains the following elements:
1. Schedule indicator ‘D’.
2. New fixed amount effective date—must fall on a payment date.
3. New fixed amount as a percent.
E.g., D,1/1/1997,0.30,D,1/1/1998,0.35
1. Volatility indicator, ‘M’ for market (Black implied) volatilities.
2. Volatility date.
If you provide both a vol_schedule and a VOLATILITY header value, and the model is BLACKY, or
BLACKY-CS vol_schedule prevails. If you specify a volatility smile through the LOADMARKETDATA
function volatilities in the smile file prevail, but vol_schedule data is still used, if specified, to compute
convexity adjustments when they are required by the term of the instrument. Vol_schedule and smile data
are only used if the interest rate model specified in the header is BLACKY, or BLACKY-CS.
E.g., M,1/1/1997,15.0,M,1/1/1998,20
29. fixings_schedule Optional. List specifying the fixing dates for the floating rates, any fixing values set in
the past, and optional weights of the fixings. Each list element contains the following items:
1. Fixings schedule indicator, ‘FIX’.
2. Fixing date.
3. Optional. Fixing value for fixings in the past expressed as a percent, e.g., for 5.5%, enter 5.5.
4. Optional. Weight of fixing in the average. Only used if weight_type is ‚relative‛ or ‚absolute.‛
E.g., FIX,6/1/2005,5.5,1
schedule fund immediately following rollday.
FEA.
Average cap with amortization and fixings schedules for past fixings
C,USD,S,100,1/1/2010,5.5,2,,52,calendar,A0,,,,,A,1/1/2003,10,A,1/1/2004,30,FIX,6
/8/2005,3.23,,FIX,6/15/2005,3.20,FIX,6/22/2005,3.27,
*TYPE=REPO
Bond repos and forward-start bond repos are supported. Repurchase agreements, or repos, are agreements
between two parties: a holder of securities sells these securities to an investor with an agreement to
repurchase them at a fixed price on a fixed date. The security ‚buyer‛ in effect lends the ‚seller‛ money for
the period of the agreement; the terms of the agreement are structured to compensate the lender.
end_date, buyback_price, start_date, sell_price, repo_rate, rate_basis, coupon_flag, ccy, credit_rating,

principal, maturity_date, cpn_rate, cpn_freq, issue_date, issue_price, first_cpn_date, last_cpn_date,
call_schedule <C, date, price,...>, sinking_fund <S, date, prin_reduction,...>
1. end_date Required. Date specifying the subsequent sale (or purchase) date of the bond.
2. buyback_price Required if start_date, sell_price, repo_rate, and rate_basis are omitted. Number specifying the
buy-back price (including bond accrued interest) of the bond occurring on end_date as a percent of face
value.
3. start_date Required if buyback_price is not specified, ignored otherwise. Date specifying the initial purchase
(or sale) date of the bond.
4. sell_price Required if buyback_price is not specified, ignored otherwise. Number specifying the selling price
(including bond accrued interest) of the bond occurring on start_date as a percent of face value.
5. repo_rate Required if buyback_price is not specified, ignored otherwise. Number specifying the annualized
term rate on the loan, as a percent. Example: for 5%, specify 5.
6. rate_basis Required if buyback_price is not specified, ignored otherwise. Text specifying the rate basis of
repo_rate. This rate is converted to a bond equivalent rate prior to cash flow mapping. Specify one of the
following:
7. coupon_flag Required. Text specifying how coupons, if any, occurring between start_date and end_date,
inclusive, should be handled. Specify one of the following:
‘K’ if the borrower of the bond keeps the coupons (coupons are mapped for a bond purchaser).
‘P’ if the borrower of the bond pays the coupons to the ultimate owner of the bond (coupons are mapped
for a bond seller).
10. principal Required. Number specifying the bond’s face value in millions of local currency. Specify a
positive number if you are loaning the bond, i.e., selling the bond for later repurchase. Specify a negative
number for a reverse repo: if you are borrowing the bond, i.e., purchasing the bond for later resale. See The
Euro for Euro-related issues. Example: For a principal of 1,000,000 specify 1.
12. cpn_rate Required for coupon bonds. Number specifying the coupon rate of the bond as a percent.
Example: For a 5.5% coupon rate, specify 5.5.
13. cpn_freq Required for coupon bonds. Number specifying the coupon frequency of the bond—the number
of times per year a coupon is paid, typically 1, 2, 4, or 12.
the bond.
of the bond as a percent of principal. Example: For 97%, specify 97.
16. first_cpn_date Required for odd-first coupon bonds. Date specifying the first coupon date of the bond—the
ending date of the first coupon’s interest period. Interest accrues from issue date until this date for the first
coupon only. Requires issue_date also.
17. last_cpn_date Required for odd-last coupon bonds. Date specifying the last coupon date of the bond—the
starting date of final coupon’s interest period. Interest accrues from this date until maturity for the last
coupon only.

Example: C,1/1/2015,104,C,1/1/2017,102,C,1/1/2019,101
following items:
Fields 8–19 are identical to the fields for a bond record—they describe the repurchased bond.
There are two ways to specify a repo: specify end_date (always required) and either buyback_price or
start_date, sell_price, repo_rate, and rate_basis. If you specify all of these fields then only buyback_price is used.
If you omit all of these fields then an error occurs. If you omit buyback_price and any of the other four fields,
an error occurs. The fields are related by the following formula
buyback_price = sell_price * (1 + repo_rate / 100 * (start_date – end_date))
where start_date – end_date is expressed in years.
If coupons stay with the current bond holder (coupon_flag = ‘K’), all payments will include accrued interest.
If coupons go to the ultimate bond holder (coupon_flag = ‘P’), none of the payments will include accrued
interest.
start_date < end_date < maturity_date (strictly).
FEA.
Repo using start_date, sell_price, repo_rate, and rate_basis

1/2/1997,,1/1/1997,100,5,BE,K,USD,Z,1,1/1/2020,8,2
Repo using buyback_price

1/2/1997,101,,,,,K,USD,Z,1,1/1/2020,8,2
*TYPE=SENSITIVITY or SENSITIVITYPAIR
*SNEXPIRY = num_days (Optional)
The goal of these instruments is to allow for VaR analysis of complex non-linear instruments, where the
sensitivities to risk factors up to second order are known, and hence VaR for short horizons can be
effectively computed without a full revaluation of the instrument. The SENSITIVITY instrument covers first
order sensitivities and diagonal gamma sensitivities, SENSITIVITYPAIR covers cross gamma sensitivities.
In order to keep the format simple each trade contains only one type of sensitivity, hence an instrument like
OPTION will be represented by at most five trade records (all of type SENSITIVITY). Those trade records
correspond to delta, gamma, theta, rho, and vega sensitivities. An instrument like SPREADOPT will have at
most 10 trade records, 8 of type SENSITIVITY and 2 of type SENSITIVITYPAIR. See the examples below.
ccy, asset, amt, mtm, risk_type, spot, beta, strike, sens_schedule <S_TYPE, date, amount,...>
ccy, asset, asset2, amt, mtm, risk_type, risk_type2, spot, spot2, beta, beta2, sens_schedule <S_TYPE, date,
amount,...>
1. ccy Required. Text specifying the currency of the trade for which sensitivities are provided. See Assets for
information on currency codes.
2. asset Required. Text specifying a currency, commodity, or equity name. See Assets for information on
currency/commodity codes. If the sensitivity type (S_TYPE) is ‘R’, ‘RG’, or ‘RXG’, see below, the field
should represent a valid credit rating, see Codes for a list of the credit rating codes.
2b. asset2 (SENSITIVITYPAIR only) Text specifying a currency, commodity, or equity name. See Assets for
information on currency/commodity codes. If the sensitivity type (S_TYPE) is ‘RXG’, see below, the field
should represent a valid credit rating, see Codes for a list of the credit rating codes. The field is used for
cross gamma sensitivities. If S_TYPE is ‘XG’ or ‘RXG’ asset and asset2 should be different. If S_TYPE is
‘XG2’ asset and asset2 should be equal.
3. amt Optional. Number specifying the units of underlying on which the instrument depends. amt is used
depending on the selected sensitivity type, see the table in the Remarks section below for details.
4. mtm Optional. Number specifying the mark-to-market value of the instrument for which sensitivities are
provided. This input is useful to get the mark to market of the overall portfolio correct. Notice however that
if the instrument is represented by many sensitivity trades, the whole MtM should be input in one
sensitivity entry and all others should have MtM set to 0.
5. risk_type Optional, required if the asset is an equity. Text specifying the equity risk model associated with
asset to be used when performing value at risk calculations. Specify one of the following:
5b. risk_type2 (SENSITIVITYPAIR only) Optional, required if asset2 is an equity. Text specifying the equity
risk model associated with asset2 to be used when performing value at risk calculations. Specify one of the
following:
6. spot Optional, only used if the asset is an equity. Number specifying the spot price of one share of the
underlying equity (asset) in ccy terms. If the spot price of the equity is not specified in the trade record, it
must be contained in the appropriately defined asset file or volatility file.
6b. spot2 (SENSITIVITYPAIR only) Optional, only used if asset2 is an equity. Number specifying the spot
price of one share of the underlying equity (asset2) in ccy terms. If the spot price of the equity is not specified
in the trade record, it must be contained in the appropriately defined asset file or volatility file.
7. beta Optional, only used if the asset is an equity and risk_type=’B’. Number specifying the beta of the
underlying equity (asset) with respect to the market index. The market value of the equity at any time is
related to a stochastic market index I (normalized to one) using
7b. beta2 (SENSITIVITYPAIR only) Optional, only used if the asset2 is an equity and risk_type=’B’. Number
specifying the beta of the underlying equity (asset2) with respect to the market index. The market value of
the equity at any time is related to a stochastic market index I (normalized to one) using
8. strike (SENSITIVITY only) Optional, only used if vega sensitivities are used. Number specifying the strike
price used to determine the moneyness of the volatility factors used in the sensitivity decomposition, see Eq.
(S.2) below. If omitted, the strike price is set to the spot price of one unit of the underlying.
9.sens_schedule Required. List specifying the sensitivity schedule of the instrument. A sensitivity schedule
begins with a sensitivity indicator (S_TYPE, see the table below) followed by a list of maturities and values.
1. Sensitivity maturity, expressed as a date or a tenor (in years from the effective date of the calculation).
The first maturity entry can be omitted, in which case it is assumed to be zero.
2. Sensitivity value.
In the special case when S_TYPE= ‘XG2’ or ‘XG2RCU’, each list element contains three items:
1. Sensitivity maturity1, expressed as a date or a tenor (in years from the effective date of the calculation).
2. Sensitivity maturity2, expressed as a date or a tenor (in years from the effective date of the calculation).
3. Sensitivity value.
To understand how sensitivities are used in the analysis consider first a generic instrument depending on a
set of factors, grouped into ‚underlying‛ factors {Ui}, discount factors {Di}, and volatility factors {Vi}. The
index i might represent different time buckets or, in the case of volatilities, time buckets and strikes. In the
case of instruments on FX or equity underlyings, the underling risk factor is the spot equity/exchange rate,
and hence does not have a time label. Notice that Ui, Di, and Vi do not need to coincide exactly with the risk
factors used in the datasets. For instance, an instrument might be sensitive to the price of the underlying at
time , while  might not be equal to one of the selected vertex maturities. In this case linear interpolation is
used to compute the values of Ui, Di, and Vi needed in Eq. (S.2) below.
We assume that the instrument is based on X units of underlying, and write the value of the instrument as
I(U,D,V,T), where T is the time to expiration. When computing VaR via MC simulation the required
instrument value at horizon can be written as
I(U’,D’,V’,T h)= I  I(U,D,V,T), (S.1)
where U’, D’, and V’ represent the new values of the risk factors at horizon, and h is time to horizon. By
using a Taylor expansion to first order in V and T and to second order in U and D, around the values U, D,
V, and T we have
I   hI/T + iI/Ui Ui+ iI/Di Di+ iI/Vi Vi +1/2 i,j2I/Ui Uj UiUj+
1/2 i,j2I/Di Dj DiDj. (S.2)
Note that for non-fixed income instruments it is sufficient to consider first order sensitivities to D and V,
and up to second order sensitivities in U, since these instruments are typically more sensitive to the price of
their natural underlying, than to discount factors and volatilities . To confirm this, we have found that for
non-fixed income instruments in many cases neglecting D and V sensitivities altogether does not greatly
affect the accuracy of the VaR estimates. On the other hand, we found that for fixed income instruments
including second order sensitivities to discount factors can improve the accuracy of the VaR estimates. The
sensitivity instruments revalue the instrument at horizon time by using Eqs. (S.1) and (S.2).
If the instruments depends on more than one underlying curve, for example, a commodity spread or a crack
option, or two interest rate curves, Eq. (S.2) can be replaced by
I   hI/T + i,kI/UikUik+  i,k I/Dik Dik+  i,k I/Vik Vik +

1/2 i,j,k,l 2I/Uik Ujl UikUjl +1/2 i,j,k,l 2I/Dik Djl DikDjl, (S.3)
where the indices k and l label different underlyings, and for discount sensitivities they label the discount
curve and the underlying rate curve.
The Monte Carlo delta-gamma approximation, currently supported for a limited set of instruments, see page
91, also uses Eqs. (S.1), (S.2), and (S.3), but it neglects vega and interest rates sensitivities.
The following table provides a correspondence between sensitivity types and the terms in Eq. (S.2-S.3).
Notice that all sensitivity values corresponding to different time buckets i, are entered as part of the same
schedule. Sensitivity schedules corresponding to different underlyings k should be entered as distinct trade
records. An example of this for a spread option is shown below. It is assumed that the instrument is based
on X units of underlying, and the amt field in the sensitivity trade record is set equal to X.
S_TYPE Sensitivity value Sensitivity time Amt used

‘T’  365 I/T 0 NO
‘TRCU’  I/T / X 0 YES
‘H’ I/Uik Maturity of the NO
factor Uik.
‘HU’ I/Uik / X Maturity of the YES
factor Uik
‘G’ 0.01 j 2I/Uik Ujk Maturity of the NO
factor Uik
‘GRCU’ j 2I/Uik Ujk / X Maturity of the YES
factor Uik
S_TYPE Sensitivity value Sensitivity time Amt used

‘RDF’ I/Di Maturity of the NO
discount factor Di
‘RDFU’ I/Di / X Maturity of the YES
discount factor Di
‘RDFG’ j 2I/Di Dj Maturity of the NO
factor Di
‘RDFGU’ j 2I/Di Dj / X Maturity of the YES
factor Di
‘R’ .0001 I/ri Maturity of the NO
zero rate ri
‘RU’ I/ri / X Maturity of the YES
zero rate ri
‘RG’ j 2I/ri rj Maturity of the NO
zero rate ri
‘RGU’ j 2I/ri rj / X Maturity of the YES
zero rate ri
‘V’ 0.01 I/Vik Maturity of the NO
volatility factor Vik
‘VRCU’ I/Vik / X Maturity of the YES
volatility factor Vik
‘XG’ 0.01 j 2I/Uik Ujl Maturity of the NO
factor Uik
‘XGRCU’ j 2I/Uik Ujl/ X Maturity of the YES
factor Uik
‘XG2’ 0.01 2I/Uik Ujk Maturity pair NO
corresponding to i,
j pair
‘XG2RCU’ 2I/Uik Ujk/ X Maturity pair YES
corresponding to i,j
pair
‘RDFXG’ j 2I/Dik Djl Maturity of the NO
factor Di
‘RDFXGU’ j 2I/Dik Djl/ X Maturity of the YES
factor Di
‘RXG’ j 2I/rik rjl Maturity of the NO
factor ri
‘RXGU’ j 2I/rik rjl/ X Maturity of the YES
factor ri
When ‘R’, ‘RG’, or ‘RXG’ sensitivities are used as input, the corresponding sensitivities with respect to Di are
internally computed so that Eq. (S.1)-(S.3) can be used. The transformation uses the expression relating
discount factors and zero rates, Di = exp( Tri), so that, for example,
I/Di = I/ri ri/Di = I/ri / ( TDi).
FEA @ENERGY 5.4, Basics and Advanced modules, supports the generation of sensitivity trade files in the
format specified above, including theta, vega, delta, gamma, cross-gamma and first order discount factor
sensitivities.
FEA @INTEREST 5.4 supports the generation of sensitivity trade files for fixed income instruments in the
format specified above, including theta, vega, and first and second order interest rate sensitivities.
In the MC simulation it is generally assumed that the price of each factor at horizon should be used. If the
sensitivity trade is derived from an instrument that expires in D days, and the VaR horizon H is greater
than D, simulated factor prices for D days can be used by setting the value of the SNEXPIRY header to D.
Simulation based valuation use the above formulas Eq. (S.1), (S.2-S.3). Analytic VaR, however, is obtained
by neglecting the non-linear, gamma, terms and theta sensitivities.
Note that when using an ‘XG’ or ‘XGRCU’ sensitivity type, the term i,j2I/Uik Ujl UikUjl in Eq. (S.2) is
approximated by i (j 2I/Uik Ujl ) Uik<Ul >, where <Ul > =1/N jUjl with N equal to the number
of sensitivity values. Analogously, when using ‘RDFXG’ sensitivity type, the term i,j2I/Dik Djl DikDjl
in Eq. (S.2) is approximated by i (j 2I/Dik Djl ) Dik<Dl >, where <Dl > =1/N jDjl with N equal to
the number of sensitivity values.
Let’s first consider the case where we choose to represent an option instrument through a SENSITIVITY
trade, and let’s assume the option record, corresponding to a European call on 10,000 MMBTU’s of spot GAS
with 40% volatility, is given by USD,GAS,0.01,E,C,7.00,1/1/2007,40.0
The corresponding set of sensitivity trades representing the option position is the following
Option equivalent sensitivity trades

*TYPE=SENSITIVITY
USD,GAS,0.01,0,T,0,s_value(T)
USD,GAS,0.01,mtm,H,1/1/2007,s_value(H)
USD,GAS,0.01,0,G,1/1/2007,s_value(G)
USD,S,0.01,0,RDF,1/1/2007,s_value(RDF)
USD,GAS,0.01,0,7.00,V,1/1/2007,s_value(V)
where s_value corresponds to the numerical value of the sensitivity computed as a function of the
sensitivity type as specified in the table above, and mtm is the market value of the option.
Another interesting case is obtained if we consider a commodity option on the spread between gas at
different locations, GAS1 and GAS2, expiring on 1/1/2007. Such instrument can be valued as a spread
option, or by using the following set of sensitivity trades (in this example we neglect volatility and discount
factor risk).
Spread Option equivalent sensitivity trades

*TYPE=SENSITIVITY
USD,GAS1,,,T,0,s_value(T)
USD,GAS1,,,H,1/1/2007,s_value(GAS1,T)
USD,GAS2,,,H,1/1/2007,s_value(GAS2,T)
USD,GAS1,,,G,1/1/2007,s_value(GAS1,T)
USD,GAS2,,,G,1/1/2007,s_value(GAS2,T)
*TYPE=SENSITIVITYPAIR
USD,GAS1,GAS2,,,XG,1/1/2007,s_value(GAS1,GAS2,T)
USD,GAS2,GAS1,,,XG,1/1/2007,s_value(GAS2,GAS1,T)
We also provide an example of an equity option on the spread between EQ1 and EQ2 expiring on 1/1/2010.
Such instrument can be valued by using the following set of sensitivity trades (in this example we neglect
discount factor risk)
Spread Option equivalent sensitivity trades for two equities

*TYPE=SENSITIVITY
EUR,EQ1,,,S,,,T,0,s_value(T)
EUR,EQ1,,,S,,,H,1/1/2010,s_value(EQ1,T)
EUR,EQ2,,,S,,,H,1/1/2010,s_value(EQ2,T)
EUR,EQ1,,,S,,,G,1/1/2010,s_value(EQ1,T)
EUR,EQ2,,,S,,,G,1/1/2010,s_value(EQ2,T)
EUR,EQ1,,,S,,,100,V,1/1/2010,s_value(EQ1,T)
EUR,EQ2,,,S,,,,V,1/1/2010,s_value(EQ2,T)
*TYPE=SENSITIVITYPAIR
EUR,EQ1,EQ2,,,S,,,S,,,XG,1/1/2010,s_value(EQ1,EQ2,T)
EUR,EQ2,EQ1,,,S,,,S,,,XG,1/1/2010,s_value(EQ2,EQ1,T)
Note that several record layouts are supported. For example, for equities we support
EUR,EQ1,,,S,10,1,H,1/1/2010,s_value(EQ1,T)
EUR,EQ1,,,,10,1,H,1/1/2010,s_value(EQ1,T)
EUR,EQ1,,,S,10,1,,H,1/1/2010,s_value(EQ1,T)
The first line represents the standard format. The second line shows that the specific risk type is chosen by
default. The third line contains an additional field for strike that will be neglected unless the sensitivity is
vega.
For commodities and currencies we support

EUR,GAS1,,,H,1/1/2010,s_value(GAS1,T)
EUR,GAS1,,,,,,H,1/1/2010,s_value(GAS1,T)
EUR,GAS1,,,,,,,H,1/1/2010,s_value(GAS1,T)
The first line represents the standard format. The second and third lines are supported to maintain a
uniform format with equities. For example, if the sensitivity file is generated by StructureTool it will
produce the sensitivity trade record in the form
YourCCY,YourAsset,,,,,,,H,1/1/2010,s_value(YourAsset,T)
and the user has to fill out the accounting currency and the asset name field as it is specified in the Varworks
dataset.
*TYPE=SMILE
Smile files contain implied volatility data for options on equities, currencies, commodities, and credit ratings
(for example, government and swap curves), as a function of terms, option expiry, and moneyness level.
These curves are used for valuations of volatility dependent instruments (e.g. options) during cash flow
mapping, mark to market and VaR calculation. These curves are NOT used to perturb the volatility vertices
during the Monte Carlo simulation when generating the different scenarios for the VaR calculation. For that
purpose, the volatility information in the volatility and correlation data files (corresponding to the volatility
of volatility) is used instead. See the Volatility as a Risk Factor section on page 54 if you need to include the
volatility as a risk factor in the VaR calculation.
If smile information (for matching currency and equity or currency and credit rating for interest rate smile
data) is also provided in the volatility file (through the level field, see Volatility section on page 272), smile
data from the smile file takes precedence.
While smile data can be read for most asset classes, it is currently used by EQUITYOPTION,
EQUITYOPTION2, OPTION, OPTION2, and STRIPOPT and by a number of Fixed Income instruments,
namely CAPFLOOR2, BARRIERCAP2, RANGEACCRUAL, AVERAGECAP, and SWAPTION2. To make
the data available to these instruments use the LOADMARKETDATA function, see page 319.
asset, credit_rating, term, expiry, moneyness, volatility
1. asset Required. Text specifying a currency, commodity, or equity name. See Assets for information on
currency/commodity codes. For custom equities the field should be set to the currency of the market in
which the option with this custom equity underlying is traded.
2. credit_rating Required. Text specifying the credit rating code of the asset, if the asset is a currency. If the
asset is not a currency, specify ‘C’ for a commodity, ‘SE’ for an equity, or ‘XS’ for a exchange rate. See Codes
for a list of the credit rating codes. Examples: specify ‘Z’ for government rates or ‘S’ for swap rates. For
custom equities the field should be set to the name of the equity.
3. term Required. Number specifying the term, in years, of the rate for which volatility is input, if
asset/credit_rating specifies an interest rate. If asset/credit_rating specifies a commodity, term represents the
expiration of the contract, in years or as a date, over which the option is written. When terms is entered in
years, specify a decimal number, i.e. for 1 day, specify 0.00277778 (= 1/360); for 6 months, specify 0.5 (= 6/12);
for 30 years, specify 30. If the asset is an equity or currency the field can be left blank or can contain ‘NC’.
4. expiry Optional. Number specifying the time to expiry, in years, for the option for which the volatility
input applies. If omitted, the same volatility is used for all expiries.
5. moneyness Optional. For fixed income data (i.e. when asset is a currency and credit_rating the credit
rating of the rate for which data is given), this input specifies the moneyness (defined as the ratio of the
strike and forward rate at expiry) of the term rate specified by term input. For non fixed income data, if the
smile model used is M0, see the SMILEMODEL header, this input specifies the moneyness defined as the
ratio of the strike and either the spot (for equity of FX assets) or forward price (for commodity assets) at
expiry. For other smile models, this input should be set to the strike price, and the transformation to a
moneyness measure is done internally by VaRworks, following the input specified by the SMILEMODEL
header, see page 96 for more details.
6. volatility Required. Number specifying the volatility of the term rate for a given expiry and moneyness
level. E.g., for 25%, specify 25.
Interpolation of smile data, if required by the terms of the instrument being valued, is done in the following
way. First, the volatility corresponding to the required moneyness is obtained for nearby terms and
expiries, by using a cubic interpolation scheme. Then, data for the required expiry is obtained for nearby
terms by using linear interpolation. Finally, linear interpolation on the nearby terms is again used to derive
the required volatility. Extrapolation beyond boundary points, if required, is always flat.
Volatility curve for USD 1-month Libor at 95% moneyness

USD,R,0.083333,.25,0.95,20
USD,R,0.083333,.5,0.95,22
USD,R,0.083333,1,0.95,20
USD,R,0.083333,5,0.95,18
Volatility curve for EUR 5-year swap rate at 100% moneyness (at the money)
EUR,S,05,.25,1,30
EUR,S,05,.5,1,32
EUR,S,05,1,1,30
EUR,S,05,5,1,28
Volatility for JPY 20-year government rate

JPY,Z,20,,,30
Volatility for GAS with moneyness set to strike

GAS,C,6/1/2005,0.25,7.746,10
Volatility for INTEL with moneyness set to strike

USD,INTC,,1,20,20
Volatility for GBP FX for an at-the-money option

GBP,XS,,1,1,20
Volatility for GBP FX for an at-the-money option to exchange GBP for JPY
GBPJPY,XS,,1,1,20
*TYPE=SPREAD
A spread option is an option on the price differential between two underlying assets. The net equivalent
positions, or weights, of the assets have opposite signs (for example, +1 and -1). Weights are netted together
for a single ‚basket‛ value, which settles against the option’s strike price. A positive weight indicates a long
position, a negative weight a short one.
For example, suppose you own a call spread option struck at 20. If the price of asset 1 at expiry is 100
(weight = 1) and the price of asset 2 at expiry is 30 (weight = -1), the option will pay out (100 – 30) – 20 = 50.
The NYMEX spark spread between electricity and natural gas reflects the costs of producing power from a
specific facility. It is used to convert Btus to megawatt hours and vice versa. The spread is the heat rate (a
proxy for efficiency) of a generating unit (the number of Btus needed to make one kilowatt of electricity),
multiplied by the cost of energy expressed as dollars per British thermal units (Btus). Visit the NYMEX web
site for an energy glossary, useful publications, and links to other energy resources. The address is
http://www.nymex.com.
Spread average-price pay on the average price differential of two assets during an averaging period.
The prices of the two assets evolve according to a stochastic process where the two prices are lognormally
distributed and correlated. The correlation is specified with a number between -1 and +1, exclusive.
opt_type, ccy, asset1, asset2, pc_type, strike, opt_expiry, weight1, weight2, corr, vol1, vol2, amount,
avg_starts, num_fixings, running_avg, risk_type, dividend_yield1, dividend_yield2, spot1, spot2, beta1,
beta2
‘O’ for an ordinary option.
currency codes.
3. asset1 Required. Text specifying the first underlying asset, which may be a currency, equity, or
4. asset2 Required. Text specifying the second underlying asset, which may be a currency, equity, or
5. pc_type Required. Text specifying if the option is a call or put. Specify one of the following:
6. strike Required. Number specifying the option’s strike price expressed in ccy units. strike can be positive,
negative, or zero.
8. weight1 Optional. Number specifying the weight of asset1. May be positive or negative. If weight1 is
omitted, it is assumed to be +1.
omitted, it is assumed to be -1.
10. corr Required. Number between -1 and +1, inclusive, specifying the correlation of asset1 and asset2.
VOLATILITY header is omitted, you must specify the volatility in this field. If you provide both a vol1 value
and a VOLATILITY header value, vol1 prevails. Example: for 25%, specify 25.
VOLATILITY2 header is omitted, you must specify the volatility in this field. If you provide both a vol2
value and a VOLATILITY2 header value, vol2 prevails. Example: for 25%, specify 25.
14. avg_starts Required for APOs; ignored otherwise. Date specifying when the averaging period starts. It is
the first sampling point in the averaging period.
15. num_fixings Required for APOs; ignored otherwise. Number greater than or equal to one specifying the
number of evenly-spaced sampling points during the averaging period. num_fixings is truncated to an
integer.
16. running_avg Optional for APOs; ignored otherwise. Number greater than zero specifying the average price
established up to the effective calculation date by past price observations. running_avg applies only if the
effective calculation date falls after avg_starts and is ignored otherwise.
compounded dividend rate of the first underlying equity (asset1), as a percent. If omitted then 0 (zero) is
22. beta1 Optional, only used if asset1 is an equity and risk_type=’B’. Number specifying the beta of the equity
with respect to the market index. The market value of the equity at any time is related to a stochastic market
index I (normalized to one) using
Specify vol1 and vol2 with respect to ccy, regardless of the base or local currency of asset1 and asset2 in the
The payoff (to the holder) at expiration from a spread option is
Call: max 0, w1 S1,T  w2 S 2,T   K 

Put: max 0, K  w1 S1,T  w2 S 2,T 
where K is the strike price, wi is the weight of the i-th asset, Si,T is the spot price of the i-th asset at option
expiration.
The payoff (to the holder) at expiration from a spread average-price option is
Call:

max  0,
1 n
  
w1 S1,t j  w2 S 2,t j  K 

 n  1 j 0 

 

n
1
Put: max  0, K  
n  1 j 1
w1 S1,t j  w2 S 2,t j 
 
where K is the strike price, wi is the weight of the i-th asset, Si,t(j) is the price of the i-th asset at time
tj = ts + j(T – ts) / n, (n + 1) is the number of fixings during the averaging period, T is the time to option
expiration in years, and ts is the time to the start of the averaging period in years.
Spread options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
Long running APO call on GAS, WTI

A,CAD,GAS,WTI,C,2.0,5/1/99,7,-1,0.5,,,,11/1/98,7,1.5
Short forward-starting APO put on GAS, WTI

A,USD,GAS,WTI,P,4.0,5/1/99,7,-1,0.5,,,,3/1/99,9
Long ordinary call on GAS, WTI

O,EUR,GAS,WTI,C,1.0,5/1/99,7,-1,0.5,,,15
*TYPE=STRIPOPT
In energy and commodity markets complex instruments are often defined in terms of basic components.
Strip of options are an important example where the complex instrument (strip) is defined by a series of
successively expiring options (striplets). Striplets can be ordinary options with a predetermined strike price
(if the fwd_start_date input is not specified), or forward-start options with a strike set after inception of the
strip, on the forward-start date.
The deterministic volatility model corrections can be included in the valuation of the instrument by
specifying one of the supported models in the SMILEMODEL header.
ccy, asset, last_opt_expiry, strip_freq, ex_type, pc_type, first_opt_expiry, amount, strike, first_fut_expiry,
fwd_start_date, strike_type, markup, vol_curve, strip_curve
currency codes.
3. last_opt_expiry Required if strip_freq is different from ‘c’. Date specifying when the last option in the strip
expires. If last_opt_expiry conflicts with strip_freq then last_opt_expiry is adjusted backward to the first valid
date. For example, if last_opt_expiry is a Sunday and strip_freq is ‚d5‛ then last_opt_expiry is adjusted to the
previous Friday.
4.strip_freq Required. Text specifying the frequency of options in the strip. strip_freq determines valid expiry
dates for options in the strip.
strip_freq Description
‘c’ Custom. Option expiry dates are specified by strip_curve.
‘d2’ Two days a week, Saturday and Sunday.
‘d6’ Six days a week, Monday through Saturday.
‘f’ Quarter-hourly, seven days a week, 24 hours a day (time consuming).
‘g’ Half-hourly, seven days a week, 24 hours a day (time consuming).
‘h’ Hourly, seven days a week, 24 hours a day (time consuming).
‘4h’ Every four hour, seven days a week
‘m Once a month, with expiration dates 365/12 days apart.
‘cm’ Once every calendar month, each expiring on the same day of the month as
last_opt_expiry.
‘w’ Once a week, each expiring on the same day of the week as last_opt_expiry.
‘q’ Once a quarter, with expiration dates 365/4 days apart.
5. ex_type Required. Text specifying the option exercise style. Specify one of the following:
‘S’ for a straddle (a put and a call with the same strike price).
7. first_opt_expiry Required. Date specifying when the first option in the strip expires. If first_opt_expiry
conflicts with strip_freq then first_opt_expiry is adjusted forward to the first valid date. For example, if
first_opt_expiry is a Sunday and strip_freq is ‚d5‛ then first_opt_expiry is adjusted to the following Monday.
8. amount Optional. Number specifying the underlying amount, in millions, used to calculate the value of
the each striplet. The total value of the strip is proportional to amount Specify a positive number for a long
strip position and negative number for a short strip position. If a strip_curve is used, see below, amounts for
each striplet may be specified independently, in which case amount is ignored. If the amounts of all striplets
(see strip_curve below) are left unspecified, amount is used.
9. strike Required for non forward starting strips. Number specifying the strike price for the strip, expressed in
ccy units. For forward-starting strips the strike price is also required if fwd_start_date is in the past.
10. first_fut_expiry Required if the strip is on futures contracts, omit if the strip is on a spot (physical) currency or
commodity. Date specifying when the underlying futures contract of the first option in the strip expires. If the
first option calls for delivery of a futures contract then specify a futures expiration date falling on or after
first_opt_expiry. If the first option calls for delivery of a physical asset or settles against the spot price of the
underlying asset then omit first_fut_expiry. If first_fut_expiry is specified then the underlying asset of each
option in the strip is a futures contract; each option’s underlying futures contract expires after that option’s
expiry by the same number of days as first_fut_expiry falls after first_opt_expiry.See Remarks below for more
information.
11. fwd_start_date Required for forward starting strips; ignored otherwise. Date specifying when the strip’s
strike is set. If fwd_start_date is in the past or it is omitted, the striplets are ordinary options (non forward
starting) and the strike price must be specified as an input.
12. strike_type Optional for forward starting strips; ignored otherwise. Text specifying how the strike price is
set. The strike is always set on fwd_start_date. If strike_type is omitted and the strip is forward starting,
strike_type is assumed to be ‘S’. Specify one of the following:
strike_type Description
‘D’ Deferred start or defined strike. The strike is set to strike. ‘d’ is used with
American-style options that can only be exercised on or after fwd_start_date
rather than on or after the option’s inception (that is, the effective calculation
date). It is also used to price a strip of forward starting options that have already
converted into regular options (see Remarks below).
‘F’ Forward. The strike is set to the asset’s forward price (plus markup) for delivery
on opt_expiry. strike is ignored.
‘I’ Index. The strike is set to the fair fixed price (plus markup) of a swap on the asset
valued on fwd_start_date. The reference swap is a daily fixed-for-float index
swap that starts on fwd_start_date plus one day and matures 30 days later. strike
is ignored.
‘S’ or omitted Spot. The strike is set to the asset’s spot price (plus markup). strike is ignored.
13. markup Optional for forward starting strips; ignored otherwise. Number specifying how many accounting
currency units to add to the strike price on fwd_start_date. markup can be positive or negative. If markup is
omitted, it is assumed to be zero.
14. vol_curve Optional if VOLATILITY header is specified, required otherwise. List specifying the volatility
(annualized standard deviation) of the price of asset or the implied volatility, as a percent. Each list element
1. Volatility indicator, ‘F’ for forward structure, ‘M’ for market (Black implied) structure of
volatilities.
2. Volatility date.
Example: M,3/1/2003,50,M,6/1/2003,60,M,9/1/2003,70
If you provide both a vol_curve and a VOLATILITY header value, vol_curve prevails.
If the vol_curve is provided with the volatility indicator set to ‘F’, then no deterministic or stochastic
volatility corrections are performed. Thus, the forward volatility curve from the trade file has priority over
the implied volatility data from the volatility and smile files.
If the VOLMODEL header is set to SV or the SMILEMODEL header is specified and is not set to NONE,
then the field becomes optional.
If the VOLMODEL header is set to SV or the SMILEMODEL header is specified and is not set to NONE and
vol_curve is omitted or the vol_curve indicator is not set to ‘F’, the volatility is internally interpolated from the
smile surface obtained from the smile file for deterministic volatility adjustment or from the dataset for
stochastic volatility adjustment. If the smile surface is not provided for the underlying, and the vol_curve is
omitted, the volatility from the volatility header will be used in the valuation.
15. strip_curve Required if strip_freq=’c’. List specifying the expiration dates and the underlying amounts of
each option in the strip. Each list element contains the following items:
1. Strip curve indicator, ‘T’
2. Striplet expiration date.
3. Striplet amount.
Example: T,3/1/2003,0.01,T,6/1/2003,0.02,T,9/1/2003,0.03
specifies a strip curve with three options expiring on 3/1/03, 6/1/03, and 9/1/03 and underlying amounts of
10,000, 20,000, and 30,000 units respectively.
If the forward start date (fwd_start_date) is equal or precedes the valuation date the forward starting options
turns into regular options. In this case make sure that strike_type is set to ‚D‛ and specify the strike price as
an input.
Strips of options are priced using FEA @ENERGY models. For a technical discussion of pricing currency and
commodity derivatives see the @ENERGY User’s Guide, available from FEA. The ‘F’ and ‘M’ volatility
indicators directly corresponds to forward and market term stuctures of volatilities. To use a constant
volatility for the whole strip, omit vol_curve and specify the VOLATILITY header.
If amounts in strip_curve are omitted, for instance T,3/1/2003, ,T,6/1/2003, ,T,9/1/2003, , in the example
above, the input amount is applied to each of the striplets. Note that the definition of amount is different
from that of the corresponding @ENERGY models. Here amount refers to each of the striplets, in @ENERGY
it refers to the whole strip.
*TYPE=STRIPSPREADOPT
In energy and commodity markets complex instruments are often defined in terms of basic components.
Strip of options are an important example where the complex instrument (strip) is defined by a series of
successively expiring options (striplets). In this case striplets are options on the spread of two underlyings.
See Spread options on page 242 for additional information on the individual striplets.
ccy, asset1, asset2, last_opt_expiry, strip_freq, pc_type, strike, first_opt_expiry, weight1, weight2, corr,
amount, vol_curve1, vol_curve2, strip_curve
currency codes.
4. last_opt_expiry Required if strip_freq is different from ‘c’. Date specifying when the last option in the strip
expires. If last_opt_expiry conflicts with strip_freq then last_opt_expiry is adjusted backward to the first valid
date. For example, if last_opt_expiry is a Sunday and strip_freq is ‚d5‛ then last_opt_expiry is adjusted to the
previous Friday.
5.strip_freq Required. Text specifying the frequency of options in the strip. strip_freq determines valid expiry
dates for options in the strip.
‘c’ Custom. Option expiry dates are specified by strip_curve.
‘d2’ Two days a week, Saturday and Sunday.
‘d6’ Six days a week, Monday through Saturday.
‘f’ Quarter-hourly, seven days a week, 24 hours a day (time consuming).
‘g’ Half-hourly, seven days a week, 24 hours a day (time consuming).
‘h’ Hourly, seven days a week, 24 hours a day (time consuming).
‘4h’ Every four hour, seven days a week
‘m Once a month, with expiration dates 365/12 days apart.
‘cm’ Once every calendar month, each expiring on the same day of the month as
last_opt_expiry.
‘w Once a week, each expiring on the same day of the week as last_opt_expiry.
‘q’ Once a quarter, with expiration dates 365/4 days apart.
7. strike Required. Number specifying the unit strike price for the strip, expressed in ccy units. strike can be
8. first_opt_expiry Required. Date specifying when the first option in the strip expires. If first_opt_expiry
conflicts with strip_freq then first_opt_expiry is adjusted forward to the first valid date. For example, if
first_opt_expiry is a Sunday and strip_freq is ‚d5‛ then first_opt_expiry is adjusted to the following Monday.
omitted, it is assumed to be +1.
omitted, it is assumed to be -1.
11. corr Required. Number between -1 and +1, inclusive, specifying the correlation of asset1 and asset2.
12. amount Optional. Number specifying the underlying amount, in millions, used to calculate the value of
the each striplet. The total value of the strip is proportional to amount Specify a positive number for a long
strip position and negative number for a short strip position. If a strip_curve is used, see below, amounts for
each striplet may be specified independently, in which case amount is ignored. If the amounts of all striplets
(see strip_curve below) are left unspecified, amount is used.
13. vol_curve1 Optional if VOLATILITY header is specified, required otherwise. List specifying the volatility
(annualized standard deviation) of the price of asset1 or the implied volatility, as a percent. Each list element
1. Volatility indicator, ‘F1’ for forward structure, ‘M1’ for market (Black implied) structure of
volatilities.
2. Volatility date.
Example: M1,3/1/2003,50,M1,6/1/2003,60,M1,9/1/2003,70
If you provide both a vol_curve1 and a VOLATILITY header value, vol_curve1 prevails.
14. vol_curve2 Optional if VOLATILIT2 header is specified, required otherwise. List specifying the volatility
(annualized standard deviation) of the price of asset2 or the implied volatility, as a percent. Each list element
1. Volatility indicator, ‘F2’ for forward structure, ‘M2’ for market (Black implied) structure of
volatilities.
2. Volatility date.

Example: M2,3/1/2003,50,M2,6/1/2003,60,M2,9/1/2003,70
15. strip_curve Required if strip_freq=’c’. List specifying the expiration dates and the underlying amounts of
each option in the strip. Each list element contains the following items:
1. Strip curve indicator, ‘T’
2. Striplet expiration date.
3. Striplet amount.
Example: T,3/1/2003,0.01,T,6/1/2003,0.02,T,9/1/2003,0.03
specifies a strip curve with three options expiring on 3/1/03, 6/1/03, and 9/1/03 and underlying amounts of
10,000, 20,000, and 30,000 units respectively.
Specify volatilities with respect to ccy, regardless of the base or local currency of asset1 and asset2 in the
Strips of spread options are priced using FEA @ENERGY models. For a technical discussion of pricing
currency and commodity derivatives see the @ENERGY User’s Guide, available from FEA. The volatility
indicators directly corresponds to forward and market term stuctures of volatilities. To use a constant
volatility for the whole strip, omit vol_curve1 and/or vol_curve2 and specify the VOLATILITY headers.
If amounts in strip_curve are omitted, for instance T,3/1/2003, ,T,6/1/2003, ,T,9/1/2003, , in the example
above, the input amount is applied to each of the striplets. Note that the definition of amount is different
from that of the corresponding @ENERGY models. Here amount refers to each of the striplets, in @ENERGY
it refers to the whole strip.
*TYPE=STRESS_FILES
*TYPE=STRESS_SCENARIOS
*DRIVER=driver-vertex
*SCENARIO=name-of-scenario
Stress data encompasses all information stored in files that is necessary as input to the Varworks stress
testing functions STRESSTEST and SDATA. There are two types of stress data files.
Files of type STRESS_FILES contain single-field records; each field is a file path that points to a file of type
STRESS_SCENARIOS. Files of type STRESS_FILES give you the ability to concatenate multiple
STRESS_SCENARIOS files for input to a stress test function. Files of type STRESS_FILES are similar in
utility to files of type HISTORICALDATA and PORTFOLIO.
Files of type STRESS_SCENARIOS contain actual scenario definitions. More than one scenario can be
defined within a STRESS_SCENARIOS file. Each scenario is prefixed with a SCENARIO header. The records
that follow the SCENARIO header define how various assets are to be stressed, or shocked, in accordance
with the scenario.
STRESS_SCENARIOS records define basic ways of shocking an asset or a set of assets. Within the context of
a given scenario, an asset may be specified in more than one record. If specified in more than one record of a
given scenario, the various shocks applied to that asset are additive. In this way, you may superpose shocks
in order to construct a more complex scenario, one that cannot be realized within a single record.
For more information about stress testing and scenario design, see Stress Testing on Page 42.
Herein is a description of the record layout for both types of stress-data files: STRESS_FILES and
STRESS_SCENARIOS.
This is the record layout for a STRESS_FILES type of file:
stress_scenarios_file_path
1. stress_scenarios_file_path Required. Text specifying the path (optional) and file name of a
STRESS_SCENARIOS type of file. If no path (that is, only a file name) is specified, only the current directory
is searched. The following three examples all refer to the same file:
c:\stress\tech_crisis.txt ,
\stress\tech_crisis.txt if C is the current drive, and
tech_crisis.txt if c:\stress\ is the current directory.
This is the record layout for a STRESS_SCENARIOS type of file:
asset, asset_class, maturity, shock_value, shock_type[, shock_model]
1. asset Optional. Text specifying the asset code of the asset or assets to be shocked, which may be a
currency or commodity. If this field is unspecified, then all pertinent assets (underlying the portfolio to be
stress tested) will be assumed. See Assets for information on currency and commodity codes.
2. asset_class Optional. Text specifying the asset class of the asset or assets to be shocked. If this field is
unspecified, then all pertinent asset classes (underlying the portfolio to be stress tested) will be assumed.
See Codes for a list of asset classes, including credit rating codes.
Note: If asset refers to a currency and you leave asset_class unspecified, then the wildcard completion of this
field will be R and S. This allows you to apply a shock model to a curve consisting of LIBOR and swap rates.
If you wish to apply a shock model to a curve consisting of LIBOR and government rates, specify two
records: one with asset_class set to R and another with asset_class set to Z. This works because shocks of a
given scenario are superimposed.
3. maturity Optional. A number specifying the maturity of the asset or assets to be shocked. If this field is
unspecified, then all pertinent maturities (underlying the portfolio to be stress tested) will be assumed, i.e., it
is assumed that you wish to refer to a curve or set of curves. If this field is specified it must conform to the
conventions for the maturity component of a vertex name . See Codes for more information.
Note: This field must be zero or unspecified if asset_class refers to a spot asset (i.e., XS, SE, or G). If left blank
when specifying other asset classes, then it is assumed you are denoting a curve or set of curves.
4. shock_value Required. Number, positive or negative, specifying the size of the stress or shock that should
be applied to the asset or assets denoted by the asset, asset_class, and maturity fields. The units of shock_value
are defined by shock_type. If shock_model is specified, then shock_value is a parameter of the model, otherwise,
it is an explicit shock amount.
5. shock_type Required. Text specifying the unit of measure of shock_value. Specify one of the following:
‘PERCENT’ if shock_value is a percentage of the asset’s market value.
‘ABSOLUTE’ if shock_value is an absolute value.
‘SDEV’ if shock_value is in units of standard deviation. Stress applied to simple returns.
‘LOGSDEV’ if shock_value is in units of standard deviation. Stress applied to log-returns.
Note: You cannot specify an ABSOLUTE shock_type if asset_class is SE since the market values of spot
equities are sometimes not provided within volatility data files. If ‘SDEV’ is selected, the formula used to
derive the stressed value is P1 = max( 0, P0 * (1 + N * V / 1.645 )), if ‘LOGSDEV’ is selected, the formula used
is P1 = P0 * exp( N * V / 1.645 ), where P0 is the pre-stress test vertex price level, P1 is the post-stress test
vertex price level, V is the daily vol from the vol_data file, and N is the shock_value.
5. shock_model Optional. Text specifying a type of collective shock to be applied to a set of assets (as
defined by the asset, asset_class , and maturity fields), which taken together, denote one or more curves.
Shock models are described in detail in the Remarks section, below. Specify one of the following:
‘PARALLEL’ if the collective shock is a parallel shift as a function of maturity (or strike for
implied volatility vertices).
‘CURVATURE’ if the collective shock is a triangle shape as a function of maturity(or strike
for implied volatility vertices).
‘TWIST’ if the collective shock is a diagonal line as a function of maturity(or strike for
implied volatility vertices).
Note: You cannot apply a shock model to spot asset classes (i.e., XS, SE, and G) since these cannot denote
curves. Similarly, if you do specify a shock model, you must leave the maturity field blank to indicate that
your specified assets represent a curve or set of curves. If asset_class is Z (S), a curve will be constructed from
R and Z (S), but the shocks will only be applied to Z (S). If asset_class is unspecified, then a curve will be
constructed from R and S and shocks will be applied to both sets of maturities.
You must have read permission for the all stress data files, and each file must be located on a network drive
or server accessible to you.
Stress data files can contain comments, prefixed with a ‘#’ symbol, and blank lines.
Taken together, the asset, asset_class, and maturity fields of a STRESS_SCENARIOS record form a composite
primary key that identifies a unique market vertex synonymous with a RiskMetrics market vertex (or
bucket).
By leaving a combination of the asset, asset_class, and maturity fields unspecified, you can wildcard your
definitions of shocks, thus reducing the number of records required to specify the stresses to be applied to
various assets.
In order to do stress testing for custom equities asset should be set to the home currency and asset_class
should be set to the name of the underlying equity. Analogously, for implied volatility vertices asset should
be set to the home currency and asset_class should be set to the name of the implied volatility identifier
specified in the asset file. One can shock more than one IV risk factor by omitting the strike and/or maturity
fields in the IV vertex name, see the examples below.
A shock model is a collective stress, one applied to a set of assets forming a curve or set of curves. VaRworks
defines three such models:
PARALLEL. This shock_model is one in which all of the assets (points) of the curve are shocked with the
same exact shock_value. It represents a uniform shift of the curve from its market value.
CURVATURE. This shock_model produces a triangle-like profile of shock values as a function of maturity.
The assets (points) of a given curve corresponding to the smallest and largest maturities (i.e., the endpoints)
receive shocks equal to shock_value while the asset (point) mid-way between the endpoints (i.e., the
midpoint) receives a shock equal to –shock_value. All other assets (points) receive shocks that are values
linearly interpolated (with respect to maturity) between shock_value and –shock_value. Thus, for example, the
asset (point) whose maturity lies halfway between the lower endpoint and the midpoint receives a shock of
value zero.
TWIST. This shock_model produces a diagonal-like profile of shock values as a function of maturity. The asset
(point) of a given curve corresponding to the smallest (largest) maturity receives a shock equal to shock_value
(-shock_value). All other assets (points) receive shocks that are values linearly interpolated (with respect to
maturity) between shock_value and –shock_value. Thus, for example, the asset (point) whose maturity lies
one-quarter of the way between the lower endpoint and the upper endpoint receives a shock of value equal
to one-half shock_value.
For more information about stress testing and scenario design, see Stress Testing on Page 42.
STRESS_FILES Example
*TYPE=STRESS_FILES
tech_crisis.txt
\stress\gulf_war.txt
g:\trader_a\stress\federal_reserve.txt
STRESS_SCENARIOS Example
*TYPE=STRESS_SCENARIOS
# interest–rate stress scenario

*SCENARIO=interest-rate stress
# use US short rate as a driver – this will drive all assets not specified below
*DRIVER=USD,R,30
# Japanese interest-rate (LIBOR+SWAP) twist corresponding to one standard deviation

JPY,,,1,SDEV,TWIST
# give JPY an additional shock

JPY,R,30,0.25,SDEV
# and shock the exchange rate by 10% of its value, too

JPY,XS,,10,PERCENT
# oil-price stress scenario

*SCENARIO=gulf war
# driver currently US short rate; for this scenario, keep unspecified assets fixed
*DRIVER=
# apply absolute (in terms of WTI price) parallel shift to WTI forward price curve
WTI,C,,5,ABSOLUTE,PARALLEL
# give additional shock to all spot commodities

,C,0,1,SDEV
*SCENARIO=shock_implied_volatility_vertex
# change the implied volatility for options on INTC underlying, strike =20.5,
# maturity = 2/10/2006 by +0.1 (i.e., if the implied vol used to price the option is 30%,
# change the value to 40%)
USD,INTC_IV(20.5,2/10/2006),,0.1,ABSOLUTE
*SCENARIO=shock_volatility_smile
# change the implied volatility for options on INTC underlying,
# maturity = 2/10/2006 by applying a 1% twist to the existing strike smile
USD,INTC_IV(,2/10/2006),,1,PERCENT,TWIST
*SCENARIO=shock_volatility_skew
# change the implied volatility for options on INTC underlying,
# strike=20.5 by applying a +0.1 curvature schock to the existing maturity skew
USD,INTC_IV(20.5,),,0.1,ABSOLUTE,CURVATURE
*SCENARIO=shock_volatility_surface
# Shift the implied volatility surface for options on INTC underlying, by +0.1,
# uniformly across maturities and strike
USD,INTC_IV(,),,0.1,ABSOLUTE
*TYPE=SWAP
Swaps are private agreements between two companies to exchange cash flows in the future according to a
prearranged schedule. They can be regarded as portfolios of forward contracts. Forward-starting swaps and
swaps with different payment frequencies for each leg are supported.
Interest-rate swaps
An interest-rate swap is an agreement to exchange net future cash flows. In fixed-for-floating swaps one
counterparty pays a fixed rate and the other pays a floating rate based on a reference rate, such as Libor.
There is no exchange of principal—the interest payments are made on a notional amount.
Currency swaps
A currency swap involves the exchange of cash flows in one currency for those in another. Unlike single
currency swaps, currency swaps typically require an exchange of principal. Typically the notional principal
is exchanged at inception at the prevailing spot rate. Interest-rate payments are then passed back on a fixed,
floating, or zero basis. The principal is then re-exchanged at maturity at the initial spot rate.
Interest-rate swap
ccy, credit_rating, principal, maturity_date, rate, rate_freq, rate_basis, first_reset_rate, floating_rate_freq,
forward_start_date,,,,,,, call_schedule <C, date, price,...>, sinking_fund <S, date, prin_reduction,...>
Currency swap
ccy, credit_rating, principal, maturity_date, rate, rate_freq, rate_basis, first_reset_rate,, forward_start_date,
ccy2, principal2, rate2, rate_freq2, rate_basis2, first_reset_rate2, call_schedule <C, date, price,...>,
1. ccy Required. Text specifying a currency code. For interest-rate swaps, specify the swap’s settlement
currency. For currency swaps, specify the settlement currency of the swap’s first leg. See Assets for
information on currency codes. See The Euro for Euro-related issues. Examples: USD, EUR, or JPY.
2. credit_rating Required. Text specifying the credit rating of the swap, which determines which yield curve
is used to discount cash flows. See Codes for a list of the credit rating codes. See The Euro for Euro-related
issues. Example: For the swap curve, specify ‘S’.
3. principal Required. Number specifying the notional principal in millions of ccy. For interest-rate swaps,
specify a positive number to pay a fixed rate or a negative number to receive a fixed rate. For currency
swaps this field is always positive, if you are short the currency swap, reverse ccy and ccy2 (along with their
corresponding principal and rate fields). See Remarks below for more information. See The Euro for Euro-
related issues. Example: For an interest-rate swap principal of 10 million ccy, paying floating, specify -10.
4. maturity_date Required. Date specifying the maturity date of the swap.
5. rate Required for all interest-rate swaps and some currency swaps—see Remarks below. Number specifying the
fixed rate, as a percent. Example: for 5.5%, specify 5.5.
6. rate_freq Required for all interest-rate swaps and all currency swaps—see Remarks below. Number specifying
the rate frequency of rate expressed as the number of payments per year; typically 1, 2, 4, or 12. For currency
swaps this is the payment frequency of the ccy leg.
7. rate_basis Required for all interest-rate swaps and some currency swaps—see Remarks below. Text specifying
the rate basis of first_reset_rate. first_reset_rate is converted to a bond equivalent rate prior to cash flow
mapping. Specify one of the following:
8. first_reset_rate Required for all interest-rate swaps and some currency swaps—see Remarks below. Number
specifying the floating rate set on the previous reset date, as a percent. Example: For 5.5%, specify 5.5.
9. floating_rate_freq Required for interest-rate swaps with unequal payment frequencies, omit otherwise. For
currency swaps omit this field and use rate_freq2 instead. Number specifying the rate frequency of the floating
rate expressed as the number of payments per year; typically 1, 2, 4, or 12. For interest-rate swaps, if
floating_rate_freq is omitted then both the fixed and floating legs have the same payment frequency rate_freq.
10. forward_start_date Required for forward-starting swaps, omit otherwise. Date specifying the date when
interest begins to accrue on a swap if it is later than the date the swap is entered into. This is the date when
the first rate fixing occurs on the floating side, and one fixed-rate payment period before the first payment
occurs on the fixed side.
11. ccy2 Required for all currency swaps, omit for interest-rate swaps. Text specifying the currency code of the
currency swap’s second leg. See Assets for information on currency codes.
12. principal2 Required for all currency swaps, omit for interest-rate swaps. Number specifying the notional
principal in millions of ccy2. This field is always positive, if you are short the currency swap, reverse ccy and
ccy2 (along with their corresponding principal and rate fields). Example: For a principal of 10 million ccy2,
specify 10.
13. rate2 Required for some currency swaps, omit for interest-rate swaps—see Remarks below. Number specifying
the ccy2 fixed rate (if applicable), as a percent. Example: For 5.5%, specify 5.5.
14. rate_freq2 Required for all currency swaps, omit for interest-rate swaps—see Remarks below. Number
specifying the rate frequency of rate2 or first_reset_rate2 expressed as the number of payments per year;
typically 1, 2, 4, or 12.
15. rate_basis2 Required for some currency swaps, omit for interest-rate swaps—see Remarks below. Text
specifying the rate basis of first_reset_rate2. first_reset_rate2 is converted to a bond equivalent rate prior to
cash flow mapping. Specify one of the following:
16. first_reset_rate2 Required for some currency swaps, omit for interest-rate swaps—see Remarks below. Number
specifying the floating rate (if applicable) of ccy2 set on the previous reset date, as a percent. Example: For
5.5%, specify 5.5.
2. Call or put date—must fall on a payment date.
3. Rate (as a percent).
Example: C,1/1/2015,14,C,1/1/2017,12,C,1/1/2019,11
following items:
2. Date—must fall on a payment date.
immediately following first_reset_rate2.
Here are the types of interest-rate swaps supported and how to specify them:
Supported Interest-rate Swaps
IR swap type Specify these fields Omit these fields (or zero)
Pay fixed ccy ccy2
Receive floating credit_rating principal2
positive principal rate2
maturity_date rate_freq2
rate rate_basis2
rate_freq first_reset_rate2
rate_basis
first_reset_rate
Pay floating ccy ccy2

Receive fixed credit_rating principal2
negative principal rate2
maturity_date rate_freq2
rate rate_basis2
rate_freq first_reset_rate2
rate_basis
first_reset_rate
If both ccy2 and principal2 are specified, then the swap is a currency swap. Here are the types of currency
swaps supported and how to specify them:
Supported Currency Swaps
Currency swap type Specify these fields Omit these fields (or zero)
Pay ccy fixed ccy rate_basis
Receive ccy2 fixed credit_rating first_reset_rate
positive principal rate_basis2
maturity_date first_reset_rate2
positive principal2
ccy2
rate
rate_freq
rate2
rate_freq2
Pay ccy floating ccy rate

Receive ccy2 floating credit_rating rate2
positive principal
maturity_date
positive principal2
ccy2
rate_freq
rate_basis
first_reset_rate
rate_freq2
rate_basis2
first_reset_rate2
Currency swap type Specify these fields Omit these fields (or zero)
Pay ccy fixed ccy rate_basis
Receive ccy2 floating credit_rating first_reset_rate
positive principal rate2
maturity_date
positive principal2
ccy2
rate
rate_freq
rate_freq2
rate_basis2
first_reset_rate2
Pay ccy floating ccy rate

Receive ccy2 fixed credit_rating rate_basis2
positive principal first_reset_rate2
maturity_date
positive principal2
ccy2
rate_freq
rate_basis
first_reset_rate
rate2
rate_freq2
The following tables describe which party may exercise the option if a call or put schedule is specified for
interest-rate and currency swaps.
Interpreting Interest-rate Swap Call/Put Schedules
If the option And the sign of Then this party

type is principal is has the option
Call Positive Floating
Call Negative Fixed
Put Positive Fixed
Put Negative Floating
Interpreting Currency Swap Call Schedules
If the currency swap Then treat the call schedule like

type is this
Fixed for floating Same as an interest-rate swap.
Floating for fixed Same as fixed for floating with

negative principal.
Fixed for fixed Same as fixed for floating, using

the first fixed rate as the fixed rate
in cancellation calculations.
Floating for floating There are no options in this case.
Specify a swap’s amortization schedule in sinking_fund.
Sinking funds are not allowed for zero-coupon instruments.

For sinking funds, the percent principal reduction is a reduction of the original principal, so all the
reductions must sum to less than or equal to 100.
For sinking funds, the reduction price is typically 100, meaning that $1 is paid for every $1 principal is
reduced. In some situations reduction price may be greater than 100 (for example, prepayment penalties).
Rates are converted to bond equivalent rates prior to cash flow mapping. These rate basis conversions are
done using one of the following formulas (see Stigum (1981) for more information).
If rate_basis is BE, BErate = rate (no conversion).
365
If rate_basis is CD, BErate  rate 
360
rate
rate _ freq 365
If rate_basis is D, BErate    rate _ freq
1  rate  rate _ freq 360
For a technical discussion of pricing interest-rate securities, see the @INTEREST User’s Guide, available
from FEA.
Pay floating, receive fixed interest-rate swap

USD,S,-100,1/1/1999,13,1,CD,9.5
Pay floating, receive fixed, with call schedule interest-rate swap

USD,S,-100,1/1/2000,13,1,CD,9.5,,,,,,,,,C,1/1/1999,12
Pay fixed, receive floating, with call schedule and sinking fund interest-rate swap
USD,S,10,1/1/2001,10.5,2,CD,7.875,,,,,,,,,C,1/1/1999,11,S,1/1/1999,10,S,1/1/2000
,10
Pay floating, receive fixed—forward starting interest-rate swap

EUR,S,-10,1/1/2000,13,2,CD,9.5,,1/1/1999
Pay fixed, receive floating—two frequencies and forward starting interest-rate swap
JPY,S,100,1/1/2001,13,2,CD,9.5,4,1/1/1999
Pay fixed, receive fixed with sinking fund currency swap

GBP,S,5,1/1/2000,12,1,,,,,EUR,3,13,1,,,S,1/1/1999,20
Pay floating, receive floating currency swap

JPY,S,90,1/1/2000,,1,CD,2,,,USD,1,,2,CD,7.5
Pay fixed, receive floating currency swap

EUR,S,5,1/1/2000,12,1,,,,,JPY,270,,1,CD,6
Pay floating, receive fixed currency swap

EUR,S,5,1/1/2000,,1,BE,7.5,,,USD,3,8,1
Pay fixed, receive fixed with sinking fund—forward starting currency swap
EUR,S,5,1/1/2001,12,2,,,,1/1/1999,GBP,3,13,2,,,S,1/1/2000,20
Pay floating, receive floating—forward starting currency swap

EUR,S,10,1/1/2002,,2,CD,5,,6/1/1999,EUR,3,,2,BE,5
*TYPE=SWAPTION
A swap option, or swaption, is an option to enter an interest-rate swap. A call gives the purchaser the right
to pay fixed; a put gives the purchaser the right to receive fixed (pay floating).
This is a deprecated trade instrument. The trade instrument Swap Options (type ii) is a replacement for this
trade instrument. The new trade type provides more flexibility in specifying the terms of a Swap Option
instrument. More specifically: 1) the payment frequency of the instrument can be specified independently
from the term of the rate underlying the instrument, 2) if the floating leg rate is a CMS rate, a distinct basis
and payment frequency can be specified for such a rate, 3) the contract can pay in arrears of its reset or not,
4) the user can specify how dates are rolled and time is counted, 5) the user has control over the
interpolation scheme used for the instrument valuation. In addition, the choice of basis for the underlying
rate now follows established market conventions.
ccy, credit_rating, principal, ex_type, pc_type, option_maturity, swap_maturity, strike_rate, rate_freq,

rate_basis, amort_schedule <A, date, amount,...>, strike_schedule <K, date, strike_rate,...>
3. principal Required. Number specifying the notional principal in millions of local currency. Specify a
issues.
‘B’ for Bermuda exercise (requires strike_schedule).
‘C’ for call option (right to pay fixed).
‘P’ for put option (right to receive fixed).
6. option_maturity Required if ex_type is ‘A’ or ‘E’, ignored if ex_type is ‘B’. Date specifying the maturity date
of the option. If ex_type is ‘B’ then specify strike_schedule instead.
7. swap_maturity Required. Date specifying the maturity date of the underlying swap.
8. strike_rate Required if ex_type is ‘A’ or ‘E’, ignored if ex_type is ‘B’. Number specifying the strike rate as a
percent. Example: For 5.5%, specify 5.5.
9. rate_freq Required. Number specifying the frequency (times per year) of the fixed and floating rates.
Typically 1, 2, 4, or 12.
10. rate_basis Required. Text specifying the rate basis of floating rate. This rate is converted to a bond
Example: A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
12. strike_schedule Required if ex_type is ‘B’, ignored otherwise. List specifying the strike schedule of the
instrument. Required for variable strike instruments, leave blank otherwise. Each list element contains the
following items:
3. New strike rate (as a percent).
Example: K,1/1/1997,5.0,K,1/1/1998,5.5
schedule immediately following rate_basis.
FEA.
European put on an amortizing swap.

USD,S,100,E,P,1/1/1997,1/1/2002,5.00,2,BE,A,1/1/1998,10,A,1/1/1999,10
American call
USD,S,100,A,C,1/1/1997,1/1/2002,5.00,2,BE
Bermuda put with a strike schedule (non-amortizing)

USD,S,100,B,P,,1/1/2002,,2,BE,K,1/1/2000,5.5,K,1/1/2001,6.0
*TYPE=SWAPTION2
A swap option, or swaption, is an option to enter an interest-rate swap. A call gives the purchaser the right
to pay fixed; a put gives the purchaser the right to receive fixed (pay floating).
ccy, credit_rating, principal, ex_type, pc_type, option_maturity, swap_maturity, strike_rate, pmt_term,

rate_term, fixed_basis, floating_basis, floating_spread, first_pmt_date, first_reset_rate, cms_freq, cms_basis,
arrears, rollday, opt_start, is_quanto, quanto_ccy, quanto_credit_rating, amort_schedule <A, date,
amount,...>, coupon_schedule <N, date, coupon rate,...>, strike_schedule <K, date, strike_rate,...> ,
vol_schedule <M1, date, vol,...>, vol2_schedule <M2, date, vol,...>, corr_schedule <CORR, date, vol,...>
3. principal Required. Number specifying the notional principal in millions of local currency. Specify a
issues.
‘B’ for Bermuda exercise (requires strike_schedule).
‘C’ for call option (right to pay fixed).
‘P’ for put option (right to receive fixed).
6. option_maturity Required if ex_type is ‘A’ or ‘E’, ignored if ex_type is ‘B’. Date specifying the maturity date
of the option. If ex_type is ‘B’ then specify strike_schedule instead.
7. swap_maturity Required. Date specifying the maturity date of the underlying swap.
8. strike_rate Required if ex_type is ‘A’ or ‘E’, ignored if ex_type is ‘B’. Number specifying the strike rate as a
percent. E.g., specify 5.5 for 5.5%.
11. fixed_basis Optional. Text specifying the rate basis of the fixed rate.
12. floating_basis Optional. Text specifying the rate basis of the fixed rate. For choices, see fixed_basis above.
13. floating_spread Optional. Number specifying the spread on the floating rate.
16. cms_freq Optional. Number specifying the payment frequency Iper year) of the CMS rate paid on the
floating leg. Defaults to the frequency corresponding to pmt_term, if omitted. Ignored if rate_term is less
than one.
Ignored if rate_term is less than one. Defaults to rate_basis, if omitted. For choices, see fixed_basis above.
20. opt_start Optional. Date specifying when the option is first exercisable. This option is only relevant for
American ex_type forward-starting options. The default is today, read from the system clock.
a swap curve.
E.g., A,6/1/1997,10,A,6/1/1998,10,A,6/1/1999,20
25. coupon_schedule Optional. List specifying the fixed coupon schedule of ccy. Ignored if swap_type
indicates ccy pays a floating rate. Each list element contains the following items:
1. Coupon indicator ‘N’.
Example: N,1/1/1997,5.0,N,1/1/1998,5.5
26. strike_schedule Required if ex_type is ‘B’, ignored otherwise. List specifying the strike schedule of the
instrument. Required for variable strike instruments, leave blank otherwise. Each list element contains the
following items:
3. New strike rate (as a percent).
E.g., K,1/1/1997,5.0,K,1/1/1998,5.5
27. vol_schedule Optional. List specifying the volatility of the underlying rate, as a percent, corresponding to
the specified term. Each list element contains the following items:
2. Volatility date.
If you provide both a vol_schedule and a VOLATILITY header value, and the model is BLACKY, vol_schedule
prevails. If you specify a volatility smile through the LOADMARKETDATA function, volatilities in the
smile file prevail, but vol_schedule data is still used, if specified, to compute convexity adjustments when
they are required by the term of the instrument. Vol_schedule and smile data are only used if the interest
rate model specified in the header is BLACKY.
E.g., M1,1/1/1997,15.0,M1,1/1/1998,20
28. vol2_schedule Optional List specifying the volatility of the foreign exchange rate, as a percent. Used only
if the interest rate model specified in the header is BLACKY and if is_quanto is set to true. Each list element
2. Volatility date.
If you provide both a vol_schedule and a VOLATILITY header value and if the interest rate model specified
in the header is BLACKY, vol_schedule prevails.
E.g., M2,1/1/1997,15.0,M2,1/1/1998,20
29. corr_schedule Optional. List specifying the correlation between the foreign exchange rate and the
underlying rate, between and including -1 and +1. Used only if the interest rate model specified in the
header is BLACKY and if is_quanto is set to true. Each list element contains the following items:
E.g., CORR,1/1/1997,0.15,CORR,1/1/1998,0.20
schedule immediately following quanto_credit_rating.
FEA.
European put on an amortizing swap.

USD,S,100,E,P,1/1/1997,1/1/2002,5.00,2,0.5,,,,,,,,,,,,,,A,1/1/1998,10,A,1/1/1999
,10
European call
USD,S,100,E,C,1/1/1997,1/1/2002,5.00,2,0.5
Bermuda put with a strike schedule (non-amortizing)

USD,S,40,B,C,5/12/98,5/12/2000,3,2,0.5,,,,,,,,,,,,,,K,5/12/97,1.2,K,11/12/97,1.4
*TYPE=VQCASHFLOW
This instrument models the case when the flow amount corresponding to a particular cashflow is uncertain,
and the distribution of possible values at the simulation horizon can be modeled as a normal distribution, or as
a shifted lognormal distribution. This instrument is particularly useful when the horizon time coincides or is
very close to the value_date of the cashflow, and one is in a situation where actual, realized amounts on
value_date can only be estimated in a statistical sense. The correlation coefficient between the overall
amount change and the log return of the price corresponding to the asset underlying the cashflow can also
be specified.
asset_code, credit_rating, value_date, amount, vqamount, vqvol, plflag, corr
1. asset_code Required. Text specifying a currency or commodity code, or equity name. See Assets for
information on asset codes.
2. credit_rating Required. Text specifying the credit rating of the cash flow. This determines which yield
curve is used to discount cash flows. Valid credit_rating values follow:
credit_rating Asset class

XS Spot foreign exchange (spot only, value_date ignored)
R Money market
S Swap
Z Government
AAA,AA,A,BBB,BB,B,C Corporate
CC,D
C Commodity
SE Spot equity index (spot only, value_date ignored)
G Brady bond (spot only, value_date ignored)
Any in-Euro ccy code See The Euro for more information.
3. value_date Required. Date specifying when the cash flow is going to take place.
4. amount Required. Number specifying the amount of the cash flow in millions of local currency. If asset
represents a commodity, amount is the number of units of that commodity that are received (amount > 0) or
paid (amount < 0) on value_date. Note that if asset is an equity amount represents the present value of the
total equity position flowing on value_date. See vqvol below for an explanation of the relation between the
total amount of the cashflow, amount and vqamount inputs. Specify a positive (negative) amount for a long
(short) cashflow position.
5.vqamount Optional. Omit or set equal to zero to specify a normal distribution of overall amount for the
cashflow. If different from zero, vqamount specifies the expected value and the sign of the uncertain
component of the overall amount, which is modeled as a shifted lognormal distribution. See vqvol below for
an explanation of the relation between the total amount of the cashflow, amount and vqamount inputs.
6. vqvol Optional. Volatility, expressed in absolute terms, specifying the distribution from which overall
amounts are determined at the simulation horizon. If vqamount is omitted or zero the distribution is N(m,),
i.e. a normal distribution with mean m equal to amount and standard deviation  equal to vqvol. If vqamount
is non zero, the distribution is given by amount ± LN(m, ), with LN a lognormal distribution with expected
value m equal to the absolute value of vqamount, percent volatility  = |vqvol / vqamount|; the + or () sign
is determined by the sign of vqamount. Note that the absolute value of vqvol is always used, so that changing
the sign of vqvol has no effect on results.
7. plflag Optional. Numerical flag determining how to include the risk associated with the uncertain amount
in the P&L calculation, when VaR is computed via MonteCarlo simulation. If plflag is equal to 0 market risk
and ‚amount risk‛ are both included. If plflag is equal to 1, only market risk is included. If plflag is equal to
2, only ‚amount risk‛ is included. Hence, if X and X(h) denote the overall amount on the effective date, and
on the horizon date respectively, and if P and P(h) denote unit MtM on the same dates, the P&L used when
computing VaR is given by P(h) X(h) PX if plflag=0, P(h)X(h) PX(h) if plflag=1, and P(h)X(h) P(h)X if
plflag=2.
8. corr Optional. Number specifying the correlation between the amount change and the log return of the
price corresponding to the asset underlying the cashflow. If the credit rating is a rate or XS the amount
change is correlated to the foreign exchange rate specified through the asset_code input. If the credit rating
is C or SE the amount change is correlated to the commodity or equity price specified through the
asset_code input. If vqamount is specified, log price changes and log amount changes are correlated via the
corr input, if vqamount is omitted log price changes and amount changes are correlated instead.
The total amount of the cashflow on the effective date of the calculation, used to compute the Mark to
Market of the instrument, is given by amount + vqamount. The distribution of values on the simulation
horizon date, is determined by amount, vqamount, and vqvol. See vqvol above for an explanation of how the
distribution is determined. Notice that if vqamount is non zero, the distribution can be specified to have a
lower bound at the value corresponding to amount.
The stochastic nature of the overall amount is currently accounted for only when Monte Carlo simulation is
used to compute VaR. Other methodologies are computed by neglecting the stochastic nature of the overall
amount, i.e. they are computed by assuming that vqvol is equal to zero. Therefore identical results can be
obtained by using the CASHFLOW instrument with a total amount equal to amount + vqamount.
If a cash flow has a spot credit rating (XS, SE, and G) then value_date is ignored and the cash flow is always
mapped to a spot vertex.
Note that plflag should be set equal to zero or one depending on whether the underlying instrument that
one is modeling stipulates that the unit price on value_date should be paid for the expected amount
(plflag=0), or for the actual realized amount (plflag=1). In the former case the risk of the cashflow includes the
volumetric risk associated with vqamount, in the latter it does not.
*TYPE=SWING
Swing contracts, or variable- or base-load factor contracts, are common in natural gas and power markets.
They will be described in terms of a generic underlying commodity. Generally, swing contracts guarantee
the owner the possibility of taking periodic delivery of a certain amount of commodity (the ‚nominated
amount‛) on certain dates in the future at a stipulated constant price, and also provide the option to change
(‚swing‛) the amount delivered according to certain fixed rules. The basic rules are 1) that a predetermined
maximum number of swings can be exercised during the term of the contract and 2) that an overall
maximum and minimum amount constraint applies during the same time period, or tenor.
Two distinct types of swing contracts are supported. In the first, the amount to which the swing applies is
only the quantity of commodity on the following delivery date. In other words, after that date and until
exercise of a new swing, the amount delivered will revert to the fixed ‚nominated amount‛. We refer to this
as the swing-daily-amount model. In the second, the swing amount becomes a new nominated amount and,
as such, will be delivered, beginning on the following delivery date, until exercise of a new swing right. We
refer to this second case as the swing-nominated-amount model.
The following conventions define the exact specifications of the contracts supported. We follow the
terminology of the natural gas market where periodic means daily delivery, the period of time over which
delivery takes place is typically one month (the delivery month), and the time period where the constant strike
price in many deals is set is called bid week. Notice however that the pricing models themselves are more
general and that parallel language can be applied to electricity, oil, and similar ‚continuously available‛
commodity markets.
Exercise of one swing right allows the owner to either increase the amount delivered to a maximum amount,
or to decrease it to a minimum amount. The swing in the amount is thus discrete and up or down to known
values (as opposed to a continuous, or ratchet discrete). This is mainly a technical restriction that might be
lifted in future releases, depending on user demands.
A swing right can be exercised on each day preceding any delivery day and only one swing right can be
exercised per day. The new amount following exercise of a swing right will be delivered on the day
following the exercise of the right. All exercise decisions are made at the same time each day.
If, during the tenor of the contract, the total amount delivered is either less than a minimum monthly
amount or more than a maximum monthly amount, a penalty must be paid by the owner of the contract.
Two penalty provisions are allowed: 1) the first implements a buyback rule whereby, at expiration, the owner
pays the writer of the contract the cost of the deficient or excess quantity delivered. For instance if X is
the (positive) deficient quantity at expiration, K is the fixed stipulated unit price, and S is the market spot
X   Max( K  S ,0) . If X  is the (positive) excess quantity
price at expiration, the penalty to be paid is
at expiration, the penalty is X   Max(S  K ,0) ; 2) the second corresponds to a fixed unit penalty per unit
amount of excess or deficient delivery.
Financial settlement for the delivery of gas can either be at expiration of the contract, or on each delivery
day. Any financial penalty related to excess or deficient delivery is always settled at expiration of the
contract.
The constant strike price is usually set equal to the published value of a certain index determined over a bid
week possibly increased by a prescribed percentage amount. Our models reduce bid week to a single day
(more precisely to a point in time) and assume delivery to begin on the following day. After bid week the
index is known and the constant price that gas will be paid for during the remaining portion of the delivery
month is fixed. However, if the contract is entered into before the corresponding ‚bid week‛, two
possibilities are allowed depending on the input provided for index: (a) if the input is positive it will be
treated again as a fixed strike; (b) if it is negative or zero, the index is modeled as the fixed price of an
hypothetical fixed for floating swap contract (always settled at the end of the delivery month. In case (b) the
actual negative value input is irrelevant, and the appropriate index is internally computed by the model.
ccy, asset, swing_type, settlement_type, penalty_type, index, mark_up, volatility, vol_to_start, nom_amt,
max_amt, min_amt, max_m_amt, min_m_amt, run_amt, max_swing, expiry_date, start_date, n_delivery,
penalty
currency codes.
3. swing_type Required. Text specifying the swing type. See swing-daily-amount and swing-nominated-amount
above for more information. Specify one of the following:
‘D’ for daily swings.
‘N’ for nominated swings.
4. settlement_type Required. Text specifying the settlement type. See settlement above for more information.
‘M’ for settlement at maturity.
‘D’ for settlement on delivery.
5. penalty_type Required. Text specifying the penalty type. See penalty above for more information. Specify
‘B’ for buy-back provision.
‘U’ for unit-penalty provision.
If penalty_type is ‘U’ then specify penalty.
6. index Required. Number specifying the base price used to set the fixed price for future delivery of one unit
of asset. If start_date falls before bid week and index is negative or zero, the input will be ignored and
automatically replaced by the appropriate value. See bid week above.
7. mark_up Required. Number specifying the percent increase or decrease with respect to index which sets
the price for future delivery of one unit of asset. Each unit of the delivered commodity will cost index  (1 +
mark_up / 100). Express mark_up as a percent. Example: for 2%, specify 2.
8. volatility Required. Number specifying the volatility, or annualized standard deviation, of asset during
the delivery month, expressed as a percent. Example: for 25%, specify 25.
9. vol_to_start Required. Number specifying the volatility, or annualized standard deviation, of the asset
during the time period preceding the delivery month, expressed as a percent. vol_to_start is only used when
the delivery month is in the future and the strike price is fixed in advance. Example: for 25%, specify 25.
10. nom_amt Required. Number specifying the number of units of asset, in millions, that will be delivered
daily starting on start_date. Specify a positive number if you are long the contract (strip + flow + swing) or a
negative number if you are short the contract (strip + flow – swing). See Remarks below.
11. max_amt Required. If swing_type is ‘D’ (daily swings) then max_amt is a number specifying the
maximum number of units of asset, in millions, that will be delivered on the day following exercise of a
swing right. If swing_type is ‘N’ (nominated swings) then max_amt is a number specifying the maximum new
nominated amount of asset, in millions, that will be delivered on the day following exercise of a swing right.
12. min_amt Required. If swing_type is ‘D’ (daily swings) then min_amt is a number specifying the minimum
number of units of asset, in millions, that will be delivered on the day following exercise of a swing right. If
swing_type is ‘N’ (nominated swings) then min_amt is a number specifying the minimum new nominated
amount of asset, in millions, that will be delivered on the day following exercise of a swing right.
13. max_m_amt Required. Number specifying the maximum total number of units of asset, in millions, that
can be delivered over the delivery month. If more units are delivered following the exercise of swing rights,
a penalty fee is charged.
14. min_m_amt Required. Number specifying the minimum total number of units of asset, in millions, that
can be delivered over the delivery month. If less units are delivered following the exercise of swing rights, a
penalty fee is charged.
15. run_amt Required. Number specifying the number of units of asset, in millions, that have been delivered
to date. If the delivery month has not yet started then run_amt is zero.
16. max_swing Required. Number specifying the maximum number of swing rights remaining in the
contract. max_swing must be an integer greater than or equal to one. The maximum number of swing rights
is 31 for a daily swing contract (swing_type is ‘D’) and four for a nominated swing contract (swing_type is
‘N’).
17. expiry_date Required. Date specifying the contract’s expiration date.
18. start_date Required. Date specifying the first asset delivery date in the contract. If delivery month is in
progress then start_date falls in the past.
19. n_delivery Required. Number specifying the number of equally-spaced delivery times from start_date to
expiry_date. n_delivery is an integer greater than or equal to 2. For gas, n_delivery is typically the number of
days between start_date to expiry_date, inclusive, for power more frequent delivery times are not unusual.
20. penalty Required if penalty_type is ‘U’, omit otherwise. Number specifying the (positive) penalty per unit
of asset expressed in units of ccy.
Swing contracts are priced using FEA SWING. Verify your basic understanding of the specifications listed
above by working through some of the relevant examples given in the SWING User’s Guide, available from
FEA.
The total value of a swing contract can be naturally decomposed into the sum of three components. Since
swing contracts guarantee the possibility of taking periodic delivery of a certain amount of commodity on
certain dates in the future at a stipulated constant price, one component is the price of such a contract if no
swing rights were exercised during its lifetime. A second crucial price component is the total value of the
swing rights associated with the contract. Finally, if the commodity flow is settled at the end of the contract,
a final straightforward price component will be the present value of the commodity already flowed. By
including this last component we assume that, when the contract is sold prior to expiration, all financial
liabilities are transferred to the new owner of the contract. For this reason the value of the commodity
already flowed, but not yet settled, is always negative or zero. We refer to these as the strip price, swing
price, and flow price components of the total value of the contract, respectively. Without loss of generality
we can always assume a long strip position. Depending on whether the swing position is long or short the
total value of the contract is then equal to strip + flow + swing or strip + flow – swing, respectively.
The SWING function arguments fwd_begin and fwd_end (described in the SWING User’s Guide) are read
from the volatility-correlation dataset. fwd_begin specifies the current forward price, for delivery during bid-
week, of one unit of asset. If start_date falls on or before today, that is, we are already in the delivery month,
then fwd_begin is the asset spot price. fwd_end specifies the current forward price, corresponding to the end of
the delivery month, of one unit of asset.
The interest rate of ccy is read from the volatility-correlation dataset.
For a technical discussion of pricing swing contracts see the SWING User’s Guide, available from FEA.
Daily swing option, struck at the future index

USD,GAS,D,M,U,0,0,60,60,0.01,0.02,0.01,0.4,0.3,0,10,11/30/1996,11/1/1996,30,0
Daily swing option, struck at fixed

USD,GAS,D,M,U,2,0,60,60,0.01,0.02,0.01,0.4,0.3,0,10,11/30/1996,11/1/1996,30,0
Daily swing option: long the strip, short the swings

USD,GAS,D,M,U,1.95,0,60,60,0.01,0.02,0.01,0.4,0.3,0,5,11/30/1996,11/1/1996,30,0
Daily swing option marked to market during delivery month (today is 11/4/1996)
USD,GAS,D,M,U,2.10,0,60,60,0.01,0.02,0.01,0.4,0.3,0.05,9,11/30/1996,11/1/1996,30
,0
Daily swing option with penalties

USD,GAS,D,D,B,0,0,60,60,0.01,0.01,0,0.3,0.21,0,30,11/30/1996,11/1/1996,30,0
Nominated-amount swing option with penalties

USD,GAS,N,D,B,0,0,60,60,0.01,0.01,0,0.3,0.21,0,2,11/30/1996,11/1/1996,30,0
TODO: check wording changes to pricevol, primary, and beta.
*DATE=yyyymmdd,ROW=number-of-records,COL=5,CONTENT=est_type
*REBASE_CCY=CCY
*NAME,LEVEL,DECAY,PRICEVOL,YIELDVOL,PRIMARY_NAME,BETA
where est_type is DVF for daily (one-day), MVF for monthly, or VF for other volatility forecasts.
Volatility files contain daily or monthly volatilities and other time-series statistics. Each record in a volatility
file specifies a vertex onto which cash flows are mapped.
name, level, decay, pricevol, yieldvol,primary_name,beta
1. name Required. Text specifying the series name (vertex) in the format:
asset.asset_class[maturity] where asset is an asset code and asset_class[maturity] is one of the Asset Class and
Maturity Codes listed in Codes. The asset_class[maturity] portion of the name has a special format for
implied volatility vertices. See the example below, or the description on page 103.
2. level Required. Number or text specifying the exchange rate or yield of the series. The entry depends on
the asset class:
Asset class Entry

XS Exchange rate in USD per unit of local currency terms (USD/local_ccy).
R,S,Z,AGY, Zero-coupon interest rate for the specified asset class and maturity in percent.
AAA,AA,A,BB
B,BB,B,
CCC,D or
custom ratings
SE The spot equity index value.
C The commodity price for the specified maturity.
G The Brady bond price as a percentage of face value.
IV (implied The volatility level corresponding to the strike and expiry (and term of the
vol) underlying rate for fixed income instruments) specified in the asset class label in
percent.
3. decay Required. Number specifying the exponential decay factor used in calculating the price volatility.
4. pricevol Required. Number specifying the price volatility estimate (as a percent) multiplied by 1.65. For
the implied volatility vertices this field should be set to be equal to the volatility of volatility estimate
multiplied by 1.65. For vertices modeled via the Primary/Secondary risk model (see page 34) this number
represents the specific volatility, not the total volatility of the price.
5. yieldvol Required. For interest-rate series (money market, swap, and government), a number specifying
the yield volatility estimate, in percent, multiplied by 1.65. For other series (foreign exchange, equity,
commodity, and implied volatility), specify ‚NC‛.
6. primary_name Optional. Text specifying the name of the risk vertex that acts as a primary source of risk
for this vertex. If not specified or ‚NC‛, the vertex will be treated as a primary source of risk. When
specified, the pricevol input above represents the specific volatility of the secondary factor, not the overall
volatility of the vertex, see Eq. PS2, page 34.
6. beta Optional. Number specifying the beta of the vertex to its primary source of risk, specified by
primary_name.
To maintain compatibility with RiskMetrics, header records in volatility files differ from those in other files.
price_volatility must be multiplied by 1.65 for compatibility with published standards.

If the interest-rate price_or_yield value encountered is numeric then that value is used in calculations.
Otherwise, if the value is not numeric (for example, ‚NA‛) then the yield is estimated using
price _ vol
yield 
maturity  yield _ vol
where
price_vol = price volatility
yield_vol = yield volatility
maturity = maturity of yield in years
This formula is derived from the following relationship
price _ vol  yield _ vol  yield  maturity
Notice that the volatilities used to compute VaR are further adjusted when CONTENT=DVF or
CONTENT=MVF, depending on the user specified risk horizon. In the former case, they are multiplied by
sqrt(BD(H)), in the latter they are multiplied by sqrt(H*12/365), with H equal to the risk horizon in calendar
days, and BD(H) is the risk horizon in business days. When CONTENT=VF no adjustments are made.
FX record
EUR.XS,0.693674,0.940,0.815916,NC
Money market record

JPY.R030,2.500000,0.940,0.01729,8.506716
Swap record
CHF.S05,3.728061,0.940,0.309955,1.724812
Government record
USD.Z30,6.321000,0.940,1.824128,1.022745
Equity index record

JPY.SE,10660,0.940,2.060359,NC
Commodity record (Constant Maturity Price Risk)

WTI.C01,68.520870,0.940,1.357080,NC
Commodity record (Fixed Expiration Price Risk)

WTI.C1/26/07,68.520870,0.940,1.357080,NC
Implied volatility record (Fixed Expiration Vertex)

USD.SP500_IV(1150;12/17/2005),15.723300,0.940,2.629120,NC
*TYPE=YIELDCURVE
Yield curve files contain points on the zero-coupon yield curves for different currencies and credit ratings
(for example, government and swap curves). The curves are used for present value and forward rate
calculations during cash flow mapping and VaR calculation. If yield curve information (for matching
currency and credit rating) is also provided in the volatility and correlation data files, the volatility and
correlation data from those files is used, but the (possibly) derived yield (see Remarks in the Volatility
section on page 272) is replaced by the data in the yield curve file.
Yield curve files can also contain data representing futures prices for any commodity in the
volatility/correlation datasets. As with yield curve information such data is used for present value
calculations during cash flow mapping and VaR calculations and it superseeds the price information
contained in the volatility/correlation files.
Tip You can create yield curve files from volatility files using the GENRATES utility. See GENRATES for
more information.
All yield curves are assumed to be composed of continuously compounded zero-coupon rates. This means
you must convert interest rates as quoted within certain markets to this standard form. For instance,
Treasury coupon curves must be converted to zero curves. There are a number of methods for making this
conversion.
One approach is the bootstrap method, see Hull (1997) pp. 80–84. See FEA’s @INTEREST product for an
implementation of this method.
You must also convert all rates to continuous compounding. You can use the following formula to convert
rates that are compounded n times per year to continuous compounding
 compounded _ rate 
continuous _ compounding _ rate  n log1  
 n 
asset, credit_rating, term, price_or_yield
1. asset Required. Text specifying a currency or commodity. See Assets for information on
currency/commodity codes.
2. credit_rating Required. Text specifying the credit rating code of rate, if asset is a currency, or ‘C’ if asset is
a commodity. See Codes for a list of the credit rating codes. Examples: specify ‘Z’ for government rates or ‘S’
for swap rates.
3. term Required. Number specifying the term, in years, of the rate given by price_or_yield, if asset is a
currency. Specify a decimal number. Examples: For 1 day, specify 0.00277778 (= 1/360). For 6 months, specify
0.5 (= 6/12). For 30 years, specify 30. If the asset is a commodity term can also be entered as a date
representing the expiration of the futures contract for which the price is given by price_or_yield. In this case
the header DATEORDER can be used to specify the format of the date.
4. price_or_yield Required. Number specifying an annualized, continuously-compounded, zero-coupon

rate, if asset is a currency. Specify the rate as a percent. Example: For 5.5%, specify 5.5. If asset is a
commodity, price_or_yield represents the price of the futures contract expiring on term.
Specify at least two different types of zero-coupon curves for each currency: government and swap. Custom
credit rating curves can also be specified thorugh this input. Yield curves are used for pricing fixed income
instruments (which curve is used is specified as part of the trade record), and for discounting other
instruments (for instance equity, commodity, or FX options where the data corresponding to the swap curve
is used). If you fail to specify a swap curve then instruments that are normally discounted against the swap
curve are discounted against the government curve. If you fail to specify a government curve then an error
occurs if your portfolio contains government or agency instruments.
To the extent the swap (asset class S) and government (asset class Z) yield curves are unspecified on the
short end, money market rates (asset class R) are treated as the short end of those yield curves. In other
words, money market rate points with maturities that are less than the shortest maturity on these yield
curves are treated as points along that curve.
Similarly, the swap yield curve, if present, is used as the long end of the money market yield curve.
Points on the yield curve that do not correspond exactly to a cash flow’s payment date are linearly
interpolated. If a cash flow date falls after the date of the last point on the yield curve, then the last point is
used. If a cash flow date falls before the date of the first point on the yield curve, then the first point is used.
Note that commodity prices specified in the volatility/correlation files can refer to either constant maturity
or fixed expiration prices .Thus an entry in the volatility file corresponding to WTI.C12 represents an
hypothetical futures vertex expiring one year after value date, the expiration date of the vertex changes as
value_date changes, and the price has to be obtained, in general, by interpolating market quoted prices.
Inputting commodity forward/futures prices with fixed expiration date via the yieldcurve file, allows for a
more accurate mark to market of commodity positions in the user’s portfolio.
The number of data points in the volatility/correlation files corresponding to a yield or commodity curve
does not need to match the number of data points specified in the yield curve file for the same asset. In
general, vertices in the volatility/correlation files are used for specifying the cashflow and simulation
buckets, while price/yield curves contained in the yieldcurve file are used for generating the mark to market
values required in the analysis.
USD 1-month Libor

USD,R,0.083333,6.06227
EUR 5-year swap rate

EUR,S,05,6.387898
JPY 20-year government rate

JPY,Z,20,3.835000
GAS futures price curve

GAS,C,11/1/05,5.60
GAS,C,12/1/05,5.90
GAS,C,1/1/06,6.30
Worksheet functions perform value-returning operations in spreadsheets automatically and return their
results in a single cell or a rectangular array of cells. Spreadsheet add-in functions must be installed before
you can use them. For more information on loading and unloading add-ins, search Microsoft Excel Help for
add-in or add-in programs.
 In the syntax line, required arguments are bold and optional arguments are in plain text (not
bold).
 Argument names usually use underline characters between words; for example num_periods
is an argument name.
 Functions are shown without the equal sign ( = ). Remember to type an equal sign at the
beginning of every formula, but not before functions in nested formulas.
When you type a function and enter it into a cell, you must use proper function syntax, that is, the sequence
of character used to enter a valid function. Every function description includes a syntax line, for example:
FUNCTIONNAME(arg1, arg2, arg3)
In the syntax line, the required arguments are bold; optional arguments are not bold. If you do not provide
required arguments to a function, you will not be able to enter the function in a cell. In the preceding
example, the arguments arg1 and arg2 are bold and therefore required. arg3 is not bold and therefore is
optional, so either of the following is allowed (assume arg1 is a string argument and arg2 and arg3 are
numeric arguments):
FUNCTIONNAME(‚some text‛, 10, 3.14159)
FUNCTIONNAME(‚some text‛, 10)
FUNCTIONNAME(‚some text‛), FUNCTIONNAME(,10), and FUNCTIONNAME() are not allowed

because both arg1 and arg2 are required arguments.
Arguments to a function can be any of the following types:

 Numbers Examples of numbers are 0, 622.1962, 0.005, and -40.002. Numbers without
decimals are called integers. Examples of integers are 0, 622, and -40.
 Text Examples of text are ‚a‛, ‚Chris‛, ‚123‛, or ‚‛. Text (or string) values used in formulas
must be enclosed in double quotation marks. A text constant that contains no characters is
written as ‚‛ and is called empty text or a zero-length string.
 Logical values The logical values are TRUE and FALSE. Logical arguments can also be
formulas that evaluate to TRUE or FALSE.
 References Examples of references are $A$1, A1, $A1, A$1, or $A$1:$F$33 References can
refer to single cells or ranges. When you use a reference as an argument that is supposed to be
a number, text, or logical value, the contents of the cells specified by the reference are used as
the argument.
 Arrays Array constants can be used as arguments in place of references when you don’t want
to enter each constant value in a separate cell on your worksheet. Surround array constants
with braces, separate values in different rows with semicolons, and separate values in different
columns with commas. An m  n array has m rows and n columns. For example, enter a 2  3
array constant as {1,2,3;4,5,6} or an 8  1 array constant as {‚p‛;‚d‛;‚g‛;‚v‛;‚t‛;‚r‛;‚h‛;‚c‛},
including the braces. If this array constant is also part of an array formula then you would
enter it as an array formula. See Array Formulas for more information.
In Microsoft Excel, the Function Wizard is an interactive set of dialog boxes that guide you through the steps
of choosing the function and arguments to use in your formula. To start the Function Wizard, choose
Function (Insert menu). The first Function Wizard dialog box contains a list of function categories, such as
Financial and Logical, and a list of functions, such as COUNT and SUM. The FEA categories list FEA
product functions. (This dialog is skipped if the active cell already contains a function.) In the second dialog
box, you describe how the function will work by entering values for the arguments.
You can also use keyboard shortcuts to easily enter a function. After you type a valid function name in a
formula press CTRL+A to display step 2 of the Function Wizard or CTRL+SHIFT+A to insert the argument
names and parentheses for the function.
You can complete nearly all tasks in Microsoft Excel with the keyboard instead of the mouse, saving time
and reducing the risk of repetitive stress injury. Here we list the most common keyboard shortcuts used for
working with FEA add-in functions. For a full list of shortcuts, search Microsoft Excel Help for keyboard
shortcuts.
 In documentation, key names match the names shown on most keyboards and appear in
capital letters. For example, the Shift key appears as SHIFT.
 The RETURN key and the ENTER key perform the same action. ‚Press ENTER‛ means that
you can press either ENTER or RETURN.
 A plus sign (+) between key names means to press the keys at the same time. For example,
CTRL+S means press the CTRL key and hold it down while you press S.
 A comma (,) between key names means to press the keys sequentially. For example, ALT,F,S
means press ALT and release it, press F and release it, and then press S and release it.
Menu commands and dialog box controls have one underlined accelerator character which you can press in
combination with the ALT key to choose the command or activate the control. To select a menu command
with the keyboard, press ALT and the underlined character. For example, ALT,F,S performs the File-Save
command. To move the focus to a dialog box control, press ALT and the underlined character.
To Press
Complete a cell entry ENTER
Cancel a cell entry ESC
Repeat the last action F4
Delete text to the end of the line CTRL+DELETE
Move one character up, down, left, or right Arrow keys
Move to the beginning of the line HOME
To Press
Create names from cell text CTRL+SHIFT+F3
Fill down CTRL+D
Fill to the right CTRL+R
Start a formula EQUAL SIGN
Activate a cell and the formula bar F2
Paste a name into a formula F3
Define a name CTRL+F3
Calculate all sheets in all open workbooks F9 or CTRL+EQUAL SIGN
Calculate the active sheet SHIFT+F9
Enter the date CTRL+SEMICOLON
Enter the time CTRL+SHIFT+COLON
Alternate between displaying cell values and displaying cell CTRL+`(single left quotation
formulas mark)
Copy a formula from the cell above the active cell into the cell CTRL+' (apostrophe)
or the formula bar
Enter a formula as an array formula CTRL+SHIFT+ENTER
Display step 2 of the Function Wizard, after you type a valid CTRL+A
function name in a formula
Insert the argument names and parentheses for a function, after CTRL+SHIFT+A
you type a valid function name in a formula
Carry out the Cells command (Format menu) CTRL+1
Apply the General number format CTRL+SHIFT+~
Apply the Percentage format with no decimal places CTRL+SHIFT+%
Apply the Date format with the day, month, and year CTRL+SHIFT+#
To Press
Move one cell up, down, left, or right Arrow keys
Extend the selection by one cell SHIFT+ arrow key
Extend the selection to the edge of the current data region CTRL+SHIFT+ arrow key
Extend the selection to the beginning of the row SHIFT+HOME
Extend the selection to the beginning of the worksheet CTRL+SHIFT+HOME
Extend the selection to the last cell in the worksheet (lower- CTRL+SHIFT+END
right corner)
Select the entire column CTRL+SPACEBAR
Select the entire row SHIFT+SPACEBAR
Select the entire worksheet CTRL+A
Extend the selection down one screen SHIFT+PAGE DOWN
Extend the selection up one screen SHIFT+PAGE UP
Select a range around the active cell (the selected range is an CTRL+SHIFT+*
area enclosed by blank rows and blank columns, that is, the
current region)
Move one screen up or down PAGE UP or PAGE DOWN
Move one screen to the right ALT+PAGE DOWN
Move one screen to the left ALT+PAGE UP
Move to the previous sheet in the workbook CTRL+PAGE UP
Move to the next sheet in the workbook CTRL+PAGE DOWN
Scroll to display the active cell CTRL+BACKSPACE
When you examine the formulas in the sample spreadsheet templates, you’ll notice that many of the FEA
add-in function arguments are range names, not cell references. For example, the @ENERGY OPT function
formula might be:
=OPT(ex_type,pc_type,strike,opt_expiry,fwd_curve,vol_curve,rate_curve,amount,spot,return_choices,mode
l,model_parameters,value_date,fut_expiry)
and not, say,:
=OPT(A1,A2,A3,A4,C1:D10,E1:F10,G1:H5,A5,A6,I1:I6,A11,J1:J3,A7,A8)
Here, cell A1 is named ex_type, cell A2 is named pc_type, cell A3 is named strike, and so on. A range name is
a word or string of characters that represents a cell or range of cells. It is an easy-to-remember identifier you
create to refer to a range. (A range is a cell, a row, a column, a selection of cells containing one or more
contiguous blocks of cells, or a 3-D range.) In FEA spreadsheet templates, range names are usually limited to
a single cell or a rectangular array of cells. Using names has the following advantages:
 Formulas that contain names are easier to read and remember than formulas using cell
references.
 If you change the structure of your worksheet, you can update the reference in one place, and
all formulas using that name are automatically updated. For example, in the OPT function
above, if you move the strike price from cell A3 to cell B25 then all you need do is change the
‚strike‛ reference to B25. All formulas using the name ‚strike‛ are updated—there’s no need
to edit the formulas themselves.
 Formulas can be entered very rapidly if range names match the function argument names. For
example, in the OPT function above, the range names correspond exactly to the names of the
OPT function arguments ex_type, pc_type, strike, and so forth. Type =OPT and press
CTRL+SHIFT+A to insert the OPT argument names and parentheses. Press ENTER to enter the
formula (or CTRL+SHIFT+ENTER to enter an array formula).
 Names can be used almost anywhere you might use a regular reference, including formulas
and dialog boxes.
 Each workbook can share a single set of names. Names that refer to cells on a worksheet can be
used throughout the workbook, eliminating the need to re-create names for each new
worksheet or to type worksheet references in cells.
 You can also create names that are specific to a particular worksheet. For example, if the name
‚strike‛ is defined on several worksheets then formulas using that name refer to the ‚strike‛
reference on that particular worksheet. To confirm which cells a formula refers to, select the
cell containing the formula, choose Auditing (Tools menu), and then click Trace Precedents.
This following instructions describe how to manipulate names.
1. On the Insert menu, click Name, then click Define (or press CTRL+F3).
2. In the Names in workbook box, enter the name for the formula or reference.
3. In the Refers to box, type the reference. The formula must begin with an equal sign (=). The
current selection is already indicated.
1. Select the cell, range of cells, or nonadjacent selections that you want to name.
2. Click the Name box at the left end of the formula bar.
3. Type the name for the cells.
4. Press ENTER.
Note You cannot name a cell while you are changing the contents of the cell.
1. Select the range you want to name, including the row or column labels.
2. On the Insert menu, point to Name, then click Create.
3. In the Create names in box, designate the location that contains the labels by selecting the Top
row, Left column, Bottom row, or Right column check box.
Note A name created by using this procedure refers only to the cells that contain values and does not
include the existing row and column labels.
1. On the Edit menu, click Go To (or press CTRL+G or F5).

2. Select the name in the Go to box.
You must have defined names in your workbook before you can paste names into a formula.
1. In the formula bar, click where you want to paste the name. If the formula bar is blank, type an
equal sign (=) to start the formula.
2. On the Insert menu, click Name, then click Paste.
3. Select a name from the Paste name list.
1. On the Insert menu, point to Name, and then click Define (or press CTRL+F3).
2. In the Names in workbook list, click the name whose reference you want to check. The Refers
to box displays the reference the name represents.
Tip You can also create a list of the available names in a workbook. Locate an area with two empty
columns on the worksheet (the list will contain two columns—one for the name and one for a description of
the name). Select a cell that will be the upper-left corner of the list. On the Insert menu, point to Name, and
then click Paste. In the Paste Name dialog box, click Paste List.
1. On the Insert menu, point to Name, and then click Define (or press CTRL+F3).
2. In the Names in workbook box, click the name whose cell reference you want to change.
3. In the Refers to box, change the reference.
1. On the Insert menu, click Name, then click Define (or press CTRL+F3).
2. In the Names in workbook list, click the name you want to change.
3. In the Names in workbook box, double-click the name.
4. Type the new name for the reference, then click Add.
5. To delete the original name, click the original name, then click Delete.
Warning This will disable all formulas that use the original name. To replace the original name with the
new name in formulas, click Replace (Edit menu), type the original name in the Find what box, type the
new name in the Replace with box, and then repeatedly click Find Next and Replace to selectively change
the names.
1. Select the range that contains formulas in which you want to replace references with names.
To change the references to names in all formulas on the worksheet, select a single cell.
2. On the Insert menu, point to Name, and then click Apply.
3. In the Apply names box, click one or more names.
 Click the cell or select a cell range. The Name box at the left end of the formula bar displays
either the address of the (active) cell, such as A1, or the name that refers to the cell(s).
–or–
 On the Insert menu, point to Name, and then click Define (or press CTRL+F3). Scroll through
the names in the Names in workbook box, while referring to the cell references in the Refers
to box.
Tip You can locate the cells that provide data to formulas and find cells that depend on values in other
cells by using the Auditing toolbar. To display the Auditing toolbar, point to Auditing on the Tools menu,
and then click Show Auditing Toolbar.
For more information about names, search Microsoft Excel Help for names and naming.
Most FEA functions can be entered as array formulas. Array formulas produce more than one result and so
occupy several worksheet cells. Therefore, an array formula covers an array range, which is a rectangular
range of cells that share a common formula. An m  n array has m rows and n columns. For example, a 5  2
array has five rows and two columns; a 1  1 array is a single cell.
Because an array range shares one formula, an array range is edited differently than ordinary cells. When
you edit an array range, you edit the entire range at once as if it were a single cell. You cannot perform any
operation that modifies only a portion of the array range, such as:
 Change the contents of cells that are a part of an array.
 Clear, move, or delete cells that are part of an array.
 Insert cells into an array range.
If you attempt any of these operations, Microsoft Excel displays a message that tells you the operation
cannot be done for an array. You can, however, format individual cells in an array range and copy and paste
all or part of an array range to another part of the worksheet.
Before entering an array formula you will need to know the size of the returned array. The following table
lists FEA spreadsheet products and the function arguments and other factors that determine the its size.
FEA product Function arguments determining the returned array size

@ENERGY return_choices and the number of underlying assets.
@EQUITY choice and the number of underlying assets.
@GLOBAL choice and the number of underlying assets.
@INTEREST choice and the number of underlying rates/currencies.
DerivaTool Size of specified array and the number of underlying assets.
SPAV choice and the number of underlying assets.
SWING choice
FEA product Function arguments determining the returned array size

VaRworks asset_list, cash_flow_array, maturity_list
If your function call only returns a single value then you can enter it as an ordinary single-cell formula
(rather than an array formula). If it returns n values then the array formula must span (at least) n cells.
This following instructions describe how to enter, edit, clear, and select array formulas and ranges.
1. Select the cell or range of cells in which you want to enter the formula.
2. Enter the formula.
Microsoft Excel adds braces when you enter the formula as an array; do not type braces
around the formula. If you do, Microsoft Excel interprets the entry as text.
3. Press CTRL+SHIFT+ENTER.
You must hold down both the CTRL and SHIFT keys when you press ENTER. If you hold
down only the SHIFT key, the formula is entered as an ordinary formula in the active cell. If
you hold down only the CTRL key, the formula is entered as an ordinary formula in all the
selected cells.
1. Select any cell in the array range.

2. Activate the formula bar.
The array formula braces disappear when the formula bar is active.
3. Edit the formula.

2. Press CTRL+/.
1. Select the array range.

2. Press DELETE (or choose Clear (Edit menu), and then choose Contents).
1. Clear the existing array range (see above).

2. Select the new range.
3. Enter the formula.
Tip When you add columns and rows to an existing array you don’t have to delete the existing array
formula (step 1 above)—simply select the new extended array range, press F2, and then press
CTRL+SHIFT+ENTER. When you delete columns and rows you must completely delete the existing array
formula, but you can copy it to the clipboard (before performing step 1) by highlighting it in the formula bar
and pressing CTRL+C. Then, instead of steps 3 and 4, press F2 to enter edit mode, press CTRL+V to paste
the formula, and then press CTRL+SHIFT+ENTER.
Calculation is the process of computing formulas and then displaying the results as values in the cells
containing the formulas. You can control when calculation occurs, and you can use calculation options to
control other aspects of calculation.
Whenever possible, Microsoft Excel updates only those cells affected by values you change so that you can
avoid unnecessary calculations. Calculations are performed on the basis of the underlying stored values in
cells, not on the values as they are formatted for display—changing the appearance of a value has no effect
on the value itself.
Each time you enter or edit a formula, Excel automatically recalculates all the formulas contained in the
current workbook. If you are entering or editing many formulas on a complex worksheet, you can speed up
the response time considerably by changing from Automatic to Manual calculation. Automatic calculation
calculates all dependent formulas every time you make a change to a value, formula, or name. This is the
default calculation setting. Manual calculation calculates open workbooks only when you press F9. Use
Automatic calculation when you want to see the effects of changes as you work; use Manual calculation
when you are building an application, modifying it heavily, or entering data and you don’t need
intermediate results.
Change when a worksheet or workbook calculates

1. On the Tools menu, click Options, then click the Calculation tab.
2. Under Calculation, select an option.
When calculation is set to Manual, you can selectively calculate portions of workbooks, worksheets, or
formulas.
Calculate all worksheets in all open workbooks

 Press F9.
Calculate only the active worksheet

 Press SHIFT+F9.
Force calculation of all cells on all worksheets in all open workbooks

 Press CTRL+ALT+F9.
Note This forces recalculation of cells whether or not their precedent cells (that is, cells
directly or indirectly related to the formula in the cell) have been changed.
Calculate a single cell

1. Select the cell.
2. Press F2.
3. Press ENTER.
Calculate a single array range

2. Press F2.
Calculate a portion of a formula

1. Select the cell containing the formula.
2. In the formula bar, select the portion of the formula you want to calculate. Make sure to
include the entire operand. For example, if you select a function, you must select the entire
function name, the opening parenthesis, the arguments, and the closing parenthesis.
3. Press F9 to calculate the selected portion.
4. Press ENTER to accept the calculated portion, or press ESC to restore the original formula.
Warning When you replace a formula or portion thereof with its value, Excel permanently
removes the formula. If you accidentally replace a formula with a value and want to restore
the formula, choose Undo (Edit menu) immediately after you enter the value.
Although every spreadsheet application has particular requirements, there are basic considerations that
generally result in faster recalculation.
Arrange formulas so they can be recalculated from left-to-right, then downward

Excel recalculates worksheets from left-to-right and then downward; design your applications to take
advantage of this recalculation order. If you use forward references—cell formulas that depend on cells
below or to the right of them—then Excel must perform more than one recalculation pass during each
recalculation cycle so results are up-to-date.
Speed up recalculation of workbooks that contain data tables

Data tables recalculate whenever a workbook is recalculated, even if they have not changed. To speed up
recalculation of worksheets that contain data tables, change the calculation option to automatically
recalculate the worksheet but not the data tables; choose Tools-Options-Calculation and then click
Automatic Except Tables. When you are ready to recalculate the table, press F9.
Minimize the number of open workbooks not needed for recalculation

If the workbook you are working on is not related to the other open workbooks then close them (remove
them from memory) to remove them from Excel’s recalculation chain.
If the other open workbooks depend on the workbook you are working on then save and close the other
open workbooks. When you have finished working on the current workbook, update the links in the other
workbooks. For example, suppose an application consists of workbooks A, B, and C, and that both
workbooks B and C have links to workbook A, but workbook A does not have links to either workbooks B
or C. When you are entering or changing data in workbook A, save and close workbooks B and C. After you
have finished working on workbook A, update the links in workbooks B and C using the Edit-Links-Update
Now command.
If the workbook you are working in depends on other open workbooks, you can speed up recalculation by
closing the other workbooks and delaying link refresh. Do not update the links until all your changes have
been made. Then, to insure up-to-date results, choose Edit-Links-Update Now, or choose File-Open to re-
open the other workbooks. In either case, Microsoft Excel updates all the links during the next recalculation
cycle.
Use file links efficiently

If your workbook contains links to other workbooks on disk, link to the results of formulas rather than
creating formulas that contain multiple links. For example, if workbook A sums several values in workbook
B, create a formula in workbook B that performs the summary, and then link to the cell that contains the
formula.
Keep linked-to workbooks small and put referenced cells in the beginning (upper-left) of the workbook so
the referenced cells can be found more quickly. Also try to refer to single-cells in linked-to workbooks rather
than multiple-cell ranges. If you link to multiple-cell ranges, Excel must read each cell in the range into
memory in order to resolve the link, even if the link itself needs only a single cell value (for example, links
involving the INDEX worksheet function).
Avoid excessive nesting of formulas

When you nest formulas in cells, the entire formula must be recalculated whenever any part of the formula
needs to be recalculated. For example, all IF function arguments are evaluated even if some of the
arguments are not needed for particular recalculation. For instance, given the following formula:
=IF(TODAY()>DATE(1997,6,22),PV(A1/100,12,100),PV(B1/100,12,100))
Excel must perform the following steps to evaluate the entire formula even if the PV formulas do not change
over time:
1. Read values from cells A1 and B1.
2. Calculate A1/100 and B1/100.
3. Calculate TODAY and DATE.
4. Calculate both PV functions.
5. Evaluate the IF condition.
6. Return the result.
To speed up recalculation, put parts of the formulas in separate cells and refer to those cells in the highest-
level formula. In this example, if you place the PV formulas in separate cells and refer to them in the IF
formula, Excel recalculates the PV formulas only when the data to which they refer changes, not whenever it
recalculates the IF formula.
Minimize volatile cells

Where possible, avoid using volatile cells, particularly if they contain file links. Volatile cells are cells whose
values change even if you do not modify the workbook. If a volatile cell contains a link to a file on disk, the
file reference is automatically refreshed each time Excel recalculates the volatile cell, further slowing
recalculation.
Cells that contain any of the following worksheet functions, and any cells dependent on them, are
recalculated each time Excel recalculates the workbook: AREAS, CELL, COLUMNS, INDEX, INDIRECT,
INFO, NOW, OFFSET, RAND, ROWS, and TODAY. In addition, Excel recalculates add-in worksheet
functions whether the add-ins are loaded or unloaded.
BACKTEST(data_array, confidence, start_date, end_date, start_season, end_season)
CASHFLOWMAP(maturity_list, asset_list, vol_data, corr_data, portfolio, confidence, home_ccy,

effective_date, preserve_var, pv, cross_corrs, asset_codes, yield_curves, exchange_rates)
CFDATA(vol_data, corr_data, value, home_ccy, portfolio, effective_date, preserve_var, pv, cross_corrs,

asset_codes, display_flag)
COMPONENTVAR(cash_flow_array, vardelta_array, as_cash_flows)
EXTREMEVALUE(tail_array, total_points, var_quantile, error_conf, tail_points, tail_quantile)
HDATA (vol_data, corr_data, hist_data, vertex, horizon, start_date, end_date, start_season, end_season,
return_filter, asset_codes, min_midpoint, interval, sort_type, cache, skip_weekends)
HISTORICALPANDL(hist_pandl_array, confidence, start_date, end_date, start_season, end_season,

lambda, current_risk, min_midpoint, interval, sort_type, return_type)
HISTORICALVAR(vol_data, corr_data, hist_data, portfolio, horizon, confidence, home_ccy, start_date,

end_date, start_season, end_season, return_filter, lambda, effective_date, asset_codes, tail_quantile,
mtm_pv, min_midpoint, interval, cache, skip_weekends)
INCREMENTALVAR(candidate_map_array, vardelta_array)
LOADMARKETDATA(vol_data, corr_data, asset_codes, yield_curves, exchange_rates, smile_curves,

effective_date, max_datasets)
MARGINALVAR(maturity_list, asset_list, vardelta_array, vol_data, corr_data, candidate_trade,

home_ccy, effective_date, preserve_var, pv, cross_corrs, asset_codes)
PORTVARANL(vol_data, corr_data, portfolio, horizon, confidence, home_ccy, effective_date,

preserve_var, pv, cross_corrs, asset_codes, yield_curves, exchange_rates)
ROLLINGWINDOWVAR(hist_pandl_array, confidence, start_date, end_date, start_season, end_season,

lambda, rolling_window, method, tail_quantile)
SDATA(vol_data, corr_data, stress_data, vertex, use_file_drivers, driver, asset_codes, sort_type)
SIMBACKTEST(hist_pandl_array, tail_to_test, start_date, end_date, start_season, end_season, lambda,

rolling_window, method, return_type)
STRESSTEST(vol_data, corr_data, stress_data, portfolio, home_ccy, use_file_drivers, driver,

effective_date, asset_codes, sort_type)
VARANL(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence, home_ccy,

pv, cross_corrs, asset_codes, yield_curves)
VARANLU(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence,

home_ccy, pv, asset_codes, yield_curves)
VARCARLO(vol_data, corr_data, portfolio, horizon, confidence, home_ccy, effective_date, cross_corrs,

asset_codes, iterations, seed, distribution, drift, pv_flag, no_analytic_limit, min_midpoint, interval)
VARCOMPARE(confidence, scenario_files, scenario_weights, out_choice, min_max_bins)
VARDELTA(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence,

home_ccy, pv, cross_corrs, asset_codes, yield_curves)
VCDATA(vol_data, corr_data, vertex, vertex2, value, confidence, home_ccy, cross_corrs, asset_codes)
VWVERSION(verbose)
This function performs several statistical tests based on P&L, VaR and ETL time series. For example, users
can take the output from ROLLINGWINDOWVAR and perform backtests based on those calculations or
they could perform backtests on any other data in a similar format. The tests are intended to evaluate the
accuracy of the VaR model used.
backtests.xls
BACKTEST(data_array, confidence, start_date, end_date, start_season, end_season)
data_array is an N x 6 excel range, which contains 6 columns of data arranged as follows:

 The first column contains dates. This column could be empty (but should nevertheless be
input). If If dates are empty it is assumed that the P&L values are sorted chronologically from
the earliest to the most recent.
 The second column contains the historical P&L values against which the predicted values of
VaR, ETL, Profit VaR and Tail Gain are compared. If this column is omitted, no tests are
performed. P&L units are arbitrary (e.g. returns or absolute P&L changes), and the output
units are the same as those of the input. This column must not be empty.
 The third and forth columns contains VaR and ETL values respectively (represented as
negative numbers).
 The fifth and sixth columns contain Profit VaR and ETG values respectively.
All columns except the 2nd (P&L) could be empty. However, with no VaR values, no tests on VaR are
performed and with no Profit VaR values, no tests on Profit VaR are performed.
Note, that the data_array input is of the same format as the output of ROLLINGWINDOWVAR.
Thus BACKTEST could be used to test VaR, ETL, Profit VaR and ETG values obtained using one of the
methodologies provided by ROLLINGWINDOWVAR or by any other user-supplied methodology.
confidence is a number between 0 and 1 specifying the size of the VaR (Profit VaR) confidence level. For a
probability level of x, approximately 1 – x percent (x percent) of the losses (gains) should exceed the
resulting VaR. The default value of confidence is 0.95 and the VaR horizon is arbitrary.
start_date is the first historical observation date for which P&L values will be used. The range of historical
P&L data used falls within the window defined by start_date and end_date, inclusive of these dates. If
omitted, loading of the historical P&L data begins with the earliest date detected. If the date column in
date_array is empty, start_date is ignored.
end_date is the last historical date for which P&L values will be used. The range of historical P&L data used
falls within the window defined by start_date and end_date, inclusive of these dates. If omitted, loading of
the historical P&L data ends with the last date detected. If the date column in date_array is empty, end_date
is ignored.
start_season is a date whose month and day-of-month indicate the start of a season window. The range in
hist_pandl_array should contain the data that falls within the window defined by start_season and end_season,
inclusive of these dates. Note that the year of the start_season date is ignored. If omitted, loading of
historical P&L data begins with January 1st. If the date column in date_array is empty, start_season is
ignored.
end_season is a date whose month and day-of-month indicate the end of a season window. The range in
inclusive of these dates. Note that the year of the end_season date is ignored. If omitted, loading of historical
P&L data ends with December 31st. If the date column in date_array is empty, end_season is ignored.
BACKTEST returns the following results.
N
Total number of data points.
Loss Exceptions, Gain Exceptions

The number of times the P&L value is below –VaR or is above Profit VaR respectively.
K_P_loss
The estimated P-value of the frequency-of-tail-losses (Kupiec’s) test (see Dowd, 2002-1, Chapter 10.2.1). This
value is the probability that we would observe the number of Loss Exceptions or more in the data of size N
under the null hypothesis that the VaR model is good.
K_P_lb_loss
The lower bound of the 95% confidence interval for the value of K_P_loss. This value is obtained by
performing bootstrapping (see Dowd, 2002-2).
K_P_ub_loss
The upper bound of the 95% confidence interval for the value of K_P_loss. This value is obtained by
performing bootstrapping (see Dowd, 2002-2).
K_crit_5_loss
The minimum number of loss exceptions that would have to be present in the data of size N in order for the
null hypothesis to be rejected at the 5% significance level.
K_crit_1_loss
The minimum number of loss exceptions that would have to be present in the data of size N in order for the
null hypothesis to be rejected at the 1% significance level.
K_P_gain, K_P_lb_gain, K_P_ub_gain, K_crit_5_gain, K_crit_1_gain

Similar statistics for Kupiec test on the profit tail.
C_loss
The estimated value of the conditional-coverage (Christoffersen’s) test statistic for the loss tail (see
Christoffersen, 2002, Chapter 8.2.4). This value is the likelihood ratio of the hypothesis that the loss
exceptions are serially correlated and the null hypothesis (that the VaR model is good and the loss
exceptions are time-independent). For large values of N this statistic is approximately distributed as 2 with
2 degrees of freedom.
C_P_loss
The estimated P-value of the C_loss obtained by bootstrapping (and therefore independent of the
distributional assumptions).
C_lb_loss
The estimated lower bound of the 95% confidence interval for the value of C_loss obtained by
bootstrapping.
C_ub_loss
The estimated upper bound of the 95% confidence interval for the value of C_loss obtained by
bootstrapping.
C_00_loss
The estimated probability of a loss non-exception followed by another loss non-exception in the
Christoffersen’s test.
C_01_loss
The estimated probability of a loss non-exception followed by a loss exception in the Christoffersen’s test.
C_10_loss
The estimated probability of a loss exception followed by a non-exception in the Christoffersen’s test.
C_11_loss
The estimated probability of a loss exception followed by another loss exception in the Christoffersen’s test.
C_gain, C_P_gain, C_lb_gain, C_ub_gain, C_00_gain, C_01_gain, C_10_gain, C_11_gain

Similar statistics for the profit tail
ASD_loss
The Absolute Size Deviation (ASD) function of loss exceptions. See definition below for details.
Ave_dur_loss
The average time (in periods) between successive loss exceptions.
SD_dur_loss
Standard deviation of time between successive loss exceptions.
Ave_exc_dev_loss
Average loss exception deviation from ETL. See definition below for details.
SD_exc_dev_loss
Standard deviation of loss exception deviation from ETL.
ASD_gain, Ave_dur_gain, SD_dur_gain, Ave_exc_dev_gain, SD_exc_dev_gain

Similar statistics for the profit tail
BACKTEST output can be arranged in any number of rows or columns but it is given in the following (row
by row) order (a 9x5 output is provided as an example).
N Loss exc. Gain exc. ASD_loss ASD_gain

Ave. VaR Ave. ETL Ave VaR(+) Ave ETG
K_P_loss K_P_lb_loss K_P_ub_loss K_crit_5_loss K_crit_1_loss
C_loss C_00_loss C_01_loss C_10_loss C_11_loss
C_P_loss C_P_lb_loss C_P_ub_loss Ave_dur_loss SD_dur_loss
K_P_gain K_P_lb_gain K_P_ub_gain K_crit_5_gain K_crit_1_gain
C_gain C_00_gain C_01_gain C_10_gain C_11_gain
C_P_gain C_P_lb_gain C_P_ub_gain Ave_dur_gain SD_dur_gain
Ave_exc_dev_l SD_exc_dev_los Ave_exc_dev_ SD_exc_dev_gain
oss s gain
If not enough output space is provided the output is truncated.
The Absolute Size Deviation (ASD) function is defined as:

1l
ASD =  | Ct  E (Ct ) | ,
l t 1
where l is the number of times an exception occurs. The ASD_loss uses the loss function:
L , ifL t  VaRt
Ct   t .
0, otherwise
Therefore the ASD_loss is effectively measuring the exceptions’ absolute average deviation from their
expected size (ETL) and not their frequencies.
Similarly, Ave_exc_dev_loss measures the exceptions’ average deviation from ETL.
Returns an array containing a portfolio’s cash flow map, converted to the home currency. The array has the
same number of rows as maturity_list and the same number of columns as asset_list. Cash flows are allocated
to vertices preserving either present value and value at risk or present value and duration.
varworks.xls (Cash flow map and Incremental VaR worksheets)
CASHFLOWMAP(maturity_list, asset_list, vol_data, corr_data, portfolio, confidence, home_ccy,

effective_date, preserve_var, pv, cross_corrs, asset_codes, yield_curves, exchange_rates)
maturity_list is an m  1 array containing unique maturity codes. See Codes for a list of maturity codes.
asset_list is a 1  n array containing currency and commodity codes. asset_list must be a proper subset of the
codes listed in asset_codes.
vol_data is text specifying a volatility file, which may include a path.
corr_data is text specifying a correlation file, which may include a path.
portfolio is text specifying a portfolio or trade file, which may include a path.
confidence is a number between 0.5 and 1, exclusive, specifying the size of the VaR confidence level. For a
probability level of x, about 1 – x percent of the losses during the horizon period should exceed the resulting
VaR.
home_ccy is text specifying the accounting currency to convert results to. Volatilities and correlations are
automatically rebased to this currency for calculations. vol_data must contain home_ccy exchange rates.
effective_date is a date specifying the effective calculation date—zero time compared with the times of the
cash flows. If this argument is omitted then the system date (today) is used.
preserve_var is a number specifying how to allocate a cash flow to adjacent vertices.
preserve_var Description
TRUE or 1 Present value and VaR are preserved (this is the RiskMetrics-compliant
allocation).
FALSE or 0 Present value and duration are preserved (the vertex set is restricted to the
vertices defined in vol_data).
2 Present value is preserved. For commodity cashflows allocation is done on the
vertex whose tenor immediately precedes the tenor of the cashflow; for other
cashflows duration is preserved.
vertex whose tenor immediately follows the tenor of the cashflow; for other
pv is a logical value specifying the valuation time of the returned cash flows.
pv Cash flow valuation

TRUE or omitted Present values.
FALSE Future values.
cross_corrs is a logical value specifying whether the corr_data correlations are changed to zero across asset
classes. The asset classes are foreign exchange (asset class code XS), interest rates (R, S, Z, AGY, AAA, AA,
A, BBB, BB, B, CCC, D), equities (SE), commodities (C), and Brady bonds (G). Intra-asset class correlations
are not changed. For example, if cross_corrs is FALSE then the (inter-asset class) correlation between Hong
Kong equities and U.S. interest rates is changed to zero but the (intra-asset class) correlation between Hong
Kong equities and U.S. equities is not.
cross_corrs Cross asset-class correlations in corr_data

TRUE or omitted Are not changed.
FALSE Are changed to zero.
asset_codes is text specifying an asset codes file, which may include a path. The currency and commodity
codes in vol_data and corr_data must be a proper subset of the codes listed in asset_codes. If asset_codes is
omitted then a default set of currency and commodity codes is used. Omit this argument if you are using a
RiskMetrics dataset; include it if you are using a MakeVC or custom dataset. See Assets for more
information.
yield_curves is text specifying a yield curve file, which may include a path. If yield_curves is specified then
the interest rates in yield_curves are used in calculations instead of the interest rates in vol_data.
exchange_rates is text specifying an exchange rate file, which may include a path. If exchange_rates is
specified then the exchange rates in exchange_rates are used in calculations instead of the exchange rates in
vol_data.
Formulas that return arrays must be entered as array formulas. For information about arrays, see Array
Formulas or Microsoft Excel Help.
We recommend you always omit yield_curves and exchange_rates to use rates consistent with those used to
calculate the volatilities and correlations.
If a cash flow occurs before the shortest vertex or after the longest vertex then the entire cash flow is
allocated to the nearest vertex and only present value is preserved.
See Cash Flow Mapping for more information.
An error value is returned if any of the following conditions is TRUE:

 Any files are not found, are invalid, or contain errors.
 You do not have read permission for all of the files.
 confidence  0.5.
 confidence  1.
 home_ccy is blank or contains an invalid currency code.
 effective_date contains an invalid date.
 pv, or cross_corrs do not evaluate to TRUE or FALSE.
Returns an array containing the maturity_list, asset_list, or vertex_list, used by other VaRworks functions. The
output list corresponds to a user specified portfolio, or to the volatility/correlation data files. It can also
return an Nx2 array containing vertices and corresponding cashflows.
varworks.xls (Inputs worksheet)
CFDATA(vol_data, corr_data, value, home_ccy, portfolio, effective_date, preserve_var, pv, cross_corrs,

asset_codes, display_flag)
value is text specifying whether to return the asset_list, maturity_list, or vertex_list.
value Array returned

‚a‛ CFDATA returns the asset list corresponding to portfolio. If portfolio is omitted,
the asset list returned correspond to the volatility/correlation data files,
vol_data and corr_data.
‚m‛ or ‚c‛ CFDATA returns the maturity list corresponding to portfolio. If portfolio is
omitted, the maturity list returned correspond to the volatility/correlation data
files, vol_data and corr_data.
‚v‛ or ‚f‛ CFDATA returns the vertex list corresponding to portfolio. If portfolio is
omitted, the vertex list returned correspond to the volatility/correlation data
files, vol_data and corr_data.
portfolio is text specifying a portfolio or trade file, which may include a path. If omitted output list refer to
the volatility/correlation data files.
preserve_var is a number specifying how to allocate a cash flow to adjacent vertices.
allocation).


information.
display_flag is a number specifying whether to use alternative identifiers, when displaying information
about equity vertices. If zero or omitted, the asset_code specified in the asset file is used. If display_flag=1, the
alternative descriptive name specified in the asset file in the field beginning with the string ‚NAME=‛ is
used. If display_flag=2, the ticker string specified in the asset file in the field beginning with the string
‚TICKER=‛ is used.
The main purpose of CFDATA is to provide the user with access to the lists of assets, credit-class/maturities,
and vertices that are employed by many of the VaRworks functions. In addition, CFDATA also provides a
different interface for generating a portfolio’s cash flow map (see CASHFLOWMAP) without the user
having to specify a maturity and asset list. CFDATA returns the following values:
NumberStrings
The number of strings retrieved.
Strings
The set of strings corresponding to the choice of output specified via the value input. If the array size is Nx2,
the string always correspond to a full vertex name.
CashFlowMap
The set of cash flows, corresponding to each vertex for which exposure is detected.
Array size Array contents
Nx1 NumberStrings
String(1)
String (2)
...
String (N-1)
Nx2 NumberStrings
Vertex(1) CashFlowMap (1)
Vertex (2) CashFlowMap (2)
< ...
Vertex (N-1) CashFlowMap (N-1)
Returns the cash flow-based Component VaR array of a portfolio, expressed in home currency or percentage
(VaRbeta) terms.
varworks.xls (Component VaR worksheet)
COMPONENTVAR(cash_flow_array, vardelta_array, as_cash_flows)
cash_flow_array is an array specifying the portfolio’s cash flow map. You can use the result of
CASHFLOWMAP. cash_flow_array must have the same number of rows and columns as vardelta_array.
vardelta_array is an array specifying the portfolio’s VaRdelta values. You can use the result of VARDELTA.
cash_flow_array must have the same number of rows and columns as vardelta_array.
as_cash_flows is a logical value specifying whether results are expressed in home currency units (cash flows)
or as percentages (VaRbeta).
as_cash_flows Results are expressed in

TRUE or omitted Home currency units (in millions). The home currency is the currency that the
cash_flow_array cash flows are expressed in.
FALSE Percent terms. The elements of the returned array sum to one, for example, 5%
is returned as 0.05, not 5.0. This is the portfolio’s VaRbeta.
COMPONENTVAR performs a matrix block-multiplication on its array arguments, that is,

component_var_array ij = cash_flow_arrayij  vardelta_arrayij. If as_cash_flows is FALSE then each element of
component_var_array is divided by the sum of elements of component_var_array.
See Component VaR for more information.

 cash_flow_array and vardelta_array have unequal dimensions.
 cash_flow_array or vardelta_array contains non-numeric entries.
 as_cash_flows does not evaluate to TRUE or FALSE.
Given a portfolio specified in terms of user defined subportfolios, COMPONENTVAR2 returns the
component VaR of a particular subportfolio, an array of values corresponding to the component VaRs for all
the subportfolios specified in the portfolio file, or the VaR of a particular subportfolio. COMPONENTVAR2
supports parametric, Monte Carlo (VaR, Shortfall, and PFE), and Historical methodologies; it requires
specific files, generated by VARCARLO2, HISTORICALVAR, and PORTVARANL, for its analysis.
COMPONENTVAR2(portfolio, subportfolio, confidence, method, as_cash_flows)
portfolio is text specifying the name of the portfolio file for which the component VaR analysis is performed.
See page 227 for how to specify a portfolio file. If omitted, subportfolio must be specified, and
COMPONENTVAR2 returns the VaR of subportfolio.
subportfolio is text specifying the name of the subportfolio for which the Component VaR is going to be
computed. If omitted COMPONENTVAR2 returns an array giving the component VaR decomposition for
all the subportfolios specified in the portfolio input. If omitted, portfolio must be specified.
confidence is a number between 0 and 1, exclusive, specifying the size of the VaR confidence level. For a
confidence level of x greater than 0.5 (less than 0.5), about 1 – x percent (x percent) of the losses (gains)
during the horizon period should exceed the resulting VaR.
method is text specifying which methodology should be used.

method Explanation
‚an‛ Compute component VaR using parametric methodology. The files xxx_an.txt
and yyy_an.txt (xxx and yyy are the names of portfolio and subportfolio input
files respectively) are needed for the analysis; they are generated by
PORTVARANL (with aggregate_flag equal to TRUE).
‚mc‛ Compute component VaR using Monte Carlo methodology. The files
xxx_mc.txt and yyy_mc.txt (xxx and yyy are the names of portfolio and
subportfolio input files respectively) are needed for the analysis; they are
generated by VARCARLO2 (with aggregate_flag equal to TRUE, and pv_flag ≠
-1).
‚hs‛ Compute component VaR using Historical methodology. The files xxx_hs.txt
and yyy_hs.txt (xxx and yyy are the names of portfolio and subportfolio input
files respectively) are needed for the analysis; they are generated by
HISTORICALVAR (with aggregate_flag equal to TRUE).
‚es‛ Compute component Shortfall using Monte Carlo methodology. The files
generated by VARCARLO2 (with aggregate_flag equal to TRUE, and pv_flag ≠
-1).
‚pfe‛ Compute component PFE using Monte Carlo methodology. The files
generated by VARCARLO2 (with aggregate_flag equal to TRUE, and pv_flag =
-1).
‚mcw‛ Compute component VaR using Monte Carlo methodology. Unlike the case
where method = ‚mc‛, the file xxx_mc.txt (xxx is the name of portfolio input) is
not required, but it is instead created by COMPONENTVAR2. When used in
this mode, subportfolio should be omitted, and the yyy_mc.txt files
corresponding to every subportfolio specified in portfolio are required.
‚hsw‛ Compute component VaR using Historical methodology. Similar to ‚mcw‛,
but xxx_hs.txt file is generated.
‚pfew‛ Compute component PFE using Monte Carlo methodology. Similar to ‚mcw‛,
but xxx_pfe.txt file is generated.
as_cash_flows is a logical value specifying whether results are expressed in home currency units (the same
as used for P&L’s) or in percentages of overall VaR (or Shortfall for method= ‚es‛).
COMPONENTVAR2 relies on the existence of multiple files containing P&L information for each Monte
Carlo or historical scenario, or cashflows for analytic VaR decomposition, for the overall portfolio, specified
by the portfolio input, and for each subportfolio specified in the portfolio input. See PORTVARANL,
VARCARLO2 and HISTORICALVAR functions for the convention on the naming of the files, and their
format, and for information on how to generate these files using the aggregate_flag input set equal to
TRUE. Note that the files for simulation methodologies must be created with the same number of iterations
and the same seed, otherwise an error will be generated.
When output files are generated using the ‚mcw‛, ‚hsw‛, or ‚pfew‛ methods, the files contain header lines
providing information about methodology and number of data lines; each data line contains a comma
separated record specifying each subportfolio file and the corresponding component VaR (or PFE if method
= ‚pfew‛).
A specific implementation of the functionality provided by COMPONENTVAR2 is available through the

RiskAnalyst interface, in the VarAnalysis.xls template.
Returns the VaR and Shortfall Risk of an input P&L distribution tail using Extreme-Value Theory, including
error bounds and regression-fitted Generalized Pareto distribution parameters, which are intermediate
results of the calculation. Output of HISTORICALVAR can be used to form the input P&L distribution tail.
Note that the Generalized Pareto distribution parameters corresponding to the tails of an historical return
distribution can also be computed, and output in flat file format, with the HISTORICALVAR function.
varworks.xls (Extreme-Value Theory worksheet)
EXTREMEVALUE(tail_array, total_points, var_quantile, error_conf, tail_points, tail_quantile)
tail_array is a range of numbers corresponding to the profits or losses of the tail of a P&L distribution. If
defining a loss (profit) tail, tail_array should be sorted top-to-bottom or left-to-right in the order of largest to
smallest loss (profit). The range need not be of size equal to total_points, but it must contain the tail threshold
value implied by tail_points, or equivalently, tail_quantile.
total_points is a number specifying the total of points in the P&L distribution of which tail_array is a subset.
var_quantile is a number greater than 0 and less than 1 specifying the size of the VaR confidence level. (This
is analogous to the confidence interval used as input to HISTORICALVAR.) (Note that if tail_array contains
losses, tail_quantile cannot exceed var_quantile; if tail_array contains profits, var_quantile cannot exceed
tail_quantile.) Specify a number close to one if you are analyzing a loss tail_array, a number close to zero if
you are analyzing a profit tail_array.
error_conf is a number between 0 and 1 specifying the confidence interval for the fit of the P&L distribution
tail to a Generalized Pareto distribution. All error estimates are a function of error_conf.
tail_points is a number corresponding to the index of tail_array that defines the threshold (or start) value of
the P&L distribution tail. If specified, tail_array must be a range of numbers of size tail_points or more;
tail_quantile is then calculated from tail_points and total_points. If omitted, tail_quantile must be specified.
tail_quantile is a number greater than 0 and less than 1 specifying the percentile of the threshold (or start)
value of the P&L distribution tail. If specified (and tail_points is omitted), tail_array must contain the point
corresponding to the tail_quantile percentile; tail_points is then calculated from tail_quantile and total_points.
If omitted, tail_points must be specified. Specify a number close to one if you are analyzing a loss tail_array, a
number close to zero if you are analyzing a profit tail_array. (If tail_points is specified, the input value for
tail_quantile is ignored.)
The tail must be input as an array of profits or losses, and it must be sorted from most extreme
value to least extreme value. The tail must include the threshold value, as implied by tail_points or
tail_quantile. (Note that if you input both tail_points and tail_quantile, the input value for tail_quantile
is ignored, and tail_quantile is recalculated for consistency with the input for tail_points. The
consistent values for tail_points and tail_quantile are output to the return array, as described below.)
If tail_array corresponds to a loss tail, then tail_quantile cannot exceed var_quantile. Similarly, if tail_array
corresponds to a profit tail, var_quantile cannot exceed tail_quantile. The reason for this is that
EXTREMEVALUE only uses the tail information you input directly, and no information can be extracted for
a quantile region for which no data was input.
Regression analysis is used to fit the tail to a Generalized Pareto distribution—a minimization of the
variance of
log1  Gx; ,     log 1  x /  

1

where G(x;,) is a Generalized Pareto distribution, parametrized by ,> 0, and x is an excess of profit or
loss, above that of the tail threshold value. The fit is applied to points of the tail corresponding to non-
negative excess values. Our analysis strictly follows that described in the second section of McNeil (1999).
Outputs to the return array that are interpretable as currency values are denominated in the units of the
profits and losses of the input tail_array.
EXTREMEVALUE returns the following values:
VaR
The Extreme-Value-Theory estimate of the Value at Risk (in units equivalent to those of tail_array). This
value depends on your choice of tail_array, var_quantile, error_conf, and tail_points/tail_quantile.
VaR Lower Bound

The estimate of the lower-bound value of the Extreme-Value VaR (in units equivalent to those of tail_array).
This value depends on your choice of tail_array, var_quantile, error_conf, and tail_points/tail_quantile.
VaR Upper Bound

The estimate of the upper-bound value of the Extreme-Value VaR (in units equivalent to those of tail_array).
This value depends on your choice of tail_array, var_quantile, error_conf, and tail_points/tail_quantile.
Shortfall(VaR)
The Extreme-Value-Theory estimate of the Shortfall Risk (in units equivalent to those of tail_array). The
Shortfall is a measure of the fatness of the loss (or profit) tail of the P&L distribution. This value depends on
your choice of tail_array, var_quantile, error_conf, and tail_points/tail_quantile.
Shortfall Lower Bound

The estimate of the lower-bound value of the Extreme-Value Shortfall Risk (in units equivalent to those of
tail_array). This value depends on your choice of tail_array, var_quantile, error_conf, and
tail_points/tail_quantile.
Shortfall Upper Bound

The estimate of the upper-bound value of the Extreme-Value Shortfall Risk (in units equivalent to those of
tail_array). This value depends on your choice of tail_array, var_quantile, error_conf, and
Generalized Pareto Distribution  Parameter

The  parameter of the Generalized Pareto distribution, as obtained via a regression fit to the P&L
distribution tail. This value depends on your choice of tail_array and tail_points/tail_quantile.
Generalized Pareto Lower Bound

The estimate of the lower-bound value on . This value depends on your choice of tail_array, error_conf, and
Generalized Pareto Upper Bound

The estimate of the upper-bound value on . This value depends on your choice of tail_array, error_conf, and
Generalized Pareto Distribution  Parameter

The  parameter of the Generalized Pareto distribution, as obtained via a regression fit to the P&L
distribution tail. This value depends on your choice of tail_array and tail_points/tail_quantile.
Generalized Pareto Lower Bound

The estimate of the lower-bound value on . This value depends on your choice of tail_array, error_conf, and
Generalized Pareto Upper Bound

The estimate of the upper-bound value on . This value depends on your choice of tail_array, error_conf, and
Total Points
This is simply the return of total_points. This value depends on your choice of total_points.
Tail Points
This is the return of tail_points—the value specified as input, or the value calculated from tail_quantile. This
value depends on your choice of total_points or tail_quantile.
Tail Quantile
This is the return of tail_quantile—the value specified as input, or the value calculated from tail_points. This
value depends on your choice of total_points or tail_quantile.
The return array is of the form:
5x3 VaR VaR Lower VaR Upper

Bound Bound
Shortfall(VaR) Shortfall Lower Shortfall Upper
Bound Bound
Pareto Pareto  Lower Pareto  Upper
Bound Bound
Pareto Pareto  Lower Pareto  Upper
Bound Bound
Total-points Tail-points Tail-quantile
 tail_array is not sorted properly.

 total_points < 1.
 var_quantile  0.
 var_quantile  1.
 error_conf  0.
 error_conf  1.
 tail_points < 1.
 tail_points > total_points.
 There is no value in tail_array corresponding to tail_points.
 tail_quantile < 0.
 tail_quantile  1.
 There is no value in tail_array corresponding to tail_quantile.
Retrieves a set of historical returns, corresponding to a specific vertex, from the current cache of historical
data. The user has the choice of viewing the returns, the histogram of the returns, the historically simulated
prices and rates corresponding to those returns, or the historically realized prices and rates.
varworks.xls (Historical VaR worksheet)
HDATA(vol_data, corr_data, hist_data, vertex, horizon, start_date, end_date, start_season, end_season,

return_filter, asset_codes, min_midpoint, interval, return_type, cache, skip_weekends)
hist_data is text specifying a historical data file, or a file containing a list of historical data files, which may
include a path. See Historical Data for more details. (A change in the hist_data input always forces the
existing historical data cache to be freed; the historical data of the new hist_data is then loaded.)
vertex is text specifying the asset, asset class, and maturity in the format asset.asset_class[maturity] where
asset is a currency or commodity code and asset_class[maturity] is an asset class code and maturity (where
applicable). Examples: ‚GAS.C12‛, ‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛.
horizon is a number specifying the horizon (in days) between returns of the historical time series
corresponding to vertex. The horizon is an integer greater than or equal to one; if horizon is not passed as an
integer then it is truncated. (A change in this input can force a reload of historical data if cache was set to
FALSE in the previous call.)
start_date is the first historical observation date for which price returns will be used. The files of hist_data
should contain historical data that falls within the window defined by start_date and end_date, inclusive of
these dates. If omitted, loading of a given historical data series from hist_data begins with the first
observation date detected. (A change in this input can force a reload of historical data if cache was set to
end_date is the last historical date for which price returns will be used The files of hist_data should contain
historical data that falls within the window defined by start_date and end_date, inclusive of these dates. Note
that end_date must not precede start_date. If omitted, loading of a given historical data series from hist_data
ends with the last observation date detected. (A change in this input can force a reload of historical data if
cache was set to FALSE in the previous call.)
start_season is a date whose month and day-of-month indicate the start of a season window. The files of
hist_data should contain historical data that falls within the window defined by start_season and end_season,
inclusive of these dates. Note that the year of the start_season date is ignored. If omitted, loading of a given
historical data series from hist_data begins with 1 January. (A change in this input can force a reload of
historical data if cache was set to FALSE in the previous call.)
end_season is a date whose month and day-of-month indicate the end of a season window. The files of
inclusive of these dates. Note that the year of the end_season date is ignored. If omitted, loading of a given
historical data series from hist_data ends with 31 December. (A change in this input can force a reload of
return_filter is a positive percent change (corresponding to the absolute value of the return on a given price,
discount factor, or exchange rate) that represents a threshold to be applied to the daily returns of all
historical time series of hist_data. If the next-day return of a given observation date exceeds the threshold,
that particular observation date entry is treated as missing data, i.e., the discarded observation date’s price is
replaced with a value linearly interpolated from the prices of adjacent below-threshold dates. Information
about discarded data is logged in the VaRworks error log as FEA_WARNING_EXPIRED messages. If
return_filter is omitted or zero, no filter is applied to the time series of hist_data. Example: consider
return_filter set to 5%. Within a give time series, suppose a price of 100 is observed on 1 January 2000 and the
next day it is observed to be 90, then the change in price over the one day is -10%. The absolute value of this
change exceeds the threshold of 5%, therefore the entry for 1 January 2000 is replaced with an interpolated
value. (A change in this input can force a reload of historical data if cache was set to FALSE in the previous
call.)
information.
min_midpoint is a number specifying the midpoint of the minimum bin of the returned histogram data. If
you specify min_midpoint and interval, the size of the HDATA formula array range must be large enough to
contain the histogram data, otherwise the histogram data is truncated. If min_midpoint is omitted then
HDATA automatically chooses a minimum midpoint. Note that min_midpoint is ignored if return_type is
specified.
interval is a number specifying the interval between bin midpoints of returned histogram data. If interval is
omitted then HDATA automatically chooses a midpoint interval. Note that interval is ignored if return_type
is specified.
return_type is case-insensitive text input specifying how to display the data retrieved from the historical
data cache. If invalid text is entered, an error is generated. Allowed return_type values are specified below.
Value Description
H or omitted Historical returns/prices are not retrieved; instead, a histogram of the
returns is retrieved.
N Depending on the size of the return range, dates, returns, prices or rates,
rolling volatilities can be generated, sorted by observation date. See below
for details.
A Depending on the size of the return range, dates, returns, prices or rates,
rolling volatilities can be generated, sorted in ascending order, from
smallest to largest return. See below for details.
D Depending on the size of the return range, dates, returns, prices or rates,
rolling volatilities can be generated, sorted in descending order, from
largest to smallest return.
NSP Dates and historically simulated price or rates are generated, sorted by
observation date.
NRP Dates and historically realized price or rates are generated, sorted by
observation date.
NV Dates and rolling volatilities are generated, sorted by observation date.
S Summary statistics on the vertex is generated. See below for details.
cache is a logical value specifying how historical data should be cached internally. This input can be used to
control the frequency with which historical data is loaded or reloaded from the files of hist_data, a major
component of calculation time. Set cache TRUE if memory permits and computation time is an issue. (A
change in this input always forces a reload of historical data.)
cache Caching behavior

FALSE or omitted Loads only enough historical data to perform the calculation specified by the
current inputs. Subsequent calls to HDATA may warrant reloading of
historical files, depending on the nature of changes to inputs.
TRUE Loads all historical data contained in the files of hist_data. Subsequent calls to
HDATA warrant loading of historical files only if hist_data is changed.
skip_weekends is a flag that, if set to TRUE (the default), will cause time series data corresponding to
weekend dates to be ignored.
The purpose of HDATA is to provide the user with access to the historical returns that are employed by
HISTORICALVAR. If HDATA and HISTORICALVAR are called with the same data windows, and the
portfolio of HISTORICALVAR depends on vertex, then the returns of HDATA are those employed by
HISTORICALVAR when it simulates the movements of vertex.
The movements of a vertex used in the historical simulation can be obtained from the output of HDATA in
the following way:
MVt  MV0  1  HRt .
Here, MVt is the simulated value of vertex corresponding to observation date t. The mark-to-market value of
vertex is MV0, which is obtained from vol_data. The historical return is HRt, which corresponds to observation
date t. The set of observation dates is determined by the input values for horizon, start_date, end_date,
start_season, end_season, and return_filter – the data window. The historically simulated price or rate can be
alternatively generated by using the return_type ‘NSP’.
HDATA can also be used to generate historical realized prices for a user specified time period (‘NRP’ return
type). It should be noted, however, that if both prices and returns are specified in the history file, the time
series of realized prices is generated by applying returns, moving backward in time, to the price
corresponding to end_date. Historical realized prices are therefore adjusted for dividends and other corporate
events, if the specified returns have been analogously adjusted, and they might not coincide with the
possibly unadjusted prices specified in the history file.
HDATA employs a caching mechanism to facilitate quick and efficient computation within a spreadsheet
environment. The first call to HDATA initiates caching. Subsequent calls update caching only as required.
The above Syntax description of inputs indicates which arguments can invoke cache updating.
Additionally, caching is updated automatically if the modification times of the files of hist_data have
changed. The user can control the extent of caching via the cache argument; set cache to TRUE if you want to
maximize caching.
HDATA uses linear interpolation to account for missing data within a given time series.
The start_date and end_date inputs can be used to bracket the successive years of historical data. The
start_season and end_season dates can be used to further select data, via season. The return_filter input can be
used to filter anomalous entries of all time series loaded via hist_data.
HDATA returns the following values:

NumberReturns
The number of returns retrieved.
E(Returns)
The expected value (mean) of the set of historical returns of vertex that fall within the specified data window.
(This is output if the input value of return_type is not set.)
SD(Returns)
The standard deviation of the set of historical returns of vertex that fall within the specified data window.
(This is output if the input value of return_type is not set.)
MarketValue
The mark-to-market value of the vertex.
Returns
The set of historical returns, with observation dates, that fall within the data window. If vertex corresponds
to an interest rate, change in rates are generated instead (a change of 1% is output as 0.01).
PriceOrRate
The set of prices or rates, with observation dates, that fall within the data window. For interest rate vertices,
the rate, not the discount factor, is generated. If result_type is equal to ‘N’ or ‘NSP’ the simulated historical
price or rate is generated, if result_type is equal to ‘NRP’ the realized (adjusted) historical price or rate is
generated instead, see remark above.
Rolling volatilities
The set of rolling volatilities, with observation dates, that fall within the data window. Rolling volatilities are
computed by using the last available twenty returns. Note that in the case of interest rates the volatilities are
expressed in absolute (not percentage) terms, i.e. a rolling volatility of 0.005 (50bp), means that the rate has a
1-sigma chance of changing by 50bp, not by 0.5% of its current value.
Summary statistics
For the selected vertex, the following information can be displayed when return_type = ‘S’ is used:
First valid date for which historical data is provided

Last valid date for which historical data is provided
Number of valid dates for which data is provided
Number of valid dates for which data is missing, and interpolation is used
Number of valid dates for which the provided data is equal to the prior date data
Minimum realized price
Maximum realized price
Mean realized price
Minimum return
Maximum return
Mean return
Return standard deviation
Return skewness
Return kurtosis
Note that if skip_weekend=TRUE, weekend dates are not considered as valid dates.
Midpoints
HDATA creates a set of evenly-distributed bins between the minimum and maximum values of historical-
return distribution. (You can control the histogram with the min_midpoint and interval arguments.) Data in
this form can be easily charted as a histogram. Bins are defined by boundary values in ascending order. The
values of the bin midpoints are determined by the total number of bins (specified by the size of the
formula’s array range) and by the minimum and maximum values generated by the simulation. A data
point is counted in a particular bin if it is greater than the bin’s lower boundary value and less or equal to a
bin’s upper boundary value. All values below the first bin’s lower boundary value are counted in the first
bin. Each bin is marked by a midpoint (the portfolio P&L in millions of home currency units) and a
corresponding frequency of data points falling in that bin. (This is the chief output if the input value of
return_type is not set.)
Frequencies
The number of occurrences of the returns falling within the bin located at the corresponding midpoint. The
sum of all the frequencies equals the total number of returns in the data window. (This is the chief output if
the input value of return_type is not set.)
HDATA outputs several basic types of return arrays, which can be transposed. The output format depends
on the specification of return_type and the size of the array range entered.
If return_type is ‘H’ or not set, then
1x1 NumberReturns
1x2 NumberReturns E(Returns)
2x2 NumberReturns E(Returns)

SD(Returns) MarketValue
Nx2 NumberReturns E(Returns)

(N > 2) SD(Returns) MarketValue
Midpoint(1) Frequency(1)
... ...
Midpoint(N-2) Frequency(N-2)
If return_type is set to ‘N’, ‘A’, or ‘D’, then
1x1 MarketValue
Nx1 MarketValue
Return(1)
Return (2)
...
Return (N-1)
Nx2 NumberReturns MarketValue

(N > 1) Obs-date(1) Return (1)
Obs-date(2) Return (2)
... ...
Obs-date(N-1) Return (N-1)

(N > 2) Obs-date(1) Return (1) PriceOrRate(1)

Obs-date(2) Return (2) PriceOrRate (2)
... ... ...
Obs-date(N-1) Return (N-1) PriceOrRate (N-1)

(N > 3) Obs-date(1) Return (1) PriceOrRate (1) Rolling Vol(1)
Obs-date(2) Return (2) PriceOrRate (2) Rolling Vol (2)
... ... ... ...
Obs-date(N-1) Return (N-1) PriceOrRate (N-1) Rolling Vol (N-
1)
If return_type is set to ‘NSP’, ‘NRP’, or ‘NV’ then
Array size Array content
Nx1 Price or Vol (1)

Price or Vol (2)
...
Price or Vol (N)
Nx2 Obs-date(1) Price or Vol (1)

Obs-date(2) Price or Vol (2)
... ...
Obs-date(N) Price or Vol (N)
where, Price or Vol is either the simulated price or rate (return_type=‘NSP’), the realized price or rate
(return_type=‘ ‘NRP’), or the rolling volatility (return_type=‘NV’).
If return_type is set to ‘S’, and an N x1 output array is specified, then the first N summary statistics specified
above are generated.

 No historical data found within specified window constraints.
 No historical data found for market factor on which portfolio depends.
 horizon < 1.
 end_date > start_date.
This function takes an array of historical profit and loss (P&L) values and (optionally) associated dates, risk
measures and probabilities (see descriptions of the inputs below) and computes VaR, Expected Tail Loss
(ETL) and other risk measures for a given confidence level, as well as several other statistics of the historical
P&L distribution (including a histogram).
backests.xls
HISTORICALPANDL(hist_pandl_array, confidence, start_date, end_date, start_season, end_season,

lambda, current_risk, min_midpoint, interval, sort_type, return_type)
hist_pandl_array is an NxM excel range, which contains M columns of historical P&L data where 2<=M<=4
(that is at least 2 columns must be present). The data must be arranged as follows:
input). If dates are empty it is assumed that the P&L values are sorted chronologically from
 The second column contains the historical P&L values; units are arbitrary (e.g. returns or
absolute P&L changes), and the output units are the same as those of the input. This column
must not be empty.
 The third column contains risk measures (used for P&L adjustments, see description of
current_risk below). The values in this column, if present, must be nonnegative. These are
used to adjust the P&L values according to the value of current_risk (see below). If omitted, no
adjustment is made.
 The forth column contains probabilities assigned to each P&L scenario. If specified,
probabilities are used to weight the P&L values. The probabilities have to be nonnegative, but
they do not have to sum to one as normalization is always performed. If probabilities are
omitted, the data is weighted according to the value of lambda (see below).
Columns three and four could be empty or omitted .
confidence is a number between 0 and 1 specifying the size of the VaR confidence level. For a probability
level of x, approximately 1 – x percent (x percent) of the losses (gains) should exceed the resulting VaR. The
default value of confidence is 0.95 and the VaR horizon is arbitrary.
hist_pandl_array is empty, start_date is ignored.
the historical P&L data ends with the last date detected. If the date column in hist_pandl_array is empty,
end_date is ignored.
historical P&L data begins with January 1st. If the date column in hist_pandl_array is empty, start_season is
ignored.
P&L data begins with 31 December. If the date column in hist_pandl_array is empty, end_season is ignored.
lambda is a fractional value, greater than or equal to zero and less than or equal to one, that parameterizes a
weighted averaging scheme applicable to the P&L values. If a nonzero value of lambda is present, the
weight column of hist_pandl_array is ignored and the values are weighted according to lambda. lambda
equal to 1 leads to equal weighting. The default value is zero – lambda-based weighting is not performed.
(See below for more details.)
current_risk is a positive value that reflects the current risk level. If both current_risk and the risk measures
in the 3rd column of hist_pandl_data are specified, the P&L values are adjusted according to the formula:
adjusted P&L(t) = P&L(t) * current_risk / risk(t), where risk(t) is the risk measure specified for date t.
Otherwise no adjustment is made. The current_risk level must use the same units as the values in the risk
column. If portfolio or asset returns are used in the P&L column, the risk column must contain risk numbers
expressed as returns or implied volatility information, and current_risk should contain the most recent risk
estimate or implied volatility for that portfolio/asset.
min_midpoint is a number that falls within the minimum bin of the returned histogram data. Typically this
is close the midpoint of the minimum bin. If min_midpoint is omitted then HISTORICALPANDL
automatically chooses a minimum midpoint. Note that min_midpoint is ignored if return_type is not ‘H’.
interval is a number specifying the interval between bin midpoints of returned histogram data. If you
specify interval, the size of the output formula array range must be large enough to contain the histogram
data, otherwise the histogram data is truncated. If interval is omitted then HISTORICALPANDL
automatically chooses a midpoint interval. Note that interval is ignored if return_type is not ‘H’.
sort_type is a one-character, case-insensitive text input denoting the type of sorting to be performed on the
set of historical P&L values loaded. The possible values for sort_type are: ‘N’ (sort sequentially by
observation date), ‘A’ (sort returns in ascending order, from smallest to largest return), and ‘D’ (sort returns
in descending order, from largest to smallest return). If invalid text is entered, sort_type ‘N’ is used. If the
return_type is ‘H’, sort_type is not used.
return_type is a one-character, case-insensitive text input denoting the type of output. The possible values
for return_type are: ‘T’ and ‘H’. The return_type determines the type of output of the return array, as
indicated below.
Value Description
T or omitted The entire distribution of loaded P&L data, sorted according to sort_type
together with some distribution statistics, VaR, Shortfall, Gain-VaR, and
Tailgain,
H The diversified VaR, standard error, shortfall risk, and P&L distribution
histogram.
HISTORICALPANDL uses linear interpolation to compute VaR of a given discrete time series.
The start_date and end_date inputs can be used to bracket the successive years of historical P&L data. The
start_season and end_season dates can be used to further filter data, via season. Each of these parameters
tends to reduce the size of the time series.
If lambda is set to a non-zero value, the hybrid approach to weighted averaging of historical returns is used.
(See J. Boudoukh et al.) This approach gives decreasing weight to the historical P&L values. The weights are
dictated by the time series defined by start_date, end_date, start_season and end_season, such that the return
corresponding to the most recent date, edate, has the largest weight. The date edate is either end_date or the
closest date to end_date that does not exceed end_date. If R(edate) is the most recent return realized from N-
member historical data, then to each of the N returns R(edate), R(edate -1), …, R(edate - (N-1)), the weight A x
lambda k-1, where k = 1, 2, …, N is assigned. Here, A = (1 - lambda) / (1 - lambda N) is a normalization factor,
which ensures that the weights sum to one. Note that this weighting of data is turned off if lambda is set to
zero – its default value. Also, setting lambda equal to 1 produces equal weighting.
HISTORICALPANDL returns the following values:
VaR
The diversified historical Value at Risk (VaR), in the same units as the input P&L data, corresponding to
the chosen level of confidence.
Expected Tail Loss (Shortfall)

The expected loss conditional on the occurrence of a loss greater than the VaR. ETL is equal to VaR plus the
average excess with respect to VaR, and is therefore a measure of the fatness of the loss (or profit) tail of the
P&L distribution.
VaR(+), Expected Tail Gain (ETG)

Measures similar to VaR and ETL only for the profit tail.
Points
The total number of historical P&L values loaded.
E(P&L)
The expected value (mean) of the portfolio P&L distribution (in the same units as the input data). This
quantity equals the weighted sum of the portfolio P&Ls where the weights are determined by either the
input probabilities of lambda.
SD(P&L)
The standard deviation of the portfolio P&L distribution (in the same units as the input data).
SE(VaR)
The standard error of the VaR estimate.
Skewness
The skewness of the portfolio P&L distribution (in the same units as the input data).
Kurtosis
The kurtosis of the portfolio P&L distribution (in the same units as the input data).
JBera
The value of the Jarque-Bera statistic of the portfolio P&L distribution. This statistic measures the
normality of the P&L distribution. The test uses the skewness coefficient to determine if the
distribution is symmetric and then measures the kurtosis of the distribution (how fat the tails are).
The Jarque-Bera statistic is then given by the following expression:
 skewness 2 kurtosis  32 
JBera  N   ,
 6 24 
where N is the number of Points. This statistic has a Chi-squared distribution under the null
hypothesis of normality. Note that a symmetric distribution has a skewness equal to zero and the
kurtosis of a normal distribution is three.
Midpoints
HISTORICALPANDL creates a set of evenly distributed bins between the minimum and maximum values
of portfolio P&L distribution. (You can control the histogram with the min_midpoint and interval arguments.)
Data in this form can be easily charted as a histogram. Bins are defined by boundary values in ascending
order. The values of the bin midpoints are determined by the total number of bins (specified by the size of
the formula’s array range) and by the minimum and maximum values loaded. A data point is counted in a
particular bin if it is greater than the bin’s lower boundary value and less or equal to a bin’s upper boundary
value. All values below the first bin’s lower boundary value are counted in the first bin. Each bin is marked
by a midpoint and a corresponding frequency of data points falling in that bin.
Frequencies
The proportion of occurrences of the historical P&Ls values (out of the total number of points) falling in the
bin located at the corresponding midpoint. The sum of all the frequencies equals 1.
HISTORICALPANDL outputs two basic types of return arrays. The output format depends on the
specification of return_type and the size of the output array range entered.
If return_type is ‘T’ or is omitted, the return array is of the form
1x1 VaR
1x2 VaR ETL
1x3 VaR ETL VaR(+)
1x4 VaR ETL VaR(+) ETG
2x1 VaR
E(P&L)
2x2 VaR ETL

E(P&L) SD(P&L)
2x3 VaR ETL VaR(+)

E(P&L) SD(P&L) SE(VaR)
2x4 VaR ETL VaR(+) ETG

E(P&L) SD(P&L) SE(VaR) Points
The above can also be output as a single row with up to 8 columns.
Nx1 VaR
(N>2) E(P&L)
Date(1)
<
Date(N-2)
Nx2 VaR ETL

E(P&L) SD(P&L)
Date(1) Adj. P&L(1)
< <
Date(N-2) Adj .P&L(N-2)
Nx3 VaR Shortfall VaR(+)

E(P&L) SD(P&L) SE(VaR)
Date(1) Adj. P&L(1) P&L(1)
< < <
Date(N-2) Adj .P&L(N-2) P&L(N-2)
Nx4 VaR ETL VaR(+) ETG

E(P&L) SD(P&L) SE(VaR) Points
Date(1) Adj. P&L(1) P&L(1) Prob.(1)

< < < <
Date(N-2) Adj .P&L(N-2) P&L(N-2) Prob(N-2)
If return_type is ‘H’, the return array is of the form shown below. NBins is the total number of bins in the
histogram.
1x2 Points Nbins
2x2 Points Nbins

VaR ETL
3x2 Points Nbins

VaR ETL
VaR(+) ETG
4x2 Points Nbins

VaR ETL
VaR(+) ETG
Skewness Kurtosis
5x2 Points Nbins

VaR ETL
VaR(+) ETG
Skewness Kurtosis
JBera Empty Cell
Nx2 Points Nbins

(N>5) VaR ETL
VaR(+) ETG
Skewness Kurtosis
JBera Empty Cell
... ...
If any of the input arguments is invalid, error values are returned. In this case consult the Error Log for
error messages.
Returns a portfolio’s diversified VaR, its standard error, Shortfall Risk, mark-to-market, distribution
statistics, and raw simulation results, as calculated using historical simulation. All returned results are
reported in the home currency.
varworks.xls (Historical VaR worksheet)

HISTORICALVAR(vol_data, corr_data, hist_data, portfolio, horizon, confidence, home_ccy, start_date,

end_date, start_season, end_season, return_filter, lambda, effective_date, asset_codes, tail_quantile,
mtm_pv, min_midpoint, interval, cache, skip_weekends, file_name, evt_tail, aggregate_flag)
hist_data is text specifying a historical data file, or a file containing a list of historical data files, which may
include a path. See Historical Data for more details. (A change in the hist_data input always forces the
existing historical data cache to be freed; the historical data of the new hist_data is then loaded.)
horizon is a number specifying the portfolio’s unwind period in days. The horizon is an integer greater than
or equal to one; if horizon is not passed as an integer then it is truncated. The resulting VaR is the expected
change in value under adverse circumstances in this time interval. (A change in this input can force a reload
of historical data if cache was set to FALSE in the previous call.)
level of x, approximately 1 – x percent (x percent) of the losses (gains) during the horizon period should
exceed the resulting VaR.
home_ccy is text specifying the currency in which results will be accounted.
start_date is the first historical observation date for which price returns will be used. The files of hist_data
should contain historical data that falls within the window defined by start_date and end_date, inclusive of
these dates. If omitted, loading of a given historical data series from hist_data begins with the first
observation date detected. (A change in this input can force a reload of historical data if cache was set to
end_date is the last historical date for which price returns will be used The files of hist_data should contain
historical data that falls within the window defined by start_date and end_date, inclusive of these dates. Note
that end_date must not precede start_date. If omitted, loading of a given historical data series from hist_data
ends with the last observation date detected. (A change in this input can force a reload of historical data if
cache was set to FALSE in the previous call.)
start_season is a date whose month and day-of-month indicate the start of a season window. The files of
inclusive of these dates. Note that the year of the start_season date is ignored. If omitted, loading of a given
historical data series from hist_data begins with 1 January. (A change in this input can force a reload of
end_season is a date whose month and day-of-month indicate the end of a season window. The files of
inclusive of these dates. Note that the year of the end_season date is ignored. If omitted, loading of a given
historical data series from hist_data ends with 31 December. (A change in this input can force a reload of
return_filter is a positive percent change (corresponding to the absolute value of the return on a given price,
discount factor, or exchange rate) that represents a threshold to be applied to the daily returns of all
historical time series of hist_data. If the next-day return of a given observation date exceeds the threshold,
that particular observation date entry is treated as missing data, i.e., the discarded observation date’s price is
replaced with a value linearly interpolated from the prices of adjacent below-threshold dates. Information
about discarded data is logged in the VaRworks error log as FEA_WARNING_EXPIRED messages. If
return_filter is omitted or zero, no filter is applied to the time series of hist_data. Example: consider
return_filter set to 5%. Within a give time series, suppose a price of 100 is observed on 1 January 2000 and the
next day it is observed to be 90, then the change in price over the one day is -10%. The absolute value of this
change exceeds the threshold of 5%, therefore the entry for 1 January 2000 is replaced with an interpolated
value. (A change in this input can force a reload of historical data if cache was set to FALSE in the previous
call.)
lambda is a fractional value, greater than or equal to zero and less than or equal to one, that parametrizes a
weighted averaging scheme applicable to the price returns (of the profits and losses) of portfolio. The scheme
is a hybrid approach that combines exponential smoothing with the tenets of historical simulation. The
default value is zero – smoothing is not performed. (See below for more details.)
information.
tail_quantile is a number between 0 and 1 specifying the percentile of the threshold (or start) of the P&L
distribution tail. If tail_quantile is greater than or equal to (less than) 0.5 the tail corresponds to the loss-end
(profit-end) of the distribution. The tail_quantile determines the type of output of the return array, as
indicated below. See Remarks for further details.
tail_quantile Output (comprising return array)

0 or omitted The diversified VaR, standard error, shortfall risk, mark-to-market, and P&L
distribution statistics (including histogram) of portfolio, as calculated using
historical simulation.
0.5 The entire P&L distribution of portfolio, as calculated using historical
simulation, sorted according to historical observation date.
< 0.5 The profit tail of the P&L distribution of portfolio, as calculated using historical
simulation, sorted from largest profit to tail_quantile.
> 0.5 The loss tail of the P&L distribution of portfolio, as calculated using historical
simulation, sorted from largest loss to tail_quantile.
mtm_pv is a logical value specifying how the P&L distribution is to be constructed. The historical
simulation constructs the P&L distribution by subtracting the model-estimated MTM price of the portfolio
from the present or future value of the portfolio estimated at the horizon.
mtm_pv Mark-to-market calculation

TRUE or omitted The value of the portfolio, as estimated at the horizon, is discounted by the
prevailing short rate of the home currency before the MTM price is subtracted.
The P&L distribution, constructed in this way, is a comparison between two
model-estimated prices.
FALSE The value of the portfolio, as estimated at the horizon, is not discounted before
the MTM is subtracted. The P&L distribution, constructed in this way, is a
comparison between a model-estimated future value and a model-estimated

MTM price.
you specify min_midpoint and interval, the size of the HISTORICALVAR formula array range must be large
enough to contain the histogram data, otherwise the histogram data is truncated. If min_midpoint is omitted
then HISTORICALVAR automatically chooses a minimum midpoint. Note that min_midpoint is ignored if
tail_quantile is specified.
omitted then HISTORICALVAR automatically chooses a midpoint interval. Note that interval is ignored if
tail_quantile is specified.
cache is a logical value specifying how historical data should be cached internally. This input can be used to
control the frequency with which historical data is loaded or reloaded from the files of hist_data, a major
component of calculation time. Set cache TRUE if memory permits and computation time is an issue. (A
change in this input always forces a reload of historical data.)
cache Caching behavior

FALSE or omitted Loads only enough historical data to perform the calculation specified by the
current inputs. Subsequent calls to HISTORICALVAR may warrant reloading
of historical files, depending on the nature of changes to inputs.
TRUE Loads all historical data contained in the files of hist_data. Subsequent calls to
HISTORICALVAR warrant loading of historical files only if hist_data is
changed.
skip_weekends is a flag that, if set to TRUE (the default), will cause time series data corresponding to
weekend dates to be ignored. Thus, if TRUE or omitted, returns are calculated between Fridays and
Mondays. If FALSE, returns over Saturdays and Sundays are calculated. Caution: Absent weekend dates are
considered to be missing data when skip_weekends is FALSE, and in such instances, weekend returns will be
linearly interpolated, just like any other missing data point.
file_name is text specifying an output file, which may include a path, containing the profit-and-loss (P&L)
distribution of the portfolio. The generated file is of type DISTRIBUTIONDATA. HISTORICALVAR writes
the change in price of the portfolio (in millions of home currency units) for each historical run to file_name.
file_name will contain header lines providing information about methodology and number of data lines (see
iterations below). If the input evt_tail is specified, headers corresponding to the Generalized Pareto
distribution parameters ( and ) obtained by fitting the profit and loss tails, according to Extreme Value
Theory, are also generated. Each line of data contains a comma separated record of a date, the
corresponding P&L, and the weighting factor determined by lambda (see Remarks section below), sorted
by P&L values, from largest loss to largest profit. If no path is specified file_name is created in the current
directory. Each time HISTORICALVAR is executed a new file is created, overwriting the previous one (of
the same name) if it exists. If file_name is omitted then no file is created. If aggregate_flag is set to true, the
name specified by file_name is not used, and a file with name xxx_hs.txt is generated where xxx is the name
of the file specified in the portfolio input, stripped of path and extension. This file is created in the same
folder where the portfolio file resides and it contains unsorted P&L’s, see aggregate_flag below for additional
information.
evt_tail is a number between 0 and 1, exclusive, specifying the percentile defining the P&L distribution tails.
evt_tail determines the loss tail (say 95%), and (1-evt_tail) the profit tail. If specified, and file_name is
specified, the two tails are fitted and the Generalized Pareto distribution parameters are computed and
included in file_name. Also included in file_name is the number of points, derived from evt_tail and the total
number of historical observations, defining the tails.
aggregate_flag is a logical value specifying a different format for the output file being generated (see
file_name above). Note that this input is very useful when one wants to ‚slice and dice‛ portfolio risk
measures along different dimensions. By generating the P&L’s files for all the trades making up a portfolio
separately, and arranging the P&L’s without sorting by dates (by setting aggregate_flag to TRUE) allows one
to build up any subportfolio P&L’s without having to rerun a potentially time consuming calculation. This is
accomplished by aggregating the P&L’s from the generated files corresponding to the trades belonging to
the desired subportfolio.
HISTORICALVAR requires vol_data, corr_data, and asset_codes in order to determine the universe of asset
vertices into which portfolio is projected. In particular, the mark-to-market of portfolio is determined from the
prices, interest rates, and exchange rates contained in vol_data. Asset vertices present in the historical time
series of hist_data must be present in vol_data and corr_data, as well. User-defined asset codes, contained in
asset_codes, are permitted.
HISTORICALVAR employs a caching mechanism to facilitate quick and efficient computation within a
spreadsheet environment. The first call to HISTORICALVAR initiates caching. Subsequent calls update
caching only as required. The above Syntax description of inputs indicates which arguments can invoke
cache updating. Additionally, caching is updated automatically if the modification times of the files of
hist_data have changed. The user can control the extent of caching via the cache argument; set cache to TRUE
if you want to maximize caching.
HISTORICALVAR uses linear interpolation to account for missing data within a given time series.
If the time series of hist_data are not all commensurate, HISTORICALVAR will construct a set of simulated
returns from the intersection of all time series on which portfolio depends. If portfolio depends on two time
series whose sequences of observation dates do not overlap, then the intersection of all portfolio time series
will be empty, historical simulation will be aborted, and an error will be logged.
The start_date and end_date inputs can be used to bracket the successive years of historical data applied to
the VaR simulation. The start_season and end_season dates can be used to further select data, via season. The
return_filter input can be used to filter anomalous entries of all time series loaded via hist_data. Each of these
parameters tends to reduce the intersection of the time series on which portfolio depends.
(See J. Boudoukh et al.) This approach gives decreasing weight to the historical simulated returns of portfolio.
The weights are dictated by the time series of hist_data defined by start_date, end_date, and horizon, such that
the return corresponding to the most recent date, edate, has the largest weight. The difference (in days)
between edate and start_date is an integer multiple of horizon. The date edate is either end_date or the closest
date to end_date that does not exceed end_date. If R(edate) is the most recent return realized from edate –
horizon to edate of an (N+1)-member historical data window, then to each of the N returns R(edate), R(edate -
horizon), …, R(edate - (N-1) x horizon) the weight A x lambda k-1, where k = 1, 2, …, N is assigned. Here, A = (1 -
lambda) / (1 - lambda N) is a normalization factor, which ensures that the weights sum to one. Note that
weighting of returns is turned off if lambda is set to zero – its default value. Also, note that setting lambda to
one produces the same value-at-risk as no weighting.
The tail_quantile input determines the type of return array output by HISTORICALVAR, as described below.
Users who wish to extend their value-at-risk analysis by exploiting Extreme-Value Theory will want to set
tail_quantile appropriately and apply the resulting output to the input of the EXTREMEVALUE function.
If you have specified a long time horizon and HISTORICALVAR returns zero VaR, then a large number of
your trades expire before the horizon. HISTORICALVAR reinvests expired trades as money-making trades,
carrying them to the horizon (from the point of expiration) as zero-coupon bonds. These reinvestments
substantially improved your standing with respect to market risk. Basically, HISTORICALVAR cashes in
your portfolio before the horizon. Expired trade reinvestment is documented in the VaRworks error log.
During the course of a simulation, HISTORICALVAR has the ability to handle simulation events (cash
flows) that intervene before the horizon, such as the pay out of coupons or dividends or the early expiration
of a trade. When these events occur, they are written to your error log as FEA_WARNING_EXPIRED
messages. All positive intervening cash flows are reinvested to the horizon as zero-coupon government
bonds. All negative intervening cash flows are carried to the horizon as losses.
HISTORICALVAR performs historical simulation of market risk by:
1. Estimating the mark-to-market (mark-to-model) value of the input portfolio via the market
information contained in vol_data, corresponding to effective_date;
2. Decomposing portfolio into its underlying market-factor dependencies;
3. Calculating the expected values of these underling assets at the horizon, using price returns
computed from the historical series contained in the files of hist_data.
4. Revaluing portfolio at the horizon; and
5. Constructing a P&L distribution from repeated implementation of steps 3 and 4.
The mtm_pv argument controls the definition of the P&L distribution. To understand the significance of this
factor is to realize the distinction between the future value of your portfolio at the horizon and the concept of
a price. The simulation estimates your portfolio value using underlying market factors moved to the horizon.
Doing so, it is constructing a future value. To attribute a price to this future value, it must be discounted by an
appropriate rate. In HISTORICALVAR, if mtm_pv is TRUE then the distribution is constructed from the
difference between the MTM and the present value of expected future portfolio value at the horizon, using
the prevailing short rate of your home currency. (This is a comparison between two prices.) If mtm_pv is
FALSE then the distribution is constructed from the difference between the MTM and the expected future
value of your portfolio at the horizon. Your choice of mtm_pv will be reflected in the returned VaR since the
VaR is directly computed from the type of distribution you define. Ultimately, your choice of mtm_pv will
depend on your motivation for estimating VaR—one choice for mtm_pv is not necessarily better than the
other!
HISTORICALVAR returns the following values:
VaR
The diversified historical Value at Risk (in millions of home currency units), which depends on your choice
of confidence, tail_quantile, and mtm_pv.
VaR/MTM
VaR as a fraction of the mark-to-market value of the portfolio. Multiply by 100 to convert to a percent. This
value depends on your choice of confidence, tail_quantile, and mtm_pv.
Mark-to-market
The mark-to-market value of the portfolio on effective_date (in millions of home currency units). This value
depends on your choice of tail_quantile.
SE(VaR)
An estimate of the standard error of the historical Value at Risk (in millions of home currency units). This
value depends on your choice of confidence, tail_quantile, and mtm_pv.
Note The standard error SE is analytically estimated assuming the limit of a large P&L sampling—as in the
case of running HISTORICALVAR repeatedly with the input parameters held fixed—wherein the tenets of
the Central Limit Theorem of statistics become applicable. Thus, it is assumed that the P&L approximates a
Gaussian distribution, allowing the VaR to be expressed proportional to the variance (or equivalently,
standard deviation SD) of the distribution. (The constant of proportionality includes the inverse of the
cumulative normal distribution, a function of the confidence level.) The problem reduces to estimating the
standard error in the sampling of a Gaussian variance, which is an exercise in statistical mathematics. The
accuracy of the approximation is predominantly governed by the validity of the Gaussian assumption and
can be viewed as (at least) an order-of-magnitude estimate of the SE in all but the most extreme cases of
departure from the underlying assumptions.

The expected loss (in millions of home currency units), conditional on the occurrence of a loss greater than
the Value at Risk. The shortfall is therefore a measure of the fatness of the loss (or profit) tail of the P&L
distribution. It depends on your choice of confidence, tail_quantile, and mtm_pv.
Iterations
The number of historical scenarios simulated. This value depends on the number of entries per (asset-
vertex) series found in the files of tail_quantile and hist_data.
E(P&L)
The expected value (mean) of the portfolio P&L distribution (in millions of home currency units). This
quantity equals the sum of the portfolio P&Ls divided by iterations and depends on your choice of
tail_quantile and mtm_pv.
SD(P&L)
The standard deviation of the portfolio P&L distribution (in millions of home currency units). This value
depends on your choice of tail_quantile and mtm_pv.
Midpoints
HISTORICALVAR creates a set of evenly-distributed bins between the minimum and maximum values of
portfolio P&L distribution. (You can control the histogram with the min_midpoint and interval arguments.)
the formula’s array range) and by the minimum and maximum values generated by the simulation. A data
corresponding frequency of data points falling in that bin. (If you want the entire distribution then specify
distribution.) These values depend on your choice of mtm_pv.
Frequencies
The number of occurrences of the portfolio P&Ls (out of the total number of iterations) falling in the bin
located at the corresponding midpoint. The sum of all the frequencies equals the number of iterations in the
simulation. These values depend on your choice of tail_quantile and mtm_pv.
HISTORICALVAR outputs two basic types of return arrays. The output format depends on the specification
of tail_quantile and the size of the array range entered. If tail_quantile is omitted, the return array is of the
form:
1x1 VaR
1x2 VaR Mark-to-market

SE(VaR) VaR/MTM

SE(VaR) VaR/MTM
Shortfall(VaR) Iterations

SE(VaR) VaR/MTM
E(P&L) SD(P&L)
Nx2 VaR Mark-to-market

SE(VaR) VaR/MTM
E(P&L) SD(P&L)
... ...
If tail_quantile is specified, the return array is of the form shown below. Total-points is the total number of
points in the P&L distribution. Tail-points is the number of observation date (Obs-date) vs profit-or-loss
(Profit-loss) entries that can be output. If tail_quantile is zero, then by definition Tail-points is equal to Total-
points.
1x1 Total-points
Nx1 Total-points
Obs-date(1)
Obs-date(2)
...
Obs-date(N-1)
1x2 Total-points Tail-points
Nx2 Total-points Tail-points

Obs-date(1) Profit-loss(1)
Obs-date(2) Profit-loss(2)
... ...
Obs-date(N-1) Profit-loss(N-1)
As horizon increases, VaR becomes less reliable.
As confidence increases, VaR becomes larger.

 No historical data found within specified window constraints.
 No historical data found for market factor on which portfolio depends.
 confidence  0.
 horizon < 1.
 end_date > start_date.
 tail_quantile < 0.
 tail_quantile  1.
 mtm_pv and cache do not evaluate to TRUE or FALSE.
Returns the incremental VaR of candidate trades, when added to an existing portfolio whose cash flow map
was used as an input argument to VARDELTA. The result is expressed in the home currency.
INCREMENTALVAR(candidate_map_array, vardelta_array)
candidate_map_array is an array specifying a cash flow map of a candidate trade or candidate portfolio. You
can use the result of CASHFLOWMAP. candidate_map_array must have the same number of rows and
columns as vardelta_array.
vardelta_array is an array of VaRdelta values from an existing portfolio. You can use the result of
VARDELTA. candidate_map_array must have the same number of rows and columns as vardelta_array.
Taking the inner product of the VaRdelta vector (calculated with VARDELTA) and the cash flow map of
candidate trades with INCREMENTALVAR indicates whether such trades will be VaR-increasing (> 0),
VaR-decreasing (< 0), or VaR-neutral (= 0).
INCREMENTALVAR computes the inner product of its arguments. That is, multiplies the corresponding
components of the arrays and returns the sum of those products. The same result can be calculated using the
Excel SUMPRODUCT function.
If you are interested in an alternative (equivalent) way of computing incremental VaR, without generating
the candidate_map_array of the candidate trade, see MARGINALVAR.
See VaRdelta for more information.

 candidate_map_array and vardelta_array have unequal dimensions.
 candidate_map_array or vardelta_array contains non-numeric elements.
Specifies which set of files containing market data will be the default market data used by VaRworks
functions if market data filenames are not explicitely specified in those function calls. Loads the market data
into memory if it is not already resident, or if the files have changed since the last time the data was loaded.
The market data is also reloaded if the effective_date specified as an argument changes. Returns an
indication of success or failure.
LOADMARKETDATA allows the use of datasets including externally specified yield curves, exchange rates,
and smile data files in conjunction with VaRworks functions that do not accept specification of these files
through function arguments.
varworks.xls (All worksheets)
LOADMARKETDATA(vol_data, corr_data, asset_codes, yield_curves, exchange_rates, smile_curves,

effective_date, max_datasets)
information.
yield_curves is text specifying a yield curve file, which may include a path. If yield_curves is specified then
the interest rates/commodity prices in yield_curves are used in calculations instead of the interest rates in
vol_data.
exchange_rates is text specifying an exchange rate file, which may include a path. If exchange_rates is
specified then the exchange rates in exchange_rates are used in calculations instead of the exchange rates in
vol_data.
smile_curves is text specifying a smile curve file, which may include a path. If smile_curves is specified then
the volatilities in the file are used in the calculations, and overwrite the volatilities specified via the trade
record.
effective_date is a date specifying when the dataset is loaded. If this argument is omitted then the system
date (today) is used. The argument can (and should) be omitted if Constant Maturity commodity vertices
are used throughout the dataset. If Fixed Expiration commodity vertices are specified, effective_date should
match the value being used by other VaRworks functions.
max_datasets is a number between 1 and 16 specifying the maximum number of datasets stored in memory
at a time. If omitted it defaults to 16.
See Volatility, Correlation, Asset, Yieldcurve, Xrate, and Smile files for more information about the
individual files that constitute the dataset.
An error value is returned if the dataset could not be loaded. If LOADMARKETDATA is successful, a string
label corresponding to the loaded dataset is returned. The label can then be used when calling any function
requiring dataset information, by replacing the volatility file argument with the desired label. This allows
the user to specify a dataset containing yield curve and/or exchange rate files to be used by a VaRworks
function with no corresponding arguments.
There is currently a static limit of 16 datasets that may be resident in memory at a time, corresponding to the
16 datasets that were most recently used.
Using multiple instances of LOADMARKETDATA with different inputs within a single spreadsheet may
lead to unpredictable results, if Shift F9 or Ctrl/Alt F9 are used to control the order of calculations.
Returns the incremental VaR of a candidate trade, when the trade is added to an existing portfolio whose
VarDelta values were generated by the VARDELTA function. The result is expressed in the home currency.
varworks.xls (Incremental VaR worksheet)
MARGINALVAR(maturity_list, asset_list, vardelta_array, vol_data, corr_data, candidate_trade,

home_ccy, effective_date, preserve_var, pv, cross_corrs, asset_codes)
maturity_list should coincide with the one used to generate the vardelta_array.
codes listed in asset_codes. asset_list should coincide with the one used to generate the vardelta_array.
vardelta_array is an array of VaRdelta values from an existing portfolio. You can use the result of
VARDELTA.
candidate_trade is text specifying a portfolio or trade file, which may include a path, for which the marginal
VaR with respect to the existing portfolio is computed.
allocation).


information.
MARGINALVAR has functionality identical to INCREMENTALVAR, but internally generates the cashflow
map used by INCREMENTALVAR. It thus provides a more flexible interface to generate real-time VaR
through the VaRdelta methodology.
See VaRdelta for more information.

 candidate_trade is internally mapped into vertices with asset codes and maturities not included
in maturity_list and asset_list .
 vardelta_array contains non-numeric elements.
Returns an array containing the analytic diversified VaR, undiversified VaR, sum of the allocated cash flows
of a portfolio, and shortfall risk. All results are converted to the home currency. Use PORTVARANL to
calculate the VaR of a portfolio without displaying detailed intermediate calculations.
PORTVARANL(vol_data, corr_data, portfolio, horizon, confidence, home_ccy, effective_date,

preserve_var, pv, cross_corrs, asset_codes, yield_curves, exchange_rates, file_name, aggregate_flag)

horizon is a number specifying the portfolio’s unwind period in days. horizon is an integer greater than or
equal to one; if horizon is not passed as an integer then it is truncated. Results are scaled by the square root of
horizon. The resulting VaR is the expected change in value under adverse circumstances in this time interval.
Specify horizon in days no matter what the forecast horizon of the volatility-correlation dataset is. For
example, if you are using a monthly (25 days) RiskMetrics dataset and want a five-day horizon then specify
5.
confidence level of x, about 1 – x percent of the losses during the horizon period should exceed the resulting
VaR.
allocation).


information.
yield_curves is text specifying a yield curve file, which may include a path. If yield_curves is omitted then the
yield curves in vol_data are used.
exchange_rates is text specifying an exchange rate file, which may include a path. If exchange_rates is omitted
then the exchange rates in vol_data are used.
file_name is text specifying an output file, which may include a path, containing the specified confidence
interval and the portfolio VaR, expressed as appropriate header lines. file_name may contain comment lines.
If no path is specified then file_name is created in the current directory. Each time PORTVARANL is
executed a new file is created, overwriting the previous one (of the same name) if it exists. If file_name is
omitted then no file is created. If aggregate_flag is set to a non zero value, the name specified by file_name is
not used, and a file with name xxx_an.txt is generated where xxx is the name of the file specified in the
portfolio input, stripped of path and extension. This file is created in the same folder where the portfolio file
resides and it contains a list of mapped cashflows for all the vertices specified by the dataset. The number
and order of the vertices matches what obtained by using the CFDATA function (omitting the portfolio
input) with value input equal to ‚v‛.
aggregate_flag is a logical value specifying a different format for the output file being generated (see
file_name above). Note that this input might be useful when one wants to ‚slice and dice‛ portfolio risk
measures along different dimensions. By generating the cashflows for all the trades making up a portfolio
separately (by setting aggregate_flag to TRUE) allows one to build up any subportfolio cashflows without
having to rerun a potentially time consuming calculation. If aggregate_flag is set to a negative value,
PORTVARANL will also compute the VaRdelta array and cache it into memory. This is useful when calls to
COMPONENTVAR2 functions are subsequently used to decompose the risk of the portfolio.
Formulas above or Microsoft Excel Help.
PORTVARANL is a convenience function that calculates a portfolio’s VaR and cash flow statistics without
returning detailed intermediate calculations.
PORTVARANL returns a 4-by-1 (or 1-by-4) array, the array contains the diversified VaR in the top-most (or
left-most) cell, then the undiversified VaR, the sum of the portfolio’s allocated cash flows, and finally the
shortfall risk.
To calculate a portfolio’s diversified VaR, use either PORTVARANL alone or both CASHFLOWMAP and
VARANL serially. Diversified VaR equals VARANL(CASHFLOWMAP(portfolio)).
To calculate a portfolio’s undiversified VaR, use either PORTVARANL alone or both CASHFLOWMAP and
VARANLU serially and sum the elements of the VARANLU array. Undiversified VaR equals
SUM(VARANLU(CASHFLOWMAP(portfolio))).
To calculate the sum of the allocated cash flows of a portfolio, use either PORTVARANL alone or both
CASHFLOWMAP and SUM serially. The sum of the allocated cash flows equals
SUM(CASHFLOWMAP(portfolio)).
We recommend using CASHFLOWMAP, VARANL, and VARANLU instead of PORTVARANL because

examining the detailed cash flow maps is necessary to understand and validate VaR calculations.
cross_corrs has no effect on the undiversified VaR.

The shortfall risk can be computed within the analytic VaR approximation. It is proportional to VaR, with a
proportionality constant given by
exp(-Icum2(c)/2) / ((1-c)Icum(c) 2)
where c is the specified confidence, and Icum() is the inverse of the cumulative normal distribution function.
For a 95% confidence interval, this constant is equal to 1.2540.
Also see Remarks for VARANL, VARANLU, and CASHFLOWMAP.
The PORTVARANL error conditions are the same as those listed in the Remarks section of VARANL,
VARANLU, and CASHFLOWMAP.
measures and probabilities (see descriptions of the inputs below) and provides a time series of VaR,
Expected Tail Loss (ETL), VaR(+) and Expected Tail Gain (ETG) calculated according to a given
methodology using a fixed rolling window of observations.
backtests.xls
ROLLINGWINDOWVAR(hist_pandl_array, confidence, start_date, end_date, start_season, end_season,

lambda, rolling_window, method, tail_quantile)
must not be empty.
 The third column contains risk measures (used for P&L adjustments). The values in this
column, if present, must be nonnegative. These are used to adjust the P&L values based on the
last risk value in each window (similarly to the current_risk adjustment in
HISTORICALPANDL). If this column is empty or omitted, no adjustment is made.
Column three could be empty or omitted .
level of x, approximately 1 – x percent (x percent) of the losses (gains) should exceed the resulting VaR. The
default value of confidence is 0.95 and the VaR horizon is arbitrary.
historical P&L data begins with January 1st If the date column in hist_pandl_array is empty, start_season is
ignored.
weighted averaging scheme applicable to the P&L values in each window. If a nonzero value of lambda is
present, the values are weighted according to lambda. lambda equal to 0 or 1 leads to equal weighting. The
default value is 0. (See below for more details.)
rolling_window is a positive integer indicating the size of the rolling window. If an invalid number is
entered, the rolling window size is set equal to the size of the loaded P&L dataset and thus no rolling is
performed.
method is a string input, which may take values "A", "H" or "E". These correspond to the methodology used
to estimate the risk measures (VaR, ETL, etc). ‚A‛ stands for Analytical, ‚H‛ for Historical, and ‚E‛ for
Extreme Value (EVT) methodologies correspondingly. Currently, the analytical and the historical methods
use exponential weighting of the data if lambda is provided (see description of lambda above). The EVT
method does not weigh the data, in which case lambda is ignored. If method is omitted, the analytical
methodology is used.
tail_quantile is a number between 0.5 and 1, which is used by the EVT estimation procedure. Only the points
that belong to the tail_quantile of the distribution are used when fitting the Generalized Pareto Distribution
to data. If provided, tail_quantile cannot be larger than confidence. If tail_quantile is omitted, it is calculated
automatically, depending on confidence. tail_quantile is only used when the method is "e", it is ignored
otherwise.
ROLLINGWINDOWVAR uses linear interpolation to compute the VaR of a given discrete time series when
the method is ‚H‛.
start_season and end_season dates can be used to further select data, via season. Each of these parameters
(See J. Boudoukh et al.) This approach gives decreasing weight to the historical P&L values. The weights are
dictated by the time series, such that the return corresponding to the most recent date inside the window,
edate, has the largest weight. If N is the width of the window, then to each of the N returns R(edate), R(edate -
1), …, R(edate - (N-1)), the weight A x lambda k-1, where k = 1, 2, …, N is assigned. Here, A = (1 - lambda) / (1 -
lambda N) is a normalization factor, which ensures that the weights inside the window sum to one. Note that
this weighting of data is turned off if lambda is set to zero – its default value in which case equal weighting is
used.
ROLLINGWINDOWVAR returns the time series of the following values for t=1, <T, where T is the number
of times the window is rolled.
T
The number of times the window is rolled.
VaR(t)
The VaR of the historical P&L data inside the window (in the same units as the input data), which depends
on your choice of confidence. Note that, to allow a meaningful display of both VaR and VaR+ results, the
output of ROLLINGWINDOWVAR for each t is equal to the negative of the actual VaR(t) number.

The expected loss conditional on the occurrence of a loss greater than VaR(t). It is the VaR(t) plus the
average excess with respect to VaR(t), and is therefore a measure of the fatness of the loss (or profit) tail of
the P&L distribution inside the window. Note that the output of ROLLINGWINDOWVAR for each t is
equal to the negative of the actual ETL(t) number.
VaR+(t), Expected Tail Gain (t)

Same as VaR(t) and Shortfall(t) only for the profit tail.
P&L(t+1)
The actual P&L value in the period following the end of the rolling window t. This value can be compared
with the predicted values of VaR(t), VaR+(t).
Loss Exceptions, Gain Exceptions

The number of times the P&L(t+1) value is below –VaR(t) or is above VaR+(t) respectively.
ROLLINGWINDOWVAR outputs the following return array.
1x1 T
1x2 T Loss Exc.
1x3 T Loss Exc. Gain Exc.
1x4 T Loss Exc. Gain Exc. Total Exc.
(N+1) x 1 T
(N<=T) Date(1)
<
Date(N)
(N+1) x 2 T Loss Exc.

(N<=T) Date(1) P/L(1)
< <
Date(N) P/L(N)
(N+1) x 3 T Loss Exc. Gain Exc.

(N<=T) Date(1) P/L(1) -VaR(1)

< < <
Date(N) P/L(N) -VaR(N)
(N+1) x 4 T Loss Exc. Gain Exc. Total Exc.

(N<=T) Date(1) P/L(1) -VaR(1) -ETL(1)
< < < <
Date(N) P/L(N) -VaR(N) -ETL(N)

(N<=T) Date(1) P/L(1) -VaR(1) -ETL(1) VaR+(1)
< < < < <
Date(N) P/L(N) -VaR(N) -ETL(N) VaR+(N)

(N<=T) Date(1) P/L(1) -VaR(1) -ETL(1) VaR+(1) ETG(1)
< < < < < <
Date(N) P/L(N) -VaR(N) -ETL(N) VaR+(N) ETG(N)
Retrieves a set of (price-equivalent) returns, as calculated from stress scenarios contained in files.
varworks.xls (Stress Test worksheet)
SDATA(vol_data, corr_data, stress_data, vertex, use_file_drivers, driver, asset_codes, sort_type)
stress_data is text specifying a stress-test data file, or a file containing a list of stress-test data files, which
may include a path. See the Stress Data section, page251, for additional information. Stress data files can be
generated by using a stress manager application provided with the distribution. See Scenario Manager
Tutorial on page 378 for information on how to use the application.
asset is a currency, equity, or commodity code and asset_class[maturity] is an asset class code and maturity
(where applicable). Examples: ‚GAS.C12‛, ‚TECH.SE‛, ‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛.
use_file_drivers is a logical value specifying weather to use scenarios specific drivers specified in the
stress_test data files, or to override them with the single driver specified as an argument to SDATA. If
use_file_drivers =TRUE and no drivers are specified in stress _test data files or use_file_drivers = FALSE and
no driver is specified as an argument of SDATA all portfolio vertices not defined in stress_data are held fixed.
use_file_drivers
TRUE The driver specified as argument of SDATA is not used. When specified,
scenario specific drivers in the stress_test data files will be used instead.
FALSE or omitted The single driver specified as argument of SDATA is used for all scenarios.
Scenario specific drivers in the stress_test data files are neglected.
driver is text specifying an asset, asset class, and maturity in the format asset.asset_class[maturity] where asset
is a currency, equity, or commodity code and asset_class[maturity] is an asset class code and maturity (where
applicable). For driver to be used, use_file_drivers must be set to FALSE. The driver is the market vertex used
to define the stress applied to all portfolio vertices not explicitly or implicitly represented in the files of
stress_data. It must represent a vertex actually stressed in each of the scenarios specified in stress_data. If
omitted, no driver is employed and all portfolio vertices not defined in stress_data are held fixed. Examples:
‚GAS.C12‛, ‚TECH.SE‛, ‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛. This argument can be overridden by
specifying drivers within the files of stress_data, via the DRIVER header, AND by setting use_file_drivers to
FALSE.
asset_codes is text specifying an asset codes file, which may include a path. The currency, equity, and
commodity codes in vol_data and corr_data must be a proper subset of the codes listed in asset_codes. If
asset_codes is omitted then a default set of currency and commodity codes is used. Omit this argument if you
are using a RiskMetrics dataset; include it if you are using a MakeVC or custom dataset. See Assets for more
information.
set of returns of the scenarios defined in the files of stress_data. The possible values for sort_type are: ‘N’ (no
sorting), ‘A’ (sort returns in ascending order, from smallest to largest return), and ‘D’ (sort returns in
descending order, from largest to smallest return). If omitted or invalid text is entered, sort_type ‘N’ is used.
The purpose of SDATA is to provide the user access to the market values of vertex, as they are defined with
the files of stress_data. The scenario definitions in stress_data represent stress rules to be applied to a set of
market vertices on which a given portfolio depends. With the SDATA function, the user can see how vertex
is shocked by the various scenarios described by stress_data. The stressed value of vertex is given in the form
of its return from the market value specified in the volatility data_file.
SDATA returns the following values:
Scenarios
The number of stress scenarios applicable to vertex.
MarketValue
The mark-to-market value of vertex.
Returns
The set of returns of vertex, as calculated from the scenarios defined in the files of stress_data. Returns are
labeled by scenario name and the path of the file containing the scenario definition. The returns are ordered
according to the text passed to sort_type.
The SDATA return array, which can be transposed, is represented in the tables below:
Nx1 MarketValue
Return(1)
Return(2)
...
Return(N-1)
Nx2 Scenarios MarketValue

Scenario(1) Return(1)
Scenario(2) Return(2)
< ...
Scenario(N-1) Return(N-1)
Nx3 Scenarios MarketValue

Stress-file(1) Scenario(1) Return(1)
Stress-file(2) Scenario(2) Return(2)
... < <
Stress-file(N-1) Scenario(N-1) Return(N-1)

 horizon < 1.
measures and weights (see descriptions of the inputs below) and generates a series of random variables (so-
called transform probabilities) that are used to test the P&L distributions generated by a chosen
methodology. The function outputs several statistics (including a histogram) using the obtained transform
probabilities. The approach is described in more details in the remarks below.
backtests.xls
SIMBACKTEST(hist_pandl_array, tail_to_test, start_date, end_date, start_season, end_season, lambda,

rolling_window, method, return_type)
must not be empty.
 The third column contains risk measures (used for P&L adjustments). The values in this
column, if present, must be nonnegative. These are used to adjust the P&L values based on the
last risk value in each window (similarly to the current_risk adjustment in
HISTORICALPANDL). If this column is empty or omitted, no adjustment is made.
Columns three could be empty or omitted .
tail_to_test is a number between 0 and 1 specifying the tail of the generated (transform probabilities)
distribution to be tested. If tail_to_test is greater than (less than) 0.5 the tail corresponding to the loss-end
(profit-end) of the generated distribution will be tested. If tail_to_test is equal to 0.5, the entire distribution
of transform probabilities will be tested. See Remarks below for further details.
historical P&L data begins with January 1st. If the date column in hist_pandl_array is empty, start_season is
ignored.
weighted averaging scheme applicable to the P&L values in each window. If a nonzero value of lambda is
present, the values are weighted according to lambda. lambda equal to 0 or 1 leads to equal weighting. The
default value is zero. (See Remarks below for more details.)
rolling_window is a positive integer indicating the size of the rolling window. If an invalid number is
entered, the rolling window size is set equal to the size of the loaded P&L dataset and thus no rolling is
performed.
method is a string input, which may take values "A" or "H". These stand for Analytical and Historical
methodologies correspondingly. The method input is used to choose a methodology by which the P&L
distribution is generated and the transform probability is obtained. Both methodologies use exponential
weighting of the historical P&L data if lambda is provided (see description of lambda above). If method is
omitted, Analytical methodology is used.
return_type is a one-character, case-insensitive text input denoting the type of output. The possible values
for return_type are: ‘T’ and ‘H’. The return_type determines the type of output of the return array, as
indicated below.
Value Description
T or omitted The dates and transform probabilities corresponding to the tail_to_test are
displayed, sorted by date, together with some distribution statistics.
H The histogram of the transform probabilities corresponding to the
tail_to_test is displayed, together with some distribution statistics.
SIMBACKTEST uses linear interpolation to compute the cumulative probability of a given return from a
discrete historical distribution when the method is ‚H‛.
start_season and end_season dates can be used to further select data, via season. Each of these parameters
This approach gives decreasing weight to the historical P&L values. The weights are dictated by the time
series, such that the return corresponding to the most recent date inside the window, edate, has the largest
weight. If N is the width of the window, then to each of the N returns R(edate), R(edate -1), …, R(edate - (N-
1)), the weight A x lambda k-1, where k = 1, 2, …, N is assigned. Here, A = (1 - lambda) / (1 - lambda N) is a
normalization factor, which ensures that the weights inside the window sum to one. Note that this
weighting of data is turned off if lambda is set to zero – its default value in which case equal weighting is
used.
SIMBACKTEST returns the following output.
N
The number of points in the tail corresponding to the tail_to_test input. When tail_to_test is equal to 0.5, N is
equal to the number of times the window is rolled.
p(t)
The transform probability value at date t. This is the risk model’s probability of observing a return below
the actual on date t. This probability is computed using the distribution generated from a rolling_window of
previous P&L values using the chosen methodology.
LR or LRtail
The value of the Likelihood Ratio test statistic (see definition below).
Midpoints
When return_type is “H”, SIMBACKTEST creates a set of bins whose midpoints are evenly distributed. The
values of the bin midpoints are determined by the total number of bins (specified by the size of the output
array) and by the minimum and maximum bin values determined by the tail_to_test input. When tail_to_test
is > 0.5, the bin values are distributed between
0 and (1- tail_to_test), when tail_to_test is < 0.5, the bin values are distributed between (1- tail_to_test) and 1,
and when tail_to_test is = 0.5, the bin values are distributed between 0 and 1.
Data in this form can be easily charted as a histogram. Each bin is marked by a midpoint and a
corresponding frequency of data points falling in that bin.
Frequencies
The proportion of occurrences of the transform probabilities (out of N) falling in the bin located at the
corresponding midpoint. The sum of all the frequencies equals 1.
SIMBACKTEST outputs two basic types of return arrays. The output depends on the specification of
return_type and the size of the output array range entered.
If return_type is ‘T’ or is omitted, the return array is of the form
1x1 LR or LTtail
Nx1 LR or LTtail
(N>1) P(t1)
P(t2)
<
P(tN-1)
1x2 N LR or LTtail
Nx1 N LR or LTtail
(N>1) Date (t1) P(t1)
Date (t2) P(t2)
< <
Date (tN-1) P(tN-1)
If return_type is ‘H’, the return array is of the form shown below.
1x1 LR or LTtail
Nx1 LR or LTtail
(N>1) Frequency(1)
Frequency(2)
...
Frequency(N-1)
1x2 N LR or LTtail
Nx2 N LR or LTtail
(N>1) Midpoint(1) Frequency(1)
... ...
The likelihood ratio (LR) testing approach implemented in the SIMBACKTEST function (see Berkowitz, J.
(2000)for more details) is briefly described below. Using historical P&L values preceeding time t, an entire
distribution forecast for a return on date t is produced, call it F t(*). Then at time t, after having observed the
actual return, we can calculate the risk model’s probability of observing a return below the actual as:
p(t) = Ft(P&Lt).
We call this p(t) a transform probability.
If we are using the correct risk model to forecast the return distribution, then we should not be able to
forecast the probability of falling below the actual return. Thus, the time series of p(t) should be distributed
independently over time as a Uniform(0,1) variable. We therefore want to test the null hypothesis
H0: p(t) ~ i.i.d. Uniform(0,1).
The histogram check gives a qualitative, graphical analysis of this hypothesis. However it is not a formal
statistical test and it does not test the time variation of p(t). A proper statistical test is described by
J.Berkowitz as follows. We transform the p(t) random variables using the inverse cumulative normal
distribution function -1:
z(t) = -1 (p(t)).

Under the null hypothesis, the z(t) should be i.i.d. Normal(0,1) variables. This hypothesis is tested against a
first-order autoregressive alternative with mean and variance obtained using the maximum likelihood
estimation. The obtained test statistic (LR) gives a probability, also known as p-value, of getting a sample,
which is even less likely than the sample we actually have, given that the null hypothesis is true.
A similar test can be performed on just the tail of the distribution. In this case, the test statistic (LR tail) is
based on a censored normal distribution and the null hypothesis is tested against an alternative with
different mean and variance. For full details, see Berkowitz, J(2000).
Returns a portfolio’s profit and loss as calculated from stress scenarios contained in files. For more
information about scenario files, see Stress Data on Page 251. For information about Stress Testing and its
application to value-at-risk, see Stress Testing on Page 42.
varworks.xls (Stress Test worksheet)
STRESSTEST(vol_data, corr_data, stress_data, portfolio, home_ccy, use_file_drivers, driver,

effective_date, asset_codes, sort_type)
stress_data is text specifying a stress-test data file, or a file containing a list of stress-test data files, which
may include a path. See the Stress Data section, page 251, for additional information. Stress data files can be
generated by using a stress manager application provided with the distribution. See Scenario Manager
Tutorial on page 378 for information on how to use the application.
home_ccy is text specifying the currency in which results will be accounted.
use_file_drivers is a logical value specifying weather to use scenarios specific drivers specified in the
stress_test data files, or to override them with the single driver specified as an argument to STRESSTEST. If
use_file_drivers =TRUE and no drivers are specified in stress _test data files or use_file_drivers = FALSE and
no driver is specified as an argument of STRESSTEST all portfolio vertices not defined in stress_data are held
fixed.
use_file_drivers
TRUE The driver specified as argument of STRESSTEST is not used. When specified,
scenario specific drivers in the stress_test data files will be used instead.
FALSE or omitted The single driver specified as argument of STRESSTEST is used for all scenarios.
Scenario specific drivers in the stress_test data files are neglected.
driver is text specifying an asset, asset class, and maturity in the format asset.asset_class[maturity] where asset
is a currency, equity, or commodity code and asset_class[maturity] is an asset class code and maturity (where
applicable). For driver to be used, use_file_drivers must be set to FALSE. The driver is the market vertex used
to define the stress applied to all portfolio vertices not explicitly or implicitly represented in the files of
stress_data. It must represent a vertex actually stressed in each of the scenarios specified in stress_data. If
omitted, no driver is employed and all portfolio vertices not defined in stress_data are held fixed. Examples:
‚GAS.C12‛, ‚TECH.SE‛, ‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛. This argument can be overridden by
specifying drivers within the files of stress_data, via the DRIVER header, AND by setting use_file_drivers to
FALSE.
information.
set of portfolio profits and losses, as calculated from the scenarios defined in the files of stress_data. The
possible values for sort_type are: ‘N’ (no sorting), ‘A’ (sort returns in ascending order, from smallest to
largest return), and ‘D’ (sort returns in descending order, from largest to smallest return). If omitted or
invalid text is entered, sort_type ‘N’ is used.
STRESSTEST returns the following values:
Mark-to-market
The mark-to-market value of the portfolio on effective_date (in millions of home currency units).
Scenarios
The number of stress scenarios simulated. This value depends on the number of scenarios defined within
the files of stress_data.
Profits and losses

The set of profits and losses of portfolio (in millions of home currency units), as calculated from the scenarios
defined in the files of stress_data. Profits and losses are labeled by scenario name and the path of the file
containing the scenario definition. The profits and losses are ordered according to the text passed to
sort_type.
The STRESSTEST return array, which can be transposed, is of the form:
Nx1 Scenarios
Mark-to-market
Profit-loss(1)
Profit-loss(2)
...
Profit-loss(N-1)
Nx2 Scenarios Mark-to-market

Scenario(1) Profit-loss(1)
Scenario(2) Profit-loss(2)
< ...
Scenario(N-1) Profit-loss(N-1)
Nx3 Scenarios Mark-to-market

Stress-file(1) Scenario(1) Profit-loss(1)
Stress-file(2) Scenario(2) Profit-loss(2)
... < <
Stress-file(N-1) Scenario(N-1) Profit-loss(N-1)

 horizon < 1.
 mtm_pv or use_file_drivers does not evaluate to TRUE or FALSE.
Returns the diversified analytic Value at Risk (VaR) of a cash flow map, converted to the home currency.
varworks.xls (Analytic VaR worksheet)
VARANL(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence, home_ccy,

pv, cross_corrs, asset_codes, yield_curves)
cash_flow_array is an array of cash flows, all home_ccy equivalent. You can use the result of
CASHFLOWMAP. cash_flow_array must have the same number of columns as asset_list and the same
number of rows as maturity_list. Use pv to specify if the cash flows are present or future values.
5.
VaR.
pv is a logical value specifying the valuation time of the cash_flow_array cash flows.
pv cash_flow_array contains

information.
The diversified VaR is the exposure of a portfolio’s cash flows incorporating their correlations. For a
portfolio with n cash flows, the diversified VaR is
D  VCV 
where D is the portfolio’s diversified VaR, V is a 1-by-n vector of the portfolio’s undiversified VaRs, C is an
n-by-n correlation matrix between changes in components, and V' is the n-by-1 transpose of V.
The value of pv in VARANL must be the same as the value of pv in CASHFLOWMAP.

 horizon < 1.
 pv and cross_corrs do not evaluate to TRUE or FALSE.
Returns an array of undiversified, analytic Values at Risk (VaRs) of a cash flow array, converted to the home
currency. The array has the same number of rows and columns as the input cash flow map. Each value in
the returned array is a cash flow multiplied by its corresponding volatility; no correlations are used. The
sum of the values in the undiversified VaR array is termed the undiversified VaR.
varworks.xls (Analytic VaR worksheet)
VARANLU(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence,

home_ccy, pv, asset_codes, yield_curves)
5.
VaR.
information.
Formulas above or Microsoft Excel Help.
The value of pv in VARANLU must be the same as the value of pv in CASHFLOWMAP.

 horizon < 1.
 pv does not evaluate as TRUE or FALSE.
Returns an array containing a portfolio’s diversified VaR, standard error, mark-to-market, and distribution
statistics calculated using Monte Carlo simulation. The entire Monte Carlo distribution can be optionally
output. All results are converted to the home currency. VARCARLO2 is similar to VARCARLO, but it
accepts additional inputs, and provides a more general output, consistent with the output of the
HISTORICALVAR function.
If the pv_flag flag is set to -1, the histogram of future portfolio values is generated, together with its
expected future value (output as hMtM) and its present value (output as MtM), and quantiles of the
distribution. The calculation also generates the expected value of future MtM conditional on having MtM >
0. This setting is useful when the portfolio represents nettable positions associated to a counterparty, and
one is interested in estimating the potential loss due to counterparty default. See Remarks below for
additional information.
varworks.xls (Monte Carlo VaR worksheet)
VARCARLO(vol_data, corr_data, portfolio, horizon, confidence, home_ccy, effective_date, cross_corrs,

asset_codes, iterations, seed, distribution, drift, pv_flag, no_analytic_limit, min_midpoint, interval)
VARCARLO2(vol_data, corr_data, portfolio, horizon, confidence, home_ccy, effective_date, cross_corrs,

asset_codes, iterations, seed, distribution, drift, pv_flag, no_analytic_limit, min_midpoint, interval, evt_tail,
aggregate_flag)

horizon is a number specifying the portfolio’s unwind period in (calendar) days. horizon is an integer greater
than or equal to one; if horizon is not passed as an integer then it is truncated. The resulting VaR is the
expected change in value under adverse circumstances in this time interval. Specify horizon in days no
matter what the forecast horizon of the volatility-correlation dataset is. For example, if you are using a
monthly (25 days) RiskMetrics dataset and want a five-day horizon then specify 5.
confidence is a number between 0 and 1, exclusive, specifying the size of the VaR confidence level. For a
confidence level of x, about 1 – x percent of the losses during the horizon period should exceed the resulting
VaR. When confidence is greater (smaller) than 0.5, the VaR output gives a quantile corresponding to the
‚loss‛ (‚gain‛) region of the distribution. Note that the same convention applies to the case when a
Potential Future Exposure is computed instead of a VaR, i.e. when pv_flag is set to -1 (see below). For
instance, if you are interested in the 5th percentile of the gain region of the distribution set confidence=0.05.

information.
iterations is an integer specifying the number of simulations to run. iterations is an integer greater than or
equal to zero. If iterations is not passed as an integer then it is truncated. If iterations = 0 then no simulation is
performed and only the portfolio’s mark-to-market is returned. The paths of all the underlying correlated
variables are sampled on each run. Each simulation run samples paths for those variables on which the
portfolio value depends. The number of simulated variables is then always less or equal than the number of
basic financial assets for which volatility and correlation data are provided. Calculation time increases
approximately linearly with the number of iterations. If iterations is omitted then 1000 is used, however
some empirical experimentation is necessary to determine how many iterations will provide you with a
satisfactory standard error for your portfolio.
seed is a number specifying the initial value used to generate a sequence of pseudo-random numbers. The
same seed produces the same sequence of pseudo-random numbers and therefore identical results for a
given set of inputs. Identical sequences are useful for testing and comparison purposes. seed must be an
integer greater than or equal to zero. If seed is zero or omitted then an internally-generated random seed is
used. Note that seed must be positive if aggregate_flag is set to true, see below.
distribution is text specifying an output file, which may include a path, containing the profit-and-loss (P&L)
distribution of the portfolio, with P&L’s sorted from largest loss to largest profit. VARCARLO writes the
change in price of the portfolio (in millions of home currency units) for each simulation run to distribution.
distribution contains iterations lines, one value per line. The file created by VARCARLO2 is of
TYPE=DISTRIBUTIONDATA, and contains header lines providing information about methodology and
number of data lines (see iterations above); each data line contains a comma separated record of the iteration
label (a number between 1 and iterations) and the corresponding P&L. If no path is specified then distribution
is created in the current directory. Each time VARCARLO or VARCARLO2 are executed a new file is
created, overwriting the previous one (of the same name) if it exists. If distribution is omitted then no
distribution file is created. If aggregate_flag is set to true the name specified by distribution is not used, and a
file with name xxx_mc.txt or xxx_pfe.txt is generated where xxx is the name of the file specified in the
portfolio input, stripped of path and extension. xxx_pfe.txt file are generated when pv_flag is equal to -1,
otherwise xxx_mc.txt are generated. This file is created in the same folder where the portfolio file resides and
it contains unsorted P&L’s, see aggregate_flag below for additional information.
drift is a logical value specifying whether the drift rates of underlying market factors should be
incorporated in their stochastic processes.
drift Drift rate

TRUE or omitted All stochastic processes will be simulated to a horizon of horizon days
assuming a risk-neutral drift rate in addition to a stochastic component of drift.
The risk-neutral drift is implied by the spot yield curves and commodity
forward-price structure contained in vol_data.
FALSE All stochastic processes will be simulated to a horizon of horizon days with a
zero total rate of drift, which is the sum of both stochastic and non-stochastic
(risk-neutral) contributions.
pv_flag is an integer value specifying how the histogram is to be constructed. For pv_flag equal to 0,1, or 2,
the Monte Carlo simulation constructs the histogram of the P&L by subtracting the model-estimated
(present or future valued ) MTM value of the portfolio from the (present or future valued) value of the
portfolio estimated at the horizon. For pv_flag equal to -1 the Monte Carlo simulation is used to construct
the histogram of the model-estimated MTM price of the portfolio at the horizon, without substracting the
MtM value of the portfolio, and without accounting for possible cashflows between value date and the
horizon date. In this case the ‚VaR‛ output numbers really refer to quantiles of the MtM distribution, while
the ‚Shortfall‛ number refers to the expected loss incurred if positive MtM are lost due to counterparty
default (PFE). See Remarks below for additional information.
pv_flag Histogram calculation

1, TRUE, or The value of the portfolio, as estimated at the horizon, is discounted by the
Omitted prevailing short rate of the home currency before the MTM price is subtracted.
The P&L distribution, constructed in this way, is a comparison between two
model-estimated prices on value date.
0 or FALSE The value of the portfolio, as estimated at the horizon, is not discounted before
the MTM is subtracted. The P&L distribution, constructed in this way, is a
comparison between a model-estimated future value and a model-estimated
present value.
2 The value of the portfolio, as estimated at the horizon, is not discounted, but
the MTM is future valued at the horizon. The P&L distribution, constructed in
this way, is a comparison between two model-estimated prices on the horizon
date.
-1 Statistics related to the future portfolio values (PFE) are displayed. Future
portfolio values do not include any of the cashflows intervening between value
date and the horizon date. See more about PFE in the Remarks section below.
no_analytic_limit is a logical value specifying specific limiting assumptions of the simulation.
no_analytic_limit Limiting assumptions

TRUE or omitted None. The simulation is performed using the drift and pv_flag settings.
FALSE The simulation is performed under the same limiting assumptions as cash
flow-based analytic VaR methods. This setting allows for comparison of Monte
Carlo and analytic VaR. In this case, all stochastic processes are simulated to
the horizon implied by the volatility-correlation dataset, with the total rate of
drift set to zero, that is, drift = FALSE. For example, if vol_data contains 30-day
volatilities, then all processes are simulated to a 30-day horizon—with zero
total drift. The portfolio is marked-to-market without accounting for non-
stochastic changes in the value of instruments; only volatility-induced changes
are taken into account in this limit. This setting renders the pv_flag argument
moot.
you specify min_midpoint and interval, the size of the VARCARLO formula array range must be large
enough to contain the histogram data, otherwise the histogram data is truncated. If min_midpoint is omitted
then VARCARLO automatically chooses a minimum midpoint.
omitted then VARCARLO automatically chooses a midpoint interval.
evt_tail (used by VARCARLO2 only) is a number between 0 and 1, exclusive, specifying the percentile
defining the P&L distribution tails. evt_tail determines the loss tail (say 95%), and (1-evt_tail) the profit tail.
If specified, and distribution is specified, the two tails are fitted and the Generalized Pareto distribution
parameters are computed and included in distribution. Also included in distribution is the number of points,
derived from evt_tail and iterations, defining the tails.
aggregate_flag (used by VARCARLO2 only) is a logical value specifying the set of risk factors (vertices)
simulated by the Monte Carlo approach. If aggregate_flag=FALSE or missing, only portfolio specific risk
factors are simulated, while if aggregate_flag=TRUE, all the risk factors specified within the volatility and
correlation dataset are simulated. The default behavior, corresponding to version 5.5 or lower of VaRworks,
is obtained by setting aggregate_flag to FALSE. Setting this input to TRUE requires specification of the seed
input, and generates an output file containing unsorted P&L’s (see distribution above). Note that this input
is very useful when one wants to ‚slice and dice‛ portfolio risk measures along different dimensions. By
generating the P&L’s files for all the trades making up a portfolio separately, and doing so with a consistent
set of random numbers (by setting aggregate_flag to TRUE), allows one to build up any subportfolio P&L’s
without having to rerun a full simulation. This is accomplished by aggregating the P&L’s from the
generated files corresponding to the trades belonging to the desired subportfolio. If aggregate_flag is equal to
-1, the file mcSimulationData.txt is also created, containing information about the horizon used in the
calculation, and the maximum horizon specified in any trade file, if a PaR calculation is being performed.
If you have specified a long time horizon and VARCARLO returns zero VaR, then a large number of your
trades expire before the horizon. VARCARLO reinvests expired trades as money-making trades, carrying
them to the horizon (from the point of expiration) as zero-coupon bonds. These reinvestments substantially
improved your standing with respect to market risk. Basically, VARCARLO cashes in your portfolio before
the horizon. Expired trade reinvestment is documented in the VaRworks error log.
During the course of a simulation, VARCARLO has the ability to handle simulation events (cash flows) that
intervene before the horizon, such as the pay out of coupons or dividends or the early expiration of a trade.
When these events occur, they are written to your error log as FEA_WARNING_EXPIRED messages. All
positive intervening cash flows are reinvested to the horizon as zero-coupon government bonds. All
negative intervening cash flows are carried to the horizon as losses. However, if pv_flag=-1, intervening cash
flows are not included in the calculation, see pv_flag above.
VARCARLO might return the error message: ‚WARNING: FEA_WARNING_MATH: VarCarlo: Simulate:
Covariance matrix not positive-definite; required adjustment.‛ RiskMetrics datasets are vulnerable to
positive-definiteness problems across currency and commodity asset classes. If this is a persistent problem
you might consider using MakeVC to create volatility-correlation datasets.
VARCARLO performs a Monte Carlo simulation of market risk by:
1. Estimating the mark-to-market (mark-to-model) value of the input portfolio on the effective_date;
2. Decomposing portfolio into its underlying market-factor dependencies;
3. Calculating the expected values of these underling assets at the horizon, assuming lognormal-
price and normal-rate stochastic processes constructed from the input volatility data vol_data
and correlation data corr_data;
4. Revaluing portfolio at the horizon; and
5. Constructing a P&L distribution from repeated implementation of steps 3 and 4.
Once the repeated iterations have been completed the VaR is estimated from the resultant P&L distribution
using the input confidence level. This involves constructing a list of P&Ls (in millions of home currency units)
associated with each Monte Carlo iteration, and sorting the list in ascending order, from largest loss to
largest gain. The VaR is estimated from the n = (1 – confidence)  (length of list) position in the list. For
example, if confidence = 0.95 and iterations = 1000, then VaR is estimated from the n=50-th value in the sorted
list. If n is fractional, it is estimated by linear interpolation. The distribution is provided upon return as a
histogram (midpoints vs. frequencies), and in its raw form as the file distribution, if specified.
The cross_corrs, drift, pv_flag, and no_analytic_limit arguments allow you to modify selective aspects of this
simulation behavior:
The cross_corrs argument allows you to switch off correlations among underlying market factors of different
asset classes while preserving correlations between underlyings of the same asset class. This feature allows
you to investigate the sensitivity of your portfolio to cross-asset class market risk.
The drift argument allows you to incorporate non-stochastic drift rates into the movements of underlying
market factors. Each underlying is assigned a rate of drift corresponding to the expected value of the
underlying at the horizon, as implied by the spot-yield and forward-price curves contained in vol_data,
assuming a risk-neutral trading environment. In VARCARLO, when we speak of drift, we refer to both this
risk-neutral term and any stochastic contribution of the same magnitude of importance, which might arise
because of the underlying stochastic process. (For example, in the case of a lognormal process, in addition to
the risk-neutral drift rate there is a term proportional to the square of the volatility. When you switch on the
drift you switch on both terms; when you do not include drift in the simulation both contributions are
neglected.)
The pv_flag argument controls the definition of the P&L distribution. To understand the significance of this
factor is to realize the distinction between the future value of your portfolio at the horizon and the concept of
a price. The simulation estimates your portfolio value using underlying market factors moved to the horizon.
Doing so, it is constructing a future value. To attribute a price to this future value, it must be discounted by an
appropriate rate. In VARCARLO, if pv_flag is TRUE or 1 then the distribution is constructed from the
difference between the MTM and the present value of expected future portfolio value at the horizon, using
the prevailing short rate of your home currency. (This is a comparison between two prices.) If pv_flag is
FALSE or 0 then the distribution is constructed from the difference between the MTM and the expected
future value of your portfolio at the horizon. Your choice of pv_flag will be reflected in the returned VaR
since the VaR is directly computed from the type of distribution you define. Ultimately, your choice of
pv_flag will depend on your motivation for estimating VaR—one choice for pv_flag is not necessarily better
than the other! If you are interested in computing Potential Future Exposures, set pv_flag=-1.
The no_analytic_limit argument is a special setting that, if FALSE, VARCARLO will operate in a specific
mode consistent with the assumptions made by the analytic VaR calculators of VaRworks. In this mode,
VARCARLO will neglect all non-stochastic changes to your portfolio value. Only volatility-induced changes
will be taken into account. Setting no_analytic_limit to FALSE will effectively force drift = FALSE and prevent
intervening cash flow events from taking place. (Also, pv_flag will be rendered moot since in this mode the
portfolio is not explicitly a function of time.) Setting no_analytic_limit to TRUE will more fully explore the
sensitivity of your portfolio to market risk, particularly over extended horizons and in intervening cash flow
events.
VARCARLO and VARCARLO2 return the following values:
VaR
The diversified Monte Carlo Value at Risk (in millions of home currency units), which depends on your
choice of pv_flag. The entire list is available by specifying distribution. If pv_flag=-1, this output corresponds
to a quantile of the MtM distribution at horizon, not of the P&L distribution.
Mark-to-market (MTM)
The mark-to-market value of the portfolio on effective_date (in millions of home currency units).
Mark-to-market at horizon (MTMh)

The mark-to-market value of the portfolio valued at horizon (i.e. horizon days past effective_date), with the
same market data as on effective_date, and including possible cashflows (e.g. coupon payments, expired
trades, and so on) occurring between effective_date and the horizon date. MTMh is useful for backtesting
purposes when a ‚clean‛ P&L is required for proper comparison with the estimated VaR. The ‚clean‛ P&L
between two dates d1 and d2 can now be computed by taking the difference of MTMh and MTM, with both
MTMh and MTM evaluated on the same portfolio files corresponding to date d1, effective_date equal to d1,
an horizon input equal to the number of days between d1 and d2, and with market data files corresponding
to dates d2 and d1, for MTMh and MTM respectively. MTMh is expressed in millions of home currency
units.
SE(VaR)
An estimate of the standard error (in millions of home currency units) of the quantile associated with the
confidence level input. This value depends on your choice of pv_flag.
Note The standard error SE is analytically estimated assuming the limit of a large VaR sampling—as in the
case of running VARCARLO repeatedly with the input parameters held fixed and the seed set to zero—
wherein the tenets of the Central Limit Theorem of statistics become applicable. The error associated with a
quantile estimate can be expressed in terms of the value of the probability density at the quantile point, a
number that is difficult to estimate. We approximate this number by using a Gaussian distribution for the
P&L characterized by a VaR matching the computed VaR. We have found this approximation gives very
reasonable estimates of the SE(VaR) when compared with the empirical distribution of VaR estimates
obtained by using a random seed. Notice that, according to VaRworks convention, VaR is set to zero when
the quantile corresponding to the confidence interval is positive. However, the estimate given for SE(VaR) is
an estimate of the error of the quantile. Therefore there might be rare cases when the VaR output is
consistently zero, even when sampled for different seeds, while SE(VaR) is different from zero.
VaR/MTM
VaR as a fraction of the mark-to-market value of the portfolio. Multiply by 100 to convert to a percent. This
value depends on your choice of pv_flag.
Shortfall(VaR)/PFE
The expected loss (in millions of home currency units), conditional on the occurrence of a loss greater than
the Value at Risk. The shortfall is therefore a measure of the fatness of the loss (or profit) tail of the P&L
distribution. It depends on your choice of confidence, tail_quantile, and pv_flag. Available only in
VARCARLO2.
If pv_flag=-1, the output is in the form of table, giving various PFE-related statistics for each of the horizon
dates. The first column gives each of end-of-month horizon dates from the effective date to the final
(specified) horizon date. The second column is the expected value of future potential losses (EE, ‚Expected
Exposure) at each (row) horizon, due to the counterparty failing to deliver a positive MtM, i.e. if
DefaultLoss={0 if MtM <0; MtM if MtM >0}, we compute PFE=<DefaultLoss>. The third, fourth and fifth
columns are the mean exposure (EE) plus one, two and three standard deviations. The sixth column is the
Exposure at the user-specified confidence level and the seventh column is the maximum running EE over
time. The first row gives the maximum of all these statistics, which is what is commonly used as the PFE.
Given a user provided probability of default over the horizon D(h), and an estimate of the recovery rate R,
the actual expected loss due to default would be equal to PFED(h)(1-R), i.e PFE gives an estimate of the
maximum possible loss.
E(P&L)
The expected value (mean) of the portfolio P&L distribution (in millions of home currency units). This
quantity equals the sum of the portfolio P&Ls divided by iterations and depends on your choice of pv_flag. If
pv_flag=-1, the output gives the present value of the expected future value of the portfolio at horizon.
SD(P&L)
The standard deviation of the portfolio P&L distribution (in millions of home currency units). This value
depends on your choice of pv_flag.
Midpoints
VARCARLO creates a set of evenly-distributed bins between the minimum and maximum values of
portfolio P&L distribution. (You can control the histogram with the min_midpoint and interval arguments.)
the formula’s array range) and by the minimum and maximum values generated by the simulation. A data
corresponding frequency of data points falling in that bin. (If you want the entire distribution then specify
distribution.) These values depend on your choice of pv_flag.
Frequencies
The number of occurrences of the portfolio P&Ls (out of the total number of iterations) falling in the bin
located at the corresponding midpoint. The sum of all the frequencies equals the number of iterations in the
simulation. These values depend on your choice of pv_flag.
The output format depends on the size of the array range entered and on whether VARCARLO or
VARCARLO2 is used:
VARCARLO output:
1x1 VaR
1x2 VaR MTM
2x2 VaR MTM

SE(VaR) VaR/MTM
3x2 VaR MTM

SE(VaR) VaR/MTM
E(P&L) SD(P&L)
Nx2 VaR MTM

SE(VaR) VaR/MTM
E(P&L) SD(P&L)
... ...
VARCARLO2 output:
1x1 VaR
1x2 VaR MTM
2x2 VaR MTM

SE(VaR) MTMh
3x2 VaR MTM

SE(VaR) MTMh
4x2 VaR MTM

SE(VaR) MTMh
E(P&L) SD(P&L)
Nx2 VaR MTM

SE(VaR) MTMh
E(P&L) SD(P&L)
... ...

As iterations increases, calculation time increases approximately linearly.
iterations and seed are truncated to integers.

 cross_corrs does not evaluate to TRUE or FALSE.
 iterations is non-numeric or negative.
 seed is non-numeric or negative.
 distribution specifies an invalid file name or path.
 drift, pv_flag, and no_analytic_limit do not evaluate to TRUE or FALSE.
Perform comparative analysis of different scenarios by providing a unified display of histograms, profit and
loss tail analysis, and summary VaR and shortfall results. It accepts subjective weights for each input
scenario, thus allowing the creation of a Value at Risk analysis that can potentially incorporate a variety of
different scenarios. Scenarios are input through flat files that can be generated by the VARCARLO2,
HISTORICALVAR, and PORTVARANL functions.
varworks.xls (VARCOMPARE worksheet)
VARCOMPARE(confidence, scenario_files, scenario_weights, out_choice, min_max_bins)
confidence is a number between 0 and 1, exclusive, specifying the size of the VaR confidence level used to
generate VaR, and expected shortfall results. If out_choice is equal to ‘S’, confidence is used to determine both
profit and loss risk numbers (see Remarks below), with confidence determining the loss quantile (say 95%),
and (1-confidence) the profit quantile. If out_choice is equal to ‘T’ and confidence is greater (less) than 0.5, the
loss (profit) tail of the cumulative distribution is displayed.
scenario_files is a 1xN (or Nx1) array containing the name of the files to be used in the comparative analysis.
Properly formatted files can be generated by using the VARCARLO2, HISTORICALVAR, and
PORTVARANL functions, see a description of the file_name output in those files.
scenario_weights is a 1xN (or Nx1) array containing the weight to be assigned to each of the scenarios.
Weights are normalized to sum to one, and are used to generate a composite histogram that combines
different scenarios. If omitted, equal weighting is assumed.
out_choice is text specifing whether histograms (out_choice= ‘H’), tails (out_choice= ‘T’), or summary risk
numbers (out_choice= ‘S’) are generated as output. If omitted, ‘S’ is assumed. See Remarks below for details
on the generated output.
min_max_bins is a 1x2 (or 2x1) array specifying the minimum and maximum values used to generate the
common histogram for the different scenarios. If omitted, and out_choice = ‘H’, the realized maximum loss
and profit as specified in the scenario_files input are used. If omitted, and out_choice = ‘T’, the realized
maximum loss and the largest VaR among the different scenarios are used.
VARCOMPARE returns the following values:
Methodology
A label of the methodology used to generate risk numbers and histograms (‚Monte Carlo‛, ‚Historical‛,
‚Analytic‛, ‚EVT‛, or ‚Weighted‛).
VaR
The diversified Value at Risk (in millions of home currency units). The VaR number depends on your choice
of confidence. The VaR number refers to the loss tail of the P&L distribution. Note that a positive VaR
corresponds to a loss.
VaR(+)
The diversified Value at Risk (in millions of home currency units). The VaR(+) number depends on your
choice of confidence. The VaR(+) number refers to the profit tail of the P&L distribution. Note that a positive
VaR corresponds to a profit.
ETL (Shortfall)
The expected tail loss (in millions of home currency units), conditional on the occurrence of a loss greater
than the VaR. The shortfall is therefore a measure of the fatness of the loss tail of the P&L distribution. It
depends on your choice of confidence.
ETG
The expected tail gain (in millions of home currency units), conditional on the occurrence of a profit greater
than the VaR(+). ETG is therefore a measure of the fatness of the profit tail of the P&L distribution. It
depends on your choice of confidence.
EVT-VaR
The diversified Value at Risk (in millions of home currency units) obtained by applying Extreme Value
Theory to the loss tail of the P&L distribution. EVT-VaR can only be generated for Monte Carlo and
Historical scenarios, provided the appropriate EVT parameters are included in the input scenario file. EVT-
VaR depends on your choice of confidence, and on the evt_tail used to fit the distributional tail. Note that a
positive EVT-VaR corresponds to a loss.
EVT-VaR(+)
The diversified Value at Risk (in millions of home currency units) obtained by applying Extreme Value
Theory to the profit tail of the P&L distribution. EVT-VaR(+) can only be generated for Monte Carlo and
Historical scenarios, provided the appropriate EVT parameters are included in the input scenario file. EVT-
VaR(+) depends on your choice of confidence, and on the evt_tail used to fit the distributional tail. Note that a
positive EVT-VaR(+) corresponds to a profit.
EVT-ETL (Shortfall)
The expected tail loss (in millions of home currency units), conditional on the occurrence of a loss greater
than EVT-VaR, obtained by applying Extreme Value Theory to the loss tail of the P&L distribution.
EVT-ETG
The expected tail gain (in millions of home currency units), conditional on the occurrence of a profit greater
than EVT-VaR(+), obtained by applying Extreme Value Theory to the profit tail of the P&L distribution.
Midpoints
VARCOMPARE creates a set of evenly-distributed bins between the minimum and maximum values of
portfolio P&L distribution. (You can control the histogram with the min_max_bins argument, and with the
dimension of the selected output array.) Data in this form can be easily charted as a histogram. Bins are
defined by boundary values in ascending order. The values of the bin midpoints are determined by the total
number of bins (specified by the size of the formula’s array range) and by the minimum and maximum
values generated by the simulation. A data point is counted in a particular bin if it is greater than the bin’s
lower boundary value and less or equal to a bin’s upper boundary value. All values below the first bin’s
lower boundary value are counted in the first bin. Each bin is marked by a midpoint (the portfolio P&L in
millions of home currency units) and a corresponding frequency of data points falling in that bin.
Frequencies
The number of occurrences of the portfolio P&Ls falling in the bin located at the corresponding midpoint,
normalized by the total number of occurrencies. The sum of all the frequencies equals one.
Cumulatives
The cumulative probability of the portfolio loss falling in the bin located at the corresponding midpoint, or
in bins corresponding to larger losses.
The output format depends on the size of the array range selected for Excel output and the value of
out_choce.
If out_choce is omitted, or it is equal to ‘S’ the return array displays information about the methodologies
employed, and various risk numbers. If m=N+1 (with N equal to the number of scenario files being input),
the last column is obtained by creating a ‚weighted histogram‛, and by computing the non-evt risk numbers
of the weighted histogram If the number of rows is k, with k<9, the first k-1 risk numbers will be displayed.
9xm Methodology 1 < Methodology m

VaR 1 < VaR m
ETL 1 < ETL m
VaR(+) 1 < VaR(+) m
ETG 1 < ETG 1 m
EVT-VaR 1 < EVT-VaR m
EVT-ETL 1 < EVT-ETL m
EVT-VaR(+) 1 < EVT-VaR(+) m
EVT-ETG 1 < EVT-ETG m
If out_choce is equal to ‘H’ the return array displays information about histograms corresponding to different
scenarios, in the order specified in the scenario_files input array. If m=N+1 (with N equal to the number of
scenario files being input), the last column displays the ‚weighted histogram‛ where each scenario is
weighted by the input provided in scenario_weights.
L x (m+1) Midpoint(1) Frequency(1) < Frequency(1)

Midpoint(2) Frequency(2) < Frequency(2)
< < < <
Midpoint(L) Frequency(L) < Frequency(L)
If out_choce is equal to ‘T’ the return array displays information about the tails corresponding to different
scenarios, in the order specified in the scenario_files input array. For each scenario file containing information
about Generalized Pareto distribution parameters, the corresponding tail fit is also provided with the
appropriate label.
(L+1) x Methodology 1 < Methodology m

(m+1) Midpoint(1) Cumulative (1) < Cumulative (1)
< < < <
Midpoint(L) Cumulative (L) < Cumulative (L)
Returns the VaRdelta array of a portfolio’s cash flow map.
varworks.xls (VaRdelta worksheet)
VARDELTA(cash_flow_array, maturity_list, asset_list, vol_data, corr_data, horizon, confidence,

home_ccy, pv, cross_corrs, asset_codes, yield_curves)
example, if you are using a monthly (25 days) RiskMetrics dataset and want a 5-day horizon then specify 5.
VaR.

information.
The VaRdelta array contains scaled derivative values that represent the cash flow vector of the fastest rate of
increase of VaR. See VaRdelta for more information.
Taking the inner product of VARDELTA with a mapped candidate trade’s cash flows using
INCREMENTALVAR indicates whether such a trade will be VaR increasing or VaR decreasing and by what
amount.
The value of pv in VARDELTA must be the same as the value of pv in CASHFLOWMAP.

 horizon < 1.
 pv and cross_corrs do not evaluate to TRUE or FALSE.
Returns volatility and correlation data for given vertices. Use VCDATA to retrieve and transform data in the
volatility-correlation dataset. VCDATA can also be used to display additional information associated with
equities, provided such information is made available through the asset file.
varworks.xls (VCDATA worksheet)
VCDATA(vol_data, corr_data, vertex, vertex2, value, confidence, home_ccy, cross_corrs, asset_codes)
asset is a currency or commodity code and asset_class[maturity] is an asset class code and maturity (where
applicable). Examples: ‚GAS.C12‛, ‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛.
vertex2 is text specifying the second asset, asset class, and maturity in the format asset.asset_class[maturity]
where asset is a currency or commodity code and asset_class[maturity] is an asset class code and maturity
(where applicable). vertex2 is required if value equals ‚c‛ and ignored otherwise. Examples: ‚GAS.C12‛,
‚USD.Z30‛, ‚JPY.SE‛, or ‚GBP.XS‛.
value is text specifying the value to return.
value Value returned

‚c‛ Correlation of vertex and vertex2, retrieved from corr_data. A number between
-1 and +1, inclusive.
‚p‛ Price (asset classes C, SE, and G), exchange rate (XS), or interest rate (R, S, Z) of
vertex, retrieved from vol_data. Interest rates are expressed in fractional form,
for example, 5% is 0.05. Prices are expressed in home_ccy currency units.
‚v‛ or omitted Price volatility of vertex, retrieved from vol_data. Expressed in fractional form,
for example, 5% is 0.05.
‚y‛ Yield volatility of vertex, retrieved from vol_data. Yield volatilities are returned
for interest-rate vertices only (asset classes R, S, and Z) and expressed in
fractional form, for example, 5% is 0.05.
‚n‛ Equities only: equity name as specified in the asset file in the field beginning
with the string ‚NAME=‛.
‚t‛ Equities only: equity ticker as specified in the asset file in the field beginning
with the string ‚TICKER=‛.
‚o‛ Equities only: equity country as specified in the asset file in the field beginning
with the string ‚COUNTRY=‛.
‚i‛ Equities only: equity industry as specified in the asset file in the field
beginning with the string ‚INDUSTRY=‛.
‚d‛ Equities only: equity trade volume as specified in the asset file in the field
beginning with the string ‚TRADEVOL=‛.
‚m‛ Equities only: equity market cap as specified in the asset file in the field
beginning with the string ‚MKTCAP=‛. The market cap in the asset file should
be specified in units of the ccy currency, specified in the asset file. The output
of VCDATA is quoted in units of 1,000,000 home_ccy currency.
‚l‛ Equities only: equity liquidity measure, computed as the ratio between the
trade volume (see ‚d‛ above), and the number of outstanding shares (obtained
by dividing the market cap by the equity price, see ‚m and ‚p‛ above).
‚x‛ Equities only: currency as specified in the ccy field of the asset file.
‚b‛ Equities only: beta as specified in the beta field of the asset file.
‚e‛ Equities only: proxy index as specified in the equity_index field of the asset file.
home_ccy is text specifying the rebase currency. vol_data must contain sufficient exchange rate information
to rebase the vertex and vertex2 assets. If home_ccy is omitted then results are not rebased, that is, they are left
in local currency terms.
confidence is a number specifying the one-tailed confidence level for the price or yield volatility. confidence
applies only if value is ‚v‛ or ‚y‛. If confidence is greater than 0.5 and less than one (0.5, 1) then it is
interpreted as a confidence level and converted into a volatility multiplier by calculating the inverse of the
standard normal cumulative distribution with confidence as the probability corresponding to the normal
distribution. If confidence is greater than or equal to one [1, +) then it is interpreted as a simple constant and
used as the volatility multiplier. Note that the confidence level and multiplier are the same quantity
expressed in different mathematical terms. For example, if confidence equals 0.95 then it is interpreted as the
95% confidence level and converted to a volatility multiplier of 1.644853. If confidence equals 1.65 (which
corresponds to the 95.0529% confidence level) then the volatility is multiplied by 1.65. If you are using
RiskMetrics or MakeVC files, set confidence equal to 1.65. If confidence is omitted, it is assumed to be 1.65.

information.
Volatilities and interest rates are returned in fractional form. For example, 5% is returned as 0.05.
The field delimiter in corr_data, vol_data, and asset_codes must be a comma ‚,‛.
Text comparisons are case insensitive.
If the result can be converted into a number then a number is returned, otherwise -1 is returned.
If corr_data, vol_data, and asset_codes do not contain paths then the current directory is searched.
For confidence, you can use the Microsoft Excel worksheet functions NORMSDIST to transform a volatility
multiplier into a confidence level and NORMSINV to transform a confidence level into a volatility
multiplier.
When value equals ‚r‛ and vertex specifies an interest-rate asset class (R, S, or Z), then missing or non-
numeric interest rates (yields) are estimated using the formula
yield = price_volatility / (yield_volatility  duration),
where duration is the maturity of the yield in years. This estimation is performed in RiskMetrics files where
money market yields are not published.

 corr_data, vol_data, and asset_codes are not found.

 You do not have read permission for corr_data, vol_data, and asset_codes.
 vertex2 is blank and value equals ‚c‛.
 A record containing vertex is not found in vol_data.
 A record containing both vertex and vertex2 is not found in corr_data.
 confidence is less than or equal to 0.5.
 home_ccy is not found in vol_data and corr_data.
 cross_corrs does not evaluate to TRUE or FALSE.
Returns the version of the installed VaRworks add-in, as text.
varworks.xls (Inputs worksheet)
VWVERSION(verbose)
verbose is a logical value specifying the type of information to return. If verbose is FALSE or omitted, only
the version is returned. If verbose is TRUE then version, licensing, and build information is returned.
If the VaRworks add-in is not installed then VWVERSION returns the #NAME? error value.
If you are using version 2.3 of VaRworks, then:

VWVERSION() equals ‚2.3‛
When an error is detected it is written to the error log. The error log is a text file, named varworks.log, that is
created (or appended to if it already exists) when you recalculate a worksheet containing a VaRworks
function. The error log is overwritten when you start a new VaRworks session (that is, quit Microsoft Excel
and start again) but grows without bound during any particular session. Do not edit or delete the error log
while VaRworks is loaded or running. To view the error log, click View Error Log in the VaRworks template
or open it in a word processor or text editor. (In Windows 95/98 you cannot view the error log in Wordpad
while VaRworks is running—use Notepad instead.)
There are two types of errors posted to the error log: warnings and fatal errors. Fatal errors halt calculations,
warnings do not. Even though warnings do not halt calculations, examine them anyway. For example, a
warning is generated if your portfolio contains expired instruments. Fatal errors require corrective action on
your part (you must edit the text files or change the function arguments). Examples of fatal error are invalid
dates (February 30, 1996), invalid numbers (12A45), and logic errors (a bond with a maturity date falling
before its issue date). The sample portfolio files contain no fatal errors but may generate warnings,
depending on the effective date you use.
The error log is located in your temporary directory. VaRworks uses the Windows GetTempPath function to
determine the temporary directory.
Windows 95/98: The GetTempPath function gets the temporary file path as follows:
1. The path specified by the TMP environment variable.
2. The path specified by the TEMP environment variable, if TMP is not defined or if TMP
specifies a directory that does not exist.
3. The current directory, if both TMP and TEMP are not defined or specify nonexistent
directories.
Windows NT/2000: The GetTempPath function does not verify that the directory specified by the TMP or
TEMP environment variables exists. The function gets the temporary file path as follows:
1. The path specified by the TMP environment variable.
2. The path specified by the TEMP environment variable, if TMP is not defined.
3. The Windows directory, if both TMP and TEMP are not defined.
Unix: ~/tmp
1. Start a command prompt

Click Start, point to Programs, then click MS-DOS Prompt (or Command Prompt).
2. Type set
A list of current environment variables is displayed. Your temporary directory is indicated by
the TMP (or TEMP) variable.
3. Type exit to exit the command prompt.
Some error log messages describe mistakes in text files. These messages contain the fields listed in the
following table.
Error Log Record Layout (Text File Errors Only)
# Field Description
1 time_stamp The date and time the error was detected. Formatted yyyy-mm-dd
hh:mm:ss. Example: 1995-06-22 17:54:28.
2 severity The severity of the error. Either ‚WARNING‛ or ‚FATAL‛.
3 function_name The name of the library function which generated the error.
4 filename The file name and path of the text file in which the error occurred.
5 line_number The line number (not the record number) of text file in which the error
occurred (if applicable).
6 field_name The name of the field where the error occurred (if applicable).
7 value The value generating the error (if applicable).
8 error_msg A description of the error.
This section lists the most common messages with their possible causes and solutions.
Possible cause Suggested action

[filename] is not in the current Change the current directory: choose Open (File menu),
directory. change the directory, and then click Cancel.
-or-
Precede [filename] with a path. For example, change
foo.txt to c:\fea\varworks\foo.txt
For more information see ‚How do I tell VaRworks where

to look for files?‛ in Answers to Common Questions.
Misspelling [filename]. Correct the spelling.
Invalid path to [filename] specified. Correct the path.
You do not have permission to read Contact your system administrator and get read
[filename]. permission for the file.
Low memory. Close other applications or add RAM or increase the swap
file size (virtual memory).
Calculation is set to Automatic. Choose Options (Tools menu), click the Calculation tab,
select Manual under Calculation, clear the Recalculate
before Save check box, and then click OK.
-or-
These errors occur in functions that return arrays and indicate that VaRworks successfully generated a cash
flow but was unable to display it. This can be corrected by modifying the asset_list (usually) or maturity_list
(infrequently) argument of the VaRworks functions to contain the asset code or maturity code of [cash flow].
You may expand the array range and add the appropriate code or change one of the existing asset_list or
maturity_list codes to accommodate [cash flow]—do not to change one that already contains holdings or the
same error message will repeat for the overwritten entry.
For example, if the currency of [cash flow] is NZD then the asset_list range must include a cell containing
NZD.
IntrLib is the FEA interest-rate derivatives library. VaRworks was unable to process one of your interest-rate
derivatives: callable bonds, bond options, caps, floors, swaptions, and so forth. The most common cause
omitting the VOLATILITY header from the file or specifying an invalid value for the MEANREVERSION or
header. See Headers for more information.
IntrLib Error Codes

Error Meaning
1 One or more of the argument validity rules were violated. Make sure you have included
a VOLATILITY header in the file and set a valid value for the MEANREVERSION
header.
2 Insufficient memory on your computer.
3 Error during execution of routine. Contact FEA if this error occurs.
4 Newton-Raphson search to fit tree to term structure failed.
5 No roots found for bisectional search routine. This error will occur for analytical
functions when a solution to the pricing formula cannot be found.
6 Too many roots exist for the bisectional search routine. This error will occur for
analytical functions when more than one solution to the pricing formula exists and a
unique solution can therefore not be found.
9 Licensing failure. Contact FEA.
VaRworks was unable to make sense of the entry value in field field_name on line line_number in the text file
filename; the reason for the error is described by error_msg. You must edit the text file and change value to a
valid entry.
For example, the error message ‚Thu Mar 21 16:51 FATAL: FeaParseCashFlow1_0, cf.txt:9, ASSET, XXX,
Invalid asset specified ‘XXX’‛ means that VaRworks encountered the invalid asset code ‘XXX’ in the Asset
field on line 9 of the file cf.txt.
The #N/A error value occurs when there is an error in the function arguments or the text files containing
volatility, correlation, or trade data. When #N/A appears, the cause can usually be found by examining the
error log varworks.log in your TEMP directory.
#N/A most commonly occurs because VaRworks cannot locate a volatility, correlation, or trade file in the
current directory—the FEA_ERR_NOTFOUND error. To change the current directory in Excel, choose Open
(File menu), change to the \fea\varworks directory (or wherever VaRworks is installed), and click Cancel.
Press CTRL+ALT+F9 to recalculate.

The current directory does not Change the current directory: choose Open (File menu),
contain the data files. change the directory to \fea\varworks (or wherever
VaRworks is installed), and then click Cancel.
-or-
Add paths to the file names. For example, change vol.txt
to c:\fea\varworks\vol.txt
For more information see Tutorial.
Your trade files contain errors. Read the VaRworks error log (varworks.log).
Array size to small. If the user-specified array range is too small to contain all
the results of an (array-returning) worksheet function then
#N/A is returned in every cell of the array. If the array
range is too large, the correct answers are returned in the
usual places and #N/A is returned in each of the
extraneous cells. This affects the CASHFLOWMAP,
PORTVARANL, VARANLU, VARCARLO, and
VARDELTA worksheet functions.
Calculation is set to Automatic Click Options (Tools menu), click the Calculation tab,
instead of Manual. select Manual under Calculation, clear the Recalculate
before Save check box, then click OK.
Incorrect system date. Correct the system date using the Windows Control Panel.
You are running Microsoft Excel 97 Array functions do not work properly in Microsoft Excel
(v. 8.0) (choose Help|About for 97 (v. 8.0). Contact Microsoft and upgrade to Microsoft
version). Excel 97 SR-1 (v. 8.0a) or higher.
Invalid or missing function For example, too many or too few arguments specified.
arguments. Also, check the Remarks section of the function
description in the User’s Guide and make sure each
argument’s value complies with the conditions.
Low memory. Close other applications or increase the swap file size
(virtual memory) or add RAM.

Corrupt data files. If you are using your own files, recreate the files. If you
are using the files that came with VaRworks then reinstall
VaRworks. If you are using RiskMetrics, download the
files again.
The #NAME? error value occurs when you use a name that Microsoft Excel doesn’t recognize.

VaRworks add-in not loaded. Load the VaRworks add-in varworks32.xll by choosing
Add-ins (Tools menu). If the add-in is not listed, click
Browse to locate it.
Demo period has expired. 1. In Windows, click Start|Programs|FEA| FEA License

-or- Manager.
Licensing failure. 2. Click Show Installed Keys.
Contact FEA if the feature 55 license has expired.
Deleting or failing to define the Define the name using the Insert-Name-Define command.
name.
Misspelling the name. Correct the spelling. Highlight the misspelled name in the
formula bar, then select the name from the name box at the
left end of the formula bar.
Misspelling the name of a function. Correct the spelling. Use the Function Wizard to insert the
correct function name into the formula.
Entering text without double Enclose text in the formula in double quotation marks.
quotation marks in the formula.
Microsoft Excel interprets your
entry as a name even though you
intended it as text.
Omitting a colon in a range Correct the formula.

reference.
You have used a formula that produces a result too long to fit in the cell. This error value also occurs when a
constant numeric value is too long. This is not an actual error value, but an indicator that the column needs
to be wider.
To adjust column width

1. Select the columns whose width you want to adjust. To select a column, click the column
heading (the lettered gray area at the top of each column).
2. Drag the border at the right of the column heading until the column is the width you want.
The column width displayed at the left end of the formula bar is the average number of
characters of the standard font that fit in a cell.
Note To make the column width fit the contents, double-click the border to the right of the column
heading.

Demo period has expired. 1. In Windows, click Start|Programs|FEA| FEA License
-or- Manager.
Licensing failure. 2. Click Show Installed Keys.
Contact FEA if the feature 55 license has expired or
contact your system administrator if your license server
is down.
FEA hardware lock is missing or Check the parallel port on the back of your PC and make
improperly installed (hardware- sure the FEA hardware lock is fitted securely in the
lock-based licensing only). parallel (printer) port.
The parallel (printer) port is not 1. On the desktop, double-click My Computer

recognized by your PC (hardware- 2. Double-click Control Panel.
lock-based licensing only). 3. Double-click System.
4. Click the Device Manger tab.
5. Click Ports.
6. Verify that the system recognizes the Printer Port
(LPT1).
If your PC does not recognize the parallel port then
contact your system administrator or the hardware
manufacturer.
You have moved or deleted [filename]. If [filename] is varworks32.xll (the VaRworks add-in) then Excel
choose Add-Ins (Tools menu). In the Add-ins Available box, select the check box next to VaRworks. If the
add-in is not listed, click Browse to locate it. It is located in the directory in which you installed VaRworks
(default: c:\fea\varworks).
This error message usually indicates a Microsoft Excel Setup problem rather than an add-in problem. The
object library provides information to Visual Basic macros. (To learn the name of the object library file(s),
search Excel Help for object library) Deleting the file VBA.INI doesn’t usually help. Instead, start Excel and
insert a module by clicking Insert-Macro-Module. If you the same error message is displayed then your VB
object library isn’t registered. Search your hard drive for *.REG files. If you see the file OLE2.REG then
double-click it and it will register the object library. Register Excel by double-clicking EXCEL.REG. Now try
inserting a module in Excel again. If that doesn’t work, try re-installing Excel with all the installation options
selected.
The size of a portfolio is limited by available memory and the constraints of the operating system.
For information about performance for differently sized portfolios, with typical datasets, on currently
available platforms, contact FEA.
Manual (clear the Recalculate before Save check box). To set the calculation mode to Manual choose Options
(Tools menu), click the Calculation tab, under Calculation choose Manual and clear the Recalculate before
Save check box.
Yes. VaRworks is based on the VaRlib programming library, which can be integrated with larger systems.
MakeVC creates custom volatility-correlation datasets from historical price and interest-rate time series.
Contact FEA for more information.
Several utilities are included:

 The VaRworks Macros are Microsoft Excel-based tools.
 Portfolio Manager let you keep your trades in an Excel workbook instead of text files.
 GENRATES extracts exchange rate and yield curve files from volatility files.
These utilities add functionality and are not required to run VaRworks properly.
The VaRworks Macros are Visual Basic for Applications (VBA) macros included in the VaRworks template
varworks.xls. They are convenient tools but are not required to run VaRworks properly.
Macro Macro type and description

CalcAll (Sub) Forces recalculation of every cell in the entire workbook
whether or not their precedent cells have been changed.
CalcSelection (Sub) Recalculates the current selection.
CalcSheet (Sub) Recalculates the current worksheet.
Change3Dview (Sub) Toggles the view of active 3D chart between the default view
and a view from directly above.
ClearVarHistory (Sub) Activates the VaR history sheet and clears the range
containing the historical data. This macro is not undo-able.
ErrorLog() (Function) Returns a string containing the path and name of the
VaRworks error log.
GotoAppBookmark (Sub) Assign this macro to a button, label, text box, list box, or
drop down list. It will activate Microsoft Word, open the
application’s User’s Guide, and go to the bookmark named by the
text label or list item.
GotoSheet (Sub) Assign this macro to a button, label, text box, list box, or
drop down list. It will activate the sheet named by the text label or
list item.
GotoWebPage (Sub) Assign this macro to a button, label, text box, list box, or
drop down list. It will activate the default Browser, and go to the
URL named by the text label or list item.
InitDropDowns (Sub) Populate all the DropDown navigation controls with
(visible) sheet names.
NextSheet (Sub) Activates the next visible sheet (Chart, DialogSheet, Module,
or Worksheet).
PrevSheet (Sub) Activates the previous visible sheet (Chart, DialogSheet,
Module, or Worksheet).
PrintActiveSheet (Sub) Prints the active sheet.
UpdateControlChart (Sub) Redraws and rescales the control chart with the current
historical data.
UpdateVarHistory (Sub) Gets the current effective date, VaR, and M-T-M from the
active workbook and appends them to the end of VaR history
range.
ViewErrorLog (Sub) Opens the error log in a file viewer.
Macro Macro type and description

ViewFileAtCursor (Sub) Opens the file named in the active cell in a file viewer.
ViewFileToLeft (Sub) Attach this macro to a button. Opens the file named in the
cell to the left of the button in a file viewer.
1. Open the workbook that contains the macro.

2. On the Tools menu, point to Macro, and then click Macros.
3. In the Macro name box, enter the name of the macro you want to run.
4. Click Run.
Note To interrupt a macro before it completes its actions, press ESC.
The VaRworks Macros are assigned to various buttons on the VaRworks template. You can create your own
button or graphic object and assign it to a macro. When you click the button or graphic object, the macro
will run automatically. (To learn how to create a button or a graphic object, search Excel Help for drawing
objects.)
1. Using the right mouse button, click the button or graphic object.
2. On the shortcut menu, click Assign Macro.
3. In the Macro Name/Reference box, enter a macro name and then click OK.
The macro source code is in a hidden module. To display it, do the following:
1. On the Format menu, point to Sheet, and then click Unhide.
2. In the Unhide Sheet box, double-click Module1.
1. If the Module1 sheet isn’t active, click the Module1 tab to make it active.
2. On the Format menu, point to Sheet, and then click Hide.
GENRATES (for GENerate RATES) is a stand-alone utility program that extracts yield curves and foreign
exchange rates from a volatility file and creates Exchange Rate and Yield Curve files. You can use these files
in VaRworks worksheet functions that have exchange_rates or yield_curves arguments.
The GENRATES command-line function genrates.exe is used at the Windows or Unix command prompt.
The syntax is (respect capitalization):
genrates [-a asset_file] [-f xrate_file] [-y ycurve_file] vol_file
The name of an input asset file generated by MakeVC. assets_file may include a path. -a is required if vol_file
is a MakeVC or custom volatility file. Omit -a if vol_file is a RiskMetrics file.
Names the output Exchange Rate file xrate_file. xrate_file may include a path. Existing files are overwritten
without warning. If -f is omitted, the exchange rate file is named xrate.txt.
Names the output Yield Curve file ycurve_file. ycurve_file may include a path. Existing files are overwritten
without warning. If -y is omitted, the yield curve file is named ycurve.txt.
Required. Specifies the name of a RiskMetrics or MakeVC volatility file.
If vol_file is a RiskMetrics file, type:

genrates vol.txt
to create the Exchange Rate file xrate.txt and the Yield Curve file ycurve.txt.
If vol_file is a MakeVC or custom volatility file, type:

genrates -a assets.txt vol.txt
where assets.txt is the asset codes file generated by MakeVC.
Missing money market yields in RiskMetrics volatility files are replaced with estimated yields derived using
the following formula
yield = price_vol / (yield_vol * duration)
where price_vol is the price volatility, yield_vol is the yield volatility, and duration is the maturity of yield in
years.
Code Credit sector

Z Government
S Swap
R Money market or LIBOR (<=360-day maturity)
AAA Corporate Credit Ratings
AA
A
BBB
BB
B
CCC
D
Custom defined credit ratings can also be used by adding to the Corporate Credit Ratings string a colon
separator and a user defined name, for instance B:MYCREDIT, see Assets on page 103 for how to specify
custom credit ratings in the dataset. If custom credit ratings rates are entered as a spread, the user specified
name must be prepended by the string S:, as in B:S:MYCREDIT, where in VaRworks the spread is defined
with respect to the government curve Z.
Vertices correspond to the risk factors used to analyze a portfolio. Each vertex name consists of three
components: an Asset, an Asset Class, and a Maturity.
Where Maturity components of a vertex name appear as input in volatility, correlation, stress, or history
files, an explicit unit of measurement may be specified by appending a case insensitive suffix to the
numerical value. The recognized suffixes are:
 Y or Year
 M or Month
 D or Day
When no explicit unit of measurement is specified, an implicit unit of measurement is determined according
to the following rules:
 Foreign Exchange and Equity Index vertices (asset classes SE and XS) must have a
maturity of 0.
 For Commodity vertices (asset class C), a unit of Months is always implied, unless Fixed
Expiration prices are used, see below.
 For Money Market vertices (asset class R) a unit of Days (360 days/year convention) is
always implied.
 For Swaps and Government Bond vertices (asset class S and Z) a unit of Years is always
implied.
 For all other vertices, a two-digit maturity implies a unit of Years, and a three-digit
maturity implies a unit of Days (360 days/year convention).
Note that for commodity risk vertices associated to constant maturity futures prices the
maturity component is specified as above. For commodity vertices associated to fixed
expiration futures prices the maturity component is specified as a date, formatted according to
the DATEORDER header. See Constant Maturity vs. Fixed Expiration Prices on page 54.
Implied volatility vertices are represented by a string of the form X_IV(K,T), where X
represents the name of the option’s underlying, K is the numerical value of the strike, and T is
a maturity of the risk factor expressed in years or as a date.
This section lists the credit ratings and maturities currently used in RiskMetrics datasets. Note that not all
maturities apply to every currency or commodity in an asset class. For example, there are 30-year
government bond rates (Z30) for USD but not NZD. In addition to the asset classes in the table below, the
user can specify arbitrary equity classes corresponding to spot maturity in the asset_codes file (see Asset).
Asset
Class
Foreign Equity Money Gov’t Commod-
Maturity Exchange Indices Market Swaps Bonds ities
Spot XS SE - - - C00
1m - - R030 - - -
3m - - R090 - - C03
6m - - R180 - - C06
12m (1y) - - R360 - - C12
15m - - - - - C15
18m - - - - - C18
24m (2y) - - - S02 Z02 C24
27m - - - - - C27
36m (3y) - - - S03 Z03 C36
4y - - - S04 Z04 -
5y - - - S05 Z05 -
7y - - - S07 Z07 -
9y - - - - Z09 -
10y - - - S10 Z10 -
15y - - - - Z15 -
20y - - - - Z20 -
30y - - - - Z30 -
The Builder templates are a set of three Microsoft Excel spreadsheet-based utility applications designed to
demonstrate VaRworks' drill-down report building capability. The three Builder templates can be used to
quickly and easily perform the following tasks; create portfolio files specifically intended for drill-down
analysis, output portfolio level VaR results, and create interactive drill-down reports for risk attribution and
limit management purposes. The names of the three Builder templates are portfolio_builder.xls,
varreport_builder.xls, and stressreport_builder.xls.
Note that the Builder templates do not currently support the inclusion of the implied volatilities as risk
factors. On the other hand, Risk Analyst application provided by FEA
supports this feature.
Step 1. The Builder templates are accessible via the

‚FEA‛ selection on the standard Excel tool bar.
Step 2. Select ‚VaRworks –

Value at Risk‛ from the
Step 3. Double click the
‚Products‛ list.
desired Builder template
from the ‚Templates‛ list.
The Portfolio Builder template is designed to create a set of portfolio text files specifically for the VaRReport
Builder and StressReport Builder templates. The Portfolio Builder template enables users to attach ‚trade
identifier‛ fields to each trade in the trade input sheets, facilitating the rapid creation of drill-down reports
within the VaRReport and StressReport templates. The following core portfolio creation tasks are covered
in this tutorial:
1. Selecting Instruments
2. Selecting Trade Identifiers
3. Inputting Trade Information
4. Creating Portfolio Files
Step 1. Select and highlight trade type

valuation models from the ‚Instruments‛ list
corresponding to trade types in the portfolio to
be analyzed.
Step 2. Once a trade type is selected and highlighted in the ‚Instruments‛ list click the ‚Add‛ button
to add the trade type to the ‚Selected Instruments‛ list. A trade type specific input worksheet will be
added to the workbook. To remove a selected instrument, highlight the trade type in the ‚Selected
Instruments‛ list and click the ‚Delete‛ button.
Step 1. Select and highlight a trade ID field from the default

‚Trade Identifiers‛ list. Click the ‚Add‛ button to insert the
trade ID into the ‚Selected Trade Idendtifiers‛ list. The trade
identification field will automatically appear in the trade
input worksheets.
Step 2. To add a new trade ID field click the ‚Add

Trade ID‛ button. To remove a trade ID field click the
‚Delete Trade ID‛ field.
Step 1. Portfolio Builder automatically creates formatted, trade type specific

worksheets based on the instruments and trade ID fields selected on the
input page. Information required for instrument valuation is entered on the
right hand side of the ‚Trade ID‛ column head.
Step 2. Enter trade ID information on

the left hand side of the ‚Trade ID‛
column head
Step 1. Once all trade data is entered, name the

input portfolio and click the ‚Create Portfolio‛
button. Portfolio files are saved to the default
directory and the address is automatically
displayed above the portfolio name box.
Step 2. In order to create a portfolio based on a sub set of the trades in the total
portfolio, click the toggle boxes in the ‚SubPortfolio Specifications‛ section, then
select and highlight a single trade ID from each trade ID category. Once the sub-
portfolio has been defined enter a sub portfolio name and click ‚Create
SubPortfolio‛. The sub-portfolio file is automatically saved to the default directory.
The VaRReport Builder template is designed to output VaR analysis information at the portfolio and sub-
portfolio levels based on the portfolio files generated by the Portfolio Builder template. The VaRReport
Builder workbook includes portfolio level VaR results, a ‚what-if‛ incremental VaR analysis tool, and an
interactive drill-down report using Microsoft Excel’s pivot table functionality. The default drill-down report
shows M-t-M, Component VaR and VaR Beta results for each of the sub-portfolio levels specified at the
portfolio building stage. The following core data analysis tasks are covered in this tutorial:
1. Entering Data Files & Model Parameters

2. Manipulating Drill Down Reports
3. Adding &Removing Sub-Portfolio Levels & Calculation Results
4. Calculating Sub-Portfolio Level Results
5. Utilizing the Incremental VaR Report
Step 1. First, specify the name and address of the volatility, correlation, asset, data, and
portfolio files. If the file location is not indicated the default directory is the assumed file
location. Next, Select the appropriate time horizon, home currency, effective date and
confidence interval.
Step 3. Select the output

calculations
Step 4. Press the ‚Calculate‛

button.
Step 2. Ensure that model parameter values listed within the

Analytic, Monte Carlo, and Historical VaR boxes are
appropriate. Refer to the Tutorial section of this manual for
assistance in selecting parameter values.
In the example shown here, double clicking a counterparty name

reveals calculation results for the underlying trading desks
associated with the selected counterpary.
Double clicking a trading desk reveals calculation results for all

instrument types associated with trading desk ‚D1‛ and the trading
counterparty ‚Duke‛.
In this example the ‚Counterparty‛ category has been dragged from the
main report table and dropped above the table to create a counterparty
page. If a specific counterparty is selected only associated trading desks
and instrument types are shown.
Step 1. Select the ‚Wizard ‚ icon from the

pivot table tool bar.
Step 2. Drag and drop portfolio categories from the right side of the pivot
table wizard to the row section of the pivot table layout. Drag and drop
calculation categories from the right side of the pivot table wizard to the
data section of the pivot table layout.
Step 2. (Alternate) With the pivot table selected, drag and drop
sub-portfolio level or calculation categories from the floating
pivot table tool bar to the desired location on the pivot table.
The default drill down report automatically displays Component VaR (CvaR), and VaRBeta results that
indicate an estimate of the marginal contribution of each sub-portfolio category to total portfolio VaR taking
into consideration the volatility reducing benefits of diversification within the total portfolio. In addition to
these automatically generated results, the VaRReport template allows users to analyze the diversified
Analytic, Monte Carlo and Historical VaR of sub-portfolios while removing the diversification benefits of all
other parts of the total portfolio. The following screen shots demonstrate how to display sub-portfolio level
diversified VaR within the drill-down report.
The default drill down report automatically displays

CvaR, and VaRBeta results for each sub-portfolio
Step 1. By clicking the ‚Refresh Dynamic Report‛ button, ‚Drill

Cvar‛(Analytic VaR), ‚Drill MCVaR‛ (Monte Carlo VaR), and
‚Drill HvaR‛ (Historical VaR) results are displayed based on the
sub-portfolio category in the upper most left-hand corner of the
drill-down report.
In the example shown here, the ‚Drill Cvar‛ indicates the Analytic VaR of all the trades
associated with counterparty ‚BP‛ in isolation, whereas the ‚Cvar‛ result indicates the overall
contribution to the total portfolio’s VaR of all the trades associated with ‚BP‛, taking into
consideration the benefits of diversification across the total portfolio. As expected, the ‚Drill
Cvar‛ value is greater than the ‚Cvar‛ value.
Step 2. The ‚BP‛ counterpary sub-portfolio category is double

clicked exposing the ‚Drill cvar‛, or risk contribution, of each trading
desk associated with ‚BP‛ removing the diversification benefits of all
trades outside of the ‚BP‛ sub-portfolio.
The Incremental VaR Report is designed to show the incremental

change in Analytic VaR if a candidate portfolio is introduced.
Step 1. Click the ‚Allow for more trades’ button to

Select the number of separate ‚Cadidate Trades‛ to be included in
the analysis.
Step 2. Specify the name and location of the Candidate Trade text
file. If no location is specified the default directory is searched.
Use the Portfolio Builder template to create candidate trades files.
The StressReport Builder template is designed to display portfolio and sub-portfolio level results for
historically based scenarios (using an input historical data file) as well as user-defined scenarios created
using the Scenario Manager utility described later in this document. This tutorial outlines the following
three core tasks:
1. Entering Data Files & Model Parameters

2. Analyzing User-Defined Scenarios
3. Analyzing Historically Defined Scenarios
Step 1. First, specify the name and directory location of the volatility, correlation, asset,
data, and portfolio files. If the file location is not indicated the default directory is the
assumed file location. Next, Select the appropriate time horizon, home currency, effective
date and confidence inverval.
Step 2. Click the ‚Calculate‛

button.
Step 1. Begin by specifying the name and

address of the input file containing the user- Step 2. The scenario analysis tool evaluates return outcomes
defined scenarios to be analyzed. If the file is based on the input portfolio and scenarios specified in the
in the default directory no address is ‚Scenario Data File‛ . It displays the scenarios resulting in the
required. largest loses if the ‚4 Worst scenarios‛ selection is specified, the
Users are encouraged to use the Scenario scenarios resulting in the largest gains if the ‚4 Best gains‛
Manager utility included with VaRworks, selection is made, or the return for a single user-specified
and described in this manual, to create scenario if the ‚Chosen scenario only‛ selection is made.
scenario files.
Step 3. When the ‚Calculate‛ button is clicked the scenario analysis tool displays the
new mark-to-market, dollar change in value and percentage change in value for the
portfolio based on the input scenarios resulting in the largest losses or gains as well
as results for an additional user-specified scenario.
The scenario analysis tool automatically displays sub-portfolio level return results for
the scenarios shown in the portfolio level summary described above. Analysis of sub-
portfolio scenario results can pinpoint and isolate specific areas of weakness within the
input portfolio to user-defined market scenarios. In the example shown here, the sub-
portfolio level report indicates that the trading strategy undertaken by trading desk
‚D5‛ would create large gains if the market events described in the ‚gulf_war.txt‛
scenario were to occur.
Step 2. The historical analysis tool evaluates historical return

Step 1. Begin by specifying the name
outcomes based on the input portfolio and historical data files.
and address of the historical data file
It displays the four largest loses if the ‚4 Worst scenarios‛
from which historical stress tests will be
selection is specified, the four largest gains if the ‚4 Best gains‛
generated. If the historical file is in the
selection is made, or the return for a single user-specified date if
default directory no address is required.
the ‚Chosen date only‛ selection is made.
Step 3. When the ‚Calculate‛ button is clicked the historical analysis tool displays
the new mark-to-market, dollar change in value and percentage change in value
for the portfolio based on the historical scenarios resulting in the four largest losses
or gains as well as results for an additional user-specified date.
The historical analysis tool automatically displays sub-portfolio level return results for the dates shown in
the portfolio level summary described above. Analysis of sub-portfolio historical stress results can pinpoint
and isolate specific areas of weakness within the input portfolio to market events that have occurred in the
past. In the example shown here, the sub-portfolio level report indicates that the trading strategy
undertaken by trading desk ‚D1‛ would create large losses if the market events of 1/23/2001 were to occur
again.
The Scenario Manager is a Microsoft Excel spreadsheet-based utility application developed to complement
VaRwork’s Stress test functionality. The Scenario Manager can be used to quickly and easily build and
organize the stress test text files required by VaRworks. The name of the spreadsheet containing the
application is stresman.xls.
The Scenario Manager uses VaRworks’ CFDATA function to build the asset, asset class, and maturity lists.
Make sure the VaRworks Add-in is loaded prior to opening the Scenario Manager spreadsheet.
Note that the Scenario Manager does not currently support the inclusion of the implied volatility vertices.
Open the Scenario Manager spreadsheet.
Specify the volatility,

correlation, and asset codes
files. These should be the
same files used in the
VaRworks template.
calculations.
Use the find file button to

browse to the text file.
The full path is returned
into the cell to the left of
the button.
Specify the Volatility (cell B3), Correlation (cell B4), and Asset files (cell B5). The Button can be used to
browse to the file. The full file path is returned into the cell to the left.
Specify the Home Currency (cell B6) used in the stress test calculations.
Click the button. This button recalculates the CFDATA function in

a hidden worksheet.
If the CFDATA calculation is successful, the Scenario Manager displays the following message:
If this message appears, continue to Step 5.
If the CFDATA calculation fails, the Scenario Manager displays the following message:
The CFDATA function can fail due to a number of reasons. Some common problems are listed below:
1. Problem: The VaRworks Add-in is not loaded.

Solution: Load the VaRworks Add-in (varworks32.xll). See how to load the Add-in on page 69.
2. Problem: CFDATA cannot locate the Volatility, Correlation, or Asset file.

Solution: Check to make sure the files exist in the specified path. You can use the button to browse to
the file.
3. Problem: Other problems with the Volatility, Correlation, or Asset file.

Solution: Check the VaRworks error log. The error log provides detailed information on the error. See how
to examine the error log on page 80.
Click the button to load and display the Scenario

Manager Form.
Displays vertex information.

This is for information
purposes only.
Text files are generated into the

displayed default directory
Define multiple asset Define FX scenarios

class scenarios
Define Interest Rate
scenarios
Organize multiple text
files on the Main tab.
Define FX scenarios
Define Equity
scenarios
Set the default directory and default file name.
Both these inputs are set in the top middle area of the Scenario Manager form. The Scenario Manager will
generate the stress test text files into the default directory selected. Click on the button to browse
to the default directory.
Although it is not required, it is a good idea to set the default file name. The default file name is only used if
a stress test text file name is not specified in other file fields in the Stress Manager.
Once the default directory and default file name have been set, you can go to step 7.
Define Generic stress test Scenarios on the Generic page

Click on the ‚Generic‛ multi-page tab. This will display the Generic Scenarios page.
The Generic Scenarios page allows you to create multiple asset class scenarios. You can also create single
asset class scenarios in the Generic page or use the Asset class specific pages such as the FX, Interest Rate,
Commodity, or Equity page. The Generic page can replicate all scenarios defined in the Asset Class specific
pages. However, you will usually use the Asset Class specific pages since they tend to be more intuitive.
Specify the text file name for the Generic Scenarios stress test file. The text file name is located in the top,
middle area of the Generic page.
Define a stress test scenario.

A scenario can be defined on one or more lines. Our first scenario will be a one line scenario that consists of
a general increase in oil prices due to the Gulf War. We will specify a parallel 35% shock to the WTI
commodity forward curve.
We can start on the top line in the page.
The first input is the ‚Use?‛ checkbox:
This input is used to tell the Scenario Manager to include this scenario when building the Generic stress test
text file. When a line is first used, the checkbox is check marked and greyed out, indicating this line has
never been used before.
Go ahead and checkmark the ‚Use?‛ Check box. It should now have a checkmark within the box, and a
white background.
The next input is the Scenario Name. VaRworks uses the scenario name to identify each scenario.
Therefore, each scenario must have a unique name.
Type ‚Gulf_war_wti‛ in the Scenario Name textbox.
Click in the Scenario Description text box. The Scenario Description is used solely for informational
purposes. Type ‚35% parallel shift in WTI curve‛ in the Scenario Description textbox.
Click on the Asset Class dropdown box. We can use the Asset Class dropdown box to select the commodity
asset class since WTI falls under this category. Choose the ‚C‛ asset class for commodity.
Tip: Notice that if you place your pointer over the Asset Class text, a tooltip pops-up displaying the Asset Class codes.
Click on the Asset dropdown box. The Asset dropdown box is used to select from the available commodity
asset codes.
Choose the ‚WTI‛ asset code.
Click on the Shock Type dropdown box. The Shock Type dropdown box is used to select from one of the
following:
 Percent
 Absolute
 Standard Deviation
Choose ‚Percent‛ from the dropdown list.
Click on the Shock Model dropdown box. The Shock Model dropdown box is used to select from the
following:
 Parallel
 Twist
 Curvature
 Single Maturity
Choose ‚Parallel‛ from the dropdown box.
Notice that the Maturity dropdown box disappears when anything other than ‚Single Maturity‛ is chosen.
Click in the Shock Value text box. The Shock Value text box is used to specify the shock amount. To specify
35%, type ‚35‛ into the text box.
We have now completed our Gulf War scenario. The line should look as follows:
Export the Scenario to the Generic stress test text file.

Click on the ‚Export‛ button to export the Gulf War scenario to the text file.
Tip: You can use the button to view the created text file.
Define FX, Interest Rate, Commodity, and Equity Scenarios on their respective pages.
Manage the Generic and Single Asset Class files.

Click on the ‚Main‛ multi-page tab. This will display the Main page.
Specify the text file name for the stress *TYPE=STRESS_FILES file. This file is used to refer VaRworks to
specific stress test scenario files. The text file name is located in the top, middle area of the Generic page.
Checkmark the ‚use?‛ checkbox next to the scenario file names that you want to include in the
*TYPE=STRESS_FILES file.
Export the Scenario to the Generic stress test text file. Click on the ‚Export‛ button to create the
TYPE=STRESS_FILES file.
Tip: Clicking the ‚Export‛ button on the Main page also exports all scenarios on each page in the Scenario Manager to
the respective scenario file.
Congratulations. You have successfully created the Stress Test Scenario files
required for use with VaRworks stress test functionality. Click on the ‚Exit
Scenario Manager‛ button to unload the Scenario Manager Form.
Question:
I have a 14 inch monitor and the Scenario Manager Form does not fit on my screen. Is there any way to
reduce the size of the Form?
Answer:
Yes. The size of the Scenario Manager Form can be changed using the dropdown box in cell C26 of the Main
worksheet. For smaller monitors, use the Small setting.
Question:
How do I define a scenario that consists of several shocks to more than one asset or asset class?
Answer:
To define a scenario that consists of several shocks to more than one asset, use multiple Scenario Manager
lines. However, specify a Scenario Name only in the first line.
For example, suppose we want to define a FX scenario that consists of a five percent increase in the
following three currencies: DKK, NOK, SEK. This Scenario is defined on the FX page as follows:
Notice that only the first line of the Nordic_increase Scenario contains a Scenario Name. The remaining two
lines contain a checkmark in the ‚Use?‛ checkbox.
If the Scenario Manager encounters a line with a check-marked ‚Use?‛ checkbox, and an undefined Scenario
Name, it will assume the line is part of the Scenario who’s Scenario Name is specified on the line above.
Question:
How do I save my Scenarios so that I can view them in the Scenario Manager the next time I open the
Scenario Manager spreadsheet?
Answer:
Save the spreadsheet before closing to retain scenarios defined during current session. The next time the
Scenario Manager is loaded, the previous scenarios will be displayed.
Question:
Does the Scenario Manager use any VaRworks functions?
Answer:
Yes, the Scenario Manager uses VaRworks’ CFDATA function to determine the available assets, asset
classes, and maturities.
Question:
Is the Scenario Manager compatible with Microsoft Excel 95?
Answer:
No. The Scenario Manager is only compatible with Microsoft Excel 97, or Excel 2000.
Question:
Will the Scenario Manager overwrite existing text files with of the same text file name?
Answer:
Yes. The Scenario Manager will overwrite any existing text files of the same name without prompting.
VaRLib is intended for professional programmers who want to integrate VaRworks functions and large
systems. The Windows file C:\ fea\varworks\varlib.pdf or Unix file fea/varworks/varlib.pdf contains the
library User Guide.
RiskMetrics—Technical Document specifies the RiskMetrics VaR methodology. Introduction to RiskMetrics and
the quarterly RiskMetrics Monitor are also available. All publications are available free of charge on
RiskMetrics Group’s Web site http://www.riskmetrics.com.
The following magazines regularly publish articles about VaR:
RISK
RISK Publications
104-112 Marylebone Lane
London W1M 5FU
UK
Tel: +44 (0)171 487 5326
Fax: +44 (0)171 486 0879
Derivatives Strategy
Derivatives Strategy & Tactics, LLC
153 Waverly Place, Suite 1200
New York, NY 10014
Tel: +1-212-366-9578
Fax: +1-212-366-0551
Futures & OTC World

Futures and Options division of Metal Bulletin PLC
Park House, Park Terrace
Worcester Park
Surrey KT4 7HY
UK
Tel: +44 (0)171 827 9977
Fax: +44 (0)171 827 5290
A compilation of VaR article reprints published in RISK is available in VaR: Understanding and Applying
Value at Risk, published by Risk Publications.
Reprints of FEA’s published VaR articles are available from FEA or on the FEA Web site
http://www.fea.com
Barry Schachter’s extensive VaR bibliography is found at: http://pw2.netcom.com/~bschacht/varbiblio.html
A good text book is Phillippe Jorion’s Value at Risk: The New Benchmark for Controlling Market Risk, Irwin
Professional Publishing, Burr Ridge, Illinois, 1996.
A good overview of extreme value theory can be found in

McNeil A.J., ‚Extreme Value Theory for Risk Managers‛, Internal Modeling and CAD II, RISK Books, 93-
113,1999. http://www.math.ethz.ch/~mcneil/ftp/cad.pdf
Garman, M. B., ‚Making VaR more flexible,‛ Derivatives Strategy, April 1996, pp. 52–53.
Garman, M. B., ‚Improving on VaR,‛ RISK, May 1996, pp. 61–63.
Garman, M. B., ‚Component VaR,‛ Derivatives Strategy, July/August 1997.
Garman, M. B., ‚Taking VaR to Pieces,‛ RISK, Oct 1997, pp. 70–71.
Garman, M. B., ‚Making VaR Proactive,‛ at http://www.fea.com/
Garman, M. B., ‚Ending the Search for Component VaR‛ at http://www.fea.com/
Basle Committee on Banking Supervision, ‚The capital adequacy treatment of the credit risk associated with
certain off-balance sheet items,‛ Basle, Switzerland, 1994.
Basle Committee on Banking Supervision, ‚Amendment to the capital accord to incorporate market risks,‛
Basle, Switzerland, January 1996.
Coopers & Lybrand LLP, ‚Summary of the FASB’s proposed standard on accounting for derivative and
similar financial instruments and for hedging activities,‛ New York, 1996.
European Union, Capital adequacy directive EEC 93/6, 1993.
Group of Thirty, ‚Derivatives: practices and principles,‛ Global Derivatives Study Group, Washington, DC:
Group of Thirty, 1993.
Kupiec, P. and J. O’Brien, ‚Recent developments in bank capital regulation; regulation of market risks,‛
Federal Reserve Board, Washington, DC, 1995.
Kupiec, P. and J. O’Brien, ‚The use of trading risk models for regulatory capital purposes,‛ Federal Reserve
Board, Washington, DC, working paper, 1995.
Securities and Exchange Commission, Proposed Amendments to Regulation S-K. Washington, DC, 1995.
Securities and Exchange Commission, Proposed Amendments to Regulation S-X. Washington, DC, 1995.
We recommend John Hull’s texts (listed below). The FEA User’s Guides for @ENERGY, @EQUITY,
@GLOBAL, @INTEREST, SPAV, and SWING describe the financial models implemented in VaRworks. The
William Margrabe Group, Inc.’s Web site http://www.margrabe.com/ is an excellent source of derivatives
information.
Black, F. ‚The pricing of commodity contracts,‛ Journal of Financial Economics, Vol. 3 (March 1976), pp. 167–
179.
Black, F., E. Derman, and W. Toy, ‚A one-factor model of interest rates and its application to treasury bond
options,‛ Financial Analysts Journal, January-February 1990, pp. 33–39.
Black, F. and P. Karasinski, ‚Bond and option pricing when short rates are log normal,‛ Financial Analysts
Journal, July-August 1991, pp. 52–59.
Black, F. and M. Scholes, ‚The pricing of options and corporate liabilities,‛ Journal of Political Economy, Vol.
81 (May-June 1973), pp. 637–659.
Boudoukh, J., Richardson M., Whitelaw R., ‚The Best of Both Worlds,‛ Risk, (May 1998), pp. 64–67.
Boyle, P. P., ‚Options: a Monte-Carlo approach,‛ Journal of Financial Economics, 4 (1977), pp. 323–338.
Brennan, M.J. and E. S. Schwartz, ‚Finite difference method and jump processes arising in the pricing of
contingent claims,‛ Journal of Financial and Quantitative Analysis, 13 (September 1978), pp. 461–474.
Brennan, M. J. and E. S. Schwartz, ‚An equilibrium model of bond pricing and a test of market efficiency,‛
Journal of Financial and Quantitative Analysis, 17 (September 1982), pp. 301–329.
Chen, R. ‚Exact solutions for futures and European futures options on pure discount bonds,‛ Journal of
Financial and Quantitative Analysis, 27 (March 1992), pp. 97–107.
Cox, J. C., J. E. Ingersoll, and S. A. Ross, ‚An intertemporal general equilibrium model of asset prices,‛
Econometrica, 53 (March 1985a), pp. 363–384.
Cox, J. C., J. E. Ingersoll, and S. A. Ross. ‚A theory of the term structure of interest rates,‛ Econometrica, 53
(March 1985b), pp. 385–407.
Cox, J. C., S. A. Ross and M. Rubinstein, ‚Option pricing: a simplified approach,‛ Journal of Financial
Economics, Vol. 7 (1979), pp. 229–263.
Cox, J. C. and M. Rubinstein, Options Markets, Englewood Cliffs, NJ: Prentice Hall, 1985.
Dowd, Kevin. 1998. Beyond Value at Risk: The New Science of Risk Management. Chichester and New York: John
Wiley and Sons.
Duffie, D., Futures Markets, Englewood Cliffs, NJ: Prentice Hall, 1989.
Garman, M. B. and M. Klass, ‚On the estimation of securities volatilities from historical data,‛ Journal of
Business, Vol. 53 (1980), pp. 67–78.
Garman, M. B. and S. W. Kohlhagen, ‚Foreign currency option values,‛ Journal of International Money and
Finance, Vol. 2 (December 1983), pp. 231–237.
Heath, D., R. Jarrow, and A. Morton, ‚Bond pricing and the term structure of interest rates: a new
methodology for contingent claims evaluation,‛ Econometrica, 60 (1992), pp. 77–105.
Ho, T. S. Y. and S. Lee, ‚Term structure movements and pricing of interest-rate claims,‛ Journal of Finance,
Vol. 41 (December 1986), pp. 1011–1029.
Hull, J., Introduction to Futures and Options Markets, second edition, Prentice Hall, 1995.
Hull, J., Options, Futures, and Other Derivatives, third edition, Prentice Hall, 1997.
Hull, J. and A. White, ‚Pricing interest-rate derivative securities,‛ Review of Financial Studies, 3, 4, (1990), pp.
573–592.
Hull, J. and A. White, ‚In the common interest,‛ RISK, March 1992, pp. 64–68.
Hull, J. and A. White, ‚One-factor interest-rate models and the valuation of interest-rate derivative
securities,‛ Journal of Financial and Quantitative Analysis, Vol. 28 (June 1993), pp. 235–254.
Jarrow, R. A. and A. Rudd, Option Pricing, Richard D. Irwin, Homewood, Illinois, 1983.
Kemna and T. Vorst, ‚A pricing method for options based on average asset values,‛ Journal of Banking and
Finance 14 (1990), pp. 113–29.
Kupiec, Paul. 1998. ‚Stress Testing in a Value at Risk Framework.‛ Journal of Derivatives 6: 7-24.
Risk Publications, Hull-White on Derivatives, London, 1996.
Risk Publications, The Chase/RISK Magazine Guide to Risk Management, fourth edition, London, 1996.
Risk Publications, Over the Rainbow—Developments in Exotic Options and Complex Swaps, Jarrow, R., editor,
London, 1995.
Risk Publications, Managing Energy Price Risk, Jameson, R., editor, London, 1995.
Risk Publications, From Black-Scholes to Black Holes—New Frontiers in Options, London, 1992.
Rubinstein, M., ‚Exotic options‛, working paper, Haas School of Business, University of California,
Berkeley, 1995.
Rubinstein, M., ‚Implied binomial trees‛, Journal of Finance, Vol. 49 (July 1994), pp. 771–818.
Securities Industry Association, Standard Securities Calculation Methods, Volume 1, third edition, New York,
NY, 1993.
Stigum, M., Money Market Calculations: Yields, Break-Evens, and Arbitrage, Business One Irwin, Homewood,
IL, 1981.
Stigum, M., The Money Market, third edition, Business One Irwin, Homewood, IL, 1990.
Taylor, S. J., Modeling Financial Time Series, John Wiley, Chichester, UK, 1986.
Turnbull and Wakeman, ‚A quick algorithm for pricing European average options,‛ Journal of Financial and
Quantitative Analysis 26, 3 (1991), pp. 377-89.
Vasicek, O. A., ‚An equilibrium characterization of the term structure,‛ Journal of Financial Economics, 5
(1977), pp. 177–188.
Vorst, T. ‚Analytic Boundaries and Approximations of the Prices and Hedge Ratios of Average Exchange
Rate Options,‛ Erasmus University, February 1990.
Wilmott, P., J. Dewynne, and S. Howison, Option Pricing: Mathematical Models and Computation, Oxford
Financial Press, Oxford, UK, 1994.
Berkowitz, J. 2000. ‚Testing Density Forecasts, with Applications to Risk Management,‛ Graduate School of
Management, University of California, Irvine.
Christoffersen, P. (1998) ‚Evaluating Interval Forecasts,‛ International Economic Review, Vol 39, pp 841-862.
Dowd, K. (2002 -1), Measuring Market Risk, Chichester and New York, John Wiley & Sons.
Dowd, K. (2002 -2). "A Bootstrap Backtest," Risk, Vol.15 (10), pp.93-94.
Kupiec, P. (1995). Techniques for verifying the accuracy of risk management models. Journal of Derivatives
Vol.3, pp 73-84.
To learn about Microsoft Excel macro and add-in programming, consult Microsoft Press’s Microsoft Excel
series. Reed Jacobson’s Microsoft Excel 97/Visual Basic Step by Step provides quick, easy, self-training on
Microsoft Excel/Visual Basic for beginners. The Microsoft Excel 97 Developer’s Handbook by Eric Wells and
Steve Harshbarger is for intermediate users who want to use Excel 97 and its Visual Basic for Applications
(VBA) programming language to develop applications. The Microsoft Excel 97 Developer’s Kit by Baarns
Consulting is for advanced users and professional developers who need to work with the Microsoft Excel
Application Programming Interface (API) using C. It also contains full details about the file format of
Microsoft Excel. For more information, see http://mspress.microsoft.com or call 1-800-MSPRESS (1-800-677-
7377).
The standard reference for the C programming language is:

Kernighan, B. W. and D. M. Ritchie, The C Programming Language, second edition, Englewood Cliffs, NJ:
Prentice Hall, 1988.
General mathematical algorithms and formulas can be found in:

Abramowitz, M. and I. Stegun, Handbook of Mathematical Functions, Dover Publications, New York, 1968.
Press, W. H., B. P. Flannery, S. A. Teukolsky, and W. T. Vetterling, Numerical Recipes in C, Cambridge

University Press, New York, 1988.
Thisted, R. A., Elements of Statistical Computing, Chapman and Hall, New York, NY, 1988.
This document and all of the information contained in it, including without limitation all text, data, graphs,
charts (collectively, the ‚Information‛) is the property of Financial Engineering Associates, Inc. or its
affiliates (collectively, ‚FEA‛), or their direct or indirect suppliers or any third party involved in the making
or compiling of the Information (collectively, the ‚FEA Parties‛), as applicable, and is provided for
informational purposes only. The Information may not be reproduced or redisseminated in whole or in part
without prior written permission from FEA.
This product uses Zthreads, Copyright (c) <2005> <Eric Crahen>. Zthreads IS PROVIDED "AS IS",
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
THE USE OR OTHER DEALINGS IN THE SOFTWARE.
None of the Information constitutes an offer to sell (or a solicitation of an offer to buy), or a promotion or
recommendation of, any security, financial product or other investment vehicle or any trading strategy,
and none of the FEA Parties endorses, approves or otherwise expresses any opinion regarding any issuer,
securities, financial products or instruments or trading strategies. None of the Information or any FEA
products or services is intended to constitute investment advice or a recommendation to make (or refrain
from making) any kind of investment decision and may not be relied on as such.
The user of the Information assumes the entire risk of any use it may make or permit to be made of the
Information. In particular, historical data and analysis should not be taken as an indication or guarantee of
any future performance, analysis or prediction. NONE OF THE FEA PARTIES MAKES ANY EXPRESS OR
IMPLIED WARRANTIES OR REPRESENTATIONS WITH RESPECT TO THE INFORMATION (OR THE
RESULTS TO BE OBTAINED BY THE USE THEREOF), AND TO THE MAXIMUM EXTENT PERMITTED
BY LAW, THE FEA PARTIES HEREBY EXPRESSLY DISCLAIM ALL IMPLIED WARRANTIES
(INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF ORIGINALITY, ACCURACY,
TIMELINESS, NON-INFRINGEMENT, COMPLETENESS, MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE) WITH RESPECT TO ANY OF THE INFORMATION.
Without limiting any of the foregoing and to the maximum extent permitted by law, in no event shall any of
the FEA Parties have any liability regarding any of the Information for any direct, indirect, special, punitive,
consequential (including lost profits) or any other damages even if notified of the possibility of such
damages.
Any use of or access to products, services or information of FEA requires a license. MSCI, Barra, MSCI
Barra, Financial Engineering Associates, FEA, @ENERGY, @EQUITY, @GLOBAL, @INTEREST, DerivaTool,
SPAV, SWING, MakeVC, VaRdelta, VaRworks, DTlib, EquiLib, ErgLib, FEA Datepak, FEA Library
Modules, GlobLib, IntrLib, STlib, StructureTool, VaRlib, ZCURVE, and Zlib and all other MSCI, Barra and
FEA product names are the trademarks, registered trademarks, or service marks of MSCI, Barra or their
affiliates, in the United States and other jurisdictions.
The governing law applicable to these provisions is the substantive law of the State of New York without
regard to its conflict or choice of law principles.

Value at Risk and Vardelta

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Value at Risk and Vardelta

Uploaded by

Copyright:

Available Formats

Value at Risk and VaRdelta

Financial Engineering Associates, Inc.

The Financial Engineering team at FEA Information in this document is subject

Types of Lines in Text Files ......................................... 84

Crack Options .............................................................. 165 CFDATA ...................................................................... 293

Programming and Microsoft Excel ........................... 393

After the tutorial, you will want to:

FEA products are listed below.

 @EQUITY for valuing equity derivatives.

FEA, an MSCI Barra company

VaRworks incorporates pricing routines from other FEA products.

VaRworks supports the following financial instruments.

There are two new interest-rate instruments: AVERAGECAP and RANGEACCRUAL.

New instrument. Convertible bonds are now supported.

In this documentation, the following regional settings are used.

Regional setting Value

To check your regional settings

Use VaR because it:

PFE(N) = MAX over t { EFE(t) + N x sigma(t)}

PFE(p) = MAX over t { Percentil(DefaultLoss(t))}

This process has four steps:

1. Shred the instruments into cash flows

2. Take present values

3. Convert the cash flows to the home currency

4. Allocate the cash flows to vertices

Bond options, swaptions, caps, and floors

Bonds with embedded call

Bond futures options

Currency and commodity options

Equities and equity futures

Eurocurrency futures options

Floating rate notes (FRNs)

Forward rate agreements (FRAs)

Money market instruments

Allocating a Cash Flow to Vertices

A transformation yields the quadratic equation

with the two solutions

Analytic VaR calculation is a two step process.

position _ risk _ vector  position _ vector  volatility _ vector

where V = position_risk_vector and C = correlation_matrix

Graphical Depiction of VaR

 PMonteCarlo  P( Anew )  P( Aold )

The VaRworks Monte Carlo procedure follows.

Three things are needed to carry out this procedure:

Si (t )  Si (0) exp[( i  i2 / 2)t  ii t ] (2)

... ... ...

and we find the matrix A such that

 corr  AT   uncorr (5)

VaR= Vo(i)=(1-c)N (7)

Component VaR Calculation via Monte Carlo

CVaR j = p j C j, o(i)=(1-c)N . (8)

Daycount convention used in single-step

Daycount convention used in multi-step

TYPE supporting multi-step framework

Currently parallel calculation is achieved by running the simulation iterations in parallel.

VaRworks HISTORICALVAR function calculates Historical VaR, Shortfall Risk, mark-to-market,

HISTORICALVAR calculates VaR by following these steps:

1. It identifies the basic underlying assets on which the portfolio depends.

Three things are needed to carry out this procedure:

From these relations, all the model covariances can be derived.

and VaR is given, as usual, by VaR   VCV   with

VaR = + + Eq. (PS3)

S pi (t )  S pi (0) exp[(  pi   pi2 / 2)t   pi pi t ]