Settings Reference¶

Complete reference for all training, evaluation and threshold settings.

For what each setting means, a worked example, and how the settings interact with each other, see the Settings Guide.

TrainSettings¶

Required Parameters¶

Optional Parameters¶

Example: TrainSettings¶

# Minimum required

out_folder: my_model

train_files:

  - /path/to/train.csv

# With all options

n: 10

out_folder: my_model

max_depth: 100

frac_eval_cat: 0.5

max_eval_fit: 1000

min_eval_fit: 50

n_dims: 3

n_cat: 5

calcs_per_dim: 5000

score_method: diff_dir_1.5

smoothing: 0.0

leaf_score: log_odds

leaf_alpha: 0.5

min_split_improvement: 0.0

pair_corr_filter: true

pair_corr_min_main: 0.9

pair_corr_max_features: null

spore_diff: 1.0

adaptive_n_rep: true

n_rep: 5

train_files:

  - /path/to/train.csv

!!! note "max_parallel_where is not a training setting" It only exists in EvalSettings and is used for SQL batching during evaluation.

EvalSettings¶

Required Parameters¶

Optional Parameters¶

Example: EvalSettings¶

# Minimum required

in_folders:

  - model

out_folder: results

test_files:

  - /path/to/test.csv

# With all options

in_folders:

  - model_v1

  - model_v2

out_folder: results

out_file: predictions.csv

keep_cols:

  - customer_id

  - date

max_parallel_where: 500

test_files:

  - /path/to/test.csv

Decision Thresholds¶

Decision thresholds are derived on the fly from the leaf counts stored in each tree (n_target/n_non_target): every tree contributes its Youden-optimal threshold, mean combination compares each target score against the mean of its trees' thresholds, maximum combination compares each tree score against its own threshold. No threshold files are written or read; training only persists label_stats.json (label counts and majority class) as the fallback prediction when no threshold margin is positive.

Parameter Guide¶

n_rep and n_dims together¶

n_rep applies to complete split candidates, not only to individual features. For example, with n_dims: 2 and n_rep: 3, every pair is built and evaluated three times using the matching repetition of each feature. The median candidate of that pair is then compared with the other possible splits. This preserves row alignment while retaining the stabilizing effect of repeated random splits.

The calcs_per_dim limit counts feature combinations. Increasing n_rep therefore increases the work per combination, but does not change how many combinations the limit permits.

train_files / test_files¶

n: Number of Trees¶

max_depth¶

max_depth caps the number of dot-separated segments in a spore's depth field, which equals the number of splits between the root and that leaf. The cap is a safety net, not a tuning knob: min_eval_fit stops the recursion first in almost every case.

To make a model shallower, lower min_eval_fit — not max_depth. See the Settings Guide for the exact semantics and the measured effect of both settings.

n_dims¶

n_cat¶

calcs_per_dim¶

n_rep: Repetitions per Candidate¶

Controls how many times the data is randomly split into count and group sets. Each repetition computes a candidate independently; the median result across all repetitions is selected. For multi-dimensional candidates, features are combined only with their matching repetition, preventing count rows from different shuffles from being paired.

score_method: Split Scoring¶

Controls how the discriminating power of a split candidate is computed. All methods are built on the plain proportion difference diff_plain = p - q:

smoothing: Laplace Smoothing¶

When smoothing is greater than zero, every bin combination receives the pseudo-count smoothing on both sides before the proportions used by all scoring methods are computed. This dampens the effect of sparsely populated cells on the candidate ranking. The left/neutral/right classification always uses the raw proportions, so the resulting model structure is unaffected by smoothing.

min_split_improvement: Dimensional Barrier¶

A multi-dimensional candidate (dim >= 2) is only selected when its score exceeds the current best split by at least this relative factor. This prevents sparse higher-dimensional combinations from winning purely due to score noise.

pair_corr_filter: 2D Correlation Filter¶

Extends the 1D is_diff_to_low check to feature combinations. In every dimension stage (dim 2..=n_dims) each evaluated candidate checks its joint correlation table: for every candidate position, the cells are grouped by the remaining features and the share of each class inside the dominant bin of that position is summed. When BOTH classes put more than pair_corr_min_main of their mass into the dominant bins, one feature of the combination is redundant given the rest and the 1D-weakest feature of the candidate is masked immediately — it is no longer used for any following combination of this node, and the triggering candidate itself is excluded. The mask only lives in the current node: the next node starts fresh with all features.

Effects:

• calcs_per_dim only counts combinations that are actually evaluated — combinations containing a masked feature are skipped without consuming budget, so the budget stretches further for the meaningful candidates.
• The check runs on the candidate's median repetition table and costs nothing extra (the table is computed for scoring anyway).
• With n_dims: 1 no pair filtering happens (there are no combination stages).
• The 1D-best feature can never be masked (it is never the weakest member of a combination).

pair_corr_min_main works like the 1D threshold of is_diff_to_low (0.9): higher values only prune near-deterministic dependencies, lower values prune more aggressively. pair_corr_max_features limits the pair stage (dim 2) to the top-K features by 1D score — a useful guard for wide datasets (e.g. pixel features) where the number of pairs grows quadratically.

spore_diff: Branch Condensation¶

The winning split is defined by the bin combinations of its correlation table. Two combinations are merged into one branch when the adjacent pair with the smallest difference in target/non-target rate (diff) stays below spore_diff:

• The observed combinations are sorted by diff — the regularized normalized difference (n*M - m*N - sqrt(n)*M - sqrt(m)*N - n*sqrt(M) - m*sqrt(N)) / (n*M + m*N) with target/non-target cell counts n/m and totals N/M, clamped to 0 on the dominating side. The square-root penalty terms keep underpopulated cells at 0 until they gather enough evidence. The pair with the smallest gap is merged first; the merged diff is recomputed from the summed counts with the same regularized formula.
• Merging continues until the smallest remaining gap reaches spore_diff or at least two observed branches remain — a split always has at least two real branches (plus an optional residual), never one.
• The residual branch (combinations never observed in the count sample, segment .n) is never merged into.
• 0.0 keeps every observed combination as its own branch — the pure fan-out split.
• >= 1.0 collapses the observed combinations into a binary split.

With spore_diff: 0.0 every branch is its own recursive subtree (depth segment .<i>), and the combinations that were NOT observed in the count sample are grouped into a single residual subtree (segment .n). Section depth is dot-separated (e.g. 0, 0.3, 0.3.n), so the decision path of a leaf is reconstructed exactly.

Effects:

• Spores keep the standard l/n/r encoding disabled; the extended dot-encoded depth is the only encoding.
• Each branch subtree scores itself via its own sample read.
• A split observed across all possible combinations has no residual branch.
• Best for sparse high-dimensional tables: with spore_diff: 0.0 the split does not cluster distinct cells into groups; with the default 1.0 it collapses into a clean binary split.

Quick Reference Table¶

Note that min_eval_fit — not max_depth — is what these profiles tune to control model size. See the Settings Guide.

See also¶

• Settings Guide — Every setting with an example, a value table, and its interactions with the other settings
• Training Internals — The algorithm these settings drive
• Best Practices — Recommended tuning order
• Troubleshooting — Common issues