bbstrader 0.1.94__py3-none-any.whl → 0.2.1__py3-none-any.whl

bbstrader/models/optimization.py

@@ -1,43 +1,42 @@
-import numpy as np
-import pandas as pd
-from pypfopt import risk_models
-from pypfopt import expected_returns
+import warnings
+
+from pypfopt import expected_returns, risk_models
 from pypfopt.efficient_frontier import EfficientFrontier
 from pypfopt.hierarchical_portfolio import HRPOpt
-import warnings
 
 __all__ = [
-    'markowitz_weights', 
-    'hierarchical_risk_parity', 
-    'equal_weighted', 
+    '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:
+    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:
+    Returns
     -------
     dict
         Dictionary containing the optimal asset weights for maximizing the Sharpe ratio, normalized to sum to 1.
 
-    Notes:
+    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:
+
+    Raises
     ------
     Exception
         If all solvers fail, each will print an exception error message during runtime.
@@ -47,21 +46,22 @@ def markowitz_weights(prices=None, rfr=0.0, freq=252):
 
     # Try different solvers to maximize Sharpe ratio
     for solver in ['SCS', 'ECOS', 'OSQP']:
-        ef = EfficientFrontier(expected_returns=returns, 
-                               cov_matrix=cov, 
+        ef = EfficientFrontier(expected_returns=returns,
+                               cov_matrix=cov,
                                weight_bounds=(0, 1),
                                solver=solver)
         try:
-            weights = ef.max_sharpe(risk_free_rate=rfr)
+            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:
+    Parameters
     ----------
     prices : pd.DataFrame, optional
         Price data for assets; if provided, daily returns will be calculated.
@@ -70,17 +70,17 @@ def hierarchical_risk_parity(prices=None, returns=None, freq=252):
     freq : int, optional
         Number of days to consider in calculating portfolio weights (default is 252).
 
-    Returns:
+    Returns
     -------
     dict
         Optimized asset weights using the HRP method, with asset weights summing to 1.
 
-    Raises:
+    Raises
     ------
     ValueError
         If neither `prices` nor `returns` are provided.
 
-    Notes:
+    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 
@@ -97,11 +97,12 @@ def hierarchical_risk_parity(prices=None, returns=None, freq=252):
     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:
+    Parameters
     ----------
     prices : pd.DataFrame, optional
         Price data for assets, where each column represents an asset.
@@ -110,21 +111,22 @@ def equal_weighted(prices=None, returns=None, round_digits=5):
     round_digits : int, optional
         Number of decimal places to round each weight to (default is 5).
 
-    Returns:
+    Returns
     -------
     dict
         Dictionary with equal weights assigned to each asset, summing to 1.
 
-    Raises:
+    Raises
     ------
     ValueError
         If neither `prices` nor `returns` are provided.
 
-    Notes:
+    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:
@@ -135,11 +137,12 @@ def equal_weighted(prices=None, returns=None, round_digits=5):
         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:
+    Parameters
     ----------
     prices : pd.DataFrame, optional
         Price data for assets, required for certain methods.
@@ -150,17 +153,17 @@ def optimized_weights(prices=None, returns=None, rfr=0.0, freq=252, method='equa
     method : str, optional
         Optimization method to use ('markowitz', 'hrp', or 'equal') (default is 'markowitz').
 
-    Returns:
+    Returns
     -------
     dict
         Dictionary containing optimized asset weights based on the chosen method.
 
-    Raises:
+    Raises
     ------
     ValueError
         If an unknown optimization method is specified.
 
-    Notes:
+    Notes
     -----
     This function integrates different optimization methods:
     - 'markowitz': mean-variance optimization with max Sharpe ratio

bbstrader/models/{portfolios.py → portfolio.py}

@@ -1,27 +1,38 @@
-import numpy as np
+import matplotlib.pyplot as plt
 import pandas as pd
 import seaborn as sns
-import matplotlib.pyplot as plt
 from sklearn.decomposition import PCA
 from sklearn.preprocessing import scale
+
 from bbstrader.models.optimization import (
-    markowitz_weights, 
-    hierarchical_risk_parity, 
-    equal_weighted
+    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
@@ -31,13 +42,13 @@ class EigenPortfolios(object):
     def get_portfolios(self) -> pd.DataFrame:
         """
         Returns the computed eigenportfolios (weights of assets in each portfolio).
-        
-        Returns:
+
+        Returns
         -------
         pd.DataFrame
             DataFrame containing eigenportfolio weights for each asset.
-        
-        Raises:
+
+        Raises
         ------
         ValueError
             If `fit()` has not been called before retrieving portfolios.
@@ -46,23 +57,23 @@ class EigenPortfolios(object):
             raise ValueError("fit() must be called first")
         return self._portfolios
 
-    def fit(self, returns: pd.DataFrame, n_portfolios: int=4) -> pd.DataFrame:
+    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:
+
+        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:
+
+        Returns
         -------
         pd.DataFrame
             DataFrame containing normalized weights for each eigenportfolio.
 
-        Notes:
+        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 
@@ -70,11 +81,12 @@ class EigenPortfolios(object):
         """
         # Winsorize and normalize the returns
         normed_returns = scale(returns
-                            .clip(lower=returns.quantile(q=.025), 
-                                    upper=returns.quantile(q=.975), 
-                                    axis=1)
-                            .apply(lambda x: x.sub(x.mean()).div(x.std())))
-        returns = returns.dropna(thresh=int(normed_returns.shape[0] * .95), axis=1)
+                               .clip(lower=returns.quantile(q=.025),
+                                     upper=returns.quantile(q=.975),
+                                     axis=1)
+                               .apply(lambda x: x.sub(x.mean()).div(x.std())))
+        returns = returns.dropna(thresh=int(
+            normed_returns.shape[0] * .95), axis=1)
         returns = returns.dropna(thresh=int(normed_returns.shape[1] * .95))
 
         cov = returns.cov()
@@ -82,9 +94,12 @@ class EigenPortfolios(object):
         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)]
+        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
@@ -93,8 +108,8 @@ class EigenPortfolios(object):
     def plot_weights(self):
         """
         Plots the weights of each asset in each eigenportfolio as bar charts.
-        
-        Notes:
+
+        Notes
         -----
         Each subplot represents one eigenportfolio, showing the contribution of each asset.
         """
@@ -109,7 +124,7 @@ class EigenPortfolios(object):
         for ax in axes.flatten():
             ax.set_ylabel('Portfolio Weight')
             ax.set_xlabel('')
-        
+
         sns.despine()
         plt.tight_layout()
         plt.show()
@@ -117,25 +132,27 @@ class EigenPortfolios(object):
     def plot_performance(self):
         """
         Plots the cumulative returns of each eigenportfolio over time.
-        
-        Notes:
+
+        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])
-        
+        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 = 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)):
@@ -143,16 +160,16 @@ class EigenPortfolios(object):
 
         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:
+
+        Parameters
         ----------
         portfolio : int, optional
             Index of the eigenportfolio to optimize (default is 1).
@@ -164,29 +181,30 @@ class EigenPortfolios(object):
             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:
+
+        Returns
         -------
         dict
             Dictionary of optimized asset weights.
-        
-        Raises:
+
+        Raises
         ------
         ValueError
             If an unknown optimizer is specified, or if prices are not provided when using Markowitz optimization.
-        
-        Notes:
+
+        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.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")
+                raise ValueError(
+                    "prices must be provided for markowitz optimization")
             prices = prices.loc[:, returns.columns]
             weights = markowitz_weights(prices=prices, freq=freq)
         elif optimizer == 'hrp':
@@ -202,4 +220,4 @@ class EigenPortfolios(object):
             rc.plot(title=f'Optimized {portfolio.name}', lw=1, rot=0)
             sns.despine()
             plt.show()
-        return weights
+        return weights

bbstrader/models/risk.py

@@ -1,14 +1,18 @@
 import pickle
+from abc import ABCMeta, abstractmethod
+from datetime import datetime
+from typing import Dict, Optional
+
 import numpy as np
 import pandas as pd
 import seaborn as sns
-from datetime import datetime
 from hmmlearn.hmm import GaussianHMM
-from abc import ABCMeta, abstractmethod
-from matplotlib import cm, pyplot as plt
-from matplotlib.dates import YearLocator, MonthLocator
-from typing import Optional, Dict
+from matplotlib import cm
+from matplotlib import pyplot as plt
+from matplotlib.dates import MonthLocator, YearLocator
+
 from bbstrader.metatrader.rates import Rates
+
 sns.set_theme()
 
 __all__ = [
@@ -311,7 +315,7 @@ class HMMRiskManager(RiskModel):
         """
         df = data_frame.copy()
         if 'Returns' or 'returns' not in df.columns:
-            if 'Close'  in df.columns:
+            if 'Close' in df.columns:
                 df['Returns'] = df['Close'].pct_change()
             elif 'Adj Close' in df.columns:
                 df['Returns'] = df['Adj Close'].pct_change()
@@ -358,12 +362,13 @@ class HMMRiskManager(RiskModel):
             ax.grid(True)
         plt.show()
 
+
 def build_hmm_models(symbol_list=None, **kwargs
                      ) -> Dict[str, HMMRiskManager]:
     mt5_data = kwargs.get("use_mt5_data", False)
     data = kwargs.get("hmm_data")
     tf = kwargs.get("time_frame", 'D1')
-    hmm_end =  kwargs.get("hmm_end", 0)
+    hmm_end = kwargs.get("hmm_end", 0)
     sd = kwargs.get("session_duration", 23.0)
     hmm_tickers = kwargs.get("hmm_tickers")
     if hmm_tickers is not None:
@@ -385,10 +390,11 @@ def build_hmm_models(symbol_list=None, **kwargs
                 hmm_models[symbol] = hmm
     if mt5_data:
         for symbol in symbols:
-            rates = Rates(symbol, tf, start_pos=hmm_end, session_duration=sd)
+            rates = Rates(symbol, timeframe=tf, start_pos=hmm_end,
+                          session_duration=sd, **kwargs)
             data = rates.get_rates_from_pos()
             assert data is not None, f"No data for {symbol}"
             hmm = HMMRiskManager(
                 data=data, verbose=True, iterations=1000, **kwargs)
             hmm_models[symbol] = hmm
-    return hmm_models
+    return hmm_models

bbstrader/trading/__init__.py

@@ -7,5 +7,5 @@ The module is designed to be flexible and extensible, allowing users to define t
 strategies and customize the trading process.
 
 """
-from bbstrader.trading.execution import *
-from bbstrader.trading.strategies import *
+from bbstrader.trading.execution import *  # noqa: F403
+from bbstrader.trading.strategies import *  # noqa: F403