Skip to main content

Analysis and performance metrics

Overview

Analytics+ functionality is a powerful tool to analyze a single or a group of portfolios. This how-to article describes how it can be used to analyze a portfolio via FA's GraphQL API. The content is divided into three sections:

  • Initialization of an Analytics+ call

  • Requesting one or multiple different types of analyses from the Analytics+

  • Accessing the result of an analysis

Analyzing a portfolio or portfolios

Initialization of Analytics+ call

You can analyze the selected portfolio or portfolios efficiently in multiple ways with a single call to the Analytics+ endpoint. However, it is important to initialize the call properly to enable all the intended analyses, but at the same time keep it as efficient as possible.

First of all, there are two alternative ways to call Analytics+:

  1. Call Analytics+ and pass a list of portfolios to analyze

  2. Embed the call under a portfolio element in order to analyze that particular portfolio

Call Analytics+ and pass a list of portfolios to analyze

Calling Analytics+ directly enables you to analyze a combination of portfolios. You need to explicitly tell, which portfolios are to be analyzed by passing the parameter pfIds, which is a list of longs. The syntax looks like this:

query CallAnalyticsDirectly(...) {
  analytics(...) {
    ...
  }
}

Embed the call under a portfolio element

When you embed the call under a portfolio element, you do not need to specify explicitly which portfolio to analyze. The analysis is limited to the portfolio under which the analytics call is embedded.

query CallAnalyticsIndirectly(...) {
  portfolio(...) {
     analytics(...) {
       ...
     }
   }
}

Parameters for initializing the analytics

Parameters for an Analytics+ are defined as follows:

query Analytics(...) {
  analytics(
    withoutPositionData: true/false,
    parameters: {
      pfIds: [pfId1, pfId2,...],
      startDate: "yyyy-MM-dd",
      endDate: "yyyy-MM-dd",
      includeDrilldownPositions: true/false,
      includeOnlyCashAccounts:true/false,
      paramsSet: {
        ...
      }
    }) {
    ...
  }
}

See more detailed documentation in the Parameters for analytics requestsection.

Requesting one or multiple different types of analyses from Analytics+

After loading the underlying data (ie. positions, securities,…), Analytics+ can perform one or multiple types of analyses on the data-set. The analyses are defined using a paramsSet data structure.

The structure looks like this:

paramsSet: [{
   key:"<key>"
   timePeriodCodes:["<time period code>"]
   grouppedByProperties: [<grouping code(s)>]
   includeData: true/false
   includeChildren: true/false
   calculateContribution: true/false
   calculateIrr: true/false
},
{
   ...
}]

See more detailed documentation Parameters for analytics request.

Accessing the result of an analysis

Call to Analytics+ returns a lots of data. In GraphQL, you also need to define the structure of the data returned by the call to the API. The high-level structure of a result set is defined as follows:

query Analytics(...) {
  analytics(...) {
    grouppedAnalytics(key:"<key>") {
      analysis(timePeriodCode:"<timePeriodCode>") {...}
      grouppedAnalyticsTimePeriod {...}
      grouppedAnalytics { ... }
      grouppedAnalyticsByGroup(groupCode:"<groupCode>") { ... }
      indexedReturnData { ... }
    }
  }
}

The description of the structure is as follows:

Field

Parameters

Description

grouppedAnalytics

key (defined in the call parameters)

Accesses a specific analysis result set

analysis

timePeriodCode (defined in the call parameters)

Accesses a specific time period analysis

groupppedAnalyticsTimePeriod

-

Returns a list of all time period analyses

grouppedAnalytics

-

If includeChildren parameter was true, the grouped child levels are returned in this.

grouppedAnalyticsByGroup

groupCode

Returns a specific group. Requires that includeChildren parameter was true.

indexedReturnData

-

If includeData parameter was true, returns a list of the data time series per day.

An example call returning a time series of daily data grouped by security type and security:

query Analytics(...) {
  analytics(
    ...
    parameters: {
      ...
      paramsSet: [{
        key:"ALLOC"
        timePeriodCodes:["GIVEN"]
        grouppedByProperties: [TYPE,SECURITY]
        includeData:true
        includeChildren:true
        ...
      }]
        }) {
        
    grouppedAnalytics(key:"ALLOC") {
      topLevelTimeSeries:indexedReturnData {
        date
        marketValue
      }
      securityTypes:grouppedAnalytics {
        securityTypesTimeSeries:indexedReturnData {
          code
          date
          marketValue
        }
        positions:grouppedAnalytics {
          positionsTimeSeries:indexedReturnData {
            code
            date
            marketValue
          }
        }
      }
    }
  }
}