Calling the API

From Flametree Technologies
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

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,

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.

Personal tools
Namespaces
Variants
Actions
Manual
File formats
Architecture
Additional information
Company
Downloads
Toolbox