bbstrader 0.1.9__py3-none-any.whl → 0.1.92__py3-none-any.whl

bbstrader/metatrader/utils.py

@@ -33,61 +33,8 @@ __all__ = [
     "InternalFailTimeout",
     "trade_retcode_message",
     "raise_mt5_error",
-    "config_logger",
 ]
 
-def config_logger(log_file: str, console_log=True):
-    # Configure the logger
-    logger = logging.getLogger(__name__)
-    logger.setLevel(logging.DEBUG)
-
-    # File handler
-    file_handler = logging.FileHandler(log_file)
-    file_handler.setLevel(logging.INFO)
-
-    # Formatter
-    formatter = logging.Formatter(
-        '%(asctime)s - %(levelname)s: %(message)s', datefmt="%Y-%m-%d %H:%M:%S")
-    file_handler.setFormatter(formatter)
-
-    # Add the handler to the logger
-    logger.addHandler(file_handler)
-
-    if console_log:
-        # handler for the console with a different level
-        console_handler = logging.StreamHandler()
-        console_handler.setLevel(logging.DEBUG)
-        console_handler.setFormatter(formatter)
-        logger.addHandler(console_handler)
-
-    return logger
-
-
-class LogLevelFilter(logging.Filter):
-    def __init__(self, levels: List[int]):
-        """
-        Initializes the filter with specific logging levels.
-
-        Args:
-            levels: A list of logging level values (integers) to include.
-        """
-        super().__init__()
-        self.levels = levels
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        """
-        Filters log records based on their level.
-
-        Args:
-            record: The log record to check.
-
-        Returns:
-            True if the record's level is in the allowed levels, False otherwise.
-        """
-        return record.levelno in self.levels
-
-
-
 # TIMEFRAME is an enumeration with possible chart period values
 # See https://www.mql5.com/en/docs/python_metatrader5/mt5copyratesfrom_py#timeframe
 TIMEFRAMES = {
@@ -141,6 +88,7 @@ class TimeFrame(Enum):
     W1 = "W1"
     MN1 = "MN1"
 
+
 class TerminalInfo(NamedTuple):
     """
     Represents general information about the trading terminal.
@@ -470,6 +418,7 @@ class TradeDeal(NamedTuple):
     comment: str
     external_id: str
 
+
 class InvalidBroker(Exception):
     """Exception raised for invalid broker errors."""
     def __init__(self, message="Invalid broker."):

bbstrader/models/optimization.py

@@ -0,0 +1,170 @@
+import numpy as np
+import pandas as pd
+from pypfopt import risk_models
+from pypfopt import expected_returns
+from pypfopt.efficient_frontier import EfficientFrontier
+from pypfopt.hierarchical_portfolio import HRPOpt
+import warnings
+
+def markowitz_weights(prices=None, 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:
+            weights = ef.max_sharpe()
+            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()
+    # 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, freq=252, method='markowitz'):
+    """
+    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, 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/portfolios.py

@@ -0,0 +1,202 @@
+import numpy as np
+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
+)
+
+
+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.
+    
+    """
+    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=.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()
+        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

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 ExecutionEngine
+from bbstrader.trading.execution import *
 from bbstrader.trading.strategies import *