KPI functions

If you have created KPI mappings in the Exabel app, you can retrieve the proxy time series and the predictions from these mappings using DSL signals referring to the KPI mapping group. You can also retrieve predictions from the auto-models and custom models.

kpi_proxy(kpi_group: int, *, forecast: bool = True, resample: bool = True)

Retrieve the proxy time series from a KPI mapping group.

The company can be used as the evaluation entity if there is only one mapping for that company within the given KPI mapping group. If there are several FactSet segments or Visible Alpha line items that have been mapped for the company, then the KPI must be specified by using the segment or the line item as the evaluation entity.

Every night, the Exabel system calculates the forecasted and resampled version of the proxy time series as part of updating the KPI mapping results. This time series is then persisted. When this DSL signal is used with forecast=True and resample=True (the default), it is this persisted version of the proxy which is retrieved, whereas if either forecast or resample is set to False, the underlying proxy signal is evaluated on the fly (and optionally either forecasted or resampled).

Parameters:

kpi_group – the id of the KPI mapping group
forecast – whether to forecast the proxy time series
resample – whether to resample the proxy time series to the fiscal calendar of the KPI

Examples:

Get the forecasted and resampled version of a proxy time series from the KPI mapping group with numeric ID 123:

kpi_proxy(123)

Get the forecasted proxy time series, without resampling:

kpi_proxy(123, resample=False)

Get the raw proxy time series, without forecasting or resampling:

kpi_proxy(123, forecast=False, resample=False)

kpi_predictions(*, kpi_group: int, model: int, kpi: str, kpi_value: str | int, freq: str, series: str, run: int, relative_days: int)

Retrieve the KPI predictions from a model.

The source of the predictions can be specified in one of three manners:

For each KPI mapping, there is a model which produces predictions for the KPI, which only uses the proxy time series as input. To retrieve these predictions, specify the KPI mapping group with the kpi_group argument.

For custom models, the predictions can be retrieved by specifying the model argument. For these models, when retrieving backtests, the run number can also be specified with the run argument.

For Exabel models, the predictions can be retrieved by specifying the kpi along with a kpi_value. For these models, you can also specify a freq, since there may be multiple Exabel models with different frequencies.

The company must be used as the evaluation entity. The signal only works if there is exactly one KPI result belonging to the given company.

Parameters:

kpi_group – The id of the KPI mapping group
model – The id of the prediction model
kpi – The KPI type. Either fs (FactSet) or va (Visible Alpha).
kpi_value – The KPI line item. If kpi is a fs, this must be a string. If kpi is va, it can be a string or an integer.
freq – Optionally, the frequency of the Exabel model. If provided, the Exabel model with that frequency is used, if it exists. If no frequency is provided, one of the available Exabel models is used, if any. If there are multiple Exabel models, the one with the company’s reporting frequency is used if it exists, and otherwise the Exabel model with a sub-annual frequency is preferred to the one with annual frequency.
series – Either backtests, predictions or combined. Defaults to combined, which combines the backtests and the live predictions into one time series.
run – The run number to retrieve backtests from. Can only be used with the model argument, and with series being either “backtests” or “combined”.
relative_days – Optionally, the number of days the “known time” is relative to the date of the data point. For example, with relative_days=7, for each data point you will get the prediction as they were calculated one week after the end of each fiscal period. A negative value will give you known times prior to the end of the fiscal periods.

Examples:

Get the combined predictions from the KPI mapping group with numeric ID 123:

kpi_predictions(kpi_group=123)

Get the combined predictions from the model with numeric ID 123:

kpi_predictions(model=123)

Get the live predictions (without backtests) from the model with numeric ID 123:

kpi_predictions(model=123, series="predictions")

Get the backtests from the model with numeric ID 123:

kpi_predictions(model=123, series="backtests")

Get the predictions of the Exabel model for FactSet sales:

kpi_predictions(kpi='fs', kpi_value='SALES')

Get the predictions of the Exabel model for Visible Alpha total revenue:

kpi_predictions(kpi='va', kpi_value=190)

kpi_model_revisions(*, kpi_group: int, model: int, kpi: str, kpi_value: str | int, freq: str, period: str, series: str, values: str | list[str], interval_width: float, error_metric: str, num_periods: int, min_periods: int)

Retrieve the revisions of KPI predictions for a given fiscal period.

The source of the revisions can be specified in one of three manners:

For each KPI mapping, there is a model which produces predictions for the KPI, which only uses the proxy time series as input. To retrieve the revisions for these predictions, specify the KPI mapping group with the kpi_group argument.

For custom models, the revisions can be retrieved by specifying the model argument.

For Exabel models, the revisions can be retrieved by specifying the kpi along with a kpi_value. For these models, you can also specify a freq, since there may be multiple Exabel models with different frequencies.

The company must be used as the evaluation entity. The signal only works if there is exactly one KPI result belonging to the given company.

Parameters:

kpi_group – the id of the KPI mapping group
model – the id of the prediction model
period – a fiscal period, for example, 1Q-2025, FQ1 or RQ1, or by specifying the last date in the period, for example 2025-03-31.
kpi – The KPI type. Either fs (FactSet) or va (Visible Alpha).
kpi_value – The KPI line item. If kpi is a fs, this must be a string. If kpi is va, it can be a string or an integer.
freq – Optionally, the frequency of the Exabel model. If provided, the Exabel model with that frequency is used, if it exists. If no frequency is provided, one of the available Exabel models is used, if any. If there are multiple Exabel models, the one with the company’s reporting frequency is used if it exists, and otherwise the Exabel model with a sub-annual frequency is preferred to the one with annual frequency.
series – the kind of time series to return; the options are predictions, backtests and combined. In the case of combined, predictions are retrieved first, and if they are not present, the backtests are retrieved. The default is combined.
values – the time series to return; the options are prediction (the predicted values), lower (the lower confidence band), upper (the upper confidence band), errors (the historical errors). The default value is usually prediction, but if the interval_width argument is provided, the default value is ['prediction', 'lower', 'upper']
interval_width – a number between 0.0 and 1.0 denoting the width of the confidence interval; the default value is 0.95
error_metric – how the errors are calculated; the options are MAPE and MAE. The default is MAPE.
num_periods – the number of fiscal periods to use in order to calculate the errors and the confidence interval. The default is 8.
min_periods – the minimum number of fiscal periods with data required in order for the errors and confidence interval to be calculated. The default is 4. (If it is set to higher than num_periods, then num_periods is used.)

Examples:

Get the revisions for the prediction of the 2023-09-30 KPI value from the KPI mapping group with numeric ID 123:

kpi_model_revisions(kpi_group=123, period="2023-09-30")

Get the revisions for the prediction of the 3Q-2021 KPI value from the model with numeric ID 123:

kpi_model_revisions(model=123, period="3Q-2021")