Duration

duration

Duration estimation utilities based on statistical requirements and traffic pipelines.

This module provides tools to estimate the temporal duration of an experiment run, mapping the conceptually abstract "required sample size" derived from statistical power analysis into physical calendar time (days) using observed traffic rates and ramp-up schedules.

FUNCTION	DESCRIPTION
`estimate_duration_days`	Estimates the required experiment run duration in days.

estimate_duration_days

estimate_duration_days(
    required_sample_size: Real, daily_traffic: Real
) -> float

Estimates the required experiment run duration in days.

Translates the calculated target sample size ($N_{\text{required}}$) into the estimated calendar days needed to accumulate that sample volume based on active daily traffic ($T_{\text{daily}}$).

Mathematical Model

The duration in days ($D$) is computed as: $$ D = \frac{N_{\text{required}}}{T_{\text{daily}}} $$ where $N_{\text{required}}$ represents the combined total sample size across all active arms (control + treatment arms) or the single-arm requirement multiplied by the number of arms.

PARAMETER	DESCRIPTION
`required_sample_size`	The total sample size needed across all arms combined (e.g., control $n$ + treatment $n$). Must be greater than zero. TYPE: `Real`
`daily_traffic`	The expected number of unique qualifying experimental units (e.g., users, sessions, or pageviews) entering the experiment pipeline per day. Must be greater than zero. TYPE: `Real`

RETURNS	DESCRIPTION
`float`	Estimated run duration in decimal calendar days. TYPE: `float`

RAISES	DESCRIPTION
`TypeError`	If `required_sample_size` or `daily_traffic` is not a real number.
`ValueError`	If `required_sample_size` or `daily_traffic` is less than or equal to zero.

Examples:

Example

>>> estimate_duration_days(required_sample_size=50000, daily_traffic=5000)
10.0

Source code in src\xpyrment\plan\duration.py

def estimate_duration_days(required_sample_size: numbers.Real, daily_traffic: numbers.Real) -> float:
    r"""Estimates the required experiment run duration in days.

    Translates the calculated target sample size ($N_{\text{required}}$) into the estimated calendar days
    needed to accumulate that sample volume based on active daily traffic ($T_{\text{daily}}$).

    ??? mathbox "Mathematical Model"

        The duration in days ($D$) is computed as:
        $$
        D = \frac{N_{\text{required}}}{T_{\text{daily}}}
        $$
        where $N_{\text{required}}$ represents the combined total sample size across all active arms
        (control + treatment arms) or the single-arm requirement multiplied by the number of arms.

    Args:
        required_sample_size (numbers.Real): The total sample size needed across all arms combined
            (e.g., control $n$ + treatment $n$). Must be greater than zero.
        daily_traffic (numbers.Real): The expected number of unique qualifying experimental units (e.g., users,
            sessions, or pageviews) entering the experiment pipeline per day. Must be greater than zero.

    Returns:
        float: Estimated run duration in decimal calendar days.

    Raises:
        TypeError: If `required_sample_size` or `daily_traffic` is not a real number.
        ValueError: If `required_sample_size` or `daily_traffic` is less than or equal to zero.

    Examples:
        ??? example "Example"

            ```python
            >>> estimate_duration_days(required_sample_size=50000, daily_traffic=5000)
            10.0
            ```
    """
    if not isinstance(required_sample_size, numbers.Real):
        raise TypeError("required_sample_size must be a real number.")
    if not isinstance(daily_traffic, numbers.Real):
        raise TypeError("daily_traffic must be a real number.")

    if required_sample_size <= 0:
        raise ValueError("required_sample_size must be greater than zero.")
    if daily_traffic <= 0:
        raise ValueError("daily_traffic must be greater than zero.")
    return required_sample_size / daily_traffic