Hide keyboard shortcuts

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 

4 

5__all__ = ['dct', 'idct', 'dst', 'idst', 'dctn', 'idctn', 'dstn', 'idstn'] 

6 

7 

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. 

13 

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. 

40 

41 Returns 

42 ------- 

43 y : ndarray of real 

44 The transformed input array. 

45 

46 See Also 

47 -------- 

48 idctn : Inverse multidimensional DCT 

49 

50 Notes 

51 ----- 

52 For full details of the DCT types and normalization modes, as well as 

53 references, see `dct`. 

54 

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 

61 

62 """ 

63 return (Dispatchable(x, np.ndarray),) 

64 

65 

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. 

71 

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. 

98 

99 Returns 

100 ------- 

101 y : ndarray of real 

102 The transformed input array. 

103 

104 See Also 

105 -------- 

106 dctn : multidimensional DCT 

107 

108 Notes 

109 ----- 

110 For full details of the IDCT types and normalization modes, as well as 

111 references, see `idct`. 

112 

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 

119 

120 """ 

121 return (Dispatchable(x, np.ndarray),) 

122 

123 

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. 

129 

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. 

156 

157 Returns 

158 ------- 

159 y : ndarray of real 

160 The transformed input array. 

161 

162 See Also 

163 -------- 

164 idstn : Inverse multidimensional DST 

165 

166 Notes 

167 ----- 

168 For full details of the DST types and normalization modes, as well as 

169 references, see `dst`. 

170 

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 

177 

178 """ 

179 return (Dispatchable(x, np.ndarray),) 

180 

181 

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. 

187 

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. 

214 

215 Returns 

216 ------- 

217 y : ndarray of real 

218 The transformed input array. 

219 

220 See Also 

221 -------- 

222 dstn : multidimensional DST 

223 

224 Notes 

225 ----- 

226 For full details of the IDST types and normalization modes, as well as 

227 references, see `idst`. 

228 

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 

235 

236 """ 

237 return (Dispatchable(x, np.ndarray),) 

238 

239 

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. 

244 

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. 

266 

267 Returns 

268 ------- 

269 y : ndarray of real 

270 The transformed input array. 

271 

272 See Also 

273 -------- 

274 idct : Inverse DCT 

275 

276 Notes 

277 ----- 

278 For a single dimension array ``x``, ``dct(x, norm='ortho')`` is equal to 

279 MATLAB ``dct(x)``. 

280 

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)``. 

284 

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. 

288 

289 **Type I** 

290 

291 There are several definitions of the DCT-I; we use the following 

292 (for ``norm=None``) 

293 

294 .. math:: 

295 

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) 

298 

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`` 

302 

303 .. math:: 

304 

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} 

308 

309 .. note:: 

310 The DCT-I is only supported for input size > 1. 

311 

312 **Type II** 

313 

314 There are several definitions of the DCT-II; we use the following 

315 (for ``norm=None``) 

316 

317 .. math:: 

318 

319 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi k(2n+1)}{2N} \right) 

320 

321 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

322 

323 .. math:: 

324 f = \begin{cases} 

325 \sqrt{\frac{1}{4N}} & \text{if }k=0, \\ 

326 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases} 

327 

328 which makes the corresponding matrix of coefficients orthonormal 

329 (``O @ O.T = np.eye(N)``). 

330 

331 **Type III** 

332 

333 There are several definitions, we use the following (for ``norm=None``) 

334 

335 .. math:: 

336 

337 y_k = x_0 + 2 \sum_{n=1}^{N-1} x_n \cos\left(\frac{\pi(2k+1)n}{2N}\right) 

338 

339 or, for ``norm='ortho'`` 

340 

341 .. math:: 

342 

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) 

345 

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. 

349 

350 **Type IV** 

351 

352 There are several definitions of the DCT-IV; we use the following 

353 (for ``norm=None``) 

354 

355 .. math:: 

356 

357 y_k = 2 \sum_{n=0}^{N-1} x_n \cos\left(\frac{\pi(2k+1)(2n+1)}{4N} \right) 

358 

359 If ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

360 

361 .. math:: 

362 

363 f = \frac{1}{\sqrt{2N}} 

364 

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 

373 

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: 

379 

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.]) 

385 

386 """ 

387 return (Dispatchable(x, np.ndarray),) 

388 

389 

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. 

395 

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. 

417 

418 Returns 

419 ------- 

420 idct : ndarray of real 

421 The transformed input array. 

422 

423 See Also 

424 -------- 

425 dct : Forward DCT 

426 

427 Notes 

428 ----- 

429 For a single dimension array `x`, ``idct(x, norm='ortho')`` is equal to 

430 MATLAB ``idct(x)``. 

431 

432 'The' IDCT is the IDCT-II, which is the same as the normalized DCT-III. 

433 

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. 

437 

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: 

443 

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.]) 

449 

450 """ 

451 return (Dispatchable(x, np.ndarray),) 

452 

453 

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. 

458 

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. 

480 

481 Returns 

482 ------- 

483 dst : ndarray of reals 

484 The transformed input array. 

485 

486 See Also 

487 -------- 

488 idst : Inverse DST 

489 

490 Notes 

491 ----- 

492 For a single dimension array ``x``. 

493 

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)``. 

498 

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. 

502 

503 **Type I** 

504 

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`. 

507 

508 .. math:: 

509 

510 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(n+1)}{N+1}\right) 

511 

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. 

515 

516 **Type II** 

517 

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` 

521 

522 .. math:: 

523 

524 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(k+1)(2n+1)}{2N}\right) 

525 

526 if ``norm='ortho'``, ``y[k]`` is multiplied by a scaling factor ``f`` 

527 

528 .. math:: 

529 

530 f = \begin{cases} 

531 \sqrt{\frac{1}{4N}} & \text{if }k = 0, \\ 

532 \sqrt{\frac{1}{2N}} & \text{otherwise} \end{cases} 

533 

534 **Type III** 

535 

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` 

539 

540 .. math:: 

541 

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) 

544 

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. 

548 

549 **Type IV** 

550 

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` 

554 

555 .. math:: 

556 

557 y_k = 2 \sum_{n=0}^{N-1} x_n \sin\left(\frac{\pi(2k+1)(2n+1)}{4N}\right) 

558 

559 The (unnormalized) DST-IV is its own inverse, up to a factor `2N`. The 

560 orthonormalized DST-IV is exactly its own inverse. 

561 

562 References 

563 ---------- 

564 .. [1] Wikipedia, "Discrete sine transform", 

565 https://en.wikipedia.org/wiki/Discrete_sine_transform 

566 

567 """ 

568 return (Dispatchable(x, np.ndarray),) 

569 

570 

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. 

576 

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. 

598 

599 Returns 

600 ------- 

601 idst : ndarray of real 

602 The transformed input array. 

603 

604 See Also 

605 -------- 

606 dst : Forward DST 

607 

608 Notes 

609 ----- 

610 

611 'The' IDST is the IDST-II, which is the same as the normalized DST-III. 

612 

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. 

616 

617 """ 

618 return (Dispatchable(x, np.ndarray),)