investing-algorithm-framework 1.3.1__py3-none-any.whl → 7.25.6__py3-none-any.whl

investing_algorithm_framework/__init__.py

@@ -1,28 +1,72 @@
-from investing_algorithm_framework.app import App
+from .analysis import generate_rolling_backtest_windows, \
+    select_backtest_date_ranges, rank_results, create_weights, \
+    get_missing_timeseries_data_entries, fill_missing_timeseries_data, \
+    create_markdown_table
+from .app import App, Algorithm, \
+    TradingStrategy, StatelessAction, Task, AppHook, Context, \
+    add_html_report, BacktestReport, \
+    pretty_print_trades, pretty_print_positions, \
+    pretty_print_orders, pretty_print_backtest, \
+    get_equity_curve_with_drawdown_chart, \
+    get_rolling_sharpe_ratio_chart, get_monthly_returns_heatmap_chart, \
+    get_yearly_returns_bar_chart, get_entry_and_exit_signals, \
+    get_ohlcv_data_completeness_chart, get_equity_curve_chart
+from .domain import ApiException, combine_backtests, PositionSize, \
+    OrderType, OperationalException, OrderStatus, OrderSide, tqdm, \
+    TimeUnit, TimeInterval, Order, Portfolio, Backtest, DataError, \
+    Position, TimeFrame, INDEX_DATETIME, MarketCredential, TakeProfitRule, \
+    PortfolioConfiguration, RESOURCE_DIRECTORY, AWS_LAMBDA_LOGGING_CONFIG, \
+    Trade, APP_MODE, AppMode, DATETIME_FORMAT, load_backtests_from_directory, \
+    BacktestDateRange, convert_polars_to_pandas, BacktestRun, \
+    DEFAULT_LOGGING_CONFIG, DataType, DataProvider, StopLossRule, \
+    TradeStatus, generate_backtest_summary_metrics, generate_algorithm_id, \
+    APPLICATION_DIRECTORY, DataSource, OrderExecutor, PortfolioProvider, \
+    SnapshotInterval, AWS_S3_STATE_BUCKET_NAME, BacktestEvaluationFocus, \
+    save_backtests_to_directory, BacktestMetrics
+from .infrastructure import AzureBlobStorageStateHandler, \
+    CSVOHLCVDataProvider, CCXTOHLCVDataProvider, PandasOHLCVDataProvider, \
+    AWSS3StorageStateHandler
 from .create_app import create_app
-from investing_algorithm_framework.domain import ApiException, \
-    TradingDataType, OrderBook, Ticker, TradingTimeFrame, OHLCV, OrderType,\
-    OrderStatus, OrderSide, Config, TimeUnit, TimeInterval, Order, Portfolio, \
-    Position
-from investing_algorithm_framework.domain import PortfolioConfiguration, \
-    RESOURCE_DIRECTORY
-from investing_algorithm_framework.app import TradingStrategy, \
-    StatelessAction, Task
+from .download_data import download, download_v2, DownloadResult, \
+    create_data_storage_path
+from .services import get_annual_volatility, get_sortino_ratio, \
+    get_drawdown_series, get_max_drawdown, get_equity_curve, \
+    get_price_efficiency_ratio, get_sharpe_ratio, \
+    get_profit_factor, get_cumulative_profit_factor_series, \
+    get_rolling_profit_factor_series, get_cagr, \
+    get_standard_deviation_returns, get_standard_deviation_downside_returns, \
+    get_max_drawdown_absolute, get_total_return, get_exposure_ratio, \
+    get_average_trade_duration, get_win_rate, get_win_loss_ratio, \
+    get_calmar_ratio, get_trade_frequency, get_yearly_returns, \
+    get_monthly_returns, get_best_year, get_best_month, get_worst_year, \
+    get_worst_month, get_best_trade, get_worst_trade, \
+    get_average_yearly_return, get_average_trade_gain, \
+    get_average_trade_loss, get_average_monthly_return, \
+    get_percentage_winning_months, get_max_drawdown_duration, \
+    get_max_daily_drawdown, get_trades_per_day, \
+    get_trades_per_year, get_average_monthly_return_losing_months, \
+    get_average_monthly_return_winning_months, get_percentage_winning_years, \
+    get_rolling_sharpe_ratio, create_backtest_metrics, get_total_growth, \
+    get_total_loss, get_cumulative_exposure, get_median_trade_return, \
+    get_average_trade_return, get_risk_free_rate_us, get_cumulative_return, \
+    get_cumulative_return_series, get_current_average_trade_return, \
+    get_current_average_trade_gain, get_current_average_trade_duration, \
+    get_current_average_trade_loss, get_negative_trades, \
+    get_positive_trades, get_number_of_trades, get_current_win_rate, \
+    get_current_win_loss_ratio, create_backtest_metrics_for_backtest, \
+    TradeTakeProfitService, TradeStopLossService
+
 
 __all__ = [
+    "Algorithm",
     "RESOURCE_DIRECTORY",
     "App",
+    "AppHook",
     "create_app",
     "ApiException",
-    "TradingDataType",
-    "OrderBook",
-    "Ticker",
-    "TradingTimeFrame",
-    "OHLCV",
     "OrderType",
     "OrderStatus",
     "OrderSide",
-    "Config",
     "PortfolioConfiguration",
     "TimeUnit",
     "TimeInterval",
@@ -31,5 +75,140 @@ __all__ = [
     "Portfolio",
     "Position",
     "StatelessAction",
-    "Task"
+    "Task",
+    "pretty_print_backtest",
+    "INDEX_DATETIME",
+    "Trade",
+    "TimeFrame",
+    "MarketCredential",
+    "OperationalException",
+    "APP_MODE",
+    "AppMode",
+    "DATETIME_FORMAT",
+    "Backtest",
+    "BacktestDateRange",
+    "convert_polars_to_pandas",
+    "AzureBlobStorageStateHandler",
+    "DEFAULT_LOGGING_CONFIG",
+    "BacktestReport",
+    "TradeStatus",
+    "Context",
+    "APPLICATION_DIRECTORY",
+    "download",
+    "pretty_print_orders",
+    "pretty_print_trades",
+    "pretty_print_positions",
+    "DataSource",
+    "OrderExecutor",
+    "PortfolioProvider",
+    "SnapshotInterval",
+    "add_html_report",
+    "AWSS3StorageStateHandler",
+    "AWS_S3_STATE_BUCKET_NAME",
+    "AWS_LAMBDA_LOGGING_CONFIG",
+    'select_backtest_date_ranges',
+    'DataType',
+    'CSVOHLCVDataProvider',
+    "CCXTOHLCVDataProvider",
+    "DataProvider",
+    "get_annual_volatility",
+    "get_sortino_ratio",
+    "get_drawdown_series",
+    "get_max_drawdown",
+    "get_equity_curve",
+    "get_price_efficiency_ratio",
+    "get_sharpe_ratio",
+    "get_profit_factor",
+    "get_cumulative_profit_factor_series",
+    "get_rolling_profit_factor_series",
+    "get_sharpe_ratio",
+    "get_cagr",
+    "get_standard_deviation_returns",
+    "get_standard_deviation_downside_returns",
+    "get_max_drawdown_absolute",
+    "get_total_return",
+    "get_exposure_ratio",
+    "get_cumulative_exposure",
+    "get_average_trade_duration",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
+    "get_trade_frequency",
+    "get_yearly_returns",
+    "get_monthly_returns",
+    "get_best_year",
+    "get_best_month",
+    "get_worst_year",
+    "get_worst_month",
+    "get_best_trade",
+    "get_worst_trade",
+    "get_average_yearly_return",
+    "get_average_trade_gain",
+    "get_average_trade_loss",
+    "get_average_monthly_return",
+    "get_percentage_winning_months",
+    "get_average_trade_duration",
+    "get_trade_frequency",
+    "get_win_rate",
+    "get_win_loss_ratio",
+    "get_calmar_ratio",
+    "get_max_drawdown_absolute",
+    "get_max_drawdown_duration",
+    "get_max_daily_drawdown",
+    "get_trades_per_day",
+    "get_trades_per_year",
+    "get_average_monthly_return_losing_months",
+    "get_average_monthly_return_winning_months",
+    "get_percentage_winning_years",
+    "get_rolling_sharpe_ratio",
+    "create_backtest_metrics",
+    "PandasOHLCVDataProvider",
+    "get_equity_curve_with_drawdown_chart",
+    "get_rolling_sharpe_ratio_chart",
+    "get_monthly_returns_heatmap_chart",
+    "get_yearly_returns_bar_chart",
+    "get_ohlcv_data_completeness_chart",
+    "rank_results",
+    "create_weights",
+    "get_entry_and_exit_signals",
+    "BacktestEvaluationFocus",
+    "combine_backtests",
+    "PositionSize",
+    "get_median_trade_return",
+    "get_average_trade_return",
+    "get_risk_free_rate_us",
+    "get_cumulative_return",
+    "get_cumulative_return_series",
+    "get_total_loss",
+    "get_total_growth",
+    "generate_backtest_summary_metrics",
+    "get_equity_curve_chart",
+    "get_current_win_rate",
+    "get_current_win_loss_ratio",
+    "get_current_average_trade_loss",
+    "get_current_average_trade_duration",
+    "get_current_average_trade_gain",
+    "get_current_average_trade_return",
+    "get_negative_trades",
+    "get_positive_trades",
+    "get_number_of_trades",
+    "BacktestRun",
+    "load_backtests_from_directory",
+    "save_backtests_to_directory",
+    "DataError",
+    "create_backtest_metrics_for_backtest",
+    "TakeProfitRule",
+    "StopLossRule",
+    "TradeStopLossService",
+    "TradeTakeProfitService",
+    "generate_algorithm_id",
+    "BacktestMetrics",
+    "generate_rolling_backtest_windows",
+    "tqdm",
+    "get_missing_timeseries_data_entries",
+    "fill_missing_timeseries_data",
+    "create_markdown_table",
+    "download_v2",
+    "DownloadResult",
+    "create_data_storage_path"
 ]

investing_algorithm_framework/analysis/__init__.py

@@ -0,0 +1,16 @@
+from .markdown import create_markdown_table
+from .backtest_data_ranges import select_backtest_date_ranges, \
+    generate_rolling_backtest_windows
+from .ranking import create_weights, rank_results
+from .data import fill_missing_timeseries_data, \
+    get_missing_timeseries_data_entries
+
+__all__ = [
+    "create_markdown_table",
+    "select_backtest_date_ranges",
+    "generate_rolling_backtest_windows",
+    "create_weights",
+    "rank_results",
+    "fill_missing_timeseries_data",
+    "get_missing_timeseries_data_entries",
+]

investing_algorithm_framework/analysis/backtest_data_ranges.py

@@ -0,0 +1,202 @@
+import pandas as pd
+from logging import getLogger
+from datetime import datetime
+from typing import List, Dict, Union
+from datetime import timezone
+
+from investing_algorithm_framework.domain import BacktestDateRange, \
+    OperationalException
+
+logger = getLogger(__name__)
+
+
+def select_backtest_date_ranges(
+    df: pd.DataFrame, window: Union[str, int] = '365D'
+) -> List[BacktestDateRange]:
+    """
+    Identifies the best upturn, worst downturn, and sideways periods
+    for the given window duration. This allows you to quickly select
+    interesting periods for backtesting.
+
+    Args:
+        df (pd.DataFrame): DataFrame with a DateTime index
+            and 'Close' column.
+        window (Union[str, int]): Duration of the window
+            to analyze. Can be a string like '365D' or an
+            integer representing days.
+
+    Returns:
+        List[BacktestDateRange]: List of BacktestDateRange
+            objects representing the best upturn, worst
+            downturn, and most sideways periods.
+    """
+    df = df.copy()
+    df = df.sort_index()
+
+    if isinstance(window, int):
+        window = pd.Timedelta(days=window)
+    elif isinstance(window, str):
+        window = pd.to_timedelta(window)
+    else:
+        raise OperationalException("window must be a string or integer")
+
+    # Check if the window is larger than the DataFrame
+    if len(df) == 0:
+        raise OperationalException("DataFrame is empty")
+
+    if df.index[-1] - df.index[0] < window:
+        raise OperationalException(
+            "Window duration is larger than the data duration"
+        )
+
+    if len(df) < 2 or df.index[-1] - df.index[0] < window:
+        raise OperationalException(
+            "DataFrame must contain at least two rows and span "
+            "the full window duration"
+        )
+
+    best_upturn = {
+        "name": "UpTurn", "return": float('-inf'), "start": None, "end": None
+    }
+    worst_downturn = {
+        "name": "DownTurn", "return": float('inf'), "start": None, "end": None
+    }
+    most_sideways = {
+        "name": "SideWays",
+        "volatility": float('inf'),
+        "return": None,
+        "start": None,
+        "end": None
+    }
+
+    for i in range(len(df)):
+        start_time = df.index[i]
+        end_time = start_time + window
+        window_df = df[(df.index >= start_time) & (df.index <= end_time)]
+
+        if len(window_df) < 2 or (window_df.index[-1] - start_time) < window:
+            continue
+
+        start_price = window_df['Close'].iloc[0]
+        end_price = window_df['Close'].iloc[-1]
+        ret = (end_price / start_price) - 1  # relative return
+        volatility = window_df['Close'].std()
+
+        # Ensure datetime for BacktestDateRange and with timezone utc
+        start_time = pd.Timestamp(start_time).to_pydatetime()
+        start_time = start_time.replace(tzinfo=timezone.utc)
+        end_time = pd.Timestamp(window_df.index[-1]).to_pydatetime()
+        end_time = end_time.replace(tzinfo=timezone.utc)
+
+        if ret > best_upturn["return"]:
+            best_upturn.update(
+                {"return": ret, "start": start_time, "end": end_time}
+            )
+
+        if ret < worst_downturn["return"]:
+            worst_downturn.update(
+                {"return": ret, "start": start_time, "end": end_time}
+            )
+
+        if volatility < most_sideways["volatility"]:
+            most_sideways.update({
+                "return": ret,
+                "volatility": volatility,
+                "start": start_time,
+                "end": end_time
+            })
+
+    return [
+        BacktestDateRange(
+            start_date=best_upturn['start'],
+            end_date=best_upturn['end'],
+            name=best_upturn['name']
+        ),
+        BacktestDateRange(
+            start_date=worst_downturn['start'],
+            end_date=worst_downturn['end'],
+            name=worst_downturn['name']
+        ),
+        BacktestDateRange(
+            start_date=most_sideways['start'],
+            end_date=most_sideways['end'],
+            name=most_sideways['name']
+        )
+    ]
+
+
+def generate_rolling_backtest_windows(
+    start_date: datetime,
+    end_date: datetime,
+    train_days: int = 365,
+    test_days: int = 90,
+    step_days: int = 90,
+    gap_days: int = 0,
+) -> List[Dict[str, BacktestDateRange]]:
+    """
+    Generate rolling windows for walk-forward backtesting.
+
+    This function creates training and testing date ranges for
+    time-series backtesting, avoiding look-ahead bias and providing
+    realistic out-of-sample performance estimates.
+
+    Args:
+        start_date (datetime): The starting date for the first
+            training window.
+        end_date (datetime): The ending date for the last
+            testing window.
+        train_days (int): Number of days in the training window.
+        test_days (int): Number of days in the testing window.
+        step_days (int): Number of days to step forward for the next window.
+        gap_days (int): Number of days to skip between train and test windows.
+            Useful to avoid look-ahead bias in indicators
+            with lag (e.g., 26 for MACD). Default is 0 (no gap).
+
+    Returns:
+        List[Dict[str, BacktestDateRange]]: A list of dictionaries containing:
+            - "train_range": BacktestDateRange for training period
+            - "test_range": BacktestDateRange for testing period
+
+    Example:
+        >>> windows = generate_rolling_backtest_windows(
+        ...     start_date=datetime(2021, 1, 1, tzinfo=timezone.utc),
+        ...     end_date=datetime(2024, 12, 31, tzinfo=timezone.utc),
+        ...     train_days=365,
+        ...     test_days=90,
+        ...     step_days=90,
+        ...     gap_days=30
+        ... )
+    """
+    windows = []
+    current_start = start_date
+    max_iterations = 10000  # Safety limit to prevent infinite loops
+    iteration = 0
+
+    while iteration < max_iterations:
+        iteration += 1
+        train_start = current_start
+        train_end = train_start + pd.Timedelta(days=train_days)
+        test_start = train_end + pd.Timedelta(days=gap_days)
+        test_end = test_start + pd.Timedelta(days=test_days)
+
+        if test_end > end_date:
+            break
+
+        train_backtest_date_range = BacktestDateRange(
+            name=f"train_window_{iteration}",
+            start_date=train_start,
+            end_date=train_end
+        )
+        test_backtest_date_range = BacktestDateRange(
+            name=f"test_window_{iteration}",
+            start_date=test_start,
+            end_date=test_end
+        )
+        windows.append({
+            "train_range": train_backtest_date_range,
+            "test_range": test_backtest_date_range,
+        })
+
+        current_start += pd.Timedelta(days=step_days)
+
+    return windows

investing_algorithm_framework/analysis/data.py

@@ -0,0 +1,170 @@
+import pandas as pd
+import polars as pl
+from typing import Union
+
+
+def fill_missing_timeseries_data(
+    data: Union[pd.DataFrame, pl.DataFrame, str],
+    missing_dates: list = None,
+    start_date=None,
+    end_date=None,
+    save_to_file: bool = False,
+    file_path: str = None
+) -> Union[pd.DataFrame, pl.DataFrame]:
+    """
+    Fill missing dates in time-series data using a hybrid approach:
+    forward-fill by default, backward-fill only when missing dates
+    are at the start of the data.
+
+    This function handles missing rows (dates) in time-series data,
+    not just missing values within existing rows. All columns are
+    duplicated from the adjacent row.
+
+    Args:
+        data (pd.DataFrame | pl.DataFrame | str): Time-series data as a
+            DataFrame or path to a CSV file. Index should be datetime.
+        missing_dates (list, optional): List of datetime objects representing
+            specific missing dates to fill. If None and start_date/end_date
+            are provided, missing dates will be auto-detected.
+        start_date (datetime, optional): Start date to check for missing dates.
+        end_date (datetime, optional): End date to check for missing dates.
+        save_to_file (bool): If True, save the result back to the CSV file.
+        file_path (str, optional): Path to save/load the CSV file.
+
+    Returns:
+        pd.DataFrame | pl.DataFrame: DataFrame with missing dates filled.
+    """
+    is_polars = False
+
+    # Load data if file path is provided
+    if isinstance(data, str):
+        file_path = data
+        df = pd.read_csv(file_path, index_col=0, parse_dates=True)
+    elif isinstance(data, pl.DataFrame):
+        is_polars = True
+        # Convert polars to pandas for processing
+        df = data.to_pandas()
+        if 'Datetime' in df.columns:
+            df = df.set_index('Datetime')
+        df.index = pd.to_datetime(df.index)
+    else:
+        df = data.copy()
+
+    # Store the index name
+    index_name = df.index.name if df.index.name else 'Datetime'
+
+    rows_to_add = []
+
+    # Determine which dates need to be filled
+    if missing_dates is not None and len(missing_dates) > 0:
+        # Convert index to set of timestamps for proper comparison
+        existing_timestamps = set(pd.to_datetime(df.index))
+        # Deduplicate missing_dates and filter out existing dates
+        seen = set()
+        dates_to_fill = []
+        for d in missing_dates:
+            dt = pd.to_datetime(d)
+            if dt not in existing_timestamps and dt not in seen:
+                dates_to_fill.append(d)
+                seen.add(dt)
+    elif start_date is not None and end_date is not None:
+        dates_to_fill = get_missing_timeseries_data_entries(
+            df, start=start_date, end=end_date, freq='D'
+        )
+    else:
+        dates_to_fill = []
+
+    # Fill missing dates
+    for missing_timestamp in dates_to_fill:
+        # Find the index position where this timestamp should be inserted
+        position = df[df.index < missing_timestamp].shape[0]
+
+        # Edge case: missing timestamp is BEFORE all existing data
+        if position == 0:
+            # Use the FIRST row (backward fill)
+            if len(df) > 0:
+                next_row = df.iloc[0]
+                new_row = next_row.to_dict()
+            else:
+                continue  # No data to fill from
+        else:
+            # Normal case: use previous row (forward fill)
+            prev_row = df.iloc[position - 1]
+            new_row = prev_row.to_dict()
+
+        rows_to_add.append({index_name: missing_timestamp, **new_row})
+
+    # Add new rows if any
+    if rows_to_add:
+        new_df = pd.DataFrame(rows_to_add).set_index(index_name)
+        df = pd.concat([df, new_df]).sort_index()
+
+    # Save to file if requested
+    if save_to_file and file_path:
+        df.to_csv(file_path)
+
+    # Convert back to polars if input was polars
+    if is_polars:
+        df = df.reset_index()
+        return pl.from_pandas(df)
+
+    return df
+
+
+def get_missing_timeseries_data_entries(
+    data: Union[pd.DataFrame, pl.DataFrame, str],
+    start=None,
+    end=None,
+    freq: str = None
+):
+    """
+    Identify missing timestamps in a time series.
+
+    Args:
+        data (pd.DataFrame | pl.DataFrame | str): Time-series data as a
+            DataFrame or path to a CSV file. Index should be datetime.
+        start (datetime, optional): The start datetime for the expected range.
+            If None, uses the first timestamp in the data.
+        end (datetime, optional): The end datetime for the expected range.
+            If None, uses the last timestamp in the data.
+        freq (str, optional): Frequency string (e.g., 'D' for daily, 'H' for
+            hourly). If None, will be inferred from the data.
+
+    Returns:
+        list: A list of missing timestamps within the specified range.
+    """
+    # Load data if file path is provided
+    if isinstance(data, str):
+        df = pd.read_csv(data, index_col=0, parse_dates=True)
+    elif isinstance(data, pl.DataFrame):
+        df = data.to_pandas()
+        if 'Datetime' in df.columns:
+            df = df.set_index('Datetime')
+        df.index = pd.to_datetime(df.index)
+    else:
+        df = data
+
+    # Get existing timestamps from the index
+    existing_timestamps = pd.to_datetime(df.index)
+
+    # Use data bounds if start/end not provided
+    if start is None:
+        start = existing_timestamps.min()
+    if end is None:
+        end = existing_timestamps.max()
+
+    # Infer frequency if not provided
+    if freq is None:
+        freq = df.index.inferred_freq
+        if freq is None and len(df) >= 2:
+            diff = df.index[1] - df.index[0]
+            freq = diff
+        elif freq is None:
+            freq = 'D'  # Default to daily
+
+    expected_timestamps = pd.date_range(start=start, end=end, freq=freq)
+
+    # Find missing by checking which expected timestamps are not in existing
+    missing_mask = ~expected_timestamps.isin(existing_timestamps)
+    missing_timestamps = expected_timestamps[missing_mask].tolist()
+    return missing_timestamps