Python library#

The data/analysis core runs without a window, i.e., headless. The library can load logs, compute FFTs, and run the node transforms from a Python script through the facade in uz_dataviewer.api, which is re-exported at the package top level.

Note

Importing the package does not import the imgui GUI stack. import uz_dataviewer (and uz_dataviewer.api / .analysis / .nodes) only requires numpy/pandas/pyarrow. The GUI (DataViewerApp / main) is loaded lazily, only when you actually access it. The core is therefore usable on a headless server and import stays fast.

Quick start#

import uz_dataviewer as uz

data = uz.read("Log.csv")              # -> Dataset (shared time axis + named signals)
t, ia = data.time, data["ia"]

df = data.to_dataframe()               # pandas: column 'time' + one per signal

spec = uz.fft(t, ia)                   # -> FftResult (.freqs, .mag, .info, .ok); full span
sdf  = uz.fft_frame(t, ia)             # -> pandas DataFrame [frequency, amplitude]

# Node transforms — the exact calculations the GUI's node graph uses.
print(uz.kinds())                      # ('fft', 'math', 'filter', 'shift')
t2, y2, info = uz.node("filter", (t, ia), type="low", cutoff=40, taps=201)

A runnable version is in examples/headless_example.py.

API reference#

The facade adds no compute logic of its own. The facade reuses the loader, FFT and node transforms used by the GUI. Thus, the results of library usage matches the results of the GUI.

class uz_dataviewer.api.Dataset(parsed)#

Bases: object

A loaded log: a shared time axis plus named signal arrays.

Thin read-friendly wrapper over loader.ParsedRun. Index a signal by name (data["ia"]), test membership ("ia" in data), iterate names, or pull the whole thing into a DataFrame with to_dataframe().

property names: list[str]#: Ordered list of signal names in this dataset.

to_dataframe()#: Return a pandas.DataFrame of time + one column per signal.

class uz_dataviewer.analysis.FftResult(freqs: ndarray | None, mag: ndarray | None, info: str)

Bases: object

Single-sided amplitude spectrum plus a human-readable status line.

freqs: Frequency axis (Hz), None on failure.

mag: Amplitude (same units as input y), None on failure.

info: Human-readable description of the computation or the failure reason.

ok: True when freqs and mag are populated.

property ok: bool: True when the computation succeeded and freqs/mag are populated.

uz_dataviewer.api.read(path) → Dataset#: Load a .csv/.parquet log and return its data as a Dataset.

uz_dataviewer.api.fft(time, y, *, remove_dc: bool = True, window: bool = True, x_min: float | None = None, x_max: float | None = None) → FftResult#

Single-sided amplitude spectrum of y.

With no x_min/x_max the whole record is transformed. Returns a uz_dataviewer.analysis.FftResult (.freqs, .mag, .info, .ok).

uz_dataviewer.api.fft_frame(time, y, **kwargs)#

Like fft() but returns a pandas.DataFrame [frequency, amplitude].

Raises ValueError (with the reason) if the transform could not be computed.

uz_dataviewer.api.node(kind: str, *signals, **params)#

Run a node transform headlessly.

signals are (time, y) tuples (one for unary kinds, two for binary math); params override the kind’s defaults. Returns (out_time, out_y, info) – e.g. an fft node returns (freqs, mag, info). kind is one of kinds() (fft/math/filter/shift plus any plugins).

uz_dataviewer.api.filter(time, y, **params)#

Convenience wrapper over transforms.filter_node (FIR low/high/band-pass).

Returns (time, filtered_y, info).

uz_dataviewer.api.math(*signals, **params)#

Convenience wrapper over transforms.math_node (scale/offset/derivative/ integral/reciprocal and binary add/sub/mul/div).

signals are (time, y) tuples. Returns (time, y_out, info).

uz_dataviewer.api.kinds() → tuple[str, ...]#: The available node-transform kinds (builtins + any loaded plugins).

uz_dataviewer.api.load_plugins(dirs: list[str] | None = None, console=None) → tuple[str, ...]#: Import every *.py in the plugin directories and return the newly registered kinds. Missing directories are skipped; a failing file is logged (if console is given) and skipped. Never raises.