Data sources & formats

Opening files

Use File → Open File… (⌘O), the + menu in the source browser, or drag files onto the window.

Select a folder to open every supported file inside it, recursively. Unsupported files are skipped, as are paths that are already open.

Files open in the window you are working in. To send one to a different window, drag it there — see Moving a file to another window.

Supported formats

CSV, TSV and TXT

• The delimiter (comma or tab) and the presence of a header row are detected automatically.
• Quoted fields are supported.
• Every column becomes a trace, including timestamp columns. Assign an x-axis explicitly — see Assigning a custom x-axis.
• Values that do not parse as numbers become NaN and appear as gaps.

Parquet

Only numeric columns are exposed; strings, dates and structs are skipped. Each column keeps its declared type. Values are read as doubles, which is exact except at the extremes of 64-bit integers.

Arrow IPC

Read as an Arrow IPC stream, with column names taken from the schema. Every numeric column becomes a trace, read at its own width. X-values come from the stream, so an Arrow file can carry a non-uniform x-axis.

This is the same format as the Arrow IPC decoder used for live connections.

Audio

Refract opens every audio format macOS can decode — uncompressed, lossless and lossy alike. Compressed files are decoded to samples as they load, so an MP3 or a FLAC plots exactly like a WAV — no conversion step first.

Channels and the x-axis

Channels become traces: stereo files give Left and Right, others give Channel 1, Channel 2 and so on.

The file's sample rate is applied to the x-axis automatically, so audio plots against seconds. The browser shows the rate beside the index row, for example @ 48000Hz. Edit it like any other transform — see X-axis transforms.

What the samples are measured in

Refract plots audio in the units the file actually carries rather than normalising everything to ±1.0. Which units those are depends on how the samples were stored, and the sample type shown in the browser tells you which case you have.

Autoscale handles the difference, so you rarely have to think about it — but it is worth knowing when you compare two files, or write a formula that mixes them. See Sample types.

Sample types

Every signal carries the type its source declared, one of ten:

The type appears as a small tag beside the signal in the formula pane. It decides whether bitwise operators accept the signal directly: over an int32 column you can write counter & 0xFF, with no bits() needed. See Types.

Loading

Opening a file reads only its header, so traces appear immediately with no samples. The full parse runs in the background the first time you plot a signal or reference it in a formula; a spinner appears in the affected track.

The source browser

The sidebar lists every source with its traces nested underneath. Click the chevron to expand or collapse a source; the footer counts what is open.

Row markers

Traces using a custom x-axis are indented beneath the trace providing it. RefractIO connections group their traces by table.

Selecting

• Click a trace to select it, or a source header to select all of its traces.
• ⌘-click toggles; ⇧-click extends.
• ⌘A selects everything visible; Esc clears the selection.

Keyboard navigation

Dragging

• Drag a trace to a track, to Add Track, or onto another trace to assign an x-axis.
• Drag a source header to move all of its traces at once.
• Dragging with several rows selected moves the whole selection.
• Dragging a signal from one track to another moves it rather than copying it.
• Dragging a file's row out of the window moves the file itself — see Moving a file to another window.

Context menus

On a source: Show in Finder (files); Edit Connection…, View Raw Stream, Clear Buffer and Reconnect (connections); Close.

On a trace: Edit Formula…, Reset to Loaded Values, Set X-Axis Transform…, Remove as X-Axis, Reset X-Axis to Index, and Delete for computed signals. Double-clicking a trace opens the formula pane.

Moving a file to another window

Refract opens as many windows as you like — File → New Window (⌘N). Each one keeps its own sources, tracks and viewport, which is how you compare two runs side by side without stacking them on the same axis.

A file that landed in the wrong window does not have to be closed and reopened. Drag its row out of the source browser and drop it on another window: the file opens there and closes here.

Where you drop it

What moves

• Whole files only. Drag a source header, or a trace row inside a source whose rows are all selected. A drag that covers only part of a file has nothing to move — there is no way to open half a file elsewhere.
• Multi-selection moves every file the selection covers entirely. A file with only some of its traces selected stays where it is.
• Connections and computed signals stay put. Neither has a file to reopen in the other window.
• A file the destination already has open is not opened twice, but it still leaves the window it came from.
• Dropping a file back in the window it came from does nothing.

Closing a source

Click × on the source row, use the context menu, or press ⌘⌫.

Closing removes the source's signals from every track. Closing a connection also stops it. Any computed signal that depended on the source is marked broken and stops drawing.