Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/scipy/fft/_realtransforms.py : 71%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from ._basic import _dispatch
2from scipy._lib.uarray import Dispatchable
3import numpy as np
5__all__ = ['dct', 'idct', 'dst', 'idst', 'dctn', 'idctn', 'dstn', 'idstn']
8@_dispatch
9def dctn(x, type=2, s=None, axes=None, norm=None, overwrite_x=False,
10 workers=None):
11 """
12 Return multidimensional Discrete Cosine Transform along the specified axes.
14 Parameters
15 ----------
16 x : array_like
17 The input array.
18 type : {1, 2, 3, 4}, optional
19 Type of the DCT (see Notes). Default type is 2.
20 s : int or array_like of ints or None, optional
21 The shape of the result. If both `s` and `axes` (see below) are None,
22 `s` is ``x.shape``; if `s` is None but `axes` is not None, then `s` is
23 ``scipy.take(x.shape, axes, axis=0)``.
24 If ``s[i] > x.shape[i]``, the ith dimension is padded with zeros.
25 If ``s[i] < x.shape[i]``, the ith dimension is truncated to length
26 ``s[i]``.
27 If any element of `s` is -1, the size of the corresponding dimension of
28 `x` is used.
29 axes : int or array_like of ints or None, optional
30 Axes over which the DCT is computed. If not given, the last ``len(s)``
31 axes are used, or all axes if `s` is also not specified.
32 norm : {None, 'ortho'}, optional
33 Normalization mode (see Notes). Default is None.
34 overwrite_x : bool, optional
35 If True, the contents of `x` can be destroyed; the default is False.
36 workers : int, optional
37 Maximum number of workers to use for parallel computation. If negative,
38 the value wraps around from ``os.cpu_count()``.
39 See :func:`~scipy.fft.fft` for more details.
41 Returns
42 -------
43 y : ndarray of real
44 The transformed input array.
46 See Also
47 --------
48 idctn : Inverse multidimensional DCT
50 Notes
51 -----
52 For full details of the DCT types and normalization modes, as well as
53 references, see `dct`.
55 Examples
56 --------
57 >>> from scipy.fft import dctn, idctn
58 >>> y = np.random.randn(16, 16)
59 >>> np.allclose(y, idctn(dctn(y)))
60 True
62 """
63 return (Dispatchable(x, np.ndarray),)
66@_dispatch
67def idctn(x, type=2, s=None, axes=None, norm=None, overwrite_x=False,
68 workers=None):
69 """
70 Return multidimensional Discrete Cosine Transform along the specified axes.
72 Parameters
73 ----------
74 x : array_like
75 The input array.
76 type : {1, 2, 3, 4}, optional
77 Type of the DCT (see Notes). Default type is 2.
78 s : int or array_like of ints or None, optional
79 The shape of the result. If both `s` and `axes` (see below) are
80 None, `s` is ``x.shape``; if `s` is None but `axes` is
81 not None, then `s` is ``scipy.take(x.shape, axes, axis=0)``.
82 If ``s[i] > x.shape[i]``, the ith dimension is padded with zeros.
83 If ``s[i] < x.shape[i]``, the ith dimension is truncated to length
84 ``s[i]``.
85 If any element of `s` is -1, the size of the corresponding dimension of
86 `x` is used.
87 axes : int or array_like of ints or None, optional
88 Axes over which the IDCT is computed. If not given, the last ``len(s)``
89 axes are used, or all axes if `s` is also not specified.
90 norm : {None, 'ortho'}, optional
91 Normalization mode (see Notes). Default is None.
92 overwrite_x : bool, optional
93 If True, the contents of `x` can be destroyed; the default is False.
94 workers : int, optional
95 Maximum number of workers to use for parallel computation. If negative,
96 the value wraps around from ``os.cpu_count()``.
97 See :func:`~scipy.fft.fft` for more details.
99 Returns
100 -------
101 y : ndarray of real
102 The transformed input array.
104 See Also
105 --------
106 dctn : multidimensional DCT
108 Notes
109 -----
110 For full details of the IDCT types and normalization modes, as well as
111 references, see `idct`.
113 Examples
114 --------
115 >>> from scipy.fft import dctn, idctn
116 >>> y = np.random.randn(16, 16)
117 >>> np.allclose(y, idctn(dctn(y)))
118 True
120 """
121 return (Dispatchable(x, np.ndarray),)
124@_dispatch
125def dstn(x, type=2, s=None, axes=None, norm=None, overwrite_x=False,
126 workers=None):
127 """
128 Return multidimensional Discrete Sine Transform along the specified axes.
130 Parameters
131 ----------
132 x : array_like
133 The input array.
134 type : {1, 2, 3, 4}, optional
135 Type of the DST (see Notes). Default type is 2.
136 s : int or array_like of ints or None, optional
137 The shape of the result. If both `s` and `axes` (see below) are None,
138 `s` is ``x.shape``; if `s` is None but `axes` is not None, then `s` is
139 ``scipy.take(x.shape, axes, axis=0)``.
140 If ``s[i] > x.shape[i]``, the ith dimension is padded with zeros.
141 If ``s[i] < x.shape[i]``, the ith dimension is truncated to length
142 ``s[i]``.
143 If any element of `shape` is -1, the size of the corresponding dimension
144 of `x` is used.
145 axes : int or array_like of ints or None, optional
146 Axes over which the DST is computed. If not given, the last ``len(s)``
147 axes are used, or all axes if `s` is also not specified.
148 norm : {None, 'ortho'}, optional
149 Normalization mode (see Notes). Default is None.
150 overwrite_x : bool, optional
151 If True, the contents of `x` can be destroyed; the default is False.
152 workers : int, optional
153 Maximum number of workers to use for parallel computation. If negative,
154 the value wraps around from ``os.cpu_count()``.
155 See :func:`~scipy.fft.fft` for more details.
157 Returns
158 -------
159 y : ndarray of real
160 The transformed input array.
162 See Also
163 --------
164 idstn : Inverse multidimensional DST
166 Notes
167 -----
168 For full details of the DST types and normalization modes, as well as
169 references, see `dst`.
171 Examples
172 --------
173 >>> from scipy.fft import dstn, idstn
174 >>> y = np.random.randn(16, 16)
175 >>> np.allclose(y, idstn(dstn(y)))
176 True
178 """
179 return (Dispatchable(x, np.ndarray),)
182@_dispatch
183def idstn(x, type=2, s=None, axes=None, norm=None, overwrite_x=False,
184 workers=None):
185 """
186 Return multidimensional Discrete Sine Transform along the specified axes.
188 Parameters
189 ----------
190 x : array_like
191 The input array.
192 type : {1, 2, 3, 4}, optional
193 Type of the DST (see Notes). Default type is 2.
194 s : int or array_like of ints or None, optional
195 The shape of the result. If both `s` and `axes` (see below) are None,
196 `s` is ``x.shape``; if `s` is None but `axes` is not None, then `s` is
197 ``scipy.take(x.shape, axes, axis=0)``.
198 If ``s[i] > x.shape[i]``, the ith dimension is padded with zeros.
199 If ``s[i] < x.shape[i]``, the ith dimension is truncated to length
200 ``s[i]``.
201 If any element of `s` is -1, the size of the corresponding dimension of
202 `x` is used.
203 axes : int or array_like of ints or None, optional
204 Axes over which the IDST is computed. If not given, the last ``len(s)``
205 axes are used, or all axes if `s` is also not specified.
206 norm : {None, 'ortho'}, optional
207 Normalization mode (see Notes). Default is None.
208 overwrite_x : bool, optional
209 If True, the contents of `x` can be destroyed; the default is False.
210 workers : int, optional
211 Maximum number of workers to use for parallel computation. If negative,
212 the value wraps around from ``os.cpu_count()``.
213 See :func:`~scipy.fft.fft` for more details.
215 Returns
216 -------
217 y : ndarray of real
218 The transformed input array.
220 See Also
221 --------
222 dstn : multidimensional DST
224 Notes
225 -----
226 For full details of the IDST types and normalization modes, as well as
227 references, see `idst`.
229 Examples
230 --------
231 >>> from scipy.fft import dstn, idstn
232 >>> y = np.random.randn(16, 16)
233 >>> np.allclose(y, idstn(dstn(y)))
234 True
236 """
237 return (Dispatchable(x, np.ndarray),)
240@_dispatch
241def dct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, workers=None):
242 r"""
243 Return the Discrete Cosine Transform of arbitrary type sequence x.
245 Parameters
246 ----------
247 x : array_like
248 The input array.
249 type : {1, 2, 3, 4}, optional
250 Type of the DCT (see Notes). Default type is 2.
251 n : int, optional
252 Length of the transform. If ``n < x.shape[axis]``, `x` is
253 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
254 default results in ``n = x.shape[axis]``.
255 axis : int, optional
256 Axis along which the dct is computed; the default is over the
257 last axis (i.e., ``axis=-1``).
258 norm : {None, 'ortho'}, optional
259 Normalization mode (see Notes). Default is None.
260 overwrite_x : bool, optional
261 If True, the contents of `x` can be destroyed; the default is False.
262 workers : int, optional
263 Maximum number of workers to use for parallel computation. If negative,
264 the value wraps around from ``os.cpu_count()``.
265 See :func:`~scipy.fft.fft` for more details.
267 Returns
268 -------
269 y : ndarray of real
270 The transformed input array.
272 See Also
273 --------
274 idct : Inverse DCT
276 Notes
277 -----
278 For a single dimension array ``x``, ``dct(x, norm='ortho')`` is equal to
279 MATLAB ``dct(x)``.
281 For ``norm=None``, there is no scaling on `dct` and the `idct` is scaled by
282 ``1/N`` where ``N`` is the "logical" size of the DCT. For ``norm='ortho'``
283 both directions are scaled by the same factor ``1/sqrt(N)``.
285 There are, theoretically, 8 types of the DCT, only the first 4 types are
286 implemented in SciPy.'The' DCT generally refers to DCT type 2, and 'the'
287 Inverse DCT generally refers to DCT type 3.
289 **Type I**
291 There are several definitions of the DCT-I; we use the following
292 (for ``norm=None``)
294 .. math::
296 y_k = x_0 + (-1)^k x_{N-1} + 2 \sum_{n=1}^{N-2} x_n \cos\left(
297 \frac{\pi k n}{N-1} \right)
299 If ``norm='ortho'``, ``x[0]`` and ``x[N-1]`` are multiplied by a scaling
300 factor of :math:`\sqrt{2}`, and ``y[k]`` is multiplied by a scaling factor
301 ``f``
303 .. math::
305 f = \begin{cases}
306 \frac{1}{2}\sqrt{\frac{1}{N-1}} & \text{if }k=0\text{ or }N-1, \\
307 \frac{1}{2}\sqrt{\frac{2}{N-1}} & \text{otherwise} \end{cases}
309 .. note::
310 The DCT-I is only supported for input size > 1.
312 **Type II**
314 There are several definitions of the DCT-II; we use the following
315 (for ``norm=None``)
317 .. math::
319 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi k(2n+1)}{2N} \right)
321 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
323 .. math::
324 f = \begin{cases}
325 \sqrt{\frac{1}{4N}} & \text{if }k=0, \\
326 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases}
328 which makes the corresponding matrix of coefficients orthonormal
329 (``O @ O.T = np.eye(N)``).
331 **Type III**
333 There are several definitions, we use the following (for ``norm=None``)
335 .. math::
337 y_k = x_0 + 2 \sum_{n=1}^{N-1} x_n \cos\left(\frac{\pi(2k+1)n}{2N}\right)
339 or, for ``norm='ortho'``
341 .. math::
343 y_k = \frac{x_0}{\sqrt{N}} + \sqrt{\frac{2}{N}} \sum_{n=1}^{N-1} x_n
344 \cos\left(\frac{\pi(2k+1)n}{2N}\right)
346 The (unnormalized) DCT-III is the inverse of the (unnormalized) DCT-II, up
347 to a factor `2N`. The orthonormalized DCT-III is exactly the inverse of
348 the orthonormalized DCT-II.
350 **Type IV**
352 There are several definitions of the DCT-IV; we use the following
353 (for ``norm=None``)
355 .. math::
357 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi(2k+1)(2n+1)}{4N} \right)
359 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
361 .. math::
363 f = \frac{1}{\sqrt{2N}}
365 References
366 ----------
367 .. [1] 'A Fast Cosine Transform in One and Two Dimensions', by J.
368 Makhoul, `IEEE Transactions on acoustics, speech and signal
369 processing` vol. 28(1), pp. 27-34,
370 :doi:`10.1109/TASSP.1980.1163351` (1980).
371 .. [2] Wikipedia, "Discrete cosine transform",
372 https://en.wikipedia.org/wiki/Discrete_cosine_transform
374 Examples
375 --------
376 The Type 1 DCT is equivalent to the FFT (though faster) for real,
377 even-symmetrical inputs. The output is also real and even-symmetrical.
378 Half of the FFT input is used to generate half of the FFT output:
380 >>> from scipy.fft import fft, dct
381 >>> fft(np.array([4., 3., 5., 10., 5., 3.])).real
382 array([ 30., -8., 6., -2., 6., -8.])
383 >>> dct(np.array([4., 3., 5., 10.]), 1)
384 array([ 30., -8., 6., -2.])
386 """
387 return (Dispatchable(x, np.ndarray),)
390@_dispatch
391def idct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False,
392 workers=None):
393 """
394 Return the Inverse Discrete Cosine Transform of an arbitrary type sequence.
396 Parameters
397 ----------
398 x : array_like
399 The input array.
400 type : {1, 2, 3, 4}, optional
401 Type of the DCT (see Notes). Default type is 2.
402 n : int, optional
403 Length of the transform. If ``n < x.shape[axis]``, `x` is
404 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
405 default results in ``n = x.shape[axis]``.
406 axis : int, optional
407 Axis along which the idct is computed; the default is over the
408 last axis (i.e., ``axis=-1``).
409 norm : {None, 'ortho'}, optional
410 Normalization mode (see Notes). Default is None.
411 overwrite_x : bool, optional
412 If True, the contents of `x` can be destroyed; the default is False.
413 workers : int, optional
414 Maximum number of workers to use for parallel computation. If negative,
415 the value wraps around from ``os.cpu_count()``.
416 See :func:`~scipy.fft.fft` for more details.
418 Returns
419 -------
420 idct : ndarray of real
421 The transformed input array.
423 See Also
424 --------
425 dct : Forward DCT
427 Notes
428 -----
429 For a single dimension array `x`, ``idct(x, norm='ortho')`` is equal to
430 MATLAB ``idct(x)``.
432 'The' IDCT is the IDCT-II, which is the same as the normalized DCT-III.
434 The IDCT is equivalent to a normal DCT except for the normalization and
435 type. DCT type 1 and 4 are their own inverse and DCTs 2 and 3 are each
436 other's inverses.
438 Examples
439 --------
440 The Type 1 DCT is equivalent to the DFT for real, even-symmetrical
441 inputs. The output is also real and even-symmetrical. Half of the IFFT
442 input is used to generate half of the IFFT output:
444 >>> from scipy.fft import ifft, idct
445 >>> ifft(np.array([ 30., -8., 6., -2., 6., -8.])).real
446 array([ 4., 3., 5., 10., 5., 3.])
447 >>> idct(np.array([ 30., -8., 6., -2.]), 1)
448 array([ 4., 3., 5., 10.])
450 """
451 return (Dispatchable(x, np.ndarray),)
454@_dispatch
455def dst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, workers=None):
456 r"""
457 Return the Discrete Sine Transform of arbitrary type sequence x.
459 Parameters
460 ----------
461 x : array_like
462 The input array.
463 type : {1, 2, 3, 4}, optional
464 Type of the DST (see Notes). Default type is 2.
465 n : int, optional
466 Length of the transform. If ``n < x.shape[axis]``, `x` is
467 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
468 default results in ``n = x.shape[axis]``.
469 axis : int, optional
470 Axis along which the dst is computed; the default is over the
471 last axis (i.e., ``axis=-1``).
472 norm : {None, 'ortho'}, optional
473 Normalization mode (see Notes). Default is None.
474 overwrite_x : bool, optional
475 If True, the contents of `x` can be destroyed; the default is False.
476 workers : int, optional
477 Maximum number of workers to use for parallel computation. If negative,
478 the value wraps around from ``os.cpu_count()``.
479 See :func:`~scipy.fft.fft` for more details.
481 Returns
482 -------
483 dst : ndarray of reals
484 The transformed input array.
486 See Also
487 --------
488 idst : Inverse DST
490 Notes
491 -----
492 For a single dimension array ``x``.
494 For ``norm=None``, there is no scaling on the `dst` and the `idst` is
495 scaled by ``1/N`` where ``N`` is the "logical" size of the DST. For
496 ``norm='ortho'`` both directions are scaled by the same factor
497 ``1/sqrt(N)``.
499 There are, theoretically, 8 types of the DST for different combinations of
500 even/odd boundary conditions and boundary off sets [1]_, only the first
501 4 types are implemented in SciPy.
503 **Type I**
505 There are several definitions of the DST-I; we use the following
506 for ``norm=None``. DST-I assumes the input is odd around `n=-1` and `n=N`.
508 .. math::
510 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(n+1)}{N+1}\right)
512 Note that the DST-I is only supported for input size > 1.
513 The (unnormalized) DST-I is its own inverse, up to a factor `2(N+1)`.
514 The orthonormalized DST-I is exactly its own inverse.
516 **Type II**
518 There are several definitions of the DST-II; we use the following for
519 ``norm=None``. DST-II assumes the input is odd around `n=-1/2` and
520 `n=N-1/2`; the output is odd around :math:`k=-1` and even around `k=N-1`
522 .. math::
524 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(2n+1)}{2N}\right)
526 if ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
528 .. math::
530 f = \begin{cases}
531 \sqrt{\frac{1}{4N}} & \text{if }k = 0, \\
532 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases}
534 **Type III**
536 There are several definitions of the DST-III, we use the following (for
537 ``norm=None``). DST-III assumes the input is odd around `n=-1` and even
538 around `n=N-1`
540 .. math::
542 y_k = (-1)^k x_{N-1} + 2 \sum_{n=0}^{N-2} x_n \sin\left(
543 \frac{\pi(2k+1)(n+1)}{2N}\right)
545 The (unnormalized) DST-III is the inverse of the (unnormalized) DST-II, up
546 to a factor `2N`. The orthonormalized DST-III is exactly the inverse of the
547 orthonormalized DST-II.
549 **Type IV**
551 There are several definitions of the DST-IV, we use the following (for
552 ``norm=None``). DST-IV assumes the input is odd around `n=-0.5` and even
553 around `n=N-0.5`
555 .. math::
557 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(2k+1)(2n+1)}{4N}\right)
559 The (unnormalized) DST-IV is its own inverse, up to a factor `2N`. The
560 orthonormalized DST-IV is exactly its own inverse.
562 References
563 ----------
564 .. [1] Wikipedia, "Discrete sine transform",
565 https://en.wikipedia.org/wiki/Discrete_sine_transform
567 """
568 return (Dispatchable(x, np.ndarray),)
571@_dispatch
572def idst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False,
573 workers=None):
574 """
575 Return the Inverse Discrete Sine Transform of an arbitrary type sequence.
577 Parameters
578 ----------
579 x : array_like
580 The input array.
581 type : {1, 2, 3, 4}, optional
582 Type of the DST (see Notes). Default type is 2.
583 n : int, optional
584 Length of the transform. If ``n < x.shape[axis]``, `x` is
585 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
586 default results in ``n = x.shape[axis]``.
587 axis : int, optional
588 Axis along which the idst is computed; the default is over the
589 last axis (i.e., ``axis=-1``).
590 norm : {None, 'ortho'}, optional
591 Normalization mode (see Notes). Default is None.
592 overwrite_x : bool, optional
593 If True, the contents of `x` can be destroyed; the default is False.
594 workers : int, optional
595 Maximum number of workers to use for parallel computation. If negative,
596 the value wraps around from ``os.cpu_count()``.
597 See :func:`~scipy.fft.fft` for more details.
599 Returns
600 -------
601 idst : ndarray of real
602 The transformed input array.
604 See Also
605 --------
606 dst : Forward DST
608 Notes
609 -----
611 'The' IDST is the IDST-II, which is the same as the normalized DST-III.
613 The IDST is equivalent to a normal DST except for the normalization and
614 type. DST type 1 and 4 are their own inverse and DSTs 2 and 3 are each
615 other's inverses.
617 """
618 return (Dispatchable(x, np.ndarray),)