fftekwfm 0.3.0.1__tar.gz

fftekwfm-0.3.0.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: fftekwfm
+Version: 0.3.0.1
+Summary: Read Tektronix WFM files with FastFrame support.
+Author: Guillaume Le Goc
+Author-email: Guillaume Le Goc <guillaume.le-goc@lncmi.cnrs.fr>
+Requires-Dist: numpy>=2.2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# FFTekWFM
+
+Tektronix [Waveform file format](https://download.tek.com/manual/Waveform-File-Format-Manual-077022011.pdf) reader.
+
+Features :
++ Support WFM file format version 1, 2 and 3
++ Support FastFrame
++ Support memory mapping
++ Support loading frames with or without pre- and post-charge data
+
+Header reader structure inspired by [TekWFM2](https://github.com/vongostev/tekwfm2).
+
+## Notice
+Note this package works for *my* use-case but is not properly tested. Consider using [TekWFM2](https://github.com/vongostev/tekwfm2) for a more established solution.
+
+## Installation
+`pip install git+https://gitlab.in2p3.fr/himagnetos/tekwfm.git`
+
+## Usage
+
+Read a file with memory mapping and plot some time series from fast frames, unscaled :
+```python
+import matplotlib.pyplot as plt
+from fftekwfm import TekWFM
+
+filename = "/path/to/tekfile.wfm"
+tek = TekWFM(filename).load_frames().get_time_frame()
+plt.figure()
+plt.plot(tek.time_frame, tek.frames[:, [0, 8000, 15000]])
+plt.xlabel("time (s)")
+plt.ylabel("signal (a.u.)")
+```
+
+Load every frames in-memory and do some calculation :
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from fftekwfm import TekWFM
+
+filename = "/path/to/tekfile.wfm"
+tek = TekWFM(filename).load_frames(mmap=False)
+Sn = np.abs(np.fft.rfft(tek.frames, axis=0))
+f = np.fft.rfftfreq(sig.shape[0], d=tek.tscale)  # tscale is the time between two samples
+plt.figure()
+plt.plot(f, S_mag)
+plt.xlabel("frequency (Hz)")
+plt.ylabel("magnitude")
+```

fftekwfm-0.3.0.1/README.md

@@ -0,0 +1,48 @@
+# FFTekWFM
+
+Tektronix [Waveform file format](https://download.tek.com/manual/Waveform-File-Format-Manual-077022011.pdf) reader.
+
+Features :
++ Support WFM file format version 1, 2 and 3
++ Support FastFrame
++ Support memory mapping
++ Support loading frames with or without pre- and post-charge data
+
+Header reader structure inspired by [TekWFM2](https://github.com/vongostev/tekwfm2).
+
+## Notice
+Note this package works for *my* use-case but is not properly tested. Consider using [TekWFM2](https://github.com/vongostev/tekwfm2) for a more established solution.
+
+## Installation
+`pip install git+https://gitlab.in2p3.fr/himagnetos/tekwfm.git`
+
+## Usage
+
+Read a file with memory mapping and plot some time series from fast frames, unscaled :
+```python
+import matplotlib.pyplot as plt
+from fftekwfm import TekWFM
+
+filename = "/path/to/tekfile.wfm"
+tek = TekWFM(filename).load_frames().get_time_frame()
+plt.figure()
+plt.plot(tek.time_frame, tek.frames[:, [0, 8000, 15000]])
+plt.xlabel("time (s)")
+plt.ylabel("signal (a.u.)")
+```
+
+Load every frames in-memory and do some calculation :
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from fftekwfm import TekWFM
+
+filename = "/path/to/tekfile.wfm"
+tek = TekWFM(filename).load_frames(mmap=False)
+Sn = np.abs(np.fft.rfft(tek.frames, axis=0))
+f = np.fft.rfftfreq(sig.shape[0], d=tek.tscale)  # tscale is the time between two samples
+plt.figure()
+plt.plot(f, S_mag)
+plt.xlabel("frequency (Hz)")
+plt.ylabel("magnitude")
+```

fftekwfm-0.3.0.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "fftekwfm"
+version = "0.3.0.1"
+description = "Read Tektronix WFM files with FastFrame support."
+readme = "README.md"
+authors = [
+    { name = "Guillaume Le Goc", email = "guillaume.le-goc@lncmi.cnrs.fr" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.9,<0.10.0"]
+build-backend = "uv_build"

fftekwfm-0.3.0.1/src/fftekwfm/__init__.py

@@ -0,0 +1,3 @@
+from .wfm import TekWFM
+
+__all__ = ["TekWFM"]

fftekwfm-0.3.0.1/src/fftekwfm/ttypes.py

@@ -0,0 +1,29 @@
+"""
+Initialize class to set its attributes types.
+"""
+
+
+class tTekWFM:
+    byte_order: str
+    version: bytes
+    bps: int
+    curve_offset: int
+    nframes: int
+    fastframe: int
+    imp_dim_count: int
+    exp_dim_count: int
+    vscale: float
+    voffset: float
+    vunits: bytes
+    type_code: int
+    dformat: str
+    tscale: float
+    toffset: float
+    tunits: bytes
+    npoints: int
+    tsfrac: float
+    tsunix: int
+    pre_start_offset: int
+    data_start_offset: int
+    post_start_offset: int
+    post_stop_offset: int

fftekwfm-0.3.0.1/src/fftekwfm/wfm.py

@@ -0,0 +1,394 @@
+"""
+TekWFM class to read Tektronix .wfm file.
+"""
+
+from pathlib import Path
+from struct import unpack_from as unpk
+from typing import Self
+
+import numpy as np
+
+from .ttypes import tTekWFM
+
+
+class TekWFM(tTekWFM):
+    def __init__(self, filename: str | Path | None = None) -> None:
+        """
+        Read Tektronix WFM file format with metadata and FastFrames support.
+
+        Parameters
+        ----------
+        filename : str | Path | None
+            Full path to the .wfm file. Can be None to access methods.
+
+        """
+
+        if filename:
+            self.filename = filename  # store file path
+
+            # Read metadata
+            header = self._load_header()  # get header
+            meta = self.decode_header(header)  # decode relevant information from header
+
+            # Store as attributes for convenience
+            for key, value in meta.items():
+                setattr(self, key, value)
+
+            # Get timestamps
+            self.get_timestamps()
+
+    def _load_header(self, n: int = 838) -> bytes:
+        """
+        Read bytes header.
+
+        Parameters
+        ----------
+        n : int, optional
+            Header size in bytes. Default is 838.
+
+        Returns
+        -------
+        header : bytes
+            Header ready to be decoded.
+
+        """
+        with open(self.filename, "rb") as f:
+            header = f.read(n)
+
+        return header
+
+    def _load_timestamps(self, n: int = 838) -> bytes:
+        """
+        Read bytes FastFrame timestamps.
+
+        Parameters
+        ----------
+        n : int, optional
+            Header size in bytes, by default 838.
+
+        Returns
+        -------
+        ts : bytes
+            Timestamps ready to be decoded.
+
+        """
+        with open(self.filename, "rb") as f:
+            f.seek(n)  # skip header
+            bts = f.read((self.nframes - 1) * 24)  # size of the WfmUpdateSpec objects
+
+        return bts
+
+    def decode_header(self, header: bytes) -> dict:
+        """
+        Decode WFM file header to obtain metadata.
+
+        Based on TekWFM2 [1] by Pavel Gostev (MIT Licence) and the Tektronix WFM file
+        format spec [2].
+
+        Parameters
+        ----------
+        header : bytes
+            Header bytes of the file.
+
+        Returns
+        -------
+        meta : dict
+            Metadata of the WFM file.
+
+        References
+        ----------
+        .. [1] https://github.com/vongostev/TekWFM2
+        .. [2] https://download.tek.com/manual/Waveform-File-Format-Manual-077022011.pdf
+
+        """
+        meta = {}
+
+        if len(header) != 838:
+            raise ValueError("WFM header bytes not 838")
+        byte_order = unpk("H", header, offset=0)[0]
+        if byte_order == 0x0F0F:
+            meta["byte_order"] = "<"  # little-endian
+
+        elif meta["byte_order"] == 0xF0F0:
+            meta["byte_order"] = ">"  # big-endian
+        else:
+            raise ValueError("Could not determine endianness.")
+
+        meta["version"] = unpk("8s", header, offset=2)[0]
+        if meta["version"] == b":WFM#001":
+            v1_offset = 2
+        elif meta["version"] == b":WFM#002":
+            v1_offset = 0
+        elif meta["version"] == b":WFM#003":
+            v1_offset = 0
+        else:
+            raise ValueError(
+                f"Only version 1, 2 and 3 of WFM supported, got {meta['version']}."
+            )
+
+        endianness = meta["byte_order"]
+        char_format = endianness + "c"
+        int_format = endianness + "i"
+        uint_format = endianness + "I"
+        byte_format = endianness + "b"
+        ulong_format = endianness + "L"
+        double_format = endianness + "d"
+
+        ## Waveform static file information
+        # Number of bytes per sample
+        meta["bps"] = unpk(byte_format, header, offset=15)[0]
+        # Byte offset to beginning of curve buffer
+        meta["curve_offset"] = unpk(int_format, header, offset=16)[0]
+        # Number of FastFrames
+        meta["nframes"] = unpk(uint_format, header, offset=72)[0] + 1
+
+        ## Waveform header
+        # 0 : Single waveform set, 1 : FastFrame set
+        meta["fastframe"] = unpk(uint_format, header, offset=78)[0]
+        # Number of implicit dimension (time)
+        meta["imp_dim_count"] = unpk(ulong_format, header, offset=114)[0]
+        # Number of explicit dimension (voltage)
+        meta["exp_dim_count"] = unpk(ulong_format, header, offset=118)[0]
+
+        ## Explicit dimension (vertical : voltage)
+        # Scaling to volts, Voltage = (wfmCurveData*vscale) + offset
+        meta["vscale"] = unpk(double_format, header, offset=168 - v1_offset)[0]
+        # offset
+        meta["voffset"] = unpk(double_format, header, offset=176 - v1_offset)[0]
+        # units
+        meta["vunits"] = unpk(char_format, header, offset=188 - v1_offset)[0]
+        # sample data type detection
+        meta["type_code"] = unpk(int_format, header, offset=240 - v1_offset)[0]
+        if meta["type_code"] == 0 and meta["bps"] == 2:
+            meta["dformat"] = endianness + "i2"
+        elif meta["type_code"] == 4 and meta["bps"] == 4:
+            meta["dformat"] = endianness + "f32"
+        else:
+            raise ValueError(
+                f"Data type code {meta['type_code']} or "
+                f"bytes-per-sample {meta['bps']} is not supported."
+            )
+
+        ## Implicit dimension (horizontal : time)
+        # scaling
+        meta["tscale"] = unpk(double_format, header, offset=488 - v1_offset)[0]
+        # offset
+        meta["toffset"] = unpk(double_format, header, offset=496 - v1_offset)[0]
+        # units
+        meta["tunits"] = unpk(char_format, header, 508 - v1_offset)[0]
+        # number of points per frame
+        meta["npoints"] = unpk(ulong_format, header, offset=504 - v1_offset)[0]
+
+        ## Wfm Update specification : trigger timestamp for first frame
+        meta["tsfrac"] = unpk(double_format, header, offset=796 - v1_offset)[0]
+        meta["tsunix"] = unpk(uint_format, header, offset=804 - v1_offset)[0]
+
+        ## Wfm Curve information
+        # Precharge start offset
+        meta["pre_start_offset"] = unpk(ulong_format, header, offset=818 - v1_offset)[0]
+        # Data start offset : bytes from beginning of curve buffer to first point
+        meta["data_start_offset"] = unpk(ulong_format, header, offset=822 - v1_offset)[
+            0
+        ]
+        # Postcharge start offset
+        meta["post_start_offset"] = unpk(ulong_format, header, offset=826 - v1_offset)[
+            0
+        ]
+        # Postcharge stop offset
+        meta["post_stop_offset"] = unpk(ulong_format, header, offset=830 - v1_offset)[0]
+
+        return meta
+
+    def _decode_fastframe_timestamps(
+        self, tsbytes: bytes, k: int, endianness: None | str = None
+    ) -> float:
+        """
+        Decode timestamp for the (k + 1)th frame.
+
+        Parameters
+        ----------
+        tsbytes : bytes
+            Binary data from WfmUpdateSpec object.
+        k : int
+            Index of the frame. 1-based because the first (0th) frame is stored
+            elsewhere in memory.
+        endianness : None or str, optionnal
+            Endianness. If None (default), read from self.
+
+        Returns
+        -------
+        ts : float
+            Absolute timestamp in second of the start trigger of the (k + 1)th frame.
+
+        """
+        if not endianness:
+            endianness = self.meta["byte_order"]
+
+        # fraction of second
+        tsfrac = unpk(f"{endianness}d", tsbytes, offset=12 + k * 24)[0]
+        # unix epoch
+        tsunix = unpk(f"{endianness}l", tsbytes, offset=20 + k * 24)[0]
+
+        return tsfrac + tsunix
+
+    def _load_frames(
+        self, pre: bool = False, post: bool = False, mmap: bool = True
+    ) -> np.ndarray | np.memmap:
+        """
+        Load all available frames. Optionaly, include pre- and post- charge data. By
+        default, memory-mapping is used instead of loading the whole array in RAM.
+
+        Parameters
+        ----------
+        pre, post : bool, optionnal
+            If True, include pre- and post-charge data. Default is False.
+        mmap : bool, optional
+            Use memory-mapping. Default is True.
+
+        Returns
+        -------
+        data : np.ndarray
+            Frames raw data with time series corresponding to one frame on columns.
+
+        """
+
+        # Number of samples : nframes * number of datapoints with pre/post charge
+        nsamples = self.nframes * self.post_stop_offset // self.bps
+
+        # Load data
+        if mmap:
+            data = np.memmap(
+                self.filename,
+                mode="r",
+                dtype=self.dformat,
+                offset=self.curve_offset,
+                shape=nsamples,
+            )
+        else:
+            data = np.fromfile(
+                self.filename,
+                dtype=self.dformat,
+                offset=self.curve_offset,
+                count=nsamples,
+            )
+
+        # Reshape with frames on columns
+        data = data.reshape(self.post_stop_offset // self.bps, self.nframes, order="F")
+
+        # Remove pre-charge data
+        if not pre:
+            start = self.data_start_offset // self.bps
+        else:
+            start = 0
+        # Remove post-charge data
+        if not post:
+            stop = start + self.npoints
+        else:
+            stop = None
+
+        return data[start:stop, :]
+
+    def _get_time_frame(self, start: float, dt: float, nsamples: int) -> np.ndarray:
+        """
+        Generate a time vector.
+
+        Parameters
+        ----------
+        start : float
+            Value of first sample.
+        dt : float
+            Time between to samples.
+        nsamples : int
+            Number of time points.
+
+        Returns
+        -------
+        time_frame : np.ndarray
+            Time vector.
+
+        """
+
+        tstop = start + nsamples * dt
+        return np.linspace(start, tstop, nsamples, endpoint=False)
+
+    def scale_data(self, data: np.ndarray) -> np.ndarray:
+        """
+        Convert input data to physical units (usually, volts)) given conversion factor
+        in metadata.
+
+        Note that if converting all the data at once, if it was in INT16, it will be
+        broadcasted to float and will be very slow. It is advised to perform all
+        necessary computations and reduction before conversion.
+
+        Parameters
+        ----------
+        data : np.ndarray
+            Input data to convert.
+
+        Returns
+        -------
+        data_scale : np.ndarray
+            Data scaled to physical units.
+
+        """
+        return data * self.vscale + self.voffset
+
+    def get_timestamps(self) -> Self:
+        """
+        Load, decode and store FastFrames onsets as an numpy array.
+
+        """
+
+        # Get timestamps bytes
+        bts = self._load_timestamps()
+
+        # Preallocate array
+        frame_onsets = np.empty(self.nframes, dtype=float)
+
+        # Get first frame timestamps
+        frame_onsets[0] = self.tsunix + self.tsfrac
+
+        # Get the rest
+        frame_onsets[1:] = [
+            self._decode_fastframe_timestamps(bts, k, endianness=self.byte_order)
+            for k in range(self.nframes - 1)
+        ]
+
+        # Start at 0
+        frame_onsets -= frame_onsets[0]
+
+        # Store
+        self.frame_onsets = frame_onsets
+
+        return self
+
+    def load_frames(self, **kwargs) -> Self:
+        """
+        Wrap the `_load_frames()` method and stores the loaded array as an attribute.
+
+        """
+        self.frames = self._load_frames(**kwargs)
+
+        return self
+
+    def get_time_frame(self) -> Self:
+        """
+        Generate a time vector corresponding to one frame. Require the frames to be
+        loaded so we know how many points there are (eg. if pre- and post-charge data
+        was included), otherwise assume pre- and post-charge data is not included.
+
+        """
+        start = self.toffset
+        dt = self.tscale
+        if hasattr(self, "frames"):
+            nsamples = self.frames.shape[0]
+        else:
+            print(
+                "[Warn] Frames not loaded, assuming time vector without pre- and "
+                "post-charge."
+            )
+            nsamples = self.npoints
+
+        self.time_frame = self._get_time_frame(start, dt, nsamples)
+
+        return self