| Author: | Filip Wasilewski |
|---|---|
| Contact: | filip.wasilewski@gmail.com |
| Version: | 0.1.6 |
| Status: | alpha |
| Date: | 2006-12-02 15:31 |
| License: | MIT |
Abstract
PyWavelets is a Python module for computing forward and inverse 1D and 2D Discrete Wavelet Transform, Stationary Wavelet Transform and Wavelet Packets decomposition and reconstruction. This document is a User Guide to PyWavelets.
PyWavelets was originally developed using MinGW C compiler, Pyrex and Python 2.4 on 32-bit WindowsXP platform. Recent release adds support for Python 2.5.
The only external requirement is a recent version of NumPy numeric array module.
Current release, including source and binary versions for Windows, is available for download from Python Cheese Shop directory at:
http://cheeseshop.python.org/pypi/PyWavelets/
The latest development version can be downloaded from wavelets.scipy.org SVN repository:
svn co http://wavelets.scipy.org/svn/multiresolution/pywt/trunk pywt
The most convenient way to install PyWavelets is to use setuptools Easy Install manager:
easy_install PyWavelets==0.1.6
Please note that in order to build PyWavelets from source code you will need a working C compiler and, in case of source code modifications, an updated version of Pyrex from
http://codespeak.net/svn/lxml/pyrex/
SVN repository, which includes features and bug fixes not yet available in the regular Pyrex distribution.
Then in the shell prompt in the PyWavelets source code directory type:
python setupegg.py install
or if using the default distutils manager:
python setup.py install
For Windows users there is also standard binary installer available in the Cheese Shop repository. Just download and execute it.
To verify the installation process try running tests and examples from tests and demo directories included in the source distribution. Note that some examples need matplotlib installed.
PyWavelets is free Open Source software available under MIT license. Just do no evil.
Feel free to contact me directly at filip.wasilewski@gmail.com. Comments, bug reports and fixes are welcome.
You can also use the wiki and trac system available at wavelets.scipy.org to improve documentation, post cookbook recipes or submit enhancement proposals or bug reports.
The families() function returns names of available built-in wavelet families. Currently the following wavelet families with over seventy wavelets are available:
Example:
The wavelist(short_name=None) function returns list of available wavelet names.
If short_name is None, then names of all implemented wavelets is returned, otherwise the function returns names of wavelets from given family name.
Example:
Wavelet(name, filter_bank=None) object describe properties of a wavelet identified by name. In order to use a built-in wavelet the parameter name must be a valid name from wavelist() list. Otherwise a filter_bank argument must be provided.
Example:
The wavefun(level) function can be used to calculates approximations of wavelet function (psi) and associated scaling function (phi) at given level of refinement.
For orthogonal wavelet returns scaling and wavelet function.
For biorthogonal wavelet returns scaling and wavelet function both for decomposition and reconstruction.
PyWavelets comes with long list of the most popular wavelets built-in and ready to use. If there is a need of using a specific wavelet which is not included in the list it is very easy to create one. Just pass an object of a class implementing get_filters_coeffs() method as a filter_bank argument of Wavelet constructor.
The get_filters_coeffs() method must return a list of four filters: lowpass decomposition, highpass decomposition, lowpass reconstruction and highpass reconstruction filter, just as the get_filters_coeffs() method of the Wavelet class.
A Wavelet object created in this way is a standard Wavelet object and can be used as any other Wavelet object.
Example:
Wavelet transform has recently became very popular when it comes to analysis, denoising and compression of signals and images.
The dwt function is used to perform single level, one dimensional Discrete Wavelet Transform.
(cA, cD) = dwt(data, wavelet, mode='sym')
The transform coefficients are returned as two arrays containing approximation (cA) and detail (cD) coefficients respectively. Length of returned arrays depends on selected mode - see dwt_coeff_len:
for all modes except periodization:
len(cA) == len(cD) == floor((len(data) + wavelet.dec_len - 1) / 2)
for periodization mode ("per"):
len(cA) == len(cD) == ceil(len(data) / 2)
Example:
(Please note the mode and level arguments order change in 0.1.6 version.)
The wavedec function performs 1D multilevel Discrete Wavelet Transform decomposition of given signal and returns ordered list of coefficients arrays [cAn, cDn, cDn-1, ..., cD2, cD1], where n denotes the level of decomposition. The first element (cAn) of the result is approximation coefficients array and the following elements (cDn - cD1) are details coefficients arrays.
wavedec(data, wavelet, mode='sym', level=None)
Example:
The dwt_max_level function can be used to compute the maximum useful level of decomposition for given input data length and wavelet filter length.
dwt_max_level(data_len, filter_len)
The returned value equals to:
floor(log(data_len/(filter_len-1))/log(2))
Although the maximum decomposition level can be quite high for long signals, usually smaller values are chosen.
Example:
Based on input data length, Wavelet decomposition filter length and signal extension mode, the dwt_coeff_len function calculates length of result coefficients arrays after dwt.
dwt_coeff_len(data_len, filter_len, mode)
For periodization mode this equals:
ceil(data_len / 2)
which is the lowest possible length guaranteeing perfect reconstruction.
For other modes:
floor((data_len + filter_len - 1) / 2)
To handle problem of border distortion while performing DWT, one of several signal extension modes can be selected.
zpd - zero-padding - signal is extended by adding zero samples:
0 0 | x1 x2 ... xn | 0 0
cpd - constant-padding - edge values are used:
x1 x1 | x1 x2 ... xn | xn xn
sym - symmetric-padding - signal is extended by mirroring samples:
x2 x1 | x1 x2 ... xn | xn xn-1
ppd - periodic-padding - signal is treated as periodic:
xn-1 xn | x1 x2 ... xn | x1 x2
sp1 - smooth-padding - signal is extended according to first derivatives calculated on the edges
DWT performed for these extension modes is slightly redundant, but ensure the perfect reconstruction. To receive the smallest number of coefficients, DWT can be computed with periodization mode
Example:
Notice that you can use either of the following forms:
Note that extending data in context of PyWavelets does not really mean reallocating memory and copying values. Instead of that the extra values are computed only when needed. This feature saves extra memory and CPU resources and helps to avoid page swapping when handling relatively big data arrays on computers with low physical memory.
The idwt function reconstructs data from given coefficients by performing single level Inverse Discrete Wavelet Transform.
idwt(cA, cD, wavelet, mode='sym', correct_size=0)
Example:
One of the cA and cD arguments can be None. In that situation the reconstruction will be performed using only the other one.
Example:
Performs multilevel reconstruction of signal from given coefficient list.
waverec(coeffs, wavelet, mode='sym')
coefficients list must be in the form like returned from wavedec decomposition:
[cAn, cDn, cDn-1, ..., cD2, cD1]
Example:
Direct reconstruction from coefficients.
upcoef(part, coeffs, wavelet, level=1, take=0)
defines coefficients type:
Example:
The dwt2 function performs single level 2D Discrete Wavelet Transform.
dwt2(data, wavelet, mode='sym')
Returns one average and three details 2D coefficients arrays. The coefficients arrays are organized in tuples in the following form:
(cA, (cH, cV, cD)),
where cA, cH, cV, cD denotes approximation, horizontal detail, vertical detail and diagonal detail coefficients respectively.
Example:
The idwt2 function reconstructs data from given coefficients by performing single level 2D Inverse Discrete Wavelet Transform.
idwt2(coeffs, wavelet, mode='sym')
A tuple with approximation coefficients and three details coefficients 2D arrays like from dwt2:
(cA, (cH, cV, cD))
Example:
Performs multilevel 2D Discrete Wavelet Transform decomposition and returns coefficients list [cAn, (cHn, cVn, cDn), ..., (cH1, cV1, cD1)], where n denotes the level of decomposition and cA, cH, cV and cD are approximation, horizontal detail, vertical detail and diagonal detail coefficients arrays.
wavedec2(data, wavelet, mode='sym', level=None)
Example:
Performs multilevel reconstruction from given coefficient list.
waverec2(coeffs, wavelet, mode='sym')
coefficients list must be in form like that from wavedec2 decomposition:
[cAn, (cHn, cVn, cDn), ..., (cH1, cV1, cD1)]
Example:
Tree structure simplifying operations on Wavelet Packet decomposition coefficients. It consists of Node elements.
WaveletPacket(data, wavelet, mode='sp1', maxlevel=None)
wp = WaveletPacket(range(16), 'db1', maxlevel=3)
Find node of given path in tree.
If node does not exist yet, it will be created by decomposition of its parent node.
Calls get_node(path) and returns data associated with node under given path.
Calls get_node(path) and sets data of node under given path.
Marks node under given path in tree as ZeroTree root.
If node does not exist yet, it will be created by decomposition of its parent node.
Returns data reconstruction using coefficients from subnodes.
If update is True, then node's data values will be replaced by reconstruction values (also in subnodes).
Returns all nodes from specified level.
Returns non-zero terminal nodes.
Walks tree and calls func on every node - func(node, *args). If func returns True, descending to subnodes will proceed.
Walks tree and calls func on every node starting from bottom most nodes.
WaveletPacket tree node.
Subnodes are called 'a' and 'd', like approximation and detail coefficients in Discrete Wavelet Transform
Path under node is accessible in Wavelet Packet tree.
Data associated with node.
Mark node as root of ZeroTree, which means that current node and all subnodes don't take part in reconstruction (all coefficients equals 0).
Field - like markZeroTree.
Returns chosen subnode.
Performs multilevel Stationary Wavelet Transform.
swt(data, wavelet, level)
Returned list of coefficient pairs is in form [(cA1, cD1), (cA2, cD2), ..., (cAn, cDn)], where n = level
Returns maximum level of Stationary Wavelet Transform for data of given length.
swt_max_level(input_len)
