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

investing_algorithm_framework/services/metrics/exposure.py

@@ -0,0 +1,210 @@
+"""
+High exposure (>1) means you’re deploying capital aggressively, possibly with many simultaneous positions.
+
+Exposure around 1 means capital is nearly fully invested most of the time, but not overlapping.
+
+Low exposure (<1) means capital is mostly idle or only partially invested.
+"""
+
+from datetime import datetime, timedelta
+from typing import List
+
+from investing_algorithm_framework.domain import Trade
+
+
+def get_exposure_ratio(
+    trades: List["Trade"], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the exposure ratio (time in market) as the fraction of the total
+    backtest duration where at least one position was open.
+
+    Unlike cumulative exposure, overlapping trades are not double-counted.
+    The result is always between 0 and 1.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float between 0 and 1 representing the exposure ratio.
+    """
+    if not trades:
+        return 0.0
+
+    # Collect trade intervals
+    intervals = []
+    for trade in trades:
+        entry = max(trade.opened_at, start_date)
+        exit = min(trade.closed_at or end_date, end_date)
+        if exit > entry:
+            intervals.append((entry, exit))
+
+    if not intervals:
+        return 0.0
+
+    # Sort intervals by start time
+    intervals.sort(key=lambda x: x[0])
+
+    # Merge overlapping intervals
+    merged = []
+    current_start, current_end = intervals[0]
+    for start, end in intervals[1:]:
+        if start <= current_end:  # overlap
+            current_end = max(current_end, end)
+        else:
+            merged.append((current_start, current_end))
+            current_start, current_end = start, end
+    merged.append((current_start, current_end))
+
+    # Total time with at least one open trade
+    total_exposed_time = sum((end - start for start, end in merged), timedelta(0))
+
+    backtest_duration = end_date - start_date
+    if backtest_duration.total_seconds() == 0:
+        return 0.0
+
+    return total_exposed_time.total_seconds() \
+        / backtest_duration.total_seconds()
+
+
+def get_cumulative_exposure(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the exposure time as a fraction of the total backtest duration
+    that the strategy had capital deployed (i.e., at least one open position).
+
+    This value can be greater than 1 if the strategy had overlapping trades.
+    For example, if the strategy had two trades open at the same time,
+    the exposure factor would be 2.0, indicating that capital was deployed
+    for twice the duration of the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date.
+        end_date (datetime): The end date.
+
+    Returns:
+        A float representing the exposure factor, which is the fraction of time
+        the strategy had capital deployed during the backtest period.
+
+    """
+    if not trades:
+        return 0.0
+
+    total_trade_duration = timedelta(0)
+    for trade in trades:
+        entry = trade.opened_at
+        exit = trade.closed_at or end_date  # open trades counted up to end
+
+        if exit > entry:
+            total_trade_duration += exit - entry
+
+    backtest_duration = end_date - start_date
+
+    if backtest_duration.total_seconds() == 0:
+        return 0.0
+
+    return (total_trade_duration.total_seconds()
+            / backtest_duration.total_seconds())
+
+
+def get_average_trade_duration(trades: List[Trade]):
+    """
+    Calculates the average duration of trades in the backtest report.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+
+    Returns:
+        A float representing the average trade duration in hours.
+    """
+    if not trades:
+        return 0.0
+
+    total_duration = 0
+
+    for trade in trades:
+        trade_duration = trade.duration
+
+        if trade_duration is not None:
+            total_duration += trade_duration
+
+    average_trade_duration = total_duration / len(trades)
+    return average_trade_duration
+
+
+def get_trade_frequency(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the trade frequency as the number of trades per day
+    during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per day.
+    """
+
+    if not trades:
+        return 0.0
+
+    total_days = (end_date - start_date).days + 1
+    if total_days <= 0:
+        return 0.0
+
+    return len(trades) / total_days
+
+
+def get_trades_per_day(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the average number of trades per day during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per day.
+    """
+    if not trades:
+        return 0.0
+
+    total_days = (end_date - start_date).days + 1
+    if total_days <= 0:
+        return 0.0
+
+    return len(trades) / total_days
+
+
+def get_trades_per_year(
+    trades: List[Trade], start_date: datetime, end_date: datetime
+) -> float:
+    """
+    Calculates the average number of trades per year during the backtest period.
+
+    Args:
+        trades (List[Trade]): List of trades executed during the backtest.
+        start_date (datetime): The start date of the backtest.
+        end_date (datetime): The end date of the backtest.
+
+    Returns:
+        A float representing the average number of trades per year.
+    """
+    if not trades:
+        return 0.0
+
+    total_years = (end_date - start_date).days / 365.25
+    if total_years <= 0:
+        return 0.0
+
+    return len(trades) / total_years

investing_algorithm_framework/services/metrics/generate.py

@@ -0,0 +1,358 @@
+from typing import List
+from logging import getLogger
+
+from investing_algorithm_framework.domain import BacktestMetrics, \
+    BacktestRun, OperationalException, Backtest, BacktestDateRange
+from .cagr import get_cagr
+from .calmar_ratio import get_calmar_ratio
+from .drawdown import get_drawdown_series, get_max_drawdown, \
+    get_max_daily_drawdown, get_max_drawdown_absolute, \
+    get_max_drawdown_duration
+from .equity_curve import get_equity_curve
+from .exposure import get_exposure_ratio, get_cumulative_exposure, \
+    get_trades_per_year, get_trades_per_day
+from .profit_factor import get_profit_factor, get_gross_loss, get_gross_profit
+from .returns import get_monthly_returns, get_yearly_returns, \
+    get_worst_year, get_best_year, get_best_month, get_worst_month, \
+    get_percentage_winning_months, get_percentage_winning_years, \
+    get_average_monthly_return, get_average_monthly_return_winning_months, \
+    get_average_monthly_return_losing_months, get_cumulative_return, \
+    get_cumulative_return_series
+from .returns import get_total_return, get_final_value, get_total_loss, \
+    get_total_growth
+from .sharpe_ratio import get_sharpe_ratio, get_rolling_sharpe_ratio
+from .sortino_ratio import get_sortino_ratio
+from .volatility import get_annual_volatility
+from .win_rate import get_win_rate, get_win_loss_ratio, get_current_win_rate, \
+    get_current_win_loss_ratio
+from .trades import get_average_trade_duration, get_average_trade_size, \
+    get_number_of_trades, get_positive_trades, get_number_of_closed_trades, \
+    get_negative_trades, get_average_trade_return, get_number_of_open_trades, \
+    get_worst_trade, get_best_trade, get_average_trade_gain, \
+    get_average_trade_loss, get_median_trade_return, \
+    get_current_average_trade_gain, get_current_average_trade_return, \
+    get_current_average_trade_duration, get_current_average_trade_loss
+
+logger = getLogger("investing_algorithm_framework")
+
+def create_backtest_metrics_for_backtest(
+    backtest: Backtest,
+    risk_free_rate: float, metrics: List[str] = None,
+    backtest_date_range: BacktestDateRange = None
+) -> Backtest:
+
+    """
+    Create BacktestMetrics for a Backtest object.
+
+    Args:
+        backtest (Backtest): The Backtest object containing
+            backtest runs.
+        risk_free_rate (float): The risk-free rate used in certain
+            metric calculations.
+        metrics (List[str], optional): List of metric names to compute.
+            If None, a default set of metrics will be computed.
+        backtest_date_range (BacktestDateRange, optional): The date range
+            for the backtest. If None, all backtest metrics will be computed
+            for each backtest run.
+
+    Returns:
+        Backtest: The Backtest object with computed metrics for each run.
+    """
+    if backtest_date_range is not None:
+        backtest_runs = [
+            backtest.get_backtest_run(backtest_date_range)
+        ]
+    else:
+        backtest_runs = backtest.get_all_backtest_runs()
+
+    for backtest_run in backtest_runs:
+        # If a date range is provided, check if the backtest run falls
+        # within the range
+        backtest_metrics = create_backtest_metrics(
+            backtest_run, risk_free_rate, metrics
+        )
+        backtest_run.backtest_metrics = backtest_metrics
+
+    backtest.backtest_runs = backtest_runs
+    return backtest
+
+
+def create_backtest_metrics(
+    backtest_run: BacktestRun, risk_free_rate: float, metrics: List[str] = None
+) -> BacktestMetrics:
+    """
+    Create a BacktestMetrics instance and optionally save it to a file.
+
+    Args:
+        backtest_run (BacktestRun): The BacktestRun object containing
+            portfolio snapshots and trades.
+        risk_free_rate (float): The risk-free rate used in certain
+            metric calculations.
+        metrics (List[str], optional): List of metric names to compute.
+            If None, a default set of metrics will be computed.
+
+    Returns:
+        BacktestMetrics: The computed backtest metrics.
+    """
+
+    if metrics is None:
+        metrics = [
+            "backtest_start_date",
+            "backtest_end_date",
+            "equity_curve",
+            "final_value",
+            "total_growth",
+            "total_growth_percentage",
+            "total_net_gain",
+            "total_net_gain_percentage",
+            "total_loss",
+            "total_loss_percentage",
+            "cumulative_return",
+            "cumulative_return_series",
+            "cagr",
+            "sharpe_ratio",
+            "rolling_sharpe_ratio",
+            "sortino_ratio",
+            "calmar_ratio",
+            "profit_factor",
+            "annual_volatility",
+            "monthly_returns",
+            "yearly_returns",
+            "drawdown_series",
+            "max_drawdown",
+            "max_drawdown_absolute",
+            "max_daily_drawdown",
+            "max_drawdown_duration",
+            "trades_per_year",
+            "trade_per_day",
+            "exposure_ratio",
+            "cumulative_exposure",
+            "best_trade",
+            "worst_trade",
+            "number_of_positive_trades",
+            "percentage_positive_trades",
+            "number_of_negative_trades",
+            "percentage_negative_trades",
+            "average_trade_duration",
+            "average_trade_size",
+            "average_trade_loss",
+            "average_trade_loss_percentage",
+            "average_trade_gain",
+            "average_trade_gain_percentage",
+            "average_trade_return",
+            "average_trade_return_percentage",
+            "median_trade_return",
+            "number_of_trades",
+            "number_of_trades_closed",
+            "number_of_trades_opened",
+            "number_of_trades_open_at_end",
+            "win_rate",
+            "current_win_rate",
+            "win_loss_ratio",
+            "current_win_loss_ratio",
+            "percentage_winning_months",
+            "percentage_winning_years",
+            "average_monthly_return",
+            "average_monthly_return_losing_months",
+            "average_monthly_return_winning_months",
+            "best_month",
+            "best_year",
+            "worst_month",
+            "worst_year",
+            "total_number_of_days",
+            "current_average_trade_gain",
+            "current_average_trade_return",
+            "current_average_trade_duration",
+            "current_average_trade_loss",
+        ]
+
+    backtest_metrics = BacktestMetrics(
+        backtest_start_date=backtest_run.backtest_start_date,
+        backtest_end_date=backtest_run.backtest_end_date,
+    )
+
+    def safe_set(metric_name, func, *args, index=None):
+        if metric_name in metrics:
+            try:
+                value = func(*args)
+                if index is not None and isinstance(value, (list, tuple)):
+                    setattr(backtest_metrics, metric_name, value[index])
+                else:
+                    setattr(backtest_metrics, metric_name, value)
+            except OperationalException as e:
+                logger.warning(f"{metric_name} failed: {e}")
+
+    # Grouped metrics needing special handling
+    if "total_net_gain" in metrics or "total_net_gain_percentage" in metrics:
+        try:
+            total_return = get_total_return(backtest_run.portfolio_snapshots)
+            if "total_net_gain" in metrics:
+                backtest_metrics.total_net_gain = total_return[0]
+            if "total_net_gain_percentage" in metrics:
+                backtest_metrics.total_net_gain_percentage = total_return[1]
+        except OperationalException as e:
+            logger.warning(f"total_return failed: {e}")
+
+    if "total_growth" in metrics or "total_growth_percentage" in metrics:
+        try:
+            total_growth = get_total_growth(backtest_run.portfolio_snapshots)
+            if "total_growth" in metrics:
+                backtest_metrics.total_growth = total_growth[0]
+            if "total_growth_percentage" in metrics:
+                backtest_metrics.total_growth_percentage = total_growth[1]
+        except OperationalException as e:
+            logger.warning(f"total_growth failed: {e}")
+
+    if "total_loss" in metrics or "total_loss_percentage" in metrics:
+        try:
+            total_loss = get_total_loss(backtest_run.portfolio_snapshots)
+            if "total_loss" in metrics:
+                backtest_metrics.total_loss = total_loss[0]
+            if "total_loss_percentage" in metrics:
+                backtest_metrics.total_loss_percentage = total_loss[1]
+        except OperationalException as e:
+            logger.warning(f"total_loss failed: {e}")
+
+    if ("average_trade_return" in metrics
+            or "average_trade_return_percentage" in metrics):
+        try:
+            avg_return = get_average_trade_return(backtest_run.trades)
+            if "average_trade_return" in metrics:
+                backtest_metrics.average_trade_return = avg_return[0]
+            if "average_trade_return_percentage" in metrics:
+                backtest_metrics.average_trade_return_percentage = \
+                    avg_return[1]
+        except OperationalException as e:
+            logger.warning(f"average_trade_return failed: {e}")
+
+    if ("average_trade_gain" in metrics
+            or "average_trade_gain_percentage" in metrics):
+        try:
+            avg_gain = get_average_trade_gain(backtest_run.trades)
+            if "average_trade_gain" in metrics:
+                backtest_metrics.average_trade_gain = avg_gain[0]
+            if "average_trade_gain_percentage" in metrics:
+                backtest_metrics.average_trade_gain_percentage = avg_gain[1]
+        except OperationalException as e:
+            logger.warning(f"average_trade_gain failed: {e}")
+
+    if ("average_trade_loss" in metrics
+            or "average_trade_loss_percentage" in metrics):
+        try:
+            avg_loss = get_average_trade_loss(backtest_run.trades)
+            if "average_trade_loss" in metrics:
+                backtest_metrics.average_trade_loss = avg_loss[0]
+            if "average_trade_loss_percentage" in metrics:
+                backtest_metrics.average_trade_loss_percentage = avg_loss[1]
+        except OperationalException as e:
+            logger.warning(f"average_trade_loss failed: {e}")
+
+    if ("current_average_trade_gain" in metrics
+            or "get_current_average_trade_gain_percentage" in metrics):
+        try:
+            current_avg_gain = get_current_average_trade_gain(
+                backtest_run.trades
+            )
+
+            if "current_average_trade_gain" in metrics:
+                backtest_metrics.current_average_trade_gain = \
+                    current_avg_gain[0]
+
+            if "current_average_trade_gain_percentage" in metrics:
+                backtest_metrics.current_average_trade_gain_percentage = \
+                    current_avg_gain[1]
+        except OperationalException as e:
+            logger.warning(f"current_average_trade_gain failed: {e}")
+
+    if ("current_average_trade_return" in metrics
+            or "current_average_trade_return_percentage" in metrics):
+        try:
+            current_avg_return = get_current_average_trade_return(
+                backtest_run.trades
+            )
+
+            if "current_average_trade_return" in metrics:
+                backtest_metrics.current_average_trade_return = \
+                    current_avg_return[0]
+            if "current_average_trade_return_percentage" in metrics:
+                backtest_metrics.current_average_trade_return_percentage =\
+                    current_avg_return[1]
+        except OperationalException as e:
+            logger.warning(f"current_average_trade_return failed: {e}")
+
+    if "current_average_trade_duration" in metrics:
+        try:
+            current_avg_duration = get_current_average_trade_duration(
+                backtest_run.trades, backtest_run
+            )
+            backtest_metrics.current_average_trade_duration = \
+                current_avg_duration
+        except OperationalException as e:
+            logger.warning(f"current_average_trade_duration failed: {e}")
+
+    if ("current_average_trade_loss" in metrics
+            or "current_average_trade_loss_percentage" in metrics):
+        try:
+            current_avg_loss = get_current_average_trade_loss(
+                backtest_run.trades
+            )
+            if "current_average_trade_loss" in metrics:
+                backtest_metrics.current_average_trade_loss = \
+                    current_avg_loss[0]
+            if "current_average_trade_loss_percentage" in metrics:
+                backtest_metrics.current_average_trade_loss_percentage = \
+                    current_avg_loss[1]
+        except OperationalException as e:
+            logger.warning(f"current_average_trade_loss failed: {e}")
+
+    safe_set("number_of_positive_trades", get_positive_trades, backtest_run.trades)
+    safe_set("percentage_positive_trades", get_positive_trades, backtest_run.trades, index=1)
+    safe_set("number_of_negative_trades", get_negative_trades, backtest_run.trades)
+    safe_set("percentage_negative_trades", get_negative_trades, backtest_run.trades, index=1)
+    safe_set("median_trade_return", get_median_trade_return, backtest_run.trades, index=0)
+    safe_set("median_trade_return_percentage", get_median_trade_return, backtest_run.trades, index=1)
+    safe_set("number_of_trades", get_number_of_trades, backtest_run.trades)
+    safe_set("number_of_trades_closed", get_number_of_closed_trades, backtest_run.trades)
+    safe_set("number_of_trades_opened", get_number_of_open_trades, backtest_run.trades)
+    safe_set("average_trade_duration", get_average_trade_duration, backtest_run.trades)
+    safe_set("average_trade_size", get_average_trade_size, backtest_run.trades)
+    safe_set("equity_curve", get_equity_curve, backtest_run.portfolio_snapshots)
+    safe_set("final_value", get_final_value, backtest_run.portfolio_snapshots)
+    safe_set("cagr", get_cagr, backtest_run.portfolio_snapshots)
+    safe_set("sharpe_ratio", get_sharpe_ratio, backtest_run.portfolio_snapshots, risk_free_rate)
+    safe_set("rolling_sharpe_ratio", get_rolling_sharpe_ratio, backtest_run.portfolio_snapshots, risk_free_rate)
+    safe_set("sortino_ratio", get_sortino_ratio, backtest_run.portfolio_snapshots, risk_free_rate)
+    safe_set("profit_factor", get_profit_factor, backtest_run.trades)
+    safe_set("calmar_ratio", get_calmar_ratio, backtest_run.portfolio_snapshots)
+    safe_set("annual_volatility", get_annual_volatility, backtest_run.portfolio_snapshots)
+    safe_set("monthly_returns", get_monthly_returns, backtest_run.portfolio_snapshots)
+    safe_set("yearly_returns", get_yearly_returns, backtest_run.portfolio_snapshots)
+    safe_set("drawdown_series", get_drawdown_series, backtest_run.portfolio_snapshots)
+    safe_set("max_drawdown", get_max_drawdown, backtest_run.portfolio_snapshots)
+    safe_set("max_drawdown_absolute", get_max_drawdown_absolute, backtest_run.portfolio_snapshots)
+    safe_set("max_daily_drawdown", get_max_daily_drawdown, backtest_run.portfolio_snapshots)
+    safe_set("max_drawdown_duration", get_max_drawdown_duration, backtest_run.portfolio_snapshots)
+    safe_set("trades_per_year", get_trades_per_year, backtest_run.trades, backtest_run.backtest_start_date, backtest_run.backtest_end_date)
+    safe_set("trades_per_day", get_trades_per_day, backtest_run.trades, backtest_run.backtest_start_date, backtest_run.backtest_end_date)
+    safe_set("exposure_ratio", get_exposure_ratio, backtest_run.trades, backtest_run.backtest_start_date, backtest_run.backtest_end_date)
+    safe_set("cumulative_exposure", get_cumulative_exposure, backtest_run.trades, backtest_run.backtest_start_date, backtest_run.backtest_end_date)
+    safe_set("best_trade", get_best_trade, backtest_run.trades)
+    safe_set("worst_trade", get_worst_trade, backtest_run.trades)
+    safe_set("win_rate", get_win_rate, backtest_run.trades)
+    safe_set("current_win_rate", get_current_win_rate, backtest_run.trades)
+    safe_set("win_loss_ratio", get_win_loss_ratio, backtest_run.trades)
+    safe_set("current_win_loss_ratio", get_current_win_loss_ratio, backtest_run.trades)
+    safe_set("percentage_winning_months", get_percentage_winning_months, backtest_run.portfolio_snapshots)
+    safe_set("percentage_winning_years", get_percentage_winning_years, backtest_run.portfolio_snapshots)
+    safe_set("average_monthly_return", get_average_monthly_return, backtest_run.portfolio_snapshots)
+    safe_set("average_monthly_return_winning_months", get_average_monthly_return_winning_months, backtest_run.portfolio_snapshots)
+    safe_set("average_monthly_return_losing_months", get_average_monthly_return_losing_months, backtest_run.portfolio_snapshots)
+    safe_set("best_month", get_best_month, backtest_run.portfolio_snapshots)
+    safe_set("best_year", get_best_year, backtest_run.portfolio_snapshots)
+    safe_set("worst_month", get_worst_month, backtest_run.portfolio_snapshots)
+    safe_set("worst_year", get_worst_year, backtest_run.portfolio_snapshots)
+    safe_set("gross_loss", get_gross_loss, backtest_run.trades)
+    safe_set("gross_profit", get_gross_profit, backtest_run.trades)
+    safe_set("cumulative_return_series", get_cumulative_return_series, backtest_run.portfolio_snapshots)
+    safe_set("cumulative_return", get_cumulative_return, backtest_run.portfolio_snapshots)
+    return backtest_metrics

investing_algorithm_framework/services/metrics/mean_daily_return.py

@@ -0,0 +1,84 @@
+import pandas as pd
+import numpy as np
+
+from .cagr import get_cagr
+
+
+def get_mean_daily_return(snapshots):
+    """
+    Calculate the mean daily return from the total value of the snapshots.
+
+    This function computes the mean daily return based on the list of
+    snapshots in the report. If the snapshots have a granularity of less
+    than a day, the function will resample to daily frequency and compute
+    average daily returns.
+
+    If there is less data then for a year, it will use cagr to
+    calculate the mean daily return.
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+
+    Returns:
+        float: The mean daily return.
+    """
+
+    if len(snapshots) < 2:
+        return 0.0  # Not enough data
+
+    # Create DataFrame from snapshots
+    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'])
+    df = df.sort_values('created_at').drop_duplicates('created_at')\
+        .set_index('created_at')
+
+    start_date = df.iloc[0].name
+    end_date = df.iloc[-1].name
+
+    # Check if the period is less than a year
+    if (end_date - start_date).days < 365:
+        # Use CAGR to calculate mean daily return
+        cagr = get_cagr(snapshots)
+        if cagr == 0.0:
+            return 0.0
+
+        return (1 + cagr) ** (1 / 365) - 1
+
+    # Resample to daily frequency using last value of the day
+    daily_df = df.resample('1D').last().dropna()
+
+    # Calculate daily returns
+    daily_df['return'] = daily_df['total_value'].pct_change()
+    daily_df = daily_df.dropna()
+
+    if daily_df.empty:
+        return 0.0
+
+    mean_return = daily_df['return'].mean()
+
+    if np.isnan(mean_return):
+        return 0.0
+
+    return mean_return
+
+
+def get_mean_yearly_return(report, periods_per_year=365):
+    """
+    Calculate the mean yearly return from a backtest report by
+    annualizing the mean daily return.
+
+    Args:
+        report (BacktestReport): The report containing the snapshots.
+        periods_per_year (int): Number of periods in a year (e.g., 365 for daily data).
+
+    Returns:
+        float: The mean yearly return (annualized).
+    """
+    mean_daily_return = get_mean_daily_return(report)
+
+    if mean_daily_return == 0.0:
+        return 0.0
+
+    return (1 + mean_daily_return) ** periods_per_year - 1
+