# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.3 `wav` Chapter.
``wav`` - Wavelet Transforms
This module is concerned with the analysis of datasets (or functions or operators) in terms of frequency and scale components using wavelet transforms.
Wavelet transforms have been applied in many fields from time series analysis to image processing and the localization in either frequency or scale that they provide is useful for data compression or denoising.
In general the standard wavelet transform uses dilation and scaling of a chosen function, :math:`\psi \left(t\right)`, (called the mother wavelet) such that
.. math::
\psi_{{a,b}}\left(t\right) = \frac{1}{\sqrt{a}}\psi \left(\frac{{t-b}}{a}\right)
where :math:`a` gives the scaling and :math:`b` determines the translation.
Wavelet methods can be divided into continuous transforms and discrete transforms.
In the continuous case, the pair :math:`a` and :math:`b` are real numbers with :math:`a>0`.
For the discrete transform, :math:`a` and :math:`b` can be chosen as :math:`a = 2^{{-j}}`, :math:`b = k2^{{-j}}` for integers :math:`j`, :math:`k`
.. math::
\psi_{{j,k}}\left(t\right) = 2^{{j/2}}\psi \left(2^jt-k\right)\text{.}
The continuous real valued, one-dimensional wavelet transform (CWT) is included in this module.
The discrete wavelet transform (DWT) at a single level together with its inverse and the multi-level DWT with inverse are also provided for one, two and three dimensions.
The Maximal Overlap DWT (MODWT) together with its inverse and the multi-level MODWT with inverse are provided for one dimension.
The choice of wavelet for CWT includes the Morlet wavelet and derivatives of a Gaussian while the DWT and MODWT offer the orthogonal wavelets of Daubechies and a selection of biorthogonal wavelets.
Functionality Index
-------------------
**One-dimensional**
continuous
real wavelet transform: :meth:`dim1_cont`
discrete
multi-level
inverse wavelet transform: :meth:`dim1_multi_inv`
wavelet transform: :meth:`dim1_multi_fwd`
single level
inverse wavelet transform: :meth:`dim1_sngl_inv`
wavelet transform: :meth:`dim1_sngl_fwd`
maximal overlap discrete
multi-level
inverse wavelet transform: :meth:`dim1_mxolap_multi_inv`
wavelet transform: :meth:`dim1_mxolap_multi_fwd`
single level
inverse wavelet transform: :meth:`dim1_mxolap_inv`
wavelet transform: :meth:`dim1_mxolap_fwd`
wavelet filter details: :meth:`dim1_init`
**Three-dimensional**
coefficient extraction: :meth:`dim3_coeff_ext`
coefficient insertion: :meth:`dim3_coeff_ins`
discrete
multi-level
inverse wavelet transform: :meth:`dim3_mxolap_multi_inv`
wavelet transform: :meth:`dim3_multi_fwd`
single level
inverse wavelet transform: :meth:`dim3_sngl_inv`
wavelet transform: :meth:`dim3_sngl_fwd`
wavelet filter details: :meth:`dim3_init`
**Two-dimensional**
coefficient extraction: :meth:`dim2_coeff_ext`
coefficient insertion: :meth:`dim2_coeff_ins`
discrete
multi-level
inverse wavelet transform: :meth:`dim2_multi_inv`
wavelet transform: :meth:`dim2_multi_fwd`
single level
inverse wavelet transform: :meth:`dim2_sngl_inv`
wavelet transform: :meth:`dim2_sngl_fwd`
wavelet filter details: :meth:`dim2_init`
For full information please refer to the NAG Library document
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html
"""
# NAG Copyright 2017-2023.
[docs]def dim1_init(wavnam, wtrans, mode, n):
r"""
``dim1_init`` returns the details of the chosen one-dimensional discrete wavelet filter.
For a chosen mother wavelet, discrete wavelet transform type (single-level or multi-level DWT or MODWT) and end extension method, this function returns the maximum number of levels of resolution (appropriate to a multi-level transform), the filter length, and the number of approximation coefficients (equal to the number of detail coefficients) for a single-level DWT or MODWT or the total number of coefficients for a multi-level DWT or MODWT.
This function must be called before any of the one-dimensional discrete transform functions in this module.
.. _c09aa-py2-py-doc:
For full information please refer to the NAG Library document for c09aa
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09aaf.html
.. _c09aa-py2-py-parameters:
**Parameters**
**wavnam** : str
The name of the mother wavelet. See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html>`__ for details.
:math:`\mathrm{wavnam} = \text{‘HAAR'}`
Haar wavelet, also known as :math:`\text{‘DB1'}` as a special case of the Daubechies wavelet.
:math:`\mathrm{wavnam} = \text{‘DBn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,38`
Daubechies wavelet with :math:`\boldsymbol{n}` vanishing moments (:math:`2\boldsymbol{n}` coefficients). For example, :math:`\mathrm{wavnam} = \text{‘DB4'}` is the name for the Daubechies wavelet with :math:`4` vanishing moments (:math:`8` coefficients).
:math:`\mathrm{wavnam} = \text{‘COIFn'}`, where :math:`\boldsymbol{n} = 1,2,\ldots,17`
Coiflet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BEYL'}`
Beylkin wavelet.
:math:`\mathrm{wavnam} = \text{‘VAID'}`
Vaidyanathan wavelet.
:math:`\mathrm{wavnam} = \text{‘SYMn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,20`
Symlet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BIORx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘BIOR3.1'}` is the name for the biorthogonal wavelet of order :math:`3.1`.
:math:`\mathrm{wavnam} = \text{‘RBIOx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Reverse biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘RBIO3.1'}` is the name for the reverse biorthogonal wavelet of order :math:`3.1`.
**wtrans** : str, length 1
The type of discrete wavelet transform that is to be applied.
:math:`\mathrm{wtrans} = \text{‘S'}`
Single-level decomposition or reconstruction by discrete wavelet transform.
:math:`\mathrm{wtrans} = \text{‘M'}`
Multiresolution, by a multi-level DWT or its inverse.
:math:`\mathrm{wtrans} = \text{‘T'}`
Single-level decomposition or reconstruction by maximal overlap discrete wavelet transform.
:math:`\mathrm{wtrans} = \text{‘U'}`
Multi-level resolution by a maximal overlap discrete wavelet transform or its inverse.
**mode** : str, length 1
The end extension method. Note that only periodic end extension is currently available for the MODWT.
:math:`\mathrm{mode} = \text{‘P'}`
Periodic end extension.
:math:`\mathrm{mode} = \text{‘H'}`
Half-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘W'}`
Whole-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘Z'}`
Zero end extension.
**n** : int
The number of elements, :math:`n`, in the input data array, :math:`x`.
**Returns**
**nwlmax** : int
The maximum number of levels of resolution, :math:`l_{\mathrm{max}}`, that can be computed when a multi-level discrete wavelet transform is applied. It is such that :math:`2^{l_{\mathrm{max}}}\leq n < 2^{{l_{\mathrm{max}}+1}}`, for :math:`l_{\mathrm{max}}` an integer.
**nf** : int
The filter length, :math:`n_f`, for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.
**nwc** : int
For a single-level transform (:math:`\mathrm{wtrans} = \text{‘S'} \text{ or } \text{‘T'}`), the number of approximation coefficients that would be generated for the given problem size, mother wavelet, extension method and type of transform; this is also the corresponding number of detail coefficients. For a multi-level transform (:math:`\mathrm{wtrans} = \text{‘M'} \text{ or } \text{‘U'}`) the total number of coefficients that would be generated over :math:`l_{\mathrm{max}}` levels and with :math:`{\textit{ikeep}} = 1` for MODWT.
**comm** : dict, communication object
Communication structure.
.. _c09aa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{wavnam}` not recognised: :math:`\mathrm{wavnam} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{wtrans} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{wtrans} = \text{‘S'}, \text{‘M'}, \text{‘T'} \text{ or } \text{‘U'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{mode} = \text{‘P'}, \text{‘H'}, \text{‘W'} \text{ or } \text{‘Z'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{wtrans} = \text{‘T'} \text{ or } \text{‘U'}` and :math:`\mathrm{mode} != \text{‘P'}`.
Constraint: :math:`\mathrm{mode} = \text{‘P'}` when :math:`\mathrm{wtrans} = \text{‘T'} \text{ or } \text{‘U'}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq 2`.
.. _c09aa-py2-py-notes:
**Notes**
One-dimensional discrete wavelet transforms (DWT) or maximum overlap wavelet transforms (MODWT) are characterised by the mother wavelet, the end extension method and whether multiresolution analysis is to be performed.
For the selected combination of choices for these three characteristics, and for a given length, :math:`n`, of the input data array, :math:`x`, ``dim1_init`` returns the dimension details for the transform determined by this combination.
The dimension details are: :math:`l_{\mathrm{max}}`, the maximum number of levels of resolution that that could be computed were a multi-level DWT/MODWT applied; :math:`n_f`, the filter length; :math:`n_c` the number of approximation (or detail) coefficients for a single-level DWT/MODWT or the total number of coefficients generated by a multi-level DWT/MODWT over :math:`l_{\mathrm{max}}` levels.
These values are also stored in the communication array :math:`\mathrm{comm}`\ ['icomm'], as are the input choices, so that they may be conveniently communicated to the one-dimensional transform functions in this module.
"""
raise NotImplementedError
[docs]def dim2_init(wavnam, wtrans, mode, m, n):
r"""
``dim2_init`` returns the details of the chosen two-dimensional discrete wavelet filter.
For a chosen mother wavelet, discrete wavelet transform type (single-level or multi-level DWT) and end extension method, this function returns the maximum number of levels of resolution (appropriate to a multi-level transform), the filter length, the total number of approximation, horizontal, vertical and diagonal coefficients and the number of coefficients in the second dimension for the single-level case.
This function must be called before any of the two-dimensional transform functions in this module.
.. _c09ab-py2-py-doc:
For full information please refer to the NAG Library document for c09ab
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09abf.html
.. _c09ab-py2-py-parameters:
**Parameters**
**wavnam** : str
The name of the mother wavelet. See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html>`__ for details.
:math:`\mathrm{wavnam} = \text{‘HAAR'}`
Haar wavelet, also known as :math:`\text{‘DB1'}` as a special case of the Daubechies wavelet.
:math:`\mathrm{wavnam} = \text{‘DBn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,38`
Daubechies wavelet with :math:`\boldsymbol{n}` vanishing moments (:math:`2\boldsymbol{n}` coefficients). For example, :math:`\mathrm{wavnam} = \text{‘DB4'}` is the name for the Daubechies wavelet with :math:`4` vanishing moments (:math:`8` coefficients).
:math:`\mathrm{wavnam} = \text{‘COIFn'}`, where :math:`\boldsymbol{n} = 1,2,\ldots,17`
Coiflet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BEYL'}`
Beylkin wavelet.
:math:`\mathrm{wavnam} = \text{‘VAID'}`
Vaidyanathan wavelet.
:math:`\mathrm{wavnam} = \text{‘SYMn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,20`
Symlet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BIORx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘BIOR3.1'}` is the name for the biorthogonal wavelet of order :math:`3.1`.
:math:`\mathrm{wavnam} = \text{‘RBIOx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Reverse biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘RBIO3.1'}` is the name for the reverse biorthogonal wavelet of order :math:`3.1`.
**wtrans** : str, length 1
The type of discrete wavelet transform that is to be applied.
:math:`\mathrm{wtrans} = \text{‘S'}`
Single-level decomposition or reconstruction by discrete wavelet transform.
:math:`\mathrm{wtrans} = \text{‘M'}`
Multiresolution, by a multi-level DWT or its inverse.
**mode** : str, length 1
The end extension method.
:math:`\mathrm{mode} = \text{‘P'}`
Periodic end extension.
:math:`\mathrm{mode} = \text{‘H'}`
Half-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘W'}`
Whole-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘Z'}`
Zero end extension.
**m** : int
The number of elements, :math:`m`, in the first dimension (number of rows of data matrix :math:`A`) of the input data.
**n** : int
The number of elements, :math:`n`, in the second dimension (number of columns of data matrix :math:`A`) of the input data.
**Returns**
**nwlmax** : int
The maximum number of levels of resolution, :math:`l_{\mathrm{max}}`, that can be computed if a multi-level discrete wavelet transform is applied (:math:`\mathrm{wtrans} = \text{‘M'}`). It is such that :math:`2^{l_{\mathrm{max}}}\leq \mathrm{min}\left(m, n\right) < 2^{{l_{\mathrm{max}}+1}}`, for :math:`l_{\mathrm{max}}` an integer.
If :math:`\mathrm{wtrans} = \text{‘S'}`, :math:`\mathrm{nwlmax}` is not set.
**nf** : int
The filter length, :math:`n_f`, for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.
**nwct** : int
The total number of wavelet coefficients, :math:`n_{\textit{ct}}`, that will be generated. When :math:`\mathrm{wtrans} = \text{‘S'}` the number of rows required in each of the output coefficient matrices can be calculated as :math:`n_{\textit{cm}} = n_{\textit{ct}}/\left(4n_{\textit{cn}}\right)`. When :math:`\mathrm{wtrans} = \text{‘M'}` the length of the array used to store all of the coefficient matrices must be at least :math:`n_{\textit{ct}}`.
**nwcn** : int
For a single-level transform (:math:`\mathrm{wtrans} = \text{‘S'}`), the number of coefficients that would be generated in the second dimension, :math:`n_{\textit{cn}}`, for each coefficient type. For a multi-level transform (:math:`\mathrm{wtrans} = \text{‘M'}`) this is set to :math:`1`.
**comm** : dict, communication object
Communication structure.
.. _c09ab-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{wavnam}` not recognised: :math:`\mathrm{wavnam} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{wtrans} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{wtrans} = \text{‘S'} \text{ or } \text{‘M'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{mode} = \text{‘P'}, \text{‘H'}, \text{‘W'} \text{ or } \text{‘Z'}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq 2`.
.. _c09ab-py2-py-notes:
**Notes**
Two-dimensional discrete wavelet transforms (DWT) are characterised by the mother wavelet, the end extension method and whether multiresolution analysis is to be performed.
For the selected combination of choices for these three characteristics, and for given dimensions (:math:`m\times n`) of data matrix :math:`A`, ``dim2_init`` returns the dimension details for the transform determined by this combination.
The dimension details are: :math:`l_{\mathrm{max}}`, the maximum number of levels of resolution that would be computed were a multi-level DWT applied; :math:`n_f`, the filter length; :math:`n_{\textit{ct}}` the total number of approximation, horizontal, vertical and diagonal coefficients (over all levels in the multi-level DWT case); and :math:`n_{\textit{cn}}`, the number of coefficients in the second dimension for a single-level DWT.
These values are also stored in the communication array :math:`\mathrm{comm}`\ ['icomm'], as are the input choices, so that they may be conveniently communicated to the two-dimensional transform functions in this module.
"""
raise NotImplementedError
[docs]def dim3_init(wavnam, wtrans, mode, m, n, fr):
r"""
``dim3_init`` returns the details of the chosen three-dimensional discrete wavelet filter.
For a chosen mother wavelet, discrete wavelet transform type (single-level or multi-level DWT) and end extension method, this function returns the maximum number of levels of resolution (appropriate to a multi-level transform), the filter length, the total number of coefficients and the number of wavelet coefficients in the second and third dimensions for the single-level case.
This function must be called before any of the three-dimensional transform functions in this module.
.. _c09ac-py2-py-doc:
For full information please refer to the NAG Library document for c09ac
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09acf.html
.. _c09ac-py2-py-parameters:
**Parameters**
**wavnam** : str
The name of the mother wavelet. See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html>`__ for details.
:math:`\mathrm{wavnam} = \text{‘HAAR'}`
Haar wavelet, also known as :math:`\text{‘DB1'}` as a special case of the Daubechies wavelet.
:math:`\mathrm{wavnam} = \text{‘DBn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,38`
Daubechies wavelet with :math:`\boldsymbol{n}` vanishing moments (:math:`2\boldsymbol{n}` coefficients). For example, :math:`\mathrm{wavnam} = \text{‘DB4'}` is the name for the Daubechies wavelet with :math:`4` vanishing moments (:math:`8` coefficients).
:math:`\mathrm{wavnam} = \text{‘COIFn'}`, where :math:`\boldsymbol{n} = 1,2,\ldots,17`
Coiflet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BEYL'}`
Beylkin wavelet.
:math:`\mathrm{wavnam} = \text{‘VAID'}`
Vaidyanathan wavelet.
:math:`\mathrm{wavnam} = \text{‘SYMn'}`, where :math:`\boldsymbol{n} = 2,3,\ldots,20`
Symlet wavelet of order :math:`\boldsymbol{n}`.
:math:`\mathrm{wavnam} = \text{‘BIORx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘BIOR3.1'}` is the name for the biorthogonal wavelet of order :math:`3.1`.
:math:`\mathrm{wavnam} = \text{‘RBIOx.y'}`, where :math:`\boldsymbol{x}.\boldsymbol{y}` can be one of 1.1, 1.3, 1.5, 2.2, 2.4, 2.6, 2.8, 3.1, 3.3, 3.5, 3.7, 3.9, 4.4, 5.5 or 6.8
Reverse biorthogonal wavelet of order :math:`\boldsymbol{x}.\boldsymbol{y}`. For example :math:`\mathrm{wavnam} = \text{‘RBIO3.1'}` is the name for the reverse biorthogonal wavelet of order :math:`3.1`.
**wtrans** : str, length 1
The type of discrete wavelet transform that is to be applied.
:math:`\mathrm{wtrans} = \text{‘S'}`
Single-level decomposition or reconstruction by discrete wavelet transform.
:math:`\mathrm{wtrans} = \text{‘M'}`
Multiresolution, by a multi-level DWT or its inverse.
**mode** : str, length 1
The end extension method.
:math:`\mathrm{mode} = \text{‘P'}`
Periodic end extension.
:math:`\mathrm{mode} = \text{‘H'}`
Half-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘W'}`
Whole-point symmetric end extension.
:math:`\mathrm{mode} = \text{‘Z'}`
Zero end extension.
**m** : int
The number of elements, :math:`m`, in the first dimension (number of rows of each two-dimensional frame) of the input data, :math:`A`.
**n** : int
The number of elements, :math:`n`, in the second dimension (number of columns of each two-dimensional frame) of the input data, :math:`A`.
**fr** : int
The number of elements, :math:`\textit{fr}`, in the third dimension (number of frames) of the input data, :math:`A`.
**Returns**
**nwlmax** : int
The maximum number of levels of resolution, :math:`l_{\mathrm{max}}`, that can be computed if a multi-level discrete wavelet transform is applied (:math:`\mathrm{wtrans} = \text{‘M'}`). It is such that :math:`2^{l_{\mathrm{max}}}\leq \mathrm{min}\left(m, n, \textit{fr}\right) < 2^{{l_{\mathrm{max}}+1}}`, for :math:`l_{\mathrm{max}}` an integer.
If :math:`\mathrm{wtrans} = \text{‘S'}`, :math:`\mathrm{nwlmax}` is not set.
**nf** : int
The filter length, :math:`n_f`, for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.
**nwct** : int
The total number of wavelet coefficients, :math:`n_{\textit{ct}}`, that will be generated. When :math:`\mathrm{wtrans} = \text{‘S'}` the number of rows required (i.e., the first dimension of each two-dimensional frame) in each of the output coefficient arrays can be calculated as :math:`n_{\textit{cm}} = n_{\textit{ct}}/\left(8\times n_{\textit{cn}}\times n_{\textit{cfr}}\right)`. When :math:`\mathrm{wtrans} = \text{‘M'}` the length of the array used to store all of the coefficient matrices must be at least :math:`n_{\textit{ct}}`.
**nwcn** : int
For a single-level transform (:math:`\mathrm{wtrans} = \text{‘S'}`), the number of coefficients that would be generated in the second dimension, :math:`n_{\textit{cn}}`, for each coefficient type. For a multi-level transform (:math:`\mathrm{wtrans} = \text{‘M'}`) this is set to :math:`1`.
**nwcfr** : int
For a single-level transform (:math:`\mathrm{wtrans} = \text{‘S'}`), the number of coefficients that would be generated in the third dimension, :math:`n_{\textit{cfr}}`, for each coefficient type. For a multi-level transform (:math:`\mathrm{wtrans} = \text{‘M'}`) this is set to :math:`1`.
**comm** : dict, communication object
Communication structure.
.. _c09ac-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{wavnam}` not recognised: :math:`\mathrm{wavnam} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{wtrans} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{wtrans} = \text{‘S'} \text{ or } \text{‘M'}`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{mode} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{mode} = \text{‘P'}, \text{‘H'}, \text{‘W'} \text{ or } \text{‘Z'}`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq 2`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{fr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{fr}\geq 2`.
.. _c09ac-py2-py-notes:
**Notes**
Three-dimensional discrete wavelet transforms (DWT) are characterised by the mother wavelet, the end extension method and whether multiresolution analysis is to be performed.
For the selected combination of choices for these three characteristics, and for given dimensions (:math:`m\times n\times \textit{fr}`) of data array :math:`A`, ``dim3_init`` returns the dimension details for the transform determined by this combination.
The dimension details are: :math:`l_{\mathrm{max}}`, the maximum number of levels of resolution that would be computed were a multi-level DWT applied; :math:`n_f`, the filter length; :math:`n_{\textit{ct}}` the total number of wavelet coefficients (over all levels in the multi-level DWT case); :math:`n_{\textit{cn}}`, the number of coefficients in the second dimension for a single-level DWT; and :math:`n_{\textit{cfr}}`, the number of coefficients in the third dimension for a single-level DWT.
These values are also stored in the communication array :math:`\mathrm{comm}`\ ['icomm'], as are the input choices, so that they may be conveniently communicated to the three-dimensional transform functions in this module.
"""
raise NotImplementedError
[docs]def dim1_cont(wavnam, wparam, x, scales):
r"""
``dim1_cont`` computes the real, continuous wavelet transform in one dimension.
.. _c09ba-py2-py-doc:
For full information please refer to the NAG Library document for c09ba
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09baf.html
.. _c09ba-py2-py-parameters:
**Parameters**
**wavnam** : str
The name of the mother wavelet. See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html>`__ for details.
:math:`\mathrm{wavnam} = \text{‘MORLET'}`
Morlet wavelet.
:math:`\mathrm{wavnam} = \text{‘DGAUSS'}`
Derivative of a Gaussian wavelet.
:math:`\mathrm{wavnam} = \text{‘MEXHAT'}`
Mexican hat wavelet.
**wparam** : int
The nondimensional wave number for the Morlet wavelet or the order of the derivative for the Gaussian wavelet. It is not referenced when :math:`\mathrm{wavnam} = \text{‘MEXHAT'}`.
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}` contains the input dataset :math:`\mathrm{x}[\textit{j}-1] = x_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.
**scales** : int, array-like, shape :math:`\left(\textit{nscal}\right)`
The scales at which the transform is to be computed.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{nscal}, n\right)`
The transform coefficients at the requested scales, where :math:`\mathrm{c}[i-1,j-1]` is the transform coefficient :math:`C_{{i,j}}` at scale :math:`i` and position :math:`j`.
.. _c09ba-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{wavnam}` not recognised: :math:`\mathrm{wavnam} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{wavnam} = \text{‘MORLET'}` and :math:`\mathrm{wparam} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{wavnam} = \text{‘MORLET'}`, :math:`5\leq \mathrm{wparam}\leq 20`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{wavnam} = \text{‘DGAUSS'}` and :math:`\mathrm{wparam} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: if :math:`\mathrm{wavnam} = \text{‘DGAUSS'}`, :math:`1\leq \mathrm{wparam}\leq 8`.
(`errno` :math:`3`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n\geq 2`.
(`errno` :math:`5`)
On entry, :math:`\textit{nscal} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{nscal}\geq 1`.
.. _c09ba-py2-py-notes:
**Notes**
``dim1_cont`` computes the real part of the one-dimensional, continuous wavelet transform
.. math::
C_{{s,k}} = \int_{\mathbb{R}}x\left(t\right)\frac{1}{\sqrt{s}}\psi^*\left(\frac{{t-k}}{s}\right)dt\text{,}
of a signal :math:`x\left(t\right)` at scale :math:`s` and position :math:`k`, where the signal is sampled discretely at :math:`n` equidistant points :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`. :math:`\psi` is the wavelet function, which can be chosen to be the Morlet wavelet, the derivatives of a Gaussian or the Mexican hat wavelet (:math:`*` denotes the complex conjugate).
The integrals of the scaled, shifted wavelet function are approximated and the convolution is then computed.
The mother wavelets supplied for use with this function are defined as follows.
(1) The Morlet wavelet (real part) with nondimensional wave number :math:`\kappa` is
.. math::
\psi \left(x\right) = \frac{1}{{\pi^{{1/4}}}}\left(\mathrm{cos}\left(\kappa x\right)-e^{{-\kappa^2/2}}\right)e^{{-x^2/2}}\text{,}
where the correction term, :math:`e^{{-\kappa^2/2}}` (required to satisfy the admissibility condition) is included.
(#) The derivatives of a Gaussian are obtained from
.. math::
\hat{\psi }^{\left(m\right)}\left(x\right) = \frac{{\mathrm{d}^m\left(e^{{-x^2}}\right)}}{{\mathrm{d}x^m}}\text{,}
taking :math:`m = 1,\ldots,8`. These are the Hermite polynomials multiplied by the Gaussian. The sign is then adjusted to give :math:`\hat{\psi }^{\left(m\right)}\left(0\right) > 0` when :math:`m` is even while the sign of the succeeding odd derivative, :math:`\hat{\psi }^{\left(m+1\right)}`, is made consistent with the preceding even numbered derivative. They are normalized by the :math:`L^2`-norm,
.. math::
p_m = \left(\int_{{-\infty }}^{\infty }\left[\hat{\psi }^{\left(m\right)}\left(x\right)\right]^2\mathrm{d}x\right)^{{1/2}}
The resulting normalized derivatives can be written in terms of the Hermite polynomials, :math:`H_m\left(x\right)`, as
.. math::
\psi^{\left(m\right)}\left(x\right) = \frac{{\alpha H_m\left(x\right)e^{{-x^2}}}}{p_m}\text{,}
where
.. math::
\alpha = \left\{\begin{array}{cc}1\text{,}&\text{when }m = 0,\mathrm{mod}\left(3, 4\right)\text{;}\\-1\text{,}&\text{when }m = 1,\mathrm{mod}\left(2, 4\right)\text{.}\end{array}\right.
Thus, the derivatives of a Gaussian provided here are,
.. math::
\psi^{\left(1\right)}\left(x\right) = -\left(\frac{2}{\pi }\right)^{{1/4}}2xe^{{-x^2}}\text{,}
.. math::
\psi^{\left(2\right)}\left(x\right) = -\left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{\sqrt{3}}\left(4x^2-2\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(3\right)}\left(x\right) = \left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{\sqrt{15}}\left(8x^3-12x\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(4\right)}\left(x\right) = \left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{\sqrt{105}}\left(16x^4-48x^2+12\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(5\right)}\left(x\right) = -\left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{{3\sqrt{105}}}\left(32x^5-160x^3+120x\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(6\right)}\left(x\right) = -\left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{{3\sqrt{1155}}}\left(64x^6-480x^4+720x^2-120\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(7\right)}\left(x\right) = \left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{{3\sqrt{15015}}}\left(128x^7-1344x^5+3360x^3-1680x\right)e^{{-x^2}}\text{,}
.. math::
\psi^{\left(8\right)}\left(x\right) = \left(\frac{2}{\pi }\right)^{{1/4}}\frac{1}{{45\sqrt{1001}}}\left(256x^8-3584x^6+13440x^4-13440x^2+1680\right)e^{{-x^2}}\text{.}
(#) The second derivative of a Gaussian is known as the Mexican hat wavelet and is supplied as an additional function in the form
.. math::
\psi \left(x\right) = \frac{2}{\left(\sqrt{3}\pi^{{1/4}}\right)}\left(1-x^2\right)e^{{-x^2/2}}\text{.}
The remaining normalized derivatives of a Gaussian can be expressed as multiples of the exponential :math:`e^{{-t^2/2}}` by applying the substitution :math:`x = t/\sqrt{2}` followed by multiplication with the scaling factor, :math:`1/\sqrt[4]{2}`.
.. _c09ba-py2-py-references:
**References**
Daubechies, I, 1992, `Ten Lectures on Wavelets`, SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dim1_sngl_fwd(x, comm):
r"""
``dim1_sngl_fwd`` computes the one-dimensional discrete wavelet transform (DWT) at a single level.
The initialization function :meth:`dim1_init` must be called first to set up the DWT options.
.. _c09ca-py2-py-doc:
For full information please refer to the NAG Library document for c09ca
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09caf.html
.. _c09ca-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}` contains the input dataset :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**ca** : float, ndarray, shape :math:`\left(:\right)`
:math:`\mathrm{ca}[i-1]` contains the :math:`i`\ th approximation coefficient, :math:`C_a\left(\textit{i}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_c`.
**cd** : float, ndarray, shape :math:`\left(:\right)`
:math:`\mathrm{cd}[\textit{i}-1]` contains the :math:`\textit{i}`\ th detail coefficient, :math:`C_d\left(\textit{i}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_c`.
.. _c09ca-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{n}` is inconsistent with the value passed to the initialization function: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
Either the initialization function has not been called first or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘M'}` or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ca-py2-py-notes:
**Notes**
``dim1_sngl_fwd`` computes the one-dimensional DWT of a given input data array, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, at a single level.
For a chosen wavelet filter pair, the output coefficients are obtained by applying convolution and downsampling by two to the input, :math:`x`.
The approximation (or smooth) coefficients, :math:`C_a`, are produced by the low pass filter and the detail coefficients, :math:`C_d`, by the high pass filter.
To reduce distortion effects at the ends of the data array, several end extension methods are commonly used.
Those provided are: periodic or circular convolution end extension, half-point symmetric end extension, whole-point symmetric end extension or zero end extension.
The number :math:`n_c`, of coefficients :math:`C_a` or :math:`C_d` is returned by the initialization function :meth:`dim1_init`.
.. _c09ca-py2-py-references:
**References**
Daubechies, I, 1992, `Ten Lectures on Wavelets`, SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dim1_sngl_inv(ca, cd, n, comm):
r"""
``dim1_sngl_inv`` computes the inverse one-dimensional discrete wavelet transform (DWT) at a single level.
The initialization function :meth:`dim1_init` must be called first to set up the DWT options.
.. _c09cb-py2-py-doc:
For full information please refer to the NAG Library document for c09cb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09cbf.html
.. _c09cb-py2-py-parameters:
**Parameters**
**ca** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The :math:`n_c` approximation coefficients, :math:`C_a`. These will normally be the result of some transformation on the coefficients computed by :meth:`dim1_sngl_fwd`.
**cd** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The :math:`n_c` detail coefficients, :math:`C_d`. These will normally be the result of some transformation on the coefficients computed by :meth:`dim1_sngl_fwd`.
**n** : int
:math:`n`, the length of the original data array from which the wavelet coefficients were computed by :meth:`dim1_sngl_fwd` and the length of the data array :math:`\mathrm{y}` that is to be reconstructed by this function.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**y** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The reconstructed data based on approximation and detail coefficients :math:`C_a` and :math:`C_d` and the transform options supplied to the initialization function :meth:`dim1_init`.
.. _c09cb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, array dimension :math:`\textit{lenc}` not large enough: :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` but must be at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n}` is inconsistent with the value passed to the initialization function: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
Either the initialization function has not been called first or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘M'}` or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09cb-py2-py-notes:
**Notes**
``dim1_sngl_inv`` performs the inverse operation of :meth:`dim1_sngl_fwd`.
That is, given sets of :math:`n_c` approximation coefficients and detail coefficients, computed by :meth:`dim1_sngl_fwd` using a DWT as set up by the initialization function :meth:`dim1_init`, on a real data array of length :math:`n`, ``dim1_sngl_inv`` will reconstruct the data array :math:`y_i`, for :math:`\textit{i} = 1,2,\ldots,n`, from which the coefficients were derived.
"""
raise NotImplementedError
[docs]def dim1_multi_fwd(x, nwl, comm):
r"""
``dim1_multi_fwd`` computes the one-dimensional multi-level discrete wavelet transform (DWT).
The initialization function :meth:`dim1_init` must be called first to set up the DWT options.
.. _c09cc-py2-py-doc:
For full information please refer to the NAG Library document for c09cc
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09ccf.html
.. _c09cc-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}` contains the one-dimensional input dataset :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**nwl** : int
The number of levels, :math:`n_{\mathrm{fwd}}`, in the multi-level resolution to be performed.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
Let :math:`q\left(\textit{i}\right)` denote the number of coefficients (of each type) produced by the wavelet transform at level :math:`\textit{i}`, for :math:`\textit{i} = n_{\mathrm{fwd}},\ldots,1`. These values are returned in :math:`\mathrm{dwtlev}`. Setting :math:`k_1 = q\left(n_{\mathrm{fwd}}\right)` and :math:`k_{{\textit{j}+1}} = k_{\textit{j}}+q\left(n_{\mathrm{fwd}}-{\textit{j}+1}\right)`, for :math:`\textit{j} = 1,2,\ldots,n_{\mathrm{fwd}}`, the coefficients are stored as follows:
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,k_1`
Contains the level :math:`n_{\mathrm{fwd}}` approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_1+1,\ldots,k_2`
Contains the level :math:`n_{\mathrm{fwd}}` detail coefficients :math:`d_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_j+1,\ldots,k_{{j+1}}`
Contains the level :math:`n_{\mathrm{fwd}}-\textit{j}+1` detail coefficients, for :math:`\textit{j} = 2,3,\ldots,n_{\mathrm{fwd}}`.
**dwtlev** : int, ndarray, shape :math:`\left(\mathrm{nwl}+1\right)`
The number of transform coefficients at each level. :math:`\mathrm{dwtlev}[0]` and :math:`\mathrm{dwtlev}[1]` contain the number, :math:`q\left(n_{\mathrm{fwd}}\right)`, of approximation and detail coefficients respectively, for the final level of resolution (these are equal); :math:`\mathrm{dwtlev}[\textit{i}-1]` contains the number of detail coefficients, :math:`q\left(n_{\mathrm{fwd}}-\textit{i}+2\right)`, for the (:math:`n_{\mathrm{fwd}}-\textit{i}+2`)th level, for :math:`\textit{i} = 3,4,\ldots,n_{\mathrm{fwd}}+1`.
.. _c09cc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{n}` is inconsistent with the value passed to the initialization function: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl}` is larger than the maximum number of levels returned by the initialization function: :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`, maximum :math:`\text{} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwl}\geq 1`.
(`errno` :math:`7`)
Either the initialization function has not been called first or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`7`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09cc-py2-py-notes:
**Notes**
``dim1_multi_fwd`` computes the multi-level DWT of one-dimensional data.
For a given wavelet and end extension method, ``dim1_multi_fwd`` will compute a multi-level transform of a data array, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, using a specified number, :math:`n_{\mathrm{fwd}}`, of levels.
The number of levels specified, :math:`n_{\mathrm{fwd}}`, must be no more than the value :math:`l_{\mathrm{max}}` returned in :math:`\textit{nwlmax}` by the initialization function :meth:`dim1_init` for the given problem.
The transform is returned as a set of coefficients for the different levels (packed into a single array) and a representation of the multi-level structure.
The notation used here assigns level :math:`0` to the input dataset, :math:`x`, with level :math:`1` being the first set of coefficients computed, with the detail coefficients, :math:`d_1`, being stored while the approximation coefficients, :math:`a_1`, are used as the input to a repeat of the wavelet transform.
This process is continued until, at level :math:`n_{\mathrm{fwd}}`, both the detail coefficients, :math:`d_{n_{\mathrm{fwd}}}`, and the approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}` are retained.
The output array, :math:`C`, stores these sets of coefficients in reverse order, starting with :math:`a_{n_{\mathrm{fwd}}}` followed by :math:`d_{n_{\mathrm{fwd}}},d_{{n_{\mathrm{fwd}}-1}},\ldots,d_1`.
"""
raise NotImplementedError
[docs]def dim1_multi_inv(nwlinv, c, n, comm):
r"""
``dim1_multi_inv`` computes the inverse one-dimensional multi-level discrete wavelet transform (DWT).
This function reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by :meth:`dim1_multi_fwd` from an original set of data.
The initialization function :meth:`dim1_init` must be called first to set up the DWT options.
.. _c09cd-py2-py-doc:
For full information please refer to the NAG Library document for c09cd
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09cdf.html
.. _c09cd-py2-py-parameters:
**Parameters**
**nwlinv** : int
The number of levels to be used in the inverse multi-level transform. The number of levels must be less than or equal to :math:`n_{\mathrm{fwd}}`, which has the value of argument :math:`\textit{nwl}` as used in the computation of the wavelet coefficients using :meth:`dim1_multi_fwd`. The data will be reconstructed to level :math:`\left({\textit{nwl}}-\mathrm{nwlinv}\right)`, where level :math:`0` is the original input dataset provided to :meth:`dim1_multi_fwd`.
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The coefficients of a multi-level wavelet transform of the dataset.
Let :math:`q\left(\textit{i}\right)` be the number of coefficients (of each type) at level :math:`\textit{i}`, for :math:`\textit{i} = n_{\mathrm{fwd}},\ldots,1`.
Then, setting :math:`k_1 = q\left(n_{\mathrm{fwd}}\right)` and :math:`k_{{\textit{j}+1}} = k_{\textit{j}}+q\left(n_{\mathrm{fwd}}-\textit{j}+1\right)`, for :math:`\textit{j} = 1,2,\ldots,n_{\mathrm{fwd}}`, the coefficients are stored in :math:`\mathrm{c}` as follows:
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,k_1`
Contains the level :math:`n_{\mathrm{fwd}}` approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_1+1,\ldots,k_2`
Contains the level :math:`n_{\mathrm{fwd}}` detail coefficients :math:`d_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_j+1,\ldots,k_{{j+1}}`
Contains the level :math:`n_{\mathrm{fwd}}-\textit{j}+1` detail coefficients, for :math:`\textit{j} = 2,3,\ldots,n_{\mathrm{fwd}}`.
The values :math:`q\left(\textit{i}\right)`, for :math:`\textit{i} = n_{\mathrm{fwd}},\ldots,1`, are contained in :math:`\textit{dwtlev}` which is produced as output by a preceding call to :meth:`dim1_multi_fwd`.
See :meth:`dim1_multi_fwd` for details.
**n** : int
:math:`n`, the length of the data array, :math:`y`, to be reconstructed. For a full reconstruction of :math:`\textit{nwl}` levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim1_multi_fwd`, this must be the same as argument :math:`\textit{n}` used in the call to :meth:`dim1_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}`, this must be equal to :math:`{\textit{dwtlev}}[\mathrm{nwlinv}+1]`, as returned from :meth:`dim1_multi_fwd`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**y** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The dataset reconstructed from the multi-level wavelet transform coefficients and the transformation options supplied to the initialization function :meth:`dim1_init`.
.. _c09cd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv}` is larger than the number of levels computed by the preceding call to :meth:`dim1_multi_fwd`: :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`, expected :math:`\text{} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwlinv}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\textit{lenc}` is set too small: :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n}` is inconsistent with the value passed to the initialization function: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
Either the initialization function has not been called first or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09cd-py2-py-notes:
**Notes**
``dim1_multi_inv`` performs the inverse operation of :meth:`dim1_multi_fwd`.
That is, given a set of wavelet coefficients, computed up to level :math:`n_{\mathrm{fwd}}` by :meth:`dim1_multi_fwd` using a DWT as set up by the initialization function :meth:`dim1_init`, on a real data array of length :math:`n`, ``dim1_multi_inv`` will reconstruct the data array :math:`y_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, from which the coefficients were derived.
If the original input dataset is level :math:`0`, then it is possible to terminate reconstruction at a higher level by specifying fewer than the number of levels used in the call to :meth:`dim1_multi_fwd`.
This results in a partial reconstruction.
"""
raise NotImplementedError
[docs]def dim1_mxolap_fwd(x, comm):
r"""
``dim1_mxolap_fwd`` computes the one-dimensional maximal overlap discrete wavelet transform (MODWT) at a single level.
The initialization function :meth:`dim1_init` must be called first to set up the MODWT options.
.. _c09da-py2-py-doc:
For full information please refer to the NAG Library document for c09da
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09daf.html
.. _c09da-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}` contains the input dataset :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**ca** : float, ndarray, shape :math:`\left(:\right)`
:math:`\mathrm{ca}[i-1]` contains the :math:`i`\ th approximation coefficient, :math:`C_a\left(\textit{i}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_c`.
**cd** : float, ndarray, shape :math:`\left(:\right)`
:math:`\mathrm{cd}[\textit{i}-1]` contains the :math:`\textit{i}`\ th detail coefficient, :math:`C_d\left(\textit{i}\right)`, for :math:`\textit{i} = 1,2,\ldots,n_c`.
.. _c09da-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{n}` is inconsistent with the value passed to the initialization function: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
On entry, the initialization function :meth:`dim1_init` has not been called first or it has not been called with :math:`\mathrm{wtrans} = \text{‘T'}`, or the communication array :math:`\mathrm{comm}`\ ['icomm'] has become corrupted.
.. _c09da-py2-py-notes:
**Notes**
``dim1_mxolap_fwd`` computes the one-dimensional MODWT of a given input data array, :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, at a single level.
For a chosen wavelet filter pair, the output coefficients are obtained by applying convolution to the input, :math:`x`.
The approximation (or smooth) coefficients, :math:`C_a`, are produced by the low pass filter and the detail coefficients, :math:`C_d`, by the high pass filter.
Periodic (circular) convolution is available as an end extension method for application to finite data sets.
The number :math:`n_c`, of coefficients :math:`C_a` or :math:`C_d` is returned by the initialization function :meth:`dim1_init`.
.. _c09da-py2-py-references:
**References**
Percival, D B and Walden, A T, 2000, `Wavelet Methods for Time Series Analysis`, Cambridge University Press
"""
raise NotImplementedError
[docs]def dim1_mxolap_inv(ca, cd, n, comm):
r"""
``dim1_mxolap_inv`` computes the inverse one-dimensional maximal overlap discrete wavelet transform (MODWT) at a single level.
The initialization function :meth:`dim1_init` must be called first to set up the MODWT options.
.. _c09db-py2-py-doc:
For full information please refer to the NAG Library document for c09db
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09dbf.html
.. _c09db-py2-py-parameters:
**Parameters**
**ca** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The :math:`n_c` approximation coefficients, :math:`C_a`. These will normally be the result of some transformation on the coefficients computed by :meth:`dim1_mxolap_fwd`.
**cd** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The :math:`n_c` detail coefficients, :math:`C_d`. These will normally be the result of some transformation on the coefficients computed by :meth:`dim1_mxolap_fwd`.
**n** : int
:math:`n`, the length of the original data array from which the wavelet coefficients were computed by :meth:`dim1_mxolap_fwd` and the length of the data array :math:`\mathrm{y}` that is to be reconstructed by this function.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**y** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The reconstructed data based on approximation and detail coefficients :math:`C_a` and :math:`C_d` and the transform options supplied to the initialization function :meth:`dim1_init`.
.. _c09db-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, array dimension :math:`\textit{lenc}` not large enough: :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` but must be at least :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n}` is inconsistent with the value passed to the initialization function: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
On entry, the initialization function :meth:`dim1_init` has not been called first or it has not been called with :math:`\mathrm{wtrans} = \text{‘T'}`, or the communication array :math:`\mathrm{comm}`\ ['icomm'] has become corrupted.
.. _c09db-py2-py-notes:
**Notes**
``dim1_mxolap_inv`` performs the inverse operation of :meth:`dim1_mxolap_fwd`.
That is, given sets of :math:`n_c` approximation coefficients and detail coefficients, computed by :meth:`dim1_mxolap_fwd` using a MODWT as set up by the initialization function :meth:`dim1_init`, on a real data array of length :math:`n`, ``dim1_mxolap_inv`` will reconstruct the data array :math:`y_i`, for :math:`\textit{i} = 1,2,\ldots,n`, from which the coefficients were derived.
.. _c09db-py2-py-references:
**References**
Percival, D B and Walden, A T, 2000, `Wavelet Methods for Time Series Analysis`, Cambridge University Press
"""
raise NotImplementedError
[docs]def dim1_mxolap_multi_fwd(x, keepa, nwl, comm):
r"""
``dim1_mxolap_multi_fwd`` computes the one-dimensional multi-level maximal overlap discrete wavelet transform (MODWT).
The initialization function :meth:`dim1_init` must be called first to set up the MODWT options.
.. _c09dc-py2-py-doc:
For full information please refer to the NAG Library document for c09dc
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09dcf.html
.. _c09dc-py2-py-parameters:
**Parameters**
**x** : float, array-like, shape :math:`\left(n\right)`
:math:`\mathrm{x}` contains the input dataset :math:`x_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`.
**keepa** : str, length 1
Determines whether the approximation coefficients are stored in array :math:`\mathrm{c}` for every level of the computed transform or else only for the final level. In both cases, the detail coefficients are stored in :math:`\mathrm{c}` for every level computed.
:math:`\mathrm{keepa} = \text{‘A'}`
Retain approximation coefficients for all levels computed.
:math:`\mathrm{keepa} = \text{‘F'}`
Retain approximation coefficients for only the final level computed.
**nwl** : int
The number of levels, :math:`n_l`, in the multi-level resolution to be performed.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
The coefficients of a multi-level wavelet transform of the dataset.
The coefficients are stored in :math:`\mathrm{c}` as follows:
If :math:`\mathrm{keepa} = \text{‘F'}`,
:math:`\mathrm{c}[0:n_a]`
Contains the level :math:`n_l` approximation coefficients;
:math:`\mathrm{c}[ {n_a+\left(i-1\right)\times n_d+1} -1: {n_a+i\times n_d} ]`
Contains the level :math:`\left(n_l-\textit{i}+1\right)` detail coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`;
If :math:`\mathrm{keepa} = \text{‘A'}`,
:math:`\mathrm{c}[ {\left(i-1\right)\times n_a+1} -1: {i\times n_a} ]`
Contains the level :math:`\left(n_l-\textit{i}+1\right)` approximation coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`;
:math:`\mathrm{c}[ {n_l\times n_a+\left(i-1\right)\times n_d+1} -1: {n_l\times n_a+i\times n_d} ]`
Contains the level i detail coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`;
The values :math:`n_a` and :math:`n_d` denote the numbers of approximation and detail coefficients respectively, which are equal and returned in :math:`\mathrm{na}`.
**na** : int
:math:`\mathrm{na}` contains the number of approximation coefficients, :math:`n_a`, at each level which is equal to the number of detail coefficients, :math:`n_d`. With periodic end extension (:math:`\mathrm{mode} = \text{‘P'}` in :meth:`dim1_init`) this is the same as the length, :math:`\textit{n}`, of the data array, :math:`\mathrm{x}`.
.. _c09dc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{n}` is inconsistent with the value passed to the initialization function: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{nwl}` is larger than the maximum number of levels returned by the initialization function: :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`, maximum = :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`6`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwl}\geq 1`.
(`errno` :math:`8`)
On entry, the initialization function :meth:`dim1_init` has not been called first or it has not been called with :math:`\mathrm{wtrans} = \text{‘U'}`, or the communication array :math:`\mathrm{comm}`\ ['icomm'] has become corrupted.
(`errno` :math:`31`)
On entry, :math:`\mathrm{keepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{keepa} = \text{‘F'} \text{ or } \text{‘A'}`.
.. _c09dc-py2-py-notes:
**Notes**
``dim1_mxolap_multi_fwd`` computes the multi-level MODWT for a data set, :math:`\textit{x}_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, in one dimension.
For a chosen number of levels, :math:`n_l`, with :math:`n_l\leq l_{\mathrm{max}}`, where :math:`l_{\mathrm{max}}` is returned by the initialization function :meth:`dim1_init` in :math:`\textit{nwlmax}`, the transform is returned as a set of coefficients for the different levels stored in a single array.
Periodic reflection is currently the only available end extension method to reduce the edge effects caused by finite data sets.
The argument :math:`\mathrm{keepa}` can be set to retain both approximation and detail coefficients at each level resulting in :math:`n_l\times \left(n_a+n_d\right)` coefficients being returned in the output array, :math:`\mathrm{c}`, where :math:`n_a` is the number of approximation coefficients and :math:`n_d` is the number of detail coefficients.
Otherwise, only the detail coefficients are stored for each level along with the approximation coefficients for the final level, in which case the length of the output array, :math:`\mathrm{c}`, is :math:`n_a+n_l\times n_d`.
In the present implementation, for simplicity, :math:`n_a` and :math:`n_d` are chosen to be equal by adding zero padding to the wavelet filters where necessary.
.. _c09dc-py2-py-references:
**References**
Percival, D B and Walden, A T, 2000, `Wavelet Methods for Time Series Analysis`, Cambridge University Press
"""
raise NotImplementedError
[docs]def dim1_mxolap_multi_inv(nwlinv, keepa, c, n, comm):
r"""
``dim1_mxolap_multi_inv`` computes the inverse one-dimensional multi-level maximal overlap discrete wavelet transform (MODWT).
This function reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by :meth:`dim1_mxolap_multi_fwd` from an original set of data.
The initialization function :meth:`dim1_init` must be called first to set up the MODWT options.
.. _c09dd-py2-py-doc:
For full information please refer to the NAG Library document for c09dd
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09ddf.html
.. _c09dd-py2-py-parameters:
**Parameters**
**nwlinv** : int
The number of levels to be used in the inverse multi-level transform. The number of levels must be less than or equal to :math:`n_{\mathrm{fwd}}`, which has the value of argument :math:`\textit{nwl}` as used in the computation of the wavelet coefficients using :meth:`dim1_mxolap_multi_fwd`. The data will be reconstructed to level :math:`\left({\textit{nwl}}-\mathrm{nwlinv}\right)`, where level :math:`0` is the original input dataset provided to :meth:`dim1_mxolap_multi_fwd`.
**keepa** : str, length 1
Determines whether the approximation coefficients are stored in array :math:`\mathrm{c}` for every level of the computed transform or else only for the final level. In both cases, the detail coefficients are stored in :math:`\mathrm{c}` for every level computed.
:math:`\mathrm{keepa} = \text{‘A'}`
Retain approximation coefficients for all levels computed.
:math:`\mathrm{keepa} = \text{‘F'}`
Retain approximation coefficients for only the final level computed.
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The coefficients of a multi-level wavelet transform of the dataset.
The coefficients are stored in :math:`\mathrm{c}` as follows:
If :math:`\mathrm{keepa} = \text{‘F'}`,
:math:`\mathrm{c}[0:n_a]`
Contains the level :math:`n_l` approximation coefficients;
:math:`\mathrm{c}[ n_a + \left(i-1\right)\times n_d+1 -1: n_a+i\times n_d ]`
Contains the level :math:`\left(n_l-\textit{i}+1\right)` detail coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`;
If :math:`\mathrm{keepa} = \text{‘A'}`,
:math:`\mathrm{c}[\left(i-1\right) \times n_a:i\times n_a]`
Contains the level :math:`\left(n_l-\textit{i}+1\right)` approximation coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`;
:math:`\mathrm{c}[n_l \times n_a+\left(i-1\right) \times n_d:n_l \times n_a+i\times n_d]`
Contains the level :math:`\textit{i}` detail coefficients, for :math:`\textit{i} = 1,2,\ldots,n_l`.
The values :math:`n_a` and :math:`n_d` denote the numbers of approximation and detail coefficients respectively, which are equal.
This number is returned as output in :math:`\textit{na}` from a preceding call to :meth:`dim1_mxolap_multi_fwd`.
See :meth:`dim1_mxolap_multi_fwd` for details.
**n** : int
:math:`n`, the length of the data array, :math:`y`, to be reconstructed.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim1_init`.
**Returns**
**y** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
The dataset reconstructed from the multi-level wavelet transform coefficients and the transformation options supplied to the initialization function :meth:`dim1_init`.
.. _c09dd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv}` is larger than the number of levels computed by the preceding call to :meth:`dim1_mxolap_multi_fwd`: :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`, expected :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwlinv}\geq 1`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc}` is set too small: :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc} \geq \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{n}` is inconsistent with the value passed to the initialization function: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{n}` should be :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`7`)
On entry, the initialization function :meth:`dim1_init` has not been called first or it has not been called with :math:`\mathrm{wtrans} = \text{‘U'}`, or the communication array :math:`\mathrm{comm}`\ ['icomm'] has become corrupted.
(`errno` :math:`21`)
On entry, :math:`\mathrm{keepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{keepa} = \text{‘F'} \text{ or } \text{‘A'}`.
.. _c09dd-py2-py-notes:
**Notes**
``dim1_mxolap_multi_inv`` performs the inverse operation of :meth:`dim1_mxolap_multi_fwd`.
That is, given a set of wavelet coefficients computed by :meth:`dim1_mxolap_multi_fwd` using a MODWT as set up by the initialization function :meth:`dim1_init` on a real array of length :math:`n`, ``dim1_mxolap_multi_inv`` will reconstruct the data array :math:`y_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,n`, from which the coefficients were derived.
.. _c09dd-py2-py-references:
**References**
Percival, D B and Walden, A T, 2000, `Wavelet Methods for Time Series Analysis`, Cambridge University Press
"""
raise NotImplementedError
[docs]def dim2_sngl_fwd(a, comm):
r"""
``dim2_sngl_fwd`` computes the two-dimensional discrete wavelet transform (DWT) at a single level.
The initialization function :meth:`dim2_init` must be called first to set up the DWT options.
.. _c09ea-py2-py-doc:
For full information please refer to the NAG Library document for c09ea
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09eaf.html
.. _c09ea-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` data matrix :math:`A`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**ca** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of approximation coefficients, :math:`C_a`.
**ch** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of horizontal coefficients, :math:`C_h`.
**cv** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of vertical coefficients, :math:`C_v`.
**cd** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of diagonal coefficients, :math:`C_d`.
.. _c09ea-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{n}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{m}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘M'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ea-py2-py-notes:
**Notes**
``dim2_sngl_fwd`` computes the two-dimensional DWT of a given input data array, considered as a matrix :math:`A`, at a single level.
For a chosen wavelet filter pair, the output coefficients are obtained by applying convolution and downsampling by two to the input, :math:`A`, first over columns and then to the result over rows.
The matrix of approximation (or smooth) coefficients, :math:`C_a`, is produced by the low pass filter over columns and rows; the matrix of horizontal coefficients, :math:`C_h`, is produced by the high pass filter over columns and the low pass filter over rows; the matrix of vertical coefficients, :math:`C_v`, is produced by the low pass filter over columns and the high pass filter over rows; and the matrix of diagonal coefficients, :math:`C_d`, is produced by the high pass filter over columns and rows.
To reduce distortion effects at the ends of the data array, several end extension methods are commonly used.
Those provided are: periodic or circular convolution end extension, half-point symmetric end extension, whole-point symmetric end extension and zero end extension.
The total number, :math:`n_{\textit{ct}}`, of coefficients computed for :math:`C_a`, :math:`C_h`, :math:`C_v`, and :math:`C_d` together and the number of columns of each coefficients matrix, :math:`n_{\textit{cn}}`, are returned by the initialization function :meth:`dim2_init`.
These values can be used to calculate the number of rows of each coefficients matrix, :math:`n_{\textit{cm}}`, using the formula :math:`n_{\textit{cm}} = n_{\textit{ct}}/\left(4n_{\textit{cn}}\right)`.
.. _c09ea-py2-py-references:
**References**
Daubechies, I, 1992, `Ten Lectures on Wavelets`, SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dim2_sngl_inv(m, n, ca, ch, cv, cd, comm):
r"""
``dim2_sngl_inv`` computes the inverse two-dimensional discrete wavelet transform (DWT) at a single level.
The initialization function :meth:`dim2_init` must be called first to set up the DWT options.
.. _c09eb-py2-py-doc:
For full information please refer to the NAG Library document for c09eb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09ebf.html
.. _c09eb-py2-py-parameters:
**Parameters**
**m** : int
Number of rows, :math:`m`, of data matrix :math:`B`.
**n** : int
Number of columns, :math:`n`, of data matrix :math:`B`.
**ca** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of approximation coefficients, :math:`C_a`. This array will normally be the result of some transformation on the coefficients computed by function :meth:`dim2_sngl_fwd`.
**ch** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of horizontal coefficients, :math:`C_h`. This array will normally be the result of some transformation on the coefficients computed by function :meth:`dim2_sngl_fwd`.
**cv** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of vertical coefficients, :math:`C_v`. This array will normally be the result of some transformation on the coefficients computed by function :meth:`dim2_sngl_fwd`.
**cd** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
Contains the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` matrix of diagonal coefficients, :math:`C_d`. This array will normally be the result of some transformation on the coefficients computed by function :meth:`dim2_sngl_fwd`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**b** : float, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}\right)`
The :math:`m\times n` reconstructed matrix, :math:`B`, based on the input approximation, horizontal, vertical and diagonal coefficients and the transform options supplied to the initialization function :meth:`dim2_init`.
.. _c09eb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{n}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`4`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{m}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘M'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09eb-py2-py-notes:
**Notes**
``dim2_sngl_inv`` performs the inverse operation of function :meth:`dim2_sngl_fwd`.
That is, given sets of approximation, horizontal, vertical and diagonal coefficients computed by function :meth:`dim2_sngl_fwd` using a DWT as set up by the initialization function :meth:`dim2_init`, on a real matrix, :math:`B`, ``dim2_sngl_inv`` will reconstruct :math:`B`.
"""
raise NotImplementedError
[docs]def dim2_multi_fwd(a, nwl, comm):
r"""
``dim2_multi_fwd`` computes the two-dimensional multi-level discrete wavelet transform (DWT).
The initialization function :meth:`dim2_init` must be called first to set up the DWT options.
.. _c09ec-py2-py-doc:
For full information please refer to the NAG Library document for c09ec
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09ecf.html
.. _c09ec-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` data matrix :math:`A`.
**nwl** : int
The number of levels, :math:`n_{\mathrm{fwd}}`, in the multi-level resolution to be performed.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
The coefficients of the discrete wavelet transform. If you need to access or modify the approximation coefficients or any specific set of detail coefficients then the use of :meth:`dim2_coeff_ext` or :meth:`dim2_coeff_ins` is recommended. For completeness the following description provides details of precisely how the coefficient are stored in :math:`\mathrm{c}` but this information should only be required in rare cases.
Let :math:`q\left(\textit{i}\right)` denote the number of coefficients (of each type) at level :math:`\textit{i}`, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`, such that :math:`q\left(i\right) = \mathrm{dwtlvm}[ n_{\mathrm{fwd}} - i + 1 -1]\times \mathrm{dwtlvn}[ n_{\mathrm{fwd}} - i + 1 -1]`.
Then, letting :math:`k_1 = q\left(n_{\mathrm{fwd}}\right)` and :math:`k_{{\textit{j}+1}} = k_{\textit{j}}+q\left(n_{\mathrm{fwd}}-\left\lceil \textit{j}/3\right\rceil +1\right)`, for :math:`\textit{j} = 1,2,\ldots,3n_{\mathrm{fwd}}`, the coefficients are stored in :math:`\mathrm{c}` as follows:
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,k_1`
Contains the level :math:`n_{\mathrm{fwd}}` approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_j+1,\ldots,k_{{j+1}}`
Contains the level :math:`n_{\mathrm{fwd}}-\left\lceil j/3\right\rceil +1` vertical, horizontal and diagonal coefficients. These are:
vertical coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 1`;
horizontal coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 2`;
diagonal coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 0`,
for :math:`j = 1,\ldots,3n_{\mathrm{fwd}}`.
**dwtlvm** : int, ndarray, shape :math:`\left(\mathrm{nwl}\right)`
The number of coefficients in the first dimension for each coefficient type at each level. :math:`\mathrm{dwtlvm}[\textit{i}-1]` contains the number of coefficients in the first dimension (for each coefficient type computed) at the (:math:`n_{\mathrm{fwd}}-\textit{i}+1`)th level of resolution, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`. Thus for the first :math:`n_{\mathrm{fwd}}-1` levels of resolution, :math:`\mathrm{dwtlvm}[{n_{\mathrm{fwd}}-\textit{i}+1}-1]` is the size of the first dimension of the matrices of vertical, horizontal and diagonal coefficients computed at this level; for the final level of resolution, :math:`\mathrm{dwtlvm}[0]` is the size of the first dimension of the matrices of approximation, vertical, horizontal and diagonal coefficients computed.
**dwtlvn** : int, ndarray, shape :math:`\left(\mathrm{nwl}\right)`
The number of coefficients in the second dimension for each coefficient type at each level. :math:`\mathrm{dwtlvn}[\textit{i}-1]` contains the number of coefficients in the second dimension (for each coefficient type computed) at the (:math:`n_{\mathrm{fwd}}-\textit{i}+1`)th level of resolution, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`. Thus for the first :math:`n_{\mathrm{fwd}}-1` levels of resolution, :math:`\mathrm{dwtlvn}[{n_{\mathrm{fwd}}-\textit{i}+1}-1]` is the size of the second dimension of the matrices of vertical, horizontal and diagonal coefficients computed at this level; for the final level of resolution, :math:`\mathrm{dwtlvn}[0]` is the size of the second dimension of the matrices of approximation, vertical, horizontal and diagonal coefficients computed.
.. _c09ec-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{n}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{m}` on initialization (see :meth:`dim2_init`).
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwlmax}} = \langle\mathit{\boldsymbol{value}}\rangle` in :meth:`dim2_init`.
Constraint: :math:`\mathrm{nwl}\leq {\textit{nwlmax}}` in :meth:`dim2_init`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwl}\geq 1`.
(`errno` :math:`7`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`7`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ec-py2-py-notes:
**Notes**
``dim2_multi_fwd`` computes the multi-level DWT of two-dimensional data.
For a given wavelet and end extension method, ``dim2_multi_fwd`` will compute a multi-level transform of a matrix :math:`A`, using a specified number, :math:`n_{\mathrm{fwd}}`, of levels.
The number of levels specified, :math:`n_{\mathrm{fwd}}`, must be no more than the value :math:`l_{\mathrm{max}}` returned in :math:`\textit{nwlmax}` by the initialization function :meth:`dim2_init` for the given problem.
The transform is returned as a set of coefficients for the different levels (packed into a single array) and a representation of the multi-level structure.
The notation used here assigns level :math:`0` to the input matrix, :math:`A`.
Level 1 consists of the first set of coefficients computed: the vertical (:math:`v_1`), horizontal (:math:`h_1`) and diagonal (:math:`d_1`) coefficients are stored at this level while the approximation (:math:`a_1`) coefficients are used as the input to a repeat of the wavelet transform at the next level.
This process is continued until, at level :math:`n_{\mathrm{fwd}}`, all four types of coefficients are stored.
The output array, :math:`C`, stores these sets of coefficients in reverse order, starting with :math:`a_{n_{\mathrm{fwd}}}` followed by :math:`v_{n_{\mathrm{fwd}}},h_{n_{\mathrm{fwd}}},d_{n_{\mathrm{fwd}}},v_{{n_{\mathrm{fwd}}-1}},h_{{n_{\mathrm{fwd}}-1}},d_{{n_{\mathrm{fwd}}-1}},\ldots,v_1,h_1,d_1`.
"""
raise NotImplementedError
[docs]def dim2_multi_inv(nwlinv, c, m, n, comm):
r"""
``dim2_multi_inv`` computes the inverse two-dimensional multi-level discrete wavelet transform (DWT).
This function reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by :meth:`dim2_multi_fwd` from an original input matrix.
The initialization function :meth:`dim2_init` must be called first to set up the DWT options.
.. _c09ed-py2-py-doc:
For full information please refer to the NAG Library document for c09ed
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09edf.html
.. _c09ed-py2-py-parameters:
**Parameters**
**nwlinv** : int
The number of levels to be used in the inverse multi-level transform. The number of levels must be less than or equal to :math:`n_{\mathrm{fwd}}`, which has the value of argument :math:`\textit{nwl}` as used in the computation of the wavelet coefficients using :meth:`dim2_multi_fwd`. The data will be reconstructed to level :math:`\left({\textit{nwl}}-\mathrm{nwlinv}\right)`, where level :math:`0` is the original input dataset provided to :meth:`dim2_multi_fwd`.
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The coefficients of a multi-level wavelet transform of the original matrix, :math:`A`, which may have been filtered or otherwise manipulated.
Let :math:`q\left(\textit{i}\right)` be the number of coefficients (of each type) at level :math:`\textit{i}`, for :math:`\textit{i} = n_{\mathrm{fwd}},\ldots,1`.
Then, setting :math:`k_1 = q\left(n_{\mathrm{fwd}}\right)` and :math:`k_{{j+1}} = k_j+q\left(n_{\mathrm{fwd}}-\left\lceil j/3\right\rceil +1\right)`, for :math:`j = 1,2,\ldots,3n_{\mathrm{fwd}}`, the coefficients are stored in :math:`\mathrm{c}` as follows:
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,k_1`
Contains the level :math:`n_{\mathrm{fwd}}` approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_j+1,\ldots,k_{{j+1}}`
Contains the level :math:`n_{\mathrm{fwd}}-\left\lceil j/3\right\rceil +1` vertical, horizontal and diagonal coefficients. These are:
vertical coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 1`;
horizontal coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 2`;
diagonal coefficients if :math:`\mathrm{mod}\left(j, 3\right) = 0`,
for :math:`j = 1,\ldots,3n_{\mathrm{fwd}}`.
Note that the coefficients in :math:`\mathrm{c}` may be extracted according to level and type into two-dimensional arrays using :meth:`dim2_coeff_ext`, and inserted using :meth:`dim2_coeff_ins`.
**m** : int
The number of elements, :math:`m`, in the first dimension of the reconstructed matrix :math:`B`. For a full reconstruction of :math:`\textit{nwl}` levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim2_multi_fwd`, this must be the same as argument :math:`\textit{m}` used in the call to :meth:`dim2_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}` levels, this must be equal to :math:`{\textit{dwtlvm}}[\mathrm{nwlinv}]`, as returned from :meth:`dim2_multi_fwd`.
**n** : int
The number of elements, :math:`n`, in the second dimension of the reconstructed matrix :math:`B`. For a full reconstruction of :math:`\textit{nwl}` levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim3_multi_fwd`, this must be the same as argument :math:`\textit{n}` used in the call to :meth:`dim2_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}`, this must be equal to :math:`{\textit{dwtlvn}}[\mathrm{nwlinv}]`, as returned from :meth:`dim2_multi_fwd`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**b** : float, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}\right)`
The :math:`m\times n` reconstructed matrix, :math:`B`, based on the input multi-level wavelet transform coefficients and the transform options supplied to the initialization function :meth:`dim2_init`.
.. _c09ed-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\mathrm{fwd}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwlinv}\leq n_{\mathrm{fwd}}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwlinv}\geq 1`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the total number of coefficients generated by the preceding call to :meth:`dim2_multi_fwd`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of coefficients in the second dimension at the required level of reconstruction.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of coefficients in the first dimension at the required level of reconstruction.
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ed-py2-py-notes:
**Notes**
``dim2_multi_inv`` performs the inverse operation of :meth:`dim2_multi_fwd`.
That is, given a set of wavelet coefficients, computed up to level :math:`n_{\mathrm{fwd}}` by :meth:`dim2_multi_fwd` using a DWT as set up by the initialization function :meth:`dim2_init`, on a real matrix, :math:`A`, ``dim2_multi_inv`` will reconstruct :math:`A`.
The reconstructed matrix is referred to as :math:`B` in the following since it will not be identical to :math:`A` when the DWT coefficients have been filtered or otherwise manipulated prior to reconstruction.
If the original input matrix is level :math:`0`, then it is possible to terminate reconstruction at a higher level by specifying fewer than the number of levels used in the call to :meth:`dim2_multi_fwd`.
This results in a partial reconstruction.
"""
raise NotImplementedError
[docs]def dim2_coeff_ext(ilev, cindex, c, comm):
r"""
``dim2_coeff_ext`` extracts a selected set of discrete wavelet transform (DWT) coefficients from the full set of coefficients stored in compact form, as computed by :meth:`dim2_multi_fwd` (two-dimensional DWT).
.. _c09ey-py2-py-doc:
For full information please refer to the NAG Library document for c09ey
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09eyf.html
.. _c09ey-py2-py-parameters:
**Parameters**
**ilev** : int
The level at which coefficients are to be extracted.
**cindex** : int
Identifies which coefficients to extract. The coefficients are identified as follows:
:math:`\mathrm{cindex} = 0`
The approximation coefficients, produced by application of the low pass filter over columns and rows of the original matrix (LL). The approximation coefficients are available only for :math:`\mathrm{ilev} = {\textit{nwl}}`, where :math:`\textit{nwl}` is the value used in a preceding call to :meth:`dim2_multi_fwd`.
:math:`\mathrm{cindex} = 1`
The vertical detail coefficients produced by applying the low pass filter over columns of the original matrix and the high pass filter over rows (LH).
:math:`\mathrm{cindex} = 2`
The horizontal detail coefficients produced by applying the high pass filter over columns of the original matrix and the low pass filter over rows (HL).
:math:`\mathrm{cindex} = 3`
The diagonal detail coefficients produced by applying the high pass filter over columns and rows of the original matrix (HH).
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
DWT coefficients, as computed by a preceding call to :meth:`dim2_multi_fwd`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**d** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
The requested coefficients.
If :math:`\mathrm{ilev} = {\textit{nwl}}` (as used in :meth:`dim2_multi_fwd`) and :math:`\mathrm{cindex} = 0`, the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` approximation coefficients :math:`a_{{ij}}` are stored in :math:`\mathrm{d}[i-1,\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
Otherwise the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` level :math:`\mathrm{ilev}` detail coefficients (of type specified by :math:`\mathrm{cindex}`) :math:`d_{{ij}}` are stored in :math:`\mathrm{d}[i-1,\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
.. _c09ey-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\leq {\textit{nwl}}`, where :math:`\textit{nwl}` is the number of levels used in the call to :meth:`dim2_multi_fwd`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\geq 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\leq 3`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in a previous call to :meth:`dim2_multi_fwd`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`, but :math:`\mathrm{cindex} = 0`.
Constraint: :math:`\mathrm{cindex} > 0` when :math:`\mathrm{ilev} < {\textit{nwl}}` in the preceding call to :meth:`dim2_multi_fwd`.
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ey-py2-py-notes:
**Notes**
``dim2_coeff_ext`` is intended to be used after a call to :meth:`dim2_multi_fwd` (two-dimensional DWT), which in turn should be preceded by a call to :meth:`dim2_init` (two-dimensional wavelet filter initialization).
Given an initial two-dimensional data set :math:`A`, a prior call to :meth:`dim2_multi_fwd` computes the approximation coefficients (at the highest requested level) and three sets of detail coefficients at all levels and stores these in compact form in a one-dimensional array :math:`\mathrm{c}`. ``dim2_coeff_ext`` can then extract either the approximation coefficients or one of the sets of detail coefficients at one of the levels into a matrix :math:`D`.
The dimensions of :math:`D` depend on the level extracted and are available from the arrays :math:`\textit{dwtlvm}` and :math:`\textit{dwtlvn}` as returned by :meth:`dim2_multi_fwd` which contain the first and second dimensions respectively.
See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html#background1>`__ for a discussion of the two-dimensional DWT.
"""
raise NotImplementedError
[docs]def dim2_coeff_ins(ilev, cindex, c, d, comm):
r"""
``dim2_coeff_ins`` inserts a selected set of two-dimensional discrete wavelet transform (DWT) coefficients into the full set of coefficients stored in compact form, which may be later used as input to the multi-level reconstruction function :meth:`dim2_multi_inv`.
.. _c09ez-py2-py-doc:
For full information please refer to the NAG Library document for c09ez
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09ezf.html
.. _c09ez-py2-py-parameters:
**Parameters**
**ilev** : int
The level at which coefficients are to be inserted.
**cindex** : int
Identifies which coefficients to insert. The coefficients are identified as follows:
:math:`\mathrm{cindex} = 0`
The approximation coefficients, produced by application of the low pass filter over columns and rows of the original matrix (LL). The approximation coefficients are present only for :math:`\mathrm{ilev} = {\textit{nwl}}`, where :math:`\textit{nwl}` is the value used in a preceding call to :meth:`dim2_multi_fwd`.
:math:`\mathrm{cindex} = 1`
The vertical detail coefficients produced by applying the low pass filter over columns of the original matrix and the high pass filter over rows (LH).
:math:`\mathrm{cindex} = 2`
The horizontal detail coefficients produced by applying the high pass filter over columns of the original matrix and the low pass filter over rows (HL).
:math:`\mathrm{cindex} = 3`
The diagonal detail coefficients produced by applying the high pass filter over columns and rows of the original matrix (HH).
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
Contains the DWT coefficients inserted by previous calls to ``dim2_coeff_ins``, or computed by a previous call to :meth:`dim2_multi_fwd`.
**d** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}\right)`
The coefficients to be inserted.
If :math:`\mathrm{ilev} = {\textit{nwl}}` (as used in :meth:`dim2_multi_fwd`) and :math:`\mathrm{cindex} = 0`, the :math:`n_{{\textit{cm}}}\times n_{\textit{cn}}` manipulated approximation coefficients :math:`a_{{\textit{i}\textit{j}}}` must be stored in :math:`\mathrm{d}[\textit{i}-1,\textit{j}-1]`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
Otherwise the :math:`n_{\textit{cm}}\times n_{\textit{cn}}` manipulated level :math:`\mathrm{ilev}` detail coefficients (of type specified by :math:`\mathrm{cindex}`) :math:`d_{{\textit{i}\textit{j}}}` must be stored in :math:`\mathrm{d}[\textit{i}-1,\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim2_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
Contains the same DWT coefficients provided on entry except for those identified by :math:`\mathrm{ilev}` and :math:`\mathrm{cindex}`, which are updated with the values supplied in :math:`\mathrm{d}`, inserted into the correct locations as expected by the reconstruction function :meth:`dim2_multi_inv`.
.. _c09ez-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\leq {\textit{nwl}}`, where :math:`{\textit{nwl}}` is the number of levels used in the call to :meth:`dim2_multi_fwd`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\geq 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\leq 3`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in a previous call to :meth:`dim2_multi_fwd`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`, but :math:`\mathrm{cindex} = 0`.
Constraint: :math:`\mathrm{cindex} > 0` when :math:`\mathrm{ilev} < {\textit{nwl}}` in the preceding call to :meth:`dim2_multi_fwd`.
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09ez-py2-py-notes:
**Notes**
``dim2_coeff_ins`` inserts a selected set of two-dimensional DWT coefficients into the full set of coefficients stored in compact form in a one-dimensional array :math:`\mathrm{c}`.
It is required that ``dim2_coeff_ins`` is preceded by a call to the initialization function :meth:`dim2_init` and the forward multi-level transform function :meth:`dim2_multi_fwd`.
Given an initial two-dimensional data set :math:`A`, a prior call to :meth:`dim2_multi_fwd` computes the approximation coefficients (at the highest requested level) and three sets of detail coefficients at all levels and stores these in compact form in a one-dimensional array :math:`\mathrm{c}`. :meth:`dim2_coeff_ext` can then extract either the approximation coefficients or one of the sets of detail coefficients at one of the levels into a two-dimensional array, :math:`\mathrm{d}`.
Following some calculation on this set of coefficients (for example, denoising), the updated coefficients in :math:`\mathrm{d}` are inserted back into the full set :math:`\mathrm{c}` using ``dim2_coeff_ins``.
Several extractions and insertions may be performed at different levels. :meth:`dim2_multi_inv` can then be used to reconstruct a manipulated data set :math:`\tilde{A}`.
The dimensions of :math:`\mathrm{d}` depend on the level extracted and are available from the arrays :math:`\textit{dwtlvm}` and :math:`\textit{dwtlvn}` as returned by :meth:`dim2_multi_fwd` which contain the first and second dimensions respectively.
See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html#background1>`__ for a discussion of the multi-level two-dimensional DWT.
"""
raise NotImplementedError
[docs]def dim3_sngl_fwd(a, comm):
r"""
``dim3_sngl_fwd`` computes the three-dimensional discrete wavelet transform (DWT) at a single level.
The initialization function :meth:`dim3_init` must be called first to set up the DWT options.
.. _c09fa-py2-py-doc:
For full information please refer to the NAG Library document for c09fa
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09faf.html
.. _c09fa-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n, \textit{fr}\right)`
The :math:`m\times n\times \textit{fr}` three-dimensional input data :math:`A`, where :math:`A_{{ijk}}` is stored in :math:`\mathrm{a}[i-1,j-1,k-1]`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(:\right)`
The coefficients of the discrete wavelet transform. If you need to access or modify the approximation coefficients or any specific set of detail coefficients then the use of :meth:`dim3_coeff_ext` or :meth:`dim3_coeff_ins` is recommended. For completeness the following description provides details of precisely how the coefficients are stored in :math:`\mathrm{c}` but this information should only be required in rare cases.
The :math:`8` sets of coefficients are stored in the following order: approximation coefficients (LLL) first, followed by :math:`7` sets of detail coefficients: LLH, LHL, LHH, HLL, HLH, HHL, HHH, where L indicates the low pass filter, and H the high pass filter being applied to, respectively, the columns of length :math:`\textit{m}`, the rows of length :math:`\textit{n}` and then the frames of length :math:`\textit{fr}`.
Note that for computational efficiency reasons each set of coefficients is stored in the order :math:`n_{\mathrm{cfr}}\times n_{\mathrm{cm}}\times n_{\mathrm{cn}}` (see output arguments :math:`\textit{nwcfr}`, :math:`\textit{nwct}` and :math:`\textit{nwcn}` in :meth:`dim3_init`).
.. _c09fa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{n}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{m}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`\textit{fr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{fr} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{fr}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or there has not been a prior call to the initialization function :meth:`dim3_init`.
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or :math:`\mathrm{wtrans} = \text{‘M'}` was used in the prior call to the initialization function :meth:`dim3_init`.
.. _c09fa-py2-py-notes:
**Notes**
``dim3_sngl_fwd`` computes the three-dimensional DWT of some given three-dimensional input data, considered as a number of two-dimensional frames, at a single level.
For a chosen wavelet filter pair, the output coefficients are obtained by applying convolution and downsampling by two to the input data, :math:`A`, first over columns, next over rows and finally across frames.
The three-dimensional approximation coefficients are produced by the low pass filter over columns, rows and frames.
In addition there are :math:`7` sets of three-dimensional detail coefficients, each corresponding to a different order of low pass and high pass filters (see `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html>`__).
All coefficients are packed into a single array.
To reduce distortion effects at the ends of the data array, several end extension methods are commonly used.
Those provided are: periodic or circular convolution end extension, half-point symmetric end extension, whole-point symmetric end extension and zero end extension.
The total number, :math:`n_{\mathrm{ct}}`, of coefficients computed is returned by the initialization function :meth:`dim3_init`.
.. _c09fa-py2-py-references:
**References**
Daubechies, I, 1992, `Ten Lectures on Wavelets`, SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dim3_sngl_inv(m, n, fr, c, comm):
r"""
``dim3_sngl_inv`` computes the three-dimensional inverse discrete wavelet transform (IDWT) at a single level.
The initialization function :meth:`dim3_init` must be called first to set up the DWT options.
.. _c09fb-py2-py-doc:
For full information please refer to the NAG Library document for c09fb
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09fbf.html
.. _c09fb-py2-py-parameters:
**Parameters**
**m** : int
The number of rows of each two-dimensional frame.
**n** : int
The number of columns of each two-dimensional frame.
**fr** : int
The number two-dimensional frames.
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The coefficients of the discrete wavelet transform. This will normally be the result of some transformation on the coefficients computed by function :meth:`dim3_sngl_fwd`.
Note that the coefficients in :math:`\mathrm{c}` may be extracted according to type into three-dimensional arrays using :meth:`dim3_coeff_ext`, and inserted using :meth:`dim3_coeff_ins`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**b** : float, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}, \mathrm{fr}\right)`
The :math:`m\times n\times \textit{fr}` reconstructed array, :math:`B`, with :math:`B_{{ijk}}` stored in :math:`\mathrm{b}[i-1,j-1,k-1]`. The reconstruction is based on the input wavelet coefficients and the transform options supplied to the initialization function :meth:`dim3_init`.
.. _c09fb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\mathrm{n}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\mathrm{m}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`\mathrm{fr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{fr} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\mathrm{fr}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients returned by :meth:`dim3_init` in argument :math:`\textit{nwct}`.
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or there has not been a prior call to the initialization function :meth:`dim3_init`.
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or :math:`\mathrm{wtrans} = \text{‘M'}` was used in the prior call to the initialization function :meth:`dim3_init`.
.. _c09fb-py2-py-notes:
**Notes**
``dim3_sngl_inv`` performs the inverse operation of function :meth:`dim3_sngl_fwd`.
That is, given sets of wavelet coefficients computed by function :meth:`dim3_sngl_fwd` using a DWT as set up by the initialization function :meth:`dim3_init`, on a real data array, :math:`B`, ``dim3_sngl_inv`` will reconstruct :math:`B`.
"""
raise NotImplementedError
[docs]def dim3_multi_fwd(a, nwl, comm):
r"""
``dim3_multi_fwd`` computes the three-dimensional multi-level discrete wavelet transform (DWT).
The initialization function :meth:`dim3_init` must be called first to set up the DWT options.
.. _c09fc-py2-py-doc:
For full information please refer to the NAG Library document for c09fc
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09fcf.html
.. _c09fc-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n, \textit{fr}\right)`
The :math:`m\times n\times \textit{fr}` three-dimensional input data :math:`A`, where with :math:`A_{{ijk}}` stored in :math:`\mathrm{a}[i-1,j-1,k-1]`.
**nwl** : int
The number of levels, :math:`n_{\mathrm{fwd}}`, in the multi-level resolution to be performed.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
The coefficients of the discrete wavelet transform. If you need to access or modify the approximation coefficients or any specific set of detail coefficients then the use of :meth:`dim3_coeff_ext` or :meth:`dim3_coeff_ins` is recommended. For completeness the following description provides details of precisely how the coefficients are stored in :math:`\mathrm{c}` but this information should only be required in rare cases.
Let :math:`q\left(\textit{i}\right)` denote the number of coefficients of each type at level :math:`\textit{i}`, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`, such that :math:`q\left(i\right) = \mathrm{dwtlvm}[n_{\mathrm{fwd}}-i]\times \mathrm{dwtlvn}[n_{\mathrm{fwd}}-i]\times \mathrm{dwtlvfr}[n_{\mathrm{fwd}}-i]`.
Then, letting :math:`k_1 = q\left(n_{\mathrm{fwd}}\right)` and :math:`k_{{\textit{j}+1}} = k_{\textit{j}}+q\left(n_{\mathrm{fwd}}-\left\lceil \textit{j}/7\right\rceil +1\right)`, for :math:`\textit{j} = 1,2,\ldots,7n_{\mathrm{fwd}}`, the coefficients are stored in :math:`\mathrm{c}` as follows:
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,k_1`
Contains the level :math:`n_{\mathrm{fwd}}` approximation coefficients, :math:`a_{n_{\mathrm{fwd}}}`. Note that for computational efficiency reasons these coefficients are stored as :math:`\mathrm{dwtlvm}[0]\times \mathrm{dwtlvn}[0]\times \mathrm{dwtlvfr}[0]` in :math:`\mathrm{c}`.
:math:`\mathrm{c}[\textit{i}-1]`, for :math:`\textit{i} = k_j+1,\ldots,k_{{j+1}}`
Contains the level :math:`n_{\mathrm{fwd}}-\left\lceil j/7\right\rceil +1` detail coefficients. These are:
LLH coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 1`;
LHL coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 2`;
LHH coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 3`;
HLL coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 4`;
HLH coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 5`;
HHL coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 6`;
HHH coefficients if :math:`\mathrm{mod}\left(j, 7\right) = 0`,
for :math:`j = 1,\ldots,7n_{\mathrm{fwd}}`. See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html#background1>`__ for a description of how these coefficients are produced.
Note that for computational efficiency reasons these coefficients are stored as :math:`\mathrm{dwtlvfr}[ \left\lceil j/7\right\rceil -1]\times \mathrm{dwtlvm}[ \left\lceil j/7\right\rceil -1]\times \mathrm{dwtlvn}[ \left\lceil j/7\right\rceil -1]` in :math:`\mathrm{c}`.
**dwtlvm** : int, ndarray, shape :math:`\left(\mathrm{nwl}\right)`
The number of coefficients in the first dimension for each coefficient type at each level. :math:`\mathrm{dwtlvm}[\textit{i}-1]` contains the number of coefficients in the first dimension (for each coefficient type computed) at the (:math:`n_{\mathrm{fwd}}-\textit{i}+1`)th level of resolution, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`.
**dwtlvn** : int, ndarray, shape :math:`\left(\mathrm{nwl}\right)`
The number of coefficients in the second dimension for each coefficient type at each level. :math:`\mathrm{dwtlvn}[\textit{i}-1]` contains the number of coefficients in the second dimension (for each coefficient type computed) at the (:math:`n_{\mathrm{fwd}}-\textit{i}+1`)th level of resolution, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`.
**dwtlvfr** : int, ndarray, shape :math:`\left(\mathrm{nwl}\right)`
The number of coefficients in the third dimension for each coefficient type at each level. :math:`\mathrm{dwtlvfr}[\textit{i}-1]` contains the number of coefficients in the third dimension (for each coefficient type computed) at the (:math:`n_{\mathrm{fwd}}-\textit{i}+1`)th level of resolution, for :math:`\textit{i} = 1,2,\ldots,n_{\mathrm{fwd}}`.
.. _c09fc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{n}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{m}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`1`)
On entry, :math:`\textit{fr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{fr} = \langle\mathit{\boldsymbol{value}}\rangle`, the value of :math:`\textit{fr}` on initialization (see :meth:`dim3_init`).
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwlmax}} = \langle\mathit{\boldsymbol{value}}\rangle` in :meth:`dim3_init`.
Constraint: :math:`\mathrm{nwl}\leq {\textit{nwlmax}}` in :meth:`dim3_init`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{nwl} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwl}\geq 1`.
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or there has not been a prior call to the initialization function :meth:`dim3_init`.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09fc-py2-py-notes:
**Notes**
``dim3_multi_fwd`` computes the multi-level DWT of three-dimensional data.
For a given wavelet and end extension method, ``dim3_multi_fwd`` will compute a multi-level transform of a three-dimensional array :math:`A`, using a specified number, :math:`n_{\mathrm{fwd}}`, of levels.
The number of levels specified, :math:`n_{\mathrm{fwd}}`, must be no more than the value :math:`l_{\mathrm{max}}` returned in :math:`\textit{nwlmax}` by the initialization function :meth:`dim3_init` for the given problem.
The transform is returned as a set of coefficients for the different levels (packed into a single array) and a representation of the multi-level structure.
The notation used here assigns level :math:`0` to the input data, :math:`A`.
Level 1 consists of the first set of coefficients computed: the seven sets of detail coefficients are stored at this level while the approximation coefficients are used as the input to a repeat of the wavelet transform at the next level.
This process is continued until, at level :math:`n_{\mathrm{fwd}}`, all eight types of coefficients are stored.
All coefficients are packed into a single array.
.. _c09fc-py2-py-references:
**References**
Wang, Y, Che, X and Ma, S, 2012, `Nonlinear filtering based on 3D wavelet transform for MRI denoising`, URASIP Journal on Advances in Signal Processing (2012:40)
"""
raise NotImplementedError
[docs]def dim3_mxolap_multi_inv(nwlinv, c, m, n, fr, comm):
r"""
``dim3_mxolap_multi_inv`` computes the inverse three-dimensional multi-level discrete wavelet transform (IDWT).
This function reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by :meth:`dim3_multi_fwd` from an original input array.
The initialization function :meth:`dim3_init` must be called first to set up the IDWT options.
.. _c09fd-py2-py-doc:
For full information please refer to the NAG Library document for c09fd
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09fdf.html
.. _c09fd-py2-py-parameters:
**Parameters**
**nwlinv** : int
The number of levels to be used in the inverse multi-level transform. The number of levels must be less than or equal to :math:`n_{\mathrm{fwd}}`, which has the value of argument :math:`\textit{nwl}` as used in the computation of the wavelet coefficients using :meth:`dim3_multi_fwd`. The data will be reconstructed to level :math:`\left({\textit{nwl}}-\mathrm{nwlinv}\right)`, where level :math:`0` is the original input dataset provided to :meth:`dim3_multi_fwd`.
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
The coefficients of the multi-level discrete wavelet transform. This will normally be the result of some transformation on the coefficients computed by function :meth:`dim3_multi_fwd`.
Note that the coefficients in :math:`\mathrm{c}` may be extracted according to level and type into three-dimensional arrays using :meth:`dim3_coeff_ext`, and inserted using :meth:`dim3_coeff_ins`.
**m** : int
The number of elements, :math:`m`, in the first dimension of the reconstructed array :math:`B`. For a full reconstruction of :math:`\textit{nwl}` levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim3_multi_fwd`, this must be the same as argument :math:`\textit{m}` used in a preceding call to :meth:`dim3_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}` levels, this must be equal to :math:`{\textit{dwtlvm}}[\mathrm{nwlinv}]`, as returned from :meth:`dim3_multi_fwd`
**n** : int
The number of elements, :math:`n`, in the second dimension of the reconstructed array :math:`B`. For a full reconstruction of :math:`\textit{nwl}`, levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim3_multi_fwd`, this must be the same as argument :math:`\textit{n}` used in a preceding call to :meth:`dim3_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}` levels, this must be equal to :math:`{\textit{dwtlvn}}[\mathrm{nwlinv}]`, as returned from :meth:`dim3_multi_fwd`.
**fr** : int
The number of elements, :math:`\textit{fr}`, in the third dimension of the reconstructed array :math:`B`. For a full reconstruction of :math:`\textit{nwl}` levels, where :math:`\textit{nwl}` is as supplied to :meth:`dim3_multi_fwd`, this must be the same as argument :math:`\mathrm{fr}` used in a preceding call to :meth:`dim3_multi_fwd`. For a partial reconstruction of :math:`\mathrm{nwlinv} < {\textit{nwl}}` levels, this must be equal to :math:`{\textit{dwtlvfr}}[\mathrm{nwlinv}]`, as returned from :meth:`dim3_multi_fwd`.
**comm** : dict, communication object
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**b** : float, ndarray, shape :math:`\left(\mathrm{m}, \mathrm{n}, \mathrm{fr}\right)`
The :math:`m\times n\times \textit{fr}` reconstructed array, :math:`B`, with :math:`B_{{ijk}}` stored in :math:`\mathrm{b}[i-1,j-1,k-1]`. The reconstruction is based on the input multi-level wavelet transform coefficients and the transform options supplied to the initialization function :meth:`dim3_init`.
.. _c09fd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle` where :math:`\textit{nwl}` is as used in the computation of the wavelet coefficients by a call to :meth:`dim3_multi_fwd`.
Constraint: :math:`\mathrm{nwlinv}\leq {\textit{nwl}}` as used in the call to :meth:`dim3_multi_fwd`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{nwlinv} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{nwlinv}\geq 1`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of wavelet coefficients required for a transform operating on :math:`\mathrm{nwlinv}` levels. If :math:`\mathrm{nwlinv} = {\textit{nwlmax}}`, the maximum number of levels as returned by the initial call to :meth:`dim3_init`, :math:`\textit{lenc}` must be at least :math:`n_{\mathrm{ct}}`, the value returned in :math:`\textit{nwct}` by the same call to :meth:`dim3_init`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of coefficients in the second dimension at the required level of reconstruction.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of coefficients in the first dimension at the required level of reconstruction.
(`errno` :math:`4`)
On entry, :math:`\mathrm{fr} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{fr}\geq \langle\mathit{\boldsymbol{value}}\rangle`, the number of coefficients in the third dimension at the required level of reconstruction.
(`errno` :math:`6`)
Either the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted or there has not been a prior call to the initialization function :meth:`dim3_init`.
(`errno` :math:`6`)
Either the initialization function was called with :math:`\mathrm{wtrans} = \text{‘S'}` or the communication array :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09fd-py2-py-notes:
**Notes**
``dim3_mxolap_multi_inv`` performs the inverse operation of :meth:`dim3_multi_fwd`.
That is, given a set of wavelet coefficients, computed up to level :math:`n_{\mathrm{fwd}}` by :meth:`dim3_multi_fwd` using a DWT as set up by the initialization function :meth:`dim3_init`, on a real three-dimensional array, :math:`A`, ``dim3_mxolap_multi_inv`` will reconstruct :math:`A`.
The reconstructed array is referred to as :math:`B` in the following since it will not be identical to :math:`A` when the DWT coefficients have been filtered or otherwise manipulated prior to reconstruction.
If the original input array is level :math:`0`, then it is possible to terminate reconstruction at a higher level by specifying fewer than the number of levels used in the call to :meth:`dim3_multi_fwd`.
This results in a partial reconstruction.
.. _c09fd-py2-py-references:
**References**
Wang, Y, Che, X and Ma, S, 2012, `Nonlinear filtering based on 3D wavelet transform for MRI denoising`, URASIP Journal on Advances in Signal Processing (2012:40)
"""
raise NotImplementedError
[docs]def dim3_coeff_ext(ilev, cindex, c, comm):
r"""
``dim3_coeff_ext`` extracts a selected set of discrete wavelet transform (DWT) coefficients from the full set of coefficients stored in compact form, as computed by :meth:`dim3_sngl_fwd` (single level three-dimensional DWT) or :meth:`dim3_multi_fwd` (multi-level three-dimensional DWT).
.. _c09fy-py2-py-doc:
For full information please refer to the NAG Library document for c09fy
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09fyf.html
.. _c09fy-py2-py-parameters:
**Parameters**
**ilev** : int
The level at which coefficients are to be extracted.
If :math:`\mathrm{ilev} = 0`, it is assumed that the coefficient array :math:`\mathrm{c}` was produced by a preceding call to the single level function :meth:`dim3_sngl_fwd`.
If :math:`\mathrm{ilev} > 0`, it is assumed that the coefficient array :math:`\mathrm{c}` was produced by a preceding call to the multi-level function :meth:`dim3_multi_fwd`.
**cindex** : int
Identifies which coefficients to extract. The coefficients are identified as follows:
:math:`\mathrm{cindex} = 0`
The approximation coefficients, produced by application of the low pass filter over columns, rows and frames of :math:`A` (LLL). After a call to the multi-level transform function :meth:`dim3_multi_fwd` (which implies that :math:`\mathrm{ilev} > 0`) the approximation coefficients are available only for :math:`\mathrm{ilev} = {\textit{nwl}}`, where :math:`\textit{nwl}` is the value used in a preceding call to :meth:`dim3_multi_fwd`.
:math:`\mathrm{cindex} = 1`
The detail coefficients produced by applying the low pass filter over columns and rows of :math:`A` and the high pass filter over frames (LLH).
:math:`\mathrm{cindex} = 2`
The detail coefficients produced by applying the low pass filter over columns, high pass filter over rows and low pass filter over frames of :math:`A` (LHL).
:math:`\mathrm{cindex} = 3`
The detail coefficients produced by applying the low pass filter over columns of :math:`A` and high pass filter over rows and frames (LHH).
:math:`\mathrm{cindex} = 4`
The detail coefficients produced by applying the high pass filter over columns of :math:`A` and low pass filter over rows and frames (HLL).
:math:`\mathrm{cindex} = 5`
The detail coefficients produced by applying the high pass filter over columns, low pass filter over rows and high pass filter over frames of :math:`A` (HLH).
:math:`\mathrm{cindex} = 6`
The detail coefficients produced by applying the high pass filter over columns and rows of :math:`A` and the low pass filter over frames (HHL).
:math:`\mathrm{cindex} = 7`
The detail coefficients produced by applying the high pass filter over columns, rows and frames of :math:`A` (HHH).
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
DWT coefficients, as computed by :meth:`dim3_sngl_fwd` or :meth:`dim3_multi_fwd`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**d** : float, ndarray, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}, \textit{n}_\textit{cfr}\right)`
The requested coefficients.
If the DWT coefficients were computed by :meth:`dim3_sngl_fwd` then
if :math:`\mathrm{cindex} = 0`, the approximation coefficients are stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`;
if :math:`1\leq \mathrm{cindex}\leq 7`, the detail coefficients, as indicated by :math:`\mathrm{cindex}`, are stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
If the DWT coefficients were computed by :meth:`dim3_multi_fwd` then
if :math:`\mathrm{cindex} = 0` and :math:`\mathrm{ilev} = {\textit{nwl}}`, the approximation coefficients are stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`;
if :math:`1\leq \mathrm{cindex}\leq 7`, the detail coefficients, as indicated by :math:`\mathrm{cindex}`, for level :math:`\mathrm{ilev}` are stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
.. _c09fy-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev} = 0` following a call to the single level function :meth:`dim3_sngl_fwd`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev} > 0` following a call to the multi-level function :meth:`dim3_multi_fwd`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\leq {\textit{nwl}}`, where :math:`\textit{nwl}` is the number of levels used in the call to :meth:`dim3_multi_fwd`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\geq 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\leq 7`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in the preceding call to :meth:`dim3_sngl_fwd`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in the preceding call to :meth:`dim3_multi_fwd`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`, but :math:`\mathrm{cindex} = 0`.
Constraint: :math:`\mathrm{cindex} > 0` when :math:`\mathrm{ilev} < {\textit{nwl}}` in the preceding call to :meth:`dim3_multi_fwd`.
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09fy-py2-py-notes:
**Notes**
``dim3_coeff_ext`` is intended to be used after a call to either :meth:`dim3_sngl_fwd` (single level three-dimensional DWT) or :meth:`dim3_multi_fwd` (multi-level three-dimensional DWT), either of which must be preceded by a call to :meth:`dim3_init` (three-dimensional wavelet filter initialization).
Given an initial three-dimensional data set :math:`A`, a prior call to :meth:`dim3_sngl_fwd` or :meth:`dim3_multi_fwd` computes the approximation coefficients (at the highest requested level in the case of :meth:`dim3_multi_fwd`) and seven sets of detail coefficients (at all levels in the case of :meth:`dim3_multi_fwd`) and stores these in compact form in a one-dimensional array :math:`\mathrm{c}`. ``dim3_coeff_ext`` can then extract either the approximation coefficients or one of the sets of detail coefficients (at one of the levels following :meth:`dim3_multi_fwd`) into a three-dimensional data set stored in :math:`\mathrm{d}`.
If a multi-level DWT was performed by a prior call to :meth:`dim3_multi_fwd` then the dimensions of the three-dimensional data stored in :math:`\mathrm{d}` depend on the level extracted and are available from the arrays :math:`\textit{dwtlvm}`, :math:`\textit{dwtlvn}` and :math:`\textit{dwtlvfr}` as returned by :meth:`dim3_multi_fwd` which contain the first, second and third dimensions respectively.
If a single level DWT was performed by a prior call to :meth:`dim3_sngl_fwd` then the dimensions of the three-dimensional data stored in :math:`\mathrm{d}` can be determined from :math:`\textit{nwct}`, :math:`\textit{nwcn}` and :math:`\textit{nwcfr}` as returned by the setup function :meth:`dim3_init`.
See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html#background1>`__ for a discussion of the three-dimensional DWT.
"""
raise NotImplementedError
[docs]def dim3_coeff_ins(ilev, cindex, c, d, comm):
r"""
``dim3_coeff_ins`` inserts a selected set of three-dimensional discrete wavelet transform (DWT) coefficients into the full set of coefficients stored in compact form, which may be later used as input to the reconstruction functions :meth:`dim3_sngl_inv` or :meth:`dim3_mxolap_multi_inv`.
.. _c09fz-py2-py-doc:
For full information please refer to the NAG Library document for c09fz
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09fzf.html
.. _c09fz-py2-py-parameters:
**Parameters**
**ilev** : int
The level at which coefficients are to be inserted.
If :math:`\mathrm{ilev} = 0`, it is assumed that the coefficient array :math:`\mathrm{c}` was produced by a preceding call to the single level function :meth:`dim3_sngl_fwd`.
If :math:`\mathrm{ilev} > 0`, it is assumed that the coefficient array :math:`\mathrm{c}` was produced by a preceding call to the multi-level function :meth:`dim3_multi_fwd`.
**cindex** : int
Identifies which coefficients to insert. The coefficients are identified as follows:
:math:`\mathrm{cindex} = 0`
The approximation coefficients, produced by application of the low pass filter over columns, rows and frames of :math:`A` (LLL). After a call to the multi-level transform function :meth:`dim3_multi_fwd` (which implies that :math:`\mathrm{ilev} > 0`) the approximation coefficients are present only for :math:`\mathrm{ilev} = {\textit{nwl}}`, where :math:`\textit{nwl}` is the value used in a preceding call to :meth:`dim3_multi_fwd`.
:math:`\mathrm{cindex} = 1`
The detail coefficients produced by applying the low pass filter over columns and rows of :math:`A` and the high pass filter over frames (LLH).
:math:`\mathrm{cindex} = 2`
The detail coefficients produced by applying the low pass filter over columns, high pass filter over rows and low pass filter over frames of :math:`A` (LHL).
:math:`\mathrm{cindex} = 3`
The detail coefficients produced by applying the low pass filter over columns of :math:`A` and high pass filter over rows and frames (LHH).
:math:`\mathrm{cindex} = 4`
The detail coefficients produced by applying the high pass filter over columns of :math:`A` and low pass filter over rows and frames (HLL).
:math:`\mathrm{cindex} = 5`
The detail coefficients produced by applying the high pass filter over columns, low pass filter over rows and high pass filter over frames of :math:`A` (HLH).
:math:`\mathrm{cindex} = 6`
The detail coefficients produced by applying the high pass filter over columns and rows of :math:`A` and the low pass filter over frames (HHL).
:math:`\mathrm{cindex} = 7`
The detail coefficients produced by applying the high pass filter over columns, rows and frames of :math:`A` (HHH).
**c** : float, array-like, shape :math:`\left(\textit{lenc}\right)`
Contains the DWT coefficients inserted by previous calls to ``dim3_coeff_ins``, or computed by a previous call to either :meth:`dim3_sngl_fwd` or :meth:`dim3_multi_fwd`.
**d** : float, array-like, shape :math:`\left(\textit{n}_\textit{cm}, \textit{n}_\textit{cn}, \textit{n}_\textit{cfr}\right)`
The coefficients to be inserted.
If the DWT coefficients were computed by :meth:`dim3_sngl_fwd` then
if :math:`\mathrm{cindex} = 0`, the approximation coefficients must be stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`;
if :math:`1\leq \mathrm{cindex}\leq 7`, the detail coefficients, as indicated by :math:`\mathrm{cindex}`, must be stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
If the DWT coefficients were computed by :meth:`dim3_multi_fwd` then
if :math:`\mathrm{cindex} = 0` and :math:`\mathrm{ilev} = {\textit{nwl}}`, the approximation coefficients must be stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`;
if :math:`1\leq \mathrm{cindex}\leq 7`, the detail coefficients, as indicated by :math:`\mathrm{cindex}`, for level :math:`\mathrm{ilev}` must be stored in :math:`\mathrm{d}[i-1,\textit{j}-1,\textit{k}-1]`, for :math:`\textit{k} = 1,2,\ldots,n_{\textit{cfr}}`, for :math:`\textit{j} = 1,2,\ldots,n_{\textit{cn}}`, for :math:`\textit{i} = 1,2,\ldots,n_{\textit{cm}}`.
**comm** : dict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to :meth:`dim3_init`.
**Returns**
**c** : float, ndarray, shape :math:`\left(\textit{lenc}\right)`
Contains the same DWT coefficients provided on entry except for those identified by :math:`\mathrm{ilev}` and :math:`\mathrm{cindex}`, which are updated with the values supplied in :math:`\mathrm{d}`, inserted into the correct locations as expected by one of the reconstruction functions :meth:`dim3_sngl_inv` (if :meth:`dim3_sngl_fwd` was called previously) or :meth:`dim3_mxolap_multi_inv` (if :meth:`dim3_multi_fwd` was called previously).
.. _c09fz-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev} = 0` following a call to the single level function :meth:`dim3_sngl_fwd`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev} > 0` following a call to the multi-level function :meth:`dim3_multi_fwd`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{ilev}\leq {\textit{nwl}}`, where :math:`{\textit{nwl}}` is the number of levels used in the call to :meth:`dim3_multi_fwd`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\geq 0`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{cindex} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{cindex}\leq 7`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in a previous call to :meth:`dim3_sngl_fwd`.
(`errno` :math:`3`)
On entry, :math:`\textit{lenc} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`n_{\textit{ct}} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{lenc}\geq n_{\textit{ct}}`, where :math:`n_{\textit{ct}}` is the number of DWT coefficients computed in a previous call to :meth:`dim3_multi_fwd`.
(`errno` :math:`5`)
On entry, :math:`\mathrm{ilev} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`{\textit{nwl}} = \langle\mathit{\boldsymbol{value}}\rangle`, but :math:`\mathrm{cindex} = 0`.
Constraint: :math:`\mathrm{cindex} > 0` when :math:`\mathrm{ilev} < {\textit{nwl}}` in the preceding call to :meth:`dim3_multi_fwd`.
(`errno` :math:`6`)
Either the initialization function has not been called first or :math:`\mathrm{comm}`\ ['icomm'] has been corrupted.
.. _c09fz-py2-py-notes:
**Notes**
``dim3_coeff_ins`` inserts a selected set of three-dimensional DWT coefficients into the full set of coefficients stored in compact form in a one-dimensional array :math:`\mathrm{c}`.
It is required that ``dim3_coeff_ins`` is preceded by a call to the initialization function :meth:`dim3_init` and either the forwards transform function :meth:`dim3_sngl_fwd` or multi-level forwards transform function :meth:`dim3_multi_fwd`.
Given an initial three-dimensional data set :math:`A`, a prior call to :meth:`dim3_sngl_fwd` or :meth:`dim3_multi_fwd` computes the approximation coefficients (at the highest requested level in the case of :meth:`dim3_multi_fwd`) and, seven sets of detail coefficients (at all levels in the case of :meth:`dim3_multi_fwd`) and stores these in compact form in a one-dimensional array :math:`\mathrm{c}`. :meth:`dim3_coeff_ext` can then extract either the approximation coefficients or one of the sets of detail coefficients (at one of the levels following :meth:`dim3_multi_fwd`) into a three-dimensional array, :math:`\mathrm{d}`.
Following some calculation on this set of coefficients (for example, denoising), the updated coefficients in :math:`\mathrm{d}` are inserted back into the full set :math:`\mathrm{c}` using ``dim3_coeff_ins``.
Several extractions and insertions may be performed. :meth:`dim3_sngl_inv` or :meth:`dim3_mxolap_multi_inv` can then be used to reconstruct a manipulated data set :math:`\tilde{A}`.
The dimensions of :math:`\mathrm{d}` depend on the level extracted and are available from either: the arrays :math:`\textit{dwtlvm}`, :math:`\textit{dwtlvn}` and :math:`\textit{dwtlvfr}` as returned by :meth:`dim3_multi_fwd` if this was called first; or, otherwise from :math:`\textit{nwct}`, :math:`\textit{nwcn}` and :math:`\textit{nwcfr}` as returned by :meth:`dim3_init`.
See `the C09 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/c09/c09intro.html#background1>`__ for a discussion of the three-dimensional DWT.
"""
raise NotImplementedError
