Skip to content

Commit

Permalink
DOC: Replace references to the API with standard code text
Browse files Browse the repository at this point in the history
  • Loading branch information
@agriyakhetarpal
agriyakhetarpal committed Jul 24, 2024
1 parent d533611 commit 1dc3a0f
Show file tree
Hide file tree
Showing 6 changed files with 109 additions and 117 deletions.
58 changes: 27 additions & 31 deletions doc/source/regression/dwt-idwt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ mystnb:

## Discrete Wavelet Transform

Let's do a {func}`Discrete Wavelet Transform <dwt>` of a sample data `x`
using the `db2` wavelet. It's simple..
Let's do a Discrete Wavelet Transform of some sample data `x`
using the `db2` wavelet. It's simple:

```{code-cell}
import pywt
Expand All @@ -65,8 +65,7 @@ cD

## Inverse Discrete Wavelet Transform

Now let's do an opposite operation
\- {func}`Inverse Discrete Wavelet Transform <idwt>`:
Now, let's do the opposite operation: an Inverse Discrete Wavelet Transform:

```{code-cell}
pywt.idwt(cA, cD, 'db2')
Expand All @@ -76,10 +75,10 @@ Voilà! That's it!

## More examples

Now let's experiment with the {func}`dwt` some more. For example let's pass a
{class}`Wavelet` object instead of the wavelet name and specify signal
extension mode (the default is {ref}`symmetric <Modes.symmetric>`) for the
border effect handling:
Now, let's experiment with `dwt` some more. For example, let's pass a
`Wavelet` object instead of the wavelet name and specify the signal
extension mode (the default is `Modes.symmetric`) for the border effect
handling:

```{code-cell}
w = pywt.Wavelet('sym3')
Expand All @@ -94,11 +93,11 @@ print(cA)
print(cD)
```

Note that the output coefficients arrays length depends not only on the input
data length but also on the :class:Wavelet type (particularly on its
{attr}`filters length <~Wavelet.dec_len>` that are used in the transformation).
Note that the output coefficients arrays' length depends not only on the
input data length but also on the `Wavelet` type (particularly on its
filters length `Wavelet.dec_len` that are used in the transformation).

To find out what the size of the output data will be, use the {func}`dwt_coeff_len`
To find out what the size of the output data will be, use the `dwt_coeff_len`
function:

```{code-cell}
Expand All @@ -119,23 +118,20 @@ Looks fine. (And if you expected that the output length would be a half of the
input data length, well, that's the trade-off that allows for the perfect
reconstruction...).

The third argument of the {func}`dwt_coeff_len` is the already mentioned signal
extension mode (please refer to the PyWavelets' documentation for the
{ref}`modes <modes>` description). Currently, there are six
{ref}`extension modes <Modes>` available:
The third argument of the `dwt_coeff_len` function is the already mentioned signal
extension mode (please refer to the PyWavelets' documentation for the `modes`
description). Currently, there are six extension modes available under `Modes`:

```{code-cell}
pywt.Modes.modes
```

As you see in the above example, the {ref}`periodization <Modes.periodization>`
(periodization) mode is slightly different from the others. It's aim when
doing the {func}`DWT <dwt>` transform is to output coefficients arrays that
are half of the length of the input data.
As you see in the above example, the periodization (`Modes.periodization`) mode
is slightly different from the others. Its aim when doing the `pywt.dwt` transform
is to output coefficients arrays that are half of the length of the input data.

Knowing that, you should never mix the periodization mode with other modes when
doing {func}`DWT <dwt>` and {func}`IDWT <idwt>`. Otherwise, it will produce
**invalid results**:
doing `dwt` and `idwt`. Otherwise, it will produce **invalid results**:

```{code-cell}
x = [3, 7, 1, 1, -2, 5, 4, 6]
Expand All @@ -150,9 +146,9 @@ print(pywt.idwt(cA, cD, 'sym3', 'periodization'))

## Tips & tricks

### Passing `None` instead of coefficients data to {func}`idwt`
### Passing `None` instead of coefficients data to `pywt.idwt()`

Now, we showcase some tips & tricks. Passing `None` as one of the coefficient
Now, we showcase some tips and tricks. Passing `None` as one of the coefficient
arrays parameters is similar to passing a _zero-filled_ array. The results are
simply the same:

Expand Down Expand Up @@ -181,9 +177,9 @@ tags: [raises-exception]
print(pywt.idwt(None, None, 'db2', 'symmetric'))
```

### Coefficients data size in {attr}`idwt`
### Coefficients data size in `pywt.idwt`

When doing the {func}`IDWT <idwt>` transform, usually the coefficient arrays
When doing the `idwt` transform, usually the coefficient arrays
must have the same size.

```{code-cell}
Expand All @@ -193,11 +189,11 @@ tags: [raises-exception]
print(pywt.idwt([1, 2, 3, 4, 5], [1, 2, 3, 4], 'db2', 'symmetric'))
```

Not every coefficient array can be used in {func}`IDWT <idwt>`. In the
following example the {func}`idwt` will fail because the input arrays are
invalid - they couldn't be created as a result of {func}`DWT <dwt>`, because
the minimal output length for dwt using `db4` wavelet and the {ref}`symmetric
<Modes.symmetric>` mode is `4`, not `3`:
Not every coefficient array can be used in `idwt`. In the
following example the `idwt` will fail because the input arrays are
invalid - they couldn't be created as a result of `dwt`, because
the minimal output length for dwt using `db4` wavelet and the `Modes.symmetric`
mode is `4`, not `3`:

```{code-cell}
---
Expand Down
4 changes: 2 additions & 2 deletions doc/source/regression/gotchas.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ kernelspec:
# Gotchas

PyWavelets utilizes `NumPy` under the hood. That's why handling the data
containing `None` values can be surprising. `None` values are converted to
'not a number' (`numpy.NaN`) values:
that contains `None` values can be surprising. `None` values are converted to
'not a number' (`numpy.nan`) values:

```{code-cell}
import numpy, pywt
Expand Down
10 changes: 5 additions & 5 deletions doc/source/regression/modes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ kernelspec:

# Signal Extension Modes

Let's import {mod}`pywt`, first:
Let's import `pywt`, first:

```{code-cell}
import pywt
Expand All @@ -57,13 +57,13 @@ def format_array(a):
return numpy.array2string(a, precision=5, separator=' ', suppress_small=True)
```

A list of available signal extension {ref}`modes <Modes>` is as follows:
A list of available signal extension modes (`Modes`) is provided as follows:

```{code-cell}
pywt.Modes.modes
```

Therefore, an invalid mode name should rise a {exc}`ValueError`:
Therefore, an invalid mode name should raise a `ValueError`:

```{code-cell}
---
Expand All @@ -72,7 +72,7 @@ tags: [raises-exception]
pywt.dwt([1,2,3,4], 'db2', 'invalid')
```

You can also refer to modes via {ref}`Modes <Modes>` class attributes:
You can also refer to modes via the attributes of the `Modes` class:

```{code-cell}
x = [1, 2, 1, 5, -1, 8, 4, 6]
Expand All @@ -82,7 +82,7 @@ for mode_name in ['zero', 'constant', 'symmetric', 'reflect', 'periodic', 'smoot
print("Mode: %d (%s)" % (mode, mode_name))
```

The default mode is {ref}`symmetric <Modes.symmetric>`:
The default mode is symmetric, i.e., `Modes.symmetric`:

```{code-cell}
cA, cD = pywt.dwt(x, 'db2')
Expand Down
50 changes: 25 additions & 25 deletions doc/source/regression/wavelet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,12 @@ kernelspec:

## Wavelet families and builtin Wavelets names

{class}`Wavelet` objects are really a handy carriers of a bunch of DWT-specific
`pywt.Wavelet` objects are really handy carriers of a bunch of DWT-specific
data like _quadrature mirror filters_ and some general properties associated
with them.

At first let's go through the methods of creating a {class}`Wavelet` object.
The easiest and the most convenient way is to use builtin named Wavelets.
At first let's go through the methods of creating a `Wavelet` object.
The easiest and the most convenient way is to use built-in named Wavelets.

These wavelets are organized into groups called wavelet families. The most
commonly used families are:
Expand All @@ -63,12 +63,12 @@ for family in pywt.families():
print("%s family: " % family + ', '.join(pywt.wavelist(family)))
```

To get the full list of builtin wavelets' names, just use the {func}`wavelist`
To get the full list of built-in wavelets' names, just use the `pywt.wavelist` function
without any arguments.

## Creating Wavelet objects

Now, since we know all the names, let's finally create a {class}`Wavelet` object:
Now that we know all the names, let's finally create a `Wavelet` object:

```{code-cell}
w = pywt.Wavelet('db3')
Expand All @@ -78,10 +78,10 @@ and, that's it!

## Wavelet properties

But what can we do with {class}`Wavelet` objects? Well, they carry some
But what can we do with `Wavelet` objects? Well, they carry some
interesting pieces of information.

First, let's try printing a {class}`Wavelet` object that we used earlier.
First, let's try printing a `Wavelet` object that we used earlier.
This shows a brief information about its name, its family name and some
properties like orthogonality and symmetry.

Expand All @@ -90,18 +90,18 @@ print(w)
```

But the most important bits of information are the wavelet filters coefficients,
which are used in {ref}`Discrete Wavelet Transform <ref-dwt>`. These coefficients
can be obtained via the {attr}`~Wavelet.dec_lo`, {attr}`Wavelet.dec_hi`,
{attr}`~Wavelet.rec_lo` and {attr}`~Wavelet.rec_hi` attributes, which
correspond to lowpass & highpass decomposition filters and lowpass &
which are used in Discrete Wavelet Transform. These coefficients
can be obtained via the `Wavelet.dec_lo`, `Wavelet.dec_hi`, `Wavelet.rec_lo`,
and the `~Wavelet.rec_hi` attributes, which
correspond to lowpass & highpass decomposition filters, and lowpass &
highpass reconstruction filters respectively:

```{code-cell}
def print_array(arr):
print("[%s]" % ", ".join(["%.14f" % x for x in arr]))
```

Another way to get the filters data is to use the {attr}`~Wavelet.filter_bank`
Another way to get the filters data is to use the `Wavelet.filter_bank`
attribute, which returns all four filters in a tuple:

```{code-cell}
Expand All @@ -110,15 +110,15 @@ w.filter_bank == (w.dec_lo, w.dec_hi, w.rec_lo, w.rec_hi)

Other properties of a `Wavelet` object are:

1. Wavelet {attr}`~Wavelet.name`, {attr}`~Wavelet.short_family_name` and {attr}`~Wavelet.family_name`:
1. `Wavelet.name`, `Wavelet.short_family_name`, and `Wavelet.family_name`:

```{code-cell}
print(w.name)
print(w.short_family_name)
print(w.family_name)
```

2. Decomposition ({attr}`~Wavelet.dec_len`) and reconstruction ({attr}`~.Wavelet.rec_len`) filter lengths:
2. Decomposition (`Wavelet.dec_len`) and reconstruction (`Wavelet.rec_len`) filter lengths:

```{code-cell}
w.dec_len
Expand All @@ -128,7 +128,7 @@ w.dec_len
w.rec_len
```

3. Orthogonality ({attr}`~Wavelet.orthogonal`) and biorthogonality ({attr}`~Wavelet.biorthogonal`):
3. Orthogonality (`Wavelet.orthogonal`) and biorthogonality (`Wavelet.biorthogonal`):

```{code-cell}
w.orthogonal
Expand All @@ -138,14 +138,14 @@ w.orthogonal
w.biorthogonal
```

3. Symmetry ({attr}`~Wavelet.symmetry`):
3. Symmetry (`Wavelet.symmetry`):

```{code-cell}
print(w.symmetry)
```

4. Number of vanishing moments for the scaling function `phi` ({attr}`~Wavelet.vanishing_moments_phi`)
and the wavelet function `psi` ({attr}`~Wavelet.vanishing_moments_psi`), associated with the filters:
4. Number of vanishing moments for the scaling function `phi` (`Wavelet.vanishing_moments_phi`)
and the wavelet function `psi` (`Wavelet.vanishing_moments_psi`), associated with the filters:

```{code-cell}
w.vanishing_moments_phi
Expand All @@ -156,7 +156,7 @@ w.vanishing_moments_psi
```

Now when we know a bit about the builtin Wavelets, let's see how to create
{ref}`custom Wavelets <custom-wavelets>` objects. These can be done in two ways:
custom `Wavelets` objects. These can be done in two ways:

1. Passing the filter bank object that implements the `filter_bank` attribute. The
attribute must return four filters coefficients.
Expand Down Expand Up @@ -189,7 +189,7 @@ my_filter_bank = (
my_wavelet = pywt.Wavelet('My Haar Wavelet', filter_bank=my_filter_bank)
```

Note that such custom wavelets **will not** have all the properties set
Note that such custom `Wavelets` objects **will not** have all the properties set
to correct values and some of them could be missing:

```{code-cell}
Expand All @@ -212,10 +212,10 @@ print(my_wavelet)
## And now... the `wavefun`!

We all know that the fun with wavelets is in wavelet functions.
Now, what would be this package without a tool to compute wavelet
Now, what would this package be without a tool to compute wavelet
and scaling functions approximations?

This is the purpose of the {meth}`~Wavelet.wavefun` method, which is used to
This is the purpose of the `Wavelet.wavefun` method, which is used to
approximate scaling function (`phi`) and wavelet function (`psi`) at the
given level of refinement, based on the filters coefficients.

Expand All @@ -234,8 +234,8 @@ w.orthogonal

For biorthogonal (non-orthogonal) wavelets, different scaling and wavelet
functions are used for decomposition and reconstruction, and thus, five
elements are returned: decomposition scaling & wavelet functions
approximations, reconstruction scaling & wavelet functions approximations,
elements are returned: decomposition scaling and wavelet functions
approximations, reconstruction scaling and wavelet functions approximations,
and the xgrid.

```{code-cell}
Expand All @@ -248,7 +248,7 @@ w.orthogonal
```

:::{seealso}
You can find live examples of the usage of {meth}`~Wavelet.wavefun` and
You can find live examples of the usage of `Wavelet.wavefun` and
images of all the built-in wavelets on the
[Wavelet Properties Browser](http://wavelets.pybytes.com) page.

Expand Down
Loading

0 comments on commit 1dc3a0f

Please sign in to comment.