Setting up the security file

From Flametree Technologies
Jump to: navigation, search



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.

Column Field Type Description Required? Sample Rules
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]

Optionality return

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. 



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>.

Security name

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


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 for asset allocation attribution or interactive reports, use one or more header values as the names of the classifications. The attribution and exposure results can then be decomposed by the given values.

The number of categories that can be assigned to a given security is unlimited. To assign multiple categories, write a string of the form


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:


Effective date

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:

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 ...
MEGACORP_2020 ... 15-Sep-2008 FT_EQUITY ...

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.

Pricing function

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.

Portfolio types

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.

Changing type

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
CONVERTIBLE_2015 01-Jul-2009 EQUITY ...

Risk functions

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.

Effective exposure

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.

Credit rating

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).

Security currency

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
US dollar USD
Euro EUR
Japanese yen JPY
British pound GBP
Australian dollar AUD
New Zealand dollar NZD
Swiss franc CHF

The full list is available at

Residual sector

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.


This field specifies the name of the yield curve(s) to be used for pricing and attribution on the current security.

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

Start date

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.

User defined

These fields are reserved for user-defined data.

Personal tools
Attribution methodology
Running FIA
Additional information