Описание анализа по шагам: что указать
Описание анализа нужно не для отчёта, а для человека, который через полгода захочет повторить расчёты и получит другие числа. Чем точнее шаги, тем быстрее находится причина расхождения.
Ниже — как описать анализ так, чтобы он воспроизводился.
Что значит «повторить анализ»
Повторить анализ — значит получить те же результаты из тех же данных тем же способом. Это не пересказ выводов и не описание методов в общем виде, а последовательность действий с параметрами. Проверка по шагам напоминает оценку износа аккумулятора: важен не один показатель, а последовательность проверок.
Проверка воспроизводимости — обычная часть подготовки публикации и внутреннего контроля.
Повторение бывает двух видов: полное, когда расчёты выполняются заново на тех же данных, и частичное, когда проверяется лишь отдельный шаг. Для публикации обычно достаточно полного повторения основного анализа и выборочной проверки дополнительных расчётов, которые не влияют на главный вывод.
Отдельно стоит проверить, совпадают ли определения переменных в описании и в скрипте. Если описание говорит «возраст на дату включения», а скрипт берёт возраст на дату выгрузки, результаты разойдутся без видимой ошибки.
Откуда начинается описание
Начало — версия набора данных: файл, дата выгрузки, номер версии, фильтры. Без этого невозможно понять, какие записи участвовали в расчёте.
Если данные менялись после анализа, указывают, какая версия использовалась, а какая актуальна сейчас.
Подготовка данных
Описывают, как из исходной выгрузки получается рабочий набор: какие записи исключены, какие переменные пересчитаны, какие категории объединены.
Каждое преобразование должно быть объяснено и, желательно, сохранено в виде скрипта, а не ручной правки в таблице.
Ручные правки в таблице — главный враг воспроизводимости. Если без них не обойтись, каждую фиксируют в журнале: что изменено, в какой строке, кто и зачем. Такой журнал позволяет повторить правку и объяснить её проверяющему, не восстанавливая ход мыслей по переписке.
Фильтры и условия
Условия отбора записывают в явном виде: возрастные границы, периоды, коды статусов. Формулировка «взрослые участники» допускает разные трактовки.
Для сложных условий полезно указать, сколько записей осталось после каждого шага.
Счётчик записей после каждого условия — простой и надёжный инструмент. Если после фильтра осталось неожиданно много или мало строк, ошибка находится сразу, а не на этапе сравнения итоговых таблиц, когда искать причину намного дороже.
Переменные
Для каждой используемой переменной указывают источник и правило расчёта. Производные переменные описывают формулой.
Если переменная бралась из нескольких источников, фиксируют приоритет.
Порядок шагов
Шаги нумеруют и описывают в том порядке, в котором они выполняются. Порядок влияет на результат: фильтр до или после пересчёта даёт разные числа.
Там, где порядок принципиален, это отмечают отдельно.
Среда и инструменты
Указывают программу и версию, а также библиотеки, если они влияют на расчёт. Иногда достаточно назвать язык и версию.
Для простых расчётов в таблицах описывают формулы и порядок применения.
Промежуточные результаты
Полезно сохранять контрольные числа: сколько записей на каждом шаге, суммы, средние. По ним быстро находится место, где расходятся два варианта анализа.
Контрольные числа прикладывают к описанию.
Контрольные числа удобно хранить рядом со скриптами в виде небольшой таблицы: шаг, число записей, сумма. При повторном запуске их сравнивают построчно, и расхождение указывает на конкретный шаг, а не на весь анализ целиком.
Оформление
Описание делают коротким, но полным: список шагов, файлы, параметры, контрольные числа. Длинные объяснения выносят в приложения.
Если описание занимает больше страницы, его разбивают на разделы по шагам.
Хорошее описание читается как рецепт: шаг, вход, выход, проверка. Оно не требует от читателя знания контекста и не отсылает к переписке. Если для понимания шага нужно спросить автора, шаг описан недостаточно подробно и его стоит переписать.
Проверка коллегой
Лучший тест — попросить коллегу повторить анализ по описанию, не задавая вопросов автору. Все места, где он застрял, переписывают.
Обычно после одной такой проверки описание становится вдвое понятнее.
Хранение описания
Описание хранят рядом со скриптами и версией данных. Если скрипты изменились, описание обновляют в тот же срок.
Расхождение между описанием и скриптами — самая частая причина неудачного повторения.
При сдаче работы описание и скрипты передают вместе. Новый исполнитель начинает с проверки, что расчёты воспроизводятся на его машине: это дешевле, чем обнаружить расхождение через год при подготовке ответа на замечания.
Пример: два разных результата
Две команды анализируют одни данные и получают разные средние. Причина оказывается в том, что одна команда исключила записи с пропуском в одной переменной, а другая — нет.
Описание шагов сразу показывает расхождение: фильтры разные, данные одни.
Чек-лист
- Указана версия набора данных.
- Описана подготовка и фильтры.
- Перечислены производные переменные.
- Шаги пронумерованы в порядке выполнения.
- Указаны среда и версии инструментов.
- Сохранены контрольные числа.
- Коллега повторил анализ по описанию.
- Описание хранится рядом со скриптами.
Частые вопросы
Нужно ли описывать каждую строку кода?
Нет. Достаточно шагов, параметров и файлов, по которым код можно найти и запустить.
Что делать, если анализ выполнялся вручную?
Описать последовательность действий и сохранить промежуточные файлы.
Кто проверяет описание?
Тот, кто не участвовал в анализе. Его задача — повторить шаги без подсказок.
Где хранить описание?
В папке анализа, вместе со скриптами и версией данных.