Skip to main content

Security Metrics

Security metrics are return and risk indicators calculated for an isolated security, without depending on a position within a portfolio. In the API reference, they are grouped under Security KPIs. With them, you can analyze how a security has behaved over time even before adding it to a portfolio, or compare securities with each other.

GorilaCORE currently offers four metrics per security: return, measured by the Time-Weighted Return (TWR), drawdown, volatility and the Sharpe ratio.

How the security's return is calculated​

Gorila uses the same TWR methodology applied to portfolios. The calculation simulates a single purchase of the security, at market price, on the period's start date, and lets the position evolve only with the price variation and the security's own corporate actions and other events (Security Events). Since there are no contributions or redemptions, the result reflects exclusively the security's return (total return concept).

Some important behaviors:

  • First available price: if the security has no quote on the requested start date, the series begins at the first available price. There is no interpolation nor retroactive pricing.
  • Ticker change: when a security changes its ticker, the histories of the two securities are treated separately. The source security's series ends on the event date, and the target security's return is calculated from then on. The same applies when a security stops being traded, for example due to maturity.
  • Offshore securities: the return is calculated in BRL, following the platform's current methodology.

Drawdown​

Drawdown measures the percentage drop in the security's value relative to its most recent peak. While the return shows how much the security yielded, the drawdown shows the path to get there: the depth of the losses an investor would have faced throughout the period. That is why it is widely used to compare securities with similar returns but different risk profiles.

Unlike the return, the security's drawdown does not start on the period's start date: it considers the security's entire price history, from the first available price. Therefore, the reference peak may be earlier than startDate, which only filters the returned dates. See more details in Drawdown.

Return basis: gross or gross-up​

The return and the drawdown let you choose the return basis through the type parameter:

  • GROSS (default): uses the security's gross returns.
  • GROSS_UP: adjusts tax-exempt income upward (gross-up), making the security comparable with taxed securities.

Note that, in the portfolio and economic group TWR endpoints, the default is GROSS_UP. To compare a security's return with a portfolio's, use the same return basis in both queries.

Volatility and Sharpe Ratio​

A security's volatility and Sharpe ratio follow the same methodology applied to portfolios: annualized values, calculated over the security's daily returns, with the calculation window defined by the calculateWindow parameter. To understand how these indicators are calculated and how to combine the window with the frequency, see the Volatility and Sharpe Ratio documentation.

Where to access​

In GorilaCORE, you can query:

To compare a security's return with a reference index, combine the security's TWR series with the series of a Benchmark.