Calling the API

From Flametree Technologies
Revision as of 07:36, 27 June 2015 by Fiasys (Talk | contribs)
Jump to: navigation, search

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 into a 64-bit DLL (Dynamic Link Library). Wrapper files are alsp available that allow the engine to be called from other languages, including as C#, Python and Java.

The API was substantially redesigned in 2015 to use 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

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.


Functions

The following 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 )

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_STRING_SOVEREIGN_CURVE_DECOMPOSITION has type string.

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_FX FX data 6
FT_MATRIX_CPI CPI and index data 7
FT_MATRIX_RESULTS Results data 8
FT_MATRIX_DIAGNOSTIC Diagnostics data 9
FT_STRING_CARRY_DECOMPOSITION Carry settings 100
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_DOUBLE_SHIFT_MATURITY Shift maturity 204
FT_STRING_KRD KRD settings 205
FT_STRING_CURVE_ALLOCATION_SECTORS Curve allocation sectors 206
FT_STRING_SPREAD_DECOMPOSITION Spread decomposition 300
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 that 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 );
   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 );
   FIA_set_bool ( FT_BOOL_CSV_REPORT, false );
   FIA_set_bool ( FT_BOOL_XLS_REPORT, true );
   FIA_set_string ( FT_STRING_REPORT_DIRECTORY, ".\\demo" );
   FIA_set_string ( FT_STRING_DATE_FORMAT, "%d-%b-%y" );
   FIA_set_long ( FT_LONG_BATCH_ID, 999 );
   FIA_run();
   diagnostic_data = FIA_get_matrix ( FT_MATRIX_DIAGNOSTIC );
Personal tools
Namespaces
Variants
Actions
Manual
Attribution methodology
Data
Configuration
Running FIA
Reporting
Tutorials
Additional information
Company
Downloads
Toolbox