Function dwt_max_level

pywt/_dwt.py:18–80

r""" dwt_max_level(data_len, filter_len) Compute the maximum useful level of decomposition. Parameters ---------- data_len : int Input data length. filter_len : int, str or Wavelet The wavelet filter length. Alternatively, the name of a discrete wav

(data_len, filter_len)

def dwt_max_level(data_len, filter_len):
    r"""
    dwt_max_level(data_len, filter_len)

    Compute the maximum useful level of decomposition.

    Parameters
    ----------
    data_len : int
        Input data length.
    filter_len : int, str or Wavelet
        The wavelet filter length.  Alternatively, the name of a discrete
        wavelet or a Wavelet object can be specified.

    Returns
    -------
    max_level : int
        Maximum level.

    Notes
    -----
    The rational for the choice of levels is the maximum level where at least
    one coefficient in the output is uncorrupted by edge effects caused by
    signal extension.  Put another way, decomposition stops when the signal
    becomes shorter than the FIR filter length for a given wavelet.  This
    corresponds to:

    .. max_level = floor(log2(data_len/(filter_len - 1)))

    .. math::
        \mathtt{max\_level} = \left\lfloor\log_2\left(\mathtt{
            \frac{data\_len}{filter\_len - 1}}\right)\right\rfloor

    Examples
    --------
    >>> import pywt
    >>> w = pywt.Wavelet('sym5')
    >>> pywt.dwt_max_level(data_len=1000, filter_len=w.dec_len)
    6
    >>> pywt.dwt_max_level(1000, w)
    6
    >>> pywt.dwt_max_level(1000, 'sym5')
    6
    """
    if isinstance(filter_len, Wavelet):
        filter_len = filter_len.dec_len
    elif isinstance(filter_len, str):
        if filter_len in wavelist(kind='discrete'):
            filter_len = Wavelet(filter_len).dec_len
        else:
            raise ValueError(
                f"'{filter_len}', is not a recognized discrete wavelet.  A list of "
                 "supported wavelet names can be obtained via "
                 "pywt.wavelist(kind='discrete')")
    elif not (isinstance(filter_len, Number) and filter_len % 1 == 0):
        raise ValueError(
            "filter_len must be an integer, discrete Wavelet object, or the "
            "name of a discrete wavelet.")