Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/scipy/fftpack/realtransforms.py : 43%

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
1"""
2Real spectrum transforms (DCT, DST, MDCT)
3"""
5__all__ = ['dct', 'idct', 'dst', 'idst', 'dctn', 'idctn', 'dstn', 'idstn']
7from scipy.fft import _pocketfft
8from .helper import _good_shape
10_inverse_typemap = {1: 1, 2: 3, 3: 2, 4: 4}
13def dctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False):
14 """
15 Return multidimensional Discrete Cosine Transform along the specified axes.
17 Parameters
18 ----------
19 x : array_like
20 The input array.
21 type : {1, 2, 3, 4}, optional
22 Type of the DCT (see Notes). Default type is 2.
23 shape : int or array_like of ints or None, optional
24 The shape of the result. If both `shape` and `axes` (see below) are
25 None, `shape` is ``x.shape``; if `shape` is None but `axes` is
26 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``.
27 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros.
28 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to
29 length ``shape[i]``.
30 If any element of `shape` is -1, the size of the corresponding
31 dimension of `x` is used.
32 axes : int or array_like of ints or None, optional
33 Axes along which the DCT is computed.
34 The default is over all axes.
35 norm : {None, 'ortho'}, optional
36 Normalization mode (see Notes). Default is None.
37 overwrite_x : bool, optional
38 If True, the contents of `x` can be destroyed; the default is False.
40 Returns
41 -------
42 y : ndarray of real
43 The transformed input array.
45 See Also
46 --------
47 idctn : Inverse multidimensional DCT
49 Notes
50 -----
51 For full details of the DCT types and normalization modes, as well as
52 references, see `dct`.
54 Examples
55 --------
56 >>> from scipy.fftpack import dctn, idctn
57 >>> y = np.random.randn(16, 16)
58 >>> np.allclose(y, idctn(dctn(y, norm='ortho'), norm='ortho'))
59 True
61 """
62 shape = _good_shape(x, shape, axes)
63 return _pocketfft.dctn(x, type, shape, axes, norm, overwrite_x)
66def idctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False):
67 """
68 Return multidimensional Discrete Cosine Transform along the specified axes.
70 Parameters
71 ----------
72 x : array_like
73 The input array.
74 type : {1, 2, 3, 4}, optional
75 Type of the DCT (see Notes). Default type is 2.
76 shape : int or array_like of ints or None, optional
77 The shape of the result. If both `shape` and `axes` (see below) are
78 None, `shape` is ``x.shape``; if `shape` is None but `axes` is
79 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``.
80 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros.
81 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to
82 length ``shape[i]``.
83 If any element of `shape` is -1, the size of the corresponding
84 dimension of `x` is used.
85 axes : int or array_like of ints or None, optional
86 Axes along which the IDCT is computed.
87 The default is over all axes.
88 norm : {None, 'ortho'}, optional
89 Normalization mode (see Notes). Default is None.
90 overwrite_x : bool, optional
91 If True, the contents of `x` can be destroyed; the default is False.
93 Returns
94 -------
95 y : ndarray of real
96 The transformed input array.
98 See Also
99 --------
100 dctn : multidimensional DCT
102 Notes
103 -----
104 For full details of the IDCT types and normalization modes, as well as
105 references, see `idct`.
107 Examples
108 --------
109 >>> from scipy.fftpack import dctn, idctn
110 >>> y = np.random.randn(16, 16)
111 >>> np.allclose(y, idctn(dctn(y, norm='ortho'), norm='ortho'))
112 True
114 """
115 type = _inverse_typemap[type]
116 shape = _good_shape(x, shape, axes)
117 return _pocketfft.dctn(x, type, shape, axes, norm, overwrite_x)
120def dstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False):
121 """
122 Return multidimensional Discrete Sine Transform along the specified axes.
124 Parameters
125 ----------
126 x : array_like
127 The input array.
128 type : {1, 2, 3, 4}, optional
129 Type of the DST (see Notes). Default type is 2.
130 shape : int or array_like of ints or None, optional
131 The shape of the result. If both `shape` and `axes` (see below) are
132 None, `shape` is ``x.shape``; if `shape` is None but `axes` is
133 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``.
134 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros.
135 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to
136 length ``shape[i]``.
137 If any element of `shape` is -1, the size of the corresponding
138 dimension of `x` is used.
139 axes : int or array_like of ints or None, optional
140 Axes along which the DCT is computed.
141 The default is over all axes.
142 norm : {None, 'ortho'}, optional
143 Normalization mode (see Notes). Default is None.
144 overwrite_x : bool, optional
145 If True, the contents of `x` can be destroyed; the default is False.
147 Returns
148 -------
149 y : ndarray of real
150 The transformed input array.
152 See Also
153 --------
154 idstn : Inverse multidimensional DST
156 Notes
157 -----
158 For full details of the DST types and normalization modes, as well as
159 references, see `dst`.
161 Examples
162 --------
163 >>> from scipy.fftpack import dstn, idstn
164 >>> y = np.random.randn(16, 16)
165 >>> np.allclose(y, idstn(dstn(y, norm='ortho'), norm='ortho'))
166 True
168 """
169 shape = _good_shape(x, shape, axes)
170 return _pocketfft.dstn(x, type, shape, axes, norm, overwrite_x)
173def idstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False):
174 """
175 Return multidimensional Discrete Sine Transform along the specified axes.
177 Parameters
178 ----------
179 x : array_like
180 The input array.
181 type : {1, 2, 3, 4}, optional
182 Type of the DST (see Notes). Default type is 2.
183 shape : int or array_like of ints or None, optional
184 The shape of the result. If both `shape` and `axes` (see below) are
185 None, `shape` is ``x.shape``; if `shape` is None but `axes` is
186 not None, then `shape` is ``scipy.take(x.shape, axes, axis=0)``.
187 If ``shape[i] > x.shape[i]``, the ith dimension is padded with zeros.
188 If ``shape[i] < x.shape[i]``, the ith dimension is truncated to
189 length ``shape[i]``.
190 If any element of `shape` is -1, the size of the corresponding
191 dimension of `x` is used.
192 axes : int or array_like of ints or None, optional
193 Axes along which the IDST is computed.
194 The default is over all axes.
195 norm : {None, 'ortho'}, optional
196 Normalization mode (see Notes). Default is None.
197 overwrite_x : bool, optional
198 If True, the contents of `x` can be destroyed; the default is False.
200 Returns
201 -------
202 y : ndarray of real
203 The transformed input array.
205 See Also
206 --------
207 dstn : multidimensional DST
209 Notes
210 -----
211 For full details of the IDST types and normalization modes, as well as
212 references, see `idst`.
214 Examples
215 --------
216 >>> from scipy.fftpack import dstn, idstn
217 >>> y = np.random.randn(16, 16)
218 >>> np.allclose(y, idstn(dstn(y, norm='ortho'), norm='ortho'))
219 True
221 """
222 type = _inverse_typemap[type]
223 shape = _good_shape(x, shape, axes)
224 return _pocketfft.dstn(x, type, shape, axes, norm, overwrite_x)
227def dct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False):
228 r"""
229 Return the Discrete Cosine Transform of arbitrary type sequence x.
231 Parameters
232 ----------
233 x : array_like
234 The input array.
235 type : {1, 2, 3, 4}, optional
236 Type of the DCT (see Notes). Default type is 2.
237 n : int, optional
238 Length of the transform. If ``n < x.shape[axis]``, `x` is
239 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
240 default results in ``n = x.shape[axis]``.
241 axis : int, optional
242 Axis along which the dct is computed; the default is over the
243 last axis (i.e., ``axis=-1``).
244 norm : {None, 'ortho'}, optional
245 Normalization mode (see Notes). Default is None.
246 overwrite_x : bool, optional
247 If True, the contents of `x` can be destroyed; the default is False.
249 Returns
250 -------
251 y : ndarray of real
252 The transformed input array.
254 See Also
255 --------
256 idct : Inverse DCT
258 Notes
259 -----
260 For a single dimension array ``x``, ``dct(x, norm='ortho')`` is equal to
261 MATLAB ``dct(x)``.
263 There are, theoretically, 8 types of the DCT, only the first 4 types are
264 implemented in scipy. 'The' DCT generally refers to DCT type 2, and 'the'
265 Inverse DCT generally refers to DCT type 3.
267 **Type I**
269 There are several definitions of the DCT-I; we use the following
270 (for ``norm=None``)
272 .. math::
274 y_k = x_0 + (-1)^k x_{N-1} + 2 \sum_{n=1}^{N-2} x_n \cos\left(
275 \frac{\pi k n}{N-1} \right)
277 If ``norm='ortho'``, ``x[0]`` and ``x[N-1]`` are multiplied by a scaling
278 factor of :math:`\sqrt{2}`, and ``y[k]`` is multiplied by a scaling factor
279 ``f``
281 .. math::
283 f = \begin{cases}
284 \frac{1}{2}\sqrt{\frac{1}{N-1}} & \text{if }k=0\text{ or }N-1, \\
285 \frac{1}{2}\sqrt{\frac{2}{N-1}} & \text{otherwise} \end{cases}
287 .. versionadded:: 1.2.0
288 Orthonormalization in DCT-I.
290 .. note::
291 The DCT-I is only supported for input size > 1.
293 **Type II**
295 There are several definitions of the DCT-II; we use the following
296 (for ``norm=None``)
298 .. math::
300 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi k(2n+1)}{2N} \right)
302 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
304 .. math::
305 f = \begin{cases}
306 \sqrt{\frac{1}{4N}} & \text{if }k=0, \\
307 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases}
309 which makes the corresponding matrix of coefficients orthonormal
310 (``O @ O.T = np.eye(N)``).
312 **Type III**
314 There are several definitions, we use the following (for ``norm=None``)
316 .. math::
318 y_k = x_0 + 2 \sum_{n=1}^{N-1} x_n \cos\left(\frac{\pi(2k+1)n}{2N}\right)
320 or, for ``norm='ortho'``
322 .. math::
324 y_k = \frac{x_0}{\sqrt{N}} + \sqrt{\frac{2}{N}} \sum_{n=1}^{N-1} x_n
325 \cos\left(\frac{\pi(2k+1)n}{2N}\right)
327 The (unnormalized) DCT-III is the inverse of the (unnormalized) DCT-II, up
328 to a factor `2N`. The orthonormalized DCT-III is exactly the inverse of
329 the orthonormalized DCT-II.
331 **Type IV**
333 There are several definitions of the DCT-IV; we use the following
334 (for ``norm=None``)
336 .. math::
338 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi(2k+1)(2n+1)}{4N} \right)
340 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
342 .. math::
344 f = \frac{1}{\sqrt{2N}}
346 .. versionadded:: 1.2.0
347 Support for DCT-IV.
349 References
350 ----------
351 .. [1] 'A Fast Cosine Transform in One and Two Dimensions', by J.
352 Makhoul, `IEEE Transactions on acoustics, speech and signal
353 processing` vol. 28(1), pp. 27-34,
354 :doi:`10.1109/TASSP.1980.1163351` (1980).
355 .. [2] Wikipedia, "Discrete cosine transform",
356 https://en.wikipedia.org/wiki/Discrete_cosine_transform
358 Examples
359 --------
360 The Type 1 DCT is equivalent to the FFT (though faster) for real,
361 even-symmetrical inputs. The output is also real and even-symmetrical.
362 Half of the FFT input is used to generate half of the FFT output:
364 >>> from scipy.fftpack import fft, dct
365 >>> fft(np.array([4., 3., 5., 10., 5., 3.])).real
366 array([ 30., -8., 6., -2., 6., -8.])
367 >>> dct(np.array([4., 3., 5., 10.]), 1)
368 array([ 30., -8., 6., -2.])
370 """
371 return _pocketfft.dct(x, type, n, axis, norm, overwrite_x)
374def idct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False):
375 """
376 Return the Inverse Discrete Cosine Transform of an arbitrary type sequence.
378 Parameters
379 ----------
380 x : array_like
381 The input array.
382 type : {1, 2, 3, 4}, optional
383 Type of the DCT (see Notes). Default type is 2.
384 n : int, optional
385 Length of the transform. If ``n < x.shape[axis]``, `x` is
386 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
387 default results in ``n = x.shape[axis]``.
388 axis : int, optional
389 Axis along which the idct is computed; the default is over the
390 last axis (i.e., ``axis=-1``).
391 norm : {None, 'ortho'}, optional
392 Normalization mode (see Notes). Default is None.
393 overwrite_x : bool, optional
394 If True, the contents of `x` can be destroyed; the default is False.
396 Returns
397 -------
398 idct : ndarray of real
399 The transformed input array.
401 See Also
402 --------
403 dct : Forward DCT
405 Notes
406 -----
407 For a single dimension array `x`, ``idct(x, norm='ortho')`` is equal to
408 MATLAB ``idct(x)``.
410 'The' IDCT is the IDCT of type 2, which is the same as DCT of type 3.
412 IDCT of type 1 is the DCT of type 1, IDCT of type 2 is the DCT of type
413 3, and IDCT of type 3 is the DCT of type 2. IDCT of type 4 is the DCT
414 of type 4. For the definition of these types, see `dct`.
416 Examples
417 --------
418 The Type 1 DCT is equivalent to the DFT for real, even-symmetrical
419 inputs. The output is also real and even-symmetrical. Half of the IFFT
420 input is used to generate half of the IFFT output:
422 >>> from scipy.fftpack import ifft, idct
423 >>> ifft(np.array([ 30., -8., 6., -2., 6., -8.])).real
424 array([ 4., 3., 5., 10., 5., 3.])
425 >>> idct(np.array([ 30., -8., 6., -2.]), 1) / 6
426 array([ 4., 3., 5., 10.])
428 """
429 type = _inverse_typemap[type]
430 return _pocketfft.dct(x, type, n, axis, norm, overwrite_x)
433def dst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False):
434 r"""
435 Return the Discrete Sine Transform of arbitrary type sequence x.
437 Parameters
438 ----------
439 x : array_like
440 The input array.
441 type : {1, 2, 3, 4}, optional
442 Type of the DST (see Notes). Default type is 2.
443 n : int, optional
444 Length of the transform. If ``n < x.shape[axis]``, `x` is
445 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
446 default results in ``n = x.shape[axis]``.
447 axis : int, optional
448 Axis along which the dst is computed; the default is over the
449 last axis (i.e., ``axis=-1``).
450 norm : {None, 'ortho'}, optional
451 Normalization mode (see Notes). Default is None.
452 overwrite_x : bool, optional
453 If True, the contents of `x` can be destroyed; the default is False.
455 Returns
456 -------
457 dst : ndarray of reals
458 The transformed input array.
460 See Also
461 --------
462 idst : Inverse DST
464 Notes
465 -----
466 For a single dimension array ``x``.
468 There are, theoretically, 8 types of the DST for different combinations of
469 even/odd boundary conditions and boundary off sets [1]_, only the first
470 4 types are implemented in scipy.
472 **Type I**
474 There are several definitions of the DST-I; we use the following
475 for ``norm=None``. DST-I assumes the input is odd around `n=-1` and `n=N`.
477 .. math::
479 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(n+1)}{N+1}\right)
481 Note that the DST-I is only supported for input size > 1.
482 The (unnormalized) DST-I is its own inverse, up to a factor `2(N+1)`.
483 The orthonormalized DST-I is exactly its own inverse.
485 **Type II**
487 There are several definitions of the DST-II; we use the following for
488 ``norm=None``. DST-II assumes the input is odd around `n=-1/2` and
489 `n=N-1/2`; the output is odd around :math:`k=-1` and even around `k=N-1`
491 .. math::
493 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(2n+1)}{2N}\right)
495 if ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f``
497 .. math::
499 f = \begin{cases}
500 \sqrt{\frac{1}{4N}} & \text{if }k = 0, \\
501 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases}
503 **Type III**
505 There are several definitions of the DST-III, we use the following (for
506 ``norm=None``). DST-III assumes the input is odd around `n=-1` and even
507 around `n=N-1`
509 .. math::
511 y_k = (-1)^k x_{N-1} + 2 \sum_{n=0}^{N-2} x_n \sin\left(
512 \frac{\pi(2k+1)(n+1)}{2N}\right)
514 The (unnormalized) DST-III is the inverse of the (unnormalized) DST-II, up
515 to a factor `2N`. The orthonormalized DST-III is exactly the inverse of the
516 orthonormalized DST-II.
518 .. versionadded:: 0.11.0
520 **Type IV**
522 There are several definitions of the DST-IV, we use the following (for
523 ``norm=None``). DST-IV assumes the input is odd around `n=-0.5` and even
524 around `n=N-0.5`
526 .. math::
528 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(2k+1)(2n+1)}{4N}\right)
530 The (unnormalized) DST-IV is its own inverse, up to a factor `2N`. The
531 orthonormalized DST-IV is exactly its own inverse.
533 .. versionadded:: 1.2.0
534 Support for DST-IV.
536 References
537 ----------
538 .. [1] Wikipedia, "Discrete sine transform",
539 https://en.wikipedia.org/wiki/Discrete_sine_transform
541 """
542 return _pocketfft.dst(x, type, n, axis, norm, overwrite_x)
545def idst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False):
546 """
547 Return the Inverse Discrete Sine Transform of an arbitrary type sequence.
549 Parameters
550 ----------
551 x : array_like
552 The input array.
553 type : {1, 2, 3, 4}, optional
554 Type of the DST (see Notes). Default type is 2.
555 n : int, optional
556 Length of the transform. If ``n < x.shape[axis]``, `x` is
557 truncated. If ``n > x.shape[axis]``, `x` is zero-padded. The
558 default results in ``n = x.shape[axis]``.
559 axis : int, optional
560 Axis along which the idst is computed; the default is over the
561 last axis (i.e., ``axis=-1``).
562 norm : {None, 'ortho'}, optional
563 Normalization mode (see Notes). Default is None.
564 overwrite_x : bool, optional
565 If True, the contents of `x` can be destroyed; the default is False.
567 Returns
568 -------
569 idst : ndarray of real
570 The transformed input array.
572 See Also
573 --------
574 dst : Forward DST
576 Notes
577 -----
578 'The' IDST is the IDST of type 2, which is the same as DST of type 3.
580 IDST of type 1 is the DST of type 1, IDST of type 2 is the DST of type
581 3, and IDST of type 3 is the DST of type 2. For the definition of these
582 types, see `dst`.
584 .. versionadded:: 0.11.0
586 """
587 type = _inverse_typemap[type]
588 return _pocketfft.dst(x, type, n, axis, norm, overwrite_x)