<div class="section-label"><span class="num">03</span> Grid options</div> <div class="section-title">Search settings for a <em>grid</em> prediction.</div> Settings for <span class="mono">predict_grid</span>. GridOptions extends [[Settings/Options#PredictOptions|PredictOptions]] except <span class="mono">missing_moments</span>, with Grid-oriented defaults for threshold and censor type. Shared fields (thresholds, censoring, scale) stay on [[Settings/Options|Options]]. **Call:** `predict_grid` **Type:** `GridOptions` **Inherits:** [[Settings/Options#PredictOptions|PredictOptions]] (except <span class="mono">missing_moments</span>) <div class="pillars"> <div class="pillar"> <div class="pillar-num">↳ 01</div> <div class="pillar-title">Inside each cell</div> <div class="pillar-text">Grid's threshold and censor defaults. Moments are chosen per combination.</div> </div> <div class="pillar"> <div class="pillar-num">↳ 02</div> <div class="pillar-title">Combinations</div> <div class="pillar-text">Which sizes to try, which columns must travel together, and the search cap.</div> </div> <div class="pillar"> <div class="pillar-num">↳ 03</div> <div class="pillar-title">Impact and retain</div> <div class="pillar-text">How missing columns are scored, which cell tables to keep, and whether the search runs in parallel.</div> </div> </div> ## GridOptions <div class="solution-list"> <div class="solution-row"> <div class="solution-num">/01</div> <div class="solution-title"><a href="#Inside%20each%20cell">Inside each cell</a></div> <div class="solution-desc"><span class="mono">threshold</span>, <span class="mono">censor_type</span>, and why <span class="mono">missing_moments</span> is absent.</div> </div> <div class="solution-row"> <div class="solution-num">/02</div> <div class="solution-title"><a href="#Combinations">Combinations</a></div> <div class="solution-desc"><span class="mono">max_iter</span>, <span class="mono">min_k</span>, <span class="mono">max_k</span>, <span class="mono">allowed_k</span>, <span class="mono">seed</span>.</div> </div> <div class="solution-row"> <div class="solution-num">/03</div> <div class="solution-title"><a href="#Sampling%20combinations">Sampling combinations</a></div> <div class="solution-desc">The size rules, <span class="mono">attribute_combi</span>, <span class="mono">required_attributes</span>, <span class="mono">attribute_groups</span>.</div> </div> <div class="solution-row"> <div class="solution-num">/04</div> <div class="solution-title"><a href="#Impact">Impact</a></div> <div class="solution-desc"><span class="mono">adjust_impact_for_missing</span>.</div> </div> <div class="solution-row"> <div class="solution-num">/05</div> <div class="solution-title"><a href="#Retain%20grid%20objects">Retain grid objects</a></div> <div class="solution-desc"><span class="mono">retain_grid_objects</span> and its keys.</div> </div> <div class="solution-row"> <div class="solution-num">/06</div> <div class="solution-title"><a href="#How%20it%20runs">How it runs</a></div> <div class="solution-desc"><span class="mono">inner_parallel</span>.</div> </div> </div> ## Inside each cell These two fields override the Predict defaults. <span class="mono">both</span> is a legal censor type here. | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">threshold</span> | vector, length ≥ 1 | <span class="mono">[0, 0.2, 0.5, 0.8]</span> | Thresholds used inside each cell | | <span class="mono">censor_type</span> | <span class="mono">relevance</span> \| <span class="mono">similarity</span> \| <span class="mono">both</span> | <span class="mono">both</span> | <span class="mono">both</span> is allowed | Grid does **not** take <span class="mono">missing_moments</span> (or the <span class="mono">verify_missing_data</span> 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. Names and defaults for those fields: [[Settings/Options#PredictOptions|PredictOptions]]. ## Combinations The search budget and the size policy. Rules for the band, the exact-size list, and how columns are constrained: [[#Sampling combinations|Sampling combinations]]. | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">max_iter</span> | integer > 0 | <span class="mono">1000</span> | Cap on how many combinations are evaluated | | <span class="mono">min_k</span> | integer > 0 | <span class="mono">1</span> | Smallest size in the band. <span class="mono">k</span> is the same setting. Leave this out when you pass <span class="mono">allowed_k</span> | | <span class="mono">max_k</span> | integer > 0, or omit | omit | Largest size in the band. Omit to allow every column. Set it equal to <span class="mono">min_k</span> for that exact size. Leave this out when you pass <span class="mono">allowed_k</span> | | <span class="mono">allowed_k</span> | list of integers > 0, or omit | omit | Exact sizes, such as <span class="mono">[1, 3, 7, 10]</span>. Replaces <span class="mono">min_k</span> and <span class="mono">max_k</span>. A contiguous list matches that band | | <span class="mono">seed</span> | unsigned integer | <span class="mono">42</span> | RNG seed for combination sampling and the missing-column noise used in Impact | ## Sampling combinations When <span class="mono">attribute_combi</span> is omitted, Grid builds the search from one size policy. ### Size policy The default policy is a band. <span class="mono">min_k</span> is the smallest number of attributes turned on in a combination. <span class="mono">max_k</span> is the largest. With both at their defaults, that includes single-attribute combinations and larger ones, up to every column, until <span class="mono">max_iter</span> is filled. Set <span class="mono">max_k</span> equal to <span class="mono">min_k</span> for combinations of that exact size. <span class="mono">k</span> is the same setting as <span class="mono">min_k</span> and is still accepted. <span class="mono">allowed_k</span> replaces that band with a list of exact sizes. <span class="mono">[1, 3, 7, 10]</span> keeps those sizes and leaves out 2, 4, 5, 6, 8, and 9. A contiguous list such as <span class="mono">[2, 3, 4]</span> is the same search as <span class="mono">min_k</span> 2 and <span class="mono">max_k</span> 4. Order does not matter. The list needs at least one size, each size once, each at least 1, and none higher than the number of attributes. Use <span class="mono">allowed_k</span>, or use <span class="mono">min_k</span> and <span class="mono">max_k</span>. The two policies cannot be combined. ### Required attributes and groups | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">required_attributes</span> | vector, length K, 0/1 | omit | Attributes that stay on in every generated combination | | <span class="mono">attribute_groups</span> | matrix G × K, 0/1 | omit | Groups of attributes that are selected together | <span class="mono">required_attributes</span> is a length-K mask in the same column order as <span class="mono">X</span>. A 1 means that attribute is on in every generated combination. <span class="mono">attribute_groups</span> has one row per group and one column per attribute. Attributes marked 1 in the same row are selected together: all on, or all off. Rows that share an attribute collapse into one group, including through a chain of overlaps. A row with a single 1 changes nothing. If a required attribute sits inside a group, the whole collapsed group stays on. A group larger than the largest legal size is left off. A required group larger than every legal size fails, because those attributes are already on in every combination. The size policy counts attributes after those rules. If the smallest legal size is smaller than the attributes that must be present, the call fails. With <span class="mono">allowed_k</span>, any listed size below that count fails, even when a larger listed size would fit. If <span class="mono">min_k</span> is higher than <span class="mono">max_k</span>, the call fails. Each size must be at least 1 and no higher than the number of attributes. Example: the second, third, and fourth attributes stay together, and the fifth and sixth stay together. The first can be selected on its own. ```text [[0, 1, 1, 1, 0, 0], [0, 0, 0, 0, 1, 1]] ``` Overlapping rows collapse. These two rows become one group of the first three attributes: ```text [[1, 1, 0, 0, 0], [0, 1, 1, 0, 0]] ``` ### Preset combinations | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">attribute_combi</span> | matrix Q × K | generated | Fixed combination matrix. Omit to sample. Cannot be combined with <span class="mono">required_attributes</span> or <span class="mono">attribute_groups</span> | When <span class="mono">attribute_combi</span> is supplied, rows outside the size policy are dropped, and what remains is still capped at <span class="mono">max_iter</span>. With <span class="mono">max_k</span> set, that drops rows outside <span class="mono">min_k</span> through <span class="mono">max_k</span>. With <span class="mono">allowed_k</span>, that drops rows whose size is not listed. Do not pass <span class="mono">attribute_combi</span> together with <span class="mono">required_attributes</span> or <span class="mono">attribute_groups</span>. The preset matrix already is the search. ## Impact | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">adjust_impact_for_missing</span> | on / off | on | Incomplete-column **Impact on Fit** / **Impact on Prediction** vs uninformative noise at that column's scale | On is the default. Observed cells of an incomplete column are replaced with noise at that column's own scale, and the missing rows stay missing, so missingness does not make the attribute look artificially weak. Off is the old include-versus-exclude baseline. Complete columns, composite ŷ, fit, variable weights, and CCTP are unchanged. The noise draw uses <span class="mono">seed</span>. What the two Impact measures mean: [[Results/Grid Insights|Grid Insights]]. ## Retain grid objects | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">retain_grid_objects</span> | omit \| comma-separated keys | omit (lean) | Which per-cell objects to keep | Set <span class="mono">retain_grid_objects</span> 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 | | --- | --- | --- | | <span class="mono">yhat_cells</span> | Per-censor cell predictions | Q × T | | <span class="mono">adjusted_fit_cells</span> | Per-censor cell adjusted fit | Q × T | | <span class="mono">n_cells</span> | Per-censor cell counts | Q × T | | <span class="mono">weights_cells</span> | Per-censor cell observation weights (also stores N×T weights instead of streaming them) | 3-D ≈ (N, T, Q) | | <span class="mono">k_cells</span> | Shared per-combination k-related values | Q × T | | <span class="mono">combi_cells</span> | Shared combination membership / design | Q × K | | <span class="mono">ysolo_distribution</span> | Computes solo payloads and keeps them: pooled histogram, composite σ, <span class="mono">xi_solo_composite</span>, and cell solo tables | histogram + N / N×Q / N×T×Q | Example: <span class="mono">retain_grid_objects="yhat_cells,k_cells,combi_cells"</span> <span class="mono">ysolo_distribution</span> is not the same as enabling a histogram on every inner cell. Inner Grid predict skips per-cell binning; this key computes <span class="mono">y_solo</span> / ξ once per cell, keeps <span class="mono">ysolo_cells</span> (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]]. ## How it runs | Name | Type / values | Default | Description | | --- | --- | --- | --- | | <span class="mono">inner_parallel</span> | <span class="mono">auto</span> \| <span class="mono">off</span> | <span class="mono">auto</span> | Parallel over attribute combinations | <div class="btn-row center"> <a class="btn-primary" href="/Settings/Options">Options</a> <a class="btn-ghost" href="/Results/Grid%20Cells">Grid Cells</a> </div> ## Related - [[Functions/Grid Prediction|Grid Prediction]] - [[Settings/Options|Options]] · [[Settings/Allowed Values|Allowed values]] - [[Results/Grid Insights|Grid Insights]] · [[Results/Grid Cells|Grid Cells]] > [!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).