Multiple outputs

By default a step returns one Table on one output port. Two features change that: outputs=[...] declares several named data ports, and graph_outputs={...} declares read-only scalar metrics shown on the node card.

Usage#

from lsdtools import Tool, Table

tool = Tool("mesh")

@tool.load(outputs=["vertices", "faces"])
def make_mesh(n: int = 8) -> dict:
    """Produce two tables from one node."""
    return {"vertices": build_vertices(n), "faces": build_faces(n)}
# → the node shows two output ports: vertices, faces

With outputs=[...] the function returns a dict whose keys match the declared names, each mapping to a Table. This works on @tool.load and @tool.shape.

Wiring a specific output#

Downstream, select a port with step.output("name") on the node handle and pass it into the next node's input:

m = make_mesh(n=8)
render_points(m.output("vertices")) # wire just the vertices port
build_index(m.output("faces")) # …and the faces port elsewhere

In a Python run, RunResult.outputs gives you every port as a {name: Table} dict; .output is the primary one. See Engine.

Read-only metrics: graph_outputs#

graph_outputs={"name": type} declares small scalars that surface live on the node card — a row count, a bounds string, a checksum. They are not data ports. Set them inside the run with ctx.set_output(...) from an injected StepContext:

from lsdtools import Tool, Table, StepContext

@tool.shape(graph_outputs={"n_rows": int, "n_dropped": int})
def drop_nulls(t: Table, column: str, ctx: StepContext = None) -> Table:
    kept = t.filter(t[column].is_valid())
    ctx.set_output("n_rows", len(kept))
    ctx.set_output("n_dropped", len(t) - len(kept))
    return kept
# → the node card shows n_rows and n_dropped after each run

Because graph_outputs are metrics about a run rather than inputs to it, they are excluded from the cache key — reporting a count never invalidates a cached result.

Combining both#

A step can declare data ports and metrics at once — return the dict of tables and set the scalars:

@tool.shape(outputs=["keep", "reject"], graph_outputs={"kept": int})
def partition(t: Table, floor: float = 0.0, ctx: StepContext = None) -> dict:
    mask = t["score"] >= floor
    keep, reject = t.filter(mask), t.filter(~mask)
    ctx.set_output("kept", len(keep))
    return {"keep": keep, "reject": reject}

Related#

Learn — Shape steps · Load steps · Parameters vs ports

API — Tool · Context · Engine

Examples — Multi-output mesh · Live node metrics