Codebook: как описать переменные набора

Codebook: как описать переменные набора

Файл с данными без описания — это набор чисел. Через год даже автор не вспомнит, что означала колонка q7_rec и почему в ней встречаются значения 9.

Codebook закрывает этот разрыв: он объясняет каждую переменную так, чтобы данные можно было использовать без переписки с автором.

Что включить

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

Дополнительно: источник переменной (вопрос анкеты, прибор, расчёт), правила преобразования и связи с другими переменными.

Имена переменных

Имена должны быть короткими, латинскими и осмысленными: age_years, income_month, q3_satisfaction.

Не используйте пробелы и специальные символы: они ломают импорт. Не переименовывайте переменные после публикации данных: старые скрипты перестанут работать.

Метки и типы

Метка — человекочитаемое описание: «Возраст на момент опроса, полных лет». Тип — числовой, строковый, дата, категориальный.

Указывайте, является ли число кодом категории или величиной. Это различие критично: среднее по кодам категорий не имеет смысла.

Единицы измерения

Для каждой количественной переменной укажите единицы: годы, килограммы, рубли, проценты. Без этого невозможно ни сравнение, ни пересчёт.

Если единицы менялись в процессе сбора, опишите, как приведены к одной шкале.

Категории и коды

Перечислите все допустимые значения с расшифровкой: 1 — «полностью согласен», 2 — «скорее согласен» и так далее.

Укажите, есть ли обратные вопросы и как они перекодированы. Иначе пользователь не поймёт, почему значения идут «не по порядку».

Пропуски

Различайте типы пропусков: отказ, «не знаю», неприменимость вопроса, техническая потеря.

Если все они закодированы одним числом (например, 99), это нужно явно указать. Смешение типов пропусков искажает расчёты.

Правила преобразования

Опишите, как получены производные переменные: суммы шкал, категории возраста, индексы. Формулы лучше приложить в виде кода.

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

Формат и хранение

Codebook удобно вести в таблице или в документе с таблицей. Машиночитаемый вариант (DDI, JSON) полезен для больших проектов и репозиториев.

Храните codebook рядом с данными и указывайте версию, к которой он относится.

Проверка соответствия

Сверьте список переменных с фактическим файлом: все ли колонки описаны, нет ли лишних.

Проверьте диапазоны значений: если в описании максимум 120, а в данных 999, это сигнал об ошибке кодирования.

Частые ошибки

• описание не всех переменных;
• отсутствие единиц;
• один код для разных типов пропусков;
• переименование после публикации;
• отсутствие формул производных переменных;
• несоответствие описания и файла;
• codebook без версии.

Как описывать составные шкалы

Для шкал укажите, из каких вопросов она собрана, как считается сумма или среднее и что делать с пропусками.

Если шкала стандартная, дайте ссылку на источник и версию. Собственная шкала требует описания всех пунктов.

Как поддерживать codebook в актуальном состоянии

Обновляйте описание в том же коммите, что и данные. Иначе появляются версии, где описание отстаёт от файла.

Перед публикацией пройдитесь по списку переменных и проверьте, что ничего не пропущено.

Как описать время и даты

Указывайте формат даты и часовой пояс: 2026-03-01, UTC или местное время. Без этого нельзя сопоставить события.

Если дата условна (например, «начало месяца»), отметьте это в описании переменной.

Как описать текстовые поля

Свободный текст сложнее всего: он не имеет фиксированных значений и часто содержит персональные данные.

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

Пример строки codebook

Такой формат читается и человеком, и скриптом. Для больших проектов его можно хранить в CSV и генерировать документацию автоматически.

Кто должен читать codebook

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

Пользователю нужны значения и единицы, рецензенту — методы и ограничения, вам — история преобразований.

Как связать codebook с анкетой

Если данные из опроса, приложите текст вопросов или ссылку на анкету. Номер вопроса без формулировки бесполезен.

Для длинных анкет сделайте таблицу соответствия: переменная, номер вопроса, формулировка.

Что делать с унаследованным codebook

Если набор пришёл от коллеги, сверьте описание с файлом и отметьте расхождения в примечании.

Не переписывайте историю: добавьте раздел «Замечания к исходному описанию».

Чек-лист

• Все переменные описаны.
• Указаны типы и единицы.
• Категории расшифрованы.
• Типы пропусков разделены.
• Производные переменные объяснены.
• Codebook хранится с данными.
• Соответствие файлу проверено.

Частые вопросы

Нужен ли codebook для небольшого набора?

Да, хотя бы в виде таблицы. Без него данные теряют ценность через несколько месяцев.

На каком языке писать?

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

Можно ли включить codebook в статью?

Обычно он слишком велик. Его размещают в репозитории и ссылаются на него из статьи.

Что делать, если данные уже опубликованы без описания?

Добавьте codebook как новую версию или отдельный файл с описанием и укажите это в метаданных.