Python — справка API

Python-пакет nextstatпредоставляет доступ к движку на Rust через привязки PyO3. Все тяжелые вычисления выполняются в Rust, а Python дает удобный API.

Основные функции

nextstat.from_pyhf(json_str: str) → Model

Парсинг строки pyhf JSON workspace в объект NextStat Model.

nextstat.from_histfactory(xml_path: str) → Model

Создание модели из HistFactory XML + ROOT-файлов гистограмм.

Семантика загрузки HistFactory XML

›ShapeSys гистограммы трактуются как относительные побиновые неопределенности и переводятся в абсолютные: σ = rel × nominal.
›StatErrorConfig:Poisson переводит StatError в Barlow-Beeston shapesys, аGaussian в staterror.
›NormalizeByTheory="True": сэмпл получает модификатор lumi, а LumiRelErr передается через конфигурацию измерения.
›NormFactor Val/Low/High → передаётся через конфигурацию параметров измерения (начальные значения и границы).

Унифицированное API (0.9.6+)

Все функции вывода принимают любой применимый тип модели (HistFactoryModel, UnbinnedModel) и диспатчат автоматически. GPU-ускорение управляется единым параметром device="cpu"|"cuda"|"metal". Старые префиксные варианты (unbinned_*, *_gpu) удалены. Все структурированные возвращаемые типы используют TypedDict для автодополнения IDE.

nextstat.fit(model, *, data=None, init_pars=None, device="cpu") → FitResult

Оценка максимального правдоподобия (MLE) через L-BFGS-B. Возвращает параметры наилучшего фита, неопределённости и NLL в минимуме.

nextstat.hypotest(poi_test, model, *, data=None, return_tail_probs=False) → float

Асимптотическая CLs-проверка гипотезы. Диспатчит по типу модели: HistFactory (биннированная) или Unbinned (qμ).

nextstat.hypotest_toys(poi_test, model, *, n_toys=1000, seed=42, expected_set=False, device="cpu") → float | dict

CLs-проверка гипотезы на тоях. Диспатчит по типу модели.

nextstat.profile_scan(model, mu_values, *, data=None, device="cpu", return_curve=False) → ProfileScanResult

Профильный скан правдоподобия. return_curve=True добавляет массивы для графиков (mu_values, q_mu_values, twice_delta_nll).

nextstat.fit_toys(model, params, *, n_toys=1000, seed=42, device="cpu") → list[FitResult]

Унифицированный фит тоев. CPU использует Rayon-параллелизм; GPU — lockstep L-BFGS-B ядра.

nextstat.ranking(model, *, device="cpu") → list[RankingEntry]

Ранжирование нюисанс-параметров (влияние на POI). Диспатчит по типу модели.

nextstat.upper_limit(model, *, method="bisect", alpha=0.05) → float | tuple

Верхний предел. method="bisect" (только наблюдаемый) или method="root" (наблюдаемый + 5 ожидаемых полос).

Поддержка HS3 (ROOT 6.37+)

NextStat нативно загружает HS3 (HEP Statistics Serialization Standard) v0.2 JSON-файлы, созданные ROOT 6.37+. Формат определяется автоматически — флаг не нужен.

HistFactoryModel.from_workspace(json_str) → Model

Автоопределение формата pyhf и HS3. Прозрачно работает с обоими.

HistFactoryModel.from_hs3(json_str, analysis=None, param_points=None) → Model

Явная загрузка HS3 с опциональным выбором анализа и набором точек параметров.

import nextstat

# Автоопределение: работает и с pyhf, и с HS3
json_str = open("workspace-postFit_PTV.json").read()
model = nextstat.HistFactoryModel.from_workspace(json_str)

# Явная загрузка HS3 с выбором анализа
model = nextstat.HistFactoryModel.from_hs3(
    json_str,
    analysis="combPdf_obsData",
    param_points="default_values",
)

result = nextstat.fit(model)

Поддерживаются модификаторы: normfactor, normsys, histosys, staterror, shapesys, shapefactor, lumi. Неизвестные типы молча пропускаются (совместимость с будущими версиями HS3).

Объект Model

model.poi_index() → int

Индекс параметра интереса в векторе параметров.

Объект FitResult

Атрибут	Тип	Описание
bestfit	list[float]	Значения параметров наилучшего фита
uncertainties	list[float]	Неопределённости параметров (на основе гессиана)
nll	float	NLL в минимуме
warnings	list[str]	Предупреждения идентифицируемости: почти сингулярный гессиан (cond > 1e8), не-конечные неопределённости, нулевая диагональ гессиана. Пустой список если модель хорошо идентифицирована.

Профильные доверительные интервалы

Обобщённые профильные CI на основе бисекции для любой LogDensityModel. Корректно асимметричны — без предположения нормальности. Вычисляет {θ : 2*(NLL(θ) - NLL_min) ≤ χ²(1, α)}.

# CI для одного параметра
ci = nextstat.profile_ci(model, fit_result, param_idx=0)
print(f"[{ci['ci_lower']:.3f}, {ci['ci_upper']:.3f}]")

# CI для всех параметров
all_ci = nextstat.profile_ci(model, fit_result)
for c in all_ci:
    print(f"param {c['param_idx']}: [{c['ci_lower']:.3f}, {c['ci_upper']:.3f}]")

Fault Tree MC (CE-IS)

Cross-Entropy Importance Sampling для оценки вероятности редких событий в деревьях отказов. Достигает p∼10⁻⁹ за ~10⁴–10⁵ сценариев вместо ~10¹¹ наивного MC. Только бернуллиевские компоненты.

result = nextstat.fault_tree_mc_ce_is(
    spec,              # FaultTreeSpec dict
    n_per_level=10000,
    seed=42,
)
print(f"P(отказ) = {result['p_failure']:.2e} ± {result['se']:.2e}")
print(f"Уровней: {result['n_levels']}, сценариев: {result['n_total_scenarios']}")

Подмодуль Bayesian

import nextstat

idata = nextstat.bayes.sample(
    model,
    n_chains=2,
    n_warmup=500,
    n_samples=1000,
    seed=42,
    target_accept=0.8,
)
# Возвращает arviz.InferenceData

Подмодуль визуализации

import numpy as np
import nextstat

scan = np.linspace(0.0, 5.0, 101)
cls_art = nextstat.viz.cls_curve(model, scan, alpha=0.05)
nextstat.viz.plot_cls_curve(cls_art, title="CLs Brazil band")

mu = [0.0, 0.5, 1.0, 2.0]
prof_art = nextstat.viz.profile_curve(model, mu)
nextstat.viz.plot_profile_curve(prof_art, title="Профильное правдоподобие")

Gymnasium / RL-среда

Gymnasium-совместимая среда для оптимизации выходов сигнала через обучение с подкреплением. Требуются gymnasium и numpy.

from nextstat.gym import HistFactoryEnv

env = HistFactoryEnv(
    workspace_json=json_str,
    channel="SR",
    sample="signal",
    reward_metric="z0",       # "nll", "q0", "z0", "qmu", "zmu"
    mu_test=5.0,
    max_steps=128,
    action_scale=0.05,
    action_mode="logmul",     # "add" or "logmul"
)

obs, info = env.reset(seed=42)
obs, reward, terminated, truncated, info = env.step(action)

Параметр	Описание
reward_metric	Метрика награды: "nll", "q0", "z0", "qmu" или "zmu"
action_mode	"add" (аддитивно) или "logmul" (лог-мультипликативно)
max_steps	Длина эпизода до обрезки

Фабричная функция: make_histfactory_env(workspace_json, channel, sample, reward_metric)

Клиент удалённого сервера

Чистый Python HTTP-клиент для удалённого nextstat-server экземпляра. Требуется httpx.

Основное

nextstat.remote.connect(url, timeout=300) → NextStatClient

Создание клиента. Поддерживает контекстный менеджер.

client.fit(workspace, *, model_id=None, gpu=True) → FitResult

Удалённый MLE-фит. Передайте workspace (dict/JSON) или model_id из кеша.

client.ranking(workspace, *, model_id=None, gpu=True) → RankingResult

Удалённый ранкинг мешающих параметров. Поддерживает model_id.

client.health() → HealthResult

Здоровье сервера (статус, версия, uptime, устройство, счётчики, кешированные модели).

Пакетные операции

client.batch_fit(workspaces, gpu=True) → BatchFitResult

Фит до 100 workspace в одном запросе. Возвращает .results (список FitResult | None).

client.batch_toys(workspace, n_toys=1000, seed=42, gpu=True) → BatchToysResult

GPU-ускоренный фиттинг тоев. Возвращает .results и .n_converged.

Кеш моделей

client.upload_model(workspace, name=None) → str

Загрузка в LRU-кеш. Возвращает model_id (SHA-256).

client.list_models() → list[ModelInfo]

Список кешированных моделей (id, имя, параметры, каналы, возраст, хиты).

client.delete_model(model_id) → bool

Удаление модели из кеша.

import nextstat.remote as remote

client = remote.connect("http://gpu-server:3742")

# Один фит
result = client.fit(workspace_json)
print(result.bestfit, result.nll, result.converged)

# Кеш моделей: загрузите один раз, фитите много раз без повторного парсинга
model_id = client.upload_model(workspace_json, name="my-analysis")
result = client.fit(model_id=model_id)  # примерно в 4 раза быстрее

# Пакетный фит
batch = client.batch_fit([ws1, ws2, ws3])
for r in batch.results:
    print(r.nll if r else "ошибка")

# Батч-тои (GPU-ускоренный)
toys = client.batch_toys(workspace_json, n_toys=10_000, seed=42)
print(f"{toys.n_converged}/{toys.n_toys} сошлось")

# Ранкинг
ranking = client.ranking(workspace_json)
for e in ranking.entries:
    print(f"{e.name}: Δμ = {e.delta_mu_up:+.3f} / {e.delta_mu_down:+.3f}")

Выбрасывает NextStatServerError(status_code, detail) при не-2xx HTTP-ответах. Типы результатов: FitResult, RankingResult, BatchFitResult, BatchToysResult, ModelInfo.

GARCH / Стохастическая волатильность

Модели волатильности для финансовых временных рядов. Доступны через модуль nextstat.volatility или напрямую из nextstat._core.

nextstat.volatility.garch(ys, *, max_iter=1000, tol=1e-6, alpha_beta_max=0.999, min_var=1e-18) → dict

MLE гауссовой GARCH(1,1). Возвращает: params ({mu, omega, alpha, beta}), conditional_variance, conditional_sigma, log_likelihood, converged.

nextstat.volatility.sv(ys, *, max_iter=1000, tol=1e-6, log_eps=1e-12) → dict

Приближённая SV через log(χ²₁) + Kalman MLE. Возвращает: params ({mu, phi, sigma}), smoothed_h, smoothed_sigma, log_likelihood, converged.

Низкоуровневые (без обёртки): nextstat._core.garch11_fit(), nextstat._core.sv_logchi2_fit()

from nextstat.volatility import garch, sv

returns = [0.01, -0.02, 0.005, 0.03, -0.015, 0.002, -0.04, 0.035]

# GARCH(1,1)
g = garch(returns)
print(f"omega={g['params']['omega']:.4f}, alpha={g['params']['alpha']:.4f}, beta={g['params']['beta']:.4f}")
print(f"Условная sigma: {g['conditional_sigma'][:5]}")

# Стохастическая волатильность
s = sv(returns)
print(f"phi={s['params']['phi']:.4f}, sigma_eta={s['params']['sigma']:.4f}")
print(f"Сглаженная sigma: {s['smoothed_sigma'][:5]}")

Нейронные PDF (--features neural)

Классы nextstat.FlowPdf и nextstat.DcrSurrogate доступны при сборке с --features neural. Позволяют вычислять ONNX-backed flow из Python напрямую.

FlowPdf

import nextstat
import numpy as np

# Загрузка предобученного flow из манифеста
flow = nextstat.FlowPdf.from_manifest("models/signal_flow/flow_manifest.json")

print(f"Контекст-параметров: {flow.n_context()}")
print(f"Наблюдаемые: {flow.observable_names()}")
print(f"Поправка нормировки: {flow.log_norm_correction():.6f}")

# Вычисление log p(x) для массива событий
events = np.array([5100.0, 5200.0, 5300.0, 5400.0])
params = np.array([])  # безусловный flow — нет контекст-параметров

log_probs = flow.log_prob_batch(events, params)
print(f"log p(x): {log_probs}")

# Обновление нормировки (Gauss-Legendre квадратура)
flow.update_normalization(bounds=(5000.0, 6000.0), order=64)

DcrSurrogate

import nextstat
import numpy as np

# Загрузка DCR-суррогата
dcr = nextstat.DcrSurrogate.from_manifest("models/bkg_dcr/flow_manifest.json")

print(f"Процесс: {dcr.process_name()}")
print(f"Систематики: {dcr.systematic_names()}")
print(f"Допуск нормировки: {dcr.norm_tolerance():.4f}")

# Вычисление log p(x | α) для заданных систематик
events = np.array([5100.0, 5200.0, 5300.0])
alpha = np.array([0.5, -0.3])  # значения jes_alpha, jer_alpha

log_probs = dcr.log_prob_batch(events, alpha)

# Валидация нормировки относительно шаблона
is_ok = dcr.validate_nominal_normalization(rtol=0.01)

Метод	Класс	Описание
from_manifest(path)	Оба	Загрузка из flow_manifest.json + ONNX
log_prob_batch(events, params)	Оба	log p(x\|θ) для массива событий
update_normalization()	Оба	Пересчёт нормировки (GL-квадратура)
n_context()	FlowPdf	Число контекст-параметров (0 = безусловный)
validate_nominal_normalization()	DcrSurrogate	Проверка нормировки относительно шаблона

GLM — Gamma и Tweedie

nextstat.gamma_glm(y, X, *, include_intercept=True)

Gamma GLM с log-связкой. Возвращает dict с params, alpha (форма), se, nll.

nextstat.tweedie_glm(y, X, *, p=1.5, include_intercept=True)

Tweedie Пуассон-Гамма GLM с log-связкой. Степень p ∈ (1, 2). Обрабатывает нули. Возвращает dict с params, phi, p.

Теория экстремальных значений (EVT)

nextstat.gev_fit(data) → dict

GEV для блочных максимумов. Параметры: mu, sigma, xi. Статический: GevModel.return_level(params, T).

nextstat.gpd_fit(exceedances) → dict

GPD для пиков над порогом. Параметры: sigma, xi. Статический: GpdModel.quantile(params, p) для VaR/ES.

Мета-анализ

nextstat.meta_fixed(estimates, se, *, labels=None, conf_level=0.95) → dict

Мета-анализ с фиксированными эффектами (inverse-variance). Возвращает pooled-оценку, ДИ, гетерогенность (Q, I², H², τ²), данные для forest plot.

nextstat.meta_random(estimates, se, *, labels=None, conf_level=0.95) → dict

Мета-анализ со случайными эффектами (DerSimonian–Laird). Та же структура возврата, что и meta_fixed.

Анализ выживаемости

nextstat.kaplan_meier(times, events, *, conf_level=0.95) → dict

Непараметрическая оценка КМ с дисперсией Гринвуда и log-log ДИ.

nextstat.log_rank_test(times, events, groups) → dict

Лог-ранг тест Мантеля-Кокса для 2+ групп. Возвращает chi², df, p-value, наблюдаемые/ожидаемые по группам.

nextstat.survival.cox_ph.fit(times, events, x, *, ties="efron", robust=True) → CoxPhFit

Cox PH с Efron/Breslow, робастные sandwich SE. .hazard_ratio_confint().

Отток / Подписки

nextstat.churn_generate_data(n_customers, *, n_cohorts=6, max_time=24.0, seed=42) → dict

Детерминированный синтетический SaaS-датасет оттока с ковариатами и назначением лечения.

nextstat.churn_retention(times, events, groups, *, conf_level=0.95) → dict

Стратифицированный КМ по группам + лог-ранг сравнение.

nextstat.churn_risk_model(times, events, covariates, names) → dict

Cox PH отношения рисков с ДИ для факторов оттока.

nextstat.churn_uplift(times, events, treated, covariates, *, horizon=12.0) → dict

AIPW каузальный uplift с чувствительностью Розенбаума (ATE, SE, ДИ, gamma_critical).

nextstat.churn_diagnostics(times, events, groups, *, treated=[], covariates=[], covariate_names=[], trim=0.01) → dict

Trust gate качества данных: доля цензурирования по сегментам, баланс ковариат (SMD), перекрытие propensity, достаточность выборки. Возвращает trust_gate_passed + предупреждения.

nextstat.churn_cohort_matrix(times, events, groups, period_boundaries) → dict

Когортная матрица удержания (life-table). Период-удержание, кумулятивное удержание, at-risk/events/censored по когортам.

nextstat.churn_compare(times, events, groups, *, correction="benjamini_hochberg", alpha=0.05) → dict

Попарное сравнение сегментов: лог-ранг + HR proxy + коррекция Бенджамини-Хохберга / Бонферрони.

nextstat.churn_uplift_survival(times, events, treated, *, covariates=[], horizon=12.0, eval_horizons=[3,6,12,24], trim=0.01) → dict

Survival-native uplift: RMST, IPW-взвешенный КМ, ΔS(t) по горизонтам. Тримминг propensity + ESS отчёт.

nextstat.churn_bootstrap_hr(times, events, covariates, names, *, n_bootstrap=1000, seed=42, conf_level=0.95, ci_method="percentile", n_jackknife=None) → dict

Параллельный бутстрап Cox PH hazard ratios с перцентильными или BCa ДИ. ci_method: "percentile" (по умолчанию) или "bca". n_jackknife задаёт размер выборки для оценки BCa-ускорения. Возвращает hr_point, hr_ci_lower/upper, покоэффициентную ci_diagnostics с эффективным методом и причиной fallback.

nextstat.churn_ingest(times, events, *, groups=None, treated=None, covariates=[], covariate_names=[], observation_end=None) → dict

Валидация и очистка массивов клиентов: удаление невалидных строк, цензурирование по observation_end. Возвращает чистый датасет + n_dropped + предупреждения.

Фармакометрика

OneCompartmentOralPkModel(times, y, *, dose, bioavailability=1.0, error_model="additive", sigma=1.0, lloq=None, lloq_policy="ignore")

1-компартментная пероральная PK с абсорбцией первого порядка. .predict(params), .nll(params).

TwoCompartmentIvPkModel(times, y, *, dose, error_model="additive", sigma=1.0, lloq=None)

2-компартментная IV болюс (CL, V1, V2, Q). Аналитическое биэкспоненциальное решение.

TwoCompartmentOralPkModel(times, y, *, dose, error_model="additive", sigma=1.0, lloq=None)

2-компартментная пероральная (CL, V1, V2, Q, Ka). Аналитическое триэкспоненциальное решение.

DosingRegimen.iv_bolus(amt, time) | .oral(amt, time) | .infusion(amt, time, duration)

Построение схем дозирования (одно-/многократные, смешанные пути). Используется всеми PK-моделями для профилей концентрация-время.

NonmemDataset.from_csv(path) → NonmemDataset

Парсинг NONMEM CSV (ID, TIME, DV, AMT, EVID, MDV, CMT, RATE). Автоконвертация записей дозирования в DosingRegimen по субъектам.

FoceEstimator.focei(model, data, omega) | .foce(model, data, omega)

Условная оценка первого порядка (с/без взаимодействия). Оптимизация ETA по субъектам + обновление популяционных параметров. Приближение Лапласа.

OmegaMatrix.from_diagonal(variances) | .from_correlation(sds, corr) | .from_covariance(matrix)

Полная Ω дисперсионно-ковариационная через факторизацию Холецкого (Ω = L·Lᵀ). Эффективные inv_quadratic() и log_det().

SaemEstimator(model, data, omega, *, n_burn=300, n_iter=200) → FoceResult

Стохастический аппроксимационный EM (класс Monolix). MH E-шаг с адаптивным proposal, M-шаг в замкнутой форме. SaemDiagnostics: acceptance rates, OFV trace.

ScmEstimator(estimator, data, covariates, *, alpha_forward=0.05, alpha_backward=0.01)

Пошаговое ковариатное моделирование: прямой отбор + обратное исключение по ΔOFV. Полный аудит-трейс с p-значениями и коэффициентами.

vpc_1cpt_oral(result, data, *, n_sim=200, n_bins=10) → VpcResult

Визуальные предсказательные проверки: симуляция реплик, биннинг по времени, квантильные интервалы предсказания.

gof_1cpt_oral(result, data) → GofResult

Диагностика качества подгонки: PRED, IPRED, IWRES, CWRES по наблюдениям.

EmaxModel(ec50, emax) | SigmoidEmaxModel(ec50, emax, gamma) | IndirectResponseModel(kin, kout, imax, ic50, type=1..4)

PD-модели: прямой Emax, уравнение Хилла, IDR типов I–IV (ОДУ через адаптивный RK45). PkPdLink для интерполяции концентрации PK→PD.

rk45(system, y0, t_span, *, rtol=1e-6, atol=1e-9) | esdirk4(system, y0, t_span)

Адаптивные ОДУ-солверы: Дорманд-Принс 4(5) для нежёстких, L-устойчивый SDIRK2 для жёстких систем (транзитные компартменты ktr > 100).

NlmeArtifact(result, *, scm=None, vpc=None, gof=None, bundle=None) → JSON/CSV

Единая сериализуемая структура всех результатов оценки. CSV-экспорт фиксированных/случайных эффектов, GOF, VPC, SCM-трейса. RunBundle фиксирует провенанс (версия, git, toolchain, сиды).

Гибридные модели (биннированные + небиннированные)

HybridModel.from_models(binned, unbinned, poi_from="binned") → HybridModel

Объединяет HistFactoryModel и UnbinnedModel в единое правдоподобие с общими параметрами по имени. n_shared(), poi_index(), with_fixed_param().

Сэмплирование / NUTS

nextstat.sample(model, *, n_chains=4, n_warmup=500, n_samples=1000, seed=42, max_treedepth=10, target_accept=0.8) → dict

NUTS (No-U-Turn Sampler). Принимает также Posterior. Возвращает цепи, диагностику и ArviZ-совместимый вывод.

nextstat.map_fit(posterior) → FitResult

MAP-оценка для байесовских апостериорных распределений.

Тестовые данные (Toy Data)

nextstat.asimov_data(model, params) → list[float]

Asimov-датасет (ожидаемые отсчёты).

nextstat.poisson_toys(model, params, *, n_toys=1000, seed=42) → list[list[float]]

Пуассоновские флуктуированные тестовые датасеты.

nextstat.fit_toys(model, params, *, n_toys=1000, seed=42) → list[FitResult]

Параллельный фит toy-датасетов на CPU (Rayon; переиспользование ленты).

nextstat.unbinned_fit_toys(model, params, *, n_toys=1000, seed=42, init_params=None, max_retries=3, max_iter=5000, compute_hessian=False) → list[FitResult]

Генерация и фит пуассоновских toy для небиннированных моделей (CPU параллелизм). Тёплый старт от MLE θ̂, повтор с jitter, плавное расширение границ. Гессиан по умолчанию пропущен для скорости; установите compute_hessian=True когда нужны pulls параметров.

GPU-ускорение

nextstat.has_cuda() → bool | nextstat.has_metal() → bool

Проверка доступности бэкендов CUDA (NVIDIA) или Metal (Apple Silicon) во время выполнения.

nextstat.fit_toys_batch_gpu(model, params, *, n_toys=1000, seed=42, device="cpu") → list[FitResult]

Батч-фит toy на GPU. device="cuda" (f64, NVIDIA), "metal" (f32, Apple Silicon) или "cpu" (Rayon).

Режимы вычислений (Parity / Fast)

nextstat.set_eval_mode("fast" | "parity") | nextstat.get_eval_mode() → str

fast (по умолчанию): наивное суммирование, SIMD/Accelerate/CUDA. parity: суммирование Кахана для детерминированной pyhf-совместимости. Накладные расходы <5%.

nextstat.set_threads(n: int) → bool

Настройка глобального пула потоков Rayon (best-effort). Установите 1 для полной детерминированности в режиме parity.

Ордниальная регрессия

OrderedLogitModel(x, y, *, n_levels) | OrderedProbitModel(x, y, *, n_levels)

Модели пропорциональных шансов (logit) и ordered probit для порядковых исходов. Обёртки: nextstat.ordinal.logit(), .probit().

Иерархические / смешанные модели

LmmMarginalModel(x, y, *, include_intercept, group_idx, n_groups, random_slope_feature_idx)

Гауссова смешанная модель (маргинальное правдоподобие).

ComposedGlmModel.linear_regression(...) | .logistic_regression(...) | .poisson_regression(...)

Иерархические GLM через статические конструкторы: случайные интерсепты, случайные наклоны, коррелированные эффекты (LKJ априорное), нецентрированная параметризация.

GARCH / Стохастическая волатильность

nextstat.volatility.garch(ys, *, max_iter=1000, tol=1e-6) → dict

Фит гауссовой GARCH(1,1) по MLE. Возвращает params (mu, omega, alpha, beta), conditional_variance, conditional_sigma, log_likelihood.

nextstat.volatility.sv(ys, *, max_iter=1000, tol=1e-6) → dict

Приближённая стохастическая волатильность через log(χ²₁) + Kalman MLE. Возвращает params (mu, phi, sigma), smoothed_h, smoothed_sigma.

Утилиты

nextstat.ols_fit(x, y, *, include_intercept=True) → list[float]

Аналитическая OLS-регрессия.

nextstat.rk4_linear(a, y0, t0, t1, dt) → dict

RK4 ОДУ-солвер для линейных систем.

nextstat.has_accelerate() → bool

Проверка доступности бэкенда Apple Accelerate.

Arrow / Parquet авторинг (nextstat.arrow_io)

Валидация схем и запись манифестов. Требует pyarrow (pip install "nextstat[io]").

nextstat.arrow_io.validate_histogram_table(table) → HistogramTableStats

Валидация контракта таблицы гистограмм.

nextstat.arrow_io.validate_modifiers_table(table) → ModifiersTableStats

Валидация контракта таблицы модификаторов (биннированный Parquet v2).

nextstat.arrow_io.write_histograms_parquet(table, path, *, compression="zstd", write_manifest=True, ...) → dict

Запись Parquet + опциональный манифест JSON; возвращает словарь манифеста.

nextstat.arrow_io.validate_histograms_parquet_manifest(manifest, *, check_sha256=True) → None

Валидация манифеста относительно Parquet-файла.

nextstat.arrow_io.load_parquet_as_histfactory_model(path, *, poi="mu", observations=None) → HistFactoryModel

Валидация Parquet-схемы через PyArrow, затем вызов nextstat.from_parquet().

nextstat.arrow_io.load_parquet_v2_as_histfactory_model(yields_path, modifiers_path, ...) → HistFactoryModel

Валидация Parquet v2, затем вызов nextstat.from_parquet_with_modifiers().

nextstat.arrow_io.validate_event_table(table) → EventTableStats

Валидация контракта небиннированной таблицы событий.

nextstat.arrow_io.write_events_parquet(table, path, *, observables=None, compression="zstd") → dict

Запись небиннированной таблицы событий в Parquet с метаданными NextStat.

Замена TREx (nextstat.analysis)

nextstat.analysis.read_root_histogram(root_path, hist_path, *, flow_policy="drop") → dict

Чтение ROOT TH1 гистограммы. Свёртка under/overflow в крайние бины. Гарантирует sumw2.

nextstat.analysis.read_root_histograms(root_path, hist_paths, *, flow_policy="drop") → dict[str, dict]

Чтение нескольких гистограмм из одного ROOT-файла.

nextstat.analysis.eval_expr(expr, env, *, n=None) → np.ndarray

Векторизованное вычисление TREx-стиль выражений. env — словарь имён переменных → 1D массивы/скаляры.

Миграция TRExFitter (nextstat.trex_config)

nextstat.trex_config.parse_trex_config(text, *, path=None) → TrexConfigDoc

Разбор .config-файла TRExFitter из строки.

nextstat.trex_config.parse_trex_config_file(path) → TrexConfigDoc

Разбор .config-файла с диска.

nextstat.trex_config.trex_doc_to_analysis_spec_v0(doc, ...) → (dict, dict)

Конвертация конфига TREx в analysis spec v0. Возвращает (spec, report); неподдерживаемые ключи фиксируются в отчёте.

nextstat.trex_config.trex_config_file_to_analysis_spec_v0(config_path, ...) → (dict, dict)

Обёртка: разбор файла → конвертация → (spec, report).

nextstat.trex_config.dump_yaml(obj) → str

Детерминированный минимальный YAML-эмиттер (без внешних зависимостей).

Аудит / Run Bundles (nextstat.audit)

nextstat.audit.environment_fingerprint() → dict[str, Any]

Компактный отпечаток окружения для воспроизводимости (без приватных данных).

nextstat.audit.write_bundle(bundle_dir, *, command, args, input_path, output_value, tool_version=None) → None

Запись воспроизводимого run bundle в директорию (Python-аналог CLI --bundle).

Рендеринг отчётов (nextstat.report)

nextstat.report.render_report(input_dir, *, pdf, svg_dir, corr_include=None, corr_exclude=None, corr_top_n=None) → None

Рендеринг PDF отчёта (+ опциональные SVG) из директории артефактов. Требует matplotlib.

CLI: python -m nextstat.report render --input-dir ... --pdf ... [--svg-dir ...]

Валидационный отчёт (nextstat.validation_report)

CLI: python -m nextstat.validation_report render --input validation_report.json --pdf out.pdf. Требует matplotlib.

Дифференцируемый слой (nextstat.torch)

PyTorch autograd.Function обёртки для сквозного дифференцируемого HEP-инференса. Два GPU-бэкенда (CUDA f64, Metal f32) плюс CPU.

CUDA путь (zero-copy)

nextstat.torch.create_session(model, signal_sample_name="signal") → DifferentiableSession

Создание CUDA-сессии для дифференцируемого NLL (требует --features cuda).

nextstat.torch.nll_loss(signal_histogram, session, params=None) → torch.Tensor

Дифференцируемый NLL (zero-copy). signal_histogram должен быть contiguous CUDA float64.

nextstat.torch.create_profiled_session(model, signal_sample_name="signal", device="auto")

Создание GPU-сессии для профилированных тестовых статистик. Возвращает ProfiledDifferentiableSession (CUDA) или MetalProfiledDifferentiableSession.

nextstat.torch.profiled_q0_loss / profiled_z0_loss / profiled_qmu_loss / profiled_zmu_loss

Дифференцируемые профилированные q₀, Z₀ = √q₀, qμ, Zμ = √qμ.

nextstat.torch.batch_profiled_q0_loss / batch_profiled_qmu_loss

Батч q₀ по нескольким гистограммам / qμ для нескольких значений μ.

nextstat.torch.signal_jacobian(signal_histogram, session) → torch.Tensor

Извлечение ∂q₀/∂signal без autograd. NumPy вариант: signal_jacobian_numpy().

Metal путь (f32)

MetalProfiledDifferentiableSession(model, signal_sample_name)

Metal GPU-сессия для профилированных тестовых статистик (f32). Сигнал загружается через CPU.

Высокоуровневые хелперы

nextstat.torch.SignificanceLoss(model, signal_sample_name="signal", *, device="auto", negate=True, eps=1e-12)

ML-дружественная обёртка потерь вокруг профилированного Z₀. По умолчанию −Z₀ (для SGD минимизации).

nextstat.torch.SoftHistogram(bin_edges, bandwidth="auto", mode="kde")

Дифференцируемое бинирование (KDE/sigmoid) для построения сигнальной гистограммы для SignificanceLoss.

MLOps интеграция (nextstat.mlops)

nextstat.mlops.metrics_dict(fit_result, *, prefix="", include_time=True, extra=None) → dict[str, float]

Плоский словарь из FitResult для логгеров экспериментов (W&B, MLflow, Neptune).

nextstat.mlops.significance_metrics(z0, q0=0.0, *, prefix="", step_time_ms=0.0) → dict[str, float]

Метрики по шагам для логирования тренировочного цикла.

nextstat.mlops.StepTimer

Лёгкий таймер: .start(), .stop() → float (мс).

Интерпретируемость (nextstat.interpret)

Ранжирование влияния систематик в стиле ML Feature Importance.

nextstat.interpret.rank_impact(model, *, gpu=False, sort_by="total", top_n=None, ascending=False) → list[dict]

Таблица влияния. Каждый dict: name, delta_mu_up/down, total_impact, pull, rank.

nextstat.interpret.rank_impact_df(model, **kwargs) → pd.DataFrame

То же, вывод pandas (требует pandas).

nextstat.interpret.plot_rank_impact(model, *, top_n=20, gpu=False, ...) → matplotlib.Figure

Горизонтальная диаграмма влияния систематик (требует matplotlib).

Агентный анализ (nextstat.tools)

Определения инструментов для LLM-управляемого стат. анализа. Совместим с OpenAI function calling, LangChain и MCP.

nextstat.tools.get_toolkit(*, transport="local", server_url=None, timeout_s=10.0) → list[dict]

OpenAI-совместимые определения для 9 операций.

nextstat.tools.execute_tool(name, arguments, ...) → dict

Выполнение вызова локально или через сервер. Возвращает {ok, result, error, meta}.

nextstat.tools.get_langchain_tools() → list[StructuredTool]

LangChain адаптер (требует langchain-core).

nextstat.tools.get_mcp_tools() → list[dict] | handle_mcp_call(name, arguments) → dict

MCP определения инструментов и диспетчер.

Суррогатная дистилляция (nextstat.distill)

Генерация обучающих данных для нейронных суррогатов правдоподобия. NextStat — ground-truth оракул; суррогат обеспечивает наносекундный инференс.

nextstat.distill.generate_dataset(model, n_samples=100_000, *, method="sobol", ...) → SurrogateDataset

Сэмплирование пространства параметров и вычисление NLL + градиент. Методы: "sobol", "lhs", "uniform", "gaussian".

nextstat.distill.train_mlp_surrogate(ds, *, hidden_layers=(256,256,128), epochs=100, ...) → nn.Module

MLP-тренер с Sobolev loss.

nextstat.distill.to_torch_dataset / to_numpy / to_npz / from_npz / to_parquet

Хелперы экспорта/импорта для PyTorch DataLoader, NumPy, .npz и Parquet.

nextstat.distill.predict_nll(surrogate, params_np) → ndarray

Вычисление суррогата на сырых параметрах.