Data Structure Module

Core data structures for storing and managing measurement data.

Main Container

DataSet

Attributes

time_data_list instance-attribute

time_data_list = TimeDataList()

freq_data_list instance-attribute

freq_data_list = FreqDataList()

cross_spec_data_list instance-attribute

cross_spec_data_list = CrossSpecDataList()

tf_data_list instance-attribute

tf_data_list = TfDataList()

modal_data_list instance-attribute

modal_data_list = ModalDataList()

sono_data_list instance-attribute

sono_data_list = SonoDataList()

meta_data_list instance-attribute

meta_data_list = MetaDataList()

pydvma_version instance-attribute

pydvma_version = VERSION

Functions

__init__

__init__(data=None)

add_to_dataset

add_to_dataset(data)

replace_data_item

replace_data_item(data, n_set)

remove_last_data_item

remove_last_data_item(data_class)

remove_data_item_by_index

remove_data_item_by_index(data_class, list_index)

calculate_fft_set

calculate_fft_set(time_range=None, window=None)

Calls analysis.calculate_fft on each TimeData item in the TimeDataList and adds FreqDataList object to dataset

calculate_tf_set

calculate_tf_set(ch_in=0, time_range=None, window=None, N_frames=1, overlap=0.5)

Calls analysis.calculate_fft on each TimeData item in the TimeDataList and adds FreqDataList object to dataset

calculate_cross_spectrum_matrix_set

calculate_cross_spectrum_matrix_set(ch_in=0, time_range=None, window='hann', N_frames=1, overlap=0.5)

Calls analysis.calculate_fft on each TimeData item in the TimeDataList and adds FreqDataList object to dataset

calculate_tf_averaged

calculate_tf_averaged(ch_in=0, time_range=None, window='hann')

Calls analysis.calculate_fft on each TimeData item in the TimeDataList and adds FreqDataList object to dataset

calculate_cross_spectra_averaged

calculate_cross_spectra_averaged(time_range=None, window=None)

Calls analysis.calculate_fft on each TimeData item in the TimeDataList and adds FreqDataList object to dataset

calculate_sono_set

calculate_sono_set(nperseg=None)

clean_impulse

clean_impulse(ch_impulse=0)

Calls analysis.clean_impulse on each TimeData item in the TimeDataList and returns a copy of the new dataset.

Note that calling this function does not change the data, and just returns a copy.

save_data

save_data(filename=None)

export_to_matlab

export_to_matlab(filename=None, overwrite_without_prompt=False)

export_to_matlab_jwlogger

export_to_matlab_jwlogger(filename=None, overwrite_without_prompt=False)

plot_time_data

plot_time_data(sets='all', channels='all')

plot_freq_data

plot_freq_data(sets='all', channels='all')

plot_tf_data

plot_tf_data(sets='all', channels='all')

plot_sono_data

plot_sono_data(n_set=0, n_chan=0, db_range=60)

__repr__

__repr__()

Time Domain Data

TimeData

One block of acquired time-series data plus its acquisition metadata.

Held inside a DataSet.time_data_list. Produced by log_data, by the test-data factories in testdata, and on import from Matlab. The numeric content is in volts (see "Voltage-Based I/O" in the user-guide acquisition page); apply channel_cal_factors to convert to engineering units at display or fit time. analysis.calculate_* functions copy units and channel_cal_factors onto their derived FreqData / TfData / CrossSpecData / SonoData outputs.

Attributes:

• time_axis (ndarray) –

  1D sample times in seconds.

• time_data (ndarray) –

  Shape (n_samples, n_channels) voltage samples.

• settings (MySettings) –

  Snapshot of the acquisition configuration.

• timestamp (datetime) –

  Capture start time.

• timestring (str) –

  Filesystem-safe rendering of timestamp.

• units (list[str] or None) –

  Engineering units per channel (e.g. ['N', 'm/s', 'g']). None if unset.

• channel_cal_factors (ndarray) –

  Per-channel multipliers from volts to engineering units. Defaults to all-ones.

• id_link –

  Reference to a source TimeData (used when this object is derived rather than freshly acquired).

• test_name (str or None) –

  Free-form label, displayed in plots.

• unique_id (UUID) –

  Generated at construction; used by derived objects to link back to their source via id_link.

Attributes

time_axis instance-attribute

time_axis = time_axis

time_data instance-attribute

time_data = time_data

settings instance-attribute

settings = settings

timestamp instance-attribute

timestamp = timestamp

timestring instance-attribute

timestring = timestring

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = channel_cal_factors

id_link instance-attribute

id_link = id_link

test_name instance-attribute

test_name = test_name

unique_id instance-attribute

unique_id = uuid4()

Functions

__init__

__init__(time_axis, time_data, settings, timestamp=None, timestring=None, units=None, channel_cal_factors=None, id_link=None, test_name=None)

__repr__

__repr__()

TimeDataList

Bases: list

Functions

calculate_fft_set

calculate_fft_set(time_range=None, window=None)

Calls analysis.calculate_fft on each item in the list and returns FreqDataList object

calculate_tf_set

calculate_tf_set(ch_in=0, time_range=None, window=None, N_frames=1, overlap=0.5)

Calls analysis.calculate_tf on each item in the list and returns TfDataList object

calculate_cross_spectrum_matrix_set

calculate_cross_spectrum_matrix_set(ch_in=0, time_range=None, window=None, N_frames=1, overlap=0.5)

Calls analysis.calculate_tf on each item in the list and returns TfDataList object

calculate_tf_averaged

calculate_tf_averaged(ch_in=0, time_range=None, window='hann')

Calls analysis.calculate_tf_averaged on whole list and returns TfData object

calculate_cross_spectra_averaged

calculate_cross_spectra_averaged(time_range=None, window=None)

Calls analysis.calculate_tf_averaged on whole list and returns TfData object

calculate_sono_set

calculate_sono_set(nperseg=None)

Calls analysis.calculate_sonogram on each item in the list and returns SonoDataList object

get_calibration_factors

get_calibration_factors()

set_calibration_factors_all

set_calibration_factors_all(factors)

set_calibration_factor

set_calibration_factor(factor, n_set=0, n_chan=0)

export_to_csv

export_to_csv(filename=None, overwrite_without_prompt=False)

Frequency Domain Data

FreqData

One-sided complex frequency spectrum of a TimeData capture.

Produced by analysis.calculate_fft. The spectrum is the raw np.fft.rfft of the (optionally windowed) time data — i.e. it is not scaled to a PSD or amplitude spectrum; consumers that need PSD should square the magnitude themselves. units and channel_cal_factors are copied verbatim from the source TimeData.

Attributes:

• freq_axis (ndarray) –

  Frequency bins in Hz (length N//2+1).

• freq_data (ndarray) –

  Shape (n_freq, n_channels) complex spectrum, one column per channel.

• settings (MySettings) –

  Snapshot of the analysis configuration (includes the window choice and the time range that was used).

• units (list[str] or None) –

  Engineering units per channel.

• channel_cal_factors (ndarray) –

  Per-channel multipliers from volts to engineering units; applied at display time.

• id_link (UUID) –

  unique_id of the source TimeData.

• test_name (str or None) –

  Free-form label.

• timestamp (datetime) –

  When this FreqData was constructed.

• timestring (str) –

  Filesystem-safe rendering of timestamp.

Attributes

freq_axis instance-attribute

freq_axis = freq_axis

freq_data instance-attribute

freq_data = freq_data

settings instance-attribute

settings = settings

test_name instance-attribute

test_name = test_name

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = channel_cal_factors

id_link instance-attribute

id_link = id_link

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

Functions

__init__

__init__(freq_axis, freq_data, settings, units=None, channel_cal_factors=None, id_link=None, test_name=None)

__repr__

__repr__()

FreqDataList

Bases: list

Functions

get_calibration_factors

get_calibration_factors()

set_calibration_factors_all

set_calibration_factors_all(factors)

set_calibration_factor

set_calibration_factor(factor, n_set=0, n_chan=0)

export_to_csv

export_to_csv(filename=None, overwrite_without_prompt=False)

Transfer Function Data

TfData

Transfer function H(f) from one input channel to one or more outputs.

Produced by analysis.calculate_tf (single TimeData) or analysis.calculate_tf_averaged (ensemble TimeDataList). The convention is Pxy[in, out] / Pxy[in, in] per output channel; tf_coherence carries the corresponding coherence.

Calibration: channel_cal_factors[k] holds the ratio cal[out_k] / cal[in] — i.e. multiplying tf_data[:, k] * channel_cal_factors[k] at display time gives the TF in engineering units. Units are constructed as "<out_unit>/<in_unit>" per output channel.

Attributes:

• freq_axis (ndarray) –

  One-sided frequency bins in Hz.

• tf_data (ndarray) –

  Shape (n_freq, n_outputs), complex. One column per non-input channel.

• tf_coherence (ndarray) –

  Same shape, real, in [0, 1].

• settings (MySettings) –

  Snapshot including the chosen ch_in and the derived ch_out_set (the channel indices in tf_data's second axis).

• units (list[str] or None) –

  Per-output-channel unit strings (e.g. ['m/s/N', 'g/N']).

• channel_cal_factors (ndarray) –

  Per-output cal ratios (cal[out] / cal[in]). A manual override here overwrites the inherited ratio.

• id_link –

  unique_id of the source TimeData (or list when averaged).

• test_name (str or None) –

  Free-form label.

• timestamp (datetime) –

  When constructed.

• timestring (str) –

  Filesystem-safe rendering of timestamp.

• flag_modal_TF (bool) –

  True after a modal fit has consumed this TfData (avoids double-fitting); used by modal.py.

Attributes

freq_axis instance-attribute

freq_axis = freq_axis

tf_data instance-attribute

tf_data = tf_data

tf_coherence instance-attribute

tf_coherence = tf_coherence

settings instance-attribute

settings = settings

test_name instance-attribute

test_name = test_name

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = channel_cal_factors

id_link instance-attribute

id_link = id_link

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

flag_modal_TF instance-attribute

flag_modal_TF = False

Functions

__init__

__init__(freq_axis, tf_data, tf_coherence, settings, units=None, channel_cal_factors=None, id_link=None, test_name=None)

__repr__

__repr__()

TfDataList

Bases: list

Functions

get_calibration_factors

get_calibration_factors()

set_calibration_factors_all

set_calibration_factors_all(factors)

set_calibration_factor

set_calibration_factor(factor, n_set=0, n_chan=0)

add_modal_reconstruction

add_modal_reconstruction(tf_data, mode='replace')

export_to_csv

export_to_csv(filename=None, overwrite_without_prompt=False)

Sonogram Data

SonoData

Short-time-FFT spectrogram (sonogram) of a multi-channel TimeData.

Produced by analysis.calculate_sonogram. Each frame is a windowed FFT of a nperseg-sample segment of the source data; segments are overlapped by noverlap and the resulting matrix lets you see how spectral content evolves over time. Used by analysis.calculate_damping_from_sono to extract per-mode damping from free-decay measurements.

Attributes:

• time_axis (ndarray) –

  Frame midpoints in seconds.

• freq_axis (ndarray) –

  One-sided frequency bins in Hz.

• sono_data (ndarray) –

  Shape (n_freq, n_frames, n_channels), complex. Magnitude-squared gives a per-bin power spectrogram.

• settings (MySettings) –

  Snapshot including pretrig_samples (used by calculate_damping_from_sono to pick the free-decay start time).

• units (list[str] or None) –

  Engineering units per channel.

• channel_cal_factors (ndarray) –

  Per-channel multipliers from volts to engineering units.

• id_link –

  unique_id of the source TimeData.

• test_name (str or None) –

  Free-form label.

• timestamp (datetime) –

  When constructed.

• timestring (str) –

  Filesystem-safe rendering of timestamp.

Attributes

time_axis instance-attribute

time_axis = time_axis

freq_axis instance-attribute

freq_axis = freq_axis

sono_data instance-attribute

sono_data = sono_data

settings instance-attribute

settings = settings

test_name instance-attribute

test_name = test_name

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = channel_cal_factors

id_link instance-attribute

id_link = id_link

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

Functions

__init__

__init__(time_axis, freq_axis, sono_data, settings, units=None, channel_cal_factors=None, id_link=None, test_name=None)

__repr__

__repr__()

SonoDataList

Bases: list

Cross-Spectrum Data

CrossSpecData

Full cross-spectrum matrix Pxy[i,j,f] and coherence matrix Cxy[i,j,f].

Produced by analysis.calculate_cross_spectrum_matrix (single TimeData) or analysis.calculate_cross_spectra_averaged (ensemble TimeDataList). The diagonal Pxy[i, i, :] is the per-channel auto-spectrum (= scipy.signal.welch with scaling='spectrum'); off-diagonal Pxy[i, j, :] matches scipy.signal.csd with the same settings. Pxy is Hermitian — Pxy[j, i, :] = conj(Pxy[i, j, :]).

Attributes:

• freq_axis (ndarray) –

  One-sided frequency bins in Hz.

• Pxy (ndarray) –

  Shape (n_channels, n_channels, n_freq), complex. Cross-spectrum matrix.

• Cxy (ndarray) –

  Same shape, real, in [0, 1]. Coherence matrix.

• settings (MySettings) –

  Includes window, time_range, N_frames, overlap actually used.

• units (list[str] or None) –

  Engineering units per channel.

• channel_cal_factors (ndarray) –

  Per-channel multipliers from volts to engineering units.

• id_link –

  unique_id of the source TimeData (or list of ids when averaged across a TimeDataList).

• test_name (str or None) –

  Free-form label.

• timestamp (datetime) –

  When constructed.

• timestring (str) –

  Filesystem-safe rendering of timestamp.

Attributes

freq_axis instance-attribute

freq_axis = freq_axis

Pxy instance-attribute

Pxy = Pxy

Cxy instance-attribute

Cxy = Cxy

settings instance-attribute

settings = settings

test_name instance-attribute

test_name = test_name

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = channel_cal_factors

id_link instance-attribute

id_link = id_link

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

Functions

__init__

__init__(freq_axis, Pxy, Cxy, settings, units=None, channel_cal_factors=None, id_link=None, test_name=None)

__repr__

__repr__()

CrossSpecDataList

Bases: list

Modal Data

ModalData

A set of fitted modes — each row of M is one mode's (fn, zn, an[chan...], pn[chan...], rk[chan...], rm[chan...]) parameter vector as produced by modal.modal_fit_all_channels.

Use add_mode to append further modes (e.g. across separate frequency-band fits); rows are kept sorted by fn. After any add/delete, the summary arrays fn, zn, an, pn are refreshed and indexable per mode.

Attributes:

• M (ndarray) –

  Shape (n_modes, 2 + 4*n_channels). Each row packs [fn, zn, an_0..an_C, pn_0..pn_C, rk_0..rk_C, rm_0..rm_C].

• fn (ndarray) –

  Per-mode natural frequencies in Hz.

• zn (ndarray) –

  Per-mode damping ratios.

• an (ndarray) –

  Shape (n_modes, n_channels) modal-constant amplitudes.

• pn (ndarray) –

  Same shape; modal-constant phases in radians.

• channels (int) –

  Number of channels (= n_channels above).

• settings (MySettings) –

  Snapshot including the source TF's settings.

• units –

  Engineering units (passed through from source).

• id_link –

  unique_id(s) of the TFs that produced these modes.

• test_name (str or None) –

  Free-form label.

Attributes

M instance-attribute

M = []

test_name instance-attribute

test_name = test_name

settings instance-attribute

settings = settings

channels instance-attribute

channels = 0

units instance-attribute

units = units

id_link instance-attribute

id_link = id_link

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

Functions

__init__

__init__(xn=None, settings=None, units=None, id_link=None, test_name=None)

add_mode

add_mode(xn)

delete_mode

delete_mode(mode_number)

__repr__

__repr__()

ModalDataList

Bases: list

Metadata

MetaData

Attributes

units instance-attribute

units = units

channel_cal_factors instance-attribute

channel_cal_factors = None

tf_cal_factors instance-attribute

tf_cal_factors = None

timestamp instance-attribute

timestamp = t

timestring instance-attribute

timestring = '_' + str(year) + '_' + str(month) + '_' + str(day) + '_at_' + str(hour) + '_' + str(minute) + '_' + str(second)

Functions

__init__

__init__(units=None, channel_cal_factors=None, tf_cal_factors=None, test_name=None)

__repr__

__repr__()

MetaDataList

Bases: list