Broadcast `x` to an array with the shape (`ndim`, 2). A helper function for `pad` that prepares and validates arguments like `pad_width` for iteration in pairs. Parameters ---------- x : {None, scalar, array-like} The object to broadcast to the shape (`ndim`, 2).
(x, ndim, as_index=False)
| 469 | |
| 470 | |
| 471 | def _as_pairs(x, ndim, as_index=False): |
| 472 | """ |
| 473 | Broadcast `x` to an array with the shape (`ndim`, 2). |
| 474 | |
| 475 | A helper function for `pad` that prepares and validates arguments like |
| 476 | `pad_width` for iteration in pairs. |
| 477 | |
| 478 | Parameters |
| 479 | ---------- |
| 480 | x : {None, scalar, array-like} |
| 481 | The object to broadcast to the shape (`ndim`, 2). |
| 482 | ndim : int |
| 483 | Number of pairs the broadcasted `x` will have. |
| 484 | as_index : bool, optional |
| 485 | If `x` is not None, try to round each element of `x` to an integer |
| 486 | (dtype `np.intp`) and ensure every element is positive. |
| 487 | |
| 488 | Returns |
| 489 | ------- |
| 490 | pairs : nested iterables, shape (`ndim`, 2) |
| 491 | The broadcasted version of `x`. |
| 492 | |
| 493 | Raises |
| 494 | ------ |
| 495 | ValueError |
| 496 | If `as_index` is True and `x` contains negative elements. |
| 497 | Or if `x` is not broadcastable to the shape (`ndim`, 2). |
| 498 | """ |
| 499 | if x is None: |
| 500 | # Pass through None as a special case, otherwise np.round(x) fails |
| 501 | # with an AttributeError |
| 502 | return ((None, None),) * ndim |
| 503 | |
| 504 | x = np.array(x) |
| 505 | if as_index: |
| 506 | x = np.round(x).astype(np.intp, copy=False) |
| 507 | |
| 508 | if x.ndim < 3: |
| 509 | # Optimization: Possibly use faster paths for cases where `x` has |
| 510 | # only 1 or 2 elements. `np.broadcast_to` could handle these as well |
| 511 | # but is currently slower |
| 512 | |
| 513 | if x.size == 1: |
| 514 | # x was supplied as a single value |
| 515 | x = x.ravel() # Ensure x[0] works for x.ndim == 0, 1, 2 |
| 516 | if as_index and x < 0: |
| 517 | raise ValueError("index can't contain negative values") |
| 518 | return ((x[0], x[0]),) * ndim |
| 519 | |
| 520 | if x.size == 2 and x.shape != (2, 1): |
| 521 | # x was supplied with a single value for each side |
| 522 | # but except case when each dimension has a single value |
| 523 | # which should be broadcasted to a pair, |
| 524 | # e.g. [[1], [2]] -> [[1, 1], [2, 2]] not [[1, 2], [1, 2]] |
| 525 | x = x.ravel() # Ensure x[0], x[1] works |
| 526 | if as_index and (x[0] < 0 or x[1] < 0): |
| 527 | raise ValueError("index can't contain negative values") |
| 528 | return ((x[0], x[1]),) * ndim |
searching dependent graphs…