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

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
@@ -82,6 +84,8 @@ class Rates(object):
         2. The `open, high, low, close, adjclose, returns,
         volume` properties returns data in  Broker's timezone by default.
 
+        See `bbstrader.metatrader.account.check_mt5_connection()` for more details on how to connect to MT5 terminal.
+
     Example:
         >>> rates = Rates("EURUSD", "1h")
         >>> df = rates.get_historical_data(
@@ -94,17 +98,18 @@ class Rates(object):
     def __init__(
         self,
         symbol: str,
-        time_frame: TimeFrame = 'D1',
+        timeframe: TimeFrame = 'D1',
         start_pos: Union[int , str] = 0,
         count: Optional[int] = MAX_BARS,
-        session_duration: Optional[float] = None
+        session_duration: Optional[float] = None,
+        **kwargs
     ):
         """
         Initializes a new Rates instance.
 
         Args:
             symbol (str): Financial instrument symbol (e.g., "EURUSD").
-            time_frame (str): Timeframe string (e.g., "D1", "1h", "5m").
+            timeframe (str): Timeframe string (e.g., "D1", "1h", "5m").
             start_pos (int, | str): Starting index (int)  or date (str) for data retrieval.
             count (int, optional): Number of bars to retrieve default is
                 the maximum bars availble in the MT5 terminal.
@@ -118,16 +123,16 @@ class Rates(object):
             For `session_duration` check your broker symbols details
         """
         self.symbol = symbol
-        self.time_frame = self._validate_time_frame(time_frame)
+        self.time_frame = self._validate_time_frame(timeframe)
         self.sd = session_duration
-        self.start_pos = self._get_start_pos(start_pos, time_frame)
+        self.start_pos = self._get_start_pos(start_pos, timeframe)
         self.count = count
-        self._mt5_initialized()
-        self.__account = Account()
+        self._mt5_initialized(**kwargs)
+        self.__account = Account(**kwargs)
         self.__data = self.get_rates_from_pos()
 
-    def _mt5_initialized(self):
-        check_mt5_connection()
+    def _mt5_initialized(self, **kwargs):
+        check_mt5_connection(**kwargs)
     
     def _get_start_pos(self, index, time_frame):
         if isinstance(index, int):
@@ -219,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:
@@ -471,13 +475,13 @@ class Rates(object):
             df.to_csv(f"{self.symbol}.csv")
         return df
 
-def download_historical_data(symbol, time_frame, date_from, 
+def download_historical_data(symbol, timeframe, date_from, 
                              date_to=pd.Timestamp.now(),lower_colnames=True, 
-                             utc=False, filter=False, fill_na=False, save_csv=False):
+                             utc=False, filter=False, fill_na=False, save_csv=False, **kwargs):
     """Download historical data from MetaTrader 5 terminal.
     See `Rates.get_historical_data` for more details.
     """
-    rates = Rates(symbol, time_frame)
+    rates = Rates(symbol, timeframe, **kwargs)
     data = rates.get_historical_data(
         date_from=date_from,
         date_to=date_to,
@@ -488,23 +492,23 @@ def download_historical_data(symbol, time_frame, date_from,
     )
     return data
 
-def get_data_from_pos(symbol, time_frame, start_pos=0, fill_na=False, 
+def get_data_from_pos(symbol, timeframe, start_pos=0, fill_na=False, 
                       count=MAX_BARS, lower_colnames=False, utc=False, filter=False,
-                        session_duration=23.0):
+                        session_duration=23.0, **kwargs):
     """Get historical data from a specific position.
     See `Rates.get_rates_from_pos` for more details.
     """
-    rates = Rates(symbol, time_frame, start_pos, count, session_duration)
+    rates = Rates(symbol, timeframe, start_pos, count, session_duration, **kwargs)
     data = rates.get_rates_from_pos(filter=filter, fill_na=fill_na,
                                     lower_colnames=lower_colnames, utc=utc)
     return data
 
-def get_data_from_date(symbol, time_frame, date_from, count=MAX_BARS, fill_na=False, 
-                  lower_colnames=False, utc=False, filter=False):
+def get_data_from_date(symbol, timeframe, date_from, count=MAX_BARS, fill_na=False, 
+                  lower_colnames=False, utc=False, filter=False, **kwargs):
     """Get historical data from a specific date.
     See `Rates.get_rates_from` for more details.
     """
-    rates = Rates(symbol, time_frame)
+    rates = Rates(symbol, timeframe, **kwargs)
     data = rates.get_rates_from(date_from, count, filter=filter, fill_na=fill_na,
                                 lower_colnames=lower_colnames, utc=utc)
     return data

bbstrader/metatrader/risk.py

@@ -118,8 +118,10 @@ class RiskManagement(Account):
             tp (int, optional): Take Profit in points, Must be a positive number.
             be (int, optional): Break Even in points, Must be a positive number.
             rr (float, optional): Risk reward ratio, Must be a positive number. Defaults to 1.5.
+        
+        See `bbstrader.metatrader.account.check_mt5_connection()` for more details on how to connect to MT5 terminal.
         """
-        super().__init__()
+        super().__init__(**kwargs)
 
         # Validation
         if daily_risk is not None and daily_risk < 0:
@@ -137,6 +139,7 @@ class RiskManagement(Account):
         if var_time_frame not in TIMEFRAMES:
             raise ValueError("Unsupported time frame {}".format(var_time_frame))
 
+        self.kwargs = kwargs
         self.symbol = symbol
         self.start_time = start_time
         self.finishing_time = finishing_time
@@ -279,7 +282,7 @@ class RiskManagement(Account):
         tf_int = self._convert_time_frame(self._tf)
         interval = round((minutes / tf_int)  * 252)
 
-        rate = Rates(self.symbol, self._tf, 0, interval)
+        rate = Rates(self.symbol, self._tf, 0, interval, **self.kwargs)
         returns = rate.returns*100
         std = returns.std()
         point = self.get_symbol_info(self.symbol).point
@@ -333,7 +336,7 @@ class RiskManagement(Account):
         tf_int = self._convert_time_frame(tf)
         interval = round((minutes / tf_int)  * 252)
 
-        rate = Rates(self.symbol, tf, 0, interval)
+        rate = Rates(self.symbol, tf, 0, interval, **self.kwargs)
         returns = rate.returns*100
         p = self.get_account_info().margin_free
         mu = returns.mean()

bbstrader/metatrader/trade.py

@@ -138,6 +138,7 @@ class Trade(RiskManagement):
             -   tp
             -   be
         See the RiskManagement class for more details on these parameters.
+        See `bbstrader.metatrader.account.check_mt5_connection()` for more details on how to connect to MT5 terminal.
         """
         # Call the parent class constructor first
         super().__init__(
@@ -160,6 +161,7 @@ class Trade(RiskManagement):
         self.console_log = console_log
         self.logger = self._get_logger(logger, console_log)
         self.tf = kwargs.get("time_frame", 'D1')
+        self.kwargs = kwargs
 
         self.start_time_hour, self.start_time_minutes = self.start.split(":")
         self.finishing_time_hour, self.finishing_time_minutes = self.finishing.split(
@@ -174,8 +176,8 @@ class Trade(RiskManagement):
         self.break_even_points  = {}
         self.trail_after_points = []
 
-        self.initialize()
-        self.select_symbol()
+        self.initialize(**kwargs)
+        self.select_symbol(**kwargs)
         self.prepare_symbol()
 
         if self.verbose:
@@ -194,7 +196,7 @@ class Trade(RiskManagement):
             return config_logger(f'{log_path}/{logger}', consol_log)
         return logger
     
-    def initialize(self):
+    def initialize(self, **kwargs):
         """
         Initializes the MetaTrader 5 (MT5) terminal for trading operations. 
         This method attempts to establish a connection with the MT5 terminal. 
@@ -207,7 +209,7 @@ class Trade(RiskManagement):
         try:
             if self.verbose:
                 print("\nInitializing the basics.")
-            check_mt5_connection()
+            check_mt5_connection(**kwargs)
             if self.verbose:
                 print(
                     f"You are running the @{self.expert_name} Expert advisor,"
@@ -216,7 +218,7 @@ class Trade(RiskManagement):
         except Exception as e:
             self.logger.error(f"During initialization: {e}")
 
-    def select_symbol(self):
+    def select_symbol(self, **kwargs):
         """
         Selects the trading symbol in the MetaTrader 5 (MT5) terminal. 
         This method ensures that the specified trading 
@@ -228,6 +230,7 @@ class Trade(RiskManagement):
             MT5TerminalError: If symbole selection fails.
         """
         try:
+            check_mt5_connection(**kwargs)
             if not Mt5.symbol_select(self.symbol, True):
                 raise_mt5_error(message=INIT_MSG)
         except Exception as e:
@@ -848,10 +851,11 @@ class Trade(RiskManagement):
             positions = self.get_positions(symbol=self.symbol)
             if positions is not None:
                 positions = [position for position in positions if position.magic == id]
-        profit = 0.0
-        balance = self.get_account_info().balance
-        target = round((balance * self.target)/100, 2)
-        if positions is not None or len(positions) != 0:
+        
+        if positions is not None:
+            profit = 0.0
+            balance = self.get_account_info().balance
+            target = round((balance * self.target)/100, 2)
             for position in positions:
                 profit += position.profit
             fees = self.get_stats()[0]["average_fee"] * len(positions)
@@ -870,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.
@@ -879,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:
@@ -1489,6 +1496,7 @@ def create_trade_instance(
         daily_risk: Optional[Dict[str, float]] = None,
         max_risk: Optional[Dict[str, float]] = None,
         pchange_sl: Optional[Dict[str, float] | float] = None,
+        **kwargs
     ) -> Dict[str, Trade]:
     """
     Creates Trade instances for each symbol provided.
@@ -1510,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.")
@@ -1529,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)