bbstrader 0.2.4__py3-none-any.whl

bbstrader/models/optimization.py

@@ -0,0 +1,182 @@
+import warnings
+
+from pypfopt import expected_returns, risk_models
+from pypfopt.efficient_frontier import EfficientFrontier
+from pypfopt.hierarchical_portfolio import HRPOpt
+
+__all__ = [
+    "markowitz_weights",
+    "hierarchical_risk_parity",
+    "equal_weighted",
+    "optimized_weights",
+]
+
+
+def markowitz_weights(prices=None, rfr=0.0, freq=252):
+    """
+    Calculates optimal portfolio weights using Markowitz's mean-variance optimization (Max Sharpe Ratio) with multiple solvers.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame, optional
+        Price data for assets, where rows represent time periods and columns represent assets.
+    freq : int, optional
+        Frequency of the data, such as 252 for daily returns in a year (default is 252).
+
+    Returns
+    -------
+    dict
+        Dictionary containing the optimal asset weights for maximizing the Sharpe ratio, normalized to sum to 1.
+
+    Notes
+    -----
+    This function attempts to maximize the Sharpe ratio by iterating through various solvers ('SCS', 'ECOS', 'OSQP')
+    from the PyPortfolioOpt library. If a solver fails, it proceeds to the next one. If none succeed, an error message
+    is printed for each solver that fails.
+
+    This function is useful for portfolio with a small number of assets, as it may not scale well for large portfolios.
+
+    Raises
+    ------
+    Exception
+        If all solvers fail, each will print an exception error message during runtime.
+    """
+    returns = expected_returns.mean_historical_return(prices, frequency=freq)
+    cov = risk_models.sample_cov(prices, frequency=freq)
+
+    # Try different solvers to maximize Sharpe ratio
+    for solver in ["SCS", "ECOS", "OSQP"]:
+        ef = EfficientFrontier(
+            expected_returns=returns,
+            cov_matrix=cov,
+            weight_bounds=(0, 1),
+            solver=solver,
+        )
+        try:
+            ef.max_sharpe(risk_free_rate=rfr)
+            return ef.clean_weights()
+        except Exception as e:
+            print(f"Solver {solver} failed with error: {e}")
+
+
+def hierarchical_risk_parity(prices=None, returns=None, freq=252):
+    """
+    Computes asset weights using Hierarchical Risk Parity (HRP) for risk-averse portfolio allocation.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame, optional
+        Price data for assets; if provided, daily returns will be calculated.
+    returns : pd.DataFrame, optional
+        Daily returns for assets. One of `prices` or `returns` must be provided.
+    freq : int, optional
+        Number of days to consider in calculating portfolio weights (default is 252).
+
+    Returns
+    -------
+    dict
+        Optimized asset weights using the HRP method, with asset weights summing to 1.
+
+    Raises
+    ------
+    ValueError
+        If neither `prices` nor `returns` are provided.
+
+    Notes
+    -----
+    Hierarchical Risk Parity is particularly useful for portfolios with a large number of assets,
+    as it mitigates issues of multicollinearity and estimation errors in covariance matrices by
+    using hierarchical clustering.
+    """
+    warnings.filterwarnings("ignore")
+    if returns is None and prices is None:
+        raise ValueError("Either prices or returns must be provided")
+    if returns is None:
+        returns = prices.pct_change().dropna(how="all")
+    # Remove duplicate columns and index
+    returns = returns.loc[:, ~returns.columns.duplicated()]
+    returns = returns.loc[~returns.index.duplicated(keep="first")]
+    hrp = HRPOpt(returns=returns.iloc[-freq:])
+    return hrp.optimize()
+
+
+def equal_weighted(prices=None, returns=None, round_digits=5):
+    """
+    Generates an equal-weighted portfolio by assigning an equal proportion to each asset.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame, optional
+        Price data for assets, where each column represents an asset.
+    returns : pd.DataFrame, optional
+        Return data for assets. One of `prices` or `returns` must be provided.
+    round_digits : int, optional
+        Number of decimal places to round each weight to (default is 5).
+
+    Returns
+    -------
+    dict
+        Dictionary with equal weights assigned to each asset, summing to 1.
+
+    Raises
+    ------
+    ValueError
+        If neither `prices` nor `returns` are provided.
+
+    Notes
+    -----
+    Equal weighting is a simple allocation method that assumes equal importance across all assets,
+    useful as a baseline model and when no strong views exist on asset return expectations or risk.
+    """
+
+    if returns is None and prices is None:
+        raise ValueError("Either prices or returns must be provided")
+    if returns is None:
+        n = len(prices.columns)
+        columns = prices.columns
+    else:
+        n = len(returns.columns)
+        columns = returns.columns
+    return {col: round(1 / n, round_digits) for col in columns}
+
+
+def optimized_weights(prices=None, returns=None, rfr=0.0, freq=252, method="equal"):
+    """
+    Selects an optimization method to calculate portfolio weights based on user preference.
+
+    Parameters
+    ----------
+    prices : pd.DataFrame, optional
+        Price data for assets, required for certain methods.
+    returns : pd.DataFrame, optional
+        Returns data for assets, an alternative input for certain methods.
+    freq : int, optional
+        Number of days for calculating portfolio weights, such as 252 for a year's worth of daily returns (default is 252).
+    method : str, optional
+        Optimization method to use ('markowitz', 'hrp', or 'equal') (default is 'markowitz').
+
+    Returns
+    -------
+    dict
+        Dictionary containing optimized asset weights based on the chosen method.
+
+    Raises
+    ------
+    ValueError
+        If an unknown optimization method is specified.
+
+    Notes
+    -----
+    This function integrates different optimization methods:
+    - 'markowitz': mean-variance optimization with max Sharpe ratio
+    - 'hrp': Hierarchical Risk Parity, for risk-based clustering of assets
+    - 'equal': Equal weighting across all assets
+    """
+    if method == "markowitz":
+        return markowitz_weights(prices=prices, rfr=rfr, freq=freq)
+    elif method == "hrp":
+        return hierarchical_risk_parity(prices=prices, returns=returns, freq=freq)
+    elif method == "equal":
+        return equal_weighted(prices=prices, returns=returns)
+    else:
+        raise ValueError(f"Unknown method: {method}")

bbstrader/models/portfolio.py

@@ -0,0 +1,223 @@
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import scale
+
+from bbstrader.models.optimization import (
+    equal_weighted,
+    hierarchical_risk_parity,
+    markowitz_weights,
+)
+
+__all__ = ["EigenPortfolios"]
+
+
+class EigenPortfolios(object):
+    """
+    The `EigenPortfolios` class applies Principal Component Analysis (PCA) to a covariance matrix of normalized asset returns
+    to derive portfolios (eigenportfolios) that capture distinct risk factors in the asset returns. Each eigenportfolio
+    represents a principal component of the return covariance matrix, ordered by the magnitude of its eigenvalue. These
+    portfolios capture most of the variance in asset returns and are mutually uncorrelated.
+
+    Notes
+    -----
+    The implementation is inspired by the book "Machine Learning for Algorithmic Trading" by Stefan Jansen.
+
+    References
+    ----------
+    Stefan Jansen (2020). Machine Learning for Algorithmic Trading - Second Edition.
+    chapter 13, Data-Driven Risk Factors and Asset Allocation with Unsupervised Learning.
+
+    """
+
+    def __init__(self):
+        self.returns = None
+        self.n_portfolios = None
+        self._portfolios = None
+        self._fit_called = False
+
+    def get_portfolios(self) -> pd.DataFrame:
+        """
+        Returns the computed eigenportfolios (weights of assets in each portfolio).
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame containing eigenportfolio weights for each asset.
+
+        Raises
+        ------
+        ValueError
+            If `fit()` has not been called before retrieving portfolios.
+        """
+        if not self._fit_called:
+            raise ValueError("fit() must be called first")
+        return self._portfolios
+
+    def fit(self, returns: pd.DataFrame, n_portfolios: int = 4) -> pd.DataFrame:
+        """
+        Computes the eigenportfolios based on PCA of the asset returns' covariance matrix.
+
+        Parameters
+        ----------
+        returns : pd.DataFrame
+            Historical returns of assets to be used for PCA.
+        n_portfolios : int, optional
+            Number of eigenportfolios to compute (default is 4).
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame containing normalized weights for each eigenportfolio.
+
+        Notes
+        -----
+        This method performs winsorization and normalization on returns to reduce the impact of outliers
+        and achieve zero mean and unit variance. It uses the first `n_portfolios` principal components
+        as portfolio weights.
+        """
+        # Winsorize and normalize the returns
+        normed_returns = scale(
+            returns.clip(
+                lower=returns.quantile(q=0.025), upper=returns.quantile(q=0.975), axis=1
+            ).apply(lambda x: x.sub(x.mean()).div(x.std()))
+        )
+        returns = returns.dropna(thresh=int(normed_returns.shape[0] * 0.95), axis=1)
+        returns = returns.dropna(thresh=int(normed_returns.shape[1] * 0.95))
+
+        cov = returns.cov()
+        cov.columns = cov.columns.astype(str)
+        pca = PCA()
+        pca.fit(cov)
+
+        top_portfolios = pd.DataFrame(
+            pca.components_[:n_portfolios], columns=cov.columns
+        )
+        eigen_portfolios = top_portfolios.div(top_portfolios.sum(axis=1), axis=0)
+        eigen_portfolios.index = [f"Portfolio {i}" for i in range(1, n_portfolios + 1)]
+        self._portfolios = eigen_portfolios
+        self.returns = returns
+        self.n_portfolios = n_portfolios
+        self._fit_called = True
+
+    def plot_weights(self):
+        """
+        Plots the weights of each asset in each eigenportfolio as bar charts.
+
+        Notes
+        -----
+        Each subplot represents one eigenportfolio, showing the contribution of each asset.
+        """
+        eigen_portfolios = self.get_portfolios()
+        n_cols = 2
+        n_rows = (self.n_portfolios + 1) // n_cols
+        figsize = (n_cols * 10, n_rows * 5)
+        axes = eigen_portfolios.T.plot.bar(
+            subplots=True, layout=(n_rows, n_cols), figsize=figsize, legend=False
+        )
+        for ax in axes.flatten():
+            ax.set_ylabel("Portfolio Weight")
+            ax.set_xlabel("")
+
+        sns.despine()
+        plt.tight_layout()
+        plt.show()
+
+    def plot_performance(self):
+        """
+        Plots the cumulative returns of each eigenportfolio over time.
+
+        Notes
+        -----
+        This method calculates the historical cumulative performance of each eigenportfolio
+        by weighting asset returns according to eigenportfolio weights.
+        """
+        eigen_portfolios = self.get_portfolios()
+        returns = self.returns.copy()
+
+        n_cols = 2
+        n_rows = (self.n_portfolios + 1 + n_cols - 1) // n_cols
+        figsize = (n_cols * 10, n_rows * 5)
+        fig, axes = plt.subplots(
+            nrows=n_rows, ncols=n_cols, figsize=figsize, sharex=True
+        )
+        axes = axes.flatten()
+        returns.mean(1).add(1).cumprod().sub(1).plot(title="The Market", ax=axes[0])
+
+        for i in range(self.n_portfolios):
+            rc = returns.mul(eigen_portfolios.iloc[i]).sum(1).add(1).cumprod().sub(1)
+            rc.plot(title=f"Portfolio {i+1}", ax=axes[i + 1], lw=1, rot=0)
+
+        for j in range(self.n_portfolios + 1, len(axes)):
+            fig.delaxes(axes[j])
+
+        for i in range(self.n_portfolios + 1):
+            axes[i].set_xlabel("")
+
+        sns.despine()
+        fig.tight_layout()
+        plt.show()
+
+    def optimize(
+        self,
+        portfolio: int = 1,
+        optimizer: str = "hrp",
+        prices=None,
+        freq=252,
+        plot=True,
+    ):
+        """
+        Optimizes the chosen eigenportfolio based on a specified optimization method.
+
+        Parameters
+        ----------
+        portfolio : int, optional
+            Index of the eigenportfolio to optimize (default is 1).
+        optimizer : str, optional
+            Optimization method: 'markowitz', 'hrp' (Hierarchical Risk Parity), or 'equal' (default is 'hrp').
+        prices : pd.DataFrame, optional
+            Asset prices used for Markowitz optimization (required if optimizer is 'markowitz').
+        freq : int, optional
+            Frequency of returns (e.g., 252 for daily returns).
+        plot : bool, optional
+            Whether to plot the performance of the optimized portfolio (default is True).
+
+        Returns
+        -------
+        dict
+            Dictionary of optimized asset weights.
+
+        Raises
+        ------
+        ValueError
+            If an unknown optimizer is specified, or if prices are not provided when using Markowitz optimization.
+
+        Notes
+        -----
+        The optimization method varies based on risk-return assumptions, with options for traditional Markowitz optimization,
+        Hierarchical Risk Parity, or equal weighting.
+        """
+        portfolio = self.get_portfolios().iloc[portfolio - 1]
+        returns = self.returns.loc[:, portfolio.index]
+        returns = returns.loc[:, ~returns.columns.duplicated()]
+        returns = returns.loc[~returns.index.duplicated(keep="first")]
+        if optimizer == "markowitz":
+            if prices is None:
+                raise ValueError("prices must be provided for markowitz optimization")
+            prices = prices.loc[:, returns.columns]
+            weights = markowitz_weights(prices=prices, freq=freq)
+        elif optimizer == "hrp":
+            weights = hierarchical_risk_parity(returns=returns, freq=freq)
+        elif optimizer == "equal":
+            weights = equal_weighted(returns=returns)
+        else:
+            raise ValueError(f"Unknown optimizer: {optimizer}")
+        if plot:
+            # plot the optimized potfolio performance
+            returns = returns.filter(weights.keys())
+            rc = returns.mul(weights).sum(1).add(1).cumprod().sub(1)
+            rc.plot(title=f"Optimized {portfolio.name}", lw=1, rot=0)
+            sns.despine()
+            plt.show()
+        return weights