Working with data
Measuring
Cursors and ranges over the plot, the samples underneath as a spreadsheet, and a calculation pad beside it.
Turning measuring on
Press the Measure button in the toolbar, or ⌘'. A readout panel docks under the tracks; drag its top edge to resize it. You can also measure without opening the panel at all — see Measuring without switching the tool on.
- Measure — the toolbar toggle, or ⌘'.
- Numbered chips — drawn on the topmost track only; the lines cross every track.
- Snap dots — the sample each visible signal resolved to.
- Tool — cursors or a range. Switching discards the other tool's marks.
- The table — one row per cursor, one column per visible signal, grouped under the track it sits on.
- The calculation pad — expressions over the table, answers in a column of their own.
There are two tools, chosen with the segmented control in the panel header:
| Tool | Marks | Table rows |
|---|---|---|
| Cursors | Numbered vertical lines you place one at a time. | One per cursor. |
| Range | A shaded band between two edges. | One per sample inside the band. |
Switching between the two tools discards the other's marks. Switching the tool off keeps them drawn over the plot, so you can go back to zooming and still see what you measured.
| Action | Effect |
|---|---|
| ⌘' or the toolbar button | Switch the tool on and off. The panel follows. |
| ⇧⌘' or Clear | Discard the cursors and the range, keeping the tool on. |
| × in the panel header | Close the panel and discard the measurement. |
While a tool is on it takes over the plot's drag gesture, so drag-to-zoom and double-click-to-reset are suspended there. The ruler, the y-axes and the zoom commands still work.
Measuring without switching the tool on
You do not have to turn Measure on first. Two modifiers borrow a measurement tool for the length of a single gesture, without opening the panel.
| Gesture | Result |
|---|---|
| ⌘-click a plot | Place a measurement cursor. |
| ⇧-drag across a plot | Select a statistics range. |
| Drag, with nothing held | Zoom, exactly as before. |
The marks are drawn over the plot exactly as they are with the tool on, so you can annotate a plot, carry on zooming, and press ⌘' only when you want the numbers. The panel opens on whichever tool you last used.
How a modifier and the tool interact
A held modifier wins over whatever tool is switched on, so ⌘ places a cursor even while the range tool is active. Where both are held, ⌘ beats ⇧.
| Gesture | Tool on | Result |
|---|---|---|
| ⌘-click | None | Cursor placed. The panel stays closed. |
| ⇧-drag | None | Range selected. The panel stays closed. |
| ⌘-click | Range | Cursor placed, and the open panel switches to cursors. |
| ⇧-drag | Cursors | Range selected, and the open panel switches to range. |
| ⌘-click | Cursors | Cursor placed, the same as a plain click. |
| Bare drag | None | Zooms. |
Cursors and a range never coexist. Landing one drops the other, which is the same thing switching tools has always done — a modifier just makes the switch one gesture at a time.
The panel follows the gesture only when it is already open. A ⌘-click on a plot with the panel closed leaves it closed, which is the point of reaching the tools this way; Refract still records which tool you used, so the next ⌘' opens on it.
Cursors
With the cursor tool on, click anywhere in a plot to drop a cursor — or ⌘-click with no tool on at all. Drag it to move it; click it again to remove it. Pressing on empty plot creates a cursor straight away, so one motion can drop it and slide it into place.
A cursor marks an x position, so its line is drawn across every track and the panel reports every visible signal at that x. Numbered chips appear on the topmost track only.
Cursors always snap to the nearest sample of a visible signal on the track you clicked, so a reading is never taken from between samples. A dot on each visible signal shows which sample was picked.
Cursors stay sorted left to right, so their numbers always match the order on screen and the order of the rows in the table.
A cursor reports every signal at the one x it marks, and stays there. For a reading that follows the pointer and leaves nothing behind, quoting each sample at its own x, see the crosshair.
Range
With the range tool on, drag across a plot to select a range — or ⇧-drag with no tool on at all. Drag either edge to adjust it; a click on open plot clears it. The band shades every track.
The summary strip above the table reports Rows, and then
From, To and Span. A span on an axis that
measures time is reported in SI units — 12.4 ms — rather than as a bare
number.
Rows are the samples inside the band. They follow the densest axis among the visible signals, and signals on any other axis are sampled onto it.
Those three describe what the measurement covers, not where the pointer stopped: they are the first and last row's own x, so the span is the samples in the table and nothing more. A drag lands between samples, and a band dragged across five samples of a 10 Hz log would otherwise claim a span up to 40% longer than the samples it holds. The numbers snap to the rows underneath as you drag, so what the strip says is always backed by a row.
A band covering no samples reports Rows 0 and nothing else — there is no
start, finish or span to quote.
A range can cover millions of samples without slowing the panel down — rows are built only as you scroll to them.
The measurement table
Rows are x positions; columns are the visible signals, in track order, each under a tinted band naming the track it sits on.
- Row number — 0-based, and the number a formula uses to index the column.
- x column — the position each row was taken at.
- Track band — spans exactly the columns belonging to that track.
- No value — the signal has a gap at this row.
The table follows the tracks. Add a signal, hide one, or reorder the tracks, and the columns change with them.
Every column is a signal on a track. To measure something the table does not already hold, add it as a computed signal — it then appears here as a column like any other.
Absolute values and deltas
Click a column header to switch that column between absolute values and the step from the row above. Click it again to switch back. The x column toggles the same way, where the step is the spacing between adjacent rows — the cursor-to-cursor interval on a time axis. Any number of columns can be in delta mode at once.
A column showing steps marks itself with a hollow triangle in place of its filled dot.
- Steps are signed, and tinted green or red by direction.
- x steps carry the axis's unit when it measures time. A y step is a difference between two samples, so it carries no x unit.
- A row with nothing above it to measure from — the first row, or the first reading after a gap — shows its absolute value instead, dimmed and slanted.
- A row with no reading at all shows
—. - A delta column holds the same values
diff()would compute over it. - Deltas are a display choice only. Copying follows what is on screen, but a reference inserted from a cell always names the sample, never the step.
The calculation pad
The pad sits to the right of the table. Each line is an expression over the table's columns, with its answer right-aligned in a column of its own. Drag the splitter between the two to set the pad's width; the width survives closing and reopening the panel.
Reducers scope to whatever the table currently holds, so mean(voltage) follows the
cursor set or the selected range and re-evaluates as either changes.
Editing
The pad keeps an empty line at the bottom and the keyboard does the rest; there is no add or remove button.
| Key | Action |
|---|---|
| Return | Accept the highlighted suggestion, or move to the next line, opening one if needed. |
| ⌫ | At the head of an empty line, close it and put the caret at the end of the line above. |
| ↑ ↓ | Cycle suggestions. With no list showing, walk the pad as one document. |
| Tab | Take the suggestion when it is the only one, otherwise step to the next. |
| Esc | Dismiss the suggestion list. |
Autocomplete offers the table's signals and the lines above the caret. A signal is inserted qualified by its source when its name alone would be ambiguous.
Answers
- A line that reduces to a single number shows that number, to six significant figures.
- A line that produces one value per row is a column, not an answer: the pad reports n pts, which is the cue to wrap it in a reducer.
- While you are typing, the column holds the last answer that parsed, dimmed.
- A committed error shows a warning triangle with the reason on hover; the editor marks the offending token.
Referring to cells and lines
Click a cell in the table to write a reference to it into the pad. Drag down a column to select a span of rows and reference all of them at once.
| In the table | Inserted | Means |
|---|---|---|
| Click one cell | voltage[2] | That signal at row 2. |
| Drag down a column | voltage[2:5] | Rows 2 to 5, inclusive at both ends. |
| Click an answer in the pad | line2 or its name | That line's answer. |
Row numbers count from zero, matching the chips on the plot and the row-number column:
voltage[0] is the first row, and a span is inclusive at both ends. The
reference lands at the caret in the line you were last editing, and the keyboard follows it
there.
Naming a line
Write name = expression to name a line's answer. Lines below can then use that name.
Every line is also reachable as line0, line1, … whether it is named
or not — the first line is line0.
References only reach upward: a line can name the lines above it, never below.
- Redefining a name shadows the earlier one from that line down.
- Deleting a line renumbers the
line<N>references that pointed past it. - A reference to the deleted line becomes
line_deleted, which never resolves — so it reads as broken instead of silently pointing at whichever line moved into that number.
The x column is not a formula reference. To read a Δx, switch the x column to deltas, or reference a signal that carries the value you want.
Copying readouts
⌘-click a cell, or right-click it and choose Copy. A pad answer that is a single number copies the same way; ⌘-clicking any other answer inserts a reference to it instead.
Values reach the clipboard at full precision, not the six figures shown on screen.
Examples
voltage[2] - voltage[0]max(current) - min(current)rms(voltage - mean(voltage))span = max(temperature) - min(temperature)
span / 2mean(voltage[10:200])count(temperature)