Object handles¶
Most formulaML functions don't return a number or a string — they return an object handle. A handle is a cell value that points at a Python object kept on the formulaML server: a fitted model, a loaded dataset, a column transformer, a fold splitter.
Why a cell can hold a Python object¶
Excel cells normally hold scalars (numbers, text, dates) or arrays of scalars. A trained scikit-learn model is none of those — it's a Python object with internal state (coefficients, support vectors, decision trees). Trying to flatten that into cell values would lose information.
Instead, formulaML keeps the live Python object on the server and gives the cell a handle. The handle renders as a small icon plus a short label, so you can see at a glance what the cell holds:
| Icon | What it usually represents |
|---|---|
| A loaded dataset | |
| An unfitted or fitted model | |
A fitted model ready for ML.PREDICT |
|
| A preprocessing step or transformer | |
| A multi-step pipeline | |
| A grid of evaluation results |
Other formulaML functions accept these handles as arguments. ML.FIT takes
a model handle and feature/target ranges; ML.PREDICT takes a fitted-model
handle and a feature range. The handle is how data flows between cells.
Handles are server-side¶
Handles are scoped to your current session. Closing and reopening the
workbook invalidates them. To rebuild a model, re-run the formulas — every
constructor, ML.FIT, and ML.PREDICT is deterministic given the same
inputs, so the chain rebuilds top-down on recalculation.
When you'll see them¶
Almost every reference page in formulaML's ML.* namespace returns a
handle. The "Returns" section of each page calls out which icon and label
to expect.
Common gotchas¶
#REF!or "Object cache is empty": the handle's underlying Python object expired. Force a recalculation (Ctrl+Alt+F9on Windows,Cmd+=on Mac) so the constructor and any downstreamML.FITre-execute.Object handle is not a fitted ...: you passed an unfitted model toML.PREDICT. Pass the result ofML.FIT(...)instead — see The FIT/PREDICT pattern.- Handle text in the cell, no icon: an Excel calculation mode quirk. Refresh the worksheet or close-and-reopen the file.