Модели HistFactory
NextStat полностью совместим с форматом pyhf JSON workspace. Вы можете взять любой существующий pyhf workspace и запустить его через NextStat без модификаций.
Формат workspace
JSON-файл workspace содержит каналы, образцы, измерения и наблюдения. NextStat парсит этот формат идентично pyhf, производя то же пуассоновское правдоподобие с термами ограничений.
Построение правдоподобия
Отрицательное лог-правдоподобие включает:
- Пуассоновские термы для каждого бина (наблюдаемое vs ожидаемое)
- Гауссовы ограничения для нормировочных и shape-систематик
- Пуассоновские ограничения для shape-факторов
- Вспомогательные термы Barlow-Beeston для побиновых статистических неопределённостей
Поддерживаемые модификаторы
| Модификатор | Тип |
|---|---|
| normfactor | Неограниченная нормировка |
| normsys | Нормировка с гауссовым ограничением |
| histosys | Shape-вариация (гистограммы up/down) |
| shapesys | Побиновое пуассоновское ограничение |
| staterror | Barlow-Beeston lite |
| lumi | Неопределённость светимости |
Поддержка HS3 (ROOT 6.37+)
NextStat нативно загружает HS3 v0.2 (HEP Statistics Serialization Standard) JSON workspace'ы, созданные ROOT 6.37+. Автоопределение формата мгновенно (скан префикса первых ~2 КБ).
# Автоопределение: pyhf vs HS3 nextstat fit --input workspace-postFit_PTV.json # Python: автоопределение model = nextstat.HistFactoryModel.from_workspace(hs3_json) # Python: явно HS3 model = nextstat.HistFactoryModel.from_hs3(hs3_json, analysis="combPdf_obsData")
Также поддерживается HS3-экспорт: model.to_hs3() генерирует HS3 JSON с точками bestfit-параметров, сохраняя оригинальные метаданные.
Коды интерполяции
| Вход | NormSys | HistoSys |
|---|---|---|
| pyhf JSON (по умолчанию) | Code4 (smooth) | Code4p (smooth) |
pyhf JSON + --interp-defaults pyhf | Code1 (exponential) | Code0 (piecewise linear) |
| HS3 JSON (всегда) | Code1 (exponential) | Code0 (piecewise linear) |
Семантика ConstraintTerm
NextStat поддерживает полный набор типов constraint-термов HistFactory, парсимых из XML-метаданных <ConstraintTerm>:
- LogNormal — альфа-преобразование (
normsys_alpha_effective) - Gamma — пуассоновское ограничение для ShapeSys-модификаторов
- Uniform — плоский приор, без штрафа ограничения
- NoConstraint — свободный параметр (поведение normfactor)
Загрузка Arrow / Polars
Создайте HistFactoryModel из колоночных данных (PyArrow, Polars, DuckDB, Spark) или Parquet-файлов:
import nextstat, pyarrow as pa
# Из PyArrow Table
model = nextstat.from_arrow(table, poi="mu")
# Из Parquet
model = nextstat.from_parquet("histograms.parquet", poi="mu")
# Экспорт yields обратно в Arrow
yields = nextstat.to_arrow(model, what="yields")См. документацию Arrow / Polars для требований к схеме и полной справки API.
Паритет с pyhf
NextStat поддерживает строгий контракт паритета с pyhf. Разница NLL на всех тестовых workspace'ах составляет < 1e-8 (детерминистический CPU-режим). Оптимизатор (L-BFGS-B) часто находит лучшие минимумы, чем SLSQP по умолчанию в pyhf, особенно на моделях со 100+ мешающими параметрами.