swt normalization and option to trim the approximation coefficients

[grlee77]

This PR adds two optional arguments to swt, swt2 and swtn that change the scaling of the coefficients and control which coefficients are retained.

Option to discard unecessary approximation coefficients
The first option, trim_approx can be set true in order to keep only the approximation coefficients from the final level of decomposition. These are the only ones used by the inverse transform, so discarding the rest reduces memory use. There are also a couple of additional benefits:

1.) when trim_approx=True the format of the coefficients returned is exactly the same as for wavedec, wavedec2 and wavedecn
2.) Because of 1.), it becomes possible to also use the existing pywt.ravel_coeffs and pywt.unravel_coeffs on the output of the SWT transforms.

Option to use energy-preserving normalization

If we rescale the wavelet analysis filterbank by 1/sqrt(2), then the set of forward transform coefficients has the same energy as the original input. Additionally the sum of the variances of the individual coefficient arrays equals the variance of the input signal.

This makes the behavior very similar to the multiple-overlap DWT (MODWT) proposed by Percival and Walden in their book on time-series analysis. With norm=True and trim_approx=True swt can be used to recreate the type of things done with matlab's modwt and in the R package waveslim.

Each commit here is well separated, so it might be easiest to review them sequentially.

[rgommers]

Looks like a very interesting enhancement.

With norm=True and trim_approx=True swt can be used to recreate the type of things done with matlab's modwt and in the R package waveslim.

If you have an example lying around already, that would be useful to add I think (perhaps as a demo instead of docstring example).

[grlee77]

I added a demo using the existing ecg signal. The variance of the coefficients is demonstrated to sum to the same value as the original signal and plots of the normalized coefficients and variance as a function of signal decomposition level are shown:

[grlee77]

I rebased this and added a commit fixing up the docstrings as requested. If there are no further comments, I will plan to merge in a few days.

[grlee77]

Somehow the demo shown above got dropped from this PR at some point. I found it here and will make a separate PR to add it back in.

[mohammadAbdolhosseiniMoghaddam]

Is trim_approx available in swt ?
I am using 1.0.3 version. The following is the thrown error:
TypeError: swt() got an unexpected keyword argument 'trim_approx'
Any help is appreciated.

[grlee77]

On Thu, Sep 26, 2019 at 3:24 PM mohammadAbdolhosseiniMoghaddam < ***@***.***> wrote: Is trim_approx available in swt ? I am using 1.0.3 version. The following is thrown error? TypeError: swt() got an unexpected keyword argument 'trim_approx' Any gelp is apperciated. It is available only in the development version of the library. At the

moment you would need to build from source to have that feature. However, I think it is probably about time to make a new release (1.1). Once 1.1 is released you will be able to install the feature via pip or conda. Note that the documentation at https://pywavelets.readthedocs.io/ defaults to the development branch and describe features not yet in an official release. You can see documentation for a specific release instead via a button near the lower right hand corner of the page.