API

The main functionality of pywavelet is to help transform/inverse transform data from the time/frequency domains to the WDM-wavelet domain.

Transform Functions

pywavelet.transforms.from_time_to_wavelet(timeseries: TimeSeries, Nf: int | None = None, Nt: int | None = None, nx: float = 4.0, mult: int = 32) → Wavelet

Transform time-domain data to wavelet-domain data.

This function performs a forward wavelet transform, converting a time-domain signal into a wavelet-domain representation.

Parameters

timeseriesTimeSeries

Input time-domain data, represented as a TimeSeries object.

Nfint, optional

Number of frequency bins for the wavelet transform. Default is None.

Ntint, optional

Number of time bins for the wavelet transform. Default is None.

nxfloat, optional

Number of standard deviations for the phi_vec, controlling the width of the wavelets. Default is 4.0.

multint, optional

Number of time bins to use for the wavelet transform. Ensure mult is not larger than half the number of time bins (Nt). Default is 32.

Returns

Wavelet

A Wavelet object representing the transformed wavelet-domain data.

Warnings

There can be significant leakage if mult is too small. The transform is only approximately exact if mult = Nt / 2.

Notes

The function warns when the mult value is too large, potentially leading to inaccurate results.

pywavelet.transforms.from_freq_to_wavelet(freqseries: FrequencySeries, Nf: int | None = None, Nt: int | None = None, nx: float = 4.0) → Wavelet

Transform frequency-domain data to wavelet-domain data.

This function performs a forward wavelet transform, converting a frequency-domain signal into a wavelet-domain representation.

Parameters

freqseriesFrequencySeries

Input frequency-domain data, represented as a FrequencySeries object.

Nfint, optional

Number of frequency bins for the wavelet transform. Default is None.

Ntint, optional

Number of time bins for the wavelet transform. Default is None.

nxfloat, optional

Number of standard deviations for the phi_vec, controlling the width of the wavelets. Default is 4.0.

Returns

Wavelet

A Wavelet object representing the transformed wavelet-domain data.

Notes

The function normalizes the wavelet-domain data to ensure consistency during the transformation process.

pywavelet.transforms.from_wavelet_to_freq(wave_in: Wavelet, dt: float, nx: float = 4.0) → FrequencySeries

Perform an inverse wavelet transform to the frequency domain.

This function converts a wavelet-domain signal into a frequency-domain signal using the inverse wavelet transform algorithm.

Parameters

wave_inWavelet

Input wavelet, represented by a Wavelet object.

dtfloat

Time step of the wavelet data.

nxfloat, optional

Scaling parameter for the phi vector used in the transformation. Default is 4.0.

Returns

FrequencySeries

A FrequencySeries object containing the signal transformed into the frequency domain.

Notes

The transformation involves normalizing the output by the square root of 2 to ensure the proper backwards transformation.

pywavelet.transforms.from_wavelet_to_time(wave_in: Wavelet, dt: float, nx: float = 4.0, mult: int = 32) → TimeSeries

Perform an inverse wavelet transform to the time domain.

This function converts a wavelet-domain signal to a time-domain signal using the inverse wavelet transform algorithm.

Parameters

wave_inWavelet

Input wavelet, represented by a Wavelet object.

dtfloat

Time step of the wavelet data.

nxfloat, optional

Scaling parameter for the phi vector used in the transformation. Default is 4.0.

multint, optional

Multiplier parameter for the phi vector. Ensures that the mult value is not larger than half the number of time bins (wave_in.Nt). Default is 32.

Returns

TimeSeries

A TimeSeries object containing the signal transformed into the time domain.

Notes

The transformation involves normalizing the output by the square root of 2 to ensure the proper backwards transformation.

Types

class pywavelet.types.TimeSeries(data: ndarray, time: ndarray)

A class to represent a time series, with methods for plotting and converting the series to a frequency-domain representation.

Attributes

dataxp.ndarray

Time domain data.

timexp.ndarray

Array of corresponding time points.

property ND: int

Return the number of data points in the time series.

copy()

property dt: float

Return the time resolution (Δt).

property duration: float

Return the duration of the time series in seconds.

property fs: float

Return the sample rate (fs).

highpass_filter(fmin: float, tukey_window_alpha: float = 0.0, bandpass_order: int = 4) → TimeSeries

Filter the time series with a highpass bandpass filter.

(we use sosfiltfilt instead of filtfilt for numerical stability)

Note: filtfilt should be used if phase accuracy (zero-phase filtering) is critical for your analysis and if the filter order is low to moderate.

Parameters

fminfloat

Minimum frequency to pass through the filter.

bandpass_orderint, optional

Order of the bandpass filter. Default is 4.

Returns

TimeSeries

A new TimeSeries object with the highpass filter applied.

property nyquist_frequency: float

Return the Nyquist frequency (fs/2).

plot(ax=None, **kwargs) → Tuple[Figure, Axes]

Custom method.

plot_spectrogram(ax=None, spec_kwargs={}, plot_kwargs={}) → Tuple[Figure, Axes]

property sample_rate: float

Return the sample rate (fs).

The sample rate is the inverse of the time resolution (Δt).

property shape: Tuple[int, ...]

Return the shape of the data array.

property t0: float

Return the initial time point in the series.

property tend: float

Return the final time point in the series.

to_frequencyseries() → FrequencySeries

Convert the time series to a frequency series using the one-sided FFT.

Returns

FrequencySeries

The frequency-domain representation of the time series.

to_wavelet(Nf: int | None = None, Nt: int | None = None, nx: float | None = 4.0) → Wavelet

Convert the time series to a wavelet representation.

Parameters

Nfint

Number of frequency bins for the wavelet transform.

Ntint

Number of time bins for the wavelet transform.

nxfloat, optional

Number of standard deviations for the phi_vec, controlling the width of the wavelets. Default is 4.0.

Returns

Wavelet

The wavelet-domain representation of the time series.

truncate(tmin: float, tmax: float) → TimeSeries

Truncate the time series to the specified time range.

Parameters

tminfloat

Minimum time to keep in the series.

tmaxfloat

Maximum time to keep in the series.

Returns

TimeSeries

A new TimeSeries object truncated to the specified time range.

zero_pad_to_power_of_2(tukey_window_alpha: float = 0.0) → TimeSeries

Zero pad the time series to make the length a power of two (useful to speed up FFTs, O(NlogN) versus O(N^2)).

Parameters

tukey_window_alphafloat, optional

Alpha parameter for the Tukey window. Default is 0.0. (prevents spectral leakage when padding the data)

Returns

TimeSeries

A new TimeSeries object with the data zero-padded to a power of two.

class pywavelet.types.FrequencySeries(data: ndarray, freq: ndarray, t0: float = 0)

A class to represent a one-sided frequency series, with various methods for plotting and converting the series to a time-domain representation.

Attributes

dataxp.ndarray

Frequency domain data.

freqxp.ndarray

Corresponding frequencies (must be non-negative).

property ND: int

Return the number of data points in the time domain signal.

copy()

property df: float

Return the frequency resolution (Δf).

property dt: float

Return the time resolution (Δt).

property duration: float

Return the duration of the time domain signal.

property fs: float

Return the sample rate (fs).

matched_filter_snr(other: FrequencySeries, psd: FrequencySeries) → float

Compute the signal-to-noise ratio (SNR) of a matched filter.

Parameters

otherFrequencySeries

The other FrequencySeries.

psdFrequencySeries

The power spectral density (PSD) of the noise.

Returns

float

The SNR of the matched filter.

property maximum_frequency: float

Return the maximum frequency in the frequency series.

property minimum_frequency: float

Return the minimum frequency in the frequency series.

noise_weighted_inner_product(other: FrequencySeries, psd: FrequencySeries) → float

Compute the noise-weighted inner product of two FrequencySeries.

Parameters

otherFrequencySeries

The other FrequencySeries.

psdFrequencySeries

The power spectral density (PSD) of the noise.

Returns

float

The noise-weighted inner product of the two FrequencySeries.

property nyquist_frequency: float

Return the Nyquist frequency (fs/2).

optimal_snr(psd: FrequencySeries) → float

Compute the optimal signal-to-noise ratio (SNR) of a FrequencySeries.

Parameters

psdFrequencySeries

The power spectral density (PSD) of the noise.

Returns

float

The optimal SNR of the FrequencySeries.

property periodogram

plot(ax=None, **kwargs) → Tuple[Figure, Axes]

plot_periodogram(ax=None, **kwargs) → Tuple[Figure, Axes]

property range: Tuple[float, float]

Return the frequency range (minimum and maximum frequencies).

property sample_rate: float

Return the sample rate (fs).

property shape: Tuple[int, ...]

Return the shape of the data array.

to_timeseries() → TimeSeries

Convert the frequency series to a time series using inverse Fourier transform.

Returns

TimeSeries

The corresponding time domain signal.

to_wavelet(Nf: int | None = None, Nt: int | None = None, nx: float | None = 4.0) → Wavelet

Convert the frequency series to a wavelet using inverse Fourier transform.

Returns

Wavelet

The corresponding wavelet.

class pywavelet.types.Wavelet(data: ndarray, time: ndarray, freq: ndarray)

A class to represent a wavelet transform result, with methods for plotting and accessing key properties like duration, sample rate, and grid size.

Attributes

dataxp.ndarray

2D array representing the wavelet coefficients (frequency x time).

timexp.ndarray

Array of time points.

freqxp.ndarray

Array of corresponding frequency points.

property ND: int

Total number of data points in the wavelet grid.

Returns

int

The product of Nt and Nf.

property Nf: int

Number of frequency bins.

Returns

int

Length of the frequency array.

property Nt: int

Number of time bins.

Returns

int

Length of the time array.

copy()

property delta_F: float

Frequency resolution (ΔF) of the wavelet grid.

Returns

float

Inverse of twice the time resolution.

property delta_T: float

Time resolution (ΔT) of the wavelet grid.

Returns

float

Difference between consecutive time points.

property delta_f: float

Frequency resolution of the wavelet grid, normalized by the total number of data points.

Returns

float

Frequency resolution per data point.

property delta_t: float

Time resolution of the wavelet grid, normalized by the total number of data points.

Returns

float

Time resolution per data point.

property duration: float

Duration of the wavelet grid.

Returns

float

Total duration in seconds.

property fs: float

Sample rate (fs) of the wavelet grid.

Returns

float

The sample rate.

matched_filter_snr(template: Wavelet, psd: Wavelet) → float

Compute the matched filter SNR of the wavelet grid given a template.

Parameters

templateWavelet

A Wavelet object representing the template.

Returns

float

The matched filter signal-to-noise ratio.

noise_weighted_inner_product(other: Wavelet, psd: Wavelet) → float

Compute the noise-weighted inner product of two wavelet grids given a PSD.

Parameters

otherWavelet

A Wavelet object representing the other wavelet grid.

psdWavelet

A Wavelet object representing the power spectral density.

Returns

float

The noise-weighted inner product.

property nyquist_frequency: float

Nyquist frequency of the wavelet grid.

Returns

float

Nyquist frequency, which is half of the sample rate.

optimal_snr(psd: Wavelet) → float

Compute the optimal SNR of the wavelet grid given a PSD.

Parameters

psdWavelet

A Wavelet object representing the power spectral density.

Returns

float

The optimal signal-to-noise ratio.

plot(ax=None, *args, **kwargs) → Tuple[Figure, Axes]

Plot a 2D grid of wavelet coefficients.

Parameters

wavelet_datanp.ndarray

A 2D array containing the wavelet coefficients with shape (Nf, Nt), where Nf is the number of frequency bins and Nt is the number of time bins.

time_gridnp.ndarray, optional

1D array of time values corresponding to the time bins. If None, uses np.arange(Nt).

freq_gridnp.ndarray, optional

1D array of frequency values corresponding to the frequency bins. If None, uses np.arange(Nf).

axplt.Axes, optional

Matplotlib Axes object to plot on. If None, creates a new figure and axes.

zscalestr, optional

Scale for the color mapping. Options are ‘linear’ or ‘log’. Default is ‘linear’.

freq_scalestr, optional

Scale for the frequency axis. Options are ‘linear’ or ‘log’. Default is ‘linear’.

absolutebool, optional

If True, plots the absolute value of the wavelet coefficients. Default is False.

freq_rangetuple of float, optional

Tuple specifying the (min, max) frequency range to display. If None, displays the full range.

show_colorbarbool, optional

If True, displays a colorbar next to the plot. Default is True.

cmapstr, optional

Colormap to use for the plot. If None, uses ‘viridis’ for absolute values or ‘bwr’ for signed values.

normmatplotlib.colors.Normalize, optional

Normalization instance to scale data values. If None, a suitable normalization is chosen based on zscale.

cbar_labelstr, optional

Label for the colorbar. If None, a default label is used based on the absolute parameter.

nan_colorstr, optional

Color to use for NaN values. Default is ‘black’.

trend_colorbool, optional

Color to use for the trend line. Not shown if None.

**kwargs

Additional keyword arguments passed to ax.imshow().

Returns

Tuple[plt.Figure, plt.Axes]

The figure and axes objects of the plot.

Raises

ValueError

If the dimensions of wavelet_data do not match the lengths of freq_grid and time_grid.

plot_trend(ax=None, *args, **kwargs) → Tuple[Figure, Axes]

property sample_rate: float

Sample rate of the wavelet grid.

Returns

float

Sample rate calculated as the inverse of the time resolution.

property shape: Tuple[int, int]

Shape of the wavelet grid.

Returns

Tuple[int, int]

Tuple representing the shape of the data array (Nf, Nt).

property t0: float

Initial time point of the wavelet grid.

Returns

float

First time point in the time array.

property tend: float

Final time point of the wavelet grid.

Returns

float

Last time point in the time array.

to_frequencyseries(nx: float = 4.0) → FrequencySeries

Convert the wavelet grid to a frequency-domain signal.

Returns

FrequencySeries

A FrequencySeries object representing the frequency-domain signal.

to_timeseries(nx: float = 4.0, mult: int = 32) → TimeSeries

Convert the wavelet grid to a time-domain signal.

Returns

TimeSeries

A TimeSeries object representing the time-domain signal.

classmethod zeros(Nf: int, Nt: int, T: float) → Wavelet

Create a Wavelet object filled with zeros.

Parameters

Nfint

Number of frequency bins.

Ntint

Number of time bins.

Returns

Wavelet

A Wavelet object with zero-filled data array.

classmethod zeros_from_grid(time: ndarray, freq: ndarray) → Wavelet

Create a Wavelet object filled with zeros.

Parameters

time: xp.ndarray freq: xp.ndarray

Returns

Wavelet

A Wavelet object with zero-filled data array.