Воспроизводимый анализ в pandas: как превратить ноутбук в pipeline

Коротко

Воспроизводимость начинается не с отдельного сервиса, а с привычки разделять этапы: загрузить данные, проверить контракт, очистить, посчитать, визуализировать и сохранить результат. Каждый шаг должен быть предсказуемым и не менять исходную таблицу незаметно.

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

Раздели анализ на слои

Не обязательно сразу превращать ноутбук в большой Python-пакет. Достаточно начать с четырёх слоёв. load отвечает за источник, clean — за форму и качество, transform — за бизнес-расчёт, report — за итоговую таблицу или график. Тогда изменение фильтра не смешивается с чтением файла и построением визуализации.

Функции лучше скрытых состояний ноутбука

Функция с явным входом и выходом помогает увидеть зависимости. Если очистка использует переменную, созданную пять ячеек назад, её сложно проверить отдельно. Используй .copy() на границе слоя и возвращай новый DataFrame, если это не дорогая операция для текущего объёма.

import pandas as pd

def clean_orders(raw: pd.DataFrame) -> pd.DataFrame:
    orders = raw.copy()
    orders['created_at'] = pd.to_datetime(orders['created_at'], errors='coerce')
    orders['revenue'] = pd.to_numeric(orders['revenue'], errors='coerce')
    orders['channel'] = orders['channel'].fillna('unknown')
    orders = orders.drop_duplicates('order_id')

    if orders['order_id'].isna().any():
        raise ValueError('order_id must not be empty')
    if orders['revenue'].isna().any():
        raise ValueError('revenue contains invalid values')
    return orders

Проверка результата — часть расчёта

Проверки должны ловить не только ошибки типов, но и смысловые поломки. Если после фильтра все заказы исчезли, код может выполниться без исключения. Поэтому полезны минимальный размер выборки, диапазон дат, уникальность ключа и контрольная сумма выручки.

def assert_report_ready(orders: pd.DataFrame, report: pd.DataFrame) -> None:
    assert len(orders) > 0, 'empty orders table'
    assert orders['order_id'].is_unique, 'duplicate order_id'
    assert orders['created_at'].notna().all(), 'invalid dates'
    assert report['revenue'].ge(0).all(), 'negative revenue'
    assert report['channel'].notna().all(), 'missing channel'

Как выглядит главный сценарий

В финальном ноутбуке или скрипте порядок действий читается сверху вниз. Сначала получаем raw-данные, затем вызываем очистку, строим отчёт и отдельно проверяем его. Такой код проще перенести из ноутбука в задачу по расписанию, когда расчёт станет регулярным.

raw_orders = pd.read_csv('data/orders.csv')
orders = clean_orders(raw_orders)

report = (
    orders.groupby('channel', as_index=False)
    .agg(orders=('order_id', 'nunique'), revenue=('revenue', 'sum'))
)

assert_report_ready(orders, report)
report.to_csv('output/channel_report.csv', index=False)

Что ломает воспроизводимость

Самые неприятные проблемы часто не выглядят как ошибки Python. Ноутбук зависит от текущей рабочей директории, использует файл с тем же именем, но другим периодом, или считает показатель после ручного удаления строк. Это нужно вынести из памяти автора в код и описание запуска.

• Не полагайся на порядок выполнения ячеек — перезапускай ядро перед публикацией.
• Не смешивай ручное редактирование CSV с автоматической очисткой.
• Храни параметры периода и фильтры в одном месте.
• Добавляй в результат дату обновления и размер исходной выборки.
• Если расчёт стал регулярным, вынеси его из ноутбука в скрипт или задачу.

Параметры должны быть видны в одном месте

Ноутбук становится трудно повторить, когда период, список каналов и порог фильтра спрятаны в разных ячейках. Собери параметры в начале сценария и передавай их в функции. Тогда коллега может запустить анализ за другой месяц, не меняя формулу внутри расчёта. Это также помогает отличить изменение входного периода от изменения логики.

Параметры результата стоит сохранять вместе с отчётом: date_from, date_to, timezone, версия источника и время запуска. Если через неделю цифра отличается, сначала сравни эти поля. Без них даже правильный результат трудно воспроизвести, потому что неизвестно, на каком срезе он был получен.

Не превращай конфигурацию в десятки переменных. Оставь только то, что действительно меняется между запусками, а константы бизнес-правила вынеси в функцию или документ определения метрики. Хорошая конфигурация отвечает на вопрос «что запускаем», а не повторяет весь код в виде словаря.

CONFIG = {
    'date_from': '2026-07-01',
    'date_to': '2026-08-01',
    'timezone': 'UTC',
    'source_version': 'orders_v3',
}

orders = load_orders(CONFIG['date_from'], CONFIG['date_to'])
clean = clean_orders(orders)
report = build_report(clean)
report['source_version'] = CONFIG['source_version']

Слои помогают понять, где изменилась цифра

Минимальная структура анализа состоит из raw, clean, metrics и output. Raw повторяет вход и не редактируется. Clean приводит типы, удаляет или маркирует плохие строки. Metrics считает показатели на определённом зерне. Output готовит таблицу для графика или передачи команде. Не обязательно создавать отдельный файл для каждого слоя, но границы должны быть видны в коде.

Контрольные числа переходят между слоями. После чтения зафиксируй строки и период, после очистки — строки в quarantine и сумму выручки, после агрегации — число уникальных заказов и покупателей. Если итог изменился, разница должна объясняться переходом между двумя соседними слоями, а не обнаруживаться в последней ячейке.

Такой подход особенно полезен при споре о метрике. Можно показать, что источник прислал 100 000 строк, 2 300 были исключены из-за неверной даты, а итоговая выручка отличается только на сумму этих строк. Обсуждение становится предметным: команда видит не только число, но и путь к нему.

Ноутбук и скрипт решают разные задачи

Ноутбук хорош для исследования: рядом видны график, промежуточная таблица и комментарий, а параметры можно менять интерактивно. Скрипт лучше подходит для регулярного запуска, где нужен один путь от входа к выходу и понятный код возврата. Не нужно выбирать один формат навсегда. Исследуй в ноутбуке, а устойчивую часть расчёта вынеси в импортируемые функции.

Граница проходит не по длине файла, а по повторяемости. Если один и тот же отчёт собирают каждую неделю, ручная последовательность ячеек уже является скрытым процессом. Переведи её в функцию, добавь тест на контрольном файле и оставь ноутбук как объяснение результата, а не как единственное место, где существует логика.

Для запуска по расписанию добавь явные ошибки и логирование. Сообщение «KeyError» мало помогает владельцу отчёта. Сообщение «в источнике orders_v3 отсутствует колонка revenue» позволяет быстро исправить проблему или передать её владельцу данных.

Практика: сделай отчёт повторяемым за один вечер

Возьми любой свежий ноутбук с продуктовым отчётом и запусти его на чистом ядре. Отметь все переменные, которые появились до текущей ячейки, и все места, где DataFrame меняется на месте. Затем вынеси параметры периода, загрузку и очистку в функции. После каждого слоя добавь два-три контрольных числа. Уже этот проход обычно показывает, какие шаги держались на памяти автора.

Положи рядом маленький CSV с известным ответом. Он должен содержать дубль, пропуск и строку на границе периода. Если pipeline даёт ожидаемый результат на таком файле и на реальном срезе, можно переходить к автоматизации. Если нет — сначала исправь определение и тест, не добавляя новый оркестратор.

Финальный результат сохрани вместе с метаданными и ссылкой на входной файл. Читатель будущего отчёта должен понять, какую цифру он видит, за какой период и какой набор правил был применён. Это и есть практическая версия воспроизводимости.

• Перезапустить ноутбук с чистого ядра.
• Собрать параметры и путь к источнику в одном месте.
• Разделить raw, clean, metrics и output.
• Добавить контрольные числа и маленькую фикстуру.
• Сохранить метаданные запуска рядом с результатом.