finol.evaluation_layer.MetricCalculator

class finol.evaluation_layer.MetricCalculator(load_dataset_output, train_model_output, mode='normal')

Class to calculate various evaluation metrics based on the loaded dataset and trained model.

Parameters:

• load_dataset_output (Dict) – Dictionary containing output from function load_dataset().

• train_model_output (Dict) – Dictionary containing output from function train_model().

Methods

calculate_annual_percentage_yield(...)	Annualized Percentage Yield (APY): Annualize the Final Cumulative Wealth based on the investment horizon \(n\) to facilitate comparison across different datasets.
calculate_average_turnover(daily_turnovers)	Average Turnover (ATO): Calculate the average proportion of portfolio vectors changed between periods, indicating rebalancing frequency.
calculate_final_cumulative_wealth(...)	Final Cumulative Wealth (FCW): Calculate the final cumulative wealth generated by the portfolio sequence \(\mathbf{b}_{1:n}\) at the end of the \(n\)-th trading periods.
calculate_maximum_drawdown(...)	Maximum DrawDown (MDD): Measure the maximum peak-to-trough decline of a portfolio over the investment horizon \(n\).
calculate_metric([portfolios, labels, runtime])	Calculate various evaluation metrics based on the provided portfolios, labels.
calculate_portfolios()	Calculate the portfolio sequence \(\mathbf{b}_{1:n}\).
calculate_runtime(runtime)	Running Time (RT): Measure the amount of time required to execute trades for an OLPS method.
calculate_sharpe_ratio(daily_returns, ...)	Sharpe Ratio (SR): Measure risk-adjusted return using the portfolio's excess return over risk-free rate per unit of volatility risk.
calculate_transaction_costs_wealth(...)	Transaction Costs-Adjusted Cumulative Wealth (TCW): Apply proportional transaction costs to the raw Cumulative Wealth equation based on rebalancing.
calculate_volatility_risk(daily_returns)	Volatility Risk (VR): Calculate the annualized standard deviation \(\sigma_n\) of daily portfolio returns, indicating return fluctuation risk.

calculate_annual_percentage_yield(num_trading_periods, final_cumulative_wealth)

Annualized Percentage Yield (APY): Annualize the Final Cumulative Wealth based on the investment horizon \(n\) to facilitate comparison across different datasets.

\[\mathrm{APY}=\sqrt[y]{\mathrm{FCW}}-1,\]

where \(y\) is the number of years in the investment period.

Parameters:

• num_trading_periods (float) – Number of trading periods \(n\).

• final_cumulative_wealth (float) – Final Cumulative Wealth.

Returns:

Annual Percentage Yield.

Return type:

float

calculate_average_turnover(daily_turnovers)

Average Turnover (ATO): Calculate the average proportion of portfolio vectors changed between periods, indicating rebalancing frequency.

\[\mathrm{ATO}=\frac{1}{2(n)} \sum_{t=1}^n\left\|\mathbf{b}_t-\hat{\mathbf{b}}_{t-1}\right\|_1,\]

where portfolio \(\hat{\mathbf{b}}_{t-1} = (\frac{b_{t-1, 1} x_{t-1, 1}}{\mathbf{b}_{t-1}^{\top} \mathbf{x}_{t-1}}, \ldots, \frac{b_{t-1, m} x_{t-1, m}}{\mathbf{b}_{t-1}^{\top} \mathbf{x}_{t-1}})\) is the portfolio vector at the end of \((t-1)\)-th period adjusted for asset returns. For simplicity, we set all elements of \(\hat{\mathbf{b}}_{0}\) to 0.

Parameters:

daily_turnovers – Daily turnover sequence.

Returns:

Average Turnover

Return type:

None

calculate_final_cumulative_wealth(portfolios, labels)

Final Cumulative Wealth (FCW): Calculate the final cumulative wealth generated by the portfolio sequence \(\mathbf{b}_{1:n}\) at the end of the \(n\)-th trading periods.

\[\mathrm{FCW}=S_0 \prod_{t=1}^n \mathbf{b}_t^{\top} \mathbf{x}_t=S_0 \prod_{t=1}^n \sum_{i=1}^m b_{t, i} x_{t, i},\]

where \(S_0\) is the initial cumulative wealth, \(\mathbf{b}_t\) is the portfolio vector and \(\mathbf{x}_t\) is the price relative vector in period \(t\).

Parameters:

• portfolios (ndarray) – Portfolio sequence \(\mathbf{b}_{1:n} \in \mathbb{R}^{n {\times} m}\).

• labels (ndarray) – Price relative sequence \(\mathbf{x}_{1:n} \in \mathbb{R}_{+}^{n {\times} m}\).

Returns:

Tuple containing the daily return, daily cumulative wealth, and final cumulative wealth.

Return type:

Tuple[ndarray, ndarray, float]

calculate_maximum_drawdown(daily_cumulative_wealth)

Maximum DrawDown (MDD): Measure the maximum peak-to-trough decline of a portfolio over the investment horizon \(n\).

\[\mathrm{MDD}=\max_{0\leq t\leq n}\left(\frac{\max_{0\leq k\leq t} S_k - S_t}{\max_{0\leq k\leq t} S_k}\right),\]

where \(S_t\) is the cumulative wealth at the end of the \(t\)-th trading period.

Parameters:

daily_cumulative_wealth – Daily Cumulative Wealth.

Returns:

Tuple containing the daily drawdown, daily maximum drawdown, and maximum drawdown.

Return type:

Tuple[ndarray, ndarray, float]

calculate_metric(portfolios=None, labels=None, runtime=None)

Calculate various evaluation metrics based on the provided portfolios, labels.

Parameters:

• portfolios – Portfolio sequence \(\mathbf{b}_{1:n}\).

• labels – Price relative sequence \(\mathbf{x}_{1:n}\).

• runtime – The runtime information. Required only when self.mode is ed (economic distillation).

Returns:

Dictionary containing calculated evaluation metrics.

Return type:

Dict

calculate_portfolios()

Calculate the portfolio sequence \(\mathbf{b}_{1:n}\).

Returns:

Tuple containing the portfolio sequence \(\mathbf{b}_{1:n}\), price relative sequence \(\mathbf{x}_{1:n}\), and other information.

Return type:

Tuple[ndarray, ndarray, float]

calculate_runtime(runtime)

Running Time (RT): Measure the amount of time required to execute trades for an OLPS method. In live markets, any delays in processing or slow computation times can result in missed opportunities or executions at less favorable prices.

Note

While it is typically assumed in OLPS problems that execution at the desired price is always possible.

Parameters:

runtime (float) – Running Time.

Returns:

Running Time.

Return type:

float

calculate_sharpe_ratio(daily_returns, annual_percentage_yield)

Sharpe Ratio (SR): Measure risk-adjusted return using the portfolio’s excess return over risk-free rate per unit of volatility risk.

\[\mathrm{SR}=\frac{\mathrm{APY}-R^f}{\sigma_n},\]

where \(R^f = 0.04\) is the annualized risk-free rate and \(\sigma_n\) denotes the annualized standard deviation of portfolio daily returns.

Parameters:

• daily_returns (ndarray) – Daily return sequence.

• annual_percentage_yield (float) – Annual Percentage Yield.

Returns:

Sharpe Ratio.

Return type:

float

calculate_transaction_costs_wealth(portfolios, labels)

Transaction Costs-Adjusted Cumulative Wealth (TCW): Apply proportional transaction costs to the raw Cumulative Wealth equation based on rebalancing.

\[\mathrm{TCW} = S_0 \prod_{t=1}^n\left[\left(\mathbf{b}_t^{\top} \mathbf{x}_t\right) \times\left(1-\frac{c}{2} \times \left\|\mathbf{b}_t-\hat{\mathbf{b}}_{t-1}\right\|_1\right)\right],\]

where \(S_0\) is the initial cumulative wealth, \(\mathbf{b}_t\) is the portfolio vector and \(\mathbf{x}_t\) is the price relative vector in period \(t\). \(c \in (0,1)\) is the transaction costs rate.

Parameters:

• portfolios – Portfolio sequence.

• labels – Price relative sequence.

Returns:

Tuple containing daily turnover and transaction costs-adjusted cumulative wealth.

Return type:

Tuple[ndarray, Series]

calculate_volatility_risk(daily_returns)

Volatility Risk (VR): Calculate the annualized standard deviation \(\sigma_n\) of daily portfolio returns, indicating return fluctuation risk.

Parameters:

daily_returns – Daily return sequence.

Returns:

Volatility Risk.

Return type:

float