Data and Columns

Marks accept values directly or string column names resolved through data=. Put data on one mark when it is local to that mark, or on the chart when its children share a table.

Regular Python sequences and one-dimensional NumPy arrays use the same API. Here, the three arrays bind directly to an area and two line marks; no table or column lookup is required. Coordinates must be real numeric, datetime-like, or categorical values that the mark supports; boolean and complex coordinate columns are rejected rather than silently coerced.

Dictionaries, pandas DataFrames, and other column-indexable objects work with this pattern. The example resolves four named columns from one shared chart table: spend and leads set position, channel sets categorical color, and pipeline value sets bubble size. A mark-level data= overrides the chart default for that mark. Numeric color values use a continuous colormap; categorical values use a discrete palette.

XY converts numeric coordinates to contiguous float64 canonical columns in the Python process. Derived float32, index, density, and decimated buffers are rendering representations—not replacements for the source values. Reusing the same NumPy array within a figure reuses the canonical column by array identity.

This separation lets pick(), hover, and selections map rendered geometry back to exact source rows even when the visible result is decimated or aggregated. Call chart.memory_report() to inspect canonical bytes, column lengths, null counts, and copies paid during ingest.

PyArrow is an optional input format, not an XY runtime dependency. Install it separately (uv add pyarrow or pip install pyarrow) and pass an Array or ChunkedArray directly:

A null-free primitive float64 Arrow Array, or a one-chunk column with that layout, can remain a read-only zero-copy view of its Arrow buffer. Integer conversion, null materialization, temporal conversion, and combining multiple chunks require counted copies. “Arrow support” therefore does not mean every Arrow layout is zero-copy; unsupported string/dictionary coordinate arrays are rejected by the numeric column store.

Python dates, datetimes, NumPy datetime64, and compatible pandas/Arrow time columns select time-axis behavior automatically. Canonical time coordinates are float64 milliseconds since the Unix epoch; NaT becomes a missing value. The current contract does not preserve arbitrary nanosecond distinctions end to end.

The datetime array selects a time scale automatically. The missing tenth value creates the visible gap in the series without changing later row indices. Missing numeric values break line/area runs or are omitted from point geometry, while canonical row indices remain stable.

A valid CSS color such as "rebeccapurple", "#6e56cf", or "var(--accent)" is a constant color. Another string is treated as a column name and resolved through data=. A color-shaped typo raises its CSS validation error instead of falling through to a misleading missing-column error.

Next, configure Axes and scales or learn how the stored columns feed large-data representations.