kissbt 0.1.5__tar.gz → 0.1.6__tar.gz

{kissbt-0.1.5 → kissbt-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: kissbt
-Version: 0.1.5
+Version: 0.1.6
 Summary: The keep it simple backtesting framework for Python.
 Author-email: Adrian Hasse <adrian.hasse@finblobs.com>
 Maintainer-email: Adrian Hasse <adrian.hasse@finblobs.com>
@@ -216,15 +216,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: scipy
 Requires-Dist: matplotlib
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: yfinance; extra == "dev"
 Requires-Dist: pyarrow; extra == "dev"
+Dynamic: license-file
 
 # kissbt
 
@@ -264,7 +265,7 @@ pip install kissbt
 To install `kissbt` via `conda`, run the following command:
 
 ```sh
-conda install kissbt
+conda install -c conda-forge kissbt
 ```
 
 ## Usage

{kissbt-0.1.5 → kissbt-0.1.6}/README.md

@@ -36,7 +36,7 @@ pip install kissbt
 To install `kissbt` via `conda`, run the following command:
 
 ```sh
-conda install kissbt
+conda install -c conda-forge kissbt
 ```
 
 ## Usage

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt/analyzer.py

@@ -2,6 +2,7 @@ from typing import Any, Dict
 
 import numpy as np
 import pandas as pd
+from scipy.stats import linregress
 
 from kissbt.broker import Broker
 
@@ -15,7 +16,13 @@ class Analyzer:
     key metrics used in financial analysis and portfolio management.
     """
 
-    def __init__(self, broker: Broker, bar_size: str = "1D") -> None:
+    def __init__(
+        self,
+        broker: Broker,
+        bar_size: str = "1D",
+        trading_hours_per_day: float = 6.5,
+        trading_days_per_year: int = 252,
+    ) -> None:
         """
         Initialize the Analyzer with a Broker instance and the bar size, which is the
         time interval of each bar in the data.
@@ -23,17 +30,29 @@ class Analyzer:
         Parameters:
             broker (Broker): The broker instance containing the trading history.
             bar_size (str): The time interval of each bar in the data, supported units
-                are 'S' for seconds, 'M' for minutes, 'H' for hours and 'D' for days
+                are 'S' for seconds, 'T' for minutes, 'H' for hours and 'D' for days
                 (default is "1D").
+            trading_hours_per_day (float): Number of trading hours per day (default is
+                6.5, which assumes US equities market hours; adjust as needed for other
+                markets).
+            trading_days_per_year (int): Number of trading days per year (default is
+                252, which assumes US equities; adjust as needed for other markets).
         """
 
         value = int(bar_size[:-1])
-        unit = bar_size[-1]
-        seconds_multiplier = {"S": 1, "M": 60, "H": 3600, "D": 3600 * 6.5}
-        if unit not in seconds_multiplier:
-            raise ValueError(f"Unsupported bar size unit: {unit}")
-        self.seconds_per_bar = value * seconds_multiplier[unit]
-        self.trading_seconds_per_year = 252 * 6.5 * 3600
+        bar_unit = bar_size[-1]
+        seconds_multiplier = {
+            "S": 1,
+            "T": 60,
+            "H": 3600,
+            "D": 3600 * trading_hours_per_day,
+        }
+        if bar_unit not in seconds_multiplier:
+            raise ValueError(f"Unsupported bar size unit: {bar_unit}")
+        self.seconds_per_bar = value * seconds_multiplier[bar_unit]
+        self.trading_seconds_per_year = (
+            trading_days_per_year * trading_hours_per_day * 3600
+        )
 
         self.broker = broker
         self.analysis_df = pd.DataFrame(self.broker.history)
@@ -50,6 +69,52 @@ class Analyzer:
                 self.analysis_df["benchmark"].cummax() - self.analysis_df["benchmark"]
             ) / self.analysis_df["benchmark"].cummax()
 
+    def _equity_curve_stats(
+        self,
+        value_series: pd.Series,
+        *,
+        prefix: str = "",
+    ) -> Dict[str, float]:
+        """
+        Calculate statistics of the equity curve based on the log-equity curve.
+        This method performs a linear regression on the log-equity curve to estimate
+        the slope, standard error, t-statistic, and R² value.
+
+        - slope: The slope of the log-equity curve, indicating the average return per
+            bar.
+        - slope_se: The standard error of the slope, indicating the variability of the
+            average return.
+        - slope_tstat: The t-statistic of the slope, indicating how strongly the data
+            supports the presence of a non-zero trend in the log-equity curve.
+        - r_squared: The R² value of the regression, indicating the proportion of
+            variance explained.
+
+        Parameters:
+            value_series (pd.Series): The series of values to analyze, typically the
+                total value of the portfolio or benchmark.
+            prefix (str): A prefix to add to the keys in the returned dictionary, useful
+                for distinguishing between portfolio and benchmark statistics.
+        """
+
+        if (value_series <= 0).any():
+            raise ValueError(
+                "Value series contains non-positive values, cannot compute log-based statistics"  # noqa: E501
+            )
+        y = np.log(value_series.to_numpy())
+        x = np.arange(y.size, dtype=float)
+
+        res = linregress(x, y)
+        slope, slope_se, r_squared = res.slope, res.stderr, res.rvalue**2
+
+        slope_tstat = slope / slope_se
+
+        return {
+            f"{prefix}slope": slope,
+            f"{prefix}slope_se": slope_se,
+            f"{prefix}slope_tstat": slope_tstat,
+            f"{prefix}r_squared": r_squared,
+        }
+
     def get_performance_metrics(self) -> Dict[str, float]:
         """
         Calculate and return key performance metrics of the trading strategy.
@@ -67,9 +132,26 @@ class Analyzer:
         - profit_factor: The profit factor of the trading strategy, a ratio of gross
             profits to gross losses.
 
-        If a benchmark is available in the data, the dictionary also includes:
-        - total_benchmark_return: The total return of the benchmark as a decimal.
-        - annual_benchmark_return: The annualized return of the benchmark as a decimal.
+        Additionally we compute the equity curve statistics for the portfolio's
+        total value, including:
+        - slope: The slope of the log-equity curve, indicating the average return per
+            bar.
+        - slope_se: The standard error of the slope, indicating the variability of the
+            average return.
+        - slope_tstat: The t-statistic of the slope (slope / slope_se), indicating how
+            strongly the data supports the presence of a non-zero trend in the
+            log-equity curve. A larger absolute value (positive or negative) provides
+            stronger evidence against H_0 (β = 0), suggesting that the observed trend is
+            unlikely to be due to random fluctuations. For typical backtests the
+            t-statistic approximately follows a standard normal distribution. Values
+            above +1.96 or below -1.96 are considered statistically significant at the
+            95% confidence level.
+        - r_squared: The R² value of the regression, indicating the proportion of
+            variance explained by the model.
+
+        If a benchmark is available in the data, the dictionary also includes the
+        total_return, annual_return, slope, slope_se, slope_tstat and r_squared for the
+        benchmark, prefixed with "benchmark_".
 
         Returns:
             Dict[str, float]: A dictionary containing the calculated performance
@@ -85,14 +167,21 @@ class Analyzer:
             "win_rate": self._calculate_win_rate(),
             "profit_factor": self._calculate_profit_factor(),
         }
+        metrics.update(self._equity_curve_stats(self.analysis_df["total_value"]))
 
         if "benchmark" in self.analysis_df.columns:
-            metrics["total_benchmark_return"] = self._calculate_total_return(
+            metrics["benchmark_total_return"] = self._calculate_total_return(
                 "benchmark"
             )
-            metrics["annual_benchmark_return"] = self._calculate_annual_return(
+            metrics["benchmark_annual_return"] = self._calculate_annual_return(
                 "benchmark"
             )
+            metrics.update(
+                self._equity_curve_stats(
+                    self.analysis_df["benchmark"],
+                    prefix="benchmark_",
+                )
+            )
 
         return metrics
 
@@ -280,14 +369,14 @@ class Analyzer:
             **kwargs(Dict[str, Any]): Additional keyword arguments to pass to the plot
                 function of pandas.
         """
-        columns_to_plot = ["date", "drawdown"]
+        columns_to_plot = ["timestamp", "drawdown"]
         if "benchmark_drawdown" in self.analysis_df.columns:
             columns_to_plot.append("benchmark_drawdown")
 
         self.analysis_df.loc[:, columns_to_plot].plot(
-            x="date",
+            x="timestamp",
             title="Portfolio Drawdown Over Time",
-            xlabel="Date",
+            xlabel="Timestamp",
             ylabel="Drawdown %",
             **kwargs,
         )
@@ -299,7 +388,7 @@ class Analyzer:
         This method creates a line plot showing the portfolio's cash, total value, and
         benchmark over time for comparison. If the benchmark is not available, it will
         plot only the available columns. If logy is True, the cash column will be
-        excluded, to focus on the total value and benchmark on logaritmic scale.
+        excluded, to focus on the total value and benchmark on logarithmic scale.
 
         Parameters:
             logy (bool): If True, use a logarithmic scale for the y-axis and exclude the
@@ -307,17 +396,52 @@ class Analyzer:
             **kwargs(Dict[str, Any]): Additional keyword arguments to pass to the plot
                 function of pandas.
         """
-        columns_to_plot = ["date", "total_value"]
+        columns_to_plot = ["timestamp", "total_value"]
         if "benchmark" in self.analysis_df.columns:
             columns_to_plot.append("benchmark")
         if not logy:
             columns_to_plot.append("cash")
 
         self.analysis_df.loc[:, columns_to_plot].plot(
-            x="date",
+            x="timestamp",
             title="Portfolio Equity Curve Over Time",
-            xlabel="Date",
+            xlabel="Timestamp",
             ylabel="Value",
             logy=logy,
             **kwargs,
         )
+
+    def plot_rolling_returns_distribution(
+        self, window_bars: int, include_benchmark: bool = True, **kwargs: Dict[str, Any]
+    ) -> None:
+        """
+        Plot box plots of rolling returns for the portfolio and optionally benchmark.
+
+        Parameters:
+            window_bars (int): Window size as number of bars.
+            include_benchmark (bool): Whether to include benchmark if available
+                (default True).
+            **kwargs (dict): Additional keyword arguments to pass to the pandas
+                DataFrame.boxplot function for customizing the appearance and behavior
+                of the box plot.
+        """
+        if window_bars >= len(self.analysis_df):
+            raise ValueError(
+                f"Window size {window_bars} is too large for the available data {len(self.analysis_df)}."  # noqa: E501
+            )
+
+        result = {
+            "Portfolio": self.analysis_df["total_value"]
+            .pct_change(periods=window_bars)
+            .dropna()
+            .reset_index(drop=True)
+        }
+        if include_benchmark and "benchmark" in self.analysis_df.columns:
+            result["Benchmark"] = (
+                self.analysis_df["benchmark"]
+                .pct_change(periods=window_bars)
+                .dropna()
+                .reset_index(drop=True)
+            )
+
+        pd.DataFrame(result).boxplot(**kwargs)

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt/broker.py

@@ -1,4 +1,3 @@
-from datetime import datetime
 from typing import Dict, List, Optional
 
 import pandas as pd
@@ -24,7 +23,7 @@ class Broker:
     Typical usage:
         broker = Broker(start_capital=100000, fees=0.001)
         broker.place_order(Order("AAPL", 100, OrderType.OPEN))
-        broker.update(next_bar, next_datetime)
+        broker.update(next_bar, next_timestamp)
     """
 
     def __init__(
@@ -64,9 +63,9 @@ class Broker:
         self._open_orders: List[Order] = []
 
         self._current_bar: pd.DataFrame = pd.DataFrame()
-        self._current_datetime = None
+        self._current_timestamp: Optional[pd.Timestamp] = None
         self._previous_bar: pd.DataFrame = pd.DataFrame()
-        self._previous_datetime = None
+        self._previous_timestamp: Optional[pd.Timestamp] = None
 
         self._long_only = long_only
         self._short_fee_rate = short_fee_rate
@@ -75,8 +74,8 @@ class Broker:
         self._benchmark = benchmark
         self._benchmark_size = 0.0
 
-        self._history: Dict[str, List[float]] = {
-            "date": [],
+        self._history: Dict[str, List[float | int | pd.Timestamp]] = {
+            "timestamp": [],
             "cash": [],
             "long_position_value": [],
             "short_position_value": [],
@@ -90,7 +89,7 @@ class Broker:
         """
         Updates the history dictionary with the current portfolio state.
         """
-        self._history["date"].append(self._current_datetime)
+        self._history["timestamp"].append(self._current_timestamp)
         self._history["cash"].append(self._cash)
         self._history["long_position_value"].append(self.long_position_value)
         self._history["short_position_value"].append(self.short_position_value)
@@ -164,7 +163,7 @@ class Broker:
             raise ValueError(f"Unknown order type {order.order_type}")
 
     def _update_closed_positions(
-        self, ticker: str, size: float, price: float, datetime: datetime
+        self, ticker: str, size: float, price: float, timestamp: pd.Timestamp
     ):
         """
         Updates the list of closed positions for a given trade.
@@ -178,7 +177,7 @@ class Broker:
             ticker (str): The ticker symbol of the position
             size (float): Position size (positive for long, negative for short)
             price (float): The current closing/reduction price
-            datetime (datetime): Timestamp of the closing/reduction
+            timestamp (timestamp): Timestamp of the closing/reduction
         """
         if (
             ticker in self._open_positions
@@ -191,9 +190,9 @@ class Broker:
                         self._open_positions[ticker].ticker,
                         min(self._open_positions[ticker].size, abs(size)),
                         self._open_positions[ticker].price,
-                        self._open_positions[ticker].datetime,
+                        self._open_positions[ticker].timestamp,
                         price,
-                        datetime,
+                        timestamp,
                     ),
                 )
             # if short position is closed/reduced
@@ -203,20 +202,20 @@ class Broker:
                         self._open_positions[ticker].ticker,
                         max(self._open_positions[ticker].size, -size),
                         price,
-                        datetime,
+                        timestamp,
                         self._open_positions[ticker].price,
-                        self._open_positions[ticker].datetime,
+                        self._open_positions[ticker].timestamp,
                     ),
                 )
 
     def _update_open_positions(
-        self, ticker: str, size: float, price: float, datetime: datetime
+        self, ticker: str, size: float, price: float, timestamp: pd.Timestamp
     ):
         """
         Updates the open positions for a given ticker.
 
         If the ticker already exists in the open positions, it updates the size, price,
-        and datetime based on the new transaction. If the size of the position becomes
+        and timestamp based on the new transaction. If the size of the position becomes
         zero, the position is removed. If the ticker does not exist, a new open position
         is created.
 
@@ -224,7 +223,8 @@ class Broker:
             ticker (str): The ticker symbol of the asset.
             size (float): The size of the position.
             price (float): The price at which the position was opened or updated.
-            datetime (datetime): The datetime when the position was opened or updated.
+            timestamp (Timestamp): The timestamp when the position was opened or
+                updated.
         """
         if ticker in self._open_positions:
             if size + self._open_positions[ticker].size == 0.0:
@@ -232,7 +232,7 @@ class Broker:
             else:
                 open_position_size = self._open_positions[ticker].size + size
                 open_position_price = price
-                open_position_datetime = datetime
+                open_position_timestamp = timestamp
 
                 if size * self._open_positions[ticker].size > 0.0:
                     open_position_price = (
@@ -240,22 +240,22 @@ class Broker:
                         * self._open_positions[ticker].price
                         + size * price
                     ) / (self._open_positions[ticker].size + size)
-                    open_position_datetime = self._open_positions[ticker].datetime
+                    open_position_timestamp = self._open_positions[ticker].timestamp
                 elif abs(self._open_positions[ticker].size) > abs(size):
-                    open_position_datetime = self._open_positions[ticker].datetime
+                    open_position_timestamp = self._open_positions[ticker].timestamp
                     open_position_price = self._open_positions[ticker].price
                 self._open_positions[ticker] = OpenPosition(
                     ticker,
                     open_position_size,
                     open_position_price,
-                    open_position_datetime,
+                    open_position_timestamp,
                 )
         else:
             self._open_positions[ticker] = OpenPosition(
                 ticker,
                 size,
                 price,
-                datetime,
+                timestamp,
             )
 
     def _update_cash(self, order: Order, price: float):
@@ -272,29 +272,29 @@ class Broker:
         else:
             self._cash -= order.size * price * (1.0 - self._fees)
 
-    def _check_long_only_condition(self, order: Order, datetime: datetime):
+    def _check_long_only_condition(self, order: Order, timestamp: pd.Timestamp):
         size = order.size
         if order.ticker in self._open_positions:
             size += self._open_positions[order.ticker].size
 
         if size < 0.0:
             raise ValueError(
-                f"Short selling is not allowed for {order.ticker} on {datetime}."
+                f"Short selling is not allowed for {order.ticker} on {timestamp}."
             )
 
     def _execute_order(
         self,
         order: Order,
         bar: pd.DataFrame,
-        datetime: datetime,
+        timestamp: pd.Timestamp,
     ) -> bool:
         """
-        Executes an order based on the provided bar data and datetime.
+        Executes an order based on the provided bar data and timestamp.
 
         Args:
             order (Order): The order to be executed.
             bar (pd.DataFrame): The bar data containing price information.
-            datetime (datetime): The datetime at which the order is executed.
+            timestamp (Timestamp): The timestamp at which the order is executed.
 
         Returns:
             bool: True if the order was successfully executed, False otherwise.
@@ -308,7 +308,7 @@ class Broker:
             return False
 
         if self._long_only:
-            self._check_long_only_condition(order, datetime)
+            self._check_long_only_condition(order, timestamp)
 
         price = self._get_price_for_order(order, bar)
 
@@ -319,16 +319,16 @@ class Broker:
         # update cash for long and short positions
         self._update_cash(order, price)
 
-        self._update_closed_positions(ticker, order.size, price, datetime)
+        self._update_closed_positions(ticker, order.size, price, timestamp)
 
-        self._update_open_positions(ticker, order.size, price, datetime)
+        self._update_open_positions(ticker, order.size, price, timestamp)
 
         return True
 
     def update(
         self,
         next_bar: pd.DataFrame,
-        next_datetime: pd.Timestamp,
+        next_timestamp: pd.Timestamp,
     ):
         """
         Updates the broker's state with the next trading bar and executes pending
@@ -344,7 +344,7 @@ class Broker:
         Args:
             next_bar (pd.DataFrame): The next trading bar data containing at minimum
                 'close' prices for assets
-            next_datetime (pd.Timestamp): The timestamp for the next trading bar
+            next_timestamp (pd.Timestamp): The timestamp for the next trading bar
 
         Notes:
             - Short fees are calculated using the current bar's closing price
@@ -354,9 +354,9 @@ class Broker:
             - Good-till-cancel orders that aren't filled are retained for the next bar
         """
         self._previous_bar = self._current_bar
-        self._previous_datetime = self._current_datetime
+        self._previous_timestamp = self._current_timestamp
         self._current_bar = next_bar
-        self._current_datetime = next_datetime
+        self._current_timestamp = next_timestamp
 
         # consider short fees
         if not self._long_only:
@@ -384,7 +384,7 @@ class Broker:
                 self._execute_order(
                     Order(ticker, -self._open_positions[ticker].size, OrderType.CLOSE),
                     self._previous_bar,
-                    self._previous_datetime,
+                    self._previous_timestamp,
                 )
 
         # buy and sell assets
@@ -396,16 +396,18 @@ class Broker:
             if open_order.ticker in ticker_not_available:
                 if open_order.size > 0:
                     print(
-                        f"{open_order.ticker} could not be bought on {self._current_datetime}."  # noqa: E501
+                        f"{open_order.ticker} could not be bought on {self._current_timestamp}."  # noqa: E501
                     )
                 else:
                     print(
-                        f"{open_order.ticker} could not be sold on {self._current_datetime}."  # noqa: E501
+                        f"{open_order.ticker} could not be sold on {self._current_timestamp}."  # noqa: E501
                     )
                 continue
             if (
                 not self._execute_order(
-                    open_order, self._current_bar, self._current_datetime
+                    open_order,
+                    self._current_bar,
+                    self._current_timestamp,
                 )
                 and open_order.good_till_cancel
             ):
@@ -437,7 +439,7 @@ class Broker:
             self._execute_order(
                 Order(ticker, -self._open_positions[ticker].size, OrderType.CLOSE),
                 self._current_bar,
-                self._current_datetime,
+                self._current_timestamp,
             )
 
     def place_order(self, order: Order):
@@ -522,7 +524,7 @@ class Broker:
         - ticker: Financial instrument identifier
         - size: Position size (positive=long, negative=short)
         - price: Average entry price
-        - datetime: Position opening timestamp
+        - timestamp: Position opening timestamp
 
         Returns:
             Dict[str, OpenPosition]: Dictionary mapping ticker symbols to positions.
@@ -578,13 +580,14 @@ class Broker:
         return self._cash
 
     @property
-    def benchmark(self) -> str:
+    def benchmark(self) -> Optional[str]:
         """Gets the benchmark symbol used for performance comparison.
 
         The benchmark tracks a reference asset (e.g., market index) to evaluate relative
         strategy performance. Returns None if no benchmark was specified.
 
         Returns:
-            str: Ticker symbol of the benchmark instrument.
+            Optional[str]: Ticker symbol of the benchmark instrument, or None if not
+                set.
         """
         return self._benchmark

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt/engine.py

@@ -20,10 +20,10 @@ class Engine:
         self.strategy = strategy
 
     def run(self, data: pd.DataFrame) -> None:
-        for current_date, current_data in data.groupby("date"):
-            current_data.index = current_data.index.droplevel("date")
+        for current_timestamp, current_data in data.groupby("timestamp"):
+            current_data.index = current_data.index.droplevel("timestamp")
 
-            self.broker.update(current_data, current_date)
-            self.strategy(current_data, current_date)
+            self.broker.update(current_data, current_timestamp)
+            self.strategy.generate_orders(current_data, current_timestamp)
 
         self.broker.liquidate_positions()

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt/entities.py

@@ -39,13 +39,13 @@ class OpenPosition:
         ticker (str): Financial instrument identifier
         size (float): Position size (positive for long, negative for short)
         price (float): Opening price of the position
-        datetime (datetime): Position opening timestamp
+        timestamp (pd.Timestamp): Position opening timestamp
     """
 
     ticker: str
     size: float
     price: float
-    datetime: pd.Timestamp
+    timestamp: pd.Timestamp
 
 
 @dataclass(frozen=True)
@@ -57,14 +57,14 @@ class ClosedPosition:
         ticker (str): Financial instrument identifier
         size (float): Position size (positive for long, negative for short)
         purchase_price (float): Entry price of the position
-        purchase_datetime (pd.Timestamp): Position entry timestamp
+        purchase_timestamp (pd.Timestamp): Position entry timestamp
         selling_price (float): Exit price of the position
-        selling_datetime (pd.Timestamp): Position exit timestamp
+        selling_timestamp (pd.Timestamp): Position exit timestamp
     """
 
     ticker: str
     size: float
     purchase_price: float
-    purchase_datetime: pd.Timestamp
+    purchase_timestamp: pd.Timestamp
     selling_price: float
-    selling_datetime: pd.Timestamp
+    selling_timestamp: pd.Timestamp

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt/strategy.py

@@ -49,7 +49,7 @@ class Strategy(ABC):
     def generate_orders(
         self,
         current_data: pd.DataFrame,
-        current_datetime: pd.Timestamp,
+        current_timestamp: pd.Timestamp,
     ) -> None:
         """
         Generate trading orders based on current market data and indicators.
@@ -71,7 +71,7 @@ class Strategy(ABC):
                 - volume: Trading volume
                 - [custom]: Any additional indicators added during data preparation
 
-            current_datetime: Timestamp of the current bar, e.g. used for order timing
+            current_timestamp: Timestamp of the current bar, e.g. used for order timing
 
         Returns:
             None
@@ -80,7 +80,7 @@ class Strategy(ABC):
             - Orders are placed through the _broker instance using methods like:
               create_market_order(), create_limit_order()
             - Position and portfolio information can be accessed through the _broker
-            - Avoid look-ahead bias by only using data available at current_datetime
+            - Avoid look-ahead bias by only using data available at current_timestamp
             - All orders are processed at the next bar's prices (which price depends on
               the order type)
 

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: kissbt
-Version: 0.1.5
+Version: 0.1.6
 Summary: The keep it simple backtesting framework for Python.
 Author-email: Adrian Hasse <adrian.hasse@finblobs.com>
 Maintainer-email: Adrian Hasse <adrian.hasse@finblobs.com>
@@ -216,15 +216,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: scipy
 Requires-Dist: matplotlib
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: yfinance; extra == "dev"
 Requires-Dist: pyarrow; extra == "dev"
+Dynamic: license-file
 
 # kissbt
 
@@ -264,7 +265,7 @@ pip install kissbt
 To install `kissbt` via `conda`, run the following command:
 
 ```sh
-conda install kissbt
+conda install -c conda-forge kissbt
 ```
 
 ## Usage

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ kissbt.egg-info/SOURCES.txt
 kissbt.egg-info/dependency_links.txt
 kissbt.egg-info/requires.txt
 kissbt.egg-info/top_level.txt
+tests/test_analyzer.py
 tests/test_broker.py
 tests/test_entities.py
 tests/test_integration.py

{kissbt-0.1.5 → kissbt-0.1.6}/kissbt.egg-info/requires.txt

@@ -1,12 +1,12 @@
 numpy
 pandas
+scipy
 matplotlib
 
 [dev]
 pytest
 pytest-mock
-flake8
-black
-isort
+ruff
+mypy
 yfinance
 pyarrow

{kissbt-0.1.5 → kissbt-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kissbt"
-version = "0.1.5"
+version = "0.1.6"
 description = "The keep it simple backtesting framework for Python."
 readme = "README.md"
 authors = [
@@ -22,6 +22,7 @@ classifiers = [
 dependencies = [
     "numpy",
     "pandas",
+    "scipy",
     "matplotlib"
 ]
 requires-python = ">=3.10"
@@ -30,9 +31,8 @@ requires-python = ">=3.10"
 dev = [
     "pytest",
     "pytest-mock",
-    "flake8",
-    "black",
-    "isort",
+    "ruff",
+    "mypy",
     "yfinance",
     "pyarrow",
 ]
@@ -41,21 +41,39 @@ dev = [
 homepage = "https://github.com/FinBlobs/kissbt"
 bug-tracker = "https://github.com/FinBlobs/kissbt/issues"
 
-[tool.black]
+[tool.ruff]
 line-length = 88
-target-version = ['py310']
-include = '\.pyi?$'
+target-version = "py310"
+src = ["kissbt", "tests"]
+exclude = [
+    ".git",
+    "__pycache__",
+    "build", 
+    "dist",
+    "examples",
+]
+
+[tool.ruff.lint]
+# Start with core rules equivalent to the original flake8 setup
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings  
+    "F",   # pyflakes
+    "I",   # isort
+]
+# TODO: Gradually add more rules like N, UP, C4, B
 
-[tool.isort]
-profile = "black"
-line_length = 88
-multi_line_output = 3
-include_trailing_comma = true
-force_grid_wrap = 0
-use_parentheses = true
-ensure_newline_before_comments = true
+[tool.ruff.format]
+# Enable Black-compatible formatting
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
 
-[tool.flake8]
-max-line-length = 88
-extend-ignore = ["E203"]
-exclude = [".git", "__pycache__", "build", "dist"]
+[tool.mypy]
+python_version = "3.10"
+# Start with basic type checking, will enable strict mode later
+warn_return_any = false
+warn_unused_configs = true
+show_error_codes = true
+ignore_missing_imports = true

kissbt-0.1.6/tests/test_analyzer.py

@@ -0,0 +1,61 @@
+import numpy as np
+import pandas as pd
+import pytest
+from kissbt.analyzer import Analyzer
+from kissbt.broker import Broker
+
+
+def test_constant_growth_benchmark_stats():
+    daily_return = 0.0001
+    num_days = 252
+    start_value = 100000.0
+    values = [start_value * (1 + daily_return) ** i for i in range(num_days)]
+
+    broker = Broker(benchmark="constant_growth")
+    for i, val in enumerate(values):
+        ts = pd.Timestamp("2023-01-01") + pd.Timedelta(days=i)
+        broker.history["timestamp"].append(ts)
+        broker.history["total_value"].append(start_value)
+        broker.history["benchmark"].append(val)
+        broker.history["cash"].append(0)
+        broker.history["long_position_value"].append(0)
+        broker.history["short_position_value"].append(0)
+        broker.history["positions"].append({})
+
+    analyzer = Analyzer(broker)
+    metrics = analyzer.get_performance_metrics()
+
+    assert abs(metrics["benchmark_slope"] - np.log(1 + daily_return)) < 1e-10
+    assert metrics["benchmark_slope_se"] < 1e-10
+    assert metrics["benchmark_slope_tstat"] > 1e5
+    assert metrics["benchmark_r_squared"] > 0.9999
+
+
+def test_portfolio_equity_curve_stats_with_volatility():
+    np.random.seed(42)
+    num_days = 256 * 3
+    start_value = 100000.0
+
+    # Generate portfolio values with some volatility
+    daily_returns = np.random.normal(0.001, 0.02, num_days)
+    portfolio_values = [start_value]
+    for ret in daily_returns:
+        portfolio_values.append(portfolio_values[-1] * (1 + ret))
+
+    broker = Broker()
+    for i, val in enumerate(portfolio_values):
+        ts = pd.Timestamp("2023-01-01") + pd.Timedelta(days=i)
+        broker.history["timestamp"].append(ts)
+        broker.history["total_value"].append(val)
+        broker.history["cash"].append(0)
+        broker.history["long_position_value"].append(val)
+        broker.history["short_position_value"].append(0)
+        broker.history["positions"].append({})
+
+    analyzer = Analyzer(broker)
+    metrics = analyzer.get_performance_metrics()
+
+    assert metrics["slope"] == pytest.approx(0.001, abs=0.0005)
+    assert metrics["slope_se"] > 0
+    assert metrics["slope_tstat"] > 1.96
+    assert 0.5 < metrics["r_squared"] < 0.9

{kissbt-0.1.5 → kissbt-0.1.6}/tests/test_broker.py

@@ -1,8 +1,5 @@
-from datetime import datetime
-
 import pandas as pd
 import pytest
-
 from kissbt.broker import Broker
 from kissbt.entities import OpenPosition, Order, OrderType
 
@@ -14,7 +11,7 @@ def test_initial_broker_state(broker):
     assert broker.closed_positions == []
     assert broker.history == {
         "cash": [],
-        "date": [],
+        "timestamp": [],
         "long_position_value": [],
         "positions": [],
         "short_position_value": [],
@@ -35,7 +32,7 @@ def test_execute_order(broker, mocker):
     broker._execute_order(
         order,
         bar=pd.DataFrame({"open": [150.0], "close": [152.0]}, index=["AAPL"]),
-        datetime=datetime.now(),
+        timestamp=pd.Timestamp.now(),
     )
     assert broker.cash == 100000 - (10 * 150 * 1.001)
     assert len(broker.open_positions) == 1
@@ -53,17 +50,17 @@ def test_update_open_positions(broker):
     assert broker._execute_order(
         order,
         bar=pd.DataFrame({"open": [150.0], "close": [152.0]}, index=["AAPL"]),
-        datetime=datetime.now(),
+        timestamp=pd.Timestamp.now(),
     )
     assert len(broker.open_positions) == 1
     assert "AAPL" in broker.open_positions
 
 
 def test_update_closed_positions(broker):
-    position = OpenPosition("AAPL", 10, 150.0, datetime.now())
+    position = OpenPosition("AAPL", 10, 150.0, pd.Timestamp.now())
     broker._open_positions["AAPL"] = position
     broker._update_closed_positions(
-        position.ticker, -position.size, position.price, position.datetime
+        position.ticker, -position.size, position.price, position.timestamp
     )
     assert len(broker.closed_positions) == 1
     assert broker.closed_positions[0].ticker == "AAPL"
@@ -72,14 +69,14 @@ def test_update_closed_positions(broker):
 def test_liquidate_positions(broker):
     order = Order("AAPL", 10, OrderType.OPEN)
     bar = pd.DataFrame({"open": [150.0], "close": [152.0]}, index=["AAPL"])
-    time = datetime.now()
+    time = pd.Timestamp.now()
     broker._execute_order(
         order,
         bar=bar,
-        datetime=time,
+        timestamp=time,
     )
     broker._current_bar = bar
-    broker._current_datetime = time
+    broker._current_timestamp = time
     broker.liquidate_positions()
 
     assert broker.open_positions == {}
@@ -87,14 +84,16 @@ def test_liquidate_positions(broker):
     assert broker.closed_positions[0].ticker == "AAPL"
     assert broker.closed_positions[0].size == 10
     assert broker.closed_positions[0].purchase_price == 150.0
-    assert broker.closed_positions[0].purchase_datetime == time
+    assert broker.closed_positions[0].purchase_timestamp == time
     assert broker.closed_positions[0].selling_price == 152.0
-    assert broker.closed_positions[0].selling_datetime == time
+    assert broker.closed_positions[0].selling_timestamp == time
 
 
 # --- Testing Portfolio Metrics ---
 def test_long_position_value(broker):
-    broker._open_positions = {"AAPL": OpenPosition("AAPL", 10, 150.0, datetime.now())}
+    broker._open_positions = {
+        "AAPL": OpenPosition("AAPL", 10, 150.0, pd.Timestamp.now())
+    }
     broker._current_bar = pd.DataFrame(
         {"open": [150.0], "close": [152.0]}, index=["AAPL"]
     )
@@ -104,7 +103,9 @@ def test_long_position_value(broker):
 
 
 def test_short_position_value(broker):
-    broker._open_positions = {"AAPL": OpenPosition("AAPL", -10, 150.0, datetime.now())}
+    broker._open_positions = {
+        "AAPL": OpenPosition("AAPL", -10, 150.0, pd.Timestamp.now())
+    }
     broker._current_bar = pd.DataFrame(
         {"open": [150.0], "close": [152.0]}, index=["AAPL"]
     )
@@ -118,7 +119,7 @@ def test_execute_order_open(broker, mocker):
     executed = broker._execute_order(
         order,
         bar=pd.DataFrame({"open": [150.0], "close": [152.0]}, index=["AAPL"]),
-        datetime=datetime.now(),
+        timestamp=pd.Timestamp.now(),
     )
     assert executed
     assert broker.cash == 98498.5
@@ -129,12 +130,12 @@ def test_execute_order_open(broker, mocker):
 def test_execute_order_close(broker):
     order = Order("AAPL", -10, OrderType.CLOSE)
     bar = pd.DataFrame({"open": [150.0], "close": [152.0]}, index=["AAPL"])
-    broker._open_positions["AAPL"] = OpenPosition("AAPL", 10, 150.0, datetime.now())
+    broker._open_positions["AAPL"] = OpenPosition("AAPL", 10, 150.0, pd.Timestamp.now())
     broker._current_bar = bar
     executed = broker._execute_order(
         order,
         bar=bar,
-        datetime=datetime.now(),
+        timestamp=pd.Timestamp.now(),
     )
     assert executed
     assert float(broker.cash) == 100000 + 10 * 152 * 0.999
@@ -154,8 +155,8 @@ def test_place_multiple_orders(broker):
 
 def test_portfolio_value_with_positions(broker):
     broker._open_positions = {
-        "AAPL": OpenPosition("AAPL", 10, 150.0, datetime.now()),
-        "GOOG": OpenPosition("GOOG", -5, 1000.0, datetime.now()),
+        "AAPL": OpenPosition("AAPL", 10, 150.0, pd.Timestamp.now()),
+        "GOOG": OpenPosition("GOOG", -5, 1000.0, pd.Timestamp.now()),
     }
     broker._current_bar = pd.DataFrame(
         {"close": [152.0, 995.0]}, index=["AAPL", "GOOG"]
@@ -164,18 +165,18 @@ def test_portfolio_value_with_positions(broker):
 
 
 def test_update_history(broker):
-    broker._current_datetime = datetime.now()
+    broker._current_timestamp = pd.Timestamp.now()
     broker._cash = 100000
     broker._open_positions = {
-        "AAPL": OpenPosition("AAPL", 10, 150.0, datetime.now()),
-        "GOOG": OpenPosition("GOOG", -5, 1000.0, datetime.now()),
+        "AAPL": OpenPosition("AAPL", 10, 150.0, pd.Timestamp.now()),
+        "GOOG": OpenPosition("GOOG", -5, 1000.0, pd.Timestamp.now()),
     }
     broker._current_bar = pd.DataFrame(
         {"close": [152.0, 995.0]}, index=["AAPL", "GOOG"]
     )
     broker._update_history()
     history = broker.history
-    assert len(history["date"]) == 1
+    assert len(history["timestamp"]) == 1
     assert len(history["cash"]) == 1
     assert len(history["long_position_value"]) == 1
     assert len(history["short_position_value"]) == 1
@@ -227,9 +228,9 @@ def test_invalid_order_type(broker):
 
 def test_position_update(broker):
     broker._open_positions["AAPL"] = OpenPosition(
-        ticker="AAPL", size=5, price=100, datetime=datetime(2024, 1, 1)
+        ticker="AAPL", size=5, price=100, timestamp=pd.Timestamp(2024, 1, 1)
     )
-    broker._update_open_positions("AAPL", 10, 110, datetime(2024, 1, 2))
+    broker._update_open_positions("AAPL", 10, 110, pd.Timestamp(2024, 1, 2))
     assert broker._open_positions["AAPL"].size == 15
     assert broker._open_positions["AAPL"].price == pytest.approx(
         (5 * 100 + 10 * 110) / 15
@@ -240,11 +241,11 @@ def test_short_position_fees(broker, mocker):
     broker._long_only = False
     broker._current_bar = pd.DataFrame({"close": [100]}, index=["AAPL"])
     broker._open_positions["AAPL"] = OpenPosition(
-        ticker="AAPL", size=-10, price=105, datetime=datetime(2024, 1, 1)
+        ticker="AAPL", size=-10, price=105, timestamp=pd.Timestamp(2024, 1, 1)
     )
     next_bar = pd.DataFrame({"close": [100]}, index=["AAPL"])
-    next_datetime = pd.Timestamp("2024-01-02")
-    broker.update(next_bar, next_datetime)
+    next_timestamp = pd.Timestamp("2024-01-02")
+    broker.update(next_bar, next_timestamp)
     assert broker.cash < 100000  # Short fee applied
 
 
@@ -291,15 +292,15 @@ def test_check_long_only_blocks_short_orders(broker):
     broker._long_only = True
     order = Order("AAPL", -10, OrderType.OPEN)
     with pytest.raises(ValueError):
-        broker._check_long_only_condition(order, datetime.now())
+        broker._check_long_only_condition(order, pd.Timestamp.now())
 
 
 def test_check_long_only_condition(broker):
-    time = datetime.now()
+    time = pd.Timestamp.now()
     broker._current_bar = pd.DataFrame(
         {"open": [150.0], "close": [152.0]}, index=["AAPL"]
     )
-    broker._current_datetime = time
+    broker._current_timestamp = time
     order = Order("AAPL", -10, order_type=OrderType.OPEN)
     with pytest.raises(ValueError):
         broker._check_long_only_condition(order, time)
@@ -308,11 +309,11 @@ def test_check_long_only_condition(broker):
 def test_update_with_short_fees(broker):
     broker._long_only = False
     broker._open_positions["AAPL"] = OpenPosition(
-        "AAPL", -10, 100, datetime(2024, 1, 1)
+        "AAPL", -10, 100, pd.Timestamp(2024, 1, 1)
     )
     next_bar = pd.DataFrame({"close": [100]}, index=["AAPL"])
-    next_datetime = pd.Timestamp("2024-01-02")
-    broker.update(next_bar, next_datetime)
+    next_timestamp = pd.Timestamp("2024-01-02")
+    broker.update(next_bar, next_timestamp)
     assert broker.cash < 100000  # Short fee applied
 
 
@@ -343,8 +344,10 @@ def test_update_cash(broker):
 def test_update_open_positions_cases(
     broker, size_change, expected_size, expected_price
 ):
-    broker._open_positions["AAPL"] = OpenPosition("AAPL", 10, 100, datetime(2024, 1, 1))
-    broker._update_open_positions("AAPL", size_change, 110, datetime(2024, 1, 2))
+    broker._open_positions["AAPL"] = OpenPosition(
+        "AAPL", 10, 100, pd.Timestamp(2024, 1, 1)
+    )
+    broker._update_open_positions("AAPL", size_change, 110, pd.Timestamp(2024, 1, 2))
 
     if expected_size is None:
         assert "AAPL" not in broker._open_positions
@@ -354,14 +357,18 @@ def test_update_open_positions_cases(
 
 
 def test_update_ticker_out_of_universe(broker):
-    broker._open_positions["AAPL"] = OpenPosition("AAPL", 10, 100, datetime(2024, 1, 1))
+    broker._open_positions["AAPL"] = OpenPosition(
+        "AAPL", 10, 100, pd.Timestamp(2024, 1, 1)
+    )
 
     broker.update(
         pd.DataFrame({"close": [100, 500]}, index=["GOOG", "AAPL"]),
-        datetime(2024, 1, 2),
+        pd.Timestamp(2024, 1, 2),
     )
 
-    broker.update(pd.DataFrame({"close": [110]}, index=["GOOG"]), datetime(2024, 1, 3))
+    broker.update(
+        pd.DataFrame({"close": [110]}, index=["GOOG"]), pd.Timestamp(2024, 1, 3)
+    )
 
     assert len(broker._closed_positions) == 1
     closed_pos = broker._closed_positions[0]
@@ -369,5 +376,5 @@ def test_update_ticker_out_of_universe(broker):
     assert closed_pos.size == 10
     assert closed_pos.purchase_price == 100
     assert closed_pos.selling_price == 500
-    assert closed_pos.purchase_datetime == datetime(2024, 1, 1)
-    assert closed_pos.selling_datetime == datetime(2024, 1, 2)
+    assert closed_pos.purchase_timestamp == pd.Timestamp(2024, 1, 1)
+    assert closed_pos.selling_timestamp == pd.Timestamp(2024, 1, 2)

{kissbt-0.1.5 → kissbt-0.1.6}/tests/test_entities.py

@@ -1,7 +1,4 @@
-from datetime import datetime
-
 import pandas as pd
-
 from kissbt.entities import OpenPosition, Order, OrderType
 
 
@@ -30,10 +27,10 @@ def test_order_defaults():
 
 
 def test_open_position_creation():
-    entry_time = pd.Timestamp(datetime(2024, 1, 1, 10, 30, 0))
-    position = OpenPosition(ticker="MSFT", size=50, price=250.0, datetime=entry_time)
+    entry_time = pd.Timestamp(2024, 1, 1, 10, 30, 0)
+    position = OpenPosition(ticker="MSFT", size=50, price=250.0, timestamp=entry_time)
 
     assert position.ticker == "MSFT"
     assert position.size == 50
     assert position.price == 250.0
-    assert position.datetime == entry_time
+    assert position.timestamp == entry_time

{kissbt-0.1.5 → kissbt-0.1.6}/tests/test_integration.py

@@ -1,6 +1,5 @@
 import pandas as pd
 import pytest
-
 from kissbt.analyzer import Analyzer
 from kissbt.broker import Broker
 from kissbt.engine import Engine
@@ -15,7 +14,7 @@ class GoldenCrossStrategy(Strategy):
     def generate_orders(
         self,
         current_data: pd.DataFrame,
-        current_date: pd.Timestamp,
+        current_timestamp: pd.Timestamp,
     ) -> None:
         for ticker in self._broker.open_positions:
             if (
@@ -66,9 +65,9 @@ def test_analyzer_with_golden_cross(tech_stock_data):
     assert len(broker.open_positions) == 0, "All positions should be closed"
     assert pytest.approx(broker.cash, 0.01) == 167534.46, "Final cash manually verified"
     assert pytest.approx(broker.portfolio_value, 0.01) == 167534.46
-    assert (
-        len(broker.closed_positions) == 15
-    ), "15 trades should have been executed, manually verified"
+    assert len(broker.closed_positions) == 15, (
+        "15 trades should have been executed, manually verified"
+    )
 
     # Create the Analyzer
     analyzer = Analyzer(broker, bar_size="1D")
@@ -99,9 +98,10 @@ def test_analyzer_with_golden_cross(tech_stock_data):
     assert pytest.approx(metrics["volatility"], abs=0.01) == 0.24
     assert pytest.approx(metrics["win_rate"], abs=0.01) == 0.47
     assert pytest.approx(metrics["profit_factor"], abs=0.01) == 3.17
-    assert pytest.approx(metrics["total_benchmark_return"], abs=0.01) == 0.29
-    assert pytest.approx(metrics["annual_benchmark_return"], abs=0.01) == 0.09
+    assert pytest.approx(metrics["benchmark_total_return"], abs=0.01) == 0.29
+    assert pytest.approx(metrics["benchmark_annual_return"], abs=0.01) == 0.09
 
     # Ensure running the plot functions does not raise an exception
     analyzer.plot_equity_curve()
     analyzer.plot_drawdowns()
+    analyzer.plot_rolling_returns_distribution(252)

{kissbt-0.1.5 → kissbt-0.1.6}/tests/test_strategy.py

@@ -1,6 +1,5 @@
 import pandas as pd
 import pytest
-
 from kissbt.broker import Broker
 from kissbt.entities import Order
 from kissbt.strategy import Strategy
@@ -8,7 +7,7 @@ from kissbt.strategy import Strategy
 
 class DummyStrategy(Strategy):
     def generate_orders(
-        self, current_data: pd.DataFrame, current_datetime: pd.Timestamp
+        self, current_data: pd.DataFrame, current_timestamp: pd.Timestamp
     ) -> None:
         for ticker in current_data.index:
             if current_data.loc[ticker, "close"] > 100: