Skip to content

File Operations Module

Functions for importing, exporting, and saving data in various formats.

Load and Save

load_data 

load_data(parent=None, filename=None)

Loads a dataset from filename, or displays a file dialog if no filename is given (the dialog needs the GUI extras installed).

Container detection is by content (zip magic bytes); .mat and legacy .npy fall back to extension:

  • .dvma container files (zip magic bytes) — the default format since 1.5.0; safe, pickle-free (see container).
  • legacy .npy pickle saves from pydvma <= 1.4.0 — supported forever. Trust model: the legacy path uses np.load(allow_pickle=True), and unpickling can execute arbitrary code, so only open legacy .npy files you or your lab created. .dvma files do not have this caveat.
  • .mat (by extension) — JW-logger imports.

save_data 

save_data(dataset, parent=None, filename=None, overwrite_without_prompt=False, sets=None)

Saves a DataSet to 'filename.dvma' (container format v2 — a zip of manifest.json + pickle-free .npy arrays; see container), or provides a dialog if no filename is given.

Legacy escape hatch: an explicit filename ending in .npy writes the pre-1.5.0 pickle format instead, for workflows that still need it. New saves should prefer .dvma — it is safe to share (loading executes no code) and readable outside Python.

Parameters:

  • dataset (DataSet) –

    An object of the class DataSet

  • parent (optional, default: None ) –

    Parent widget for file dialog

  • filename (str, default: None ) –

    Output filename, dialog shown if not provided

  • overwrite_without_prompt (bool, default: False ) –

    If True, overwrite without asking

  • sets (int or Iterable[int], default: None ) –

    If given, writes dataset.subset(sets) instead of the whole dataset — the notebook counterpart of the web app's Save "Choose sets…" picker (see datastructure.DataSet.subset for the exact inclusion rule). None (the default) writes dataset unchanged.

save_fig 

save_fig(plot, parent=None, figsize=None, filename=None, overwrite_without_prompt=False)

Saves figure to file 'filename.png' and 'filename.pdf', or provides dialog if no filename provided.

Parameters:

  • plot (PlotData or Figure) –

    A PlotData object or matplotlib Figure object

  • parent (optional, default: None ) –

    Parent widget for file dialog

  • figsize (tuple, default: None ) –

    Tuple for figure size

  • filename (str, default: None ) –

    Output filename, dialog shown if not provided

  • overwrite_without_prompt (bool, default: False ) –

    If True, overwrite without asking

Export Functions

export_to_matlab 

export_to_matlab(dataset, parent=None, filename=None, overwrite_without_prompt=False)

Exports dataset class to file 'filename.mat', or provides dialog if no filename provided.

Saved file can be loaded directly in Matlab as set of arrays.

Parameters:

  • dataset (DataSet) –

    An object of the class DataSet

  • parent (optional, default: None ) –

    Parent widget for file dialog

  • filename (str, default: None ) –

    Output filename, dialog shown if not provided

  • overwrite_without_prompt (bool, default: False ) –

    If True, overwrite without asking

export_to_matlab_jwlogger 

export_to_matlab_jwlogger(dataset, parent=None, filename=None, overwrite_without_prompt=False)

Exports dataset class to file 'filename.mat', or provides dialog if no filename provided.

Saved file is compatible with Jim Woodhouse logger file format.

Parameters:

  • dataset (DataSet) –

    An object of the class DataSet

  • parent (optional, default: None ) –

    Parent widget for file dialog

  • filename (str, default: None ) –

    Output filename, dialog shown if not provided

  • overwrite_without_prompt (bool, default: False ) –

    If True, overwrite without asking

export_to_csv 

export_to_csv(data_list, parent=None, filename=None, overwrite_without_prompt=False)

Exports data to file 'filename.csv', or provides dialog if no filename provided.

Saved file is *.csv

Parameters:

  • data_list (TimeDataList, FreqDataList, or TfDataList) –

    Data list to export

  • parent (optional, default: None ) –

    Parent widget for file dialog

  • filename (str, default: None ) –

    Output filename, dialog shown if not provided

  • overwrite_without_prompt (bool, default: False ) –

    If True, overwrite without asking

Import Functions

import_from_matlab_jwlogger 

import_from_matlab_jwlogger(filename=None)

Imports dataset class from file 'filename.mat', or provides dialog if no filename provided.

Saved file is compatible with Jim Woodhouse logger file format. The conventions below were confirmed against the recovered MATLAB source ("Data logger V2.9a": specmenu.m save path, avtflogpars.m averaged-TF computation, dospec.m):

  • SPECTRAL files save yspec, dt2, npts, freq, tfun. freq is the SAMPLE RATE, npts the FFT length, so yspec has npts/2 + 1 rows on the one-sided axis rfftfreq(npts, 1/freq) (df = freq/npts).
  • TIME files save indata, buflen, freq, dt2, tsmax — there is NO npts and no tfun (JW's guitar_string captures confirmed this; the old import assumed npts and raised KeyError). The time axis comes from indata's own length at fs = freq; buflen duplicates that length and tsmax records the capture's scale (the data is already in physical units — do NOT rescale by it).
  • tfun selects spectrum (0) / transfer function (1).
  • dt2 is the saved dtype vector [n_time_channels, n_yspec_columns, n_sonogram] — column COUNTS, not column types.
  • The averaged-TF logger writes yspec as INTERLEAVED pairs [H1, coh1, H2, coh2, ...] — each output channel's H1-estimator TF followed by its coherence (avtflogpars.m: thing(:,2k-1) = cross/autoin; thing(:,2k) = |cross|^2/(autoin*autoout)).
  • The save menu also allows ARBITRARY column subsets ("Channels to save": one / all / displayed / custom) and files can be composited by the Add-on-load path — so real archives also contain bare-H files (coherence stripped) and multi-instrument H collections.
  • The writer duplicates the first positive bin into the DC row (yspec(1,:) = yspec(2,:)), so the DC bin is cosmetic.

Import behaviour for TF files: coherence columns are detected unambiguously (real-valued AND within [0, 1] — no measured complex FRF is both). The documented interleaved [H, coh, ...] layout is recognised and split with positional pairing; an equal split in any other order pairs by order of appearance; files with no coherence columns, or an ambiguous mix, import as before (every column a TF channel — nothing is dropped).

Parameters:

  • filename (str, default: None ) –

    Input filename, dialog shown if not provided