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

bbstrader/__ini__.py

@@ -5,9 +5,9 @@ Simplified Investment & Trading Toolkit
 """
 __author__      = "Bertin Balouki SIMYELI"
 __copyright__   = "2023-2024 Bertin Balouki SIMYELI"
-__email__       = "bbalouki@outlook.com"
+__email__       = "bertin@bbstrader.com"
 __license__     = "MIT"
-__version__     = '0.1.91'
+__version__     = '0.2.0'
 
 
 from bbstrader import btengine

bbstrader/btengine/data.py

@@ -153,12 +153,19 @@ class BaseCSVDataHandler(DataHandler):
     @property
     def symbols(self)-> List[str]:
         return self.symbol_list
+    
     @property
     def data(self)-> Dict[str, pd.DataFrame]:
         return self.symbol_data
+    
+    @property
+    def datadir(self)-> str:
+        return self.csv_dir
+    
     @property
     def labels(self)-> List[str]:
         return self.columns
+    
     @property
     def index(self)-> str | List[str]:
         return self._index
@@ -203,6 +210,7 @@ class BaseCSVDataHandler(DataHandler):
                 'adj_close' if 'adj_close' in new_names else 'close'
             ].pct_change().dropna()
             self._index = self.symbol_data[s].index.name
+            self.symbol_data[s].to_csv(os.path.join(self.csv_dir, f'{s}.csv'))
             if self.events is not None:
                 self.symbol_data[s] = self.symbol_data[s].iterrows()
 
@@ -474,7 +482,8 @@ class YFDataHandler(BaseCSVDataHandler):
             filepath = os.path.join(cache_dir, f"{symbol}.csv")
             try:
                 data = yf.download(
-                    symbol, start=self.start_date, end=self.end_date, multi_level_index=False)
+                    symbol, start=self.start_date, end=self.end_date, 
+                    multi_level_index=False, progress=False)
                 if data.empty:
                     raise ValueError(f"No data found for {symbol}")
                 data.to_csv(filepath)
@@ -634,12 +643,13 @@ class FMPDataHandler(BaseCSVDataHandler):
             api_key=self.__api_key,
             start_date=self.start_date, 
             end_date=self.end_date,
-            benchmark_ticker=None
+            benchmark_ticker=None,
+            progress_bar=False
         )
         if period in ['daily', 'weekly', 'monthly', 'quarterly', 'yearly']:
-            return toolkit.get_historical_data(period=period)
+            return toolkit.get_historical_data(period=period, progress_bar=False)
         elif period in ['1min', '5min', '15min', '30min', '1hour']:
-            return toolkit.get_intraday_data(period=period)
+            return toolkit.get_intraday_data(period=period, progress_bar=False)
         
     def _format_data(self, data: pd.DataFrame, period: str) -> pd.DataFrame:
         if data.empty or len(data) == 0:

bbstrader/btengine/strategy.py

@@ -86,6 +86,7 @@ class MT5Strategy(Strategy):
         self.tf = kwargs.get("time_frame", 'D1')
         self.logger = kwargs.get("logger")
         self._initialize_portfolio()
+        self.kwargs = kwargs
 
     @property
     def cash(self) -> float:
@@ -201,19 +202,22 @@ class MT5Strategy(Strategy):
         - ``action``: The action to take for the symbol (LONG, SHORT, EXIT, etc.)
         - ``price``: The price at which to execute the action.
         - ``stoplimit``: The stop-limit price for STOP-LIMIT orders.
+        - ``id``: The unique identifier for the strategy or order.
 
-        The dictionary can be use for pending orders (limit, stop, stop-limit) where the price is required.
+        The dictionary can be use for pending orders (limit, stop, stop-limit) where the price is required
+        or for executing orders where the each order has a unique identifier.
         """
         pass
 
-    def apply_risk_management(self, optimer, freq=252) -> Dict[str, float] | None:
+    def apply_risk_management(self, optimer, symbols=None, freq=252) -> Dict[str, float] | None:
         """
         Apply risk management rules to the strategy.
         """
         if optimer is None:
             return None
+        symbols = symbols or self.symbols
         prices = self.get_asset_values(
-            symbol_list=self.symbols, bars=self.data, mode=self.mode, 
+            symbol_list=symbols, bars=self.data, mode=self.mode, 
             window=freq, value_type='close', array=False, tf=self.tf
         )
         prices = pd.DataFrame(prices)
@@ -222,7 +226,7 @@ class MT5Strategy(Strategy):
             weights = optimized_weights(prices=prices, freq=freq, method=optimer)
             return {symbol: weight for symbol, weight in weights.items()}
         except Exception:
-            return {symbol: 0.0 for symbol in self.symbols}
+            return {symbol: 0.0 for symbol in symbols}
 
     def get_quantity(self, symbol, weight,   price=None, volume=None, maxqty=None) -> int:
         """
@@ -530,7 +534,7 @@ class MT5Strategy(Strategy):
                     asset_values[asset] = getattr(values, value_type)    
         elif mode == 'live':
             for asset in symbol_list:
-                rates = Rates(symbol=asset, time_frame=tf, count=window + 1)
+                rates = Rates(asset, timeframe=tf, count=window + 1, **self.kwargs)
                 if array:
                     values = getattr(rates, value_type).values
                     asset_values[asset] = values[~np.isnan(values)]
@@ -575,11 +579,11 @@ class MT5Strategy(Strategy):
         Returns:
             bool : True if there are open positions, False otherwise
         """
-        account = account or Account()
+        account = account or Account(**self.kwargs)
         positions = account.get_positions(symbol=symbol)
         if positions is not None:
             open_positions = [
-                pos for pos in positions if pos.type == position
+                pos.ticket for pos in positions if pos.type == position
                 and pos.magic == strategy_id
             ]
             if one_true:
@@ -600,7 +604,7 @@ class MT5Strategy(Strategy):
         Returns:
             prices : numpy array of buy or sell prices for open positions if any or an empty array.
         """
-        account = account or Account()
+        account = account or Account(**self.kwargs)
         positions = account.get_positions(symbol=symbol)
         if positions is not None:
             prices = np.array([

bbstrader/config.py

@@ -3,6 +3,10 @@ from typing import List
 from pathlib import Path
 from datetime import datetime
 
+
+ADMIRAL_PATH = "C:\\Program Files\\Admirals Group MT5 Terminal\\terminal64.exe"
+FTMO_PATH    = "C:\\Program Files\\FTMO MetaTrader 5\\terminal64.exe"
+
 def get_config_dir(name: str=".bbstrader") -> Path:
     """
     Get the path to the configuration directory.

bbstrader/core/data.py

@@ -0,0 +1,23 @@
+import pandas as pd
+import numpy as np
+from financetoolkit import Toolkit
+
+
+__all__ = [
+    'FMP',
+]
+
+class FMP(Toolkit):
+    """
+    FMPData class for fetching data from Financial Modeling Prep API
+    using the Toolkit class from financetoolkit package.
+
+    See `financetoolkit` for more details.
+
+    """
+    def __init__(self, api_key: str ='', symbols: str | list = 'AAPL'):
+        super().__init__(tickers=symbols, api_key=api_key)
+
+
+class DataBendo:
+    ...

bbstrader/metatrader/rates.py

@@ -20,7 +20,9 @@ from exchange_calendars import(
 __all__ = [
     'Rates', 
     'download_historical_data', 
-    'get_data_from_pos'
+    'get_data_from_pos',
+    'get_data_from_date'
+    
 ]
 
 MAX_BARS = 10_000_000
@@ -121,7 +123,6 @@ class Rates(object):
             For `session_duration` check your broker symbols details
         """
         self.symbol = symbol
-        tf = kwargs.get('time_frame')
         self.time_frame = self._validate_time_frame(timeframe)
         self.sd = session_duration
         self.start_pos = self._get_start_pos(start_pos, timeframe)
@@ -223,7 +224,6 @@ class Rates(object):
         df.columns = ['Date', 'Open', 'High', 'Low', 'Close', 'Volume']
         df['Adj Close'] = df['Close']
         df = df[['Date', 'Open', 'High', 'Low', 'Close', 'Adj Close', 'Volume']]
-        #df = df.columns.rename(str.lower).str.replace(' ', '_')
         df['Date'] = pd.to_datetime(df['Date'], unit='s', utc=utc)
         df.set_index('Date', inplace=True)
         if lower_colnames:

bbstrader/metatrader/trade.py

@@ -874,8 +874,9 @@ class Trade(RiskManagement):
         """
         This function checks if it's time to set the break-even level for a trading position. 
         If it is, it sets the break-even level. If the break-even level has already been set, 
-        it checks if the price has moved in a favorable direction. If it has, and the trail parameter is set to True, 
-        it updates the break-even level based on the trail_after_points and stop_trail parameters.
+        it checks if the price has moved in a favorable direction. 
+        If it has, and the trail parameter is set to True, it updates 
+        the break-even level based on the trail_after_points and stop_trail parameters.
 
         Args:
             id (int): The strategy ID or expert ID.
@@ -883,8 +884,10 @@ class Trade(RiskManagement):
             trail (bool): Whether to trail the stop loss or not.
             stop_trail (int): Number of points to trail the stop loss by.
                 It represent the distance from the current price to the stop loss.
-            trail_after_points (int): Number of points in profit from where the strategy will start to trail the stop loss.
-            be_plus_points (int): Number of points to add to the break-even level. Represents the minimum profit to secure.
+            trail_after_points (int): Number of points in profit 
+                from where the strategy will start to trail the stop loss.
+            be_plus_points (int): Number of points to add to the break-even level. 
+                Represents the minimum profit to secure.
         """
         time.sleep(0.1)
         if not mm:
@@ -1515,6 +1518,7 @@ def create_trade_instance(
         based on the importance of the symbol in the portfolio or strategy.
     """
     logger = params.get('logger', None)
+    ids = params.get('expert_id', None)
     trade_instances = {}
     if not symbols:
         raise ValueError("The 'symbols' list cannot be empty.")
@@ -1534,10 +1538,19 @@ def create_trade_instance(
             for symbol in symbols:
                 if symbol not in pchange_sl:
                     raise ValueError(f"Missing percentage change for symbol '{symbol}'.")
+    if isinstance(ids, dict):
+        for symbol in symbols:
+            if symbol not in ids:
+                raise ValueError(f"Missing expert ID for symbol '{symbol}'.")
     
     for symbol in symbols:
         try:
             params['symbol'] = symbol
+            params['expert_id'] = (
+                ids[symbol] if ids is not None and isinstance(ids, dict) else 
+                ids if ids is not None and isinstance(ids, (int, float)) else 
+                params['expert_id'] if 'expert_id' in params else None
+            )
             params['pchange_sl'] = (
                 pchange_sl[symbol] if pchange_sl is not None
                 and isinstance(pchange_sl, dict) else 

bbstrader/models/__init__.py

@@ -5,6 +5,6 @@ It is designed to be a versatile base module for different types of models used
 """
 from bbstrader.models.risk import *
 from bbstrader.models.optimization import *
-from bbstrader.models.portfolios import *
+from bbstrader.models.portfolio import *
 from bbstrader.models.factors import *
 from bbstrader.models.ml import *

bbstrader/models/factors.py

@@ -0,0 +1,275 @@
+import pandas as pd
+import numpy as np
+import yfinance as yf
+from datetime import datetime
+from bbstrader.metatrader.rates import download_historical_data
+from bbstrader.btengine.data import FMPDataHandler, EODHDataHandler
+from typing import List, Dict, Literal, Union
+from bbstrader.tseries import (
+    find_cointegrated_pairs,
+    select_candidate_pairs,
+    select_assets,
+)
+
+__all__ = [
+    "search_coint_candidate_pairs",
+]
+
+def search_coint_candidate_pairs(
+        securities: pd.DataFrame | List[str] = None,
+        candidates: pd.DataFrame | List[str] = None,
+        start:      str = None,
+        end:        str = None,
+        period_search: bool = False,
+        select:     bool = True,
+        source:     str = None,
+        universe:   int = 100,
+        window:     int = 2,
+        rolling_window: int = None,
+        npairs:     int = 10,
+        tf:         str = 'D1',
+        path:       str = None,
+        **kwargs
+) -> List[Dict[str, str]] | pd.DataFrame:
+    """
+    Searches for candidate pairs of securities based on cointegration analysis.
+
+    This function either processes preloaded securities and candidates data 
+    (as pandas DataFrames) or downloads historical data from a specified 
+    source (e.g., Yahoo Finance, MetaTrader 5, Financial Modeling Prep, or EODHD).
+    It then selects the top `npairs` based on cointegration.
+
+    Args:
+        securities (pd.DataFrame | List[str], optional): 
+            A DataFrame or list of tickers representing the securities for analysis. 
+            If using a DataFrame, it should include a MultiIndex with levels 
+            ['ticker', 'date'].
+        candidates (pd.DataFrame | List[str], optional): 
+            A DataFrame or list of tickers representing the candidate securities 
+            for pair selection.
+        start (str, optional): 
+            The start date for data retrieval in 'YYYY-MM-DD' format. Ignored 
+            if both `securities` and `candidates` are DataFrames.
+        end (str, optional): 
+            The end date for data retrieval in 'YYYY-MM-DD' format. Ignored 
+            if both `securities` and `candidates` are DataFrames.
+        period_search (bool, optional):
+            If True, the function will perform a periodic search for cointegrated from 3 years
+            to the end date by taking 2 yerars rolling window. So you need to have at least 3 years of data
+            or set the `window` parameter to 3. Defaults to False.
+        select (bool, optional):
+            If True, the function will select the top cointegrated pairs based on the 
+            cointegration test results in form of List[dict].
+            If False, the function will return all cointegrated pairs in form of DataFrame.
+            This can be useful for further analysis or visualization.
+        source (str, optional): 
+            The data source for historical data retrieval. Must be one of 
+            ['yf', 'mt5', 'fmp', 'eodhd']. Required if `securities` and 
+            `candidates` are lists of tickers.
+        universe (int, optional): 
+            The maximum number of assets to retain for analysis. Defaults to 100.
+        window (int, optional): 
+            The number of years of historical data to retrieve if `start` and `end` 
+            are not specified. Defaults to 2 years.
+        rolling_window (int, optional): 
+            The size of the rolling window (in days) used for asset selection. 
+            Defaults to None.
+        npairs (int, optional): 
+            The number of top cointegrated pairs to select. Defaults to 10.
+        tf (str, optional): 
+            The timeframe for MetaTrader 5 data retrieval. Defaults to 'D1'.
+        path (str, optional): 
+            The path to MetaTrader 5 historical data files. Required if `source='mt5'`.
+        **kwargs: 
+            Additional parameters for data retrieval (e.g., API keys, date ranges 
+            for specific sources), see ``bbstrader.btengine.data.FMPDataHandler`` or
+            ``bbstrader.btengine.data.EODHDataHandler`` for more details.
+
+    Returns:
+        List[dict]: A list containing the selected top cointegrated pairs if `select=True`.
+        pd.DataFrame: A DataFrame containing all cointegrated pairs if `select=False`.
+
+    Raises:
+        ValueError: If the inputs are invalid or if the `source` is not one of 
+        the supported sources.
+
+    Examples:
+        Using preloaded DataFrames:
+            >>> securities = pd.read_csv('securities.csv', index_col=['ticker', 'date'])
+            >>> candidates = pd.read_csv('candidates.csv', index_col=['ticker', 'date'])
+            >>> pairs = search_candidate_pairs(securities=securities, candidates=candidates)
+
+        Using a data source (Yahoo Finance):
+            >>> securities = ['SPY', 'IWM', 'XLF', 'HYG', 'XLE', 'LQD', 'GDX', 'FXI', 'EWZ', ...]
+            >>> candidates = ['AAPL', 'AMZN', 'NVDA', 'MSFT', 'GOOGL', 'AMD', 'BAC', 'NFLX', ...]
+
+            >>> pairs = search_candidate_pairs(
+            ...     securities=securities,
+            ...     candidates=candidates,
+            ...     start='2022-12-12',
+            ...     end='2024-12-10',
+            ...     source='yf',
+            ...     npairs=10
+            ... )
+            >>>    [
+            ...    {'x': 'LQD', 'y': 'TMO'},
+            ...    {'x': 'IEF', 'y': 'COP'},
+            ...    {'x': 'WMT', 'y': 'IWM'},
+            ...    {'x': 'MDT', 'y': 'OIH'},
+            ...    {'x': 'EWZ', 'y': 'CMCSA'},
+            ...    {'x': 'VLO', 'y': 'XOP'},
+            ...    {'x': 'SHY', 'y': 'F'},
+            ...    {'x': 'ABT', 'y': 'LQD'},
+            ...    {'x': 'PFE', 'y': 'USO'},
+            ...    {'x': 'LQD', 'y': 'MDT'}
+            ...    ]
+
+        Using MetaTrader 5:
+            >>> securities = ['EURUSD', 'GBPUSD']
+            >>> candidates = ['USDJPY', 'AUDUSD']
+            >>> pairs = search_candidate_pairs(
+            ...     securities=securities,
+            ...     candidates=candidates,
+            ...     source='mt5',
+            ...     tf='H1',
+            ...     path='/path/to/terminal64.exe',
+            ... )
+
+    Notes:
+        - If `securities` and `candidates` are DataFrames, the function assumes 
+          the data is already preprocessed and indexed by ['ticker', 'date'].
+        - When using `source='fmp'` or `source='eodhd'`, API keys and other 
+          required parameters should be passed via `kwargs`.
+
+    """
+
+    def _download_and_process_data(source, tickers, start, end, tf, path, **kwargs):
+        """Download and process data for a list of tickers from the specified source."""
+        data_list = []
+        for ticker in tickers:
+            try:
+                if source == 'yf':
+                    data = yf.download(
+                        ticker, start=start, end=end, progress=False, multi_level_index=False)
+                    data = data.drop(columns=['Adj Close'], axis=1)
+                elif source == 'mt5':
+                    start, end = pd.Timestamp(start), pd.Timestamp(end)
+                    data = download_historical_data(
+                        symbol=ticker, timeframe=tf, date_from=start, date_to=end, **{'path': path})
+                    data = data.drop(columns=['adj_close'], axis=1)
+                elif source in ['fmp', 'eodhd']:
+                    handler_class = FMPDataHandler if source == 'fmp' else EODHDataHandler
+                    handler = handler_class(
+                        events=None, symbol_list=[ticker], **kwargs)
+                    data = handler.data[ticker]
+                else:
+                    raise ValueError(f"Invalid source: {source}")
+
+                data = data.reset_index()
+                data = data.rename(columns=str.lower)
+                data['ticker'] = ticker
+                data_list.append(data)
+
+            except Exception as e:
+                print(f"No Data found for {ticker}: {e}")
+                continue
+
+        return pd.concat(data_list)
+
+    def _handle_date_range(start, end, window):
+        """Handle start and end date generation."""
+        if start is None or end is None:
+            end = pd.Timestamp(datetime.now()).strftime('%Y-%m-%d')
+            start = (
+                pd.Timestamp(datetime.now()) -
+                pd.DateOffset(years=window) + pd.DateOffset(days=1)
+            ).strftime('%Y-%m-%d')
+        return start, end
+
+    def _period_search(start, end, securities, candidates, npairs=npairs):
+        if window < 3 or (pd.Timestamp(end) - pd.Timestamp(start)).days / 365 < 3:
+            raise ValueError(
+                "The date range must be at least two (2) years for period search."
+            )
+        top_pairs = []
+        p_start = pd.Timestamp(end) - pd.DateOffset(years=1)
+        periods = pd.date_range(start=p_start, end=pd.Timestamp(end), freq='BQE')
+        npairs = max(round(npairs/2), 1)
+        for period in periods:
+            s_start = period - pd.DateOffset(years=2) + pd.DateOffset(days=1)
+            print(f"Searching for pairs in period: {s_start} - {period}")
+            pairs = find_cointegrated_pairs(
+                securities, candidates, n=npairs, start=str(s_start), stop=str(period), coint=True)      
+            pairs['period'] = period
+            top_pairs.append(pairs)
+        top_pairs = pd.concat(top_pairs)
+        if len(top_pairs.columns) <= 1:
+            raise ValueError(
+                "No pairs found in the specified period."
+                "Please adjust the date range or increase the number of pairs."
+                )
+        return top_pairs.head(npairs*2)
+
+    def _process_asset_data(securities, candidates, universe, rolling_window):
+        """Process and select assets from the data."""
+        securities = select_assets(
+            securities, n=universe, rolling_window=rolling_window)
+        candidates = select_assets(
+            candidates, n=universe, rolling_window=rolling_window)
+        return securities, candidates
+    
+    if (securities is not None and candidates is not None
+            and isinstance(securities, pd.DataFrame)
+            and isinstance(candidates, pd.DataFrame)
+            ):
+        if isinstance(securities.index, pd.MultiIndex) and isinstance(candidates.index, pd.MultiIndex):
+            securities, candidates = _process_asset_data(
+                securities, candidates, universe, rolling_window)
+        if period_search:
+            start = securities.index.get_level_values('date').min()
+            end = securities.index.get_level_values('date').max()
+            top_pairs = _period_search(start, end, securities, candidates)
+        else:
+            top_pairs = find_cointegrated_pairs(
+                securities, candidates, n=npairs, coint=True)
+        if select:
+            return select_candidate_pairs(top_pairs, period=True if period_search else False)
+        else:
+            return top_pairs
+
+    elif source is not None:
+        if source not in ['yf', 'mt5', 'fmp', 'eodhd']:
+            raise ValueError(
+                "source must be either 'yf', 'mt5', 'fmp', or 'eodhd'")
+        if not isinstance(securities, list) or not isinstance(candidates, list):
+            raise ValueError(
+                "securities and candidates must be a list of tickers")
+
+        start, end = _handle_date_range(start, end, window)
+        if source in ['fmp', 'eodhd']:
+            kwargs[f'{source}_start'] = kwargs.get(f'{source}_start') or start
+            kwargs[f'{source}_end'] = kwargs.get(f'{source}_end') or end
+
+        securities_data = _download_and_process_data(
+            source, securities, start, end, tf, path, **kwargs)
+        candidates_data = _download_and_process_data(
+            source, candidates, start, end, tf, path, **kwargs)
+        securities_data = securities_data.set_index(['ticker', 'date'])
+        candidates_data = candidates_data.set_index(['ticker', 'date'])
+        securities_data, candidates_data = _process_asset_data(
+            securities_data, candidates_data, universe, rolling_window)
+        if period_search:
+            top_pairs = _period_search(start, end, securities_data, candidates_data).head(npairs)
+        else:
+            top_pairs = find_cointegrated_pairs(securities_data, candidates_data, n=npairs, coint=True)
+        if select:
+            return select_candidate_pairs(top_pairs, period=True if period_search else False)
+        else:
+            return top_pairs
+
+    else:
+        msg = (
+            "Invalid input. Either provide securities"
+            "and candidates as DataFrames or specify a data source."
+        )
+        raise ValueError(msg)