Benchmarks are commonly used by portfolio managers to gauge the portfolio's active performance, risk, and/or exposures against an index (e.g. discover how much a portfolio outperforms the S&P 500).

Requesting Benchmarks

Use the query below to find out the names and IDs of the benchmarks available in your account:

query {
  model(id:"xxxxx-xx"){
    benchmarks {
      id
      name
    }
  }
}

You should see a response similar to the following:

{
  "data": {
    "model": {
      "benchmarks": [
        {
          "id": "SP500",
          "name": "S&P 500"
        },
        {
          "id": "Russell3000",
          "name": "Russell 3000"
        },
...
    ]
  }
}

You can use these results for locating the appropriate benchmark ID to be used in later requests.

Benchmarks As "Base" Inputs

Benchmarks can be referenced in the API by passing them in as base position set inputs (e.g. when using the optimization or simulation end points).

The base field requires a JSON structure in the following format:

[{
    "id": "SP500",
    "type": "BENCHMARK"
}]

An array is used in order to provide for the flexibility of passing in multiple benchmarks with various weights. For example, in the following scenario we create a benchmark that is 70% SP500 and 30% Russell3000:

[{
    "id": "SP500",
    "type": "BENCHMARK",
    "weight": 70
}, {
    "id": "Russell3000",
    "type": "BENCHMARK",
    "weight": 30
}]

Using Benchmarks

Now we'll look at how to pass the benchmark input into a query.

The following query will provide us with the performance difference between the existing portfolio and the benchmark, from 2017-06-01 to 2017-06-02. Using the Simulation end point, we can pass in the portfolio as a position set input and the benchmark JSON from above as a base* (note: to learn more about obtaining portfolio IDs from your account to be referenced as a position set, please see the articles on Requesting Portfolios and Using Position Sets).

*The base input can be used to compare to any other positionSet, including another portfolio or any benchmark. In all cases, the returned values can be understood as the difference of geometric sums.

Query

query(
  $modelId: String!,
  $portfolio: PositionSetInput!,
  $benchmark: [PositionSetInput!],
  $fromDate: Date!,
  $toDate: Date!
) {
  model(id: $modelId) {
    simulation(
      positionSet: $portfolio,
      base: $benchmark,
      from: $fromDate, to: $toDate
    ) {
      performance {
        date
        percentReturnCumulative {
          total
          attribution {
            summary {
              factors
              specific
            }
            factors {
              name
              value
            }
          }
        }
      }
    }
  }
}

Variables

{
  "modelId": "xxxxx-xx",
  "portfolio": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "PORTFOLIO"
  },
  "benchmark": [{
    "id": "SP500",
    "type": "BENCHMARK",
    "weight": 70
  }, {
    "id": "Russell3000",
    "type": "BENCHMARK",
    "weight": 30
  }],
  "fromDate": "2017-06-01",
  "toDate": "2017-06-02"
}

We can also pass in a benchmark as part of an optimization, in order to track an objective against the benchmark.

In the following example, we are requesting optimizations on 2017-06-01 and 2017-06-02, with our objective set to minimize total risk while providing our composite benchmark of 70% S&P500 and 30% Russell 1000. This optimization will target a portfolio that minimizes total active risk relative to the provided benchmark, commonly known as “minimizing tracking error against the benchmark”:

Query

query(
  $modelId: String!,
  $portfolio: PositionSetInput!,
  $objective: [OptimizationObjective]!,
  $benchmark: [PositionSetInput]!,
  $onDate: [Date]!
) {
  model(id: $modelId) {
    optimization(
      positionSet: $portfolio,
      objective: $objective,
      constraints: {},
      base: $benchmark,
      on: $onDate
    ) {
      positionsDelta {
        date
        equities {
          id {
            ticker
            mic
          }
          economicExposure
        }
      }
    }
  }
}

Variables

{
  "modelId": "xxxxx-xx",
  "portfolio": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "PORTFOLIO"
  },
  "objective": {
    "minimizeTotalRisk": true
  },
  "benchmark": [{
    "id":"SP500",
    "type":"BENCHMARK",
    "weight": 70
  }, {
    "id":"Russell3000",
    "type":"BENCHMARK",
    "weight": 30
  }],
  "onDate": [
    "2017-06-01"
  ]
}