Setting up the security file
The security definition file, or security master, records quantities such as identifier, name, type, currency, maturity, coupon and credit rating for the securities in your portfolio.
Each line in the security definition file sets up an individual security. In some cases, a security definition may require multiple rows if its characteristics change over time. In this case, the security ID will be the same on each row, but the security’s effective date will be different on each row.
A security only need be set up once in the security file, even if it used in many portfolios, while unused security definitions are ignored. Therefore, you can use a single security definition file for all your portfolios and benchmarks and add to it over time as the number of securities you trade increases.
Security 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, but note that Excel can change date formats if you open and save a file in Excel.
Security file structure
The number of fields required to define a security varies according to its type. However, the data requirements for all securities are identical over the first eleven fields.
|1||Security ID code||String||Unique identifier for security||Yes||AU0000IFXHB8
|Must be at least 3 characters
No tabs or commas
|2||Security name||String||Name of security||Yes||IFC 5.750 24-Jun-2014||Must be at least 3 characters
No tabs or commas
|3||Classification||String||Names of bucket and corresponding value.||No||[Blank]
|All entries must be of the form HEADER = VALUE.
Both HEADER and VALUE must have at least three characters with no tabs or commas.
Values must be assigned using an '=' symbol.
Any number of classifications can be supplied, but multiple 'bucket=value' assignments must be separated by a pipe (|) symbol.
|4||Effective date||Date||Date at which record becomes effective. If no date is supplied, the record is assumed valid over all dates.||No||[Blank]
|Must either be blank or a string that can be parsed as a date, using the date format supplied in the DateFormat or SecurityDateFormat strings|
|5||Pricing function||String||Name of pricing function used for this security.||No||FT_BOND_CURVE_ZERO
|Only one pricing function can be assigned to a given security.
If no pricing function is supplied, the security is assumed to use a perturbational model, in which case values of YTM and MD must be supplied in the weights and returns files.
Click here to see the list of pricing functions available in the current release.
|6||Risk functions||String||Name of risk function(s) specifying which additional risks are to be calculated for this security.||No||Inflation(UK_CPI)
|Multiple risk functions can be assigned to individual securities.
Multiple risk functions must be separated by a pipe (|) symbol.
Click here to see the list of risk functions available in the current release.
|7||Effective exposure||Integer||Flag indicating whether effective exposure is zero||No||1, 0||Should be 0 for futures and 1 for all other security types.
If not supplied, set to 1
|8||Credit rating||String||Credit rating of security||No||AAA, AA-, B+||Any credit rating identifier may be entered, as this value is only used for reporting and classification purposes.
If not supplied, set to 'NR' (not rated)
|9||Security currency||String||3-character currency code||Yes||AUD||Currency codes must follow the global ISO 4217 standard.|
|10||Residual sector||String||Name of returns category into which to write residual return for the current security||No||[Blank]
Country spread duration
|Any valid string; can be blank|
|11||Curves||String||The names of all yield curves used by this security, in descending order of creditworthiness||Depends on data requirements of pricing function||AA_CURVE|B_CURVE||All named curves must have been set up in the yield curve file.
|12||Start date||Date||Date at which this security's cash flows begin||Depends on data requirements of pricing function||15-Jan-2020||Must either be blank or a string that can be parsed as a date, using the date format supplied in the DateFormat or SecurityDateFormat strings|
|13||Maturity||Date||Maturity date of bond||Depends on data requirements of pricing function||23/06/2014||Must either be blank or a string that can be parsed as a date, using the date format supplied in the DateFormat or SecurityDateFormat strings|
|14||Coupon||Double||Nominal coupon||Depends on data requirements of pricing function||0.0575||Must be number greater than or equal to zero
Must be entered in absolute terms (ie 4.5% coupon is recorded as 0.045, not 4.5)
|15||Frequency||Integer||Number of coupons per year||Depends on data requirements of pricing function||2||Integer greater than or equal to zero|
|16||Strike||Double||Strike price of security. Only applicable to options||Depends on data requirements of pricing function||100.44||Number greater than zero|
|17||Term||Double||Term of security, in years. Only applicable to sinking securities||Depends on data requirements of pricing function||30||Number greater than zero|
|18||PSA||Double||Repayment rate for securities that use the PSA prepayment model||Depends on data requirements of pricing function||1.2||Number greater than zero|
|19||Paydown||Double||The fraction of the bond's principal that is outstanding at the given effective date||Depends on data requirements of pricing function||0.677443||Number greater than zero|
|20-148||User defined||Double||User-defined fields||Depends on data requirements of pricing function||These fields may be defined by the user. Any information stored in these fields is passed to the pricing function and may be used in customised pricing functions.|
The usage of the various fields is described in more detail below.
Security file fields
Security ID code
A security ID can be made up of any combination of characters, including spaces and punctuation marks. The only restriction on a security ID is that it 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 security definition file. Suitable security IDs include CUSIP or SEDOL codes, an internal code, or a descriptive name.
Although security IDs can be made up of upper and lower case characters, they are always converted internally to upper case.
CASH00001 Cash00001 cash00001
are all interpreted as CASH00001.
A security ID can appear more than once in a security file, as long as each entry has a different effective date. The unique key for security identification is the tuple <Security ID, Effective date>.
A security name is a user-friendly identifier for the security. Both the security name and the security ID will be shown on reports that refer to individual securities. The name must be between 3 and 256 characters in length and cannot include a tab or a comma character.
Unlike security IDs, security names are not converted to upper case, and are shown on reports exactly as they appear in the security file.
Although the custom sector field can be left blank, it provides an extremely flexible way to add as much classification information as you require to the current security's definition. Sector fields are of the form
HEADER = VALUE
where HEADER is the name of the class of variables to be assigned, and VALUE is the value of that class for the given security. HEADER and VALUE must always be linked with an '=' sign, but spaces are ignored.
For instance, suppose you wanted to record each security's country, and to have this appear on FIA's reports. (FIA currently records security currencies and yield curves, but not specific countries.) Simply fill this field with the entry
Country = (country name)
where (country name) is the country you want to associate with the current security. The header Country will then appear on reports that list individual securities, and the assigned value for Country will be shown under that heading.
If a country has been set up for some securities but not for others, the value Undefined will be written to those securities that have not have a value assigned.
The field is also available for use by other parts of the program. For instance, if you want to use a custom classification in the FIA's drill-down reporting, use the header value in PartitionList. The attribution and exposure results can then be decomposed by the given category. (For more information, see 'Configuring FIA').
Custom classification schemes can also be used for partitioning portfolios in asset allocation calculations (see Asset allocation).
The number of categories that can be assigned to a given security is unlimited. To assign multiple categories, write a string of the form
HEADER1 = VALUE1 ¦ HEADER2 = VALUE2 ¦ HEADER3 = VALUE3
where the assignments are separated by a ¦ character. For instance, to declare that a particular security was issued in the US, that its sector is INDUSTRIAL, and its home state is Utah, write the following string to the classification field:
COUNTRY = US ¦ SECTOR = INDUSTRIAL ¦ STATE = Utah
The effective date is the date at which the security’s settings on the current line become active.
Most of the securities you hold will not have any structural changes over time. In this case, the effective date can either be left blank, or set to some date in the far past.
However, some securities do have properties that may change over time. For instance:
- A security's user-defined classification in the custom sector field may change;
- A bond may be downgraded, resulting in a lower credit rating;
- A convertible bond may change its pricing type;
- A bond's coupon may be reset to a new value.
In each case there will be a change in some structural value of the security. For the above examples, the changed entries will be classification, credit rating, pricing type and coupon, respectively. FIA allows the user to handle such occurrences by entering a new definition for the security that reflects the required changes, using the same security ID but a different effective date.
More than one change in the security’s parameters can be made at the same date.
For instance, consider a convertible bond that has its pricing function changed from FT_BOND_ZERO_CURVE to FT EQUITY on 15th September 2008. This is represented by two records in the security definition file:
|Column 1||Column 4||Column 5||...|
The first row shows the security initially had pricing function FT_BOND_ZERO_COUPON. The effective date of this setting is left blank, so in the absence of any other entries it will apply to all dates.
The second row shows that the security's pricing function changed to FT_EQUITY on the 15th of September 2008. This type will be used for all analysis on and after that date.
- Any number of security updates can be made to a given security, but the program checks that there are no duplicate security ID/effective date combinations.
- Entries in this column must conform to the relevant date format string in the project’s configuration file (see Chapter 4, Setting up the configuration file).
- If two or more parameters change on the same date, these changes can be included in the same record.
- The start date in column 4 is the date at which data in that record becomes valid. If the start date is left blank, the implied date is Julian date 0, or about 4713 BC. We recommend that the start date be left blank in all cases except where the characteristics of the bond change during its lifetime. In particular, the issuance date of a security need not be entered in this field.
Security type is a string identifier that identifies the pricing function appropriate for the type of security recorded. Every record must be assigned one of these entries, unless it uses perturbational attribution, in which case this field should be left blank.
The list of defined pricing functions is available here.
In addition to the above list, there is also a Portfolio type, which is composed of holdings in other securities. This may be the most appropriate type for a derivative such as a swap. Note that it is not possible to assign a Portfolio type to a security directly. Instead, a portfolio is set up as a subportfolio in a weights and returns file, and it is automatically recognised as a Portfolio type in FIA's reports. Refer to Subportfolios for more information.
As described above, a security can have more than one pricing function over time. For instance, a convertible bond that changed its type from FT_BOND_ZERO_CURVE to FT_EQUITY on 1st July 2009 would have its first three columns set up as follows:
|Column 1||Column 4||Column 5|
RISK_FUNCTION is a string identifier that specifies the risk functions appropriate for the security recorded.
The list of defined pricing functions is available here.
Indicates whether the effective exposure of the current security is its market exposure or zero.
This field should be 0 for futures for which a cash offset is not provided, and 1 for all others.
If not supplied, the effective exposure is set to 1.
The credit rating applicable to this security, using Moodys, S&P or Fitch ratings, or a user-defined scheme.
This field is only used in reports and as a classification value.
If not supplied, the rating is set to UNR (unrated).
Currency is a string identifier that denotes the currency in which the security is issued.
FIA uses the standard three-letter ISO 4217 format for currency codes. A table of commonly used currencies is shown below.
|Currency||ISO 4217 code|
|New Zealand dollar||NZD|
The full list is available at http://en.wikipedia.org/wiki/ISO_4217.
The residual sector field allows the user to direct residuals to named buckets on a per-security basis, rather than just to a generic residual category.
- If the residual field is left blank, all residual return is directed to the default residual bucket, which may be renamed using the ResidualReturnLabel field in the configuration file.
- If the residual field is set to the value of a return label that has already been set up, all residual return for that security is added to that return bucket. For instance, if you want to direct all residual return from a complex swap to Duration, set the residual field for that security to the value Duration.
- If the residual field is set to some other value, a new residual bucket is set up with that name and all residual return from securities with this residual value is directed to the new bucket. For instance, setting up a new residual bucket with a value of Country spread for a group of securities will result in a new return field with this name appearing on all residual reports.
This field specifies the name of the yield curve(s) to be used for pricing and attribution on the current security.
- All named curves must be set up in the yield curve file.
- Curves must be named in descending order of credit-worthiness, so the name of the highest rated curve always comes first.
- If there is more than one curve, their names must be separated by a pipe (|) symbol.
- If more than one curve is provided, the return due to the change in spread between each curve pair will be shown on the attribution report.
For instance, a corporate bond might have this field set to RISK_FREE_CURVE|SECTOR CURVE. In this case, an attribution analysis will calculate the returns made by movements in RISK_FREE_CURVE, and by changes in the spread between RISK_FREE_CURVE and SECTOR_CURVE.
Similarly, a bond with this field set to SOVEREIGN_CURVE|SWAP_CURVE|SECTOR_CURVE will generate
- returns due to movements in SOVEREIGN_CURVE;
- returns due to changes in the spread between SOVEREIGN_CURVE and SWAP_CURVE;
- returns due to changes in the spread between SWAP_CURVE and SECTOR_CURVE.
This field specifies the date at which a security's cash flows begin.
If this field is left empty, the security is assumed to start paying cash flows from the current settlement date.
This field specifies the date at a security's final payment will be made.
Maturity dates must lie between 1st Jan 1970 and 1st Jan 2150.
If a security matures during a calculation period, its return after maturity is set to zero. No assumptions are made about reinvestment.
The annual coupon applicable to this security. Coupons that vary over time can be adjusted using the effective date.
Coupons are stored in decimal format. A 4.5% coupon is recorded as 0.045.
The frequency, or number per year, for coupon payments. Typical values are 1 or 2 for bonds and 4 or 12 for floating rate notes.
The option strike price. Only applicable for options.
The period, in years, for which an amortizing bond is issued. This term is only used for sinking securities, such as MBS.
The PSA repayment rate, in decimal terms (ie 150% PSA = 1.5). If not set, the value defaults to 1.
This term is only applicable to securities that can accept prepayments, such as MBS.
The fraction of the security's principal currently outstanding at the given effective date.
This field is only used for sinking securities such as MBS where the principal can be reduced over time.
If left blank, Bond factor defaults to 1.0.
These fields are reserved for user-defined data.