Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/numpy/lib/_twodim_base_impl.py: 31%

1""" Basic functions for manipulating 2d arrays 

2 

3""" 

4import functools 

5import operator 

6 

7from numpy._core._multiarray_umath import _array_converter 

8from numpy._core.numeric import ( 

9 asanyarray, arange, zeros, greater_equal, multiply, ones, 

10 asarray, where, int8, int16, int32, int64, intp, empty, promote_types, 

11 diagonal, nonzero, indices 

12 ) 

13from numpy._core.overrides import set_array_function_like_doc, set_module 

14from numpy._core import overrides 

15from numpy._core import iinfo 

16from numpy.lib._stride_tricks_impl import broadcast_to 

17 

18 

19__all__ = [ 

20 'diag', 'diagflat', 'eye', 'fliplr', 'flipud', 'tri', 'triu', 

21 'tril', 'vander', 'histogram2d', 'mask_indices', 'tril_indices', 

22 'tril_indices_from', 'triu_indices', 'triu_indices_from', ] 

23 

24 

25array_function_dispatch = functools.partial( 

26 overrides.array_function_dispatch, module='numpy') 

27 

28 

29i1 = iinfo(int8) 

30i2 = iinfo(int16) 

31i4 = iinfo(int32) 

32 

33 

34def _min_int(low, high): 

35 """ get small int that fits the range """ 

36 if high <= i1.max and low >= i1.min: 

37 return int8 

38 if high <= i2.max and low >= i2.min: 

39 return int16 

40 if high <= i4.max and low >= i4.min: 

41 return int32 

42 return int64 

43 

44 

45def _flip_dispatcher(m): 

46 return (m,) 

47 

48 

49@array_function_dispatch(_flip_dispatcher) 

50def fliplr(m): 

51 """ 

52 Reverse the order of elements along axis 1 (left/right). 

53 

54 For a 2-D array, this flips the entries in each row in the left/right 

55 direction. Columns are preserved, but appear in a different order than 

56 before. 

57 

58 Parameters 

59 ---------- 

60 m : array_like 

61 Input array, must be at least 2-D. 

62 

63 Returns 

64 ------- 

65 f : ndarray 

66 A view of `m` with the columns reversed. Since a view 

67 is returned, this operation is :math:`\\mathcal O(1)`. 

68 

69 See Also 

70 -------- 

71 flipud : Flip array in the up/down direction. 

72 flip : Flip array in one or more dimensions. 

73 rot90 : Rotate array counterclockwise. 

74 

75 Notes 

76 ----- 

77 Equivalent to ``m[:,::-1]`` or ``np.flip(m, axis=1)``. 

78 Requires the array to be at least 2-D. 

79 

80 Examples 

81 -------- 

82 >>> A = np.diag([1.,2.,3.]) 

83 >>> A 

84 array([[1., 0., 0.], 

85 [0., 2., 0.], 

86 [0., 0., 3.]]) 

87 >>> np.fliplr(A) 

88 array([[0., 0., 1.], 

89 [0., 2., 0.], 

90 [3., 0., 0.]]) 

91 

92 >>> A = np.random.randn(2,3,5) 

93 >>> np.all(np.fliplr(A) == A[:,::-1,...]) 

94 True 

95 

96 """ 

97 m = asanyarray(m) 

98 if m.ndim < 2: 

99 raise ValueError("Input must be >= 2-d.") 

100 return m[:, ::-1] 

101 

102 

103@array_function_dispatch(_flip_dispatcher) 

104def flipud(m): 

105 """ 

106 Reverse the order of elements along axis 0 (up/down). 

107 

108 For a 2-D array, this flips the entries in each column in the up/down 

109 direction. Rows are preserved, but appear in a different order than before. 

110 

111 Parameters 

112 ---------- 

113 m : array_like 

114 Input array. 

115 

116 Returns 

117 ------- 

118 out : array_like 

119 A view of `m` with the rows reversed. Since a view is 

120 returned, this operation is :math:`\\mathcal O(1)`. 

121 

122 See Also 

123 -------- 

124 fliplr : Flip array in the left/right direction. 

125 flip : Flip array in one or more dimensions. 

126 rot90 : Rotate array counterclockwise. 

127 

128 Notes 

129 ----- 

130 Equivalent to ``m[::-1, ...]`` or ``np.flip(m, axis=0)``. 

131 Requires the array to be at least 1-D. 

132 

133 Examples 

134 -------- 

135 >>> A = np.diag([1.0, 2, 3]) 

136 >>> A 

137 array([[1., 0., 0.], 

138 [0., 2., 0.], 

139 [0., 0., 3.]]) 

140 >>> np.flipud(A) 

141 array([[0., 0., 3.], 

142 [0., 2., 0.], 

143 [1., 0., 0.]]) 

144 

145 >>> A = np.random.randn(2,3,5) 

146 >>> np.all(np.flipud(A) == A[::-1,...]) 

147 True 

148 

149 >>> np.flipud([1,2]) 

150 array([2, 1]) 

151 

152 """ 

153 m = asanyarray(m) 

154 if m.ndim < 1: 

155 raise ValueError("Input must be >= 1-d.") 

156 return m[::-1, ...] 

157 

158 

159@set_array_function_like_doc 

160@set_module('numpy') 

161def eye(N, M=None, k=0, dtype=float, order='C', *, device=None, like=None): 

162 """ 

163 Return a 2-D array with ones on the diagonal and zeros elsewhere. 

164 

165 Parameters 

166 ---------- 

167 N : int 

168 Number of rows in the output. 

169 M : int, optional 

170 Number of columns in the output. If None, defaults to `N`. 

171 k : int, optional 

172 Index of the diagonal: 0 (the default) refers to the main diagonal, 

173 a positive value refers to an upper diagonal, and a negative value 

174 to a lower diagonal. 

175 dtype : data-type, optional 

176 Data-type of the returned array. 

177 order : {'C', 'F'}, optional 

178 Whether the output should be stored in row-major (C-style) or 

179 column-major (Fortran-style) order in memory. 

180 

181 .. versionadded:: 1.14.0 

182 device : str, optional 

183 The device on which to place the created array. Default: None. 

184 For Array-API interoperability only, so must be ``"cpu"`` if passed. 

185 

186 .. versionadded:: 2.0.0 

187 ${ARRAY_FUNCTION_LIKE} 

188 

189 .. versionadded:: 1.20.0 

190 

191 Returns 

192 ------- 

193 I : ndarray of shape (N,M) 

194 An array where all elements are equal to zero, except for the `k`-th 

195 diagonal, whose values are equal to one. 

196 

197 See Also 

198 -------- 

199 identity : (almost) equivalent function 

200 diag : diagonal 2-D array from a 1-D array specified by the user. 

201 

202 Examples 

203 -------- 

204 >>> np.eye(2, dtype=int) 

205 array([[1, 0], 

206 [0, 1]]) 

207 >>> np.eye(3, k=1) 

208 array([[0., 1., 0.], 

209 [0., 0., 1.], 

210 [0., 0., 0.]]) 

211 

212 """ 

213 if like is not None: 

214 return _eye_with_like( 

215 like, N, M=M, k=k, dtype=dtype, order=order, device=device 

216 ) 

217 if M is None: 

218 M = N 

219 m = zeros((N, M), dtype=dtype, order=order, device=device) 

220 if k >= M: 

221 return m 

222 # Ensure M and k are integers, so we don't get any surprise casting 

223 # results in the expressions `M-k` and `M+1` used below. This avoids 

224 # a problem with inputs with type (for example) np.uint64. 

225 M = operator.index(M) 

226 k = operator.index(k) 

227 if k >= 0: 

228 i = k 

229 else: 

230 i = (-k) * M 

231 m[:M-k].flat[i::M+1] = 1 

232 return m 

233 

234 

235_eye_with_like = array_function_dispatch()(eye) 

236 

237 

238def _diag_dispatcher(v, k=None): 

239 return (v,) 

240 

241 

242@array_function_dispatch(_diag_dispatcher) 

243def diag(v, k=0): 

244 """ 

245 Extract a diagonal or construct a diagonal array. 

246 

247 See the more detailed documentation for ``numpy.diagonal`` if you use this 

248 function to extract a diagonal and wish to write to the resulting array; 

249 whether it returns a copy or a view depends on what version of numpy you 

250 are using. 

251 

252 Parameters 

253 ---------- 

254 v : array_like 

255 If `v` is a 2-D array, return a copy of its `k`-th diagonal. 

256 If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th 

257 diagonal. 

258 k : int, optional 

259 Diagonal in question. The default is 0. Use `k>0` for diagonals 

260 above the main diagonal, and `k<0` for diagonals below the main 

261 diagonal. 

262 

263 Returns 

264 ------- 

265 out : ndarray 

266 The extracted diagonal or constructed diagonal array. 

267 

268 See Also 

269 -------- 

270 diagonal : Return specified diagonals. 

271 diagflat : Create a 2-D array with the flattened input as a diagonal. 

272 trace : Sum along diagonals. 

273 triu : Upper triangle of an array. 

274 tril : Lower triangle of an array. 

275 

276 Examples 

277 -------- 

278 >>> x = np.arange(9).reshape((3,3)) 

279 >>> x 

280 array([[0, 1, 2], 

281 [3, 4, 5], 

282 [6, 7, 8]]) 

283 

284 >>> np.diag(x) 

285 array([0, 4, 8]) 

286 >>> np.diag(x, k=1) 

287 array([1, 5]) 

288 >>> np.diag(x, k=-1) 

289 array([3, 7]) 

290 

291 >>> np.diag(np.diag(x)) 

292 array([[0, 0, 0], 

293 [0, 4, 0], 

294 [0, 0, 8]]) 

295 

296 """ 

297 v = asanyarray(v) 

298 s = v.shape 

299 if len(s) == 1: 

300 n = s[0]+abs(k) 

301 res = zeros((n, n), v.dtype) 

302 if k >= 0: 

303 i = k 

304 else: 

305 i = (-k) * n 

306 res[:n-k].flat[i::n+1] = v 

307 return res 

308 elif len(s) == 2: 

309 return diagonal(v, k) 

310 else: 

311 raise ValueError("Input must be 1- or 2-d.") 

312 

313 

314@array_function_dispatch(_diag_dispatcher) 

315def diagflat(v, k=0): 

316 """ 

317 Create a two-dimensional array with the flattened input as a diagonal. 

318 

319 Parameters 

320 ---------- 

321 v : array_like 

322 Input data, which is flattened and set as the `k`-th 

323 diagonal of the output. 

324 k : int, optional 

325 Diagonal to set; 0, the default, corresponds to the "main" diagonal, 

326 a positive (negative) `k` giving the number of the diagonal above 

327 (below) the main. 

328 

329 Returns 

330 ------- 

331 out : ndarray 

332 The 2-D output array. 

333 

334 See Also 

335 -------- 

336 diag : MATLAB work-alike for 1-D and 2-D arrays. 

337 diagonal : Return specified diagonals. 

338 trace : Sum along diagonals. 

339 

340 Examples 

341 -------- 

342 >>> np.diagflat([[1,2], [3,4]]) 

343 array([[1, 0, 0, 0], 

344 [0, 2, 0, 0], 

345 [0, 0, 3, 0], 

346 [0, 0, 0, 4]]) 

347 

348 >>> np.diagflat([1,2], 1) 

349 array([[0, 1, 0], 

350 [0, 0, 2], 

351 [0, 0, 0]]) 

352 

353 """ 

354 conv = _array_converter(v) 

355 v, = conv.as_arrays(subok=False) 

356 v = v.ravel() 

357 s = len(v) 

358 n = s + abs(k) 

359 res = zeros((n, n), v.dtype) 

360 if (k >= 0): 

361 i = arange(0, n-k, dtype=intp) 

362 fi = i+k+i*n 

363 else: 

364 i = arange(0, n+k, dtype=intp) 

365 fi = i+(i-k)*n 

366 res.flat[fi] = v 

367 

368 return conv.wrap(res) 

369 

370 

371@set_array_function_like_doc 

372@set_module('numpy') 

373def tri(N, M=None, k=0, dtype=float, *, like=None): 

374 """ 

375 An array with ones at and below the given diagonal and zeros elsewhere. 

376 

377 Parameters 

378 ---------- 

379 N : int 

380 Number of rows in the array. 

381 M : int, optional 

382 Number of columns in the array. 

383 By default, `M` is taken equal to `N`. 

384 k : int, optional 

385 The sub-diagonal at and below which the array is filled. 

386 `k` = 0 is the main diagonal, while `k` < 0 is below it, 

387 and `k` > 0 is above. The default is 0. 

388 dtype : dtype, optional 

389 Data type of the returned array. The default is float. 

390 ${ARRAY_FUNCTION_LIKE} 

391 

392 .. versionadded:: 1.20.0 

393 

394 Returns 

395 ------- 

396 tri : ndarray of shape (N, M) 

397 Array with its lower triangle filled with ones and zero elsewhere; 

398 in other words ``T[i,j] == 1`` for ``j <= i + k``, 0 otherwise. 

399 

400 Examples 

401 -------- 

402 >>> np.tri(3, 5, 2, dtype=int) 

403 array([[1, 1, 1, 0, 0], 

404 [1, 1, 1, 1, 0], 

405 [1, 1, 1, 1, 1]]) 

406 

407 >>> np.tri(3, 5, -1) 

408 array([[0., 0., 0., 0., 0.], 

409 [1., 0., 0., 0., 0.], 

410 [1., 1., 0., 0., 0.]]) 

411 

412 """ 

413 if like is not None: 

414 return _tri_with_like(like, N, M=M, k=k, dtype=dtype) 

415 

416 if M is None: 

417 M = N 

418 

419 m = greater_equal.outer(arange(N, dtype=_min_int(0, N)), 

420 arange(-k, M-k, dtype=_min_int(-k, M - k))) 

421 

422 # Avoid making a copy if the requested type is already bool 

423 m = m.astype(dtype, copy=False) 

424 

425 return m 

426 

427 

428_tri_with_like = array_function_dispatch()(tri) 

429 

430 

431def _trilu_dispatcher(m, k=None): 

432 return (m,) 

433 

434 

435@array_function_dispatch(_trilu_dispatcher) 

436def tril(m, k=0): 

437 """ 

438 Lower triangle of an array. 

439 

440 Return a copy of an array with elements above the `k`-th diagonal zeroed. 

441 For arrays with ``ndim`` exceeding 2, `tril` will apply to the final two 

442 axes. 

443 

444 Parameters 

445 ---------- 

446 m : array_like, shape (..., M, N) 

447 Input array. 

448 k : int, optional 

449 Diagonal above which to zero elements. `k = 0` (the default) is the 

450 main diagonal, `k < 0` is below it and `k > 0` is above. 

451 

452 Returns 

453 ------- 

454 tril : ndarray, shape (..., M, N) 

455 Lower triangle of `m`, of same shape and data-type as `m`. 

456 

457 See Also 

458 -------- 

459 triu : same thing, only for the upper triangle 

460 

461 Examples 

462 -------- 

463 >>> np.tril([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) 

464 array([[ 0, 0, 0], 

465 [ 4, 0, 0], 

466 [ 7, 8, 0], 

467 [10, 11, 12]]) 

468 

469 >>> np.tril(np.arange(3*4*5).reshape(3, 4, 5)) 

470 array([[[ 0, 0, 0, 0, 0], 

471 [ 5, 6, 0, 0, 0], 

472 [10, 11, 12, 0, 0], 

473 [15, 16, 17, 18, 0]], 

474 [[20, 0, 0, 0, 0], 

475 [25, 26, 0, 0, 0], 

476 [30, 31, 32, 0, 0], 

477 [35, 36, 37, 38, 0]], 

478 [[40, 0, 0, 0, 0], 

479 [45, 46, 0, 0, 0], 

480 [50, 51, 52, 0, 0], 

481 [55, 56, 57, 58, 0]]]) 

482 

483 """ 

484 m = asanyarray(m) 

485 mask = tri(*m.shape[-2:], k=k, dtype=bool) 

486 

487 return where(mask, m, zeros(1, m.dtype)) 

488 

489 

490@array_function_dispatch(_trilu_dispatcher) 

491def triu(m, k=0): 

492 """ 

493 Upper triangle of an array. 

494 

495 Return a copy of an array with the elements below the `k`-th diagonal 

496 zeroed. For arrays with ``ndim`` exceeding 2, `triu` will apply to the 

497 final two axes. 

498 

499 Please refer to the documentation for `tril` for further details. 

500 

501 See Also 

502 -------- 

503 tril : lower triangle of an array 

504 

505 Examples 

506 -------- 

507 >>> np.triu([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) 

508 array([[ 1, 2, 3], 

509 [ 4, 5, 6], 

510 [ 0, 8, 9], 

511 [ 0, 0, 12]]) 

512 

513 >>> np.triu(np.arange(3*4*5).reshape(3, 4, 5)) 

514 array([[[ 0, 1, 2, 3, 4], 

515 [ 0, 6, 7, 8, 9], 

516 [ 0, 0, 12, 13, 14], 

517 [ 0, 0, 0, 18, 19]], 

518 [[20, 21, 22, 23, 24], 

519 [ 0, 26, 27, 28, 29], 

520 [ 0, 0, 32, 33, 34], 

521 [ 0, 0, 0, 38, 39]], 

522 [[40, 41, 42, 43, 44], 

523 [ 0, 46, 47, 48, 49], 

524 [ 0, 0, 52, 53, 54], 

525 [ 0, 0, 0, 58, 59]]]) 

526 

527 """ 

528 m = asanyarray(m) 

529 mask = tri(*m.shape[-2:], k=k-1, dtype=bool) 

530 

531 return where(mask, zeros(1, m.dtype), m) 

532 

533 

534def _vander_dispatcher(x, N=None, increasing=None): 

535 return (x,) 

536 

537 

538# Originally borrowed from John Hunter and matplotlib 

539@array_function_dispatch(_vander_dispatcher) 

540def vander(x, N=None, increasing=False): 

541 """ 

542 Generate a Vandermonde matrix. 

543 

544 The columns of the output matrix are powers of the input vector. The 

545 order of the powers is determined by the `increasing` boolean argument. 

546 Specifically, when `increasing` is False, the `i`-th output column is 

547 the input vector raised element-wise to the power of ``N - i - 1``. Such 

548 a matrix with a geometric progression in each row is named for Alexandre- 

549 Theophile Vandermonde. 

550 

551 Parameters 

552 ---------- 

553 x : array_like 

554 1-D input array. 

555 N : int, optional 

556 Number of columns in the output. If `N` is not specified, a square 

557 array is returned (``N = len(x)``). 

558 increasing : bool, optional 

559 Order of the powers of the columns. If True, the powers increase 

560 from left to right, if False (the default) they are reversed. 

561 

562 .. versionadded:: 1.9.0 

563 

564 Returns 

565 ------- 

566 out : ndarray 

567 Vandermonde matrix. If `increasing` is False, the first column is 

568 ``x^(N-1)``, the second ``x^(N-2)`` and so forth. If `increasing` is 

569 True, the columns are ``x^0, x^1, ..., x^(N-1)``. 

570 

571 See Also 

572 -------- 

573 polynomial.polynomial.polyvander 

574 

575 Examples 

576 -------- 

577 >>> x = np.array([1, 2, 3, 5]) 

578 >>> N = 3 

579 >>> np.vander(x, N) 

580 array([[ 1, 1, 1], 

581 [ 4, 2, 1], 

582 [ 9, 3, 1], 

583 [25, 5, 1]]) 

584 

585 >>> np.column_stack([x**(N-1-i) for i in range(N)]) 

586 array([[ 1, 1, 1], 

587 [ 4, 2, 1], 

588 [ 9, 3, 1], 

589 [25, 5, 1]]) 

590 

591 >>> x = np.array([1, 2, 3, 5]) 

592 >>> np.vander(x) 

593 array([[ 1, 1, 1, 1], 

594 [ 8, 4, 2, 1], 

595 [ 27, 9, 3, 1], 

596 [125, 25, 5, 1]]) 

597 >>> np.vander(x, increasing=True) 

598 array([[ 1, 1, 1, 1], 

599 [ 1, 2, 4, 8], 

600 [ 1, 3, 9, 27], 

601 [ 1, 5, 25, 125]]) 

602 

603 The determinant of a square Vandermonde matrix is the product 

604 of the differences between the values of the input vector: 

605 

606 >>> np.linalg.det(np.vander(x)) 

607 48.000000000000043 # may vary 

608 >>> (5-3)*(5-2)*(5-1)*(3-2)*(3-1)*(2-1) 

609 48 

610 

611 """ 

612 x = asarray(x) 

613 if x.ndim != 1: 

614 raise ValueError("x must be a one-dimensional array or sequence.") 

615 if N is None: 

616 N = len(x) 

617 

618 v = empty((len(x), N), dtype=promote_types(x.dtype, int)) 

619 tmp = v[:, ::-1] if not increasing else v 

620 

621 if N > 0: 

622 tmp[:, 0] = 1 

623 if N > 1: 

624 tmp[:, 1:] = x[:, None] 

625 multiply.accumulate(tmp[:, 1:], out=tmp[:, 1:], axis=1) 

626 

627 return v 

628 

629 

630def _histogram2d_dispatcher(x, y, bins=None, range=None, density=None, 

631 weights=None): 

632 yield x 

633 yield y 

634 

635 # This terrible logic is adapted from the checks in histogram2d 

636 try: 

637 N = len(bins) 

638 except TypeError: 

639 N = 1 

640 if N == 2: 

641 yield from bins # bins=[x, y] 

642 else: 

643 yield bins 

644 

645 yield weights 

646 

647 

648@array_function_dispatch(_histogram2d_dispatcher) 

649def histogram2d(x, y, bins=10, range=None, density=None, weights=None): 

650 """ 

651 Compute the bi-dimensional histogram of two data samples. 

652 

653 Parameters 

654 ---------- 

655 x : array_like, shape (N,) 

656 An array containing the x coordinates of the points to be 

657 histogrammed. 

658 y : array_like, shape (N,) 

659 An array containing the y coordinates of the points to be 

660 histogrammed. 

661 bins : int or array_like or [int, int] or [array, array], optional 

662 The bin specification: 

663 

664 * If int, the number of bins for the two dimensions (nx=ny=bins). 

665 * If array_like, the bin edges for the two dimensions 

666 (x_edges=y_edges=bins). 

667 * If [int, int], the number of bins in each dimension 

668 (nx, ny = bins). 

669 * If [array, array], the bin edges in each dimension 

670 (x_edges, y_edges = bins). 

671 * A combination [int, array] or [array, int], where int 

672 is the number of bins and array is the bin edges. 

673 

674 range : array_like, shape(2,2), optional 

675 The leftmost and rightmost edges of the bins along each dimension 

676 (if not specified explicitly in the `bins` parameters): 

677 ``[[xmin, xmax], [ymin, ymax]]``. All values outside of this range 

678 will be considered outliers and not tallied in the histogram. 

679 density : bool, optional 

680 If False, the default, returns the number of samples in each bin. 

681 If True, returns the probability *density* function at the bin, 

682 ``bin_count / sample_count / bin_area``. 

683 weights : array_like, shape(N,), optional 

684 An array of values ``w_i`` weighing each sample ``(x_i, y_i)``. 

685 Weights are normalized to 1 if `density` is True. If `density` is 

686 False, the values of the returned histogram are equal to the sum of 

687 the weights belonging to the samples falling into each bin. 

688 

689 Returns 

690 ------- 

691 H : ndarray, shape(nx, ny) 

692 The bi-dimensional histogram of samples `x` and `y`. Values in `x` 

693 are histogrammed along the first dimension and values in `y` are 

694 histogrammed along the second dimension. 

695 xedges : ndarray, shape(nx+1,) 

696 The bin edges along the first dimension. 

697 yedges : ndarray, shape(ny+1,) 

698 The bin edges along the second dimension. 

699 

700 See Also 

701 -------- 

702 histogram : 1D histogram 

703 histogramdd : Multidimensional histogram 

704 

705 Notes 

706 ----- 

707 When `density` is True, then the returned histogram is the sample 

708 density, defined such that the sum over bins of the product 

709 ``bin_value * bin_area`` is 1. 

710 

711 Please note that the histogram does not follow the Cartesian convention 

712 where `x` values are on the abscissa and `y` values on the ordinate 

713 axis. Rather, `x` is histogrammed along the first dimension of the 

714 array (vertical), and `y` along the second dimension of the array 

715 (horizontal). This ensures compatibility with `histogramdd`. 

716 

717 Examples 

718 -------- 

719 >>> from matplotlib.image import NonUniformImage 

720 >>> import matplotlib.pyplot as plt 

721 

722 Construct a 2-D histogram with variable bin width. First define the bin 

723 edges: 

724 

725 >>> xedges = [0, 1, 3, 5] 

726 >>> yedges = [0, 2, 3, 4, 6] 

727 

728 Next we create a histogram H with random bin content: 

729 

730 >>> x = np.random.normal(2, 1, 100) 

731 >>> y = np.random.normal(1, 1, 100) 

732 >>> H, xedges, yedges = np.histogram2d(x, y, bins=(xedges, yedges)) 

733 >>> # Histogram does not follow Cartesian convention (see Notes), 

734 >>> # therefore transpose H for visualization purposes. 

735 >>> H = H.T 

736 

737 :func:`imshow <matplotlib.pyplot.imshow>` can only display square bins: 

738 

739 >>> fig = plt.figure(figsize=(7, 3)) 

740 >>> ax = fig.add_subplot(131, title='imshow: square bins') 

741 >>> plt.imshow(H, interpolation='nearest', origin='lower', 

742 ... extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]]) 

743 <matplotlib.image.AxesImage object at 0x...> 

744 

745 :func:`pcolormesh <matplotlib.pyplot.pcolormesh>` can display actual edges: 

746 

747 >>> ax = fig.add_subplot(132, title='pcolormesh: actual edges', 

748 ... aspect='equal') 

749 >>> X, Y = np.meshgrid(xedges, yedges) 

750 >>> ax.pcolormesh(X, Y, H) 

751 <matplotlib.collections.QuadMesh object at 0x...> 

752 

753 :class:`NonUniformImage <matplotlib.image.NonUniformImage>` can be used to 

754 display actual bin edges with interpolation: 

755 

756 >>> ax = fig.add_subplot(133, title='NonUniformImage: interpolated', 

757 ... aspect='equal', xlim=xedges[[0, -1]], ylim=yedges[[0, -1]]) 

758 >>> im = NonUniformImage(ax, interpolation='bilinear') 

759 >>> xcenters = (xedges[:-1] + xedges[1:]) / 2 

760 >>> ycenters = (yedges[:-1] + yedges[1:]) / 2 

761 >>> im.set_data(xcenters, ycenters, H) 

762 >>> ax.add_image(im) 

763 >>> plt.show() 

764 

765 It is also possible to construct a 2-D histogram without specifying bin 

766 edges: 

767 

768 >>> # Generate non-symmetric test data 

769 >>> n = 10000 

770 >>> x = np.linspace(1, 100, n) 

771 >>> y = 2*np.log(x) + np.random.rand(n) - 0.5 

772 >>> # Compute 2d histogram. Note the order of x/y and xedges/yedges 

773 >>> H, yedges, xedges = np.histogram2d(y, x, bins=20) 

774 

775 Now we can plot the histogram using 

776 :func:`pcolormesh <matplotlib.pyplot.pcolormesh>`, and a 

777 :func:`hexbin <matplotlib.pyplot.hexbin>` for comparison. 

778 

779 >>> # Plot histogram using pcolormesh 

780 >>> fig, (ax1, ax2) = plt.subplots(ncols=2, sharey=True) 

781 >>> ax1.pcolormesh(xedges, yedges, H, cmap='rainbow') 

782 >>> ax1.plot(x, 2*np.log(x), 'k-') 

783 >>> ax1.set_xlim(x.min(), x.max()) 

784 >>> ax1.set_ylim(y.min(), y.max()) 

785 >>> ax1.set_xlabel('x') 

786 >>> ax1.set_ylabel('y') 

787 >>> ax1.set_title('histogram2d') 

788 >>> ax1.grid() 

789 

790 >>> # Create hexbin plot for comparison 

791 >>> ax2.hexbin(x, y, gridsize=20, cmap='rainbow') 

792 >>> ax2.plot(x, 2*np.log(x), 'k-') 

793 >>> ax2.set_title('hexbin') 

794 >>> ax2.set_xlim(x.min(), x.max()) 

795 >>> ax2.set_xlabel('x') 

796 >>> ax2.grid() 

797 

798 >>> plt.show() 

799 """ 

800 from numpy import histogramdd 

801 

802 if len(x) != len(y): 

803 raise ValueError('x and y must have the same length.') 

804 

805 try: 

806 N = len(bins) 

807 except TypeError: 

808 N = 1 

809 

810 if N != 1 and N != 2: 

811 xedges = yedges = asarray(bins) 

812 bins = [xedges, yedges] 

813 hist, edges = histogramdd([x, y], bins, range, density, weights) 

814 return hist, edges[0], edges[1] 

815 

816 

817@set_module('numpy') 

818def mask_indices(n, mask_func, k=0): 

819 """ 

820 Return the indices to access (n, n) arrays, given a masking function. 

821 

822 Assume `mask_func` is a function that, for a square array a of size 

823 ``(n, n)`` with a possible offset argument `k`, when called as 

824 ``mask_func(a, k)`` returns a new array with zeros in certain locations 

825 (functions like `triu` or `tril` do precisely this). Then this function 

826 returns the indices where the non-zero values would be located. 

827 

828 Parameters 

829 ---------- 

830 n : int 

831 The returned indices will be valid to access arrays of shape (n, n). 

832 mask_func : callable 

833 A function whose call signature is similar to that of `triu`, `tril`. 

834 That is, ``mask_func(x, k)`` returns a boolean array, shaped like `x`. 

835 `k` is an optional argument to the function. 

836 k : scalar 

837 An optional argument which is passed through to `mask_func`. Functions 

838 like `triu`, `tril` take a second argument that is interpreted as an 

839 offset. 

840 

841 Returns 

842 ------- 

843 indices : tuple of arrays. 

844 The `n` arrays of indices corresponding to the locations where 

845 ``mask_func(np.ones((n, n)), k)`` is True. 

846 

847 See Also 

848 -------- 

849 triu, tril, triu_indices, tril_indices 

850 

851 Notes 

852 ----- 

853 .. versionadded:: 1.4.0 

854 

855 Examples 

856 -------- 

857 These are the indices that would allow you to access the upper triangular 

858 part of any 3x3 array: 

859 

860 >>> iu = np.mask_indices(3, np.triu) 

861 

862 For example, if `a` is a 3x3 array: 

863 

864 >>> a = np.arange(9).reshape(3, 3) 

865 >>> a 

866 array([[0, 1, 2], 

867 [3, 4, 5], 

868 [6, 7, 8]]) 

869 >>> a[iu] 

870 array([0, 1, 2, 4, 5, 8]) 

871 

872 An offset can be passed also to the masking function. This gets us the 

873 indices starting on the first diagonal right of the main one: 

874 

875 >>> iu1 = np.mask_indices(3, np.triu, 1) 

876 

877 with which we now extract only three elements: 

878 

879 >>> a[iu1] 

880 array([1, 2, 5]) 

881 

882 """ 

883 m = ones((n, n), int) 

884 a = mask_func(m, k) 

885 return nonzero(a != 0) 

886 

887 

888@set_module('numpy') 

889def tril_indices(n, k=0, m=None): 

890 """ 

891 Return the indices for the lower-triangle of an (n, m) array. 

892 

893 Parameters 

894 ---------- 

895 n : int 

896 The row dimension of the arrays for which the returned 

897 indices will be valid. 

898 k : int, optional 

899 Diagonal offset (see `tril` for details). 

900 m : int, optional 

901 .. versionadded:: 1.9.0 

902 

903 The column dimension of the arrays for which the returned 

904 arrays will be valid. 

905 By default `m` is taken equal to `n`. 

906 

907 

908 Returns 

909 ------- 

910 inds : tuple of arrays 

911 The indices for the triangle. The returned tuple contains two arrays, 

912 each with the indices along one dimension of the array. 

913 

914 See also 

915 -------- 

916 triu_indices : similar function, for upper-triangular. 

917 mask_indices : generic function accepting an arbitrary mask function. 

918 tril, triu 

919 

920 Notes 

921 ----- 

922 .. versionadded:: 1.4.0 

923 

924 Examples 

925 -------- 

926 Compute two different sets of indices to access 4x4 arrays, one for the 

927 lower triangular part starting at the main diagonal, and one starting two 

928 diagonals further right: 

929 

930 >>> il1 = np.tril_indices(4) 

931 >>> il2 = np.tril_indices(4, 2) 

932 

933 Here is how they can be used with a sample array: 

934 

935 >>> a = np.arange(16).reshape(4, 4) 

936 >>> a 

937 array([[ 0, 1, 2, 3], 

938 [ 4, 5, 6, 7], 

939 [ 8, 9, 10, 11], 

940 [12, 13, 14, 15]]) 

941 

942 Both for indexing: 

943 

944 >>> a[il1] 

945 array([ 0, 4, 5, ..., 13, 14, 15]) 

946 

947 And for assigning values: 

948 

949 >>> a[il1] = -1 

950 >>> a 

951 array([[-1, 1, 2, 3], 

952 [-1, -1, 6, 7], 

953 [-1, -1, -1, 11], 

954 [-1, -1, -1, -1]]) 

955 

956 These cover almost the whole array (two diagonals right of the main one): 

957 

958 >>> a[il2] = -10 

959 >>> a 

960 array([[-10, -10, -10, 3], 

961 [-10, -10, -10, -10], 

962 [-10, -10, -10, -10], 

963 [-10, -10, -10, -10]]) 

964 

965 """ 

966 tri_ = tri(n, m, k=k, dtype=bool) 

967 

968 return tuple(broadcast_to(inds, tri_.shape)[tri_] 

969 for inds in indices(tri_.shape, sparse=True)) 

970 

971 

972def _trilu_indices_form_dispatcher(arr, k=None): 

973 return (arr,) 

974 

975 

976@array_function_dispatch(_trilu_indices_form_dispatcher) 

977def tril_indices_from(arr, k=0): 

978 """ 

979 Return the indices for the lower-triangle of arr. 

980 

981 See `tril_indices` for full details. 

982 

983 Parameters 

984 ---------- 

985 arr : array_like 

986 The indices will be valid for square arrays whose dimensions are 

987 the same as arr. 

988 k : int, optional 

989 Diagonal offset (see `tril` for details). 

990 

991 Examples 

992 -------- 

993 

994 Create a 4 by 4 array. 

995 

996 >>> a = np.arange(16).reshape(4, 4) 

997 >>> a 

998 array([[ 0, 1, 2, 3], 

999 [ 4, 5, 6, 7], 

1000 [ 8, 9, 10, 11], 

1001 [12, 13, 14, 15]]) 

1002 

1003 Pass the array to get the indices of the lower triangular elements. 

1004 

1005 >>> trili = np.tril_indices_from(a) 

1006 >>> trili 

1007 (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]), array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3])) 

1008 

1009 >>> a[trili] 

1010 array([ 0, 4, 5, 8, 9, 10, 12, 13, 14, 15]) 

1011 

1012 This is syntactic sugar for tril_indices(). 

1013 

1014 >>> np.tril_indices(a.shape[0]) 

1015 (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]), array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3])) 

1016 

1017 Use the `k` parameter to return the indices for the lower triangular array 

1018 up to the k-th diagonal. 

1019 

1020 >>> trili1 = np.tril_indices_from(a, k=1) 

1021 >>> a[trili1] 

1022 array([ 0, 1, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15]) 

1023 

1024 See Also 

1025 -------- 

1026 tril_indices, tril, triu_indices_from 

1027 

1028 Notes 

1029 ----- 

1030 .. versionadded:: 1.4.0 

1031 

1032 """ 

1033 if arr.ndim != 2: 

1034 raise ValueError("input array must be 2-d") 

1035 return tril_indices(arr.shape[-2], k=k, m=arr.shape[-1]) 

1036 

1037 

1038@set_module('numpy') 

1039def triu_indices(n, k=0, m=None): 

1040 """ 

1041 Return the indices for the upper-triangle of an (n, m) array. 

1042 

1043 Parameters 

1044 ---------- 

1045 n : int 

1046 The size of the arrays for which the returned indices will 

1047 be valid. 

1048 k : int, optional 

1049 Diagonal offset (see `triu` for details). 

1050 m : int, optional 

1051 .. versionadded:: 1.9.0 

1052 

1053 The column dimension of the arrays for which the returned 

1054 arrays will be valid. 

1055 By default `m` is taken equal to `n`. 

1056 

1057 

1058 Returns 

1059 ------- 

1060 inds : tuple, shape(2) of ndarrays, shape(`n`) 

1061 The indices for the triangle. The returned tuple contains two arrays, 

1062 each with the indices along one dimension of the array. Can be used 

1063 to slice a ndarray of shape(`n`, `n`). 

1064 

1065 See also 

1066 -------- 

1067 tril_indices : similar function, for lower-triangular. 

1068 mask_indices : generic function accepting an arbitrary mask function. 

1069 triu, tril 

1070 

1071 Notes 

1072 ----- 

1073 .. versionadded:: 1.4.0 

1074 

1075 Examples 

1076 -------- 

1077 Compute two different sets of indices to access 4x4 arrays, one for the 

1078 upper triangular part starting at the main diagonal, and one starting two 

1079 diagonals further right: 

1080 

1081 >>> iu1 = np.triu_indices(4) 

1082 >>> iu2 = np.triu_indices(4, 2) 

1083 

1084 Here is how they can be used with a sample array: 

1085 

1086 >>> a = np.arange(16).reshape(4, 4) 

1087 >>> a 

1088 array([[ 0, 1, 2, 3], 

1089 [ 4, 5, 6, 7], 

1090 [ 8, 9, 10, 11], 

1091 [12, 13, 14, 15]]) 

1092 

1093 Both for indexing: 

1094 

1095 >>> a[iu1] 

1096 array([ 0, 1, 2, ..., 10, 11, 15]) 

1097 

1098 And for assigning values: 

1099 

1100 >>> a[iu1] = -1 

1101 >>> a 

1102 array([[-1, -1, -1, -1], 

1103 [ 4, -1, -1, -1], 

1104 [ 8, 9, -1, -1], 

1105 [12, 13, 14, -1]]) 

1106 

1107 These cover only a small part of the whole array (two diagonals right 

1108 of the main one): 

1109 

1110 >>> a[iu2] = -10 

1111 >>> a 

1112 array([[ -1, -1, -10, -10], 

1113 [ 4, -1, -1, -10], 

1114 [ 8, 9, -1, -1], 

1115 [ 12, 13, 14, -1]]) 

1116 

1117 """ 

1118 tri_ = ~tri(n, m, k=k - 1, dtype=bool) 

1119 

1120 return tuple(broadcast_to(inds, tri_.shape)[tri_] 

1121 for inds in indices(tri_.shape, sparse=True)) 

1122 

1123 

1124@array_function_dispatch(_trilu_indices_form_dispatcher) 

1125def triu_indices_from(arr, k=0): 

1126 """ 

1127 Return the indices for the upper-triangle of arr. 

1128 

1129 See `triu_indices` for full details. 

1130 

1131 Parameters 

1132 ---------- 

1133 arr : ndarray, shape(N, N) 

1134 The indices will be valid for square arrays. 

1135 k : int, optional 

1136 Diagonal offset (see `triu` for details). 

1137