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. > [!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). ```mermaid classDiagram direction TB class PredictOptions { shared base fields } class MaxFitOptions { +objective +inner_parallel } class GridOptions { +max_iter +k +seed +attribute_combi +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` `greater_than` ```text PredictOptions ├── threshold ├── censor_type, censor_unit, censor_operator ├── prediction_scale ├── adj_fit_multiplier, inv_method └── verify_missing_data, 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 | gt | 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 | | verify_missing_data | on / off | off | Extra missing-data checks | | 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 [[Config/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 ``` Field details (MaxFit-specific 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 all [[#PredictOptions|PredictOptions]] fields, with Grid-oriented defaults for threshold and censor type. **Call:** `predict_grid` **Type:** `GridOptions` **Inherits:** [[#PredictOptions|PredictOptions]] ```text GridOptions ├── …PredictOptions ├── threshold, censor_type (Grid defaults) ├── max_iter, k, seed ├── attribute_combi ├── retain_grid_objects │ ├── yhat_cells, adjusted_fit_cells, n_cells, weights_cells │ ├── k_cells, combi_cells │ └── ysolo_distribution └── inner_parallel ``` Field details (Grid-specific 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 | | attribute_combi | matrix Q × K | generated | Fixed combination matrix; omit to sample | | 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 | 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**, and other [[Results/Grid Insights|Grid Insights]] do **not** require retain. | 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 | 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 | Pooled solo histogram on [[Results/Solo Distribution\|Solo Distribution]] | histogram | Example: retain_grid_objects="yhat_cells,k_cells,combi_cells" ysolo_distribution is not the same as ysolo_cells (N × Q), which may appear with related cell retention. Shapes and nesting: [[Results/Grid Cells|Grid Cells]]. <div class="btn-row"> <a class="btn-primary" href="/Config/Allowed%20Values">Allowed values</a> <a class="btn-ghost" href="/Results/Grid%20Cells">Grid Cells</a> </div> ## Related - [[Predict]] · [[MaxFit]] · [[Grid Prediction]] - [[Config/Allowed Values|Allowed values]] - [[Results/Overview|Results]]