Dividends on equity index derivatives are typically captured as a continuously compounded yield, with a different yield over a forecast horizon, to create a term structure of dividend yields. The dividend yield has a significant impact on pricing of equity index derivatives.
Findur does not support importing the dividend yield on equity indices out-of-the-box.
In this paper we describe a method to import dividend yields. The method described is powerful, and can be quickly and easily customized if necessary.
As it stands, the solution delivers significant benefits to users that demand an easier, more reliable, secure, and transparent solution to control pricing of a portfolio of equity index derivatives.
A Catalog of Findur’s Problems Handling Equity Index Dividends
Dividends on equity indices are saved in a dedicated Dividends Manager window in Findur. The screen has minimal functionality: it displays the currently saved dividend yield on an equity index. The user may see the dividend on one equity index at a time, who saved it, and the last saved date and time. Users cannot review the dividend history.
There is only one version of the dividend that is available for all users in the system for use in valuations. If a user updates the dividends, it will affect all users, including any on-going official simulations. In contrast to all other market data (prices/rates/exchange rates/volatilities/correlations) in the system, there is no distinction between current levels, and closing levels. There is no time-series available to view the history.
Also, unlike other market data, there is no way to run a what-if scenario that bumps dividends. There is no way to see what dividend yield was used during historical valuations on a prior day, or month-end or year-end.
There is no API to set the dividends to facilitate importing the dividend yield. In particular, there is no support for importing dividend yields from Bloomberg, or any other market data source.
When users revalue equity index derivatives, the pricing model inputs such as the index level, strike, and term structure of interest rates are exposed to the user, but the dividend yield is difficult to find.
Some Findur users update dividend yields on a regular, sometimes daily, basis. Dividend yield changes have a significant impact on pricing, and therefore affect daily P&L. Accurate attribution of P&L requires a reliable method to isolate the daily P&L that arose as a result of the change in the dividend yield.
All around, Findur has functional gaps that make maintenance, pricing, P&L and the general transparency of the operations difficult for users that have a portfolio of equity index derivatives.
In this paper we describe a solution that helps to address some of these concerns. Another paper addresses the P&L attribution concerns.
Importing Equity Index Dividend Yield: the Manual Method
The first problem most users encounter is how to import the equity index dividend yield. The Dividends Manager screen is divorced from all other sources of market data in the system. It is easy enough for a user to manually set the dividend yield on an equity index, but that becomes tedious once there are several indices, or as soon as the yields change frequently.
Findur has no API to import dividends. The only way to import dividends is to shoe-horn the system’s API that allows a user to import a specifically formatted comma-separated or XML file. This method is same as using the Standard Import/Export screen to import the dividends.
Many users have encountered the Standard Import/Export screen. The screen supports importing many business objects into the system, but the structure of the file is not intuitive. The first step a user typically follows to view the required file structure is to select an existing business object (a dividend yield in this case) and export it to a CSV or XML file.
The user then views the exported CSV or XML file, perhaps in Notepad++, manually updates the data, and uses the Standard Import/Export screen to import the dividend. For dividend yield import this will fail! The user will see an error related to the dividend yield version: the import utility detected an attempt to update an existing dividend with a version that already exists. In response the user will bump the version in the CSV or XML file by 1, and try again. It’s a painful, laborious process. The version number of the dividends on the S&P 500 index will almost certainly be different to the version number of the dividend yield of the Russell 2000 index.
This manual import process is quickly rejected as being unsuitable for a production environment. Any effort to cast this process as a bug with Openlink will fail, and be met with a discussion about an enhancement and scheduling on the product roadmap, perhaps available for release in another three years.
A Flexible Interface to Import Dividends
We have a solution that wraps the Standard Import/Export process in an API to simplify dividend updates.
The solution shares some of Findur’s market data infrastructure to simplify additional upstream and downstream processing needs that arise. In the end, users will welcome a more familiar operational framework. Developers will recognize the use of sensible design patterns that make the solution easier to deploy, maintain, and enhance if that ever becomes necessary.
Use the Market Manager Index Definitions to Store Dividend Yields
The first process is to setup some market data infrastructure that is more familiar to users.
Users are familiar with an index definition in the Market Manager. The solution is designed to extend the Market Manager data model. Market Manager index definitions that store dividend yields will have the Index Sub Group field set to Dividends to distinguish them from other index definitions that store interest rates or market prices.
There are several benefits to using the Market Manager index definitions for this solution.
- Security: Findur has robust out-of-the-box support to secure market index definitions and data sets. This solution needs no special custom features to allow or to deny access to update the definitions and data.
- Time-series: Findur has out-of-the box support for viewing the history of index data. It isn’t great, but it is consistent with the history of interest rates, exchange rates, market prices, etc. Any solution that extracts market data history to a data warehouse will be able now to extract dividend yield history to the same location.
- Deployment: Findur has out-of-the-box support for deployment of index definitions.
- Data updates: Findur has services available to import and update market data. Market Data Tools, and any other interfaces, adapters or APIs that control market data can be leveraged to update dividend yields when all of these business objects are stored in Findur in a consistent manner.
Store an XML Import Template
The absence of an Openlink API to import dividends requires shoe-horning the Standard Import/Export API. We can only use that API if we have the required file format using the exact layout the system expects.
The solution follows the required XML import format. At runtime, the solution picks up a template XML file, updates the necessary fields, adds elements, and removes elements, as necessary, saves the file, and uses the file to save the dividend yields.
This screenshot shows the template XML file with several fields that the solution updates to perform the update.
Extending the Solution to Another Data Source
The solution described here uses Market Manager index definitions to retrieve the dividend yields. We believe that to be the best way to store the data, based on the many benefits described earlier. However, if an alternative data source or event handling is desired, the solution has ready support for those features.
The solution use object-oriented programming principals and follows a design pattern that makes it easy to use any available data source: CSV, XML, JSON, database table, etc.
The existing solution instantiates a collection of IndexDividends, a concrete implementation of the abstract collection of Dividends. The data source for the IndexDividends objects is Market Manager index definitions, which are retrieved in the overridden retrieve() method. To change the data source, extend the abstract Dividends class, and override the retrieve() method. In the retrieve() method, use the public add(Dividend) method to add the Dividends to the collection using the new data source. To save the dividends, execute the saveToDividendManager() method.
package com.findur.oc.dividends;
import java.math.BigDecimal;
import java.util.Date;
import com.findur.oc.util.logger.MessageLog;
public class NewDividendsDataSource extends Dividends {
private static final long serialVersionUID = -6756505236386035879L;
private NewDividendsDataSource(MessageLog messageLog,
DividendInstrument dividendInstrument) {
super(messageLog, dividendInstrument);
}
@Override
public void retrieve() {
//Use the new data source to retrieve the dividend's label,
//start date, end date and value
String label = ..
Date startDate = ..
Date endDate = ..
BigDecimal yield = ..
Dividend dividend = Dividend.create(
getDividendInstrument(), label,
startDate, endDate, yield);
add(dividend);
}
public static NewDividendsDataSource create(MessageLog messageLog,
DividendInstrument dividendInstrument) {
return new NewDividendsDataSource(messageLog, dividendInstrument);
}
}The constructor for the concrete Dividends class needs to receive an instantiated DividendInstrument, which handles the strange way that Findur stores the dividends associated with a version of an equity index ticker. All that is required to instantiate a DividendInstrument is to pass a reference to the Findur Session and the instrument’s ticker as a String.
package com.findur.oc.dividends;
import com.findur.oc.util.logger.MessageLog;
import com.olf.openrisk.application.Session;
public final class SaveDividendsUsingNewDataSource {
public static void main(final String[] arguments) {
Session session = null;
MessageLog messageLog = null;
try {
//Attach to Findur session
session = ..
messageLog = new MessageLog(session,
SaveDividendsUsingNewDataSource.class);
//Get the equity index ticker
String ticker = ..
DividendInstrument instrument = DividendInstrument
.create(messageLog, ticker);
NewDividendsDataSource dividends = NewDividendsDataSource
.create(messageLog, instrument);
dividends.saveToDividendManager();
} catch (Exception e) {
messageLog.logException(e);
throw new RuntimeException(e);
} finally {
PluginHelper.detach();
}
}
}Findur Upgrade Considerations
An experienced Findur practitioner might ask at this point about the upgrade path. If the Standard Import/Export XML file format changes, will the solution break? The answer is: the solution is designed for this possibility.
First, hopefully there is an enhancement in future that affects importing dividends. In fact, as a user, we would welcome anything that improves the handling of dividends. Presumably if the import process has changed in a future version, it is because the process has improved, and there is a better method available, deprecating this solution.
However, we think it is unlikely that Openlink will change the import/export file format. If it happens, and the dividend handling remains awkward enough to warrant continued use of the solution described here, we have designed for this eventuality. We are skeptical of any enhancements in this functionality since these features have been in place unchanged for nearly two decades!
The XML format required by the Standard Import/Export screen is saved to the database. A user may update that template if, for example, a new field is required. Depending on the nature of the change to the XML schema, it may be necessary to update the solution code. We separated the XML file update concerns from the rest of the solution, following the Separate of Concerns design principal.
The solution has an EquityDividendParser class, that is responsible for the interface between the dividend business object and the XML file. The parser handles the retrieval of the XML template file, updating the elements that must be added or removed from the file, and setting the data that must be injected into the element values. It also handles saving the updated file. If the XML structure must change in a future version of Findur, changes should be isolated to the EquityDividendParser.
If a future change updates an XML tag, the XML tags are enumerated in the XmlTag enum.
Importantly, the EquityDividendParser uses common Java XML APIs, rather than any proprietary Openlink API. The internet abounds with examples of how to handle XML, so there is no need to use one vendor’s black-box API to handle common requirements for handling XML files.
Next Steps
Contact us today and we will share additional details of the solution. There is no reason to reinvent the wheel to import an equity dividend into Findur.
