Skip to content

Parameters

Securities


Example of long/short global stocks portfolio with user defined label (JSON):

[
  {
    "id": "0f82eb",
    "symbol": "GMEXICOB:XMEX",
    "quantity": 125000.0,
    "label": "AB"
  },
  {
    "id": "76ac8d",
    "symbol": "CNCO",
    "quantity": 150000.0,
    "label": "DL"
  },
  {
    "id": "47e7ba",
    "symbol": "SIE:XETR",
    "quantity": 10000.0,
    "label": "DL"
  },
  {
    "id": "86f551",
    "symbol": "BN:XPAR",
    "quantity": 4000.0,
    "label": "AB"
  },
  {
    "id": "1b9b11",
    "symbol": "BMW:XETR",
    "quantity": 2000.0,
    "label": "AB"
  },
  {
    "id": "a089b0",
    "symbol": "AAPL",
    "quantity": -1000.0,
    "label": "AB"
  },
  {
    "id": "bc1413",
    "symbol": "FB",
    "quantity": -2400.0,
    "label": "DL"
  }
]

The parameter securities is an array of objects representing each security in the portfolio. Each object in the array has the following attributes:

Attribute Description
id string REQUIRED A unique identifier (UID) for a security.
symbol string REQUIRED Security symbol: Please refer to our symbology.
quantity float REQUIRED Numbers of shares or contracts. Positive quantities are longs and negative are shorts. For fixed income securities, mutual funds, swaps, cash and margin the amounts are defined in the security's currency.
label string optional, default is "" (no aggregation label) Aggregation label defined by the user. It is used when aggregation is custom.
cost_price float optional, default is null Unit price of the security.
market_price float optional, default is null Current market price in local currency.
currency string optional, default is null 3-letter ISO 4217 code for currency. The currency of the security. To see all supported currencies click here.
fx_rate float optional, default is null The price of the domestic currency stated in terms of another currency.
multiplier float optional, default is null The securitie's multiplier.
unrealized_pl float optional, default is null The current profit or loss on an open security.
unrealized_pl_in_base float optional, default is null The current profit or loss on an open security based on the portfolio base currency.
isin string optional, default is null A 12-digit alphanumeric code that uniquely identifies a specific security. The numbers are allocated by a country's respective national numbering agency (NNA).
status string optional, default is OK It can be "OK", "ERROR" or "UNHEALTHY".
exchange string optional, default is null The stock exchange where the security is traded.
name string optional, default is null The security full name in the market.
extra_data object optional, default is null An object sent by the user in order to give more details to the API.

Maximum securities length:

  • 250 securities (with or without a supplied nlv).
  • 3000 securities (nlv is not optional and needs to be supplied).

Magnitude


The parameter magnitude is an instantaneous shock as a decimal number: -10% = -0.10.

Certain rates/spreads can also be shocked and the magnitude of the shock is an absolute widening or tightening of the rate/spread. For example:

Shock Magnitude Current level New level
IND:SPX -1% 2821 2792
IND:LIBOR3M -1% 1.77 0.77

In the table above, the shock in SPX is a percent change, whereas the libor shock is an absolute shift.

For a list of rates and spreads that are shocked in absolute terms please click here.

Confidence


The parameter confidence can be one of: 1_sigma, 2_sigma, 3_sigma, 85%, 90%, 95%, 97%, 97.5% or 99%. Any other value returns 400. For example: 1_sigma represents the left tail outside a one-sigma move from the mean of the profit and loss distribution (PL). It represents roughly the worst/best 16% (=68%+16%) forecasted outcomes. Conversely, 95% explicitly represents the worst/best 5% forecasted outcomes.

The table below clarifies:

Confidence Probability
1_sigma One sigma dispersion around the mean (approx. 68.27%) + one tail Tail measure* ≅ 15.87%
2_sigma Two sigma dispersion around the mean (approx. 95.45%) + one tail Tail measure* ≅ 2.28%
3_sigma The API calculates it at 99%, not at the 99.87% of a normal three-sigma tail. Tail measure* = 1%
85% Explicit 85% Tail measure* = 15%
90% Explicit 90% Tail measure* = 10%
95% Explicit 95% Tail measure* = 5%
97% Explicit 97% Tail measure* = 3%
97.5% Explicit 97.5% Tail measure* = 2.5%
99% Explicit 99% Tail measure* = 1%

* Tail measure = (1-confidence)

Projection model


Example of projection model (JSON):

{
  "name": "US equity indexes",
  "tickers": ["IND:SPX", "IND:NDX"],
  "labels": ["S&P 500", "Nasdaq 100"]
}

The parameter projection_model is an object that sets the factors of the top-down factor model and a label for each factor. Use it instead of projection when you want to name the factors. When you send projection_model, the API ignores projection.

The object has the following attributes:

Attribute Description
name string REQUIRED The name of the projection model.
tickers array REQUIRED The symbols of the factors, as strings. From 1 to 15 symbols.
labels array REQUIRED A label for each symbol in tickers, in the same order, as strings.

If an attribute is missing or has a value of the wrong type, the API returns 400 with the message Invalid Argument: projection_model: invalid projection model.

Posterior model


The parameter posterior_model sets the method that the engine uses to calculate the posterior probabilities of the simulated scenarios, so that they agree with a stress scenario. The White Paper explains the prior and the posterior probabilities.

It accepts these values. They are case sensitive, and any other value returns 400.

Value How the engine weights the simulated scenarios
entropy The default. The engine solves for the probabilities that are closest to the prior (minimum relative entropy) and match the shock.
kernel A Gaussian kernel centered on the shock. A scenario gets more probability when its move is closer to the shock.
crisp The scenarios whose move falls in a narrow band around the shock get 99% of the probability. All other scenarios share 1%.

Calculation model


The parameter model string selects the calculation engine:

Value Description
v1 The default engine.
v2 The new calculation engine.

The API does not validate the value: any value other than v2 runs the v1 engine. Only these calculations read model: Parametric Risk Attribution, Historical Risk Attribution, Tracking Error, Volatility and Correlation Matrix, Parametric Stress Test, Exposure, Sensitivity, Beta, Properties and Days to Unwind. The other calculations ignore it.

Use Drift


By default our simulations are zero-centered. This flag specifies that the dispersion of simulations should be around the average of the historical risk factors instead.

In the calculation of the averages, volatility_half_life and correlation_half_life are taken into account.

Forecasts


Example of forecast (JSON):

[
  {
    "symbol": "NFLX",
    "years": 1.0,
    "targets": [160, 260, 400, 480],
    "probabilities": [0.55, 0.15, 0.15, 0.15]
  },
  {
    "symbol": "SPY",
    "years": 0.5,
    "targets": [270, 260, 200],
    "probabilities": [0.5, 0.4, 0.1]
  }
]

User-supplied forecasts can represent outcomes that are difficult to be captured by the covariance matrix, for example: a takeover situation, a pharmaceutical company clearing a drug trial or even a large correction not captured with the historical data.

The parameter forecasts is an array of objects representing the price forecast for a security in the portfolio. Each object in the array has the following attributes:

Attribute Description
years float REQUIRED Timeframe for the forecast to materialize in years.
targets array REQUIRED Target prices at a horizon represented by attribute years. Can contain any number of targets.
probabilities array REQUIRED Probabilities associated to each element inside the attribute targets.

The arrays targets and probabilities have to be of same size and probabilities need to sum to 1.0.

Volatility Surface


Example of volatility surface (JSON):

[
  {
    "symbol": "IBM",
    "time_to_expiration": [0.12, 0.25],
    "moneyness": [0.97, 1, 1.03, 1.05],
    "volatilities": [
      [0.36, 0.16, 0.33, 0.26],
      [0.19, 0.2, 0.17, 0.16]
    ]
  }
]

Surfaces are parameterized in years to expiration and moneyness. When supplied, the surface is used to price any options on the underlying. When omitted, an implied volatility is calculated with Black and Scholes.

The parameter volatility_surface is an array of objects representing the implied volatilities for underlying securities in the portfolio. Each object in the array has the following attributes:

Attribute Description
time_to_expiration array REQUIRED Various times to expiration (as a fraction of a year).
moneyness array REQUIRED Various moneyness.
volatilities 2d array REQUIRED Implied volatilities, with times_to_expiration rows and moneyness columns.

Filter Expression


Example using logical operator 'and'. Retrieve identifiers for positions that are long and also denominated in a currency different than the base currency of the portfolio:

"exposure('long') and currency('foreign securities')"

Example using logical operator 'or'. Retrieve any shorts or illiquid positions:

"exposure('short') or liquidity('>300%')"

Example using logical operator 'not'. Retrieve all positions that are not long options:

"not(type('equity option long delta'))"

Example using logical operators combined:

"currency('foreign securities') and (not(exposure('short') or liquidity('>300%')))"

Filters are powerful constructs to return the unique identifiers of certain positions in the portfolio, satisfying a specific criteria. When used, they isolate the behavior of a unique group, compared to the whole. For example: how illiquid securities might react to an oil shock.

The parameter filter supports the following expressions:

Filter Function Description
currency Extracts the unique identifiers according to different currency related buckets: 'foreign securities', 'domestic securities'.
exposure Extracts the unique identifiers that represent long exposures (including long calls and short puts) and short exposures (including long puts and short calls): 'long', 'short'.
type Extracts the identifiers of securities from a specific type: 'equity option long delta', 'equity option short delta', 'future option long delta', 'future option short delta', 'foreign equity long', 'foreign equity short', 'us equity long', 'us equity short', 'fx forward', 'fx option long delta', 'fx option short delta'.
liquidity Extracts the identifiers of securities satisfying certain liquidity criteria: '0-5%', '5-25%', '25-50%', '50-100%', '100-300%', '>300%'.

Liquidity above is expressed as the proportion of the 20-day average trading volume required to unwind a position in full, taking into account a 20% participation rate. Thus, ">300%" means that will take at least 3 days to unwind the position(s) in full.

Simple filters above can be combined into complex filters using logical expressions, namely: or, and and not. Please see various examples in the right panel.

If no security matches the filter, the calculation still runs on the whole portfolio, but the per-security results are empty.

Sampling Combinations


Sampling Horizon Explanation
1 1 One-day ahead forecasts with daily sampling
5 5 Week-ahead forecasts with weekly (non-overlapping) sampling
1 5 Week-ahead forecasts with daily (overlapping) sampling