Skip to content

Waveform I/O

Read saved waveform files back into arrays and normalized metadata

Read saved waveform files back into numpy arrays + normalized metadata.

The public entry point for users who want their raw data out of the library's five on-disk formats (NPZ, plain CSV, enhanced CSV, MAT, HDF5) for their own analysis. Reads files written before provenance existed (provenance is then None) and normalizes the three binary formats' differing metadata conventions (see scpi_control.waveform_schema) into one flat dict.

LoadedWaveform dataclass 

LoadedWaveform(time: ndarray, voltage: ndarray, channel: Optional[Union[int, str]], sample_rate: Optional[float], metadata: Dict[str, Any] = dict(), provenance: Optional[AcquisitionProvenance] = None, source_format: str = 'NPZ', source_path: Optional[Path] = None)

One waveform read back from disk, format differences normalized away.

to_dataframe 

to_dataframe()

Return a pandas DataFrame (columns: time, voltage; metadata in .attrs).

Source code in scpi_control/waveform_io.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
def to_dataframe(self):
    """Return a pandas DataFrame (columns: time, voltage; metadata in .attrs)."""
    try:
        import pandas as pd
    except ImportError:
        raise ImportError("pandas is required for to_dataframe(). Install with: pip install pandas")
    df = pd.DataFrame({"time": self.time, "voltage": self.voltage})
    df.attrs["channel"] = self.channel
    df.attrs["sample_rate"] = self.sample_rate
    df.attrs["metadata"] = dict(self.metadata)
    if self.provenance is not None:
        df.attrs["provenance"] = self.provenance.to_dict()
    return df

load_waveform 

load_waveform(path: Union[str, Path], format: Optional[str] = None) -> LoadedWaveform

Load a waveform file saved by scpi_control (any version, any format).

Parameters:

Name Type Description Default
path Union[str, Path]

File to read.

 required
format Optional[str]

Force a format ("NPZ", "CSV", "MAT", "HDF5"); None auto-detects from the extension.

 None

Raises:

Type Description
FileNotFoundError

If path does not exist.
ValueError

If the format is unknown or the file cannot be parsed.
ImportError

If the format needs an uninstalled optional dependency.
Source code in scpi_control/waveform_io.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def load_waveform(path: Union[str, Path], format: Optional[str] = None) -> LoadedWaveform:
    """Load a waveform file saved by scpi_control (any version, any format).

    Args:
        path: File to read.
        format: Force a format ("NPZ", "CSV", "MAT", "HDF5"); None auto-detects
            from the extension.

    Raises:
        FileNotFoundError: If path does not exist.
        ValueError: If the format is unknown or the file cannot be parsed.
        ImportError: If the format needs an uninstalled optional dependency.
    """
    path = Path(path)
    if not path.exists():
        raise FileNotFoundError(f"Waveform file not found: {path}")
    if format is None:
        format = _EXTENSION_FORMATS.get(path.suffix.lower())
        if format is None:
            raise ValueError(f"Cannot detect format from extension {path.suffix!r}. Pass format= explicitly (NPZ, CSV, MAT, HDF5).")
    format = format.upper()
    if format in ("NPY", "NPZ"):
        return _load_npz(path)
    if format in ("CSV", "CSV_ENHANCED"):
        return _load_csv(path)
    if format == "MAT":
        return _load_mat(path)
    if format == "HDF5":
        return _load_hdf5(path)
    raise ValueError(f"Unknown format: {format}. Supported: NPZ, CSV, MAT, HDF5")

See Also

  • Waveform - Waveform acquisition and data handling
  • Provenance - Acquisition provenance attached to saved waveforms