Skip to content

ref / select_all ​

ref is the single reference noun in GoFish, and it works in two positions:

  • Inline in a layout — ref("a") inside a .relate() clause, ref(token) anywhere — it resolves at layout time against the name tree, hygienically scoped (see scoping).
  • As chart data — chart(ref("maxBar")).mark(text(...)) — it resolves at build time against the named-layer registry to a list of one ref, the node registered under that name. Like all chart data it is a list; being singular is a check that exactly one node matched.

select_all(name) is the plural chart-data verb: it returns an array of refs, one per node a named mark produced (node-unit; aggregate or not, no flattening). Pass either form as the data argument to a second chart() call to build overlays and connectors.

Think of select_all as the DOM's querySelectorAll (always a collection) and ref(name)-as-data as querySelector (the one-or-bust singular).

python
from gofish import layer, chart, scatter, blank, select_all, line

layer([
    # Step 1: name the mark
    chart(catch_locations)
        .flow(scatter(by="lake", x="x", y="y"))
        .mark(blank().name("points")),

    # Step 2: select_all those nodes as data for a connector
    chart(select_all("points")).mark(line(stroke="coral", stroke_width=2)),
]).render(w=500, h=300, axes=True)

Signature ​

python
ref(name: str) -> Ref            # singular; as chart data, a list of exactly one ref
select_all(name: str) -> list[Ref]  # one ref per matching node

Parameters ​

ParameterTypeDescription
namestrThe name of the layer to reference (registered via .name() on a mark)

Singular as data: exactly one ​

When you pass ref(name) as chart data it must resolve to exactly one node:

  • Zero matches → error. Nothing was registered under that name in scope.
  • More than one match → error, with a hint to use select_all(name) instead. A named mark that produced several nodes is a collection, and the singular reference refuses to silently pick one.
python
chart(ref("kpi")).mark(text(text="peak"))  # a list of one ref; raises on 0 or >1 nodes

Node-unit selection ​

select_all selects at node granularity: one ref per node the named mark produced, never flattened and never merged. Each ref points at a placed node, so overlay marks position themselves relative to it, and a ref's datum is that node's data bag.

python
bars = select_all("bars")  # list[Ref]
bars[0].datum             # the raw row-bag behind the first bar

The bag is a list of rows — a 1-row list for a fully-split leaf, all the partition's rows for an auto-summed aggregate.

Why a ref, not a "selection"? ​

GoFish models a selection as a plain list of refs rather than a bespoke selection object, and this is deliberate:

  • A ref is structurally a one-element selection. ref(name) (one ref) and select_all (a list of refs) are the singular/plural of the very same noun, so there is nothing new to learn — the ref you get from a selection behaves exactly like a ref you wrote by hand inline.
  • Geometry is decoupled from data. A ref points at a placed node; you read its placement off the ref (that is how line / ribbon draw) and its bound datum via the ref's datum. Selecting does not flatten or reshape your data.
  • Batch operations live in .flow, not on the noun. Unlike D3, where the selection object owns .data(), .attr(), .filter(), etc., GoFish keeps a selection inert. To partition, re-key, or re-encode a selection you run it through operators in .flow (e.g. group, spread) — see path-aware by below.

Hygienic scoping ​

Layer-name lookup is hygienic: a name registered via .name() is visible only within its scope and does not cross component boundaries. A name registered on a mark inside a mark component is internal to that component — it is not selectable from outside. This is the same component-boundary rule that string-name ref resolution always followed inline, so the inline-layout and chart-data lookup paths share one scoping rule.

Within that boundary, chart data follows the same widening rule as inline ref: the lookup starts at the scope the chart is built in, searches the scopes nested in it, nearest first, then widens one enclosing scope at a time. Every layer is a scope. The nearest scopes that have the name all contribute, so a mark repeated per row or per cell carries one name: a select_all outside a spread gathers every cell's marks, and one inside a cell finds its own. The singular form reports how many marks it matched when there is more than one. Inline, a string ref (and a .relate() operand) takes the nearest match to the layer that relates it; see the ref mark.

Inline select_all is not supported yet ​

select_all is a chart-data verb only. Using it inline inside a layout raises — pass it as the data argument to a chart() instead. (Inline plural references may arrive later; for now use a named layer + select_all as data.)

Connectors take select_all directly ​

line and ribbon consume a list of refs and read placed geometry off them, so feed them select_all:

python
chart(select_all("points")).mark(line(stroke="black"))

When the connector traces a chart's own marks, chaining .layer() with a bare connector mark (or with by) is sugar for this two-chart select_all recipe — only reach for select_all by hand to connect another chart's marks.

Path-aware by after a selection ​

After select_all, the stream items are refs, not raw records. Operators' by option reads a ref through its datum rows, so you write the same bare field name you would on raw records:

python
chart(select_all("bars")) \
    .flow(group(by="species")) \
    .mark(ribbon(opacity=0.8))  # not by="datum.species"

On a ref, a field resolves to a scalar only if every row in the ref's bag agrees on that field (homogeneity collapse — SQL's ONLY_FULL_GROUP_BY rule); otherwise it is None. So by="lake" works on lake-aggregate bars (all rows share a lake) but by="species" does not until you disaggregate. See spread → path-aware by for the full explanation.

pluck(source, path) — every value at a path ​

Where by's path projection collapses a row-bag to a single scalar (and goes None when the bag disagrees), pluck is its un-collapsed counterpart: it returns the full list of distinct values present at a path, in the order they first appear.

python
from gofish import pluck

pluck(ref, "species")  # → ["Bass", "Trout", ...] (distinct across the bag)

source may be a ref that a mark function received (pluck reads its datum bag), a list of rows, or a single row. path is a field name or a path ("a.b", "a[0]"), read as JS reads one; a list met along the path is read element by element, and a row that lacks the field, or holds None there, adds no value. Two values are one when JS counts them as one (1, 1.0 and "1"), so pluck answers what JS pluck answers. Reach for pluck when a field is multi-valued in the current bag and you want to enumerate its values rather than group by it — the case where by="field" would resolve to None.

pluck runs in Python, on the rows the mark function received, and returns plain Python values. Here it counts the species in each lake for a label:

python
def label(d):
    species = pluck(d[0], "species")
    return spread([text(text=f"{len(species)} spp"), d[0]],
                  dir="y", alignment="middle", spacing=10)

chart(seafood, axes=True) \
    .flow(spread(by="lake", dir="x")) \
    .mark(rect(h="count")) \
    .layer(chart().flow(group(by="lake")).mark(label))

project(source, path) — the single value at a path ​

project is the collapsing counterpart to pluck: it returns the one value at a path when the bag agrees on it (the same homogeneity collapse by performs), and None otherwise. Where pluck(ref, "site") gives you the whole multiset ["Morris"], project(ref, "site") gives you "Morris" directly — no indexing.

python
from gofish import project

project(ref, "site")  # → "Morris"  (None if the bag disagrees on "site")