Calling the API
Contents |
Introduction
This page describes how to call the Flametree attribution engine from within another application, using the Appllication Programming Interface (API).
The Flametree API is a collection of function calls and related constants that allow the FIA attribution engine to be called from within another program, rather than as a stand-alone application.
The library is written in C++ and is compiled as a 64-bit DLL (Dynamic Link Library) for Windows, and as a shared object library for Linux. Wrapper files are available that allow the engine to be called from other languages, including C#, Python and Java.
The API uses 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
- it is simple to understand and use;
- it is future-proof, in that planned additions to the engine’s functionality in future releases will not break existing code that calls the library.
Data structures
In addition to the usual types of parameter such as integer and boolean-valued switches, FIA uses vector and matrix types to pass data to and from the host program.
A vector type is defined as
typedef vector <string> VECTOR_MATRIX;
A matrix type is defined as
typedef vector <vector<string> > STRING_MATRIX;
Please refer to the appropriate language section to see how to instantiate and use these data structures in non-C++ environments.
API Functions
The following API functions are available to the user:
int FIA_set_integer ( const int parameter_ID, const int value ) int FIA_set_long ( const int parameter_ID, const long value ) int FIA_set_double ( const int parameter_ID, const double value ) int FIA_set_bool ( const int parameter_ID, const bool value ) int FIA_set_string ( const int parameter_ID, string value ) int FIA_set_vector_string ( const int parameter_ID, VECTOR_MATRIX value ) int FIA_set_matrix ( const int parameter_ID, STRING_MATRIX value ) STRING_MATRIX FIA_get_matrix ( const int parameter_ID ) int FIA_run ( void )
Functions may be called in any order, but the FIA engine will log one or more errors if there are problems. For instance, calling FIA_run() before setting up portfolio, security and yield curve data will generate a fatal error, as will setting a constrained string-value switch to an invalid value.
Symbolic constants
When calling an API function, always use the symbolic constant rather than its numerical value. This makes your code self-documenting and guards against any possible future reallocation of values.
The type of each constant is supplied within its name.
For instance,
- FT_STRING_SOVEREIGN_CURVE_DECOMPOSITION has type string.
- FT_MATRIX_PORTFOLIO has type matrix.
The full list of symbolic constants, supplied in file enum.cs in your installation files, is as follows:
| Name |
|---|
| 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_DIAGNOSTIC |
| FT_STRING_CARRY_DECOMPOSITION |
| FT_STRING_CARRY_ALLOCATION_SECTORS |
| 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 |
| FT_STRING_CURVE_ALLOCATION_SECTORS |
| FT_STRING_SPREAD_ALLOCATION_SECTORS |
| FT_BOOL_ROLLDOWN_ATTRIBUTION |
| FT_BOOL_CONVEXITY_ATTRIBUTION |
| FT_BOOL_PAYDOWN_ATTRIBUTION |
| FT_BOOL_SECURITY_SPECIFIC_ATTRIBUTION |
| FT_BOOL_Z_SPREAD_ATTRIBUTION |
| FT_BOOL_INTERACTION_ATTRIBUTION |
| FT_STRING_BRINSON_ALLOCATION_SECTORS |
| FT_BOOL_CSV_REPORT |
| FT_BOOL_XLS_REPORT |
| FT_BOOL_CSV_HEADER |
| FT_BOOL_RAW_REPORT |
| FT_BOOL_TREEMAP_REPORT |
| FT_BOOL_REPORT_FILE_NAMES |
| FT_BOOL_SORT_DESCENDING |
| FT_BOOL_ROOT_LEVEL_ONLY |
| FT_BOOL_LOOK_THROUGH |
| FT_BOOL_HIDE_ZERO_BENCHMARK_HOLDINGS |
| 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_EXPOSURES_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_TRACKING_ERROR_REPORT |
| FT_BOOL_SQL_DATA_REPORT |
| FT_STRING_FX_RETURN_LABEL |
| FT_STRING_INTERACTION_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_CURVE_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_MATURITY_BUCKETS |
| FT_STRING_DURATION_BUCKETS |
| FT_STRING_COUPON_BUCKETS |
| FT_STRING_TENOR |
| FT_STRING_REPORT_SECTORS |
| FT_STRING_REPORT_DIRECTORY |
| FT_STRING_REPORT_FORMAT |
| 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 |
| FT_STRING_START_DATE |
| FT_STRING_END_DATE |
| FT_STRING_BRINSON_MODEL |
| FT_STRING_SMOOTHING_MODEL |
| FT_BOOL_PRICE_RETURN |
| FT_BOOL_BASE_TO_LOCAL |
| FT_BOOL_USE_CASH_OFFSETS |
| FT_BOOL_RETURN_CODES |
| FT_BOOL_RESIDUAL_AS_CREDIT |
| FT_STRING_BASE_CURRENCY |
| FT_STRING_HEDGE_CURRENCY |
| FT_INT_N_CORES |
| FT_INT_BATCH_ID |
| FT_BOOL_INTERPOLATE_AT_TTM |
| FT_INT_NDP |
| FT_BOOL_TOTALS_AT_TOP |
| FT_BOOL_DTS |
| FT_BOOL_SKIP_FIRST_DATE |
| FT_BOOL_SILENT |
| FT_BOOL_LOCAL_TO_BASE |
| FT_BOOL_FILE_HEADERS |
| FT_BOOL_RETURN_RESULTS_IN_API |
Using the API
The API is called via a sequence of function calls, similar to those shown below:
FIA_set_matrix ( FT_MATRIX_SECURITY, security_data ); FIA_set_matrix ( FT_MATRIX_PORTFOLIO, portfolio_data ); FIA_set_matrix ( FT_MATRIX_BENCHMARK, benchmark_data ); FIA_set_matrix ( FT_MATRIX_YIELDCURVE, yieldcurve_data );
These calls assign string matrices of security, portfolio, benchmark and yield curve data.
FIA_set_string ( FT_STRING_CARRY_DECOMPOSITION, "AGGREGATED" ); FIA_set_string ( FT_STRING_SOVEREIGN_CURVE_DECOMPOSITION, "STB" ); FIA_set_bool ( FT_BOOL_CONVEXITY_ATTRIBUTION, true );
These calls set up the attribution calculation. Carry effects are set to AGGREGATED, sovereign curve attribution is set to Shift/Twist/Butterfly, and returns due to convexity are calculated.
FIA_set_bool ( FT_BOOL_CSV_REPORT, false ); FIA_set_bool ( FT_BOOL_XLS_REPORT, true );
These settings turn XLS report generation on and CSV report generation off.
FIA_set_string ( FT_STRING_REPORT_DIRECTORY, ".\\demo" );
This line tells the program to write all reports to a subdirectory called demo below the current directory.
FIA_set_string ( FT_STRING_DATE_FORMAT, "%d-%b-%y" );
This line tells the program that all dates in the supplied data files are in the form 13-May-15.
FIA_set_long ( FT_LONG_BATCH_ID, 999 );
This line assigns the batch number 999 to all reports.
FIA_run();
This line runs the attribution engine.
diagnostic_data = FIA_get_matrix ( FT_MATRIX_DIAGNOSTIC );
This line assigns all program diagnostic data to STRING_MATRIX diagnostic_data. The contents of this matrix may be used elsewhere in the program.
