Setting up the configuration file

Contents 1 Introduction 2 Setting up a configuration file 2.1 Setting up values 3 File names 4 Date formats 4.1 Date format strings 4.2 Attribution calculation configuration 4.3 Mixed model allocation options 4.4 Fixed income allocation attribution options 4.5 Smoothing options 4.6 Benchmark hedging options 4.7 Futures cash offset options 4.8 Reporting options 4.9 Start and end dates 4.10 Reporting and allocation options

Introduction

The configuration file is a short text file that contains the names of the files to be used in the attribution calculation, the type of attribution to be performed, and any other information required for the analysis, such as the base currency for the final reports. A configuration file must be supplied each time FIA is run.

A configuration file allows the user to set large numbers of parameters without having to retype them each time the program is run.

Configuration files may be given any name, but must have the suffix cnf. Configuration files may be written or edited using any text editor, such as Notepad (in Windows) or gedit (in Linux).

A sample configuration file looks as follows:

# sample.cnf
[FIA]
PortfolioFile = statfund1.csv
SecurityFile = sec_defs.csv
CarryDecomposition = pull_to_par
SovereignCurveDecomposition = STB
RollDownAttribution = n
DateFormat = %d/%m/%Y

This file specifies that

• the portfolio data file to be analyzed is called statfund1.csv;
• the benchmark associated with the portfolio is unspecified. In this case, no benchmark will appear in the final results;
• no exchange rate attribution is to be performed;
• return due to carry return is to be shown in the final report;
• changes in the sovereign yield curve for all markets are to be broken down into parallel shift, twist, and curvature components;
• credit curve attribution is to be run, using the AAA, Aa2 and A2 curves;
• roll-down effects are not to be calculated, but will instead be added to the residual return;
• dates will be read in the dd/mm/yyyy format.

The user has left a comment on the first line that the name of the file is sample.cnf. Any line that is prefixed by a # symbol is treated as a comment, and is ignored by FIA.

A detailed list of the possible options specified in the configuration file is shown in the next table. Note that many settings do not need to have values assign, as sensible default values are defined.

A configuration file must always start with [FIA].

If an option setting that does not correspond to a defined field is supplied, FIA flags an error and stops.

Portfolios that are regularly analysed may be assigned their own configuration file. This file can then be reused as often as required.

Options may be set in any order.

Options are case-sensitive.

Setting up a configuration file

There are two ways to set up a configuration file for FIA.

• The first is to construct it manually using a text editor. For users who want to follow this route, full documentation is provided below.
• The second is to construct it using our freely downloadable graphical user interface (see Using the configuration GUI), which allows you to set up configuration files using drop-down menus and similar controls.

Setting up values

For string-valued options, use the pattern

FIELD=VALUE

VALUE can be upper or lower case.

For Boolean-valued options, use the pattern

FIELD=VALUE

where VALUE can take the values True, False, Yes, No, 1, 0.

Some fields can also be integer and real-valued.

No quotation marks are needed. Spaces to either side of the ‘=’ sign are ignored.

If a field is specified that is not recognized by FIA, the program will stop with an error message.

The following tables show the names and formats of quantities that may be read from the configuration file. Click on the field name to go the setup page for each file type.

File names

Field	Description	Required?	Possible values	Example	Default
PortfolioFile	Name of portfolio weights and returns file, including file path if required	Yes	File name as string	portfolio.csv	Not applicable
BenchmarkFile	Name of benchmark weights and returns file, including file path if required	No	File name as string	benchmark.csv	None
SecurityFile	Name of security definitions file, including file path if required	Yes	File name as string	sec_defs.csv	Not applicable
YieldCurveFile	Name of yield curve data file, including file path if required	No	File name as string	yc.csv	Not applicable
FXFile	Name of exchange rate file, including file path if required, containing currency codes, dates and rates.	No	File name as string	fxfile.csv	None
IndexFile	Name of file containing time series such as inflation indices, LIBOR and paydown schedules	No	File name as string	IndexFile.csv	None

Notes

• File names can include a path. For instance, C:\FIA_data\my_data\security_master.csv is an allowable value. Relative paths, such as .\FIA_data\my_data\security_master.csv, can also be used.

• The benchmark file is optional. If no benchmark is specified, the program will run attribution on the supplied portfolio only and generate an appropriate set of reports. The only exception is when the user has requested a type of attribution that requires an asset allocation calculation, which specifically requires a benchmark. In this case FIA will generate an error message and halt.

Date formats

Field	Description
DateFormat	User-supplied format for parsing dates from all files
SecurityDateFormat	User-supplied format for parsing dates in security file
PortfolioDateFormat	User-supplied format for parsing dates in portfolio returns files
BenchmarkDateFormat	User-supplied format for parsing dates in benchmark returns files
YieldCurveDateFormat	User-supplied format for parsing dates in yield curve files
FXDateFormat	User-supplied format for parsing dates in exchange rate files
IndexDateFormat	User-supplied format for parsing dates in index file

Date format strings

FIA can parse a wide range of date formats. Date formats are constructed by appending a number of format specifiers, corresponding to the day, month and year fields of the supplied date, together with the field delimiters.

Formats correspond to those used by the C strptime function. The following formats are allowable:

Format	Example	Sample
%d	Day of month (1-31)	15
%m	Month number (1-12)	2
%b	Month in abbreviated or full form	February, Feb
%y	The year without century data (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068)	45
%Y	The year, including century	2015

Date format strings are constructed by aggregating the above format strings with the date delimiter. For instance, if your dates are in the dd-mm-yy format, set the format string to %d-%m-%y, using a hyphen as the delimiter.

The following table lists some example date format strings.

Date	Format
15/05/2013	%d/%m/%Y
15/05/13	%d/%m/%y
05/15/2013	%m/%d/%Y
05-15-2013	%m-%d-%Y
05152003	%m%d%Y
20031505	%Y%m%d
15-May-13	%d-%b-%y
15-May-2013	%d-%b-%Y

Initially, all date formats have the default value %Y-%m-%d. This can be overridden as follows:

FIA allows you to specify a date format to be used for all files, a specific date format for each file, or any combination of the two. Formats are applied using the following schema:

• Any formats supplied in SecurityDateFormat, PortfolioDateFormat, YieldCurveDateFormat, FXDateFormat are applied first to the corresponding files;
• Next, format DateFormat is applied to any files that have not had a custom format applied;
• If DateFormat has not been supplied, the default format is applied to any remaining files.

Example	Setting	Result
Example 1	No date format strings set	All dates from all files will be read using the default format string %Y-%m-%d
Example 2	DateFormat is set to DEMO_STRING No other format strings set	All dates in all files will be read and parsed using DEMO_STRING
Example 3	DateFormat is set to DEMO_STRING1, SecurityDateFormat is set to DEMO_STRING2.	All dates in the security file will be read and parsed using DEMO_STRING2 All dates in other files will be read and parsed using DEMO_STRING1
Example 4	DateFormat is not set SecurityDateFormat is set to DEMO_STRING1	All dates in the security file will be read and parsed using DEMO_STRING1 All other dates will be read and parsed according to the default format string %Y-%m-%d

Attribution calculation configuration

Field	Description	Required?	Possible values	Example	Default
CarryDecomposition	String indicating type of carry return attribution required: NONE: no return measured for the passage of time. AGGREGATED: all return from carry assigned to one source. PULL_TO_PAR: return decomposed into return from current yield and return from pull-to-par effects. CREDIT_CARRY: carry return decomposed into return generated by risk-free yield, and return generated by spread above this yield. [Other values are reserved for future expansion]	No	NONE AGGREGATED PULL_TO_PAR CREDIT_CARRY	PULL_TO_PAR	AGGREGATED
SovereignCurveDecomposition	String indicating type of yield curve attribution required: NONE: no return assigned to sovereign curve movements. The user may prefer not to display this field if no securities in the portfolio are affected by changes in the term structure. AGGREGATED: all return from sovereign curve movements assigned to one source DURATION: return from sovereign curve assigned to parallel and non-parallel curve movements STB: return from sovereign curve assigned to parallel shift, twist and curvature movements KRD: return from sovereign curve assigned to movements at various maturities CCB: twist motions measured by performing a least-squared fit of a first-order polynomial to the curve PCA: models curve movements using principal component analysis [Other values are reserved for future expansion]	No	NONE AGGREGATED DURATION STB KRD CCB PCA	DURATION	AGGREGATED
AverageCurveLevel	String indicating averaging routine to calculate mean level of yield curve: ARITHMETIC: Simple arithmetic averaging of yield levels TRAPEZOIDAL: Uses trapezoidal integration to remove effect of unequally spaced sample points on the yield curve FIXED: Uses maturity specified in value ShiftMaturity at which to measure changes in curve [Other values are reserved for future expansion]	No	ARITHMETIC TRAPEZOIDAL FIXED	ARITHMETIC	TRAPEZOIDAL
LowerTwistMaturity	Lower maturity about which curve twists are measured. Only used if SovereignCurveDecomposition=STB.	No	>0	5	3
UpperTwistMaturity	Upper maturity about which curve twists are measured. Only used if SovereignCurveDecomposition=STB.	No	>0	15	10
ShiftMaturity	Maturity point at which curve shifts are measured. For instance, if this value is set to 5, then a curve's parallel shift is deemed to be the change in the curve's level at the 5 year maturity.	No	>0	5	7
ConvexityAttribution	Whether to display returns due to security convexity If this field is not displayed, any returns from this source are assigned to RESIDUAL.	No	True, False, Yes, No, 1, 0	No	No
RollDownAttribution	Whether to display returns due to roll-down effects If this field is not displayed, any returns from this source are assigned to RESIDUAL.	No	True, False, Yes, No, 1, 0	No	No
PayDownAttribution	Whether to display returns due to paydown If this field is not displayed, any returns from this source are assigned to RESIDUAL.	No	True, False, Yes, No, 1, 0	No	No
LeverageAttribution	Whether to display returns due to leverage If the portfolio has leverage in place (effective exposure differs from market exposure), this switch makes FIA calculate the proportion of return generated by leverage.	No	True, False, Yes, No, 1, 0	No	No
MaturityList	List of maturities that define buckets used in reporting.	No	Any set of positive numbers. List does not need to be sorted. '0' is added automatically if not explicitly declared.	0,1,2,3,4,5,10,15	0,1,...,10,15,20,30
DurationList	List of modified durations that define buckets used in reporting.	No	Any set of positive numbers. List does not need to be sorted. '0' is added automatically if not explicitly declared.	0,1,2,3,4,5,10,15	0,1,...,10,15,20,30
KRDList	List of key rate durations to be used if SovereignCurveDecomposition=KRD.	No	Any set of positive numbers. List does not need to be sorted. '0' is added automatically if not explicitly declared.	0,1,...,10,15,20,30	0,1,...,10,15,20,30
TenorList	List of tenor points on yield curve to be used if CurveReport=T.	No	Any set of positive numbers. List does not need to be sorted. '0' is added automatically if not explicitly declared.	0,1,...,10,15,20,30	0,1,...,10,15,20,30

Mixed model allocation options

Field	Description	Required?	Possible values	Example	Default
BrinsonAllocationSectors	Sectors with which to perform allocation attribution on security-level returns. If this field is set to one or more valid sector names, returns will be decomposed using market value (Brinson) allocation. Allocation returns will be calculated using the supplied sector list, and a stock selection return will also be displayed. The Brinson allocation model firstly calculates asset allocation returns for an entire portfolio, and then assigns any remaining return to a stock selection category. The Brinson allocation model should be used for equity portfolios. It is also suitable for mixed portfolios that contain both equity and fixed income securities. If the portfolio has been managed from the top-down in terms of security type and then country allocations, set BrinsonAllocationSectors=pricing, country (assuming a country variable has been defined). The program will then calculate the return made by the security type allocation decision, then the return made by the country allocation decision for each pricing type, and then a security selection return. If the configuration file has been set up to calculate fixed income returns, then these effects will be displayed in the system's report. If fixed income allocation decisions have been taken, then they will show up in the same report. For instance, if a configuration file requires both overall asset allocation returns and spread duration allocation returns, then values should be assigned to BrinsonAllocationSectors and SpreadAllocationSectors, and corresponding returns will be displayed on the attribution report. If equity attribution is to be run, the value of the Residual label should be changed to Stock selection. Equity securities have no interest rate exposures, so no carry return will be generated and all non-allocation return will be directed to this return category.	No	See below	See below	[Blank]

Fixed income allocation attribution options

Field	Description	Required?	Possible values	Example	Default
CarryAllocationSectors	Sectors with which to perform allocation attribution on security-level carry returns. If this field is set to one or more valid sector names, carry returns will be decomposed using market value allocation. Allocation returns on carry will be calculated using the supplied sector list, and a stock selection return will also be displayed. Only market allocation is available for carry returns. If carry return is decomposed into multiple sources of sub-return (such as running yield and pull-to-par) then the overall allocation return for carry will be calculated, followed by individual stock selection returns, one for each source. For instance, if CarryAllocationSectors is set to Credit, Duration then the following four sources of carry return will be calculated: Carry allocation return due to credit allocation decisions Carry allocation return due to duration allocation decisions Running yield return Pull-to-par return If a portfolio does not generate any carry returns (for instance, if it only contains equities), no carry allocation or selection returns will be calculated.	No	See below	See below	[Blank]
CurveAllocationSectors	Sectors with which to perform allocation attribution on security-level curve (non-carry) returns. Allocation returns will be calculated using the supplied sector list, and a stock selection return will also be displayed, decomposed into fixed income effects if required. For instance, if CurveAllocationSectors is set to Credit, Country and the fixed income effects are Curve and Credit then the following five sources of curve return will be calculated: Market direction return Duration allocation return due to credit duration allocation decisions Duration allocation return due to country duration allocation decisions Curve returns Credit returns Note that curve and credit returns will be differ from the values calculated using a bottom-up approach, since a different attribution model is being used.	No	See below	See below	[Blank]
SpreadAllocationSectors	Sectors with which to perform spread allocation attribution on security-level curve spread returns. Allocation returns will be calculated using the supplied sector list, and a stock selection return will also be displayed, decomposed into fixed income effects if required. For instance, if SpreadAllocationSectors is set to Credit, Country and the fixed income effects are Curve and Credit then the following five sources of curve return will be calculated: Market spread direction return Spread duration allocation return due to credit spread duration allocation decisions Spread duration allocation return due to country spread duration allocation decisions Curve returns Credit returns Note that curve and credit returns will be differ from the values calculated using a bottom-up approach, since a different attribution model is being used.	No	See below	See below	[Blank]
DTS	This setting calculates spread duration allocation returns using a Duration Times Spread (DTS) approach rather than a vanilla spread duration allocation approach. This setting is only used if a value has been assigned to SpreadAllocationSectors, so that spread duration allocation is being calculated.	No	on,off,yes,no,1,0,true,false	Yes	No
ResidualAsCredit	If there is significant credit return in the residual term, this switch labels return of type residual as having type credit, so it contributes to the curve allocation attribution calculation. This setting is only used if a value has been assigned to CurveAllocationSectors, so that spread duration allocation is being calculated. ResidualCredit should only be used for a portfolio where there is significant credit return, but no credit curve.	No	on,off,yes,no,1,0,true,false	Yes	No

Smoothing options

Field	Description	Required?	Possible values	Example	Default
SmoothingModel	String indicating type of smoothing algorithm required. CARINO: Arithmetic smoothing using the Carino algorithm (return contributions combine arithmetically). GEOMETRIC: Geometric smoothing (return contributions combine multiplicatlively) [Other values are reserved for future expansion]	No	CARINO GEOMETRIC	GEOMETRIC	CARINO

Benchmark hedging options

Field	Description	Required?	Possible values	Example	Default
HedgeCurrency	Currency in which hedging is performed. HedgeCurrency must be a currency code of the same type supplied in the FX file. If HedgeCurrency is not set, no hedging is performed.	No	Any three-character ISO 4217 currency label	AUD	None
HedgeRatio	Hedge ratio for hedging calculation. HedgeRatio must lie between 0 (no hedging) and 1 (100% hedging).	No	0.0 to 1.0	0.5	1.0

Futures cash offset options

Field	Description	Required?	Possible values	Example	Default
UseCashOffsets	Whether to use cash holdings in portfolio as offsets against futures holdings If this switch is set to 'on', futures holdings are treated exactly like the underlying security, and a cash offset must be included in the portfolio's holdings to replicate the zero effective exposure of futures. If the switch is set to 'off' (the default), the zero effective exposure of futures contracts is taken into account automatically when calculating performance. Many commercial attribution systems calculate and export cash offset holdings by default. Futures cash offset holdings must be set up as zero-interest, since they are an accounting convenience rather than a physical asset.	No	on,off,yes,no,1,0,true,false	Yes	No

Reporting options

Field	Description	Required?	Possible values	Example	Default
XLSReport	Whether to generate Excel reports	No	on,off,yes,no,1,0,true,false	on	on
CSVReport	Whether to generate CSV reports	No	on,off,yes,no,1,0,true,false	on	on
SummaryAttributionReport	Whether to generate summary reports, showing returns from all risks aggregated over all dates and securities. Relative reports are generated if a benchmark is provided.	No	on,off,yes,no,1,0,true,false	on	on
MaturityExposureReport	Whether to generate maturity bucketed exposure reports. Relative exposure reports are generated if a benchmark is provided.	No	on,off,yes,no,1,0,true,false	on	on
DurationExposureReport	Whether to generate duration bucketed exposure reports. Relative exposure reports are generated if a benchmark is provided.	No	on,off,yes,no,1,0,true,false	on	on
InteractiveAttributionReport	Whether to generate interactive risk reports (Excel only). Relative risk reports are generated if a benchmark is provided.	No	on,off,yes,no,1,0,true,false	on	on
SecurityAttributionReport	Whether to generate reports showing unweighted returns	No	on,off,yes,no,1,0,true,false	on	on
SecurityRiskNumberReport	Whether to generate reports showing price, duration, yield, convexity	No	on,off,yes,no,1,0,true,false	on	on
DateRiskReport	Whether to generate reports showing portfolio returns and risks over time, both by time interval and cumulative	No	on,off,yes,no,1,0,true,false	on	on
SQLDataReport	Whether to generate a CSV report showing weights and risk returns at the security level in a format suitable for importing into an SQL database	No	on,off,yes,no,1,0,true,false	on	on
CurveReport	Whether to generate reports showing sovereign yield curves used in analysis broken down according to the requested decomposition.	No	on,off,yes,no,1,0,true,false	on	on
TreeMapReport	Whether to generate a CSV file containing data about the current portfolio suitable for generating a tree map report.	No	on,off,yes,no,1,0,true,false	on	off
ReportSectors	Names of sectors, in order, to be used when generating a drill-down reports. See the following section for more information on this option.	No	See below	See below	PRICING,CURRENCY,SECURITY
LookThrough	For portfolios that contain one or more levels of subportfolios, whether to show the subportfolios in the same way as securities in the upper level portfolio, or to show the constituent securities only without any nesting structure	No	on,off,yes,no,1,0,true,false	on	on
RootLevelOnly	For portfolios that contain one or more levels of subportfolios, whether to generate reports only for the top level portfolio, or to generate stand-alone reports for all subportfolios.	No	on,off,yes,no,1,0,true,false	on	on
SkipFirstDate	Controls whether the start date shown on reports is the date at the start of the first interval, or at the end of the first interval.	No	on,off,yes,no,1,0,true,false	on	off

Start and end dates

Field	Description	Required?	Possible values	Example	Default
Start date	Start date for report	No	[Any date]	31-Dec-2015	N/A
End date	End date for report	No	[Any date]	31-Jan-2015	N/A

Notes

The start date must lie on or before the end date.

If no dates are supplied, the program calculates results over all the dates in the supplied returns files.

For a report covering a single interval, the start and end dates should be the same.

For instance, if you want to calculate attribution reports over a single day (say, 6th July to 7th July 2015), the calculation is for the single interval ending 7th July 2015. In this case, set StartDate=07-07-15 and EndDate=07-07-15.

To view results over a calendar month, set StartDate to be the first day in the month, and EndDate to be the last day. For instance, to calculate returns over January 2015 set StartDate=01-Jan-2015 and EndDate=31-Jan-2015. The results will include the return generated between 31st December 2014 and 1st January 2015.

Reporting and allocation options

ReportSectors, CarryAllocationSectors, CurveAllocationSectors and SpreadAllocationSectors each require a comma-delimited list of sector names.

Sectors can be in any order and in any number.

CarryAllocationSectors, CurveAllocationSectors and SpreadAllocationSectors can only have one instance each defined. However, unlike other reporting options, you can define as many instances of ReportSectors as you wish. Each instance will generate a separate drill-down report on your data.

There are two types of sector.

The first sector type are those that are always available; these are CURRENCY, CREDIT, CURVE, MATURITY, DURATION, SECURITY.

• CURRENCY is the name of the security' currency, defined in column 6 of the security master file
• CREDIT is the security credit rating, either defined in column 11 of the security master file or assigned by default
• CURVE is the security's assigned risk-free yield curve, defined in column 8 of the security master file
• MATURITY is the maturity bucket into which the security falls at the report date. Maturity buckets are set up in the configuration file. Note that a security's maturity bucket may change over time as its maturity decreases. All maturity calculation and bucket assignments are handled automatically by FIA; there is no need to perform any maturity bucketing calculations.
• DURATION is the duration bucket into which the security falls at the report date. Duration buckets are set up in the configuration file. Note that a security's duration bucket may change over time as its duration changes. All duration calculation and bucket assignments are handled automatically by FIA; there is no need to perform any duration bucketing calculations.

The second sector type are those sector names defined in the Custom sectors column of the security master file. If a particular security has not had its sector type defined, a default value of Unassigned is used.

For instance, if you have Country = (country name) defined, then the sector COUNTRY can also be used for reporting and for allocation calculations.

Often, the last entry in the ReportSectors list will be SECURITY, as this ensures that the bottom-most level of the drill-down report always shows individual securities. However, the SECURITY field can be omitted, in which case the lowest level of the drill-down report will correspond to the last sector given in the list.

A typical group of ReportSectors looks as follows:

[FIA]
...
ReportSectors = Duration, Credit, Security
ReportSectors = Maturity, Security
ReportSectors = Currency, Country, Security
ReportSectors = Curve

• The first entry generates a drill-down report by duration bucket, then by credit rating, and finally by security.
• The second entry generates a drill-down report by maturity bucket, then by security.
• The third entry generates a drill-down report by currency, then by country, then by security. Note that Country is not available by default, so a Country=VALUE entry must be set up for each line in the security master file.
• The fourth entry generates a drill-down report by assigned yield curve only. No information at the security level is provided.

FIA allows at most 8 levels in the drill-down report, due to constraints imposed by Excel.