Справка по формату конфигурации NextStat

стабильно

NextStat использует блочный текстовый формат конфигурации для описания статистического анализа. Формат совместим с конфигами TRExFitter (общая часть), но при этом является полноценной частью NextStat, а не «прослойкой» ради совместимости.

Быстрый старт

# Режим NTUP: построить workspace из ROOT ntuple (TTree)
nextstat import trex-config --config analysis.config --output workspace.json

# Режим HIST: импортировать существующий экспорт HistFactory
nextstat import trex-config --config analysis.config --output workspace.json

# Один шаг: построить гистограммы и workspace
nextstat build-hists --config analysis.config --out-dir output/

# Полный пайплайн через analysis spec (YAML)
nextstat run --config analysis.yaml

Синтаксис

# Комментарии: '#', '//' или '%' (с учетом кавычек)
Key: Value
Key: "quoted value with # inside"

Region: SR
  Variable: mbb
  Binning: 0, 50, 100, 200

Sample: signal
  Тип: SIGNAL
  File: data/signal.root

• Все ключи регистронезависимы (ReadFrom, readfrom, READFROM эквивалентны)
• Значения могут быть в кавычках или без
• Списки задаются в нескольких форматах: a, b, c / [a, b, c] / a; b; c
• Блоки начинаются с ТипБлока: name и продолжаются до следующего заголовка блока
• Блоки могут быть вложенными: Sample внутри Region, Systematic внутри Sample

Режимы

Глобальные ключи

Ключи верхнего уровня (вне блоков) или внутри блока Job:.

Блок Region

Region: SR
  Variable: mbb
  Binning: 0, 50, 100, 150, 200, 300
  Selection: njet >= 4

Форматы Variable + Binning

# Inline (в строке): равномерный биннинг
Variable: "jet_pt", 10, 0, 100    # 10 бинов от 0 до 100

# Inline (в строке): явные границы
Variable: "jet_pt", 0, 50, 100, 200, 500

# Отдельные ключи:
Variable: jet_pt
Binning: 0, 50, 100, 200, 500

Блок Sample

Sample: ttbar
  Тип: BACKGROUND
  File: data/ttbar.root
  Weight: weight_mc * weight_sf
  Regions: SR; CR
  NormFactor: mu_ttbar
  StatError: true

Блок Systematic

Четыре типа: norm, weight, tree, histo.

Общие ключи (для всех типов)

Тип: norm

Systematic: lumi
  Тип: norm
  Samples: all
  Lo: 0.98
  Hi: 1.02

Тип: weight

Systematic: btag
  Тип: weight
  Samples: ttbar
  WeightUp: weight_btag_up
  WeightDown: weight_btag_down

Три способа задать веса (в порядке приоритета):

Тип: tree

Systematic: jer
  Тип: tree
  Samples: signal
  FileUp: data/signal_jer_up.root
  FileDown: data/signal_jer_down.root

Тип: histo

Systematic: model
  Тип: histo
  Samples: signal
  HistoNameUp: signal_model_up
  HistoNameDown: signal_model_down

Блок NormFactor

NormFactor: mu_ttbar
  Samples: ttbar
  Nominal: 1.0
  Min: 0.0
  Max: 10.0

Язык выражений

Поля Variable, Selection и Weight используют выражения, которые компилируются в байткод:

Вложенность и область действия блоков

Region: SR
  Variable: mbb
  Binning: 0, 50, 100, 200

  Sample: signal                    # переопределение только для этого региона
    Weight: weight_mc * 1.1         # меняет вес только в SR

    Systematic: jes_sr_only         # применяется только к "signal" в "SR"
      Тип: norm
      Lo: 0.95
      Hi: 1.05

Sample: signal                      # определение верхнего уровня
  Тип: SIGNAL
  File: data/signal.root
  Weight: weight_mc

• Systematic внутри Sample → Samples по умолчанию берется из родительского Sample
• Sample внутри Region → создает регион-специфичное переопределение и объединяется с Sample верхнего уровня
• Systematic внутри Region → Regions по умолчанию берется из родительского Region

Режим HIST

ReadFrom: HIST
HistoPath: path/to/histfactory_export

# Опционально: фильтровать по выбранным регионам/сэмплам
Region: SR
Region: CR_ttbar

Sample: signal
Sample: ttbar

• HistoPath или CombinationXml указывает на экспорт HistFactory
• Блоки Region и Sample работают как фильтры: сохраняются только перечисленные элементы
• Ключи Variable, Binning, File и Weight не требуются
• Систематики импортируются из XML, не переопределяются

Отчеты покрытия

# Отчет по неизвестным атрибутам
nextstat import trex-config --config analysis.config \
  --output workspace.json \
  --coverage-json coverage.json

# Отчет по компиляции выражений
nextstat import trex-config --config analysis.config \
  --output workspace.json \
  --expr-coverage-json expr_coverage.json

• Отчет покрытия: каждый нераспознанный ключ с номером строки и областью блока
• Отчет по выражениям: скомпилированные выражения, требуемые ветки, ошибки компиляции

Analysis Spec (обертка YAML)

$schema: https://nextstat.ru/schemas/trex/analysis_spec_v0.schema.json
schema_version: trex_analysis_spec_v0

inputs:
  mode: trex_config_txt
  trex_config_txt:
    config_path: analysis.config
    base_dir: null

execution:
  determinism: { threads: 1, parity: true }
  import:
    enabled: true
    output_json: workspace.json
  fit:
    enabled: true
    output_json: fit.json
  profile_scan:
    enabled: true
    start: 0.0
    stop: 5.0
    points: 21
    output_json: scan.json

nextstat run --config analysis.yaml
nextstat validate --config analysis.yaml   # только проверка схемы

Полный пример (NTUP)

ReadFrom: NTUP
TreeName: nominal
Measurement: meas
POI: mu_sig

# ── Regions ──────────────────────────────

Region: SR
  Variable: mbb
  Binning: 0, 50, 100, 150, 200, 300, 500
  Selection: njet >= 4 && nbtag >= 2

Region: CR_ttbar
  Variable: mbb
  Binning: 0, 100, 200, 500
  Selection: njet >= 4 && nbtag == 1

# ── Samples ──────────────────────────────

Sample: data
  Тип: DATA
  File: data/data.root

Sample: signal
  Тип: SIGNAL
  File: data/signal.root
  Weight: weight_mc * weight_pileup
  NormFactor: mu_sig
  StatError: true

Sample: ttbar
  Тип: BACKGROUND
  File: data/ttbar.root
  Weight: weight_mc * weight_pileup
  Regions: SR; CR_ttbar
  NormFactor: mu_ttbar
  StatError: true

# ── Systematics ──────────────────────────

Systematic: lumi
  Тип: norm
  Samples: signal; ttbar
  Lo: 0.98
  Hi: 1.02

Systematic: jes
  Тип: weight
  Samples: signal; ttbar
  WeightUp: weight_jes_up
  WeightDown: weight_jes_down

Systematic: btag
  Тип: weight
  Samples: signal; ttbar
  WeightBase: weight_btag
  WeightUpSuffix: _up
  WeightDownSuffix: _down

Systematic: ttbar_gen
  Тип: tree
  Samples: ttbar
  FileUp: data/ttbar_gen_up.root
  FileDown: data/ttbar_gen_down.root

NormFactor: mu_ttbar
  Samples: ttbar
  Nominal: 1.0
  Min: 0.0
  Max: 10.0