spacr.qt.widgets.formula_editor

The column formula editor — type an expression, get a column.

The chrome over spacr.qt.widgets.formula. Everything about what an expression means is in there; this module is a name box, an expression box, a list of what has been defined and a preview of the first few values.

Three things it insists on

It validates while you type, not when you commit. The expression is parsed on every keystroke (a parse of a forty-character string is microseconds), so the error message for area / perimter appears next to the typo rather than after an Add that appears to do nothing. The Add button is disabled until the formula parses and resolves against the loaded table.

It shows the values, not just the syntax. A formula can be perfectly valid and produce a column that is 90% infinities, which no amount of syntax checking catches. The preview evaluates the expression over the head of the table and prints notice — “3 of 4 rows have a finite value · 1 became NaN or infinite in the calculation” — which is the sentence that stops a bad ratio column reaching a chart.

It hands back a frame, not a mutation. FormulaPanel.computed_frame() returns the loaded table plus the computed columns, a copy every time. The loaded frame is never grown, so removing a formula removes its column, and two screens showing the same table do not accumulate each other’s columns.

Where the columns go

Nowhere, by itself. The panel emits FormulaPanel.formulas_changed and the host re-hands the computed frame to whatever it is driving — the trellis, the gate editor, the feature explorer, the Local Data Filter. That is the whole integration: a computed column is an ordinary column from the moment it exists, classified by the same classify_columns() rule as a measured one, so it appears in the column well, in the filter picker and in the export without any of them being told about formulas.

Classes

FormulaDialog	FormulaPanel in a window, for a screen with no room for it.
FormulaPanel	Define computed columns for one table.

Module Contents

class spacr.qt.widgets.formula_editor.FormulaDialog(parent=None, *, panel: FormulaPanel | None = None)

Bases: PySide6.QtWidgets.QDialog

FormulaPanel in a window, for a screen with no room for it.

Non-modal, so the chart behind it redraws as columns are added — which is the point of adding them.

Parameters:

• parent – parent widget.

• panel – an existing FormulaPanel to host. None builds one, which is the ordinary case; passing one lets a screen keep the panel alive across openings so a half-written formula survives.

Wrap a formula panel in its own window.

The window is sized in scaled pixels rather than raw ones: a size set from Python does not grow with the stylesheet’s font size, and at the 200% scale the prose inside wrapped to more height than the window had.

Parameters:

• parent – parent widget, or None.

• panel – an existing panel to show; None builds one.

class spacr.qt.widgets.formula_editor.FormulaPanel(parent=None)

Bases: PySide6.QtWidgets.QWidget

Define computed columns for one table.

Parameters:

parent – owning widget, or None.

The panel starts with no table. Give it one with set_frame(), which may be called again whenever the table changes; the formulas defined so far are kept and re-validated against the new columns.

Emits formulas_changed whenever the set changes — the host’s cue to re-read computed_frame().

Build the computed-columns panel.

Parameters:

parent – parent widget, or None.

add_formula(formula: spacr.qt.widgets.formula.ColumnFormula) → bool

Add formula, or report why it cannot be computed here.

Parameters:

formula – the derived-column formula to append; one with the same name is replaced. When a table is loaded the formula is test-applied first and rejected if it fails.

Returns:

True when it was added.

clear() → None

Drop every computed column.

commit() → bool

Add the formula currently in the two boxes.

computed_frame() → pandas.DataFrame | None

The table plus the computed columns; a copy, never the original.

Returns the loaded frame unchanged when nothing is defined, so a host can call this unconditionally.

formulas() → spacr.qt.widgets.formula.FormulaSet

The defined formulas. The panel’s own object — copy before editing.

frame() → pandas.DataFrame | None

The table as loaded, without the computed columns.

remove(name: str) → None

Drop the formula called name and its column.

Parameters:

name – name of the formula (and of the column it makes); an unknown name does nothing.

remove_selected() → None

Drop the selected computed columns.

results() → List[spacr.qt.widgets.formula.ColumnResult]

One ColumnResult per column.

set_formulas(formulas: Sequence[spacr.qt.widgets.formula.ColumnFormula]) → None

Replace the whole set — for restoring a saved analysis.

Parameters:

formulas – formulas to use, in the order they are applied; each sees the columns made by the ones before it.

set_frame(frame: pandas.DataFrame | None) → None

Point the panel at a table.

Existing formulas are kept and re-applied. That is the opposite of what the Local Data Filter does with its clauses, on purpose: a filter clause naming a missing column narrows by less than it claims and is dangerous to keep, while a formula naming a missing column fails, says which column, and is exactly what the user wants back when they reload the same table.

Parameters:

frame – the table the formulas are computed on, or None to detach the panel from any table.

status() → str

The line under the boxes — the validation message or the notice.