spacr.qt.widgets.gate_console

A console and a chat box beside the gating surface.

Two panes with one job between them: let the user ask a question about the table they are gating without leaving the screen to do it.

Console

Runs an expression against the CURRENT frame and prints the answer. Not a Python shell – a Python shell in a GUI is a way to hang the GUI, and the questions that come up while gating are all of one shape: “how many objects satisfy this”, “what is the median of that”. So it evaluates pandas expressions with the frame in scope and nothing else.

Chat

The same box, addressed in English. It is wired to whatever assistant the host provides and is EMPTY when none is configured – it says so rather than pretending to think, because a chat box that silently ignores you is worse than one that is honestly unavailable.

Both write into one transcript, so the record of what was asked and what came back reads in order regardless of which pane asked.

Classes

GateConsole

The console and the chat box, sharing one transcript.

Functions

evaluate(→ str)

Answer one question about frame.

Module Contents

class spacr.qt.widgets.gate_console.GateConsole(parent=None)

Bases: PySide6.QtWidgets.QWidget

The console and the chat box, sharing one transcript.

Parameters:

parent – parent widget.

Build the console that answers questions about the gated table.

Parameters:

parent – parent widget, or None.

ask(question: str) → str

Put a question to the assistant, or say there is not one.

Parameters:

question – the question text, stripped; empty does nothing and returns "". It is written to the console, emitted on asked and passed to the responder, if one is set.

reply(answer: str) → None

Record an answer that arrived later, from an async host.

Parameters:

answer – the answer text, written to the console as given (converted with str).

run(expression: str) → str

Evaluate expression and record both halves.

Parameters:

expression – a Python expression over the loaded table, as evaluate() takes it; stripped, and empty does nothing and returns "".

run_input() → None

Run whatever is typed, clearing the box only if it was accepted.

CLEARED ONLY ON SUCCESS, so a refused expression stays where the user can fix it rather than having to be retyped from memory.

send_chat() → None

Send the chat box to the assistant, clearing it only if accepted.

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

Point the console at a table to gate.

Parameters:

frame – the rows, or None to clear.

set_responder(responder: Callable[[str], str] | None) → None

Give the chat box something to answer with.

Without one it says it is not configured rather than staying silent: a chat box that ignores you is worse than one that is honestly unavailable.

Parameters:

responder – a callable taking the question text and returning the answer, or None to remove it. An exception it raises is shown as the answer.

transcript() → str

Everything the console has printed.

Returns:

the transcript as plain text.

write(line: str, *, prefix: str = '') → None

Append one line to the log.

Parameters:

• line – the text.

• prefix – an optional marker put in front of it.

spacr.qt.widgets.gate_console.evaluate(expression: str, frame: pandas.DataFrame | None) → str

Answer one question about frame.

The frame is in scope as df, and every column as itself, so area.mean() and df['area'].mean() both work – the first is what people type.

Errors come back as text rather than exceptions: this is a question box, and a typo is a normal thing to do in one.

Parameters:

• expression – a Python expression, stripped; empty returns "". It is evaluated with df, pd, np and every column whose name is an identifier in scope, and a restricted set of builtins.

• frame – the table to question; None or an empty frame returns "no table loaded".