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` file	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 utilized when `aggregation` is set to `"aggregation_label"`.
`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: 1sigma, 2sigma, 3sigma, 85%, 90% or 95%. For example: 1sigma represents the left tail outside a one-sigma move from the mean of the profit and loss distribution (PL). It would represent 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
`1sigma`	One sigma dispersion around the mean (approx. 68.27%) + one tail Tail measure* ≅ `15.86%`
`2sigma`	Two sigma dispersion around the mean (approx. 95.45%) + one tail Tail measure* ≅ `2.27%`
`3sigma`	Three sigma dispersion around the mean (approx. 99.73%) + one tail Tail measure* ≅ `0.13%`
`85%`	Explicit 85% Tail measure* = `15%`
`90%`	Explicit 90% Tail measure* = `10%`
`95%`	Explicit 95% Tail measure* = `5%`
`97%`	Explicit 95% Tail measure* = `3%`
`99%`	Explicit 95% Tail measure* = `1%`

* Tail measure = (1-confidence)

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` file	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.

Filters that do not satisfy all the conditions return an empty dictionary, therefore the whole portfolio is used.

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