mth5.processing.spectre package
Submodules
mth5.processing.spectre.frequency_band_helpers module
Module for tools for create and manage frequency bands.
Bands can be defined by explicitly specifying band edges for each band, but here are some convenience functions for other ways to specify.
- mth5.processing.spectre.frequency_band_helpers.bands_of_constant_q(band_center_frequencies: ndarray, q: float | None = None, fractional_bandwidth: float | None = None) FrequencyBands[source]
Generate frequency bands centered at band_center_frequencies. These bands have Q = f_center/delta_f = constant. Normally f_center is defined geometrically, i.e. sqrt(f2*f1) is the center freq between f1 and f2.
- Parameters:
band_center_frequencies (np.ndarray) – The center frequencies for the bands
q (float) – Q = f_center/delta_f = constant. Q is 1/fractional_bandwidth. Q is nonsene when less than 1, just as fractional bandwidth is nonsense when greater than 1. - Upper case Q is used in the literature See - https://en.wikipedia.org/wiki/Bandwidth_(signal_processing)#Fractional_bandwidth - https://en.wikipedia.org/wiki/Q_factor
- Returns:
frequency_bands – Frequency bands object with bands packed inside.
- Return type:
FrequencyBands
- mth5.processing.spectre.frequency_band_helpers.half_octave(target_frequency: float, fft_frequencies: ndarray | None = None) Band[source]
Create a half-octave wide frequency band object centered at target frequency.
- Parameters:
target_frequency (float) – The center frequency (geometric) of the band
fft_frequencies (Optional[np.ndarray]) – (array-like) Frequencies associated with an instance of a spectrogram. If provided, the indices of the spectrogram associated with the band will be stored in the Band object.
- Rtype band:
mt_metadata.common.band.Band
- Return band:
FrequencyBand object with lower and upper bounds.
- mth5.processing.spectre.frequency_band_helpers.log_spaced_frequencies(f_lower_bound: float, f_upper_bound: float, num_bands: int | None = None, num_bands_per_decade: float | None = None, num_bands_per_octave: float | None = None)[source]
Convenience function for generating logarithmically spaced fenceposts running from f_lower_bound Hz to f_upper_bound Hz.
These can be taken, two at a time as band edges, or used as band centers with a constant Q scheme. This is basically the same as np.logspace, but allows for specification of frequencies in Hz.
Note in passing, replacing np.exp with 10** and np.log with np.log10 yields same base.
- Parameters:
f_lower_bound (float) – lowest frequency under consideration
f_upper_bound (float) – highest frequency under consideration
num_bands (int) –
- Total number of bands. Note that num_bands is one fewer than the number
of frequencies returned (gates and fenceposts).
num_bands_per_decade (int (TODO test, float maybe ok also.. need to test)) – number of bands per decade. 8 is a nice choice.
num_bands – total number of bands. This supercedes num_bands_per_decade if supplied
- Returns:
frequencies – logarithmically spaced fence posts acoss lowest and highest frequencies. These partition the frequency domain between f_lower_bound and f_upper_bound
- Return type:
array
mth5.processing.spectre.prewhitening module
This module has methods for pre-whitening time series to reduce spectral leakage before FFT.
- mth5.processing.spectre.prewhitening.apply_prewhitening(prewhitening_type: Literal['first difference', ''], run_xrds_input: Dataset) Dataset[source]
Applies pre-whitening to time series to avoid spectral leakage when FFT is applied.
- Parameters:
prewhitening_type (Literal["first difference", ]) – Placeholder to allow for multiple methods of pre-whitening. Currently only “first difference” is supported.
run_xrds_input (xr.Dataset) – Time series to be pre-whitened (can be multivariate).
- Returns:
run_xrds – pre-whitened time series
- Return type:
xr..Dataset
- mth5.processing.spectre.prewhitening.apply_recoloring(prewhitening_type: Literal['first difference'], stft_obj: Dataset) Dataset[source]
Inverts the pre-whitening operation in frequency domain. Modifies the input xarray in-place.
- Parameters:
prewhitening_type (Literal["first difference", ]) – Placeholder to allow for multiple methods of pre-whitening. Currently only “first difference” is supported.
stft_obj (xarray.core.dataset.Dataset) – Time series of Fourier coefficients to be recoloured
- Returns:
stft_obj – Recolored time series of Fourier coefficients.
- Return type:
xarray.core.dataset.Dataset
mth5.processing.spectre.stft module
This module has methods for applying the short-time-Fourier-transform.
- mth5.processing.spectre.stft.run_ts_to_stft_scipy(decimation_obj: DecimationLevel | Decimation, run_xrds_orig: Dataset) Spectrogram[source]
Converts a runts object into a time series of Fourier coefficients. This method uses scipy.signal.spectrogram.
TODO: consider making this a method of RunTS; runts.to_spectrogram(decimation_obj)
- Parameters:
decimation_obj (Union[AuroraDecimationLevel, FCDecimation]) – Information about how the decimation level is to be processed
run_xrds_orig (: xarray.core.dataset.Dataset) – Time series to be processed
- Returns:
stft_obj – Time series of Fourier coefficients
- Return type:
xarray.core.dataset.Dataset