File Import
Shippingstatefulfile_importRead a CSV/TSV/TXT file into a typed DataFrame, Signal, or Signal Bundle
Signature
Outputs
dataDataFrame|Signal|SignalBundle— The parsed file as a typed DataFrame, or folded into a Signal / Signal Bundle depending on Output As.
Parameters
| Key | Type | Default | Notes |
|---|---|---|---|
file_path | path | Path to the CSV / TSV / TXT file to import (open-file picker, extensions csv/tsv/txt/dat/tab/asc). | |
format | enum | auto | one of: auto, csv, tsv, txt |
output_as | enum | dataframe | one of: dataframe, signal, signal_bundle |
delimiter | enum | auto | one of: auto, comma, semicolon, tab, space, whitespace, pipe |
has_header | bool | true | Treat the first (non-skipped) row as column names. A trailing 'name [unit]' is split into a column unit. |
skip_rows | int | 0 | Number of leading rows to discard before the header (file preamble). |
comment_char | text | # | Lines starting with this character are ignored. Empty = none. |
decimal_sep | enum | . | one of: ., , |
thousands_sep | enum | none | one of: none, comma, period, space |
encoding | enum | auto | one of: auto, utf8, latin1 |
null_tokens | text | NA,NaN,null | Comma-separated tokens that mean an empty/missing cell. |
max_rows | int | 0 | Limit the number of data rows read (0 = all). |
time_column | int | -1 | 0-based column index used as the time axis (-1 = synthesize from Sample Rate). Active only in signal modes. |
value_column | int | 0 | 0-based column index used as the signal values (single-Signal mode only). |
sample_rate | float | 1000.0Hz | Sampling rate used when no time column is chosen. Active only in signal modes. |
unit | text | Physical unit for the signal values when the column header carries none. Active only in signal modes. |
Description
File Import is a pure source node (no inputs, one data output) that reads a delimited text file — CSV, TSV, or whitespace-separated TXT — and parses it into a typed DataFrame. Optionally it folds the numeric columns into a Signal (one column) or a SignalBundle (one Signal per numeric column) via the output_as selector, so a file can drop straight onto the canvas as either a table or a waveform bus.
Parsing is fully configurable: delimiter, has_header, skip_rows, comment_char, decimal_sep, thousands_sep, encoding, null_tokens, and max_rows cover the messy realities of instrument exports and European locale files. When a header cell is written as name [unit], the trailing bracketed token is split off and attached to that column as its physical unit, so units survive import into Captyse's dimensional algebra automatically.
The parse is cached in node state, fingerprinted by (path, mtime, parse-options). On a re-run — including a live 20 Hz tick — an unchanged file is never re-read or re-parsed; only the cheap output-shape conversion runs. Switching output_as reuses the cached frame because the output mode is deliberately excluded from the fingerprint. This is what makes File Import stateful: the cache is real memory carried across evaluations.
On every run the resolved output is also upserted (idempotently, keyed by node id) into the workspace MEMORY_REGISTRY, so an import appears in the Explorer immediately and is {{name}}-referenceable without wiring a sink. An empty file_path is a hard error; a genuine read/parse failure surfaces as a node error so the user sees the bad path.
Examples
Import a sensor log as a DataFrame
Point file_path at run_03.csv, leave output_as = dataframe. A file whose header reads t [s],accel [m/s^2],temp [degC] parses to a 3-column typed table where each column carries its own unit. The frame lands in the Explorer and can be referenced elsewhere as {{run_03}}.
Fold columns into a waveform bundle
Set output_as = signal_bundle and time_column = 0. Every remaining numeric column becomes its own Signal sampled against column 0 as the time axis, emitted as one SignalBundle ready for a multi-trace plot:
t,a,b
0,1,10
1,2,20 --> bundle = [ Signal(a)=[1,2,3], Signal(b)=[10,20,30] ]
2,3,30Single Signal from one column
With output_as = signal, value_column = 2, and time_column = -1, the node synthesizes a uniform time base at sample_rate (default 1000 Hz) and emits column 2 as a lone Signal — handy when the file has no explicit time axis.
Applications
- Loading recorded instrument/DAQ logs (CSV/TSV) into a processing graph without any preprocessing script.
- Ingesting European-locale exports with comma decimals and space/period thousands separators directly.
- Turning a wide multi-column measurement file into a Signal Bundle for synchronized multi-trace plotting and analysis.
- Seeding a graph from a reference dataset that then appears in the Explorer for reuse across multiple graphs via {{name}} references.
Neat
The parse cache is keyed by file mtime, so File Import survives a 20 Hz live tick reading a static file with near-zero cost — only the output-shape conversion re-runs.
`output_as` is intentionally left out of the cache fingerprint, so toggling between DataFrame / Signal / Bundle never forces a re-read; the same parsed frame is simply reshaped.
Column units are recovered from `name [unit]` header syntax, so a well-labeled CSV round-trips its dimensional metadata into Captyse without manual annotation.
The output is upserted into the memory registry keyed by node id, so an import is instantly visible in the Explorer and addressable by name without a sink.
Known issues
An empty File Path is a hard error rather than an idle no-op, unlike the registry sources — the node needs a path to do anything.
In single-Signal / Bundle modes only numeric columns fold into waveforms; text columns are excluded from the Signal output (they remain in the DataFrame mode).
Auto delimiter/encoding detection is heuristic; unusual files may need the delimiter, decimal, thousands, or encoding set explicitly to parse correctly.