Calling the API

From Flametree Technologies
Revision as of 07:44, 28 July 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 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

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

FT_MATRIX_PORTFOLIO has type matrix.

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
FT_BOOL_INFLATION_ATTRIBUTION 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
FT_STRING_MIXED_ALLOCATION_SECTORS Hybrid allocation switch 500
FT_BOOL_CSV_REPORT CSV report switch 600
FT_BOOL_XLS_REPORT XLS report switch 601
FT_BOOL_CSV_HEADER CSV header report switch 602
FT_BOOL_RAW_REPORT 603;
FT_BOOL_TREEMAP_REPORT 604
FT_BOOL_REPORT_FILE_NAMES 605
FT_BOOL_SORT_DESCENDING 606
FT_BOOL_ROOT_LEVEL_ONLY 607;
FT_BOOL_LOOK_THROUGH 608
FT_BOOL_SUMMARY_RISK_REPORT 700
FT_BOOL_STRESS_REPORT 701
FT_BOOL_STATIC_RISK_REPORT 702
FT_BOOL_RAW_RETURNS_REPORT 703
FT_BOOL_INTERACTVE_RISK_REPORT 704
FT_BOOL_EXPOSURES_REPORT 705
FT_BOOL_DURATION_EXPOSURE_REPORT 706
FT_BOOL_MATURITY_EXPOSURE_REPORT 707
FT_BOOL_DATE_RISK_REPORT 708
FT_BOOL_EX_POST_RISK_REPORT 709
FT_BOOL_CURVE_REPORT 710
FT_BOOL_TRACKING_ERROR_REPORT 711
FT_BOOL_SQL_DATA_REPORT 712
FT_STRING_FX_RETURN_LABEL 800
FT_STRING_INTERACTION_LABEL 801
FT_STRING_TIME_RETURN_LABEL 802
FT_STRING_RUNNING_YIELD_LABEL 803
FT_STRING_PULL_TO_PAR_LABEL 804
FT_STRING_RISK_FREE_CARRY_LABEL 805
FT_STRING_CREDIT_CARRY_LABEL 806
FT_STRING_ROLLDOWN_RETURN_LABEL 807
FT_STRING_SPREAD_RETURN_LABEL 808
FT_STRING_RESIDUAL_RETURN_LABEL 809
FT_STRING_SOVEREIGN_CURVE_RETURN_LABEL 810
FT_STRING_DURATION_CURVE_RETURN_LABEL 811
FT_STRING_NON_PARALLEL_CURVE_RETURN_LABEL 812
FT_STRING_CONVEXITY_RETURN_LABEL 813
FT_STRING_TOTAL_RETURN_LABEL 814
FT_STRING_SHIFT_RETURN_LABEL 815
FT_STRING_TWIST_RETURN_LABEL 816
FT_STRING_CURVATURE_RETURN_LABEL 817
FT_STRING_INFLATION_RETURN_LABEL 818
FT_STRING_PAYDOWN_RETURN_LABEL 819
FT_STRING_CASH_RETURN_LABEL 820
FT_STRING_UNATTRIBUTED_RETURN_LABEL 821
FT_STRING_PRICE_RETURN_LABEL 822
FT_STRING_MATURITY_BUCKETS 900
FT_STRING_DURATION_BUCKETS 901
FT_STRING_COUPON_BUCKETS 902
FT_STRING_TENOR 903
FT_STRING_REPORT_SECTORS 904
FT_STRING_REPORT_DIRECTORY 1000
FT_STRING_REPORT_FORMAT 1001
FT_STRING_DATE_FORMAT 1100
FT_STRING_SECURITY_DATE_FORMAT 1101
FT_STRING_PORTFOLIO_DATE_FORMAT 1102
FT_STRING_BENCHMARK_DATE_FORMAT 1103
FT_STRING_YIELDCURVE_DATE_FORMAT 1104
FT_STRING_FX_DATE_FORMAT 1105
FT_STRING_CPI_DATE_FORMAT 1106
FT_STRING_START_DATE 11200 FT_STRING_END_DATE 1201 FT_STRING_BRINSON_MODEL 1202
FT_STRING_SMOOTHING_MODEL 1203
FT_BOOL_PRICE_RETURN 1204
FT_BOOL_BASE_TO_LOCAL 1205
FT_BOOL_USE_CASH_OFFSETS 1206
FT_BOOL_RETURN_CODES 1207
FT_BOOL_RESIDUAL_AS_CREDIT 1208
FT_STRING_BASE_CURRENCY 1209
FT_STRING_HEDGE_CURRENCY 1210
FT_INT_N_CORES 1211
FT_LONG_BATCH_ID 1211

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.

Personal tools
Namespaces
Variants
Actions
Manual
Attribution methodology
Data
Configuration
Running FIA
Reporting
Tutorials
Additional information
Company
Downloads
Toolbox