Options - Prediction Engine

<div class="section-label">02 Options</div> <div class="section-title">Settings for each prediction call.</div> These are **advanced knobs**. For general analysis, call predict, predict_maxfit, or predict_grid without the options argument; each method uses suitable defaults. To customize a run, pass the matching object: [[#PredictOptions|PredictOptions]] with predict, [[#MaxFitOptions|MaxFitOptions]] with predict_maxfit, or [[#GridOptions|GridOptions]] with predict_grid. MaxFitOptions and GridOptions **extend** PredictOptions: the same shared fields, with respective relevant options key-values. ```mermaid classDiagram direction TB class PredictOptions { shared base fields } class MaxFitOptions { +objective +inner_parallel } class GridOptions { +max_iter +k +seed +attribute_combi +adjust_impact_for_missing +retain_grid_objects +inner_parallel } PredictOptions <|-- MaxFitOptions PredictOptions <|-- GridOptions ``` ## PredictOptions Settings for predict. Also the shared base inherited by MaxFitOptions and GridOptions. **Call:** `predict` **Type:** `PredictOptions` **Defaults when omitted:** threshold `[0.5]`; `censor_type` `relevance`; `censor_unit` `percent`; `censor_operator` `gte` ```text PredictOptions ├── threshold ├── censor_type, censor_unit, censor_operator ├── prediction_scale ├── adj_fit_multiplier, inv_method └── missing_moments, include_linear_regression, verbose ``` Field details: | Name | Type / values | Default | Description | | --- | --- | --- | --- | | threshold | vector, length ≥ 1 | [0.5] | Censor cut(s); becomes T on results | | censor_type | relevance \| similarity | relevance | Score that is thresholded. both is invalid here | | censor_unit | score \| percent | percent | Raw score vs percentile | | censor_operator | gt \| lt \| gte \| lte | gte | How the cut compares to the score | | prediction_scale | response \| logistic | response | Prediction on y scale or logistic scale | | adj_fit_multiplier | identity \| K \| log | K | How adjusted fit is scaled | | inv_method | gaussian \| cholesky \| pseudoinverse | gaussian | Covariance inversion method | | missing_moments | pairwise \| complete | pairwise | How μ, Σ, and PSR N treat NaNs. Incomplete X rows still get weight 0; this does not drop them from ŷ. complete is listwise. Alias: verify_missing_data on → complete | | include_linear_regression | on / off | off | Attach optional yhat_linear when available | | verbose | on / off | off | Diagnostic status messages | > [!note]- Percentile algorithm > When censor_unit is percent, a process-wide percentile algorithm also applies (full_sort or order_statistics). It is not a field on the options object. See [[Settings/Allowed Values#Percentile algorithm|Allowed values]]. ## MaxFitOptions Settings for predict_maxfit. Includes all [[#PredictOptions|PredictOptions]] fields, with MaxFit-oriented defaults for threshold and censor type. **Call:** `predict_maxfit` **Type:** `MaxFitOptions` **Inherits:** [[#PredictOptions|PredictOptions]] ```text MaxFitOptions ├── …PredictOptions ├── threshold, censor_type (MaxFit defaults) ├── objective └── inner_parallel ``` MaxFit-specific options and overridden defaults: | Name | Type / values | Default | Description | | --- | --- | --- | --- | | threshold | vector, length ≥ 1 | [0, 0.2, 0.5, 0.8] | Candidate thresholds to search | | censor_type | relevance \| similarity \| both | both | both allowed (unlike Predict) | | objective | fit \| adjusted_fit \| kfit | kfit | Score used to pick the winning threshold | | inner_parallel | auto \| off | auto | Within-call parallel when searching both censor types | Other PredictOptions fields keep the Predict defaults unless you override them. ## GridOptions Settings for predict_grid. Includes [[#PredictOptions|PredictOptions]] fields except missing_moments, with Grid-oriented defaults for threshold and censor type. **Call:** `predict_grid` **Type:** `GridOptions` **Inherits:** [[#PredictOptions|PredictOptions]] (except missing_moments) ```text GridOptions ├── …PredictOptions (not missing_moments) ├── threshold, censor_type (Grid defaults) ├── max_iter, k, seed ├── attribute_combi ├── adjust_impact_for_missing ├── retain_grid_objects │ ├── yhat_cells, adjusted_fit_cells, n_cells, weights_cells │ ├── k_cells, combi_cells │ └── ysolo_distribution └── inner_parallel ``` Grid-specific options and overridden defaults: | Name | Type / values | Default | Description | | --- | --- | --- | --- | | threshold | vector, length ≥ 1 | [0, 0.2, 0.5, 0.8] | Thresholds used inside each cell | | censor_type | relevance \| similarity \| both | both | both allowed | | max_iter | integer > 0 | 1000 | Cap on combination search iterations | | k | integer > 0 | 1 | Combination size / sampling parameter | | seed | unsigned integer | 42 | RNG seed for combination sampling and the missing-column noise used in Impact | | attribute_combi | matrix Q × K | generated | Fixed combination matrix; omit to sample | | adjust_impact_for_missing | on / off | on | Incomplete-column **Impact on Fit** / **Impact on Prediction** vs uninformative noise at that column's scale (same missing rows). Off is the old include-versus-exclude baseline. Complete columns, composite ŷ, fit, variable weights, and CCTP are unchanged | | retain_grid_objects | omit \| comma-separated keys | omit (lean) | Which per-cell objects to keep (see below) | | inner_parallel | auto \| off | auto | Parallel over attribute combinations | Grid does **not** take missing_moments (or the verify_missing_data alias). It chooses complete vs pairwise moments per combination: holey selected columns use listwise complete-case; combinations of complete columns stay pairwise. Other PredictOptions fields keep the Predict defaults unless you override them. ### Retain grid objects Set retain_grid_objects on GridOptions to the specific keys you need. Omit it (the default) for a lean composite. Name only the objects you intend to inspect; that keeps memory intentional. Controls which per-combination payloads appear on [[Results/Grid Cells|Grid Cells]]. **Impact on Fit**, **Impact on Prediction**, variable weights, and CCTP do **not** require retain. Two keys also turn on extra work, not only extra copies: | Key | Unlocks | Typical shape | | --- | --- | --- | | yhat_cells | Per-censor cell predictions | Q × T | | adjusted_fit_cells | Per-censor cell adjusted fit | Q × T | | n_cells | Per-censor cell counts | Q × T | | weights_cells | Per-censor cell observation weights (also stores N×T weights instead of streaming them) | 3-D ≈ (N, T, Q) | | k_cells | Shared per-combination k-related values | Q × T | | combi_cells | Shared combination membership / design | Q × K | | ysolo_distribution | Computes solo payloads and keeps them: pooled histogram, composite σ, xi_solo_composite, and cell solo tables | histogram + N / N×Q / N×T×Q | Example: retain_grid_objects="yhat_cells,k_cells,combi_cells" ysolo_distribution is not the same as enabling a histogram on every inner cell. Inner Grid predict skips per-cell binning; this key computes y_solo / ξ once per cell, keeps ysolo_cells (N × Q), and bins **one** pooled histogram after the search. Lean Grid (omit retain) skips that work. Shapes and nesting: [[Results/Grid Cells|Grid Cells]] · [[Results/Solo Distribution|Solo Distribution]]. --- <div class="btn-row center"> <a class="btn-primary" href="/Settings/Allowed%20Values">Allowed values</a> <a class="btn-ghost" href="/Results/Grid%20Cells">Grid Cells</a> </div> ## Related - [[Predict]] · [[MaxFit]] · [[Grid Prediction]] - [[Settings/Allowed Values|Allowed values]] - [[Results/Overview|Results]] > [!warning]- C ABI / native integrators > Option names, defaults, and retain knobs here follow the thin clients. The C ABI may expose different symbols, flag names, or ownership rules. Integration engineers should pin and follow the public header contract rather than this chapter alone: [[Install/Native Runtime|Native Runtime]] · [C ABI on GitHub](https://github.com/CambridgeSportsAnalytics/rbp-math-c-abi).