FIA has a large number of configuration options. These allow all aspects of the calculation to be tailored to your input data formats, investment model and reporting requirements.
Only a small number of quantities must be set in order to run an analysis. In all other cases, FIA provides sensible defaults.
Configuration can be carried out in a configuration file, as settings in the GUI, via calls to the local API, or over the Web API. However, the names and settings of FIA's variables are identical in all cases. In this section, we focus on how to set up a configuration file, as the settings are virtually identical for other modes.
The configuration file
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 does not correspond to a defined field, 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
VALUE can be upper or lower case.
For Boolean-valued options, use the pattern
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 recognised by FIA, the program will stop with an error message.
|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|
- 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 allocation attribution, which specifically requires a benchmark. In this case FIA will generate an error message and halt.
|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|
Click here for more information about date formats.
General reporting settings
|BasisPoints||Boolean||If active, shows all returns in terms of basis points. If false, or not set, all returns are shown as percentages.||No||Yes, no, true, false, 1, 0||True||False|
|ndp||Integer||Integer-valued switch, sets how many decimal places are used for reporting.||No||Any integer between 0 and 12||2||4|
|TotalsAtTop||Boolean||Controls whether totals on interactive reports should appear above or below the raw data.||No||Yes, no, true, false, 1, 0||True||False|
|Smoothing||String||Name of smoothing algorithm to use when reporting
If set, the given logo file is inserted into every Excel worksheet
|SortDescending||Boolean||In interactive reports, controls whether results are shown in ascending or descending order||No|
|BatchID||Integer||Assigns a number to each report's name. If not set, a random number is assigned.|
|LookThrough||Boolean||If true, all holdings in sub-portfolios are displayed as if they are holdings in the top level portfolio.
If false, holdings in sub-portfolios are displayed in aggregate
|RootLevelOnly||Boolean||If true, no reports are generated for sub-portfolios|
|ReportSectors||String||Configures the hierarchy and data shown in a drill-down report.
See here for more information.
File-based reporting settings
The following table describes the various file-based reporting options available within FIA.
|ReportDirectory||String||Name of the directory to which reports are written.
If not set, reports are written to the current active directory.
|No||Any valid directory string for your operating system, including relative paths.||c:\mydata
|SingleExcelReportFile||String||Name of Excel workbook to which all Excel reports are written.
If set, all reports are written into separate worksheeets within workbook If not set, all Excel reports are written to separate workbooks
Note that the Excel suffix should not be provided.
|ZipFile||String||Name of zip file to which all reports are written
If set, all reports are written into a compressed Zip file with this name, and the originals erased
|LogoFile||String||Name of logo file in JPG format
If set, the given logo file is inserted into every Excel worksheet
|CSVreport||Boolean||Generate CSV reports|
|XLSreport||Boolean||Generate Excel reports|
If ReportDirectory does not exist, FIA will try to create it before running reports. If this is unsuccessful (for instance, if FIA does not have sufficent permissions on your system) the program will abort with an error message.
Directories are not case sensitive on Windows systems, but are case sensitive on Linux and Unix systems.
FIA's reporting options are controlled from the configuration file. In this section, we described the options available.
Click on the name of the report for more information.
|SummaryAttributionReport||Boolean||Generate summary report|
|InteractiveAttributionReport||Boolean||Generate hierarchical report|
|PortfolioRiskNumberReport||Boolean||Generates history of portfolio and benchmark risk numbers (YTM, MD, C, Z-spread, leverage) at each date over calculation interval|
|SecurityRiskNumberReport||Boolean||Generates report showing risk numbers for all securities in portfolio and benchamrk at last date in calculation interval|
|SecurityAttributionReport||Boolean||Shows attribution returns for all securities in portfolio and benchamrk over calculation interval|
|MaturityExposureReport||Boolean||Shows allocation to maturity buckets at last date in calculation interval. Maturity buckets are defined here|
|DurationExposureReport||Boolean||Shows allocation to duration buckets at last date in calculation interval. Duration buckets are defined here|
|DateRiskReport||Boolean||Shows aggregated attribution returns at portfolio level over calculation interval. Both daily and cumulative reports are generated.|
|SQLDataReport||Boolean||Generates file of normalised returns, ready for import into an SQL data table|
|ExPostRiskReport||Boolean||Generates ex-post risk statistics|
|CurveReport||Boolean||Generates report on yield curve movements. If more than one yield curve is supplied, Excel reports are written to separate worksheets in the same workbook.|
|StressReport||Boolean||Generates stress report|
|TreeMapReport||Boolean||Generate data for use in heat map|
Interactive reports can be extensively configured. Click here for more information.
|TimeReturnLabel||Label for time/coupon return. Only used when CouponDecomposition set to AGGREGATED||Coupon|
|RunningYieldLabel||Label for return due to runninh yield. Only used when CouponDecomposition set to PULL_TO_PAR||Running yield|
|PullToParLabel||Label for return due to pull to par effects. Only used when CouponDecomposition set to PULL_TO_PAR||Pull to par|
|RiskFreeCarryLabel||Label for return due to risk free yield. Only used when CouponDecomposition set to CREDIT_CARRY||Risk-free carry|
|CreditCarryLabel||Label for return due to pull to par effects. Only used when CouponDecomposition set to CREDIT_CARRY||Credit carry|
|RolldownLabel||Label for rolldown return||Rolldown|
|ResidualReturnLabel||Label for residual return||Residual|
|SovereignCurveReturnLabel||Label for return due to changes in sovereign curve||Sovereign curve|
|CapitalCurveReturnLabel||Label for return due to changes in capital return||Capital|
|DurationCurveReturnLabel||Label for return due to parallel changes in the sovereign curve. Only used when SovereignCurveDecomposition set to DURATION||Duration|
|NonParallelCurveReturnLabel||Label for return due to non-parallel changes in the sovereign curve. Only used when SovereignCurveDecomposition set to DURATION||Non-parallel curve|
|ShiftReturnLabel||Label for return due to parallel shift in sovereign curve. Only used when SovereignCurveDecomposition set to STB||Shift|
|TwistReturnLabel||Label for return due to steepening or flattening in sovereign curve. Only used when SovereignCurveDecomposition set to STB||Twist|
|CurvatureReturnLabel||Label for return due to increasing or decreasing curvature in sovereign curve. Only used when SovereignCurveDecomposition set to STB||Curvature|
|ConvexityReturnLabel||Label for return due to convexity.||Convexity|
|SpreadReturnLabel||Label for return due to movements in the country or sector spread||Spread|
|FXReturnLabel||Label for return due to changes in exchange rates||FX return|
|UnatttributedReturnLabel||Label for return to due unattributed securities||Unattributed|
|TotalReturnLabel||Label for sum of all returns||Total|
FIA allows the names of any of the displayed sources of risk to be changed. For instance, to change Residual to Credit, set
in the configuration file. Note that no quotation marks are required.