Signals → DataFrame

Shipping

df_from_signals

Pack a signal or bundle into a typed table: a time column plus one f64 column per channel

Signature

Inputs

signalsSignal|SignalBundlerequired— A single Signal (treated as a 1-channel bundle) or a multi-channel SignalBundle to tabulate.

Outputs

dfDataFrame— Rectangular frame: an optional leading time column plus one f64 column per input channel.

Parameters

Key	Type	Default	Notes
`include_time`	bool	true	Add a leading time column taken from the FIRST channel's timestamps.
`time_name`	string	time	Header for the time column when it is included.

Description

Signals → DataFrame (df_from_signals) is the bridge from Captyse's signal wire family into the columnar DataFrame world. It takes a Signal — treated as a one-channel bundle — or a full SignalBundle and packs it into a typed [DataFrame]: an optional leading time column plus one `f64` column per channel, each column carrying the channel's label as its header and the channel's physical unit in the column metadata.

When include_time is on, a single shared index column is built from the first channel's timestamps (unit s) — each channel keeps its own timestamps internally, but a rectangular frame needs exactly one index, so channel 0 provides it. The remaining columns follow in channel order.

Because channels may differ in length, the frame is made rectangular by NULL padding: every column is grown to the longest channel's row count, and the short tails become genuine missing cells (NaN value plus a validity mask reading false) rather than misleading zeros. A column that is already full-length takes a fast path with no mask allocated.

The node is stateless — the output depends only on the current input. It is the exact inverse of df_to_signals, and the natural front-end for exporting computed traces to CSV via file_export or viewing them in the DataGrid.

Mathematics

R = k max ∣ x^{(k)} ∣ (longest channel \Rightarrow row count)

col_{k} [i] = {x_{i}^{(k)}, NULL, i < ∣ x^{(k)} ∣ i \geq ∣ x^{(k)} ∣

time [i] = t_{i}^{(0)} (first channel’s timestamps, unit s)

Examples

Two channels to a table

Feed a 2-channel bundle (a = [1, 2], b = [3, 4], both sampled at $t = 0, 1$ ) with include_time = true.

| time | a | b | |------|---|---| | 0 | 1 | 3 | | 1 | 2 | 4 |

The result is a 3-column, 2-row frame ready for file_export or a DataGrid sink.

Unequal channels pad with nulls

With include_time = false and channels a = [1, 2, 3], b = [9], the frame has 3 rows. The short channel b fills rows 1 and 2 with NULL cells:

| a | b | |---|------| | 1 | 9 | | 2 | null | | 3 | null |

Downstream df_filter not_null on b would keep only the first row.

Applications

Exporting a set of computed signals or a full sensor bundle to CSV/TSV by wiring df into a file_export node.
Viewing multi-channel simulation output as a spreadsheet-style table in the DataGrid.
Preparing signal data for the columnar toolkit (select, filter, sort, slice, concat) before re-plotting with df_to_signals.
Aligning several traces of unequal length into one rectangular frame with explicit missing cells instead of padded zeros.

Neat

Short channels are padded with true NULLs (NaN + a validity mask), so a partial acquisition reads as missing data rather than as spurious zero samples — a common failure mode of naive zero-padding.

Full-length columns skip the mask allocation entirely (a validity-free fast path), so the common equal-length case pays no null-tracking overhead.

Each column inherits its channel's physical unit into the frame metadata, so a later file_export or set_unit round-trips units without a separate annotation step.

Known issues

Only the first channel's timestamps become the time column; if channels are on different time bases the index reflects channel 0 alone and other channels are aligned by row position, not by time.

With an empty input (zero channels) the frame has row_count 0 and, at most, an empty time column.