Configuration and CLI reference

Use this page when authoring an experiment file or automating a command. For a short runnable path, start with the experiment configuration guide.

DatasetSpec

spec names columns that are not ordinary model features.

target, exposure, and every protected-column name must be non-empty. protected_cols must be unique and cannot overlap target, exposure, claim count, or time. When data loads, every named field must exist. Unknown fields are rejected: use claim_count, not claim_count_col, in spec.

ExperimentConfig

Explicit features must exist, be unique, and exclude every named special column, including protected columns. Automatic feature discovery excludes them for the same reason.

Preprocessing settings

preprocessing.binner and preprocessing.grouper are parameter mappings. The workflow injects exposure_col, claim_count_col, and target_col from spec; do not repeat them.

Configured exposure and claim-count columns are required during preprocessing fit. Values must be finite, exposure must meet the one-day floor (1/366 with 0.1% tolerance), and claim counts must be non-negative. Direct transformer calls without exposure_col use unweighted binning or unit row weights for grouping.

Binner

min_claims requires spec.claim_count. Missing numeric values get a stable Missing category.

Grouper

Similarity uses aggregate claim amount divided by aggregate exposure. Ordered categoricals only merge adjacent levels.

Model kinds

ModelSpec.kind defaults to glm and params defaults to an empty mapping. For direct GLM and GBM models, the workflow derives exposure_col from DatasetSpec.exposure (spec.exposure in YAML). Omit it from model params: an omitted or null value uses the spec, a matching non-null value is accepted, and a conflicting non-null value raises ValueError.

GLM parameters

GBM parameters

Unknown constructor parameters fail rather than being collected by **kwargs.

Nested frequency-severity YAML

spec.claim_count is required. Frequency and severity sub-specs must be direct glm or gbm kinds and cannot nest another frequency-severity model.

models:
  frequency-severity:
    kind: frequency_severity
    frequency:
      kind: glm
      params:
        family: poisson
        link: log
        alpha: 0.001
    severity:
      kind: glm
      params:
        family: gamma
        link: log
        alpha: 0.001

The workflow derives exposure, claim-count, and claim-amount column names from spec. Conflicting non-null exposure_col, claim_count_col, or claim_amount_col values in the outer model's params raise ValueError; omitted or null values use the spec. Frequency fits \(y = \text{claim count}/\text{exposure}\) with exposure weight. Severity fits only positive-claim rows on mean claim size with claim-count weight.

Tuning settings

TuningSpec is optional. Its complete YAML shape is:

tuning:
  n_trials: 30
  calibration_penalty: 2.0
  search_space:
    tweedie-glm:
      alpha:
        type: float
        low: 1.0e-6
        high: 0.1
        log: true
      l1_ratio:
        type: float
        low: 0.0
        high: 1.0
    tweedie-gbm:
      num_leaves:
        type: int
        low: 8
        high: 64
        step: 8
      max_depth:
        type: categorical
        choices: [-1, 4, 6]

A custom model entry replaces that model's built-in search space. It does not merge with the defaults. GLM or GBM siblings without a custom entry keep their existing built-in spaces exactly:

Search-space parameters must be exposed by that model kind's estimator. Unknown model names, unsupported parameters, frequency-severity spaces, empty spaces, empty choices, invalid distributions, and extra fields fail validation. The fixed identity, routing, and seed parameters family, link, objective, tweedie_power, tweedie_variance_power, exposure_col, and random_state cannot appear in a search space.

Explicit Python n_trials= and calibration_penalty= arguments have highest precedence. CLI --trials and --calibration-penalty supply those explicit arguments. Omitted arguments defer first to tuning, then to 20 and 1.0. The sampler's separate random_state=42 API is unchanged.

Split behavior

Configuration exposes a fraction-based temporal split. For a direct cutoff or integer test size in Python, use temporal_split itself.

Random seeds

Three independent seeds control an experiment; set each where it belongs.

Protected-group audit outputs

Each ModelResult.protected_calibration is a mapping from protected-column name to a calibration_table built only from outer-test predictions for that model. Each table keeps the raw subgroup label in group, retains missing labels as a subgroup, and reports exposure, observed and predicted claim amount, pure premiums, and O/P ratio. Multiple protected columns are audited independently, not as intersections.

Provide review-ready categorical or pre-banded groups. Azoic does not infer bins for continuous protected values. These tables are descriptive evidence for review, not a fairness threshold, automated decision, or legal assessment.

Complete YAML shape

Relative data_path values resolve from the YAML file's directory. If this config is saved in examples/, synthetic.parquet means examples/synthetic.parquet.

name: motor-pricing-v1
data_path: synthetic.parquet

spec:
  target: claim_amount
  exposure: exposure
  claim_count: claim_count
  time_col: null
  protected_cols:
    - review_group

features:
  - driver_age
  - vehicle_age
  - region
  - vehicle_brand

preprocessing:
  binner:
    cols: [driver_age, vehicle_age]
    strategy: tree
    max_bins: 6
    min_exposure: 50
    min_claims: 5
    monotonic: false
    random_state: 42
  grouper:
    cols: [region, vehicle_brand]
    strategy: similarity
    max_groups: 6
    min_exposure: 50
    min_claims: 5
    other_label: Other

split: random
test_size: 0.2
random_state: 42
tuning: null

models:
  tweedie-glm:
    kind: glm
    params:
      family: tweedie
      link: log
      tweedie_power: 1.5
      alpha: 0.001
      random_state: 42

  tweedie-gbm:
    kind: gbm
    params:
      objective: tweedie
      tweedie_variance_power: 1.5
      n_estimators: 100
      num_leaves: 31
      learning_rate: 0.05
      random_state: 42

  frequency-severity:
    kind: frequency_severity
    frequency:
      kind: glm
      params:
        family: poisson
        link: log
    severity:
      kind: glm
      params:
        family: gamma
        link: log

CLI commands

Run azoic COMMAND --help for Typer's current option spellings.

Workflow outputs

d2_test is 1 minus deviance_test divided by the null deviance. The null predicts the test set's observed mean rate (total claims / total exposure), using the same exposure-weighted Tweedie deviance at power 1.5. A negative value means worse deviance than that constant-rate null. It is NaN for a claim-free test set or zero null deviance (including a constant positive observed rate).

Run.train_indices and Run.test_indices are immutable tuple[int, ...] values containing the actual fit/evaluation row positions, in their original partition order. All models within a run share those positions. For tuning, TuneResult.run records the final outer partition, not an inner trial split.

Recover rows from the exact input frame without sorting, filtering, or changing its index. The fingerprint covers shape, columns, dtypes, index, values, and categorical vocabulary (including unused levels), category dtype/order, and the ordered flag. Workflow evaluation deep-copies configuration and nested model parameters; public dictionaries and DataFrames remain mutable. Category-aware fingerprints intentionally change, so older runs need fresh evaluation.

Matching seeds or row counts alone cannot establish matching partitions. Comparisons warn once on different fingerprints, target/exposure columns, or holdout membership, naming affected runs without dropping rows. Holdout positions are compared as sets, so a permutation alone does not warn.

train_frame = portfolio.iloc[list(run.train_indices)]
test_frame = portfolio.iloc[list(run.test_indices)]

Convert tuples to a list or integer array: pandas interprets a bare tuple as row/column indexing. CLI export-tariff recalibrates direct GLMs and distilled students on the returned run's training positions only. Student fits use those same positions; diagnostic and distillation-fidelity frames use test positions. The CLI preserves the fitted estimator and holdout and rejects a reloaded dataset whose fingerprint changed after fitting. --no-recalibrate preserves the structural tariff. Library callers choose their calibration frame and must keep distillation fit/validation observations disjoint; distinct frame objects alone do not establish independence (see Reporting and operations).

Run metrics describe raw estimator predictions. If applying a training-derived scale factor later, label those adjusted diagnostics separately.

Validation rules

• ExperimentConfig, ModelSpec, PreprocessingSpec, TuningSpec, and all parameter distributions reject extra fields.
• Data must be non-empty; exposure must be finite and at least one day in years (1/366, with 0.1% tolerance: EXPOSURE_FLOOR = (1/366) * (1 - 0.001)); target and claim count must be non-negative and finite.
• Claim-count and target rows must be zero or positive together.
• Features must exist, be unique, and exclude special columns. Protected columns must be unique, non-empty, present in the data, and distinct from other special columns.
• Temporal splits reject absent or missing time values and keep timestamp ties together.
• Tweedie LightGBM power outside \([1.0, 2.0)\) fails.
• Frequency-severity requires both nested sub-specs and spec.claim_count.
• Tuning rejects unknown models, empty model spaces, unsupported or fixed parameters, invalid scalar distributions, and frequency-severity spaces.
• Preprocessing credibility by claims requires a claim-count column.
• Model prediction frames may omit outcome columns; fitted workflow pipelines supply harmless placeholders and drop them before the final estimator.