Calling the local API

From Flametree Technologies
Jump to: navigation, search

Contents

Introduction

The Flametree Application Program Interface (API) is a collection of function calls and related constants that allow the Flametree FIA attribution engine to be called from another program.

The Flametree attribution engine is written in C++. However, we provide language wrappers that allow the core library to be called from a wide range of languages, including C++, C-Sharp, Python and Java.

This page assumes that you are calling a locally deployed version of the Flametree engine. If you wish to call the software remotely over the Internet, please refer to the section on Flametree's Web API.

Functions

The Flametree API contains the following functions:

int FIA_set_integer          ( const int SYMBOLIC_CONSTANT, const int value );
int FIA_set_double           ( const int SYMBOLIC_CONSTANT, const double value );
int FIA_set_bool             ( const int SYMBOLIC_CONSTANT, const bool value );
int FIA_set_string           ( const int SYMBOLIC_CONSTANT, const std::string value );
int FIA_set_vector_string    ( const int SYMBOLIC_CONSTANT, const vector<std::string> value );
int FIA_set_matrix           ( const int SYMBOLIC_CONSTANT, STRING_MATRIX value );
STRING_MATRIX FIA_get_matrix ( const int SYMBOLIC_CONSTANT );
void FIA_init                ( void );
int FIA_run                  ( void );
std::string FIA_get_version  ( void );

where STRING_MATRIX is defined as

typedef std::vector <std::vector<std::string> > STRING_MATRIX;

Here, SYMBOLIC_CONSTANT identifies the quantity to be set or read, and value is its supplied value.

All parameters required to run the Flametree engine are passed via calls to functions with the prefix ‘FT_set_’, including the names of data arrays for input and output, switches that control the attribution analysis, values to specify the type and format of reports, and other information such as date format strings.

The very first API command you should call is FIA_init() to set up all parameters with default values, and to clear any previously assigned data. If you do not call this command, the API will be called with undefined inputs and may fail with unpredictable results.

Parameters may be specified in any order, and FT_run() may be called multiple times in the same program. Since parameter settings are preserved between runs, this allows the user to run the engine multiple times in the same session. For instance, if a large number of portfolios are to be analysed using the same attribution settings, only the names of the data arrays need be changed between calls to FT_run().

Results may be accessed via the contents of a STRING_MATRIX returned by FIA_get_matrix. Depending on the settings of various reporting switches, the FIA engine will also write CSV and XLS reports to disk each time FT_run() is called.

It is typically not necessary to set every parameter, since FT_init() assigns sensible defaults for all quantities. As a result, you may find it is only necessary to set a small number of parameters to achieve the results you require. Default values for each parameter are shown in the Data Dictionary tables later in this document.

Each call to an API function returns a status code. A value of ERR_OK = 0 indicates a successful call, and any other value indicates a failure.

This API is an example of a data–driven interface (also known as a message-passing, or event-based API). Instead of using a large collection of method calls, the API depends on a much smaller number of calls and a data dictionary of arguments. The advantages of using a data-driven API for the Flametree engine are that

API constants

Data types

Data parameters used by the API are of the following standard C++ types:

where STRING_MATRIX is defined by

typedef vector <vector<string> > STRING_MATRIX;

Symbolic constants

A symbolic constant represents a system-defined integer that is used to refer to a particular library parameter.

For instance, the symbolic constant that refers to the security master data array is FT_SECURITY_DATA, and the command to assign a data array called security_data to act as the security master data array is

FIA_set_matrix ( FT_SECURITY_DATA, security_data );

The naming conventions for symbolic constants are

Required files

Any C++ program that makes use of the Flametree API must include file APIWrapper.h via a command of the form

#include “APIWrapper.h”

This ensures that the API function prototypes are recognised and that the various symbolic constants used are resolved at link time. The values of all constants are generated by enum statements in the APIWrapper.h file.

The API also requires that you make the appropriate Flametree run-time library available to your program. The library typically has the name libfiaXX.dll (for Windows) and libfiaXX.so (for Linux), where XX is 32 or 64, depending on the user’s requirements.

Sample usage

The following code fragment shows how to call the API from a C++ program.

Include standard header files

#include “APIWrapper.h”

Set up STRING_MATRIX data arrays contains security, portfolio, benchmark and yield curve data

FIA_set_matrix ( FT_SECURITY_DATA, security_data );
FIA_set_matrix ( FT_PORTFOLIO_DATA, portfolio_data );
FIA_set_matrix ( FT_BENCHMARK_DATA, benchmark_data );
FIA_set_matrix ( FT_YIELDCURVE_DATA, yieldcurve_data );

Set up attribution analysis to calculate aggregated carry effects

FIA_set_string ( FT_STRING_CARRY_DECOMPOSITION, “AGGREGATED” );

Decompose sovereign yield curve movements into shift, twist, curvature movements

FIA_set_string ( FT_STRING_SOVEREIGN_CURVE_DECOMPOSITION, “STB” );

Only generate Excel output files

FIA_set_bool ( FT_BOOL_CSV_REPORT, false );
FIA_set_bool ( FT_BOOL_XLS_REPORT, true );

Run the attribution analysis

FIA_run();

A full set of demo files is available with your release installation.


Reporting and allocation options

Types of sectors

The sectors used by FIA fall into two separate groups.

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

  • PRICING is the name of the pricing function, defined in column 5 of the security master file
  • 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
  • SUPPLEMENTARY_CURVE is the security's assigned supplementary credit curve, defined in column 9 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, depending on the buckets defined in FT_STRING_MATURITY_BUCKETS. 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, depending on the buckets defined in FT_STRING_DURATION_BUCKETS. 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.
  • SECURITY refers to individual securities. This variable is typically not required for asset allocation calculations. It is most often used at the end of a list of sectors in FT_STRING_REPORT_SECTORS, to indicate that a drill-down report’s highest level of detail should be at the individual security level. If the SECURITY field is omitted, the lowest level of the drill-down report will correspond to the last sector given in the list.

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 defined a partition called COUNTRY, then this sector can also be used for reporting and for allocation calculations.

Lists of sectors

Some variables are used to hold a list of sectors in the form of a comma-delimited list.

The following variables hold a single comma-delimited list of sectors:

  • FT_STRING_CARRY_ALLOCATION_SECTORS
  • FT_STRING_CURVE_ALLOCATION_SECTORS
  • FT_STRING_SPREAD_ALLOCATION_SECTORS
  • FT_STRING_MIXED_ALLOCATION_SECTORS

These are all used to set up particular types of attribution analysis. For instance, FT_STRING_MIXED_ALLOCATION_SECTORS allows the user to specify the names and order in which asset allocation calculations should be performed for a Brinson analysis.

FT_STRING_REPORT_SECTORS is used for reporting instead of attribution calculation. This variable identifies a vector of string lists, where each vector of strings generates a separate drill-down report on the library’s output.

Allowed symbolic constants

Data structures

FT_MATRIX_PORTFOLIO
FT_MATRIX_BENCHMARK
FT_MATRIX_SECURITY
FT_MATRIX_YIELDCURVE
FT_MATRIX_STRESS
FT_MATRIX_MAP
FT_MATRIX_FX
FT_MATRIX_INDEX
FT_MATRIX_RESULTS
FT_MATRIX_RISKS
FT_MATRIX_CURVES
FT_MATRIX_DIAGNOSTIC

Date formats

FT_BOOL_FILE_HEADERS
FT_STRING_DATE_FORMAT
FT_STRING_SECURITY_DATE_FORMAT
FT_STRING_PORTFOLIO_DATE_FORMAT
FT_STRING_BENCHMARK_DATE_FORMAT
FT_STRING_YIELDCURVE_DATE_FORMAT
FT_STRING_FX_DATE_FORMAT
FT_STRING_INDEX_DATE_FORMAT

Attribution switches

FT_STRING_CARRY_DECOMPOSITION
FT_STRING_SOVEREIGN_CURVE_DECOMPOSITION
FT_STRING_AVERAGE_CURVE_LEVEL
FT_DOUBLE_LOWER_TWIST_MATURITY
FT_DOUBLE_UPPER_TWIST_MATURITY
FT_DOUBLE_SHIFT_MATURITY
FT_STRING_KRD_VALUES
FT_BOOL_ROLLDOWN_ATTRIBUTION
FT_BOOL_CONVEXITY_ATTRIBUTION
FT_BOOL_PAYDOWN_ATTRIBUTION 
FT_BOOL_SECURITY_SPECIFIC_ATTRIBUTION 
FT_BOOL_Z_SPREAD_ATTRIBUTION	
FT_BOOL_LEVERAGE_ATTRIBUTION		
FT_BOOL_HEDGED_RETURNS		
FT_BOOL_PRICE_RETURN				
FT_BOOL_DTS						
FT_STRING_BRINSON_ALLOCATION_SECTORS 	
FT_STRING_BRINSON_MODEL					
FT_BOOL_INTERACTION_ATTRIBUTION			
FT_STRING_CARRY_ALLOCATION_SECTORS		
FT_STRING_CURVE_ALLOCATION_SECTORS		
FT_STRING_SPREAD_ALLOCATION_SECTORS		
FT_STRING_RESIDUAL_ALLOCATION_SECTORS

General report settings

FT_STRING_REPORT_DIRECTORY 				
FT_STRING_REPORT_FORMAT					
FT_STRING_SINGLE_EXCEL_REPORT_FILE		
FT_STRING_ZIP_FILE						
FT_STRING_LOGO_FILE						
FT_BOOL_CSV_REPORT						
FT_BOOL_XLS_REPORT						
FT_BOOL_PROTECTED_REPORT				
FT_BOOL_ROOT_LEVEL_ONLY					
FT_BOOL_LOOK_THROUGH					
FT_BOOL_TOTALS_AT_TOP					
FT_BOOL_SORT_DESCENDING					
FT_BOOL_HIDE_ZERO_BENCHMARK_HOLDINGS

Which reports to generate

FT_BOOL_SUMMARY_ATTRIBUTION_REPORT 		
FT_BOOL_STRESS_REPORT					
FT_BOOL_PORTFOLIO_RISK_NUMBER_REPORT	
FT_BOOL_SECURITY_RISK_NUMBER_REPORT		
FT_BOOL_SECURITY_ATTRIBUTION_REPORT		
FT_BOOL_INTERACTIVE_ATTRIBUTION_REPORT	
FT_BOOL_DURATION_EXPOSURE_REPORT		
FT_BOOL_MATURITY_EXPOSURE_REPORT		
FT_BOOL_DATE_RISK_REPORT				
FT_BOOL_EX_POST_RISK_REPORT				
FT_BOOL_CURVE_REPORT					
FT_BOOL_SQL_DATA_REPORT					
FT_BOOL_TREEMAP_REPORT

Report sector settings

FT_STRING_MATURITY_BUCKETS 				
FT_STRING_DURATION_BUCKETS				
FT_STRING_COUPON_BUCKETS				
FT_STRING_TENOR_BUCKETS					
FT_STRING_REPORT_SECTORS

Miscellaneous settings

FT_STRING_START_DATE 					
FT_STRING_END_DATE						
FT_STRING_SMOOTHING_MODEL				
FT_BOOL_USE_CASH_OFFSETS				
FT_BOOL_RETURN_CODES					
FT_INT_N_CORES							
FT_INT_BATCH_ID							
FT_BOOL_INTERPOLATE_AT_TTM				
FT_INT_NDP								
FT_STRING_LIBDIR						
FT_STRING_BASE_CURRENCY					
FT_STRING_HEDGE_CURRENCY				
FT_DOUBLE_HEDGE_RATIO					
FT_BOOL_SILENT							
FT_BOOL_ADD_SPREADS

FX conversion flags

FT_BOOL_LOCAL_TO_BASE 					
FT_BOOL_BASE_TO_LOCAL					
FT_BOOL_PORTFOLIO_BASE_TO_LOCAL			
FT_BOOL_PORTFOLIO_LOCAL_TO_BASE			
FT_BOOL_BENCHMARK_BASE_TO_LOCAL			
FT_BOOL_BENCHMARK_LOCAL_TO_BASE

Effect labels

FT_STRING_FX_RETURN_LABEL 				
FT_STRING_TIME_RETURN_LABEL				
FT_STRING_RUNNING_YIELD_LABEL			
FT_STRING_PULL_TO_PAR_LABEL				
FT_STRING_RISK_FREE_CARRY_LABEL			
FT_STRING_CREDIT_CARRY_LABEL			
FT_STRING_ROLLDOWN_RETURN_LABEL			
FT_STRING_SPREAD_RETURN_LABEL			
FT_STRING_RESIDUAL_RETURN_LABEL			
FT_STRING_SOVEREIGN_CURVE_RETURN_LABEL	
FT_STRING_DURATION_CURVE_RETURN_LABEL	
FT_STRING_NON_PARALLEL_RETURN_LABEL 	
FT_STRING_CONVEXITY_RETURN_LABEL		
FT_STRING_TOTAL_RETURN_LABEL			
FT_STRING_SHIFT_RETURN_LABEL			
FT_STRING_TWIST_RETURN_LABEL		
FT_STRING_CURVATURE_RETURN_LABEL	
FT_STRING_PAYDOWN_RETURN_LABEL		
FT_STRING_UNATTRIBUTED_RETURN_LABEL	
FT_STRING_PRICE_RETURN_LABEL		
FT_STRING_SPECIFIC_RETURN_LABEL			
FT_STRING_SECURITY_SPECIFIC_RETURN_LABEL
FT_STRING_Z_SPREAD_RETURN_LABEL			
FT_STRING_INTERACTION_RETURN_LABEL		
FT_STRING_DELTA_RETURN_LABEL			
FT_STRING_LEVERAGE_RETURN_LABEL
Personal tools
Namespaces
Variants
Actions
Manual
File formats
Local API
API
Architecture
Additional information
Company
Downloads
Toolbox