QuantStats: почему падает HTML‑отчёт с бенчмарком и как это исправить

Разбираем ошибку pandas, из-за которой HTML‑отчёт QuantStats с бенчмарком падает. Воспроизведение и решения: откат до 0.0.70 или обновление до 0.0.74.

При создании HTML‑отчёта (tear sheet) QuantStats для одного актива всё работает. Но стоит добавить бенчмарк — у некоторых пользователей отчёт падает с ошибкой pandas. В этом материале показано минимальное воспроизведение, что именно ломается и как это исправить на поддерживаемых версиях QuantStats.

Воспроизведение проблемы

Проблема возникает при построении HTML‑отчёта с бенчмарком. Пример ниже получает дневные доходности GLD и сравнивает их со SPY в отчёте.

import quantstats as qs
qs.extend_pandas()
asset_ret = qs.utils.download_returns('GLD')
qs.reports.html(
    asset_ret,
    benchmark="SPY",
    title='Gold vs S&P 500',
    output='reports/gld_vs_spy.html'
)

В проблемных версиях выполнение заканчивается исключением вида:

ValueError: The truth value of a Series is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all().

В чём дело

Трассировка указывает на внутренний вызов kelly_criterion в QuantStats и проверку истинности Series в pandas, из‑за которой и срабатывает ошибка. Это поведение зафиксировано в трекере проекта и признано ошибкой в коде. Согласно отчёту, проблема проявляется в версиях 0.0.71, 0.0.72 и 0.0.73. В 0.0.70 всё работает, а в 0.0.74 исправлено.

Как исправить

Есть два надёжных пути. Первый — откатить QuantStats на проверенный релиз, в котором при использовании бенчмарка ошибка не возникает. Второй — обновиться до версии с исправлением.

Чтобы использовать рабочую старую версию:

pip install --upgrade quantstats==0.0.70

Чтобы перейти на версию с исправлением:

pip install --upgrade quantstats==0.0.74

После установки рабочей версии тот же код сгенерирует HTML‑отчёт как и ожидается:

import quantstats as qs
qs.extend_pandas()
asset_ret = qs.utils.download_returns('GLD')
qs.reports.html(
    asset_ret,
    benchmark="SPY",
    title='Gold vs S&P 500',
    output='reports/gld_vs_spy.html'
)

Почему это важно

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

Итоги

Если привычный процесс после обновления библиотеки внезапно перестаёт работать, проверьте трекер задач проекта и убедитесь, не описана ли уже регрессия и не исправлена ли она. Когда важна воспроизводимость, фиксируйте точные версии в окружении. В данном случае отчёты QuantStats с бенчмарком работают в 0.0.70 и снова исправлены в 0.0.74.