Concat Frames

Shipping

df_concat

Combine 2–4 DataFrames: stack rows (append) or join columns (side by side)

Signature

Inputs

aDataFramerequired— First frame (required).
bDataFramerequired— Second frame (required).
cDataFrame— Third frame (optional). Skipped if unwired.
dDataFrame— Fourth frame (optional). Skipped if unwired.

Outputs

dfDataFrame— The merged frame — stacked rows or side-by-side columns depending on axis.

Parameters

Key	Type	Default	Notes
`axis`	enum	rows	one of: rows, cols

Description

Concat Frames (df_concat) combines 2–4 DataFrames — inputs a/b are required, c/d optional and skipped when unwired — into one frame, in port order. The axis param picks the direction.

Rows (axis = rows) stacks the frames vertically (append rows). All frames must have the same column count (a mismatch is an error). For each column position the frames' columns merge: identical dtypes keep the type; an all-numeric mix widens to `f64` (lossless across i64/bool/datetime/f64); anything text-involved stringifies (lossless display). Names come from the first frame; a column's unit is kept only if all frames agree, else cleared. Null masks are concatenated in order.

Columns (axis = cols) places the frames side by side — every column of every frame, in order. Frames shorter than the longest are padded with NULL rows so all columns are equal length, and duplicate column names get a numeric suffix (v, v_2, v_3, …). The node is stateless.

Mathematics

rows: out [c] = col^{(0)} [c] ∥ col^{(1)} [c] ∥ \dots (same column count required)

dtype merge: same \to keep, all numeric \to f 64, else \to str

cols: out = [all columns of a, b, \dots], R = f max rows (f), short frames padded NULL

Examples

Stack rows (append)

Frame a with x = [1, 2] and frame b with x = [3], axis = rows, gives a 3-row frame x = [1, 2, 3]. Both x columns are f64, so the dtype is preserved.

Join columns side by side

Frame a with v = [1, 2] and frame b with v = [9], axis = cols, gives a 2-column frame: v = [1, 2] and v_2 = [9, null] — the shorter frame is null-padded to length 2 and the duplicate name is suffixed.

Applications

Appending runs / trials (same schema) into one long table for pooled analysis.
Joining two aligned measurement frames column-wise (e.g. inputs beside outputs) into a single export.
Merging batches of imported CSVs of identical column layout with a single node (up to 4 at a time).
Building a wide comparison table from independently computed columns, letting null padding handle length differences.

Neat

Row-stacking widens conflicting dtypes to the narrowest lossless type — all-numeric to f64, otherwise to a string display — so mixed-type stacks never silently corrupt values.

Column-stacking auto-disambiguates duplicate headers (v, v_2, v_3…) and null-pads short frames, so heterogeneous-length joins always produce a rectangular frame.

Units survive a row concat only when every source agrees; a disagreement clears the unit rather than picking an arbitrary one, avoiding a misleading label.

Known issues

Row concat requires matching column counts across all wired frames; a mismatch is a hard error (align schemas with df_select first).

Row concat merges by column position, not by name — columns must line up positionally even if the names differ.

Column concat pads by row position with nulls; it does not join on a key, so rows are not matched by value.