tm-data-types 0.4.1__tar.gz → 0.5.0__tar.gz

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 (50) hide show
  1. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/PKG-INFO +1 -1
  2. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/pyproject.toml +8 -10
  3. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/__init__.py +12 -1
  4. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/waveforms/analog_waveform.py +187 -12
  5. tm_data_types-0.5.0/src/tm_data_types/datum/waveforms/digital_waveform.py +309 -0
  6. tm_data_types-0.5.0/src/tm_data_types/datum/waveforms/fastframe_analog_waveform.py +184 -0
  7. tm_data_types-0.5.0/src/tm_data_types/datum/waveforms/fastframe_common.py +153 -0
  8. tm_data_types-0.5.0/src/tm_data_types/datum/waveforms/fastframe_digital_waveform.py +137 -0
  9. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/mat.py +2 -2
  10. tm_data_types-0.5.0/src/tm_data_types/files_and_formats/tss/__init__.py +5 -0
  11. tm_data_types-0.5.0/src/tm_data_types/files_and_formats/tss/tss_reader.py +235 -0
  12. tm_data_types-0.5.0/src/tm_data_types/files_and_formats/wfm/data_formats/analog.py +238 -0
  13. tm_data_types-0.5.0/src/tm_data_types/files_and_formats/wfm/data_formats/digital.py +312 -0
  14. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/data_formats/iq.py +39 -3
  15. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/wfm.py +33 -41
  16. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/wfm_format.py +201 -24
  17. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/byte_data_class.py +9 -5
  18. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/class_lookup.py +5 -2
  19. tm_data_types-0.4.1/src/tm_data_types/datum/waveforms/digital_waveform.py +0 -138
  20. tm_data_types-0.4.1/src/tm_data_types/files_and_formats/wfm/data_formats/analog.py +0 -98
  21. tm_data_types-0.4.1/src/tm_data_types/files_and_formats/wfm/data_formats/digital.py +0 -149
  22. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/LICENSE.md +0 -0
  23. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/README.md +0 -0
  24. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/__init__.py +0 -0
  25. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/data_types.py +0 -0
  26. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/datum.py +0 -0
  27. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/waveforms/__init__.py +0 -0
  28. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/waveforms/iq_waveform.py +0 -0
  29. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/datum/waveforms/waveform.py +0 -0
  30. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/__init__.py +0 -0
  31. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/abstracted_file.py +0 -0
  32. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/__init__.py +0 -0
  33. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/csv.py +0 -0
  34. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/data_formats/__init__.py +0 -0
  35. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/data_formats/analog.py +0 -0
  36. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/data_formats/digital.py +0 -0
  37. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/csv/data_formats/iq.py +0 -0
  38. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/__init__.py +0 -0
  39. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/data_formats/__init__.py +0 -0
  40. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/data_formats/analog.py +0 -0
  41. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/data_formats/digital.py +0 -0
  42. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/mat/data_formats/iq.py +0 -0
  43. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/__init__.py +0 -0
  44. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/data_formats/__init__.py +0 -0
  45. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/files_and_formats/wfm/wfm_data_classes.py +0 -0
  46. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/__init__.py +0 -0
  47. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/byte_data_types.py +0 -0
  48. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/enums.py +0 -0
  49. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/helpers/instrument_series.py +0 -0
  50. {tm_data_types-0.4.1 → tm_data_types-0.5.0}/src/tm_data_types/io_factory_methods.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tm_data_types
3
- Version: 0.4.1
3
+ Version: 0.5.0
4
4
  Summary: Read and write common Test & Measurement data types.
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE.md
@@ -38,7 +38,6 @@ documentation = "https://tm-data-types.readthedocs.io"
38
38
  homepage = "https://pypi.org/project/tm_data_types/"
39
39
  repository = "https://github.com/tektronix/tm_data_types"
40
40
 
41
-
42
41
  [tool.coverage.paths]
43
42
  source = [
44
43
  "src/tm_data_types",
@@ -77,7 +76,7 @@ classifiers = [
77
76
  "Topic :: Scientific/Engineering",
78
77
  "Topic :: System :: Hardware :: Hardware Drivers",
79
78
  ]
80
- version = "0.4.1"
79
+ version = "0.5.0"
81
80
 
82
81
  [tool.poetry.group.dev.dependencies]
83
82
  docutils-stubs = "^0.0.22"
@@ -94,16 +93,17 @@ poetry-audit-plugin = "^1.0.0"
94
93
  poetry-plugin-export = "^1.7.1"
95
94
  poetry-pre-commit-plugin = "^0.2.2"
96
95
  pre-commit = "^4.2"
97
- pylint = "4.0.5"
98
- pyright = {extras = ["nodejs"], version = "1.1.409"}
96
+ pylint = "4.0.7"
97
+ pyright = {extras = ["nodejs"], version = "1.1.411"}
99
98
  pyroma = "^5.0"
99
+ safety = "~3.7.0" # TODO: Remove this version pin once the issue with safety is resolved
100
100
  tox = "^4.0"
101
101
  tox-gh-actions = "^3.1.0"
102
- twine = "^6.0.1"
102
+ twine = "^7.0.0"
103
103
  types-python-dateutil = "^2.9"
104
104
  types-pyyaml = "^6.0"
105
105
  types-requests = "^2.31"
106
- wheel = "^0.47.0"
106
+ wheel = "^0.48.0"
107
107
 
108
108
  [tool.poetry.group.docs.dependencies]
109
109
  black = "^26.1.0"
@@ -124,7 +124,7 @@ nodeenv = "^1.9.1"
124
124
  packaging = "^26.0"
125
125
  pydantic = "^2.7.4"
126
126
  pygments = "^2.17.2"
127
- pymdown-extensions = "^10.8.1"
127
+ pymdown-extensions = "^11.0.1"
128
128
  requests = "^2.31.0"
129
129
  symspellpy = "^6.7.7"
130
130
  tomli = "^2.0.1"
@@ -205,9 +205,6 @@ disable = [
205
205
  "too-many-return-statements", # caught by ruff
206
206
  "too-many-statements", # caught by ruff
207
207
  "unnecessary-default-type-args", # not necessary to check for
208
- "unused-argument", # caught by ruff
209
- "unused-import", # caught by ruff
210
- "use-implicit-booleaness-not-comparison-to-string", # caught by ruff
211
208
  "while-used", # using while loops in example scripts
212
209
  "wrong-import-order", # caught by ruff
213
210
  ]
@@ -276,6 +273,7 @@ flake8-quotes = {docstring-quotes = "double"}
276
273
  ignore = [
277
274
  "ANN401", # Dynamically typed expressions (typing.Any) are disallowed in *args and **kwargs (allowed in this package)
278
275
  "COM812", # Trailing comma missing (allowed in this package)
276
+ "CPY001", # Missing copyright notice at top of file (allowed in this package)
279
277
  "FA100", # Missing `from __future__ import annotations`, but uses ... (allowed in this package)
280
278
  "FBT", # flake8-boolean-trap (allowed in this package)
281
279
  "FIX002", # Line contains TO DO (allowed in this package)
@@ -8,10 +8,16 @@ from importlib.metadata import version
8
8
  from tm_data_types.datum.data_types import Normalized, RawSample
9
9
  from tm_data_types.datum.waveforms.analog_waveform import AnalogWaveform, AnalogWaveformMetaInfo
10
10
  from tm_data_types.datum.waveforms.digital_waveform import DigitalWaveform, DigitalWaveformMetaInfo
11
+ from tm_data_types.datum.waveforms.fastframe_analog_waveform import (
12
+ FastFrameAnalogWaveform,
13
+ FrameTimingInfo,
14
+ )
15
+ from tm_data_types.datum.waveforms.fastframe_digital_waveform import FastFrameDigitalWaveform
11
16
  from tm_data_types.datum.waveforms.iq_waveform import IQWaveform, IQWaveformMetaInfo
12
17
  from tm_data_types.datum.waveforms.waveform import Waveform, WaveformMetaInfo
18
+ from tm_data_types.files_and_formats.tss.tss_reader import TSSReader
13
19
  from tm_data_types.helpers.class_lookup import FileExtensions
14
- from tm_data_types.helpers.enums import SIBaseUnit
20
+ from tm_data_types.helpers.enums import SIBaseUnit, SummaryFrameType
15
21
  from tm_data_types.io_factory_methods import (
16
22
  read_file,
17
23
  read_files_in_parallel,
@@ -27,12 +33,17 @@ __all__ = [
27
33
  "AnalogWaveformMetaInfo",
28
34
  "DigitalWaveform",
29
35
  "DigitalWaveformMetaInfo",
36
+ "FastFrameAnalogWaveform",
37
+ "FastFrameDigitalWaveform",
30
38
  "FileExtensions",
39
+ "FrameTimingInfo",
31
40
  "IQWaveform",
32
41
  "IQWaveformMetaInfo",
33
42
  "Normalized",
34
43
  "RawSample",
35
44
  "SIBaseUnit",
45
+ "SummaryFrameType",
46
+ "TSSReader",
36
47
  "Waveform",
37
48
  "WaveformMetaInfo",
38
49
  "read_file",
@@ -1,7 +1,7 @@
1
1
  """Handles information pertaining to analog waveforms."""
2
2
 
3
3
  from functools import cached_property
4
- from typing import Any, Optional, Type
4
+ from typing import Any, Iterator, Optional, Type
5
5
 
6
6
  import numpy as np
7
7
 
@@ -62,7 +62,7 @@ class AnalogWaveformMetaInfo(WaveformMetaInfo):
62
62
  real_data_start_index: Optional[int] = None
63
63
 
64
64
 
65
- class AnalogWaveform(Waveform):
65
+ class AnalogWaveform(Waveform): # pylint: disable=too-many-instance-attributes,too-many-public-methods
66
66
  """Class which represents an analog waveform with a y-axis and x-axis."""
67
67
 
68
68
  ################################################################################################
@@ -85,6 +85,27 @@ class AnalogWaveform(Waveform):
85
85
  self.y_axis_spacing: float = 1.0
86
86
  self.y_axis_offset: float = 0.0
87
87
  self.y_axis_units: str = SIBaseUnit.VOLTS.value
88
+ self._frame_data: Optional[np.ndarray] = None
89
+ self._frame_count: int = 1
90
+ self._current_frame: int = 0
91
+ self._tt_offsets: Optional[np.ndarray] = None
92
+ self._frame_gmt_sec: Optional[np.ndarray] = None
93
+ self._frame_gmt_fract: Optional[np.ndarray] = None
94
+ self._summary_frame: int = -1
95
+ self._frame_precharge: Optional[np.ndarray] = None
96
+ self._frame_postcharge: Optional[np.ndarray] = None
97
+ self._precharge_length: int = 0
98
+ self._postcharge_length: int = 0
99
+
100
+ def __getattribute__(self, key: str) -> Any:
101
+ """Return the active frame view when accessing y_axis_values on FastFrame data."""
102
+ if key == "y_axis_values":
103
+ frame_data = object.__getattribute__(self, "__dict__").get("_frame_data")
104
+ if frame_data is not None:
105
+ current_frame = object.__getattribute__(self, "_current_frame")
106
+ return RawSample(frame_data[current_frame])
107
+ return object.__getattribute__(self, "__dict__")["y_axis_values"]
108
+ return super().__getattribute__(key)
88
109
 
89
110
  def __setattr__(self, key: str, value: Any) -> None:
90
111
  """Set the attributes for the waveform class.
@@ -93,22 +114,118 @@ class AnalogWaveform(Waveform):
93
114
  key: The attribute name to set as a string.
94
115
  value: The value that the attribute is set to.
95
116
  """
96
- if key in {"y_axis_values", "y_axis_spacing", "y_axis_offset"}:
117
+ if key in {"y_axis_values", "y_axis_spacing", "y_axis_offset", "_frame_data"}:
97
118
  self.__dict__.pop("normalized_vertical_values", None)
98
119
 
99
120
  if key == "y_axis_values":
100
- # y-axis values need to be typecase when set.
121
+ if self.__dict__.get("_frame_data") is not None:
122
+ msg = "Cannot set y_axis_values directly on FastFrame waveform. Use fill_frame()."
123
+ raise ValueError(msg)
101
124
  if not isinstance(value, MeasuredData):
102
125
  super().__setattr__("y_axis_values", RawSample(value))
103
126
  else:
104
127
  super().__setattr__("y_axis_values", value)
128
+ elif key == "current_frame":
129
+ frame_count = self.__dict__.get("_frame_count", 1)
130
+ if not 0 <= value < frame_count:
131
+ msg = f"Frame {value} out of range [0, {frame_count})"
132
+ raise IndexError(msg)
133
+ super().__setattr__("_current_frame", value)
105
134
  else:
106
135
  super().__setattr__(key, value)
107
136
 
137
+ def __iter__(self) -> Iterator[NDArray[Any]]:
138
+ """Iterate over all frames as numpy array views."""
139
+ if self._frame_data is not None:
140
+ for index in range(self._frame_count):
141
+ yield self._frame_data[index]
142
+ else:
143
+ yield np.asarray(self.y_axis_values)
144
+
108
145
  ################################################################################################
109
146
  # Public Methods
110
147
  ################################################################################################
111
148
 
149
+ @classmethod
150
+ def create_fastframe(
151
+ cls,
152
+ frame_count: int,
153
+ record_length: int,
154
+ dtype: PossibleTypes = np.int16,
155
+ precharge_length: int = 0,
156
+ postcharge_length: int = 0,
157
+ **kwargs: Any,
158
+ ) -> "AnalogWaveform":
159
+ """Pre-allocate a FastFrame waveform.
160
+
161
+ Args:
162
+ frame_count: Number of frames to allocate.
163
+ record_length: Samples per frame.
164
+ dtype: Sample data type.
165
+ precharge_length: Samples per frame in the precharge region.
166
+ postcharge_length: Samples per frame in the postcharge region.
167
+ **kwargs: Additional waveform attributes.
168
+
169
+ Returns:
170
+ Pre-allocated AnalogWaveform ready for fill_frame() calls.
171
+ """
172
+ waveform = cls()
173
+ waveform._frame_data = np.empty((frame_count, record_length), dtype=dtype)
174
+ waveform._frame_count = frame_count
175
+ waveform._current_frame = 0
176
+ waveform._tt_offsets = np.zeros(frame_count, dtype=np.float64)
177
+ waveform._frame_gmt_sec = np.zeros(frame_count, dtype=np.int64)
178
+ waveform._frame_gmt_fract = np.zeros(frame_count, dtype=np.float64)
179
+ waveform._precharge_length = precharge_length
180
+ waveform._postcharge_length = postcharge_length
181
+ if precharge_length:
182
+ waveform._frame_precharge = np.zeros((frame_count, precharge_length), dtype=dtype)
183
+ if postcharge_length:
184
+ waveform._frame_postcharge = np.zeros((frame_count, postcharge_length), dtype=dtype)
185
+ for key, val in kwargs.items():
186
+ setattr(waveform, key, val)
187
+ return waveform
188
+
189
+ def fill_frame(self, frame_idx: int, data: np.ndarray) -> None:
190
+ """Copy frame data into the pre-allocated buffer."""
191
+ if self._frame_data is None:
192
+ msg = "Not a FastFrame waveform. Use create_fastframe() first."
193
+ raise ValueError(msg)
194
+ self._frame_data[frame_idx] = data
195
+ self.__dict__.pop("normalized_vertical_values", None)
196
+
197
+ def set_frame_timing(
198
+ self,
199
+ frame_idx: int,
200
+ tt_offset: float,
201
+ gmt_sec: int = 0,
202
+ gmt_fract: float = 0.0,
203
+ ) -> None:
204
+ """Set per-frame timing metadata."""
205
+ if self._tt_offsets is not None:
206
+ self._tt_offsets[frame_idx] = tt_offset
207
+ if self._frame_gmt_sec is not None:
208
+ self._frame_gmt_sec[frame_idx] = gmt_sec
209
+ if self._frame_gmt_fract is not None:
210
+ self._frame_gmt_fract[frame_idx] = gmt_fract
211
+
212
+ def frame_data(self, idx: int) -> NDArray[Any]:
213
+ """Get a specific frame's data without changing current_frame."""
214
+ if self._frame_data is not None:
215
+ return self._frame_data[idx]
216
+ if not idx:
217
+ return np.asarray(self.y_axis_values)
218
+ frame_count = self.__dict__.get("_frame_count", 1)
219
+ msg = f"Frame {idx} out of range [0, {frame_count})"
220
+ raise IndexError(msg)
221
+
222
+ def frame(self, index: int) -> "AnalogWaveform":
223
+ """Return this waveform for single-frame data (TekHSI compat)."""
224
+ if index == self.current_frame:
225
+ return self
226
+ msg = f"Single-frame waveform has no frame {index}"
227
+ raise ValueError(msg)
228
+
112
229
  def transform_to_normalized(self) -> "AnalogWaveform":
113
230
  """Convert the waveform to normalized."""
114
231
  copied_waveform = self.copy()
@@ -128,14 +245,7 @@ class AnalogWaveform(Waveform):
128
245
  self,
129
246
  as_type: Type[ByteData] | Type[PossibleTypes] | PossibleTypes,
130
247
  ) -> "AnalogWaveform":
131
- """Convert the waveform to a new type.
132
-
133
- Args:
134
- as_type: The type to convert to.
135
-
136
- Returns:
137
- A copy of the waveform transformed to raw sample values.
138
- """
248
+ """Convert the waveform to a new type."""
139
249
  copied_waveform = self.copy()
140
250
  copied_waveform.y_axis_offset = self.y_axis_values.calculate_offset(self.y_axis_offset)
141
251
  copied_waveform.y_axis_values = RawSample(copied_waveform.y_axis_values, as_type=as_type)
@@ -154,6 +264,71 @@ class AnalogWaveform(Waveform):
154
264
  # Properties
155
265
  ################################################################################################
156
266
 
267
+ @property
268
+ def frame_count(self) -> int:
269
+ """Number of frames.
270
+
271
+ 1 for normal waveforms, >1 for FastFrame.
272
+ """
273
+ return self._frame_count
274
+
275
+ @property
276
+ def is_fastframe(self) -> bool:
277
+ """True if this waveform contains multiple FastFrame acquisitions."""
278
+ return self._frame_count > 1
279
+
280
+ @property
281
+ def current_frame(self) -> int:
282
+ """Active frame index."""
283
+ return self._current_frame
284
+
285
+ @property
286
+ def tt_offsets(self) -> Optional[np.ndarray]:
287
+ """Per-frame trigger-to-trigger offsets in seconds."""
288
+ return self._tt_offsets
289
+
290
+ @property
291
+ def summary_frame(self) -> int:
292
+ """Index of the summary frame, or -1 if none."""
293
+ return self._summary_frame
294
+
295
+ @property
296
+ def all_frames(self) -> Optional[np.ndarray]:
297
+ """Direct access to the 2D frame array."""
298
+ return self._frame_data
299
+
300
+ @property
301
+ def frame_gmt_sec(self) -> Optional[np.ndarray]:
302
+ """Per-frame GMT seconds array."""
303
+ return self._frame_gmt_sec
304
+
305
+ @property
306
+ def frame_gmt_fract(self) -> Optional[np.ndarray]:
307
+ """Per-frame GMT fractional seconds array."""
308
+ return self._frame_gmt_fract
309
+
310
+ @property
311
+ def precharge_length(self) -> int:
312
+ """Number of precharge samples stored per frame."""
313
+ return self._precharge_length
314
+
315
+ @property
316
+ def postcharge_length(self) -> int:
317
+ """Number of postcharge samples stored per frame."""
318
+ return self._postcharge_length
319
+
320
+ def frame_precharge(self, idx: int) -> Optional[NDArray[Any]]:
321
+ """Return precharge samples for a frame when present."""
322
+ if self._frame_precharge is None:
323
+ return None
324
+ return self._frame_precharge[idx]
325
+
326
+ def frame_postcharge(self, idx: int) -> Optional[NDArray[Any]]:
327
+ """Return postcharge samples for a frame when present."""
328
+ if self._frame_postcharge is None:
329
+ return None
330
+ return self._frame_postcharge[idx]
331
+
157
332
  @cached_property
158
333
  def normalized_vertical_values(self) -> Normalized: # pyright: ignore [reportIncompatibleMethodOverride]
159
334
  """Cache the y values with the extent and offset are applied.
@@ -0,0 +1,309 @@
1
+ """Handles information pertaining to digital waveforms."""
2
+
3
+ from functools import cached_property
4
+ from typing import Any, Iterator, Optional
5
+
6
+ import numpy as np
7
+
8
+ from numpy.typing import NDArray
9
+ from pydantic.dataclasses import dataclass as pydantic_dataclass
10
+
11
+ from tm_data_types.datum.data_types import Digitized, MeasuredData, PossibleTypes, RawSample
12
+ from tm_data_types.datum.waveforms.waveform import Waveform, WaveformMetaInfo
13
+ from tm_data_types.helpers.enums import SIBaseUnit
14
+
15
+
16
+ @pydantic_dataclass(kw_only=True)
17
+ class DigitalWaveformMetaInfo(WaveformMetaInfo): # pylint: disable=too-many-instance-attributes
18
+ """Data which can come from tekmeta or a header for digital waveforms.
19
+
20
+ This class extends WaveformMetaInfo with digital-specific metadata fields.
21
+ It includes all the standard waveform metadata plus digital-specific fields
22
+ for digital probe states and digital signal information.
23
+
24
+ Digital-specific fields:
25
+ - digital_probe_0_state through digital_probe_7_state: State of digital probes
26
+ - digital_probe_0_threshold through digital_probe_7_threshold: Threshold values
27
+ - digital_probe_0_name through digital_probe_7_name: Names of digital probes
28
+ - digital_probe_0_unit through digital_probe_7_unit: Units for digital probes
29
+
30
+ Examples:
31
+ >>> meta_info = DigitalWaveformMetaInfo()
32
+ >>> meta_info.digital_probe_0_state = b"0x01"
33
+ >>> meta_info.digital_probe_0_threshold = 1.65
34
+ >>> meta_info.set_custom_metadata(
35
+ ... test_equipment="MSO54",
36
+ ... digital_pattern="PRBS7"
37
+ ... )
38
+ >>> print(meta_info.digital_probe_0_threshold) # 1.65
39
+ >>> print(meta_info.test_equipment) # "MSO54"
40
+ """
41
+
42
+ ################################################################################################
43
+ # Class Variables
44
+ ################################################################################################
45
+
46
+ digital_probe_0_state: bytes = b"0x01"
47
+ digital_probe_1_state: bytes = b"0x01"
48
+ digital_probe_2_state: bytes = b"0x01"
49
+ digital_probe_3_state: bytes = b"0x01"
50
+ digital_probe_4_state: bytes = b"0x01"
51
+ digital_probe_5_state: bytes = b"0x01"
52
+ digital_probe_6_state: bytes = b"0x01"
53
+ digital_probe_7_state: bytes = b"0x01"
54
+
55
+
56
+ class DigitalWaveform(Waveform): # pylint: disable=too-many-instance-attributes
57
+ """Class which represents a digital waveform with a y-axis and x-axis."""
58
+
59
+ ################################################################################################
60
+ # Dunder Methods
61
+ ################################################################################################
62
+
63
+ def __str__(self) -> str:
64
+ """Returns a string representation of the class.
65
+
66
+ Returns:
67
+ digital
68
+ """
69
+ return "digital"
70
+
71
+ def __init__(self) -> None:
72
+ """Initialize the digital waveform class with the raw data."""
73
+ super().__init__()
74
+ self.y_axis_byte_values: MeasuredData = MeasuredData(np.empty(0))
75
+ self.y_axis_units: str = SIBaseUnit.NONE.value
76
+ self.digital_bitmask: int = 0
77
+ self._frame_data: Optional[np.ndarray] = None
78
+ self._frame_count: int = 1
79
+ self._current_frame: int = 0
80
+ self._tt_offsets: Optional[np.ndarray] = None
81
+ self._frame_gmt_sec: Optional[np.ndarray] = None
82
+ self._frame_gmt_fract: Optional[np.ndarray] = None
83
+ self._frame_precharge: Optional[np.ndarray] = None
84
+ self._frame_postcharge: Optional[np.ndarray] = None
85
+ self._precharge_length: int = 0
86
+ self._postcharge_length: int = 0
87
+
88
+ def __getattribute__(self, key: str) -> Any:
89
+ """Return the active frame view when accessing byte values on FastFrame data."""
90
+ if key == "y_axis_byte_values":
91
+ frame_data = object.__getattribute__(self, "__dict__").get("_frame_data")
92
+ if frame_data is not None:
93
+ current_frame = object.__getattribute__(self, "_current_frame")
94
+ return RawSample(frame_data[current_frame])
95
+ return object.__getattribute__(self, "__dict__")["y_axis_byte_values"]
96
+ return super().__getattribute__(key)
97
+
98
+ def __setattr__(self, key: str, value: Any) -> None:
99
+ """Set the attributes for the waveform class.
100
+
101
+ Args:
102
+ key: The attribute name to set as a string.
103
+ value: The value that the attribute is set to.
104
+ """
105
+ if key in {"y_axis_values", "y_axis_spacing", "y_axis_offset", "_frame_data"}:
106
+ self.__dict__.pop("normalized_vertical_values", None)
107
+
108
+ if key == "y_axis_byte_values":
109
+ if self.__dict__.get("_frame_data") is not None:
110
+ msg = (
111
+ "Cannot set y_axis_byte_values directly on FastFrame waveform. "
112
+ "Use fill_frame()."
113
+ )
114
+ raise ValueError(msg)
115
+ if not isinstance(value, MeasuredData):
116
+ super().__setattr__("y_axis_byte_values", RawSample(value))
117
+ else:
118
+ super().__setattr__("y_axis_byte_values", value)
119
+ elif key == "current_frame":
120
+ frame_count = self.__dict__.get("_frame_count", 1)
121
+ if not 0 <= value < frame_count:
122
+ msg = f"Frame {value} out of range [0, {frame_count})"
123
+ raise IndexError(msg)
124
+ super().__setattr__("_current_frame", value)
125
+ else:
126
+ super().__setattr__(key, value)
127
+
128
+ def __iter__(self) -> Iterator[NDArray[Any]]:
129
+ """Iterate over all frames as numpy array views."""
130
+ if self._frame_data is not None:
131
+ for index in range(self._frame_count):
132
+ yield self._frame_data[index]
133
+ else:
134
+ yield np.asarray(self.y_axis_byte_values)
135
+
136
+ ################################################################################################
137
+ # Public Methods
138
+ ################################################################################################
139
+
140
+ def get_nth_bitstream(self, bitstream_number: int) -> Digitized:
141
+ """Get the bitstream based on the value provided.
142
+
143
+ Example:
144
+ get_nth_bitstream(1) will provide the 2nd bitstream.
145
+
146
+ Args:
147
+ bitstream_number: The bitstream number (starting at 0) to get.
148
+
149
+ Returns:
150
+ The bitstream that is associated with the provided value.
151
+ """
152
+ return self.normalized_vertical_values.T[bitstream_number]
153
+
154
+ @classmethod
155
+ def create_fastframe(
156
+ cls,
157
+ frame_count: int,
158
+ record_length: int,
159
+ dtype: PossibleTypes = np.int8,
160
+ precharge_length: int = 0,
161
+ postcharge_length: int = 0,
162
+ **kwargs: Any,
163
+ ) -> "DigitalWaveform":
164
+ """Pre-allocate a FastFrame digital waveform."""
165
+ waveform = cls()
166
+ waveform._frame_data = np.empty((frame_count, record_length), dtype=dtype)
167
+ waveform._frame_count = frame_count
168
+ waveform._current_frame = 0
169
+ waveform._tt_offsets = np.zeros(frame_count, dtype=np.float64)
170
+ waveform._frame_gmt_sec = np.zeros(frame_count, dtype=np.int64)
171
+ waveform._frame_gmt_fract = np.zeros(frame_count, dtype=np.float64)
172
+ waveform._precharge_length = precharge_length
173
+ waveform._postcharge_length = postcharge_length
174
+ if precharge_length:
175
+ waveform._frame_precharge = np.zeros((frame_count, precharge_length), dtype=dtype)
176
+ if postcharge_length:
177
+ waveform._frame_postcharge = np.zeros((frame_count, postcharge_length), dtype=dtype)
178
+ for key, val in kwargs.items():
179
+ setattr(waveform, key, val)
180
+ return waveform
181
+
182
+ def fill_frame(self, frame_idx: int, data: np.ndarray) -> None:
183
+ """Copy frame data into the pre-allocated buffer."""
184
+ if self._frame_data is None:
185
+ msg = "Not a FastFrame waveform. Use create_fastframe() first."
186
+ raise ValueError(msg)
187
+ self._frame_data[frame_idx] = data
188
+ self.__dict__.pop("normalized_vertical_values", None)
189
+
190
+ def set_frame_timing(
191
+ self,
192
+ frame_idx: int,
193
+ tt_offset: float,
194
+ gmt_sec: int = 0,
195
+ gmt_fract: float = 0.0,
196
+ ) -> None:
197
+ """Set per-frame timing metadata."""
198
+ if self._tt_offsets is not None:
199
+ self._tt_offsets[frame_idx] = tt_offset
200
+ if self._frame_gmt_sec is not None:
201
+ self._frame_gmt_sec[frame_idx] = gmt_sec
202
+ if self._frame_gmt_fract is not None:
203
+ self._frame_gmt_fract[frame_idx] = gmt_fract
204
+
205
+ def frame_data(self, idx: int) -> NDArray[Any]:
206
+ """Get a specific frame's data without changing current_frame."""
207
+ if self._frame_data is not None:
208
+ return self._frame_data[idx]
209
+ if not idx:
210
+ return np.asarray(self.y_axis_byte_values)
211
+ frame_count = self.__dict__.get("_frame_count", 1)
212
+ msg = f"Frame {idx} out of range [0, {frame_count})"
213
+ raise IndexError(msg)
214
+
215
+ def frame(self, index: int) -> "DigitalWaveform":
216
+ """Return this waveform for single-frame data (TekHSI compat)."""
217
+ if index == self.current_frame:
218
+ return self
219
+ msg = f"Single-frame waveform has no frame {index}"
220
+ raise ValueError(msg)
221
+
222
+ ################################################################################################
223
+ # Properties
224
+ ################################################################################################
225
+
226
+ @property
227
+ def frame_count(self) -> int:
228
+ """Number of frames.
229
+
230
+ 1 for normal waveforms, >1 for FastFrame.
231
+ """
232
+ return self._frame_count
233
+
234
+ @property
235
+ def is_fastframe(self) -> bool:
236
+ """True if this waveform contains multiple FastFrame acquisitions."""
237
+ return self._frame_count > 1
238
+
239
+ @property
240
+ def tt_offsets(self) -> Optional[np.ndarray]:
241
+ """Per-frame trigger-to-trigger offsets in seconds."""
242
+ return self._tt_offsets
243
+
244
+ @property
245
+ def all_frames(self) -> Optional[np.ndarray]:
246
+ """Direct access to the 2D frame array."""
247
+ return self._frame_data
248
+
249
+ @property
250
+ def frame_gmt_sec(self) -> Optional[np.ndarray]:
251
+ """Per-frame GMT seconds array."""
252
+ return self._frame_gmt_sec
253
+
254
+ @property
255
+ def frame_gmt_fract(self) -> Optional[np.ndarray]:
256
+ """Per-frame GMT fractional seconds array."""
257
+ return self._frame_gmt_fract
258
+
259
+ @property
260
+ def precharge_length(self) -> int:
261
+ """Number of precharge samples stored per frame."""
262
+ return self._precharge_length
263
+
264
+ @property
265
+ def postcharge_length(self) -> int:
266
+ """Number of postcharge samples stored per frame."""
267
+ return self._postcharge_length
268
+
269
+ def frame_precharge(self, idx: int) -> Optional[NDArray[Any]]:
270
+ """Return precharge samples for a frame when present."""
271
+ if self._frame_precharge is None:
272
+ return None
273
+ return self._frame_precharge[idx]
274
+
275
+ def frame_postcharge(self, idx: int) -> Optional[NDArray[Any]]:
276
+ """Return postcharge samples for a frame when present."""
277
+ if self._frame_postcharge is None:
278
+ return None
279
+ return self._frame_postcharge[idx]
280
+
281
+ @property
282
+ def current_frame(self) -> int:
283
+ """Active frame index."""
284
+ return self._current_frame
285
+
286
+ @current_frame.setter
287
+ def current_frame(self, value: int) -> None:
288
+ self.current_frame = value
289
+
290
+ @cached_property
291
+ def normalized_vertical_values(self) -> Digitized:
292
+ """Cache the iq values with the extent and offset are applied.
293
+
294
+ This is reset when iq values are changed.
295
+
296
+ Returns:
297
+ An np array with the iq_axis_extent_magnitude and y_axis_offset are applied.
298
+ """
299
+ digitized_y_values = Digitized(self.y_axis_byte_values)
300
+ return digitized_y_values.reshape((self.record_length, -1))
301
+
302
+ @property
303
+ def _measured_data(self) -> np.ndarray:
304
+ """The abstract representation of the y_axis data.
305
+
306
+ Returns:
307
+ The y_axis values
308
+ """
309
+ return self.y_axis_byte_values