0
# PyWavelets
1

2
A comprehensive Python library for wavelet transforms providing discrete and continuous wavelet analysis for signal and image processing. PyWavelets offers extensive functionality including 1D, 2D, and nD transforms, multilevel decomposition, stationary wavelets, continuous wavelet transforms, and wavelet packet analysis with over 100 built-in wavelet filters.
3

4
## Package Information
5

6
- **Package Name**: PyWavelets
7
- **Language**: Python
8
- **Installation**: `pip install PyWavelets`
9

10
## Core Imports
11

12
```python
13
import pywt
14
```
15

16
Common pattern for specific functions:
17

18
```python
19
from pywt import dwt, idwt, wavedec, waverec
20
```
21

22
## Basic Usage
23

24
```python
25
import pywt
26
import numpy as np
27

28
# Create test signal
29
data = np.sin(np.linspace(0, 4*np.pi, 100))
30

31
# Single-level discrete wavelet transform
32
coeffs = pywt.dwt(data, 'db4')
33
cA, cD = coeffs  # approximation and detail coefficients
34

35
# Reconstruct signal
36
reconstructed = pywt.idwt(cA, cD, 'db4')
37

38
# Multi-level wavelet decomposition
39
coeffs = pywt.wavedec(data, 'db4', level=3)
40
# coeffs = [cA3, cD3, cD2, cD1] - approximation + details
41

42
# Reconstruct from multi-level coefficients
43
reconstructed = pywt.waverec(coeffs, 'db4')
44

45
# 2D transform for images
46
import matplotlib.pyplot as plt
47

48
# Create sample 2D data
49
image = np.random.random((64, 64))
50

51
# 2D wavelet transform
52
coeffs2d = pywt.dwt2(image, 'db4')
53
cA, (cH, cV, cD) = coeffs2d
54

55
# Reconstruct
56
reconstructed2d = pywt.idwt2(coeffs2d, 'db4')
57
```
58

59
## Architecture
60

61
PyWavelets is built around several key components:
62

63
- **Wavelet Objects**: Core classes representing discrete and continuous wavelets with filter coefficients and properties
64
- **Transform Functions**: Hierarchical transform capabilities from single-level to multilevel, 1D to nD
65
- **Coefficient Utilities**: Tools for manipulating and converting coefficient representations
66
- **Extension Modes**: Signal boundary handling for finite-length signals
67
- **Thresholding**: Signal denoising and feature extraction capabilities
68

69
The library follows a consistent API pattern where transform functions take data, wavelet specification, mode, and dimensional parameters, returning coefficient tuples or arrays that can be directly used for reconstruction.
70

71
## Capabilities
72

73
### Wavelet Objects and Utilities
74

75
Core wavelet objects, available wavelets, and utility functions for wavelet analysis including frequency analysis and filter bank operations.
76

77
```python { .api }
78
class Wavelet:
79
    def __init__(self, name: str, filter_bank=None): ...
80
    def wavefun(self, level: int = 8): ...
81

82
class ContinuousWavelet:
83
    def __init__(self, name: str, dtype=np.float64): ...
84
    def wavefun(self, level: int = 8, length=None): ...
85

86
def wavelist(family: str = None, kind: str = 'all') -> list: ...
87
def families(short: bool = True) -> list: ...
88
```
89

90
[Wavelet Objects and Utilities](./wavelets.md)
91

92
### Single-Level Discrete Wavelet Transform
93

94
Single-level forward and inverse discrete wavelet transforms for 1D, 2D, and nD data with complete coefficient decomposition.
95

96
```python { .api }
97
def dwt(data, wavelet, mode: str = 'symmetric', axis: int = -1): ...
98
def idwt(cA, cD, wavelet, mode: str = 'symmetric', axis: int = -1): ...
99
def dwt2(data, wavelet, mode: str = 'symmetric', axes=(-2, -1)): ...
100
def idwt2(coeffs, wavelet, mode: str = 'symmetric', axes=(-2, -1)): ...
101
def dwtn(data, wavelet, mode: str = 'symmetric', axes=None): ...
102
def idwtn(coeffs, wavelet, mode: str = 'symmetric', axes=None): ...
103
def dwt_max_level(data_len: int, filter_len: int) -> int: ...
104
def dwt_coeff_len(data_len: int, filter_len: int, mode: str) -> int: ...
105
def dwtn_max_level(shape: tuple, wavelet, axes=None) -> int: ...
106
def downcoef(part: str, data, wavelet, mode: str = 'symmetric', level: int = 1): ...
107
def upcoef(part: str, coeffs, wavelet, level: int = 1, take: int = 0): ...
108
def pad(x, pad_widths, mode: str): ...
109
```
110

111
[Single-Level DWT](./single-level-dwt.md)
112

113
### Multi-Level Discrete Wavelet Transform
114

115
Multi-level wavelet decomposition and reconstruction providing hierarchical analysis with automatic or specified decomposition levels. Includes fully separable transforms for axis-specific decomposition control.
116

117
```python { .api }
118
def wavedec(data, wavelet, mode: str = 'symmetric', level: int = None, axis: int = -1): ...
119
def waverec(coeffs, wavelet, mode: str = 'symmetric', axis: int = -1): ...
120
def wavedec2(data, wavelet, mode: str = 'symmetric', level: int = None, axes=(-2, -1)): ...
121
def waverec2(coeffs, wavelet, mode: str = 'symmetric', axes=(-2, -1)): ...
122
def wavedecn(data, wavelet, mode: str = 'symmetric', level: int = None, axes=None): ...
123
def waverecn(coeffs, wavelet, mode: str = 'symmetric', axes=None): ...
124
def fswavedecn(data, wavelet, mode: str = 'symmetric', levels=None, axes=None): ...
125
def fswaverecn(fswavedecn_result): ...
126
```
127

128
[Multi-Level DWT](./multi-level-dwt.md)
129

130
### Stationary Wavelet Transform
131

132
Stationary (undecimated) wavelet transforms providing translation-invariant analysis with no downsampling, preserving all frequency information.
133

134
```python { .api }
135
def swt(data, wavelet, level: int = None, start_level: int = 0, axis: int = -1, 
136
        trim_approx: bool = False, norm: bool = False): ...
137
def iswt(coeffs, wavelet, norm: bool = False, axis: int = -1): ...
138
def swt2(data, wavelet, level: int, start_level: int = 0, axes=(-2, -1), 
139
         trim_approx: bool = False, norm: bool = False): ...
140
def iswt2(coeffs, wavelet, norm: bool = False, axes=(-2, -1)): ...
141
```
142

143
[Stationary Wavelet Transform](./stationary-dwt.md)
144

145
### Continuous Wavelet Transform
146

147
Continuous wavelet transform for time-frequency analysis providing detailed spectral analysis with adjustable time-frequency resolution.
148

149
```python { .api }
150
def cwt(data, scales, wavelet, sampling_period: float = 1.0, 
151
        method: str = 'conv', axis: int = -1, *, precision: int = 12): ...
152
def next_fast_len(n: int) -> int: ...
153
```
154

155
[Continuous Wavelet Transform](./continuous-dwt.md)
156

157
### Wavelet Packet Transform
158

159
Wavelet packet decomposition providing complete binary tree analysis for detailed frequency localization and adaptive basis selection.
160

161
```python { .api }
162
class WaveletPacket:
163
    def __init__(self, data, wavelet, mode: str = 'symmetric', maxlevel=None): ...
164
    def decompose(self): ...
165
    def reconstruct(self, update: bool = False): ...
166

167
class WaveletPacket2D:
168
    def __init__(self, data, wavelet, mode: str = 'symmetric', maxlevel=None): ...
169

170
def get_graycode_order(level: int, x: str = 'a', y: str = 'd') -> list: ...
171
```
172

173
[Wavelet Packet Transform](./wavelet-packets.md)
174

175
### Coefficient Manipulation
176

177
Utilities for converting between different coefficient representations, packing/unpacking coefficients, and working with coefficient arrays.
178

179
```python { .api }
180
def coeffs_to_array(coeffs, padding: int = 0, axes=None): ...
181
def array_to_coeffs(arr, coeff_slices, output_format: str = 'wavedecn'): ...
182
def ravel_coeffs(coeffs, axes=None): ...
183
def unravel_coeffs(arr, coeff_slices, coeff_shapes, output_format: str = 'wavedecn'): ...
184
```
185

186
[Coefficient Manipulation](./coefficient-utils.md)
187

188
### Thresholding and Denoising
189

190
Signal thresholding functions for noise reduction, feature extraction, and signal enhancement with various thresholding methods.
191

192
```python { .api }
193
def threshold(data, value, mode: str = 'soft', substitute: float = 0): ...
194
def threshold_firm(data, value_low, value_high): ...
195
```
196

197
[Thresholding and Denoising](./thresholding.md)
198

199
### Multiresolution Analysis
200

201
Multiresolution analysis providing direct access to approximation components at each decomposition level for signal analysis and reconstruction.
202

203
```python { .api }
204
def mra(data, wavelet, level: int = None, axis: int = -1, 
205
        transform: str = 'swt', mode: str = 'periodization'): ...
206
def imra(mra_coeffs): ...
207
```
208

209
[Multiresolution Analysis](./multiresolution-analysis.md)
210

211
### Sample Data
212

213
Test datasets and demo signals for experimentation and learning with various data types including images and time series.
214

215
```python { .api }
216
def pywt.data.aero(): ...
217
def pywt.data.ascent(): ...
218
def pywt.data.camera(): ...
219
def pywt.data.ecg(): ...
220
def pywt.data.nino(): ...
221
def demo_signal(name: str, n: int = None): ...
222
```
223

224
The data module provides built-in test datasets including 512x512 grayscale images (aero, ascent, camera), physiological signals (ecg), climate data (nino), and various synthetic test signals through demo_signal().
225

226
## Types
227

228
```python { .api }
229
# Wavelet specification can be:
230
# - str: wavelet name ('db4', 'haar', 'sym8', etc.)
231
# - Wavelet: Wavelet object
232
# - ContinuousWavelet: Continuous wavelet object
233

234
# Extension modes for boundary handling
235
Mode = Literal[
236
    'zero', 'constant', 'symmetric', 'periodic', 
237
    'smooth', 'periodization', 'reflect', 
238
    'antisymmetric', 'antireflect'
239
]
240

241
# Common coefficient formats
242
CoeffsFormat1D = Tuple[np.ndarray, np.ndarray]  # (cA, cD)
243
CoeffsFormat2D = Tuple[np.ndarray, Tuple[np.ndarray, np.ndarray, np.ndarray]]  # (cA, (cH, cV, cD))
244
CoeffsFormatND = Dict[str, np.ndarray]  # {'aa': cA, 'ad': cH, 'da': cV, 'dd': cD, ...}
245

246
# Multi-level coefficient formats
247
MultiLevelCoeffs1D = List[np.ndarray]  # [cAn, cDn, ..., cD1]
248
MultiLevelCoeffs2D = List[Union[np.ndarray, Tuple[np.ndarray, np.ndarray, np.ndarray]]]
249
MultiLevelCoeffsND = List[Union[np.ndarray, Dict[str, np.ndarray]]]
250
```