# Wavelet Packets

PyWavelets implements one-dimensional, two-dimensional and n-dimensional wavelet packet transform structures. The higher dimensional structures almost completely sharing programming interface with the one-dimensional tree structure.

In order to achieve this simplification, a new inheritance scheme was used in which a `BaseNode` base node class is a superclass for the `Node`, `Node2D` and `NodeND` classes.

The node classes are used as data wrappers and can be organized in trees ( binary trees for 1D transform case, quad-trees for the 2D one and 2**N-ary trees in ND). They are also superclasses to the `WaveletPacket`, `WaveletPacket2D` and `WaveletPacketND` classes that are used as the decomposition tree roots and contain a couple additional methods.

Here 1D, 2D and ND refer to the number of axes of the data to be transformed. All wavelet packet objects can operate on general n-dimensional arrays, but the 1D or 2D classes apply transforms along only 1 or 2 dimensions. The ND classes allow transforms over an arbitrary number of axes of n-dimensional data.

The below diagram illustrates the inheritance tree:

> - `BaseNode` - common interface for 1D and 2D nodes:

>   - `Node` - data carrier node in a 1D decomposition tree

>     - `WaveletPacket` - 1D decomposition tree root node

>   - `Node2D` - data carrier node in a 2D decomposition tree

>     - `WaveletPacket2D` - 2D decomposition tree root node

>   - `NodeND` - data carrier node in a ND decomposition tree

>     - `WaveletPacketND` - ND decomposition tree root node

## BaseNode - a common interface of WaveletPacket, WaveletPacket2D and WaveletPacketND

class pywt.BaseNode

  Note

  The BaseNode is a base class for `Node`, `Node2D`, and `NodeND`. It should not be used directly unless creating a new transformation type. It is included here to document the common interface of the node and wavelet packet transform classes.

  __init__(parent, data, node_name)
    Parameters:

      - parent – parent node. If parent is `None` then the node is considered detached.

      - data – The data associated with the node. An n-dimensional numeric array.

      - node_name – a name identifying the coefficients type. See `Node.node_name` and `Node2D.node_name` for information on the accepted subnodes names.

  data

    Data associated with the node. An n-dimensional numeric array.

  parent

    Parent node. Used in tree navigation. `None` for root node.

  wavelet

    `Wavelet` used for decomposition and reconstruction. Inherited from parent node.

  axes

    A tuple of ints containing the axes along which the wavelet packet transform is to be applied.

  mode

    Signal extension mode for the `dwt()` (`dwt2()`) and `idwt()` (`idwt2()`) decomposition and reconstruction functions. Inherited from parent node.

  level

    Decomposition level of the current node. `0` for root (original data), `1` for the first decomposition level, etc.

  path

    Path string defining position of the node in the decomposition tree.

  path_tuple

    A version of `path`, but in tuple form rather than as a single string. The tuple form is easier to work with for n-dimensional transforms. The length of the tuple will be equal to the number of levels of decomposition at the current node.

  node_name

    Node name describing `data` coefficients type of the current subnode.

    See `Node.node_name` and `Node2D.node_name`.

  maxlevel

    Maximum allowed level of decomposition. Evaluated from parent or child nodes.

  is_empty

    Checks if `data` attribute is `None`.

  has_any_subnode

    Checks if node has any subnodes (is not a leaf node).

  decompose()

    Performs Discrete Wavelet Transform on the `data` and returns transform coefficients.

  reconstruct([update=False])

    Performs Inverse Discrete Wavelet Transform on subnodes coefficients and returns reconstructed data for the current level.

    Parameters:

      update – If set, the `data` attribute will be updated with the reconstructed value.

    Note

    Descends to subnodes and recursively calls `reconstruct()` on them.

  get_subnode(part[, decompose=True])

    Returns subnode or None (see decomposition flag description).

    Parameters:

      - part – Subnode name

      - decompose – If True and subnode does not exist, it will be created using coefficients from the DWT decomposition of the current node.

  __getitem__(path)

    Used to access nodes in the decomposition tree by string `path`.

    Parameters:

      path – Path string composed from valid node names. See `Node.node_name` and `Node2D.node_name` for node naming convention.

    Similar to `get_subnode()` method with decompose=True, but can access nodes on any level in the decomposition tree.

    If node does not exist yet, it will be created by decomposition of its parent node.

  __setitem__(path, data)

    Used to set node or node’s data in the decomposition tree. Nodes are identified by string `path`.

    Parameters:

      - path – Path string composed from valid node names. See `Node.node_name` and `Node2D.node_name` for node naming convention.

      - data – numeric array or `BaseNode` subclass.

  __delitem__(path)

    Used to delete node from the decomposition tree.

    Parameters:

      path – Path string composed from valid node names. See `Node.node_name` and `Node2D.node_name` for node naming convention.

  get_leaf_nodes([decompose=False])

    Traverses through the decomposition tree and collects leaf nodes (nodes without any subnodes).

    Parameters:

      decompose – If `decompose` is `True`, the method will try to decompose the tree up to the `maximum level`.

  walk(self, func[, args=()[, kwargs={}[, decompose=True]]])

    Traverses the decomposition tree and calls `func(node, *args, **kwargs)` on every node. If func returns `True`, descending to subnodes will continue.

    Parameters:

      - func –

        callable accepting `BaseNode` as the first param and optional positional and keyword arguments:

            func(node, *args, **kwargs)

      - decompose – If `decompose` is `True` (default), the method will also try to decompose the tree up to the `maximum level`.

    Args:

      arguments to pass to the `func`

    Kwargs:

      keyword arguments to pass to the `func`

  walk_depth(self, func[, args=()[, kwargs={}[, decompose=False]]])

    Similar to `walk()` but traverses the tree in depth-first order.

    Parameters:

      - func –

        callable accepting `BaseNode` as the first param and optional positional and keyword arguments:

            func(node, *args, **kwargs)

      - decompose – If `decompose` is `True`, the method will also try to decompose the tree up to the `maximum level`.

    Args:

      arguments to pass to the `func`

    Kwargs:

      keyword arguments to pass to the `func`

## WaveletPacket and Node

class pywt.Node(BaseNode)
  node_name

    Node name describing `data` coefficients type of the current subnode.

    For `WaveletPacket` case it is just as in `dwt()`:

      - `a` - approximation coefficients

      - `d` - details coefficients

  decompose()

    See also

    `dwt()` for 1D Discrete Wavelet Transform output coefficients.

  reconstruct()

    See also

    `idwt()` for 1D Inverse Discrete Wavelet Transform

class pywt.WaveletPacket(Node)
  __init__(data, wavelet[, mode='symmetric'[, maxlevel=None[, axis=-1]]])
    Parameters:

      - data – data associated with the node. N-dimensional numeric array.

      - wavelet – Wavelet to use in the transform. This can be a name of the wavelet from the `wavelist()` list or a `Wavelet` object instance.

      - mode – Signal extension mode for the `dwt()` and `idwt()` decomposition and reconstruction functions.

      - maxlevel – Maximum allowed level of decomposition. If not specified it will be calculated based on the `wavelet` and `data` length using `pywt.dwt_max_level()`.

      - axis – The axis of the array that is to be transformed.

  get_level(level[, order="natural"[, decompose=True]])

    Collects nodes from the given level of decomposition.

    Parameters:

      - level – Specifies decomposition `level` from which the nodes will be collected.

      - order – Specifies nodes order - natural (`natural`) or frequency (`freq`).

      - decompose – If set then the method will try to decompose the data up to the specified `level`.

    If nodes at the given level are missing (i.e. the tree is partially decomposed) and the `decompose` is set to `False`, only existing nodes will be returned.

  reconstruct([update=True])

    Reconstruct data from the subnodes.

    Parameters:

      update – A boolean indicating whether the coefficients of the current node and its subnodes will be replaced with values from the reconstruction.

## WaveletPacket2D and Node2D

class pywt.Node2D(BaseNode)
  node_name
    For `WaveletPacket2D` case it is just as in `dwt2()`:

      - `a` - approximation coefficients (LL)

      - `h` - horizontal detail coefficients (LH)

      - `v` - vertical detail coefficients (HL)

      - `d` - diagonal detail coefficients (HH)

  decompose()

    See also

    `dwt2()` for 2D Discrete Wavelet Transform output coefficients.

  reconstruct()

    See also

    `idwt2()` for 2D Inverse Discrete Wavelet Transform

  expand_2d_path(self, path):

class pywt.WaveletPacket2D(Node2D)
  __init__(data, wavelet[, mode='symmetric'[, maxlevel=None[, axes=(-2, -1)]]])
    Parameters:

      - data – data associated with the node. N-dimensional numeric array.

      - wavelet – Wavelet to use in the transform. This can be a name of the wavelet from the `wavelist()` list or a `Wavelet` object instance.

      - mode – Signal extension mode for the `dwt()` and `idwt()` decomposition and reconstruction functions.

      - maxlevel – Maximum allowed level of decomposition. If not specified it will be calculated based on the `wavelet` and `data` length using `pywt.dwt_max_level()`.

      - axes – The axes of the array that are to be transformed.

  get_level(level[, order="natural"[, decompose=True]])

    Collects nodes from the given level of decomposition.

    Parameters:

      - level – Specifies decomposition `level` from which the nodes will be collected.

      - order – Specifies nodes order - natural (`natural`) or frequency (`freq`).

      - decompose – If set then the method will try to decompose the data up to the specified `level`.

    If nodes at the given level are missing (i.e. the tree is partially decomposed) and the `decompose` is set to `False`, only existing nodes will be returned.

  reconstruct([update=True])

    Reconstruct data from the subnodes.

    Parameters:

      update – A boolean indicating whether the coefficients of the current node and its subnodes will be replaced with values from the reconstruction.

## WaveletPacketND and NodeND

class pywt.NodeND(BaseNode)
  node_name
    For `WaveletPacketND` case it is just as in `dwtn()`:

      - in 1D it has keys ‘a’ and ‘d’

      - in 2D it has keys ‘aa’, ‘ad’, ‘da’, ‘dd’

      - in 3D it has keys ‘aaa’, ‘aad’, ‘ada’, ‘daa’, …, ‘ddd’

  decompose()

    See also

    `dwtn()` for ND Discrete Wavelet Transform output coefficients.

  reconstruct()

    See also

    `idwtn()` for ND Inverse Discrete Wavelet Transform

class pywt.WaveletPacketND(NodeND)
  __init__(data, wavelet[, mode='symmetric'[, maxlevel=None[, axes=None]]])
    Parameters:

      - data – data associated with the node. N-dimensional numeric array.

      - wavelet – Wavelet to use in the transform. This can be a name of the wavelet from the `wavelist()` list or a `Wavelet` object instance.

      - mode – Signal extension mode for the `dwt()` and `idwt()` decomposition and reconstruction functions.

      - maxlevel – Maximum allowed level of decomposition. If not specified it will be calculated based on the `wavelet` and `data` length using `pywt.dwt_max_level()`.

      - axes – The axes of the array that are to be transformed.

  get_level(level[, decompose=True])

    Collects nodes from the given level of decomposition.

    Parameters:

      - level – Specifies decomposition `level` from which the nodes will be collected.

      - decompose – If set then the method will try to decompose the data up to the specified `level`.

    If nodes at the given level are missing (i.e. the tree is partially decomposed) and the `decompose` is set to `False`, only existing nodes will be returned.

  reconstruct([update=True])

    Reconstruct data from the subnodes.

    Parameters:

      update – A boolean indicating whether the coefficients of the current node and its subnodes will be replaced with values from the reconstruction.