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

bbstrader/btengine/execution.py

@@ -2,15 +2,16 @@ from datetime import datetime
 from queue import Queue
 from abc import ABCMeta, abstractmethod
 from bbstrader.btengine.event import FillEvent, OrderEvent
+from bbstrader.btengine.data import DataHandler
 from bbstrader.metatrader.account import Account
+from bbstrader.config import config_logger
 
 __all__ = [
     "ExecutionHandler",
-    "SimulatedExecutionHandler",
+    "SimExecutionHandler",
     "MT5ExecutionHandler"
 ]
 
-
 class ExecutionHandler(metaclass=ABCMeta):
     """
     The ExecutionHandler abstract class handles the interaction
@@ -42,7 +43,7 @@ class ExecutionHandler(metaclass=ABCMeta):
         )
 
 
-class SimulatedExecutionHandler(ExecutionHandler):
+class SimExecutionHandler(ExecutionHandler):
     """
     The simulated execution handler simply converts all order
     objects into their equivalent fill objects automatically
@@ -53,7 +54,7 @@ class SimulatedExecutionHandler(ExecutionHandler):
     handler.
     """
 
-    def __init__(self, events: Queue, **kwargs):
+    def __init__(self, events: Queue, data: DataHandler, **kwargs):
         """
         Initialises the handler, setting the event queues
         up internally.
@@ -62,6 +63,8 @@ class SimulatedExecutionHandler(ExecutionHandler):
             events (Queue): The Queue of Event objects.
         """
         self.events = events
+        self.bardata = data
+        self.logger = kwargs.get("logger", config_logger("execution.log"))
 
     def execute_order(self, event: OrderEvent):
         """
@@ -72,51 +75,145 @@ class SimulatedExecutionHandler(ExecutionHandler):
             event (OrderEvent): Contains an Event object with order information.
         """
         if event.type == 'ORDER':
+            dtime = self.bardata.get_latest_bar_datetime(event.symbol)
             fill_event = FillEvent(
-                datetime.now(), event.symbol,
+                dtime, event.symbol,
                 'ARCA', event.quantity, event.direction, None
             )
             self.events.put(fill_event)
+            self.logger.info(
+                f"{event.direction} ORDER FILLED: SYMBOL={event.symbol}, "
+                f"QUANTITY={event.quantity}, PRICE @{event.price} EXCHANGE={fill_event.exchange}", 
+                custom_time=fill_event.timeindex
+            )
 
 
 class MT5ExecutionHandler(ExecutionHandler):
-    def __init__(self, events: Queue, **kwargs):
+    """
+    The main role of `MT5ExecutionHandler` class is to estimate the execution fees 
+    for different asset classes on the MT5 terminal. 
+    
+    Generally we have four types of fees when we execute trades using the MT5 terminal 
+    (commissions, swap, spread and other fees). But most of these fees depend on the specifications 
+    of each instrument and the duration of the transaction for the swap for example. 
+    
+    Calculating the exact fees for each instrument would be a bit complex because our Backtest engine 
+    and the Portfolio class do not take into account the duration of each trade to apply the appropriate 
+    rate for the swap for example. So we have to use only the model of calculating the commissions 
+    for each asset class and each instrument.
+    
+    The second thing that must be taken into account on MT5 is the type of account offered by the broker. 
+    Brokers have different account categories each with its specifications for each asset class and each instrument. 
+    Again considering all these conditions would make our class very complex. So we took the `Raw Spread` 
+    account fee calculation model from [Just Market](https://one.justmarkets.link/a/tufvj0xugm/registration/trader) 
+    for indicies, forex, commodities and crypto. We used the [Admiral Market](https://cabinet.a-partnership.com/visit/?bta=35537&brand=admiralmarkets) 
+    account fee calculation model from `Trade.MT5` account type for stocks and ETFs.
+
+    NOTE:
+        This class only works with `bbstrader.metatrader.data.MT5DataHandler` class.
+    """
+    def __init__(self, events: Queue, data: DataHandler, **kwargs):
         """
+        Initialises the handler, setting the event queues up internally.
+
+        Args:
+            events (Queue): The Queue of Event objects.
         """
         self.events = events
-        self.account = Account()
-
-    def _estimate_total_fees(self, symbol, lot):
-        # TODO: Implement the calculation of fees based on the broker's fees
-        # https://www.metatrader5.com/en/terminal/help/trading/market_watch
-        # Calculate fees based on the broker's fees , swap and commission
-        return 0.0
+        self.bardata = data
+        self.logger = kwargs.get("logger", config_logger("execution.log"))
+        self.__account = Account()
 
     def _calculate_lot(self, symbol, quantity, price):
-        FX = self.account.get_symbol_type(symbol) == 'FX'
-        COMD = self.account.get_symbol_type(symbol) == 'COMD'
-        FUT = self.account.get_symbol_type(symbol) == 'FUT'
-        CRYPTO = self.account.get_symbol_type(symbol) == 'CRYPTO'
-        symbol_info = self.account.get_symbol_info(symbol)
+        symbol_type = self.__account.get_symbol_type(symbol)
+        symbol_info = self.__account.get_symbol_info(symbol)
         contract_size = symbol_info.trade_contract_size
 
         lot = (quantity*price) / (contract_size * price)
         if contract_size == 1:
             lot = quantity
-        if COMD or FUT or CRYPTO and contract_size > 1:
+        if symbol_type in [
+            'COMD', 'FUT', 'CRYPTO'] and contract_size > 1:
             lot = quantity  / contract_size
-        if FX:
+        if symbol_type == 'FX':
             lot = (quantity*price / contract_size)
         return self._check_lot(symbol, lot)
 
     def _check_lot(self, symbol, lot):
-        symbol_info =  self.account.get_symbol_info(symbol)
+        symbol_info = self.__account.get_symbol_info(symbol)
         if lot < symbol_info.volume_min:
             return symbol_info.volume_min
         elif lot > symbol_info.volume_max:
             return symbol_info.volume_max
         return round(lot, 2)
     
+    def _estimate_total_fees(self, symbol, lot, qty, price):
+        symbol_type = self.__account.get_symbol_type(symbol)
+        if symbol_type in ['STK', 'ETF']:
+            return self._estimate_stock_commission(symbol, qty, price)
+        elif symbol_type == 'FX':
+            return self._estimate_forex_commission(lot)
+        elif symbol_type == 'COMD':
+            return self._estimate_commodity_commission(lot)
+        elif symbol_type == 'IDX':
+            return self._estimate_index_commission(lot)
+        elif symbol_type == 'FUT':
+            return self._estimate_futures_commission()
+        elif symbol_type == 'CRYPTO':
+            return self._estimate_crypto_commission()
+        else:
+            return 0.0
+            
+    def _estimate_stock_commission(self, symbol, qty, price):
+        # https://admiralmarkets.com/start-trading/contract-specifications?regulator=jsc
+        min_com = 1.0
+        min_aud = 8.0
+        min_dkk = 30.0
+        min_nok = min_sek = 10.0
+        us_com = 0.02 # per chare
+        ger_fr_uk_cm = 0.001 # percent
+        eu_asia_cm = 0.0015 # percent
+        if (
+            symbol in self.__account.get_stocks_from_country('USA')
+            or self.__account.get_symbol_type(symbol) == 'ETF'
+            and self.__account.get_currency_rates(symbol)['mc'] == 'USD'
+        ):
+            return max(min_com, qty * us_com)
+        elif (
+            symbol in self.__account.get_stocks_from_country('GBR')
+            or symbol in self.__account.get_stocks_from_country('FRA')
+            or symbol in self.__account.get_stocks_from_country('DEU')
+            or self.__account.get_symbol_type(symbol) == 'ETF'
+            and self.__account.get_currency_rates(symbol)['mc'] in ['GBP', 'EUR']
+        ):
+            return max(min_com, qty*price*ger_fr_uk_cm)
+        else:
+            if self.__account.get_currency_rates(symbol)['mc'] == 'AUD':
+                return max(min_aud, qty*price*eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)['mc'] == 'DKK':
+                return max(min_dkk, qty*price*eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)['mc'] == 'NOK':
+                return max(min_nok, qty*price*eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)['mc'] == 'SEK':
+                return max(min_sek, qty*price*eu_asia_cm)
+            else:
+                return max(min_com, qty*price*eu_asia_cm)
+
+    def _estimate_forex_commission(self, lot):
+        return 3.0 * lot
+
+    def _estimate_commodity_commission(self, lot):
+        return 3.0 * lot
+
+    def _estimate_index_commission(self, lot):
+        return 0.25 * lot
+
+    def _estimate_futures_commission(self):
+        return 0.0
+
+    def _estimate_crypto_commission(self):
+        return 0.0
+    
     def execute_order(self, event: OrderEvent):
         """
         Executes an Order event by converting it into a Fill event.
@@ -130,13 +227,18 @@ class MT5ExecutionHandler(ExecutionHandler):
             quantity = event.quantity
             price = event.price
             lot = self._calculate_lot(symbol, quantity, price)
-            fees = self._estimate_total_fees(symbol, lot)
+            fees = self._estimate_total_fees(symbol, lot, quantity, price)
+            dtime = self.bardata.get_latest_bar_datetime(symbol)
             fill_event = FillEvent(
-                timeindex=datetime.now(), symbol=symbol,
+                timeindex=dtime, symbol=symbol,
                 exchange='MT5', quantity=quantity, direction=direction,
                 fill_cost=None, commission=fees
             )
             self.events.put(fill_event)
+            self.logger.info(
+                f"{direction} ORDER FILLED: SYMBOL={symbol}, QUANTITY={quantity}, "
+                f"PRICE @{price} EXCHANGE={fill_event.exchange}", custom_time=fill_event.timeindex
+            )
 
 
 class IBExecutionHandler(ExecutionHandler):

bbstrader/btengine/performance.py

@@ -2,15 +2,11 @@ import numpy as np
 import pandas as pd
 import seaborn as sns
 import yfinance as yf
-
 from scipy.stats import mstats
 import matplotlib.pyplot as plt
 from matplotlib.ticker import MaxNLocator
 import quantstats as qs
 
-import warnings
-warnings.filterwarnings("ignore")
-warnings.simplefilter(action='ignore', category=FutureWarning)
 sns.set_theme()
 
 __all__ = [
@@ -53,6 +49,7 @@ def create_sortino_ratio(returns, periods=252) -> float:
     """
     return qs.stats.sortino(returns, periods=periods)
 
+
 def create_drawdowns(pnl):
     """
     Calculate the largest peak-to-trough drawdown of the PnL curve
@@ -138,7 +135,7 @@ def plot_performance(df, title):
     plt.show()
 
 
-def plot_returns_and_dd(df, benchmark: str, title):
+def plot_returns_and_dd(df: pd.DataFrame, benchmark: str, title):
     """
     Plot the returns and drawdowns of the strategy
     compared to a benchmark.
@@ -216,7 +213,7 @@ def plot_returns_and_dd(df, benchmark: str, title):
     plt.show()
 
 
-def plot_monthly_yearly_returns(df, title):
+def plot_monthly_yearly_returns(df:pd.DataFrame, title):
     """
     Plot the monthly and yearly returns of the strategy.
 
@@ -253,7 +250,7 @@ def plot_monthly_yearly_returns(df, title):
 
     # Calculate and prepare yearly returns DataFrame
     yearly_returns_df = equity_df['Total'].resample(
-        'YE').last().pct_change().to_frame(name='Yearly Returns') * 100
+        'A').last().pct_change().to_frame(name='Yearly Returns') * 100
 
     # Set the aesthetics for the plots
     sns.set_theme(style="darkgrid")

bbstrader/btengine/portfolio.py

@@ -3,17 +3,30 @@ from queue import Queue
 from pathlib import Path
 from datetime import datetime
 from bbstrader.btengine.event import (
-    OrderEvent, FillEvent, MarketEvent, SignalEvent
+    OrderEvent, 
+    FillEvent, 
+    MarketEvent, 
+    SignalEvent
 )
 from bbstrader.btengine.data import DataHandler
 from bbstrader.btengine.performance import (
-    create_drawdowns, create_sharpe_ratio, create_sortino_ratio, 
-    plot_performance, show_qs_stats,plot_returns_and_dd, 
+    create_drawdowns, 
+    create_sharpe_ratio, 
+    create_sortino_ratio, 
+    plot_performance, 
+    show_qs_stats, 
+    plot_returns_and_dd, 
     plot_monthly_yearly_returns
 )
+from bbstrader.config import BBSTRADER_DIR
 import quantstats as qs
 
 
+__all__ = [
+    'Portfolio',
+]
+
+
 class Portfolio(object):
     """
     This  describes a `Portfolio()` object that keeps track of the positions 
@@ -97,7 +110,9 @@ class Portfolio(object):
         self.timeframe = kwargs.get("time_frame", "D1")
         self.trading_hours = kwargs.get("session_duration", 6.5)
         self.benchmark = kwargs.get('benchmark', 'SPY')
+        self.output_dir = kwargs.get('output_dir', None)
         self.strategy_name = kwargs.get('strategy_name', '')
+        self.print_stats = kwargs.get('print_stats', True)
         if self.timeframe not in self._tf_mapping():
             raise ValueError(
                 f"Timeframe not supported,"
@@ -112,6 +127,7 @@ class Portfolio(object):
                                       [(s, 0) for s in self.symbol_list])
         self.all_holdings = self.construct_all_holdings()
         self.current_holdings = self.construct_current_holdings()
+        self.equity_curve = None
 
     def _tf_mapping(self):
         """
@@ -188,7 +204,7 @@ class Portfolio(object):
         for s in self.symbol_list:
             # Approximation to the real value
             market_value = self.current_positions[s] * \
-                self.bars.get_latest_bar_value(s, "Adj Close")
+                self.bars.get_latest_bar_value(s, "adj_close")
             dh[s] = market_value
             dh['Total'] += market_value
 
@@ -230,7 +246,7 @@ class Portfolio(object):
 
         # Update holdings list with new quantities
         price = self.bars.get_latest_bar_value(
-            fill.symbol, "Adj Close"
+            fill.symbol, "adj_close"
         )
         cost = fill_dir * price * fill.quantity
         self.current_holdings[fill.symbol] += cost
@@ -295,6 +311,7 @@ class Portfolio(object):
         list of dictionaries.
         """
         curve = pd.DataFrame(self.all_holdings)
+        curve['Datetime'] = pd.to_datetime(curve['Datetime'], utc=True)
         curve.set_index('Datetime', inplace=True)
         curve['Returns'] = curve['Total'].pct_change(fill_method=None)
         curve['Equity Curve'] = (1.0+curve['Returns']).cumprod()
@@ -325,20 +342,24 @@ class Portfolio(object):
         ]
         now = datetime.now().strftime('%Y%m%d%H%M%S')
         strategy_name = self.strategy_name.replace(' ', '_')
-        results_dir = Path('.backtests') / strategy_name
+        if self.output_dir:
+            results_dir = Path(self.output_dir) / strategy_name
+        else:
+            results_dir = Path('.backtests') / strategy_name
         results_dir.mkdir(parents=True, exist_ok=True)
         
-        csv_file =  f"{strategy_name}_{now}_equity.csv"
+        csv_file =  f"{strategy_name}_{now}_equities.csv"
         png_file = f'{strategy_name}_{now}_returns_heatmap.png'
         html_file = f"{strategy_name}_{now}_report.html"
         self.equity_curve.to_csv(results_dir / csv_file)
         
-        plot_performance(self.equity_curve, self.strategy_name)
-        plot_returns_and_dd(self.equity_curve, self.benchmark, self.strategy_name)
-        qs.plots.monthly_heatmap(returns, savefig=f"{results_dir}/{png_file}")
-        plot_monthly_yearly_returns(self.equity_curve, self.strategy_name)
-        show_qs_stats(returns, self.benchmark, self.strategy_name, 
-                      save_dir=f"{results_dir}/{html_file}")
+        if self.print_stats:
+            plot_performance(self.equity_curve, self.strategy_name)
+            plot_returns_and_dd(self.equity_curve, self.benchmark, self.strategy_name)
+            qs.plots.monthly_heatmap(returns, savefig=f"{results_dir}/{png_file}")
+            plot_monthly_yearly_returns(self.equity_curve, self.strategy_name)
+            show_qs_stats(returns, self.benchmark, self.strategy_name, 
+                        save_dir=f"{results_dir}/{html_file}")
 
         return stats