Setting up the returns file
Setting up the returns file
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.
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:
|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:
- the named portfolio had holdings in the given security at the date shown;
- at that date, the market weight of the security was as given in Column 4;
- at that date, the base and local currency returns of the security were as given in Columns 5 and 6;
- if supplied, the yield, modified duration and convexity of the security were as shown in Columns 7, 8 and 9.
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.
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.
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.
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.
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.
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.
- If fund STATFUND1 holds 100% of fund TRUST1, then the market weight of TRUST1 is 1.00.
- If fund STATFUND1 holds 5% of fund TRUST1, then the market weight of TRUST1 is 0.05.
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.