investing-algorithm-framework 7.0.2__tar.gz → 7.1.0__tar.gz

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 7.0.2
+Version: 7.1.0
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/app/app.py

@@ -26,7 +26,7 @@ from investing_algorithm_framework.infrastructure import setup_sqlalchemy, \
     BacktestOrderExecutor, CCXTOHLCVDataProvider, clear_db
 from investing_algorithm_framework.services import OrderBacktestService, \
     BacktestPortfolioService, BacktestTradeOrderEvaluator, \
-    DefaultTradeOrderEvaluator
+    DefaultTradeOrderEvaluator, get_risk_free_rate_us
 from .app_hook import AppHook
 from .eventloop import EventLoopService
 
@@ -381,6 +381,10 @@ class App:
             None
         """
         logger.info("Initializing data sources")
+
+        if data_sources is None or len(data_sources) == 0:
+            return
+
         data_provider_service = self.container.data_provider_service()
         data_provider_service.reset()
 
@@ -415,6 +419,10 @@ class App:
             None
         """
         logger.info("Initializing data sources for backtest")
+
+        if data_sources is None or len(data_sources) == 0:
+            return
+
         data_provider_service = self.container.data_provider_service()
         data_provider_service.reset()
 
@@ -825,6 +833,18 @@ class App:
         self.initialize_backtest_services()
         self.initialize_backtest_portfolios()
 
+        if risk_free_rate is None:
+            logger.info("No risk free rate provided, retrieving it...")
+            risk_free_rate = get_risk_free_rate_us()
+
+            if risk_free_rate is None:
+                raise OperationalException(
+                    "Could not retrieve risk free rate for backtest metrics."
+                    "Please provide a risk free as an argument when running "
+                    "your backtest or make sure you have an internet "
+                    "connection"
+                )
+
         algorithm = self.container.algorithm_factory().create_algorithm(
             name=name if name else self._name,
             strategies=(
@@ -888,18 +908,90 @@ class App:
 
         return backtest
 
+    def run_vector_backtests(
+        self,
+        backtest_date_range: BacktestDateRange,
+        initial_amount,
+        strategies: List[TradingStrategy],
+        snapshot_interval: SnapshotInterval = SnapshotInterval.DAILY,
+        risk_free_rate: Optional[float] = None,
+        skip_data_sources_initialization: bool = False
+    ):
+        """
+        Run vectorized backtests for a set of strategies. The provided
+        set of strategies need to have their 'buy_signal_vectorized' and
+        'sell_signal_vectorized' methods implemented to support vectorized
+        backtesting.
+
+        Args:
+            backtest_date_range: The date range to run the backtest for
+                (instance of BacktestDateRange)
+            initial_amount: The initial amount to start the backtest with.
+                This will be the amount of trading currency that the backtest
+                portfolio will start with.
+            strategies (List[TradingStrategy]): List of strategy objects
+                that need to be backtested. Each strategy should implement
+                the 'buy_signal_vectorized' and 'sell_signal_vectorized'
+                methods to support vectorized backtesting.
+            snapshot_interval (SnapshotInterval): The snapshot
+                interval to use for the backtest. This is used to determine
+                how often the portfolio snapshot should be taken during the
+                backtest. The default is TRADE_CLOSE, which means that the
+                portfolio snapshot will be taken at the end of each trade.
+            risk_free_rate (Optional[float]): The risk-free rate to use for
+                the backtest. This is used to calculate the Sharpe ratio
+                and other performance metrics. If not provided, the default
+                risk-free rate will be tried to be fetched from the
+                US Treasury website.
+            skip_data_sources_initialization (bool): Whether to skip the
+                initialization of data sources. This is useful when the data
+                sources are already initialized, and you want to skip the
+                initialization step. This will speed up the backtesting
+                process, but make sure that the data sources are already
+                initialized before calling this method.
+
+        Returns:
+            List[Backtest]: List of Backtest instances for each strategy
+                that was backtested.
+        """
+        backtests = []
+        data_sources = []
+
+        for strategy in strategies:
+            data_sources.extend(strategy.data_sources)
+
+        if not skip_data_sources_initialization:
+            self.initialize_data_sources_backtest(
+                data_sources, backtest_date_range
+            )
+
+        for strategy in tqdm(strategies):
+            backtests.append(
+                self.run_vector_backtest(
+                    backtest_date_range=backtest_date_range,
+                    initial_amount=initial_amount,
+                    strategy=strategy,
+                    snapshot_interval=snapshot_interval,
+                    risk_free_rate=risk_free_rate,
+                    skip_data_sources_initialization=True
+                )
+            )
+
+        return backtests
+
     def run_vector_backtest(
         self,
         backtest_date_range: BacktestDateRange,
         initial_amount,
-        strategy,
+        strategy: TradingStrategy,
         snapshot_interval: SnapshotInterval = SnapshotInterval.DAILY,
         metadata: Optional[Dict[str, str]] = None,
         risk_free_rate: Optional[float] = None,
+        skip_data_sources_initialization: bool = False
     ) -> Backtest:
         """
-        Run a vectorized backtest for an algorithm. The provided algorithm
-        or set of strategies need to have their 'buy_signal_vectorized' and
+        Run vectorized backtests for a strategy. The provided
+        strategy needs to have its 'buy_signal_vectorized' and
         'sell_signal_vectorized' methods implemented to support vectorized
         backtesting.
 
@@ -925,6 +1017,12 @@ class App:
                 backtest report. This can be used to store additional
                 information about the backtest, such as the author, version,
                 parameters or any other relevant information.
+            skip_data_sources_initialization (bool): Whether to skip the
+                initialization of data sources. This is useful when the data
+                sources are already initialized, and you want to skip the
+                initialization step. This will speed up the backtesting
+                process, but make sure that the data sources are already
+                initialized before calling this method.
 
         Returns:
             Backtest: Instance of Backtest
@@ -935,9 +1033,24 @@ class App:
             snapshot_interval=snapshot_interval,
             initial_amount=initial_amount
         )
-        self.initialize_data_sources_backtest(
-            strategy.data_sources, backtest_date_range
-        )
+
+        if not skip_data_sources_initialization:
+            self.initialize_data_sources_backtest(
+                strategy.data_sources, backtest_date_range
+            )
+
+        if risk_free_rate is None:
+            logger.info("No risk free rate provided, retrieving it...")
+            risk_free_rate = get_risk_free_rate_us()
+
+            if risk_free_rate is None:
+                raise OperationalException(
+                    "Could not retrieve risk free rate for backtest metrics."
+                    "Please provide a risk free as an argument when running "
+                    "your backtest or make sure you have an internet "
+                    "connection"
+                )
+
         backtest_service = self.container.backtest_service()
         backtest_service.validate_strategy_for_vector_backtest(strategy)
         backtest = backtest_service.create_vector_backtest(
@@ -946,7 +1059,17 @@ class App:
             initial_amount=initial_amount,
             risk_free_rate=risk_free_rate
         )
-        backtest.metadata = metadata if metadata is not None else {}
+
+        # Add the metadata to the backtest
+        if metadata is None:
+
+            if strategy.metadata is not None:
+                backtest.metadata = {}
+            else:
+                backtest.metadata = strategy.metadata
+        else:
+            backtest.metadata = metadata
+
         return backtest
 
     def run_backtests(
@@ -977,7 +1100,8 @@ class App:
                 for the backtest. This is used to determine how often the
                 portfolio snapshot should be taken during the backtest.
             risk_free_rate (Optional[float]): The risk-free rate to use for
-                calculating performance metrics. If not provided, the default
+                the backtest. This is used to calculate the Sharpe ratio
+                and other performance metrics. If not provided, the default
                 risk-free rate will be tried to be fetched from the
                 US Treasury website.
             save (bool): Whether to save the backtest reports to disk.
@@ -994,7 +1118,6 @@ class App:
         """
         backtests = []
         backtest_service = self.container.backtest_service()
-        final_algorithms = []
 
         if algorithms is not None:
             final_algorithms = algorithms
@@ -1011,6 +1134,18 @@ class App:
                 "No algorithms or strategy provided for backtesting"
             )
 
+        if risk_free_rate is None:
+            logger.info("No risk free rate provided, retrieving it...")
+            risk_free_rate = get_risk_free_rate_us()
+
+            if risk_free_rate is None:
+                raise OperationalException(
+                    "Could not retrieve risk free rate for backtest metrics."
+                    "Please provide a risk free as an argument when running "
+                    "your backtest or make sure you have an internet "
+                    "connection"
+                )
+
         for date_range in backtest_date_ranges:
             for algorithm in final_algorithms:
 

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/app/strategy.py

@@ -27,8 +27,12 @@ class TradingStrategy:
             sources to use for the strategy. The data sources will be used
             to indentify data providers that will be called to gather data
             and pass to the strategy before its run.
+        metadata (optional): Dict[str, Any] - a dictionary
+            containing metadata about the strategy. This can be used to
+            store additional information about the strategy, such as its
+            author, version, description, params etc.
     """
-    time_unit: str = None
+    time_unit: TimeUnit = None
     interval: int = None
     worker_id: str = None
     strategy_id: str = None
@@ -36,6 +40,7 @@ class TradingStrategy:
     data_sources: List[DataSource] = None
     traces = None
     context: Context = None
+    metadata: Dict[str, Any] = None
 
     def __init__(
         self,
@@ -43,6 +48,7 @@ class TradingStrategy:
         time_unit=None,
         interval=None,
         data_sources=None,
+        metadata=None,
         worker_id=None,
         decorated=None
     ):
@@ -65,6 +71,8 @@ class TradingStrategy:
         if data_sources is not None:
             self.data_sources = data_sources
 
+        self.metadata = metadata if metadata is not None else {}
+
         if decorated is not None:
             self.decorated = decorated
 

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/domain/models/time_unit.py

@@ -1,8 +1,16 @@
 from datetime import timedelta
 from enum import Enum
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
 
 
 class TimeUnit(Enum):
+    """
+    Enum class the represents a time unit such as
+    second, minute, hour or day. This can class
+    can be used to specify time specification within
+    the framework.
+    """
     SECOND = "SECOND"
     MINUTE = "MINUTE"
     HOUR = "HOUR"
@@ -18,7 +26,11 @@ class TimeUnit(Enum):
                 if value.upper() == entry.value:
                     return entry
 
-        raise ValueError(
+            raise OperationalException(
+                f"Could not convert string {value} to time unit"
+            )
+
+        raise OperationalException(
             f"Could not convert value {value} to time unit," +
             " please make sure that the value is either of type string or" +
             f"TimeUnit. Its current type is {type(value)}"
@@ -38,17 +50,21 @@ class TimeUnit(Enum):
             TimeUnit: The extracted time unit.
         """
         if not isinstance(file_path, str):
-            raise ValueError("File path must be a string.")
+            raise OperationalException(
+                "File path must be a string."
+            )
 
         parts = file_path.split('_')
         if len(parts) < 2:
-            raise ValueError("File name does not contain a valid time unit.")
+            raise OperationalException(
+                "File name does not contain a valid time unit."
+            )
 
         time_unit_str = parts[-1].split('.')[0].upper()
         try:
             return TimeUnit.from_string(time_unit_str)
         except ValueError:
-            raise ValueError(
+            raise OperationalException(
                 f"Could not extract time unit from file name: {file_path}. "
                 "Expected format 'symbol_timeunit.csv', "
                 f"got '{time_unit_str}'."

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/download_data.py

@@ -1,5 +1,6 @@
+from pathlib import Path
 from dateutil import parser
-from datetime import timezone
+from datetime import timezone, datetime
 import pandas
 import polars
 from typing import Union
@@ -8,21 +9,21 @@ from investing_algorithm_framework.services import DataProviderService, \
 from investing_algorithm_framework.infrastructure import \
     get_default_data_providers
 from investing_algorithm_framework.domain import DataSource, \
-    OperationalException
+    OperationalException, DataType
 
 
 def download(
     symbol: str,
-    market=None,
-    date=None,
+    market: str = None,
+    date: Union[datetime, str] = None,
     time_frame: str = None,
-    data_type: str = "ohlcv",
-    start_date: str = None,
-    end_date: str = None,
+    data_type: Union[str, DataType] = DataType.OHLCV,
+    start_date: Union[datetime, str] = None,
+    end_date: Union[datetime, str] = None,
     window_size: int = 200,
     pandas: bool = True,
     save: bool = True,
-    storage_path: str = None,
+    storage_path: Union[str, Path] = None,
 ) -> Union[pandas.DataFrame, polars.DataFrame]:
     """
     Download market data from the specified source. This function

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/infrastructure/data_providers/ccxt.py

@@ -142,7 +142,7 @@ class CCXTOHLCVDataProvider(DataProvider):
                 symbol=symbol,
                 market=market,
                 time_frame=data_source.time_frame,
-                storage_path=self.storage_path,
+                storage_path=data_source.storage_path,
                 start_date=start_date,
                 end_date=end_date
             )

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/__init__.py

@@ -12,6 +12,7 @@ from .portfolios import PortfolioService, BacktestPortfolioService, \
 from .positions import PositionService, PositionSnapshotService
 from .repository_service import RepositoryService
 from .trade_service import TradeService
+from .metrics import get_risk_free_rate_us
 
 __all__ = [
     "OrderService",
@@ -34,4 +35,5 @@ __all__ = [
     "PortfolioProviderLookup",
     "TradeOrderEvaluator",
     "DefaultTradeOrderEvaluator",
+    "get_risk_free_rate_us"
 ]

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/backtesting/backtest_service.py

@@ -323,7 +323,7 @@ class BacktestService(Observable):
             algorithm: The algorithm to create the backtest report for
             number_of_runs: The number of runs
             backtest_date_range: The backtest date range of the backtest
-            risk_free_rate: The risk-free rate to use in the calculations
+            risk_free_rate: The risk-free rate to use for the backtest metrics
             strategy_directory_path (optional, str): The path to the
                 strategy directory
 

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/data_providers/data_provider_service.py

@@ -44,18 +44,18 @@ class DataProviderIndex:
 
     def register(self, data_source: DataSource) -> DataProvider:
         """
-        Register an ohlcv data provider for a given market and symbol.
+        Register a data source in the DataProvider Index.
 
-        This method will also check if the data provider supports
-        the market. If no data provider is found for the market and symbol,
-        it will raise an ImproperlyConfigured exception.
 
-        If multiple data providers are found for the market and symbol,
+        This method will go over all data providers and select the
+        best matching data provider for the data source.
+
+        If multiple data providers are found for the data source,
         it will sort them by priority and pick the best one.
 
         Args:
             data_source (DataSource): The data source to register the
-                ohlcv data provider for.
+                data provider for.
 
         Returns:
             None

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/metrics/__init__.py

@@ -27,6 +27,7 @@ from .exposure import get_exposure, get_average_trade_duration, \
 from .win_rate import get_win_rate, get_win_loss_ratio
 from .calmar_ratio import get_calmar_ratio
 from .generate import create_backtest_metrics
+from .risk_free_rate import get_risk_free_rate_us
 
 __all__ = [
     "get_annual_volatility",
@@ -81,4 +82,5 @@ __all__ = [
     "create_backtest_metrics",
     "get_growth",
     "get_growth_percentage",
+    "get_risk_free_rate_us"
 ]

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/metrics/generate.py

@@ -57,7 +57,9 @@ def create_backtest_metrics(
             backtest_results.portfolio_snapshots,
             risk_free_rate=risk_free_rate
         ),
-        sortino_ratio=get_sortino_ratio(backtest_results.portfolio_snapshots),
+        sortino_ratio=get_sortino_ratio(
+            backtest_results.portfolio_snapshots, risk_free_rate=risk_free_rate
+        ),
         profit_factor=get_profit_factor(backtest_results.trades),
         calmar_ratio=get_calmar_ratio(backtest_results.portfolio_snapshots),
         annual_volatility=get_annual_volatility(

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/metrics/sharpe_ratio.py

@@ -53,12 +53,11 @@ from datetime import datetime
 
 from investing_algorithm_framework.domain import PortfolioSnapshot
 from .mean_daily_return import get_mean_daily_return
-from .risk_free_rate import get_risk_free_rate_us
 from .standard_deviation import get_daily_returns_std
 
 
 def get_sharpe_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None,
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float,
 ) -> float:
     """
     Calculate the Sharpe Ratio from a backtest report using daily or
@@ -79,9 +78,6 @@ def get_sharpe_ratio(
     mean_daily_return = get_mean_daily_return(snapshots)
     std_daily_return = get_daily_returns_std(snapshots)
 
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
-
     if std_daily_return == 0:
         return float('nan')  # Avoid division by zero
 
@@ -92,21 +88,18 @@ def get_sharpe_ratio(
 
 
 def get_rolling_sharpe_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float
 ) -> List[Tuple[float, datetime]]:
     """
     Calculate the rolling Sharpe Ratio over a 365-day window.
 
     Args:
         snapshots (List[PortfolioSnapshot]): Time-sorted list of snapshots.
-        risk_free_rate (float, optional): Annualized risk-free rate (e.g., 0.03 for 3%).
+        risk_free_rate (float): Annualized risk-free rate (e.g., 0.03 for 3%).
 
     Returns:
         List[Tuple[float, datetime]]: List of (sharpe_ratio, snapshot_date).
     """
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
-
     data = [(s.created_at, s.total_value) for s in snapshots]
     df = pd.DataFrame(data, columns=["created_at", "total_value"])
     df['created_at'] = pd.to_datetime(df['created_at'])

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/investing_algorithm_framework/services/metrics/sortino_ratio.py

@@ -30,7 +30,7 @@ from .standard_deviation import get_downside_std_of_daily_returns
 
 
 def get_sortino_ratio(
-    snapshots: List[PortfolioSnapshot], risk_free_rate: Optional[float] = None,
+    snapshots: List[PortfolioSnapshot], risk_free_rate: float
 ) -> float:
     """
     Calculate the Sortino Ratio for a given report.
@@ -46,9 +46,8 @@ def get_sortino_ratio(
     Args:
         snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
             from the backtest report.
-        risk_free_rate (float, optional): Annual risk-free rate as a decimal
-            (e.g., 0.047 for 4.7%). If not provided, defaults to the US risk-free
-            rate.
+        risk_free_rate (float): Annual risk-free rate as a decimal
+            (e.g., 0.047 for 4.7%).
 
     Returns:
         float: The Sortino Ratio.
@@ -61,9 +60,6 @@ def get_sortino_ratio(
     mean_daily_return = get_mean_daily_return(snapshots)
     std_downside_daily_return = get_downside_std_of_daily_returns(snapshots)
 
-    if risk_free_rate is None:
-        risk_free_rate = get_risk_free_rate_us()
-
     if std_downside_daily_return == 0:
         return float('nan')  # or 0.0, depending on preference
 

{investing_algorithm_framework-7.0.2 → investing_algorithm_framework-7.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "investing-algorithm-framework"
-version = "v7.0.2"
+version = "v7.1.0"
 description = "A framework for creating trading bots"
 authors = ["MDUYN"]
 readme = "README.md"