Usage guide

JavaScope interaction

uz_dataviewer is designed to work with the data logged by the UltraZohm hardware and the JavaScope software. JavaScope is for running an experiment: connect, trigger, observe live, tune parameters, and record. uz_dataviewer is for understanding the recording afterwards: open one or many logs, arrange subplots, zoom into gigabyte-scale data, run FFTs.

  UltraZohm hardware
       │  TCP :1000  (live stream, 20 ch)
       ▼
┌──────────────────────┐     commands / parameters
│  JavaScope (Java)     │ ───────────────────────────►  back to device
│  live scope + control │
└──────────┬───────────┘
           │ writes
           ▼
     Log_*.csv  ──────────────┬───────────────► Matlab (JS_plot_data.m), Python (uz_dataviewer.read())
                              │
                              ▼
                ┌────────────────────────────┐
                │  (uz_dataviewer)           │  Data inspection, FFT, analysis
                └────────────────────────────┘

Loading data

• Navigation ▸ Open file(s)… loads .csv (JavaScope ;-separated or standard ,-separated — the delimiter is auto-detected) and .parquet, multiple at once. On the desktop you can also drag .csv/.parquet files onto the window.

• Expand a run to see its channels. The checkbox (de)activates a run; right-click ▸ Remove run drops it.

• Per-log time normalization: right-click a run ▸ tick Normalize start time and enter a start (default 0), then Apply. This shifts that log’s time axis without touching the samples; untick to restore. (Also load("Log.csv", 0).)

• Large logs: channels load compactly and large Parquet files stream in, so a multi-million-sample log opens at roughly its in-memory size. A very large CSV is refused (parsing it whole would risk running out of memory) with a message pointing you to convert it once: convert("Log.csv") in the console, or uz-dataviewer convert Log.csv from a shell — both write a .parquet beside the source that loads leanly. (Native; the browser build is bounded by its ~4 GB limit — see Limitations of web version.)

Window types

The center area holds four window types, shown as dockable tabs:

• Plot window

• FFT window

• Histogram window

• Nodes (transforms → derived signals)

Plot window

• Drag a channel from the tree onto a plot cell to add it.

• Layout toolbar sets the grid (1x1 default … 2x2, 3x1, …).

• Type (per cell): line / scatter / stairs / xy (one signal vs another — pick the X signal in the cell header, and a style dropdown selects Line / Markers / Both). Time-series types preserve spikes when downsampling; xy uses a plain stride, so a very dense phase plot can alias.

• Link X axes (toolbar): pan/zoom one subplot and the others follow. Any plot you pan/zoom drives the shared range — there is no master plot; all linked plots show the same time window.

• Max points (toolbar, with a quick-pick presets dropdown): the per-signal drawing budget — the visible window is drawn with about this many points and stays ~constant as you zoom. “downsampling: active” means the view is decimated; it switches to “off (all samples)” once the visible window holds fewer raw samples than Max points. The cell header shows ~N pts shown (M in view) so you see both the drawn budget and the raw samples in the window.

• Reset view auto-fits the cell to its data; Clear empties it.

• Right axis: right-click a signal in the legend ▸ Right axis to put it on its own (secondary Y) scale.

• samples — a marker at every sample. spy — drag a rectangle on the plot; the inset below shows just that region (its line colours match the main plot). cursors — two draggable vertical lines with a Δx / frequency / Δy readout. Enabling cursors/spy places them at 25 % / 75 % of the current view, so they always start on-screen.

• Export writes the cell’s signals over its current X window to CSV; tick start at 0 to rebase the time column. (The export is comma-separated and re-imports cleanly. On a log already time-normalized to 0, the start is 0 either way.)

For all plots: the mouse wheel zooms, right-click and drag draws a zoom rectangle, hold Shift to zoom only X, hold Alt to zoom only Y. Right-click an axis for more options.

FFT window

1. Drag signals in (from the tree or a plot) to overlay several.

2. Window selector — choose the time window:

   • plot_N — follow that subplot’s current X range (computes immediately),

   • Full — the whole record,

   • Custom — type t min / t max.

   Switching to Full / Custom does not auto-compute (the window may be huge).

3. Press Compute. If settings changed since the last compute you’ll see ⚠ stale - press Compute.

4. Options: Remove DC, Hann window, log x / log y.

5. Export writes the spectrum to CSV (frequency,<sig>…).

Histogram window

The Histogram window works exactly like the FFT window: drag signals in, pick the time window, press Compute, and Export (bin_center,<sig>…). Its only option is the number of bins.

Nodes (transforms → derived signals)

The Nodes window is a dataflow canvas: build a small graph that turns signals into new signals, which then appear in Navigation and can be dragged into any plot / FFT / Histogram like a loaded channel.

1. Add a source — drag a channel from Navigation onto the canvas; a source node wraps that signal at the drop point (or node_source(run, signal)). Tick crop time on the node to use only a t min … t max window instead of the full record.

2. Add a transform — toolbar + fft / + math / + filter / + shift:

   • fft — amplitude spectrum (its output’s x-axis is frequency); options remove DC, Hann.

   • math — scale / offset (with a constant k), derivative, integral, reciprocal (1/A) (one input), or A+B / A-B / A*B / A/B (two inputs of equal length).

   • filter — windowed-sinc FIR low / high / band pass; set cutoff (Hz), cutoff2 for band, and taps (more = sharper).

   • shift — offset the signal’s time axis by a constant (by seconds).

3. Wire it — drag from a node’s out pin to another node’s in pin. You can chain transforms (e.g. filter → fft).

4. Evaluate — the toolbar Evaluate (whole graph) or a node’s eval button computes on demand and materializes each transform’s result as a derived run named node_<id>. Edit anything and the node shows (stale) until re-evaluated.

5. Use the result — the derived node_<id> appears in Navigation; drag its out channel into a plot, or feed it to the FFT / Histogram windows.

Everything here is a command (node_*), so a graph is fully scriptable and saved with the session. Double-click a node to rename it inline; its derived signal takes the new name (or node_rename(node, name)).

Custom transforms (plugins): you can add your own node kinds by dropping a small Python file in a plugin folder — see Node plugins.

Console & scripting

Every action is echoed to the Console as a canonical command (> add_signal(plot_1, run_1, ia), and > set_x_lim(plot_1, 1.2, 1.8) when you zoom). The input box runs the same commands:

• type a command name for completion (matches listed below the box; Tab fills the first; Up/Down cycle history),

• help lists everything, help <name> shows one,

• the log body is always selectable (drag to mark, Ctrl+C to copy) and auto-scrolls.

load("Log.csv")                         # optional 2nd arg normalises the start time
set_grid(2, 2)
add_signal(plot_1, run_1, ia)           # run by id ...
add_signal(plot_2, Log.csv, Speed_rpm)  # ... or by file label
set_axis(plot_1, run_1, Speed_rpm, right)
cursors(plot_1, on)
fft_source(run_1, ia)                    # send to the FFT window
fft_follow(full)                         # analyse the whole record
fft()                                    # compute + focus the FFT window
export_data(plot_1, "out.csv", true)     # true = rebase start time to 0

Plots are referenced plot_1..plot_N (row-major); runs as run_<id> or by filename.

Save / restore a session

• Session ▸ Save state… / Load state… — exact JSON snapshot (grid, assignments, plot types, cursors/spy, secondary axes, FFT/Histogram config, time normalization, file list); restore reloads the files and rebuilds the view.

• Session ▸ Export script… / Run script… — an editable .uzscript of commands that reproduces the session when replayed.

Command reference

The Arguments column lists each parameter as name:kind; optional ones are bracketed ([start:float]). The argument kinds are: plot = plot_N; run = run_N or a file label; fwindow = custom / full / plot_N; bool = on/off (or true/false); the rest are int / float / str.

Table 8 uz_dataviewer console commands

Command	Group	Description	Arguments	Source
load	Data / runs	Load a .csv/.parquet log; the optional start normalises the time origin.	path:str, [start:float]	commands.py:330
convert	Data / runs	Stream-convert a large CSV to Parquet (loads with a ~1.5x memory peak); dst defaults to src with a .parquet extension.	src:str, [dst:str]	commands.py:339
normalize_time	Data / runs	Shift a run so its first sample sits at start (default 0).	run:run, [start:float]	commands.py:350
reset_time	Data / runs	Restore a run’s original (un-normalised) timestamps.	run:run	commands.py:360
remove_run	Data / runs	Remove a loaded run and its plots.	run:run	commands.py:386
set_active	Data / runs	Show/hide a run without removing it.	run:run, on:bool	commands.py:391
set_grid	Layout	Set the subplot grid to rows x cols.	rows:int, cols:int	commands.py:369
link_x	Layout	Link/unlink the X axes across subplots.	on:bool	commands.py:375
set_max_points	Layout	Max points drawn per signal (downsample budget).	n:int	commands.py:380
add_signal	Signals	Add a signal to a subplot.	plot:plot, run:run, signal:str	commands.py:400
remove_signal	Signals	Remove a signal from a subplot.	plot:plot, run:run, signal:str	commands.py:409
clear_plot	Signals	Remove all signals from a subplot.	plot:plot	commands.py:416
set_plot_type	Signals	Set a subplot’s type (line/scatter/stairs/xy).	plot:plot, type:str	commands.py:421
set_xy_style	Signals	Set the XY plot draw style: Line, Markers, or Both.	plot:plot, style:str	commands.py:427
set_xy	Signals	Use a signal as the X axis (XY plot) for a subplot.	plot:plot, run:run, signal:str	commands.py:486
set_axis	Signals	Assign a signal to the left or right Y axis of a subplot.	plot:plot, run:run, signal:str, side:str	commands.py:516
set_x_lim	View	Set a subplot’s X-axis limits.	plot:plot, min:float, max:float	commands.py:438
set_y_lim	View	Set a subplot’s Y-axis limits.	plot:plot, min:float, max:float	commands.py:448
reset_view	View	Auto-fit a subplot to its data extent.	plot:plot	commands.py:455
show_samples	Tools	Toggle per-sample markers on a subplot.	plot:plot, on:bool	commands.py:460
spy	Tools	Toggle the spy (drag-rect zoom inset) on a subplot.	plot:plot, on:bool	commands.py:466
set_spy_rect	Tools	Position the spy rectangle (enables spy).	plot:plot, xmin:float, ymin:float, xmax:float, ymax:float	commands.py:475
cursors	Tools	Toggle two measurement cursors (Δx / frequency readout) on a subplot.	plot:plot, on:bool	commands.py:498
set_cursors	Tools	Place the two cursors at x1 and x2 (enables cursors).	plot:plot, x1:float, x2:float	commands.py:507
export_data	Tools	Export a subplot’s signals to CSV (relative=true zeroes the start time).	plot:plot, path:str, [relative:bool]	commands.py:536
set_export_relative	Tools	Toggle ‘start time at 0’ for a subplot’s CSV export.	plot:plot, on:bool	commands.py:545
fft_source	FFT window	Add a signal to the FFT window (it can show several at once).	run:run, signal:str	commands.py:559
fft_clear	FFT window	Remove all signals from the FFT window.		commands.py:572
fft_remove	FFT window	Remove a signal from the FFT window.	run:run, signal:str	commands.py:577
fft_follow	FFT window	Set the FFT time window source (custom / full / plot_N).	target:fwindow	commands.py:587
fft_range	FFT window	Set the FFT custom time window.	min:float, max:float	commands.py:599
fft_xlim	FFT window	Set the FFT plot’s X-axis view limits.	min:float, max:float	commands.py:606
fft	FFT window	Recompute and focus the FFT window.		commands.py:615
fft_remove_dc	FFT window	Toggle FFT DC removal.	on:bool	commands.py:621
fft_hann	FFT window	Toggle the FFT Hann window.	on:bool	commands.py:627
fft_logx	FFT window	Toggle the FFT log X axis.	on:bool	commands.py:633
fft_logy	FFT window	Toggle the FFT log Y axis.	on:bool	commands.py:638
fft_export	FFT window	Export the FFT spectra to CSV.	path:str	commands.py:643
hist_source	Histogram window	Add a signal to the Histogram window (it can show several at once).	run:run, signal:str	commands.py:559
hist_clear	Histogram window	Remove all signals from the Histogram window.		commands.py:572
hist_remove	Histogram window	Remove a signal from the Histogram window.	run:run, signal:str	commands.py:577
hist_follow	Histogram window	Set the Histogram time window source (custom / full / plot_N).	target:fwindow	commands.py:587
hist_range	Histogram window	Set the Histogram custom time window.	min:float, max:float	commands.py:599
hist_xlim	Histogram window	Set the Histogram plot’s X-axis view limits.	min:float, max:float	commands.py:606
histogram	Histogram window	Recompute and focus the Histogram window.		commands.py:650
hist_bins	Histogram window	Set the Histogram bin count.	n:int	commands.py:656
hist_export	Histogram window	Export the histogram bins to CSV.	path:str	commands.py:662
node_source	Nodes	Add a source node wrapping a loaded signal (the graph’s input).	run:run, signal:str	commands.py:729
node_add	Nodes	Add a transform node (fft, math, filter, shift, or an installed plugin kind).	kind:str	commands.py:739
node_set	Nodes	Set a transform node parameter (e.g. node_set(node_2, cutoff, 1000)).	node:node, key:str, value:str	commands.py:750
node_link	Nodes	Connect a node’s output to another node’s input.	src:node, dst:node	commands.py:757
node_unlink	Nodes	Disconnect a node link.	src:node, dst:node	commands.py:763
node_remove	Nodes	Remove a node (and its derived run, if any).	node:node	commands.py:769
node_rename	Nodes	Rename a node (its derived run takes the new name).	node:node, name:str	commands.py:778
node_pos	Nodes	Set a node’s canvas position.	node:node, x:float, y:float	commands.py:791
node_eval	Nodes	Evaluate the graph (or one node + its inputs), materializing derived signals.	[node:node]	commands.py:797
load_plugins	Nodes	Load external node plugins from a directory (or the configured defaults).	[dir:str]	commands.py:804
save_state	Session	Save the GUI state to a JSON file.	path:str	commands.py:673
load_state	Session	Restore the GUI state from a JSON file.	path:str	commands.py:680
export_script	Session	Write the session as a replayable .uzscript.	path:str	commands.py:687
run_script	Session	Replay commands from a .uzscript file.	path:str	commands.py:695
clear_console	Console	Clear the console log.		commands.py:703
help	Console	List commands, or show help for one.	[name:str]	commands.py:708

This table is generated from the live command registry (python -m uz_dataviewer.command_doc), and help prints the same list in the console, so both stay current.