Skip to content

Documentation enhancements #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rkapl123 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Documentation enhancements #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca4fa92
Add historical simulation VaR to analytics descriptions
rkapl123 Aug 22, 2025
7f4244f
Added explanation for additional default block specification
rkapl123 Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 48 additions & 2 deletions Docs/UserGuide/parameterisation/ore.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -917,9 +917,9 @@ \subsubsection{Sensitivity and Stress Testing}

See the examples in sections \ref{example:marketrisk} for a demonstrations of these analytics.

\subsubsection{Value at Risk}
\subsubsection{Parametric Value at Risk}

The {\tt VaR} analytics provide computation of Value-at-Risk measures based on the sensitivity (delta, gamma, cross gamma) data above. Listing \ref{lst:ore_var} shows a configuration example.
The {\tt VaR} analytics provide computation of parametric Value-at-Risk measures based on the sensitivity (delta, gamma, cross gamma) data above. Listing \ref{lst:ore_var} shows a configuration example.

\begin{listing}[H]
%\hrule\medskip
Expand Down Expand Up @@ -964,6 +964,52 @@ \subsubsection{Value at Risk}

See the example in section \ref{example:marketrisk_parametricvar} for a demonstration.

\subsubsection{Historical Simulation Value at Risk}

The {\tt Historical Simulation VaR} analytics provide computation of historical simulated Value-at-Risk measures based on the historical market scenarios passed in a csv file. Listing \ref{lst:ore_histvar} shows a configuration example.

\begin{listing}[H]
%\hrule\medskip
\begin{minted}[fontsize=\footnotesize]{xml}
<Analytics>
<Analytic type="parametricVar">
<Parameter name="active">Y</Parameter>
<Parameter name="historicalScenarioFile">scenarios.csv</Parameter>
<Parameter name="simulationConfigFile">simulation.xml</Parameter>
<Parameter name="historicalPeriod">2017-01-17,2019-12-30</Parameter>
<Parameter name="mporDays">10</Parameter>
<Parameter name="mporCalendar">USD</Parameter>
<Parameter name="mporOverlappingPeriods">true</Parameter>
<Parameter name="quantiles">0.01,0.05,0.95,0.99</Parameter>
<Parameter name="includeExpectedShortfall">Y</Parameter>
<Parameter name="breakdown">Y</Parameter>
<Parameter name="portfolioFilter">PF1</Parameter>
<Parameter name="outputFile">histvar.csv</Parameter>
</Analytic>
</Analytics>
\end{minted}
\caption{ORE analytic: Historical Simulation VaR}
\label{lst:ore_histvar}
\end{listing}

The parameters have the following interpretation:

\begin{itemize}
\item {\tt historicalScenarioFile:} csv file containing the market scenarios for each date in the observation periods defined below; the granularity of the scenarios (e.g. discount and index curves, number of yield curve tenors) needs to match the simulation market definition above; each yield curve tenor scenario is represented as a discount factor.
\item {\tt simulationConfigFile:} defines the structure of the simulation market applied in the P&L calculation, e.g. discount and index curves, yield curve tenor points used, FX pairs etc.
\item {\tt historicalPeriod:} comma-separated date list, an even number of ordered dates is required (d1, d2, d3, d4, ...), where each pair (d1-d2, d3-d4, ...) defines the start and end of historical observation periods used.
\item {\tt mporDays:} Number of calendar days between historical scenarios taken from the observation periods in order to compute P&L efects (typically 1 or 10)
\item {\tt mporCalendar:} Calendar applied in the scenario date calculation
\item {\tt mporOverlappingPeriods:} Boolean, if true we use overlapping periods of length mporDays (t to t + 10 calendar days, t+1 to t+11, t+2 to t+12, ...), otherwise consecutive periods (t to t+10, t+10 to t+20, ...)
\item {\tt quantiles:} Several desired quantiles can be specified here in a comma separated list; these lead to several columns of results in the output file. Note that e.g. the 1\% quantile corresponds to the lower tail of the P\&L distribution (VaR), 99\% to the upper tail.
\item {\tt includeExpectedShortfall:} If yes, also include the expected shortfall in the output file
\item {\tt breakdown:} If yes, VaR is computed by portfolio, risk class (All, Interest Rate, FX, Inflation, Equity, Credit) and risk type (All, Delta \& Gamma, Vega)
\item {\tt portfolioFilter:} Regular expression used to filter the portfolio for which VaR is computed; if the filter is not provided, then the full portfolio is processed
\item {\tt outputFile:} Output file name
\end{itemize}

See the example in section \ref{example:marketrisk_histsim} for a demonstration.

\subsubsection{P\&L, P\&L Explain, ZeroToParShift, Scenario}

The {\tt pnl} and {\tt pnlExplain} analytics provide computation of a single-period P\&L and its
Expand Down
13 changes: 11 additions & 2 deletions Docs/UserGuide/parameterisation/todaysmarket.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,12 @@ \subsection{Market: {\tt todaysmarket.xml}}\label{sec:market}

There can be alternative versions of each block each labeled with a unique identifier (e.g. Discount curve block with ID
'default', discount curve block with ID 'ois', another one with ID 'xois', etc). The purpose of these IDs will be
explained at the end of this section. We now discuss each block's layout.
explained at the end of this section. The ID 'default' has a special significance, being the default block that is taken by
ORE if no other ID is specified in the market configurations (see end of this section), however beware that this doesn't apply
to the dependency mechanism that collects curves before building other curves that depend on them (especially when using a lazyMarketBuilding parameter being set).
In this case you'd need to add the 'default' block to the market configuration as suggested for the {\tt IndexForwardingCurvesId} in the examples at the end of this section.

We now discuss each block's layout.

\subsubsection{Discounting Curves}

Expand Down Expand Up @@ -459,15 +464,19 @@ \subsubsection{Market Configurations}
\begin{minted}[fontsize=\footnotesize]{xml}
<Configuration id="default">
<DiscountingCurvesId>xois_eur</DiscountingCurvesId>
<IndexForwardingCurvesId>default</IndexForwardingCurvesId>
</Configuration>
<Configuration id="collateral_inccy">
<DiscountingCurvesId>ois</DiscountingCurvesId>
<IndexForwardingCurvesId>default</IndexForwardingCurvesId>
</Configuration>
<Configuration id="collateral_eur">
<DiscountingCurvesId>xois_eur</DiscountingCurvesId>
<IndexForwardingCurvesId>default</IndexForwardingCurvesId>
</Configuration>
<Configuration id="libor">
<DiscountingCurvesId>inccy_swap</DiscountingCurvesId>
<IndexForwardingCurvesId>default</IndexForwardingCurvesId>
</Configuration>
\end{minted}
\caption{Market configurations}
Expand All @@ -486,4 +495,4 @@ \subsubsection{Market Configurations}
'lgmcalibration', 'fxcalibration', 'pricing' and 'simulation' (i.e. risk factor evolution).

\medskip The configuration ID concept extends across all curve and volatility objects though currently used only to
distinguish discounting.
distinguish discounting.