HMPlot

Data

A table whose columns the components inside it read by name.

Scatter plot of y against x. x from 0.9 to 4.1, y from 0.9 to 4.1. 4 points.

Static preview; loading the interactive plot

<script>
  import { Data, Plot, Points } from "hmplot";
  const data = { x: [1, 2, 3, 4], y: [3, 1, 4, 2] };
</script>

<Data value={data}>
  <Plot height={300} axes2d>
    <Points x="x" y="y" />
  </Plot>
</Data>

Options

animationGroupcolumn | column[] | null
Match animation rows by these columns within each filtered/transformed snapshot; selections keep Data.key. null restores key/position matching. Default: inherited; otherwise Data.key, then position.
valuetable | transform
The table: columns, rows, typed arrays, an Arrow table or a GeoJSON FeatureCollection (Python also takes it as the first argument); or a transform (a Filter, Group, ...: its handle in Svelte, value=node in Python), whose live output the components inside read, computed once wherever it is drawn.
rowsnumber
Number of rows instead of a table: an integer from 0 to 2147483647. Generate columns with row(), random() and Calculate; pass value or rows, not both.
keycolumn | column[]
The column (or columns) whose values identify a row across updates, so selections and animations follow it. Default: the row's index.
schemaRecord<string, type | {type, domain, unit, timezone}>
Column types, when inference is not enough: numeric, categorical, ordinal, boolean, datetime, duration or geometry.

Usage

value accepts column tables, row records, and FeatureCollections. Nested Data replaces the active table. Plot and Facet data shortcuts establish the same scope. A key keeps observation identity stable through reorderings.

A transform’s output

value can also be a transform: its live output, read where this Data is. A pipeline computed once can feed several plots in different places, each mark keeping its own Plot or Frame as its visual parent. In Python pass the transform node, hm.Data(value=totals), or a mark’s data=totals; in Svelte its handle, bind:this={totals} then <Data value={totals}>.

with hm.Scene():
    with hm.Data(sales):
        with hm.Filter(where=hm.col.amount > 20):
            totals = hm.Group(by="region", columns={"orders": hm.count()})
    with hm.Row():
        with hm.Plot():
            hm.Points(data=totals, x="region", y="orders", select=True)
        with hm.Plot():
            with hm.Data(value=totals):
                hm.Points(x="region", y="orders", respond="selected")
<script>
  import { Data, Filter, Group, Plot, Points, count, greater } from "hmplot";
  let { sales } = $props();
  let totals = $state();
</script>

<Data value={sales}>
  <Filter where={greater("amount", 20)}>
    <Group bind:this={totals} by="region" columns={{ orders: count() }} />
  </Filter>
</Data>
{#if totals}
  <Plot data={totals}><Points x="region" y="orders" select /></Plot>
  <Plot><Data value={totals}><Points x="region" y="orders" respond="selected" /></Data></Plot>
{/if}
  • The pipeline runs once per change of its inputs, however many plots read it, and every reader draws the same output; removing one reader leaves the others drawing.
  • The connection is fixed: a Data reads the transform it was given for its life. Define the transform before its consumers. Python automatically includes a detached pipeline rooted at hm.Data(table) in each scene that reads it; a transform already parented to another Scene cannot be imported this way. A pipeline never reads its own output (an error names the cycle).
  • Selections and other interaction state are the source table’s: a click on one plot’s group selects its rows, which every reader of the pipeline sees.
  • A transform reading the view (@time, the pointer) takes the clock of the plots drawing it. Plots with their own clocks are ambiguous and reported; put them in one InputContext.
  • An HTML export of the whole scene keeps the references; exporting one plot whose data is a pipeline outside it is refused. Put the views in an explicit with hm.Scene() as chart: and export chart; the same rule applies to a Row containing views of a detached chain.
  • A positional hm.Data(node) adds the node as a child, as for any container: pass value= to read a transform’s output.

Reading the rows

read() on a transform’s handle, or on a Data’s (bind:this gives a DataHandle), gives the rows it holds now, on the host: for a value the page shows outside a plot, such as a total in a sentence, a breadcrumb or a list. It waits for the current inputs to run, then returns { length, version, columns }: numbers as Float64Array (NaN where missing), times as Date, categories as their values (null where missing). read({ columns: ["region", "orders"] }) picks and orders the columns; read({ rows: true }) gives one object per row instead. In Python, await totals.read() in a displayed scene gives a dict of NumPy arrays (pandas.DataFrame(await totals.read())).

<script>
  let totals = $state(), top = $state([]);
  // subscribe() says when the output changes; read() fetches it.
  $effect(() => totals?.subscribe(async (status) => {
    if (status.pending || status.error) return;
    const { rows } = await totals.read({ rows: true });
    top = rows.sort((a, b) => b.orders - a.orders).slice(0, 10);
  }));
</script>
table = await totals.read(["region", "orders"])
  • A read copies the columns from the GPU: one wait per call, and its size is bounded by limit.readback (16 MiB). Marks draw the same output without it; never read on every pointer move to redraw what a mark could draw.
  • The rows are the visible ones, in the output’s order: a Filter’s kept rows, a Group’s groups.
  • version names the output it was read from; two reads with the same version hold the same rows. A brush or an input that changes the rows publishes a new version.
  • A Group of the brushed rows (Filter where="@brushed" above it) reads the brushed rows’ statistics; a selection resource’s rows() reads which source rows are selected.

Use rows=N instead of value to generate rows without uploading a table. Pass one or the other. row() (hm.row()) gives the zero-based position among visible rows; numeric constants and seeded random() expressions provide generated values. Retain a source index or random draw in [Calculate] before filtering or sampling when it should follow the original row. The count is an integer from 0 to 2147483647, subject to device memory for generated arrays.

animationGroup (animation_group in Python) on Data, Plot or Frame matches animated rows by a column or list of columns independently of Data keys. It inherits through the tree; a child Frame overrides its branch, and explicit null (Python None) restores Data-key/position matching. Filter to one row per group before tweening: a country/year table can keep key=["country", "year"] and animate by "country" after filtering to one year. Groups must be unique in each tweened snapshot, and changing the group column scheme resets motion history. Selection, hover and connections keep Data identity.

Related examples

Data shortcuts

Particles without an uploaded table

Ten million stars, filtered live