Setting up the returns file

From Flametree Technologies
Jump to: navigation, search

Contents

Setting up the returns file

Content

The returns definition files supply information about your portfolio and benchmark and how quantities such as security holdings, weights and returns change over time.

Any number of rows and columns may be entered into the file, but unused data will be ignored.

Format

Returns files must be supplied in comma or tab-delimited ASCII format, without leading or trailing rows. Therefore, no data field (such as a security name) can include a comma or a tab. Standard editing tools such as Excel or Notepad can be used to edit and update files.

All rows in the returns file must conform to the following format:

Column Field Type Description Required? Sample Rules
1 Date Date Date at end of current interval Yes 02-Sep-2010 Must be a string that can be parsed as a date, using the date format supplied in the DateFormat, PortfolioDateFormat or BenchmarkDateFormat strings
2 Portfolio String Portfolio in which the current security is held Yes STF1 Can include spaces.

FIA treats a portfolio name as a file name, and flags an error if this conversion cannot be applied. For instance, a portfolio name containing colons is disallowed.

3 Security ID code String ID code for current security Yes MEGACORP 15082015 Must have a corresponding entry in the security definition file.
4 Market weight Double Weight of current security in portfolio Yes 1200 Can be an asset allocation or a market value. If the sum of market weights does not equal one, weights are renormalised internally.
5 Base currency return Real Base currency return of security Yes -0.0043 Must be entered in absolute terms (ie 0.56% return is recorded as 0.0056, not 0.56)

If LocalToBase is set to true, and a file of FX rates is supplied, base currency returns will be calculated internally from local currency returns and FX returns.

6 Local currency return Real Local currency return of security Yes -0.0043 Must be entered in absolute terms (ie 0.56% return is recorded as 0.0056, not 0.56)

If BaseToLocal is set to true, and a file of FX rates is supplied, local currency returns will be calculated internally from base currency returns and FX returns.

7 Yield to maturity Real Yield to maturity (YTM) of security at current date No 0.0544 Required only for perturbational securities

Must be entered in absolute terms (ie 2.4% YTM is recorded as 0.024, not 2.4) If a value of YTM is supplied, this value will be used in place of any internally calculated value.

8 Modified duration Real Modified duration (MD) of security at current date No 4.33 Required only for perturbational securities
9 Convexity Real Convexity (C) of security at current date No 23.99 Used only for perturbational securities, and may be omitted
10 OAS Real Option-adjusted spread for security at current date No 0.012 Only used by securities with optionality
11 Spread duration Real Spread duration (SMD) for security at current date No 0.012
12 Z-spread Real Z-spread for security at current date No 0.012
13 Price Real Price of security at current date No 105.443
14 Volatility Real Volatility of security at current date No 0.0844
15 Delta Real First-order sensitivity of option price to changes in price of the underlying security No 0.5 Only used by securities with optionality
16 Gamma Real Second-order sensitivity of option price to changes in the price of underlying asset No -0.02 Only used by securities with optionality
17 Theta Real Sensitivity of option price with respect to elapsed time No 0.05 Only used by securities with optionality
18 Rho Real Sensitivity of option price with respect to changes in the risk-free interest rate No 0.05 Only used by securities with optionality
19 Vega Real Sensitivity of option price with respect to changes in the volatility of the underlying asset No 0.05 Only used by securities with optionality
Weights, returns and risks must be entered in decimal format. 
For instance, a 5% weight is recorded as 0.05, and a -21bp return as -0.0021.

Each row in the file shows that:

Columns

Date

Entries in the Date column must conform to the relevant date format string in the project’s configuration file (see Setting up the configuration file).

Data may be supplied at any frequency you wish, including daily, weekly or monthly. We recommend daily data for most accurate results. If a few days are missing, FIA will use the most recent data available up to that point for attribution.

Portfolio

This field supplies the name of the portfolio or benchmark that holds the named securities. The portfolio name is used in reporting.

A returns file can contain data on any number of portfolios. However, only one portfolio can be set up as a root portfolio.

Like a security name, a portfolio name must be between 3 and 256 characters in length, and cannot include a tab or a comma character, since these are used as column delimiters in the returns file. In addition, a portfolio name cannot be the same as that of an existing security.

The Portfolio field is always converted internally to upper case before being used.

FIA is designed to process two such files at the same time, usually referred to as the portfolio and the benchmark.

Security ID code

The Security ID field supplies an identifier code for the current security.

This must match a security ID that has been set up in the security definition file, and an error is flagged if no matching definition is found.

Just as for security IDs in the security master file, the Security field can be made up of upper and lower case characters. However,

The SecurityID field is always converted internally to upper case before being used. 

Therefore, a security with ID cash00001 in the returns file be matched with the security definition for CASH00001 in the security master file.

Note that you can use the name of another portfolio in the security field in order to set up a nested portfolio structure.

The portfolio name need not match that of a security.

Market weight

For securities, this field is used to supply the market exposure of the current security. As long as the same scheme is used for all securities, market weight can either be supplied in dollars, as an asset allocation between 0 and 1, or in some other form (note that negative weights are permissible).

Some securities, particularly futures, can have a zero market weight but a non-zero effective exposure. The effect this has on performance calculations is handled automatically by FIA.

Base currency return and local currency return

These fields specify the return of the security over the previous period in its own currency and in the currency in which the overall return of the portfolio is measured. For instance, if your data is supplied at a weekly frequency, then the security returns should be the base return and local return made over the previous week. These figures should include returns made from all sources, including accrued interest.

If weights are normalised to 1 at each date, then the sum-product of weights and base currency returns will equal the overall portfolio return at that date.

By supplying the weights, base and local currency returns of each security, the user ensures that the overall returns shown in FIA’s reports are identical to the overall returns calculated by the source performance data system.

If local currency return is unavailable but base currency return is available, or vice versa, use the BaseToLocal or LocalToBase to calculate these quantities from the available data and a supplied set of FX rates. If you use one of these options, an FX file containing exchange rates at each date for which returns are supplied must be available.

Yield to maturity

This optional field allows the user to supply a YTM (yield to maturity) for the current security. This is useful in ensuring that FIA’s attribution calculations are as accurate as possible. If no yield is supplied, FIA will calculate a YTM from the appropriate yield curves for the current security, but this may differ from the true YTM due to security-specific effects. The main impact of not supplying a yield will be seen in the time return data and in (possibly) larger residuals at the security level.

Modified duration

This optional field allows the user to supply a modified duration, or interest-rate sensitivity measure, for the current security. This can be useful for highly complex securities that may be complex to define and model. In such cases, it may be easier to set up the security as a pass-through security, to supply an external modified duration and to use that in the attribution analysis.

Other column definitions may be added in future.

Convexity

This optional field allows the user to supply a convexity, or second-order interest-rate sensitivity measure, for the current security.

Other column definitions may be added in future.

Other fields

These fields allow the user to supply prices, volatilites, and option 'greeks'. The user may prefer to supply values of these quantities rather than supply functions to calculate them internally.

Nested portfolios and carve-outs

Portfolio nesting is an extremely versatile feature that is central to FIA’s capabilities.

Instead of supplying the name of a security in column 3, you can supply the name of another portfolio that has been set up in the same file. The market weight is then interpreted as the fraction of that portfolio you hold. This is a very simple but powerful way to model hierarchical portfolio holdings.

For instance, suppose you manage both a managed fund called STATFUND1, and a unit trust called TRUST1. If the fund holds 50% of the unit trust, then all you need to do is to set up both funds in the same file under their own names, and to add a single line at each date the holding is active:

[Date] [STATFUND1] [TRUST1] [0.5]

For subportfolios, this field supplies the fraction of the subportfolio that is held in the current portfolio.

Note that the market weight of a subportfolio can be more than 1. For instance, if we have set up a swap INTSWAP as a subportfolio with market value $1, then a $100,000 holding in that swap is defined by using the subportfolio INTSWAP as a security with a market weight of 100,000.

The fractional holding of a subportfolio can also vary over time. For instance, if the holding in TRUST1 increases from 50% to 70% at a given date, then that new holding should be used at the appropriate date.

Portfolios can be nested to any depth and at any level of complexity.

The nested portfolio capability allows carve-outs, easily customized benchmarks, separation of strategic groupings of bonds, and synthetic securities. The topic is covered in more detail here.

Personal tools
Namespaces
Variants
Actions
Manual
File formats
Architecture
Additional information
Company
Downloads
Toolbox