Calling the API

From Flametree Technologies
Jump to navigation Jump to search


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 for data structures

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_MATRIX_PORTFOLIO has type matrix.

FT_BOOL_INFLATION_ATTRIBUTION // Attribution switches - mixed/hybrid const int FT_STRING_MIXED_ALLOCATION_SECTORS = 500; // Report settings const int FT_BOOL_CSV_REPORT = 600; const int FT_BOOL_XLS_REPORT = 601; const int FT_BOOL_CSV_HEADER = 602; const int FT_BOOL_RAW_REPORT = 603; const int FT_BOOL_TREEMAP_REPORT = 604; const int FT_BOOL_REPORT_FILE_NAMES = 605; const int FT_BOOL_SORT_DESCENDING = 606; const int FT_BOOL_ROOT_LEVEL_ONLY = 607; const int FT_BOOL_LOOK_THROUGH = 608; // Individual reports const int FT_BOOL_SUMMARY_RISK_REPORT = 700; const int FT_BOOL_STRESS_REPORT = 701; const int FT_BOOL_STATIC_RISK_REPORT = 702; const int FT_BOOL_RAW_RETURNS_REPORT = 703; const int FT_BOOL_INTERACTVE_RISK_REPORT = 704; const int FT_BOOL_EXPOSURES_REPORT = 705; const int FT_BOOL_DURATION_EXPOSURE_REPORT = 706; const int FT_BOOL_MATURITY_EXPOSURE_REPORT = 707; const int FT_BOOL_DATE_RISK_REPORT = 708; const int FT_BOOL_EX_POST_RISK_REPORT = 709; const int FT_BOOL_CURVE_REPORT = 710; const int FT_BOOL_TRACKING_ERROR_REPORT = 711; const int FT_BOOL_SQL_DATA_REPORT = 712; // Labels const int FT_STRING_FX_RETURN_LABEL = 800; const int FT_STRING_INTERACTION_LABEL = 801; const int FT_STRING_TIME_RETURN_LABEL = 802; const int FT_STRING_RUNNING_YIELD_LABEL = 803; const int FT_STRING_PULL_TO_PAR_LABEL = 804; const int FT_STRING_RISK_FREE_CARRY_LABEL = 805; const int FT_STRING_CREDIT_CARRY_LABEL = 806; const int FT_STRING_ROLLDOWN_RETURN_LABEL = 807; const int FT_STRING_SPREAD_RETURN_LABEL = 808; const int FT_STRING_RESIDUAL_RETURN_LABEL = 809; const int FT_STRING_SOVEREIGN_CURVE_RETURN_LABEL = 810; const int FT_STRING_DURATION_CURVE_RETURN_LABEL = 811; const int FT_STRING_NON_PARALLEL_CURVE_RETURN_LABEL = 812; const int FT_STRING_CONVEXITY_RETURN_LABEL = 813; const int FT_STRING_TOTAL_RETURN_LABEL = 814; const int FT_STRING_SHIFT_RETURN_LABEL = 815; const int FT_STRING_TWIST_RETURN_LABEL = 816; const int FT_STRING_CURVATURE_RETURN_LABEL = 817; const int FT_STRING_INFLATION_RETURN_LABEL = 818; const int FT_STRING_PAYDOWN_RETURN_LABEL = 819; const int FT_STRING_CASH_RETURN_LABEL = 820; const int FT_STRING_UNATTRIBUTED_RETURN_LABEL = 821; const int FT_STRING_PRICE_RETURN_LABEL = 822; // Report sector settings const int FT_STRING_MATURITY_BUCKETS = 900; const int FT_STRING_DURATION_BUCKETS = 901; const int FT_STRING_COUPON_BUCKETS = 902; const int FT_STRING_TENOR = 903; const int FT_STRING_REPORT_SECTORS = 904; // General report settings const int FT_STRING_REPORT_DIRECTORY = 1000; const int FT_STRING_REPORT_FORMAT = 1001; // Date formats const int FT_STRING_DATE_FORMAT = 1100; const int FT_STRING_SECURITY_DATE_FORMAT = 1101; const int FT_STRING_PORTFOLIO_DATE_FORMAT = 1102; const int FT_STRING_BENCHMARK_DATE_FORMAT = 1103; const int FT_STRING_YIELDCURVE_DATE_FORMAT = 1104; const int FT_STRING_FX_DATE_FORMAT = 1105; const int FT_STRING_CPI_DATE_FORMAT = 1106; // Miscellaneous const int FT_STRING_START_DATE = 11200; const int FT_STRING_END_DATE = 1201; const int FT_STRING_BRINSON_MODEL = 1202; const int FT_STRING_SMOOTHING_MODEL = 1203; const int FT_BOOL_PRICE_RETURN = 1204; const int FT_BOOL_BASE_TO_LOCAL = 1205; const int FT_BOOL_USE_CASH_OFFSETS = 1206; const int FT_BOOL_RETURN_CODES = 1207; const int FT_BOOL_RESIDUAL_AS_CREDIT = 1208; const int FT_STRING_BASE_CURRENCY = 1209; const int FT_STRING_HEDGE_CURRENCY = 1210; const int FT_INT_N_CORES = 1211; const int FT_LONG_BATCH_ID = 1211;
Name Description Value
FT_MATRIX_PORTFOLIO Portfolio data 0
FT_MATRIX_BENCHMARK Benchmark data 1
FT_MATRIX_SECURITY Security master data 2
FT_MATRIX_YIELDCURVE Yield curve data 3
FT_MATRIX_STRESS Stress scenario data 4
FT_MATRIX_MAP Security mapping data 5
FT_MATRIX_CPI CPI and index data 7
FT_MATRIX_RESULTS Results data 8
FT_MATRIX_DIAGNOSTIC Diagnostics data 9
FT_STRING_CARRY_ALLOCATION_SECTORS Carry allocation settings 101
FT_STRING_SOVEREIGN_CURVE_DECOMPOSITION Sovereign curve decomposition 200
FT_STRING_AVERAGE_CURVE_LEVEL Average sovereign curve level 201
FT_DOUBLE_LOWER_TWIST_MATURITY Lower curve twist maturity 202
FT_DOUBLE_UPPER_TWIST_MATURITY Upper curve twist maturity 203
FT_STRING_KRD KRD settings 205
FT_STRING_CURVE_ALLOCATION_SECTORS Curve allocation sectors 206
FT_STRING_SPREAD_ALLOCATION_SECTORS Spread allocation sectors 301
FT_STRING_RATINGS_LIST String ratings list 302
FT_BOOL_ROLLDOWN_ATTRIBUTION Rolldown attribution switch 400
FT_BOOL_CONVEXITY_ATTRIBUTION Convexity attribution switch 401
Inflation attribution switch 402
FT_BOOL_PAYDOWN_ATTRIBUTION Paydown attribution switch 403
FT_BOOL_CASH_ATTRIBUTION Cash attribution switch 404
FT_BOOL_FX_ATTRIBUTION FX attribution switch 405

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.


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.


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.