Вспомогательные функции

Вспомогательные функции для логирования, визуализации и вычислений.

Логирование

warn_once

Вывод предупреждения один раз

Выводит предупреждение только при первом вызове с данным сообщением. Последующие вызовы с тем же сообщением игнорируются. Полезно для предотвращения дублирования предупреждений в циклах или повторяющихся операциях.

Параметры:

message (str): Текст предупреждения для вывода.

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

from aboba.utils import warn_once

# Первый вызов выведет предупреждение
warn_once("Это предупреждение появится только один раз")

# Повторные вызовы с тем же сообщением будут проигнорированы
for i in range(100):
    warn_once("Это предупреждение появится только один раз")

Визуализация

draw_interval

Исходный код

Визуализация доверительного интервала

Рисует доверительный интервал для разницы между группами. Визуализирует точечную оценку эффекта и границы доверительного интервала.

Параметры:

interval (Tuple[float, float]): Кортеж с нижней и верхней границами доверительного интервала.
point_estimate (float): Точечная оценка эффекта.
title (Optional[str]): Заголовок графика. По умолчанию None.
ax (Optional[matplotlib.axes.Axes]): Оси matplotlib для рисования. Если None, создаются новые. По умолчанию None.

Возвращает:

matplotlib.axes.Axes: Оси с нарисованным графиком.

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

import matplotlib.pyplot as plt
from aboba.utils import draw_interval

# Визуализация доверительного интервала
interval = (-0.5, 2.5)
point_estimate = 1.0

fig, ax = plt.subplots(figsize=(10, 4))
draw_interval(
    interval=interval,
    point_estimate=point_estimate,
    title="95% доверительный интервал для разницы средних",
    ax=ax
)
plt.show()

draw_pvalue_distribution

Исходный код

Визуализация распределения p-value

Рисует гистограмму распределения p-value из множественных тестов. Полезно для анализа мощности тестов и проверки калибровки.

Параметры:

pvalues (List[float]): Список p-value для визуализации.
alpha (float): Уровень значимости для отображения порога. По умолчанию 0.05.
title (Optional[str]): Заголовок графика. По умолчанию None.
ax (Optional[matplotlib.axes.Axes]): Оси matplotlib для рисования. Если None, создаются новые. По умолчанию None.

Возвращает:

matplotlib.axes.Axes: Оси с нарисованным графиком.

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

import numpy as np
import matplotlib.pyplot as plt
from aboba.utils import draw_pvalue_distribution

# Генерируем p-value из множественных тестов
np.random.seed(42)
pvalues = np.random.uniform(0, 1, 1000)

fig, ax = plt.subplots(figsize=(10, 6))
draw_pvalue_distribution(
    pvalues=pvalues,
    alpha=0.05,
    title="Распределение p-value",
    ax=ax
)
plt.show()

Статистические вычисления

calculate_real_alpha

Исходный код

Вычисление реального уровня значимости

Вычисляет реальный уровень значимости (частоту ошибок первого рода) на основе списка p-value. Используется для проверки калибровки статистических тестов.

Параметры:

pvalues (List[float]): Список p-value из множественных тестов.
alpha (float): Номинальный уровень значимости. По умолчанию 0.05.

Возвращает:

float: Реальный уровень значимости (доля p-value меньше alpha).

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

import numpy as np
from aboba.utils import calculate_real_alpha

# Генерируем p-value из тестов без эффекта (должны быть равномерно распределены)
np.random.seed(42)
pvalues_null = np.random.uniform(0, 1, 10000)

# Вычисляем реальный уровень значимости
real_alpha = calculate_real_alpha(pvalues_null, alpha=0.05)
print(f"Номинальный alpha: 0.05")
print(f"Реальный alpha: {real_alpha:.4f}")

# Для хорошо откалиброванного теста реальный alpha должен быть близок к номинальному

Использование для проверки калибровки теста

from aboba.experiment import AbobaExperiment
from aboba.tests import AbsoluteIndependentTTest
from aboba.utils import calculate_real_alpha

# Запускаем множественные эксперименты без эффекта
pvalues = []
for i in range(1000):
    # Создаем данные без эффекта
    experiment = create_experiment_without_effect(seed=i)
    result = experiment.run()
    pvalues.append(result.pvalue)

# Проверяем калибровку
real_alpha = calculate_real_alpha(pvalues, alpha=0.05)
print(f"Реальный уровень ошибок первого рода: {real_alpha:.4f}")
# Должен быть близок к 0.05 для хорошо откалиброванного теста