Как исправить IndexError в pandas HDF5 при столбце 'index'

Почему pandas падает при записи DataFrame в HDF5 (table) из-за столбца 'index'. Объясняем ошибку IndexError и даем простое решение: переименовать колонку.

Когда pandas работает с HDF5 в табличном режиме и спотыкается о столбец с именем «index»

Сериализация pandas DataFrame в HDF5 в формате table обычно рутинна, пока внезапно не перестает быть таковой. Казалось бы, обычная запись через HDFStore.put может упасть с неожиданным IndexError, даже если фрейм чистый и заданы подсказки по размерам строк. Тонкая причина — столбец с буквальным именем index.

Воспроизведение: запись DataFrame в табличном режиме

Путь записи выглядит прямолинейным. DataFrame сохраняется через put с format="table", включёнными data_columns и настроенным min_itemsize для строк.

import pandas as pd
# Пример DataFrame со столбцом с буквальным именем 'index'
meta_frame = pd.DataFrame({
    "index": [0, 1, 2],
    "xPosition": [1.0, 2.0, 3.0],
    "yPosition": [4.0, 5.0, 6.0],
    "approachID": [10, 11, 12]
})
item_key = "some_node"
with pd.HDFStore("example.h5") as h5store:
    h5store.put(item_key, meta_frame, format="table", data_columns=True, min_itemsize={"values": 100})

В такой конфигурации запись может завершиться с ошибкой tuple index out of range. Трассировка указывает на внутренности писателя HDF5 в pandas.

IndexError: tuple index out of range

Файл ".../site-packages/pandas/io/pytables.py", строка 4473, в write_data
new_shape = (nrows,) + self.dtype[names[nindexes + i]].shape

Что именно ломается

Сбой вызывает сам факт наличия столбца с именем index. Достаточно сохранить именно это имя, чтобы воспроизвести ошибку. Переименование в любую другую метку — например, в числовую строку или вариант с заглавной буквы — проблему устраняет.

Решение: переименовать проблемный столбец

Надёжно помогает переименование index в другое имя. Самый щадящий вариант — начать его с заглавной буквы.

import pandas as pd
meta_frame = pd.DataFrame({
    "index": [0, 1, 2],
    "xPosition": [1.0, 2.0, 3.0],
    "yPosition": [4.0, 5.0, 6.0],
    "approachID": [10, 11, 12]
})
# Переименуем только проблемный столбец
safe_frame = meta_frame.rename(columns={"index": "Index"})
item_key = "some_node"
with pd.HDFStore("example.h5") as h5store:
    h5store.put(item_key, safe_frame, format="table", data_columns=True, min_itemsize={"values": 100})

Если удобнее, подойдёт любое иное имя, лишь бы это была не точная строка index. Например, авто-нумерованные или более описательные метки.

Почему это важно для конвейеров данных

Табличный режим HDF5 часто применяется в долгих или автоматизированных задачах. Падение с IndexError глубоко внутри писателя способно сорвать конвейер, особенно когда форма набора и типы кажутся нормальными. Понимание, что причиной может быть одно-единственное имя столбца, экономит время на разборе и помогает держать код записи стабильным для наборов данных, приходящих из разных источников.

Выводы

Если запись в HDF5 в режиме table с pandas падает с «IndexError: tuple index out of range», при том что фрейм в остальном корректен, проверьте, нет ли столбца с буквальным именем index. Переименуйте его, например в Index — это предотвращает падение и не требует менять ни данные, ни параметры записи, включая format="table", data_columns=True и настройки min_itemsize.