DOCSEARCHbyAlgolia
Submit Docs

PyWavelets Documentation

repository·main·Indexed 25 days ago

https://github.com/pywavelets/pywt

PyWavelets is a Python library for computational harmonic analysis using wavelets, providing tools for n-dimensional Discrete Wavelet Transforms (DWT), 1D Continuous Wavelet Transform (CWT), and Wavelet Packet decomposition. Compatible with Matlab's Wavelet Toolbox, it supports real and complex-valued data and allows for custom wavelet filter banks. The library utilizes C and Cython for high-performance up/downsampling convolutions.

Tokens
14.3K
Snippets
31
Records
121
Agent score
81%

What's inside PyWavelets

  1. What is PyWavelets

    main

    PyWavelets is an Open Source library for wavelet transforms in Python. It provides tools for time-frequency analysis using wavelets, which are mathematical basis functions localized in both time and frequency.

    Key features include:

    • 1D, 2D, and nD Forward and Inverse Discrete Wavelet Transform (DWT and IDWT).
    • Multilevel DWT and IDWT (1D, 2D, and nD).
    • 1D and 2D Stationary Wavelet Transform (Undecimated Wavelet Transform).
    • 1D and 2D Wavelet Packet decomposition and reconstruction.
    • 1D Continuous Wavelet Transform.
    • Computing approximations of wavelet and scaling functions.
    • Support for over 100 built-in wavelet filters and custom wavelets.
    • Support for single/double precision and real/complex calculations.
    • Compatibility with Matlab Wavelet Toolbox (TM) results.

  2. Overview of PyWavelets capabilities

    main

    PyWavelets is a Python package designed for computational harmonic analysis using wavelets. It provides implementations for:

    • n-dimensional Discrete Wavelet Transforms (DWT): Supports dimensions $n > 3$.
    • 1D Continuous Wavelet Transform (CWT).
    • Custom Wavelet Filter Banks: Users can specify their own filters.
    • High-performance computing: Core up/downsampling convolutions are implemented in C, with Cython used to wrap these routines for axis-specific 1D transformations.
    • Flexible Data Support: Supports both real and complex-valued data in single or double precision.
    • Advanced Transformation Control: Allows transforming only a subset of axes and varying the wavelet and signal boundary extension mode on a per-axis basis.

    The API is designed to be similar to Matlab's wavelet toolbox, making it familiar to users transitioning from that environment.

  3. Main features of PyWavelets

    main

    PyWavelets is a comprehensive library for wavelet analysis in Python, supporting:

    • Discrete Wavelet Transform (DWT and IDWT): 1D, 2D, and nD forward and inverse transforms.
    • Multilevel DWT/IDWT: 1D, 2D, and nD multilevel decomposition.
    • Stationary Wavelet Transform (Undecimated Wavelet Transform): 1D, 2D, and nD.
    • Wavelet Packet decomposition: 1D and 2D decomposition and reconstruction.
    • Continuous Wavelet Transform (CWT): 1D implementation.
    • Function Approximations: Computing approximations of wavelet and scaling functions.
    • Wavelet Support: Over 100 built-in wavelet filters and support for custom wavelets.
    • Precision & Types: Single and double precision; real and complex calculations.
    • Compatibility: Results are compatible with the Matlab Wavelet Toolbox (TM).

  4. Use thresholding functions in pywt.thresholding

    main

    The pywt.thresholding module provides implementations of common signal thresholding functions used to reduce noise or extract features from wavelet coefficients.

    Key functions include:

    • threshold: Performs standard thresholding (e.g., hard or soft thresholding).
    • threshold_firm: Performs firm thresholding, which provides a transition between soft and hard thresholding behavior. This function requires a pair of threshold values that define the width of the transition region.

  5. Explore the PyWavelets API Reference

    main

    The PyWavelets API is organized into several functional modules covering wavelet theory and signal processing. Key areas of functionality include:

    • Wavelet Definitions: Accessing wavelet families and properties via wavelets.
    • Transforms: Performing Discrete Wavelet Transforms (dwt, idwt), 2D decompositions, N-dimensional transforms (nd-dwt-and-idwt), and Stationary Wavelet Transforms (swt, iswt).
    • Advanced Analysis: Multi-resolution analysis (mra), Wavelet Packets, and Continuous Wavelet Transforms (cwt).
    • Signal Processing: Handling wavelet coefficients, applying thresholding functions, and managing signal extension modes.

  6. Perform Wavelet Packet Transform

    main

    Unlike the standard DWT which only decomposes the approximation subband, the Wavelet Packet Transform applies additional levels of decomposition to all wavelet subbands from the first level. This allows for a wide variety of potential wavelet packet bases by choosing which subsets of decompositions to perform.

    For 2D wavelet packets, you can use the pywt.WaveletPacket2D class. Note that coefficients can be rearranged into 'frequency' ordering using the .get_level() method.

  8. Avoid mixing `Modes.periodization` with other extension modes

    main
    The periodization mode is designed to produce coefficient arrays that are exactly half the length of the input data. However, this mode is distinct from others. Do not mix periodization during dwt with a different mode (like symmetric) during idwt, as this will produce invalid results.

  9. Traverse the 2D Wavelet Packet tree

    main

    Nodes in a WaveletPacket2D tree are Node2D objects identified by path strings. Because each node has four children, the subnode naming follows the dwt2 convention:

    • 'a': LL (low-low) coefficients
    • 'h': LH (low-high) coefficients
    • 'v': HL (high-low) coefficients
    • 'd': HH (high-high) coefficients

    You can access nodes using the indexing operator obj[path]. Paths can be compound (e.g., 'aa', 'av') to traverse deeper into the tree.

    Errors:

    • IndexError: Raised if the path length exceeds maxlevel.
    • ValueError: Raised if the subnode name is not one of ['a', 'h', 'v', 'd'].
    import pywt
import numpy

x = numpy.array([[1, 2, 3, 4, 5, 6, 7, 8]] * 8, 'd')
wp = pywt.WaveletPacket2D(data=x, wavelet='db1', mode='symmetric')

# Accessing first level nodes
print(wp['a'].data)
print(wp['h'].data)

# Accessing subnodes (compound paths)
print(wp['aa'].data)

# Accessing via node object
node = wp['a']
print(node['a'].data)

  10. How Wavelet Packet structures are organized

    main

    PyWavelets uses a hierarchical tree structure for wavelet packet transforms. The architecture is based on a node-based inheritance scheme where different dimensionality (1D, 2D, ND) is handled by specific classes, all sharing a common interface via BaseNode.

    The Inheritance Hierarchy

    • BaseNode: The common interface for all nodes and wavelet packet roots.
      • Node (1D): Data carrier in a 1D binary tree. Rooted by WaveletPacket.
      • Node2D (2D): Data carrier in a 2D quad-tree. Rooted by WaveletPacket2D.
      • NodeND (ND): Data carrier in an ND $2^N$-ary tree. Rooted by WaveletPacketND.

    Dimensionality and Axes

    • 1D/2D classes: Apply transforms along only 1 or 2 specific dimensions.
    • ND classes: Allow transforms over an arbitrary number of axes of n-dimensional data.
    • All wavelet packet objects can operate on general n-dimensional arrays, but the scope of the transform is determined by the class type.

  11. Perform Multilevel Discrete Wavelet Transform (Mallat decomposition)

    main

    The most common multilevel decomposition approach decomposes only the approximation subband (the lowpass subband) at each subsequent level. In 2D, this produces four sets of coefficients representing the combinations of filters over the two axes. In $n$ dimensions, it produces $2^n$ sets of coefficients.

    Use pywt.wavedecn for $n$-dimensional data decomposition and pywt.waverecn for the inverse transform. Specific 1D and 2D versions of these routines are also available.

  12. How scales and frequencies relate in CWT

    main

    In the Continuous Wavelet Transform, the scale determines the width of the wavelet.

    • Scale = 1: Corresponds to the natural extent of the wavelet (the range [wavelet.lower_bound, wavelet.upper_bound]).
    • Larger Scales: The wavelet is stretched, making it sensitive to lower frequencies.
    • Sampling and Aliasing: If a scale is too low, the wavelet may be inadequately sampled by the discrete signal, leading to aliasing (violation of the Nyquist limit).
    • Center Frequency: For wavelets like cmor, fbsp, and shan, a normalized center frequency of 1.0 corresponds to $1/dt$ (the sampling frequency). For a signal sampled at 100 Hz, a center frequency of 1.0 at scale=1 is 100 Hz, which is above the Nyquist rate (50 Hz), requiring scales >= 2 for valid analysis.