ultrazohm-dataviewer 0.1.80.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. ultrazohm_dataviewer/__init__.py +44 -0
  2. ultrazohm_dataviewer/__main__.py +8 -0
  3. ultrazohm_dataviewer/_version.py +1 -0
  4. ultrazohm_dataviewer/analysis.py +321 -0
  5. ultrazohm_dataviewer/analysis_service.py +42 -0
  6. ultrazohm_dataviewer/api.py +190 -0
  7. ultrazohm_dataviewer/app.py +609 -0
  8. ultrazohm_dataviewer/assets/app_settings/icon.ico +0 -0
  9. ultrazohm_dataviewer/assets/app_settings/icon.png +0 -0
  10. ultrazohm_dataviewer/assets/favicon.svg +11 -0
  11. ultrazohm_dataviewer/cli.py +107 -0
  12. ultrazohm_dataviewer/cli_console.py +113 -0
  13. ultrazohm_dataviewer/client.py +183 -0
  14. ultrazohm_dataviewer/client_methods.py +237 -0
  15. ultrazohm_dataviewer/command_doc.py +137 -0
  16. ultrazohm_dataviewer/commands.py +812 -0
  17. ultrazohm_dataviewer/console.py +102 -0
  18. ultrazohm_dataviewer/control_credentials.py +53 -0
  19. ultrazohm_dataviewer/control_protocol.py +41 -0
  20. ultrazohm_dataviewer/control_server.py +196 -0
  21. ultrazohm_dataviewer/csv_policy.py +9 -0
  22. ultrazohm_dataviewer/csv_source.py +53 -0
  23. ultrazohm_dataviewer/downsample.py +43 -0
  24. ultrazohm_dataviewer/exports.py +51 -0
  25. ultrazohm_dataviewer/flashing.py +94 -0
  26. ultrazohm_dataviewer/live.py +990 -0
  27. ultrazohm_dataviewer/live_mapping.py +54 -0
  28. ultrazohm_dataviewer/live_settings.py +87 -0
  29. ultrazohm_dataviewer/loader.py +574 -0
  30. ultrazohm_dataviewer/loading.py +49 -0
  31. ultrazohm_dataviewer/model.py +256 -0
  32. ultrazohm_dataviewer/node_jobs.py +63 -0
  33. ultrazohm_dataviewer/nodes.py +598 -0
  34. ultrazohm_dataviewer/operations.py +386 -0
  35. ultrazohm_dataviewer/panels/__init__.py +1 -0
  36. ultrazohm_dataviewer/panels/analysis.py +376 -0
  37. ultrazohm_dataviewer/panels/base.py +24 -0
  38. ultrazohm_dataviewer/panels/fft.py +73 -0
  39. ultrazohm_dataviewer/panels/histogram.py +52 -0
  40. ultrazohm_dataviewer/panels/live.py +856 -0
  41. ultrazohm_dataviewer/panels/log_browser.py +164 -0
  42. ultrazohm_dataviewer/panels/navigation.py +150 -0
  43. ultrazohm_dataviewer/panels/nodes.py +371 -0
  44. ultrazohm_dataviewer/panels/plots.py +913 -0
  45. ultrazohm_dataviewer/panels/python.py +93 -0
  46. ultrazohm_dataviewer/panels/script_editor.py +155 -0
  47. ultrazohm_dataviewer/panels/settings.py +85 -0
  48. ultrazohm_dataviewer/panels/status.py +32 -0
  49. ultrazohm_dataviewer/plot_window.py +60 -0
  50. ultrazohm_dataviewer/plugins.py +124 -0
  51. ultrazohm_dataviewer/polars_io.py +68 -0
  52. ultrazohm_dataviewer/polars_source.py +65 -0
  53. ultrazohm_dataviewer/preferences.py +77 -0
  54. ultrazohm_dataviewer/process_launcher.py +49 -0
  55. ultrazohm_dataviewer/requests.py +181 -0
  56. ultrazohm_dataviewer/sampling.py +135 -0
  57. ultrazohm_dataviewer/script_job.py +43 -0
  58. ultrazohm_dataviewer/script_worker.py +18 -0
  59. ultrazohm_dataviewer/scripting.py +217 -0
  60. ultrazohm_dataviewer/session.py +550 -0
  61. ultrazohm_dataviewer/settings.py +113 -0
  62. ultrazohm_dataviewer/sources.py +682 -0
  63. ultrazohm_dataviewer/state.py +646 -0
  64. ultrazohm_dataviewer/transforms.py +151 -0
  65. ultrazohm_dataviewer/user_paths.py +97 -0
  66. ultrazohm_dataviewer/validation.py +91 -0
  67. ultrazohm_dataviewer/windows_console.py +46 -0
  68. ultrazohm_dataviewer/workers.py +84 -0
  69. ultrazohm_dataviewer-0.1.80.dev0.dist-info/METADATA +675 -0
  70. ultrazohm_dataviewer-0.1.80.dev0.dist-info/RECORD +73 -0
  71. ultrazohm_dataviewer-0.1.80.dev0.dist-info/WHEEL +5 -0
  72. ultrazohm_dataviewer-0.1.80.dev0.dist-info/entry_points.txt +2 -0
  73. ultrazohm_dataviewer-0.1.80.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,44 @@
1
+ """UltraZohm Data Viewer -- an imgui_bundle based log viewer.
2
+
3
+ A desktop data viewer for JavaScope ``.csv`` and ``.parquet`` logs, providing
4
+ the same core functionality as the legacy Plotly/Dash ``dataviewer.py`` with a
5
+ VSCode-style docked layout, drag-and-drop subplots and range-aware downsampling.
6
+
7
+ The data/analysis core is also usable **headlessly as a library** -- see
8
+ :mod:`ultrazohm_dataviewer.api` (and the repository's ``ultrazohm_dataviewer_library.rst``). Importing this package does
9
+ **not** import the imgui GUI stack; GUI entry points live in ``ultrazohm_dataviewer.app``. Headless operations need only
10
+ numpy/pandas/pyarrow.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from ._version import __version__
16
+
17
+ # Control clients need only the standard library. Numerical dependencies are
18
+ # loaded when their public functions are first requested.
19
+ from .client import Client, ViewerError, RunHandle, NodeHandle, ViewHandle
20
+
21
+
22
+ def __getattr__(name):
23
+ if name in {"Dataset", "fft", "fft_frame", "kinds", "node", "read"}:
24
+ from . import api
25
+ value = getattr(api, name)
26
+ globals()[name] = value
27
+ return value
28
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
29
+
30
+ __all__ = [
31
+ "__version__",
32
+ "Client",
33
+ "ViewerError",
34
+ "RunHandle",
35
+ "NodeHandle",
36
+ "ViewHandle",
37
+ # headless library API
38
+ "Dataset",
39
+ "read",
40
+ "fft",
41
+ "fft_frame",
42
+ "node",
43
+ "kinds",
44
+ ]
@@ -0,0 +1,8 @@
1
+ """Allow ``python -m ultrazohm_dataviewer [files...]``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .cli import main
6
+
7
+ if __name__ == "__main__":
8
+ raise SystemExit(main())
@@ -0,0 +1 @@
1
+ __version__ = '0.1.80.dev0'
@@ -0,0 +1,321 @@
1
+ """Signal transforms used by the FFT window.
2
+
3
+ Kept GUI-free so it is unit-testable and reusable from other analysis windows.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+
10
+ import numpy as np
11
+
12
+ from .sources import shift_time, TimeShift
13
+
14
+ from .downsample import visible_slice
15
+ from .sources import ByteCache, SampleSource
16
+
17
+ def _hann(n: int) -> tuple[np.ndarray, float]:
18
+ """Return a computation-owned Hann window and its coherent-gain sum.
19
+
20
+ Do not retain potentially large windows after their FFT completes.
21
+ """
22
+ w = np.hanning(n).astype(np.float32)
23
+ return w, float(w.sum(dtype=np.float64))
24
+
25
+
26
+ def _next_fast_len(n: int) -> int:
27
+ """Smallest 5-smooth (2^a·3^b·5^c) integer >= ``n``.
28
+
29
+ ``np.fft.rfft`` is dramatically faster on 5-smooth lengths than on lengths with
30
+ a large prime factor -- a ~9x cliff at multi-million-sample windows -- so the
31
+ transform zero-pads up to one. Pure-Python (no scipy) to keep the dependency
32
+ list lean; the next power of two is always a valid upper bound.
33
+ """
34
+ if n <= 6:
35
+ return n
36
+ best = 1 << (n - 1).bit_length() # next power of two >= n
37
+ p5 = 1
38
+ while p5 < best:
39
+ p3 = p5
40
+ while p3 < best:
41
+ x = p3
42
+ while x < n:
43
+ x <<= 1
44
+ if x < best:
45
+ best = x
46
+ p3 *= 3
47
+ p5 *= 5
48
+ return best
49
+
50
+
51
+ class FftResult:
52
+ """Single-sided amplitude spectrum plus a human-readable status line.
53
+
54
+ Attributes:
55
+ freqs: Frequency axis (Hz), ``None`` on failure.
56
+ mag: Amplitude (same units as input ``y``), ``None`` on failure.
57
+ info: Human-readable description of the computation or the failure reason.
58
+ ok: ``True`` when ``freqs`` and ``mag`` are populated.
59
+ """
60
+
61
+ def __init__(self, freqs: np.ndarray | None, mag: np.ndarray | None, info: str) -> None:
62
+ self.freqs = freqs
63
+ self.mag = mag
64
+ self.info = info
65
+
66
+ @property
67
+ def ok(self) -> bool:
68
+ """``True`` when the computation succeeded and ``freqs``/``mag`` are populated."""
69
+ return self.freqs is not None and self.mag is not None
70
+
71
+
72
+ def compute_fft(
73
+ time: np.ndarray,
74
+ y: np.ndarray,
75
+ x_min: float,
76
+ x_max: float,
77
+ *,
78
+ remove_dc: bool = True,
79
+ window: bool = True,
80
+ timestamp_resolution: float = 0.0,
81
+ ) -> FftResult:
82
+ """Single-sided amplitude spectrum of ``y`` over ``[x_min, x_max]``.
83
+
84
+ The window is selected by time so zooming the source plot narrows the
85
+ transform. Returns an empty :class:`FftResult` (with an ``info`` reason) when
86
+ the slice is too short or the time axis is unusable.
87
+ """
88
+ time, y = np.asarray(time), np.asarray(y)
89
+ if time.ndim != 1 or y.ndim != 1 or time.shape != y.shape:
90
+ return FftResult(None, None, "FFT needs equal-length one-dimensional time and value arrays.")
91
+ if time.shape[0] == 0:
92
+ return FftResult(None, None, "No samples in this run to transform.")
93
+ if x_max <= x_min:
94
+ return FftResult(None, None, "Selected window is too short for an FFT.")
95
+
96
+ # Binary search requires an ordered axis, including samples outside the
97
+ # requested window. Validate before slicing so invalid input cannot hide.
98
+ from .loader import validate_time_axis
99
+ try:
100
+ validate_time_axis(time, "FFT")
101
+ if not np.isfinite([x_min, x_max]).all():
102
+ raise ValueError("FFT window limits must be finite.")
103
+ except ValueError as exc:
104
+ return FftResult(None, None, str(exc))
105
+
106
+ start, stop = visible_slice(time, x_min, x_max, padding=False)
107
+ # Keep float32 (JavaScope data is float32): numpy's pocketfft preserves it as a
108
+ # complex64 transform -- half the memory of the old float64 upcast (big on a
109
+ # multi-million-sample full-window FFT, and on the WASM heap) and faster. A copy
110
+ # so the demean/window can run in place.
111
+ ys = np.array(y[start:stop], dtype=np.float32)
112
+ ts = time[start:stop]
113
+ n = ys.shape[0]
114
+ if n < 4:
115
+ return FftResult(None, None, "Selected window is too short for an FFT.")
116
+ # A single O(n) pass at Compute (not per frame): NaN/Inf in the window would
117
+ # otherwise propagate through the whole spectrum. The transform assumes a
118
+ # uniform time base, so masking would corrupt it -- reject instead.
119
+ if not np.isfinite(ys).all():
120
+ return FftResult(None, None, "Selected window has non-finite samples (NaN/Inf); cannot compute FFT.")
121
+
122
+ from .sampling import regular_sample_interval
123
+ try:
124
+ dt = regular_sample_interval(ts, "FFT", timestamp_resolution=timestamp_resolution)
125
+ except ValueError as exc:
126
+ return FftResult(None, None, str(exc))
127
+
128
+ # Scale before demeaning/FFT to avoid overflowing float32 intermediates.
129
+ scale = max(abs(float(ys.min())), abs(float(ys.max()))) or 1.0
130
+ ys /= scale
131
+ if remove_dc:
132
+ ys -= ys.mean(dtype=np.float64) # accumulate the mean in float64, subtract in place
133
+ # Amplitude normalisation is by the window's *coherent gain* (Σw): a tone of
134
+ # amplitude A peaks at A/2·Σw, so 2/Σw recovers A. For the rectangular case
135
+ # Σw = n, which is the plain 2/n. (Using 2/n with a Hann window under-reports
136
+ # every amplitude by ~2x, since Σw ≈ n/2.)
137
+ if window:
138
+ w, wsum = _hann(n)
139
+ ys *= w
140
+ norm = 2.0 / wsum
141
+ else:
142
+ norm = 2.0 / n
143
+
144
+ # Zero-pad to a 5-smooth length so rfft avoids the large-prime slow path; the
145
+ # amplitude stays normalised by the *original* window (padding only interpolates bins).
146
+ m = _next_fast_len(n)
147
+ spectrum = np.fft.rfft(ys, n=m)
148
+ freqs = np.fft.rfftfreq(m, d=dt)
149
+ mag = norm * np.abs(spectrum)
150
+ # The single-sided ×2 folds the negative-frequency twin onto each bin; the DC
151
+ # bin (and the Nyquist bin at even length) has no twin, so halve it back.
152
+ if mag.size:
153
+ mag[0] *= 0.5
154
+ if m % 2 == 0:
155
+ mag[-1] *= 0.5
156
+ if not np.isfinite(freqs).all() or np.any(freqs > np.finfo(np.float32).max):
157
+ return FftResult(None, None, "FFT frequency exceeds the finite float32 output range.")
158
+ mag = mag.astype(np.float64) * scale
159
+ if not np.isfinite(mag).all() or np.any(mag > np.finfo(np.float32).max):
160
+ return FftResult(None, None, "FFT amplitude exceeds the finite float32 output range.")
161
+ info = f"{n:,} samples, fs = {1.0 / dt:,.1f} Hz, window [{x_min:.4f}, {x_max:.4f}] s"
162
+ return FftResult(freqs.astype(np.float32), mag.astype(np.float32), info)
163
+
164
+
165
+ def compute_signal_fft(run, channel, x_min, x_max, *, remove_dc=True, window=True,
166
+ cancel=None, label=None):
167
+ """Read and validate one spectrum, reporting failures with the signal identity."""
168
+ if run.axis_domain != "time":
169
+ raise ValueError("FFT requires a time-domain recording")
170
+ label = label or f"{channel} @ {run.label}"
171
+ selected = AnalysisInput((run.id, channel), label, run.data_source(), run.time_offset, run.timestamp_resolution)
172
+ return selected.fft(x_min, x_max, remove_dc=remove_dc, window=window, cancel=cancel)
173
+
174
+
175
+ def histogram_sources(series, lo, hi, bins, cancel=None):
176
+ """Two-pass histogram over raw batches with common edges for all sources.
177
+
178
+ series: (label, source, channel, display_time_offset). Display summaries are
179
+ never used here. Memory is proportional to one batch and the output bins.
180
+ """
181
+ from .sources import check
182
+ from .validation import histogram_bins
183
+ bins = histogram_bins(bins)
184
+ ranges, minimum, maximum, dropped = [], None, None, 0
185
+ for label, source, channel, offset in series:
186
+ check(cancel)
187
+ from .sources import displayed_bounds
188
+ start, stop = displayed_bounds(source, lo, hi, offset, cancel)
189
+ count = 0
190
+ for _, values in source.iter_raw([channel], start, stop, cancel):
191
+ y = values[channel]
192
+ finite = np.isfinite(y)
193
+ dropped += int(len(y) - finite.sum())
194
+ y = y[finite]
195
+ if len(y):
196
+ low, high = float(y.min()), float(y.max())
197
+ minimum = low if minimum is None else min(minimum, low)
198
+ maximum = high if maximum is None else max(maximum, high)
199
+ count += len(y)
200
+ if count:
201
+ ranges.append((label, source, channel, start, stop, count))
202
+ if minimum is None:
203
+ return [], 0, dropped
204
+ from .validation import expanded_range
205
+ minimum, maximum = expanded_range(minimum, maximum, bins)
206
+ edges = np.linspace(minimum, maximum, bins + 1)
207
+ centers = (edges[:-1] + edges[1:]) / 2
208
+ results, total = [], 0
209
+ for label, source, channel, start, stop, count in ranges:
210
+ counts = np.zeros(len(centers), dtype=np.int64)
211
+ for _, values in source.iter_raw([channel], start, stop, cancel):
212
+ y = values[channel]
213
+ counts += np.histogram(y[np.isfinite(y)], bins=edges)[0]
214
+ results.append((label, centers, counts, float(edges[1] - edges[0])))
215
+ total += count
216
+ return results, total, dropped
217
+
218
+
219
+ @dataclass(frozen=True)
220
+ class AnalysisInput:
221
+ """A selected source and its displayed time offset, captured before scheduling.
222
+
223
+ Requests capture sources and scalar view/options, rather than GUI state.
224
+ Sources and the byte cache are shared. Derived-source validators also share
225
+ the graph/registry deliberately so they can detect invalidation during work.
226
+ """
227
+
228
+ ref: tuple[int, str]
229
+ label: str
230
+ source: SampleSource
231
+ time_offset: TimeShift | float
232
+ timestamp_resolution: float = 0.0
233
+
234
+ @classmethod
235
+ def capture(cls, registry, refs):
236
+ inputs = []
237
+ for ref in refs:
238
+ run = registry.get(ref[0])
239
+ if run is None or ref[1] not in run.signals:
240
+ raise ValueError(f"Analysis source {ref} is no longer loaded")
241
+ if run.axis_domain != "time":
242
+ raise ValueError("Analysis windows require a time-domain recording")
243
+ inputs.append(cls(ref, f"{ref[1]} @ {run.label} [run_{run.id}]",
244
+ run.data_source(), run.time_offset, run.timestamp_resolution))
245
+ return tuple(inputs)
246
+
247
+ def read_window(self, lo, hi, cancel):
248
+ from .sources import displayed_bounds
249
+ start, stop = displayed_bounds(self.source, lo, hi, self.time_offset, cancel)
250
+ t, values = self.source.read_rows([self.ref[1]], start, stop, cancel)
251
+ return shift_time(t, self.time_offset), values[self.ref[1]]
252
+
253
+ def fft(self, lo, hi, *, remove_dc, window, cancel=None):
254
+ try:
255
+ t, y = self.read_window(lo, hi, cancel)
256
+ result = compute_fft(t, y, lo, hi, remove_dc=remove_dc, window=window,
257
+ timestamp_resolution=self.timestamp_resolution)
258
+ if not result.ok:
259
+ raise ValueError(result.info)
260
+ except (ValueError, OSError) as exc:
261
+ raise ValueError(f"Cannot compute FFT for {self.label}: {exc}") from exc
262
+ return result
263
+
264
+
265
+ @dataclass(frozen=True)
266
+ class AnalysisResult:
267
+ series: list
268
+ info: str
269
+
270
+
271
+ @dataclass(frozen=True)
272
+ class FftRequest:
273
+ sources: tuple[AnalysisInput, ...]
274
+ window: tuple[float, float]
275
+ remove_dc: bool
276
+ hann: bool
277
+ cache: ByteCache
278
+
279
+ def compute(self, cancel=None) -> AnalysisResult:
280
+ from .sources import ArraySource, check
281
+ results, errors, info = [], [], ""
282
+ lo, hi = self.window
283
+ for selected in self.sources:
284
+ check(cancel)
285
+ try:
286
+ result = selected.fft(lo, hi, remove_dc=self.remove_dc, window=self.hann, cancel=cancel)
287
+ except ValueError as exc:
288
+ errors.append(str(exc))
289
+ continue
290
+ source = ArraySource(result.freqs, {'value': result.mag}, self.cache)
291
+ if result.mag.size > 4096:
292
+ source.prepare_summary('value', cancel)
293
+ results.append((selected.ref, result.freqs, result.mag, source))
294
+ info = result.info
295
+ check(cancel)
296
+ if errors:
297
+ info = "\n".join([f"{len(results)} succeeded, {len(errors)} failed", *errors])
298
+ return AnalysisResult(results, info or "Drag signals here to analyse them.")
299
+
300
+
301
+ @dataclass(frozen=True)
302
+ class HistogramRequest:
303
+ sources: tuple[AnalysisInput, ...]
304
+ window: tuple[float, float]
305
+ bins: int
306
+
307
+ def compute(self, cancel=None) -> AnalysisResult:
308
+ from .sources import check
309
+ lo, hi = self.window
310
+ series = [(s.ref, s.source, s.ref[1], s.time_offset) for s in self.sources]
311
+ results, total, dropped = histogram_sources(series, lo, hi, self.bins, cancel)
312
+ check(cancel)
313
+ values = [(ref, centers, counts.astype(np.float64), width)
314
+ for ref, centers, counts, width in results]
315
+ if results:
316
+ note = f", {dropped:,} non-finite skipped" if dropped else ""
317
+ info = (f"{len(results)} signal(s), {total:,} samples{note}, "
318
+ f"window [{lo:.4f}, {hi:.4f}] s")
319
+ else:
320
+ info = "Drag signals here to histogram them."
321
+ return AnalysisResult(values, info)
@@ -0,0 +1,42 @@
1
+ """GUI-independent analysis request construction and input identity."""
2
+ from .analysis import AnalysisInput, FftRequest, HistogramRequest
3
+ from .sources import validation_error
4
+
5
+
6
+ def config(state, kind):
7
+ return state.fft if kind == 'fft' else state.histogram
8
+
9
+
10
+ def source_error(state, cfg):
11
+ sources = []
12
+ for ref in cfg.sources:
13
+ run = state.registry.get(ref[0])
14
+ if run is None or ref[1] not in run.signals:
15
+ return 'Analysis source is no longer loaded'
16
+ if run.axis_domain != 'time':
17
+ return 'Analysis windows require a time-domain recording'
18
+ sources.append(run.data_source())
19
+ return validation_error(sources, state.services.validation_jobs)
20
+
21
+
22
+ def fingerprint(state, kind):
23
+ cfg = config(state, kind)
24
+ try:
25
+ window = state.resolve_x_window(cfg.follow_plot, (cfg.x_min, cfg.x_max), cfg.sources)
26
+ except ValueError:
27
+ window = (cfg.x_min, cfg.x_max)
28
+ versions = tuple((ref, state.registry.get(ref[0]).time_version,
29
+ state.registry.get_signal(*ref).version)
30
+ for ref in cfg.sources if state.registry.get_signal(*ref) is not None)
31
+ options = (cfg.remove_dc, cfg.window) if kind == 'fft' else (cfg.bins,)
32
+ return (versions, *window, source_error(state, cfg), *options)
33
+
34
+
35
+ def request(state, kind, limits=None):
36
+ cfg = config(state, kind)
37
+ if limits is None:
38
+ limits = state.resolve_x_window(cfg.follow_plot, (cfg.x_min, cfg.x_max), cfg.sources)
39
+ inputs = AnalysisInput.capture(state.registry, cfg.sources)
40
+ if kind == 'fft':
41
+ return FftRequest(inputs, limits, cfg.remove_dc, cfg.window, state.registry.cache)
42
+ return HistogramRequest(inputs, limits, cfg.bins)
@@ -0,0 +1,190 @@
1
+ """Ergonomic, GUI-free public API for headless / scripting use.
2
+
3
+ This module is the supported way to use ``ultrazohm_dataviewer`` as a *library* -- loading
4
+ logs, computing FFTs and running the node transforms from a plain Python script or a
5
+ notebook, with no window and (importantly) **without importing the imgui GUI stack**.
6
+ It is a thin convenience layer over the existing pure-NumPy building blocks
7
+ (:mod:`loader`, :mod:`analysis`, :mod:`nodes`, :mod:`transforms`); it adds no new
8
+ compute logic.
9
+
10
+ import ultrazohm_dataviewer as uz
11
+
12
+ data = uz.read("Log.csv") # -> Dataset (shared time axis + named signals)
13
+ t, ia = data.time, data["ia"]
14
+
15
+ spec = uz.fft(t, ia) # -> FftResult (full span by default)
16
+ df = uz.fft_frame(t, ia) # -> pandas DataFrame [frequency, amplitude]
17
+
18
+ t2, y2, info = uz.node("filter", (t, ia), type="low", cutoff=40, taps=201)
19
+ print(uz.kinds()) # ('fft', 'math', 'filter', 'shift')
20
+
21
+ The node calculations are exactly those the GUI's node graph uses (they share
22
+ :data:`nodes.REGISTRY`); :func:`load_plugins` opts into any external plugin kinds.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import numpy as np
28
+
29
+ from . import nodes
30
+ from .analysis import FftResult, compute_fft
31
+ from .loader import parse_file, validate_backend
32
+ from .plugins import load_plugins
33
+
34
+ __all__ = [
35
+ "Dataset",
36
+ "read",
37
+ "fft",
38
+ "fft_frame",
39
+ "node",
40
+ "filter",
41
+ "math",
42
+ "kinds",
43
+ "load_plugins",
44
+ "FftResult",
45
+ ]
46
+
47
+
48
+ class Dataset:
49
+ """A loaded log: a shared ``time`` axis plus named signal arrays.
50
+
51
+ Thin read-friendly wrapper over ``loader.ParsedRun``. Index a signal by name
52
+ (``data["ia"]``), test membership (``"ia" in data``), iterate names, or pull the
53
+ whole thing into a DataFrame with :meth:`to_dataframe`.
54
+ """
55
+
56
+ __slots__ = ("label", "path", "time", "signals", "units", "backend", "timestamp_resolution")
57
+
58
+ def __init__(self, parsed) -> None:
59
+ self.timestamp_resolution = parsed.timestamp_resolution
60
+ self.backend: str = parsed.backend
61
+ self.label: str = parsed.label
62
+ self.path: str = parsed.path
63
+ self.time: np.ndarray = parsed.time
64
+ self.signals: dict[str, np.ndarray] = parsed.signals
65
+ self.units: dict[str, str] = parsed.units
66
+
67
+ @property
68
+ def names(self) -> list[str]:
69
+ """Ordered list of signal names in this dataset."""
70
+ return list(self.signals)
71
+
72
+ def __getitem__(self, name: str) -> np.ndarray:
73
+ return self.signals[name]
74
+
75
+ def __contains__(self, name: str) -> bool:
76
+ return name in self.signals
77
+
78
+ def __iter__(self):
79
+ return iter(self.signals)
80
+
81
+ def __len__(self) -> int:
82
+ return len(self.signals)
83
+
84
+ def __repr__(self) -> str:
85
+ return f"Dataset(label={self.label!r}, n_rows={self.time.shape[0]}, signals={self.names})"
86
+
87
+ def to_dataframe(self):
88
+ """Return a backend-native DataFrame of time plus one column per signal."""
89
+ if self.backend == "polars":
90
+ import polars as pl
91
+ return pl.DataFrame({"time": self.time, **self.signals})
92
+ import pandas as pd
93
+
94
+ return pd.DataFrame({"time": self.time, **self.signals})
95
+
96
+
97
+ def read(path, *, backend="pyarrow") -> Dataset:
98
+ """Load a ``.csv``/``.parquet`` log and return its data as a :class:`Dataset`."""
99
+ return Dataset(parse_file(str(path), backend=backend))
100
+
101
+
102
+ def fft(
103
+ time,
104
+ y,
105
+ *,
106
+ remove_dc: bool = True,
107
+ window: bool = True,
108
+ x_min: float | None = None,
109
+ x_max: float | None = None,
110
+ timestamp_resolution: float = 0.0,
111
+ ) -> FftResult:
112
+ """Single-sided amplitude spectrum of ``y``.
113
+
114
+ With no ``x_min``/``x_max`` the whole record is transformed. Returns a
115
+ ``ultrazohm_dataviewer.analysis.FftResult`` (``.freqs``, ``.mag``, ``.info``, ``.ok``).
116
+ Pass ``timestamp_resolution=data.timestamp_resolution`` for a loaded Dataset
117
+ to account for known logger quantization; plain arrays default to unspecified.
118
+ """
119
+ t = np.asarray(time, dtype=np.float64)
120
+ yy = np.asarray(y, dtype=np.float64)
121
+ if t.ndim != 1 or yy.ndim != 1 or t.shape != yy.shape:
122
+ return FftResult(None, None, "FFT needs equal-length one-dimensional time and value arrays.")
123
+ lo = float(x_min) if x_min is not None else (float(t[0]) if len(t) else 0.)
124
+ hi = float(x_max) if x_max is not None else (float(t[-1]) if len(t) else 0.)
125
+ return compute_fft(t, yy, lo, hi, remove_dc=remove_dc, window=window,
126
+ timestamp_resolution=timestamp_resolution)
127
+
128
+
129
+ def fft_frame(time, y, *, backend="pyarrow", **kwargs):
130
+ """Like :func:`fft` but returns a backend-native frame [frequency, amplitude].
131
+
132
+ PyArrow (default) returns pandas; backend="polars" returns a Polars DataFrame.
133
+
134
+ Raises ``ValueError`` (with the reason) if the transform could not be computed.
135
+ """
136
+ validate_backend(backend)
137
+
138
+ result = fft(time, y, **kwargs)
139
+ if not result.ok:
140
+ raise ValueError(result.info)
141
+ columns = {"frequency": result.freqs, "amplitude": result.mag}
142
+ if backend == "polars":
143
+ import polars as pl
144
+ return pl.DataFrame(columns)
145
+ import pandas as pd
146
+ return pd.DataFrame(columns)
147
+
148
+
149
+ def kinds() -> tuple[str, ...]:
150
+ """The available node-transform kinds (builtins + any loaded plugins)."""
151
+ return nodes.transform_kinds()
152
+
153
+
154
+ def node(kind: str, *signals, timestamp_resolution=0.0, **params):
155
+ """Run a node transform headlessly.
156
+
157
+ ``signals`` are ``(time, y)`` tuples (one for unary kinds, two for binary math);
158
+ ``params`` override the kind's defaults. Returns ``(out_time, out_y, info)`` --
159
+ e.g. an ``fft`` node returns ``(freqs, mag, info)``. ``kind`` is one of
160
+ :func:`kinds` (``fft``/``math``/``filter``/``shift`` plus any plugins).
161
+ """
162
+ spec = nodes.REGISTRY.get(kind)
163
+ if spec is None:
164
+ raise ValueError(f"unknown node kind {kind!r}; one of {kinds()}")
165
+ merged = nodes.default_params(kind)
166
+ merged.update({k: v for k, v in params.items()})
167
+ inputs = [
168
+ (np.asarray(t, dtype=np.float64), np.asarray(s, dtype=np.float64)) for t, s in signals
169
+ ]
170
+ time, values, info, _ = nodes.compute_node(
171
+ nodes.Node(0, kind, kind, params=merged), inputs, timestamp_resolution=timestamp_resolution
172
+ )
173
+ return time, values, info
174
+
175
+
176
+ def filter(time, y, **params):
177
+ """Validated ``node('filter', ...)`` convenience wrapper (FIR low/high/band-pass).
178
+
179
+ Returns ``(time, filtered_y, info)``.
180
+ """
181
+ return node("filter", (time, y), **params)
182
+
183
+
184
+ def math(*signals, **params):
185
+ """Validated ``node('math', ...)`` convenience wrapper (scale/offset/derivative/
186
+ integral/reciprocal and binary add/sub/mul/div).
187
+
188
+ ``signals`` are ``(time, y)`` tuples. Returns ``(time, y_out, info)``.
189
+ """
190
+ return node("math", *signals, **params)