0
# Wavelet Objects and Utilities
1

2
Core wavelet objects, discovery functions, and utility functions for wavelet analysis including frequency analysis and filter bank operations.
3

4
## Capabilities
5

6
### Wavelet Discovery
7

8
Functions to explore available wavelets and families supported by PyWavelets.
9

10
```python { .api }
11
def wavelist(family: str = None, kind: str = 'all') -> list:
12
    """
13
    List available wavelets.
14
    
15
    Parameters:
16
    - family: Wavelet family ('haar', 'db', 'sym', 'coif', 'bior', 'rbio', 'dmey', 'gaus', 'mexh', 'morl', 'cgau', 'shan', 'fbsp', 'cmor') or None for all families
17
    - kind: Type of wavelets ('all', 'continuous', 'discrete')
18
    
19
    Returns:
20
    List of available wavelet names
21
    """
22

23
def families(short: bool = True) -> list:
24
    """
25
    List available wavelet families.
26
    
27
    Parameters:
28
    - short: Return short family names if True, long names if False
29
    
30
    Returns:
31
    List of wavelet family names
32
    """
33
```
34

35
#### Usage Examples
36

37
```python
38
import pywt
39

40
# List all available wavelets
41
all_wavelets = pywt.wavelist()
42
print(f"Total wavelets: {len(all_wavelets)}")
43

44
# List Daubechies wavelets
45
db_wavelets = pywt.wavelist('db')
46
print(f"Daubechies wavelets: {db_wavelets}")
47

48
# List only continuous wavelets
49
continuous = pywt.wavelist(kind='continuous')
50
print(f"Continuous wavelets: {continuous}")
51

52
# List wavelet families
53
families = pywt.families()
54
print(f"Wavelet families: {families}")
55
```
56

57
### Discrete Wavelet Objects
58

59
The primary class for working with discrete wavelets, providing access to filter coefficients and wavelet properties.
60

61
```python { .api }
62
class Wavelet:
63
    def __init__(self, name: str, filter_bank=None):
64
        """
65
        Discrete wavelet object.
66
        
67
        Parameters:
68
        - name: Wavelet name ('haar', 'db1', 'db2', ..., 'db45', 'sym2', ..., 'sym20', etc.)
69
        - filter_bank: Custom filter bank as (dec_lo, dec_hi, rec_lo, rec_hi) tuple
70
        """
71
    
72
    # Properties
73
    name: str  # Wavelet name
74
    family_name: str  # Full family name
75
    short_family_name: str  # Short family name
76
    dec_lo: np.ndarray  # Decomposition low-pass filter
77
    dec_hi: np.ndarray  # Decomposition high-pass filter  
78
    rec_lo: np.ndarray  # Reconstruction low-pass filter
79
    rec_hi: np.ndarray  # Reconstruction high-pass filter
80
    dec_len: int  # Decomposition filter length
81
    rec_len: int  # Reconstruction filter length
82
    orthogonal: bool  # True if orthogonal wavelet
83
    biorthogonal: bool  # True if biorthogonal wavelet
84
    symmetry: str  # Symmetry type ('asymmetric', 'near symmetric', 'symmetric')
85
    vanishing_moments_psi: int  # Vanishing moments of wavelet function
86
    vanishing_moments_phi: int  # Vanishing moments of scaling function
87
    filter_bank: tuple  # (dec_lo, dec_hi, rec_lo, rec_hi)
88
    inverse_filter_bank: tuple  # Inverse filter bank
89
    
90
    def wavefun(self, level: int = 8):
91
        """
92
        Compute wavelet and scaling functions.
93
        
94
        Parameters:
95
        - level: Decomposition level (higher = more detailed)
96
        
97
        Returns:
98
        For orthogonal wavelets: (psi, x) - wavelet function and x coordinates
99
        For biorthogonal wavelets: (psi_d, psi_r, x) - decomposition and reconstruction wavelets with x coordinates
100
        For scaling functions: (phi, psi, x) or (phi_d, psi_d, phi_r, psi_r, x)
101
        """
102
```
103

104
#### Usage Examples
105

106
```python
107
import pywt
108
import numpy as np
109
import matplotlib.pyplot as plt
110

111
# Create Daubechies-4 wavelet
112
db4 = pywt.Wavelet('db4')
113
print(f"Name: {db4.name}")
114
print(f"Family: {db4.family_name}")
115
print(f"Orthogonal: {db4.orthogonal}")
116
print(f"Filter length: {db4.dec_len}")
117
print(f"Vanishing moments: {db4.vanishing_moments_psi}")
118

119
# Access filter coefficients
120
print(f"Low-pass filter: {db4.dec_lo}")
121
print(f"High-pass filter: {db4.dec_hi}")
122

123
# Compute and plot wavelet function
124
phi, psi, x = db4.wavefun(level=8)
125
plt.figure(figsize=(12, 4))
126
plt.subplot(1, 2, 1)
127
plt.plot(x, phi)
128
plt.title('Scaling function (φ)')
129
plt.subplot(1, 2, 2)  
130
plt.plot(x, psi)
131
plt.title('Wavelet function (ψ)')
132
plt.show()
133

134
# Biorthogonal wavelet example
135
bior = pywt.Wavelet('bior2.2')
136
phi_d, psi_d, phi_r, psi_r, x = bior.wavefun()
137
print(f"Biorthogonal: {bior.biorthogonal}")
138
```
139

140
### Continuous Wavelet Objects
141

142
Class for continuous wavelets used in continuous wavelet transforms (CWT).
143

144
```python { .api }
145
class ContinuousWavelet:
146
    def __init__(self, name: str, dtype=np.float64):
147
        """
148
        Continuous wavelet object.
149
        
150
        Parameters:
151
        - name: Continuous wavelet name ('gaus1'-'gaus8', 'mexh', 'morl', 'cgau1'-'cgau8', 'shan', 'fbsp', 'cmor')
152
        - dtype: Data type for computations
153
        """
154
    
155
    # Properties  
156
    name: str  # Wavelet name
157
    family_name: str  # Full family name
158
    short_family_name: str  # Short family name
159
    complex_cwt: bool  # True if CWT produces complex output
160
    lower_bound: float  # Lower support bound
161
    upper_bound: float  # Upper support bound  
162
    center_frequency: float  # Center frequency
163
    bandwidth_frequency: float  # Bandwidth frequency
164
    fbsp_order: int  # B-spline order (for 'fbsp' wavelets)
165
    
166
    def wavefun(self, level: int = 8, length: int = None):
167
        """
168
        Compute continuous wavelet function.
169
        
170
        Parameters:
171
        - level: Resolution level
172
        - length: Length of the wavelet function
173
        
174
        Returns:
175
        (psi, x) - wavelet function values and x coordinates
176
        """
177
```
178

179
#### Usage Examples
180

181
```python
182
import pywt
183
import numpy as np
184
import matplotlib.pyplot as plt
185

186
# Mexican hat wavelet
187
mexh = pywt.ContinuousWavelet('mexh')
188
print(f"Name: {mexh.name}")
189
print(f"Complex CWT: {mexh.complex_cwt}")
190
print(f"Center frequency: {mexh.center_frequency}")
191

192
# Compute wavelet function
193
psi, x = mexh.wavefun()
194
plt.figure(figsize=(8, 4))
195
plt.plot(x, psi)
196
plt.title('Mexican Hat Wavelet')
197
plt.xlabel('x')
198
plt.ylabel('ψ(x)')
199
plt.grid(True)
200
plt.show()
201

202
# Complex Morlet wavelet
203
morlet = pywt.ContinuousWavelet('morl')
204
psi, x = morlet.wavefun()
205
plt.figure(figsize=(12, 4))
206
plt.subplot(1, 2, 1)
207
plt.plot(x, np.real(psi), label='Real')
208
plt.plot(x, np.imag(psi), label='Imaginary')
209
plt.title('Morlet Wavelet')
210
plt.legend()
211
plt.subplot(1, 2, 2)
212
plt.plot(x, np.abs(psi))
213
plt.title('Morlet Wavelet (Magnitude)')
214
plt.show()
215
```
216

217
### Wavelet Factory Function
218

219
Convenience function that returns the appropriate wavelet object type.
220

221
```python { .api }
222
def DiscreteContinuousWavelet(name: str, filter_bank=None):
223
    """
224
    Factory function returning appropriate Wavelet or ContinuousWavelet object.
225
    
226
    Parameters:
227
    - name: Wavelet name
228
    - filter_bank: Custom filter bank for discrete wavelets
229
    
230
    Returns:
231
    Wavelet object for discrete wavelets or ContinuousWavelet object for continuous wavelets
232
    """
233
```
234

235
### Signal Extension Modes
236

237
Constants and utilities for handling signal boundaries during transforms.
238

239
```python { .api }
240
class Modes:
241
    """Signal extension modes for boundary handling."""
242
    zero: str = 'zero'  # Zero padding
243
    constant: str = 'constant'  # Constant padding
244
    symmetric: str = 'symmetric'  # Symmetric extension
245
    reflect: str = 'reflect'  # Reflection at boundaries
246
    periodic: str = 'periodic'  # Periodic extension
247
    smooth: str = 'smooth'  # Smooth padding
248
    periodization: str = 'periodization'  # Periodization
249
    antisymmetric: str = 'antisymmetric'  # Antisymmetric extension
250
    antireflect: str = 'antireflect'  # Antireflection
251
    
252
    @staticmethod
253
    def from_object(mode) -> str:
254
        """
255
        Convert mode object to mode string.
256
        
257
        Parameters:
258
        - mode: Mode specification (string, integer, or Mode constant)
259
        
260
        Returns:
261
        Mode string
262
        """
263
```
264

265
### Wavelet Analysis Functions
266

267
Utility functions for analyzing wavelet properties and frequency characteristics.
268

269
```python { .api }
270
def integrate_wavelet(wavelet, precision: int = 8):
271
    """
272
    Integrate wavelet function from -∞ to x.
273
    
274
    Parameters:
275
    - wavelet: Wavelet instance or name
276
    - precision: Precision level for wavelet function approximation
277
    
278
    Returns:
279
    For orthogonal wavelets: (int_psi, x)
280
    For biorthogonal wavelets: (int_psi_d, int_psi_r, x)
281
    """
282

283
def central_frequency(wavelet, precision: int = 8) -> float:
284
    """
285
    Compute central frequency of wavelet function.
286
    
287
    Parameters:
288
    - wavelet: Wavelet instance or name  
289
    - precision: Precision level for wavelet function approximation
290
    
291
    Returns:
292
    Central frequency value
293
    """
294

295
def scale2frequency(wavelet, scale: float, precision: int = 8) -> float:
296
    """
297
    Convert CWT scale to normalized frequency.
298
    
299
    Parameters:
300
    - wavelet: Wavelet instance or name
301
    - scale: CWT scale value
302
    - precision: Precision level for wavelet function approximation
303
    
304
    Returns:
305
    Normalized frequency (1.0 = sampling frequency)
306
    """
307

308
def frequency2scale(wavelet, freq: float, precision: int = 8) -> float:
309
    """
310
    Convert normalized frequency to CWT scale.
311
    
312
    Parameters:
313
    - wavelet: Wavelet instance or name
314
    - freq: Normalized frequency
315
    - precision: Precision level for wavelet function approximation
316
    
317
    Returns:
318
    CWT scale value
319
    """
320
```
321

322
### Filter Bank Operations
323

324
Functions for working with wavelet filter banks and creating custom wavelets.
325

326
```python { .api }
327
def qmf(filt: np.ndarray) -> np.ndarray:
328
    """
329
    Compute Quadrature Mirror Filter (QMF).
330
    
331
    Parameters:
332
    - filt: Input filter coefficients
333
    
334
    Returns:
335
    QMF coefficients with mirror image magnitude response
336
    """
337

338
def orthogonal_filter_bank(scaling_filter: np.ndarray) -> tuple:
339
    """
340
    Generate orthogonal filter bank from scaling filter.
341
    
342
    Parameters:
343
    - scaling_filter: Scaling filter coefficients (must have even length)
344
    
345
    Returns:
346
    (dec_lo, dec_hi, rec_lo, rec_hi) - decomposition and reconstruction filter bank
347
    """
348
```
349

350
#### Usage Examples
351

352
```python
353
import pywt
354
import numpy as np
355

356
# Analyze wavelet frequency characteristics
357
db4 = pywt.Wavelet('db4')
358
central_freq = pywt.central_frequency(db4)
359
print(f"Central frequency: {central_freq}")
360

361
# Convert between scales and frequencies for CWT
362
mexh = pywt.ContinuousWavelet('mexh')
363
scale = 10
364
freq = pywt.scale2frequency(mexh, scale)
365
print(f"Scale {scale} corresponds to frequency {freq}")
366

367
back_to_scale = pywt.frequency2scale(mexh, freq)
368
print(f"Frequency {freq} corresponds to scale {back_to_scale}")
369

370
# Create QMF from scaling filter
371
scaling_filter = db4.dec_lo
372
qmf_filter = pywt.qmf(scaling_filter)
373
print(f"Original filter: {scaling_filter}")
374
print(f"QMF filter: {qmf_filter}")
375

376
# Generate complete orthogonal filter bank
377
dec_lo, dec_hi, rec_lo, rec_hi = pywt.orthogonal_filter_bank(scaling_filter)
378
print(f"Decomposition filters - Lo: {len(dec_lo)}, Hi: {len(dec_hi)}")
379
print(f"Reconstruction filters - Lo: {len(rec_lo)}, Hi: {len(rec_hi)}")
380
```
381

382
## Types
383

384
```python { .api }
385
# Wavelet specifications
386
WaveletSpec = Union[str, Wavelet, ContinuousWavelet]
387

388
# Filter bank format  
389
FilterBank = Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]  # (dec_lo, dec_hi, rec_lo, rec_hi)
390

391
# Extension modes
392
Mode = Literal[
393
    'zero', 'constant', 'symmetric', 'periodic', 
394
    'smooth', 'periodization', 'reflect', 
395
    'antisymmetric', 'antireflect'
396
]
397
```