Data intake

The intake module sits between your data source and the JSON the widgets receive. The package never parses file formats, converts units, or renames columns; readers such as brodata, pygef, and python-ags4 stay upstream. Channel and Vertical bindings adapt the chart to whatever the columns are called.

The intake enforces only what the front end cannot recover from:

• JSON safety. NaN and inf become None, because NaN is invalid JSON and kills the trait sync. Numpy scalars unwrap to plain Python numbers. A non-numeric sample raises immediately, with the column and the value named. Nothing is silently coerced.
• Equal lengths. Every column is indexed by the vertical sample position. A ragged dict would silently misalign channels, so it raises.
• Render order. Rows sort so the topmost sample comes first, because that is the order the front end renders in. Samples without a vertical value cannot be placed and are dropped.

The CPTViewer and ProfileViewer constructors call these helpers for you (a borehole log has no sample columns, so BoreholeViewer takes its layers as given). Call them directly to inspect or test what the widget will receive.

tidy

from cpt_anywidget import tidy

tidy(data, vertical="depth")

Turns tidy columns into the cptData dict the widget receives.

Parameter	Type	Description
data	DataFrame or dict	A polars or pandas DataFrame, or a dict mapping column names to any equal-length iterables (lists, tuples, numpy arrays): one row per depth sample, one column per measurement.
vertical	str, Vertical, or dict	The column that places rows on the vertical axis. Rows sort ascending for depth-like coordinates and descending for positive-up ones, so the first sample is the topmost either way.

Returns exactly what the widget receives: plain lists, JSON-safe samples, rows in render order.

Raises ValueError when:

• the data object is neither a DataFrame nor a dict of columns (convert to a dict of columns first, for example pyarrow’s .to_pydict()),
• a column holds a non-numeric sample (coerce upstream, for example pd.to_numeric(...) or .cast(pl.Float64)),
• columns differ in length,
• the vertical column is not in the data.

split

from cpt_anywidget import split

split(data, name="name")

Turns tidy long-format columns into {name: columns}, one group per CPT. The ProfileViewer constructor composes split and tidy exactly this way.

Parameter	Type	Description
data	DataFrame or dict	Every CPT’s samples stacked in one DataFrame or dict of columns, with a name column that tells them apart.
name	str	The column that holds the CPT names. Default: "name".

Groups keep first-appearance order and drop the name column. Each group is raw: feed it to tidy.

Raises ValueError when the name column is not in the data, or when columns differ in length.