Управление экспериментами

Классы для управления и организации экспериментов A/B-тестирования.

AbobaExperiment

Класс для управления A/B экспериментом

Основной класс для проведения A/B экспериментов. Управляет данными, группами, применением тестов и визуализацией результатов. Поддерживает различные статистические тесты, препроцессинг данных и анализ результатов.

Инициализация

def __init__(
    self,
    alpha=0.05,
    experiment_name: Optional[str] = "AB experiment",
    visualization_method: Optional[Callable] = default_visualization_method,
    language: Language = "eng",
    **visualization_kwargs
)

Параметры

alpha (float): Уровень значимости для статистических тестов. По умолчанию 0.05.
experiment_name (Optional[str]): Название эксперимента для отображения. По умолчанию "AB experiment".
visualization_method (Optional[Callable]): Метод визуализации результатов. По умолчанию default_visualization_method.
visualization_kwargs: Дополнительные параметры для визуализации.

Методы

group

def group(
    self,
    name: str,
    test: BaseTest,
    data: Union[pd.DataFrame, List[pd.DataFrame]],
    data_pipeline: Pipeline,
    synthetic_effect: Optional[EffectModifier] = None,
    n_iter: int = 1,
    joblib_kwargs: Optional[dict] = None,
) -> ExperimentGroup

Создаёт и регистрирует группу эксперимента с указанным тестом, данными и пайплайном обработки.

draw

def draw(
    self,
    groups: Optional[List[str]] = None,
    group_configs: Optional[Dict[str, GroupVisualizationConfig]] = None,
    lang: Language = None,
    figsize: Optional[Tuple[float, float]] = None,
    filter_empty: bool = True,
    **kwargs
) -> Tuple[Optional[Figure], Any]

Рисует стандартный AA‑layout (интервалы, гистограмма p-value, ECDF) для выбранных групп.

Параметры

groups (Optional[List[str]]): Список имён групп для отображения. Если None, отображаются все группы.
group_configs (Optional[Dict[str, GroupVisualizationConfig]]): Настройки отображения для отдельных групп.
lang (Language): Язык подписей графика.
figsize (Optional[Tuple[float, float]]): Размер рисунка.
filter_empty (bool): Пропускать пустые группы.
kwargs: Дополнительные параметры для визуализации.

draw_comparison

def draw_comparison(
    self,
    group_pairs: List[Tuple[str, str]],
    separate_pairs: bool = False,
    **kwargs
) -> Tuple[Optional[Figure], Any]

Строит сравнительную визуализацию для пар групп.

Параметры

group_pairs (List[Tuple[str, str]]): Список пар групп вида (group1, group2).
separate_pairs (bool):
если True, группы располагаются попарно в порядке g1, g2, g1, g2, ...;
если False, повторяющиеся группы удаляются.
kwargs: Дополнительные параметры визуализации.

quick_summary

def quick_summary(self) -> pd.DataFrame

Возвращает краткую сводку по всем группам (реальный alpha, доля отклонений, средние p-value и т.п.).

draw_power_curve

def draw_power_curve(
    self,
    effect_grid: Optional[List[float]] = None,
    effect_type: Literal["absolute", "relative"] = "absolute",
    n_iter: int = 500,
    target_power: float = 0.8,
    groups: Optional[List[str]] = None,
    group_configs: Optional[Dict[str, GroupVisualizationConfig]] = None,
    group_col: str = None,
    lang: Language = None,
    figsize: Tuple[float, float] = (9, 6),
    alpha_line_on: bool = True,
    **kwargs
) -> Tuple[plt.Figure, plt.Axes]

Строит кривые мощности (power curves): зависимость статистической мощности теста от величины эффекта для одной или нескольких групп. Для каждой точки из effect_grid выполняется серия симуляций, после чего оценивается доля отклонений нулевой гипотезы и доверительный интервал.

Параметры

effect_grid (Optional[List[float]]): Сетка значений эффекта для симуляции. Интерпретация зависит от effect_type:
при absolute эффект прибавляется к значениям тестовой группы;
при relative значения тестовой группы умножаются на 1 + effect.

Если None, используется сетка по умолчанию np.linspace(0.0, 0.6, 20).

effect_type (Literal["absolute", "relative"]): Тип синтетического эффекта:
absolute - аддитивный эффект;
relative - относительное изменение через множитель 1 + effect.
n_iter (int): Количество симуляций для каждой точки эффекта.
target_power (float): Уровень желаемой мощности, отображаемый горизонтальной линией.
groups (Optional[List[str]]): Список групп для анализа. Если None, используются все группы.
group_configs (Optional[Dict[str, GroupVisualizationConfig]]): Настройки отображения отдельных групп.
group_col (str): Название колонки с меткой групп. Если не указано, метод пытается определить её через GroupSampler в пайплайне.
lang (Language): Язык подписей графика. Если None, используется язык эксперимента.
figsize (Tuple[float, float]): Размер фигуры.
alpha_line_on (bool): Если True, на графике отображается горизонтальная линия уровня значимости.
kwargs: Дополнительные параметры, передаваемые в simulate_power_for_effect.

Пример использования

import numpy as np
import pandas as pd
import scipy.stats as sps

from aboba.experiment import AbobaExperiment
from aboba.pipeline import Pipeline
from aboba.splitters import GroupSplitter
from aboba.tests import AbsoluteIndependentTTest
from aboba.effect_modifiers import GroupModifier

# Генерируем данные
data = pd.DataFrame({
    "value": np.concatenate([
        sps.norm.rvs(size=1000, loc=0, scale=1),
        sps.norm.rvs(size=1000, loc=0, scale=1),
    ]),
    "b_group": np.concatenate([
        np.repeat(0, 1000),
        np.repeat(1, 1000),
    ]),
})

splitter = GroupSplitter(column="b_group", size=200)
data_pipeline = Pipeline([("splitter", splitter)])
test = AbsoluteIndependentTTest(value_column="value")

exp = AbobaExperiment()

# AA‑группа (без эффекта)
aa = exp.group(
    name="AA",
    test=test,
    data=data,
    data_pipeline=data_pipeline,
    n_iter=500,
).run()

# AB‑группа с синтетическим эффектом
effect = GroupModifier(effects={1: 0.3}, value_column="value", group_column="b_group")
ab = exp.group(
    name="AB, effect=0.3",
    test=test,
    data=data,
    data_pipeline=data_pipeline,
    synthetic_effect=effect,
    n_iter=500,
).run()

summary = exp.quick_summary()
print(summary)

fig, axes = exp.draw()

ExperimentGroup

Исходный код

Класс для представления группы эксперимента

Представляет одну группу внутри AbobaExperiment. Обычно экземпляры создаются методом AbobaExperiment.group(...), а не напрямую.

Инициализация

def __init__(
    self,
    name: str,
    test: BaseTest,
    data: Union[pd.DataFrame, List[pd.DataFrame]],
    data_pipeline: Pipeline,
    synthetic_effect: Optional[EffectModifier] = None,
    n_iter: int = 1,
    joblib_kwargs: Optional[dict] = None
)

Параметры

name (str): Название группы (например, 'control', 'test').
test (BaseTest): Статистический тест для анализа.
data (Union[pd.DataFrame, List[pd.DataFrame]]): Данные для эксперимента.
data_pipeline (Pipeline): Пайплайн обработки данных.
synthetic_effect (Optional[EffectModifier]): Модификатор эффектов для добавления синтетических эффектов. По умолчанию None.
n_iter (int): Количество итераций для запуска теста. По умолчанию 1.
joblib_kwargs (Optional[dict]): Параметры для параллельного выполнения через joblib. По умолчанию None.

Методы

run

def run(self) -> 'ExperimentGroup'

Запускает тест несколько раз параллельно и сохраняет результаты.

Возвращает:

ExperimentGroup: Возвращает self для цепочки вызовов.

get_data

def get_data(self) -> pd.DataFrame

Получает результаты эксперимента в виде DataFrame.

Возвращает:

pd.DataFrame: DataFrame с результатами всех итераций теста.

Примеры использования

Обычно вы работаете с ExperimentGroup, полученным из эксперимента:

exp = AbobaExperiment()
group = exp.group(
    name="AA",
    test=test,
    data=data,
    data_pipeline=pipeline,
    n_iter=500,
).run()

results_df = group.get_data()
print(results_df.head())