Skip to content

Wandas 0.9.0

Wandas 0.9.0 makes one cached STFT the starting point for cross-spectral analysis: the CSD, transfer function and coherence can be derived from an existing spectrogram or CSD without recomputing the spectra. It also adds opt-in sparse STFTs and WAV output to binary streams, and changes the default STFT hop to follow the window length.

Highlights / 主な変更

  • SpectrogramFrame.csd() averages the frames of an existing STFT into a complete CSD, and CrossSpectralFrame.transfer_function() and CrossSpectralFrame.coherence() derive both quantities from it.
  • stft(detrend="constant" | "linear") removes each frame's trend so the spectrogram route matches ChannelFrame.csd() with the same detrend.
  • stft(allow_sparse=True) accepts hops longer than the window (WDF 0.6, STFT Recipe operation version 2).
  • to_wav and write_wav write to binary streams such as BytesIO and pipes.
  • An omitted STFT hop_length now defaults to win_length // 4 instead of n_fft // 4.

Changes

Compatibility and migration

Affected surface or artifact Classification Deprecation start Replacement or migration Removal/change version Exception reason and decision link
Default hop_length of ChannelFrame.stft() and ChannelFrameDataset.stft() when win_length < n_fft Stable, semantic change None Pass hop_length=n_fft // 4 to keep the old frames 0.9.0 The old default gave a non-overlapping Hann STFT that could not be inverted; #483
Sparse STFT results Serialized, additive WDF 0.6 Not applicable Upgrade readers to 0.9.0+ before loading sparse artifacts 0.9.0 Non-sparse results keep their WDF version; #470
STFT Recipe nodes Serialized, operation version 2 Not applicable New Recipes publish version 2; version 1 nodes remain replayable with the n_fft // 4 default 0.9.0 #470, #483
SpectrogramFrame.csd, CrossSpectralFrame.transfer_function/coherence, stft(detrend=...), WAV streams Stable, additive Not applicable Opt in to the new API 0.9.0 No removal

0.9.0では、win_length を n_fft より短く指定し hop_length を省略した stft() の hop が変わります。以前の結果を再現するには hop_length=n_fft // 4 を渡してください。 sparse STFT の結果は WDF 0.6 で保存されるため、読込側も0.9.0以降へ揃えてください。

Sparse STFT compatibility

STFT accepts allow_sparse=True for hops exceeding the window length. Per-frame cepstrum and spectral-envelope transformations preserve these gaps. Sparse results use WDF 0.6; other results retain their existing WDF version. New STFT Recipes publish operation version 2 while version 1 remains replayable. Upgrade readers before loading these new artifacts. ISTFT reconstruction still requires overlapping windows.

STFT default hop follows the window length

ChannelFrame.stft() and ChannelFrameDataset.stft() now default an omitted hop_length to win_length // 4, as welch(), csd(), coherence(), transfer_function() and the librosa convention already do. They previously used n_fft // 4.

This changes results for calls that pass a win_length smaller than n_fft without hop_length. For example, stft(n_fft=2048, win_length=512) now uses a hop of 128 instead of 512. The old hop equalled the window, so a Hann STFT had no overlap and its ISTFT could not reconstruct the signal. A call that relied on the old default and used a window shorter than n_fft // 4 raised an error; it now succeeds. Calls without win_length, or with win_length=n_fft, and calls with an explicit hop_length are unchanged. To keep the old frames, pass hop_length=n_fft // 4.

Saved spectrograms and WDF files store the resolved hop and are unaffected. STFT Recipes saved by Wandas 0.8.1 (operation version 1) keep the n_fft // 4 default on replay. Recipes keep an omitted hop omitted, so version 2 Recipes replay with the new default.

Transfer function and coherence from a CSD

CrossSpectralFrame.transfer_function() and CrossSpectralFrame.coherence() derive both quantities from an existing complete CSD without recomputing the spectra, and both are Recipe operations. ChannelFrame.transfer_function() and ChannelFrame.coherence() now compute one CSD matrix internally; their values and signatures are unchanged.

SpectrogramFrame.csd() builds the same complete CSD from an existing STFT by averaging its frames, so one cached spectrogram can feed the spectrogram view, the CSD, the transfer function and the coherence. stft() accepts detrend="constant" or "linear" to remove each frame's trend first, so the result matches ChannelFrame.csd() with the same detrend; new STFT Recipe version 2 nodes record it, and version 1 nodes reject it.

CrossSpectralFrame.coherence() warns when the CSD was computed with average="median", because that coherence can exceed 1.

WAV output destinations

ChannelFrame.to_wav and write_wav now accept writable binary streams, including BytesIO, with an explicit format="WAV". Output is encoded in memory and written at the stream's current position, so non-seekable streams such as pipes are supported. Caller-owned streams remain open. Strings and all os.PathLike paths continue to infer the format from the extension; custom path objects are converted with os.fspath.