Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/numpy/lib/_stride_tricks

1"""

2Utilities that manipulate strides to achieve desirable effects.

4An explanation of strides can be found in the :ref:`arrays.ndarray`.

6Functions

7---------

9.. autosummary::

10 :toctree: generated/

12"""

13import numpy as np

14from numpy._core.numeric import normalize_axis_tuple

15from numpy._core.overrides import array_function_dispatch, set_module

17__all__ = ['broadcast_to', 'broadcast_arrays', 'broadcast_shapes']

20class DummyArray:

21 """Dummy object that just exists to hang __array_interface__ dictionaries

22 and possibly keep alive a reference to a base array.

23 """

25 def __init__(self, interface, base=None):

26 self.__array_interface__ = interface

27 self.base = base

30def _maybe_view_as_subclass(original_array, new_array):

31 if type(original_array) is not type(new_array):

32 # if input was an ndarray subclass and subclasses were OK,

33 # then view the result as that subclass.

34 new_array = new_array.view(type=type(original_array))

35 # Since we have done something akin to a view from original_array, we

36 # should let the subclass finalize (if it has it implemented, i.e., is

37 # not None).

38 if new_array.__array_finalize__:

39 new_array.__array_finalize__(original_array)

40 return new_array

43@set_module("numpy.lib.stride_tricks")

44def as_strided(x, shape=None, strides=None, subok=False, writeable=True):

45 """

46 Create a view into the array with the given shape and strides.

48 .. warning:: This function has to be used with extreme care, see notes.

50 Parameters

51 ----------

52 x : ndarray

53 Array to create a new.

54 shape : sequence of int, optional

55 The shape of the new array. Defaults to ``x.shape``.

56 strides : sequence of int, optional

57 The strides of the new array. Defaults to ``x.strides``.

58 subok : bool, optional

59 .. versionadded:: 1.10

61 If True, subclasses are preserved.

62 writeable : bool, optional

63 .. versionadded:: 1.12

65 If set to False, the returned array will always be readonly.

66 Otherwise it will be writable if the original array was. It

67 is advisable to set this to False if possible (see Notes).

69 Returns

70 -------

71 view : ndarray

73 See also

74 --------

75 broadcast_to : broadcast an array to a given shape.

76 reshape : reshape an array.

77 lib.stride_tricks.sliding_window_view :

78 userfriendly and safe function for a creation of sliding window views.

80 Notes

81 -----

82 ``as_strided`` creates a view into the array given the exact strides

83 and shape. This means it manipulates the internal data structure of

84 ndarray and, if done incorrectly, the array elements can point to

85 invalid memory and can corrupt results or crash your program.

86 It is advisable to always use the original ``x.strides`` when

87 calculating new strides to avoid reliance on a contiguous memory

88 layout.

90 Furthermore, arrays created with this function often contain self

91 overlapping memory, so that two elements are identical.

92 Vectorized write operations on such arrays will typically be

93 unpredictable. They may even give different results for small, large,

94 or transposed arrays.

96 Since writing to these arrays has to be tested and done with great

97 care, you may want to use ``writeable=False`` to avoid accidental write

98 operations.

100 For these reasons it is advisable to avoid ``as_strided`` when

101 possible.

102 """

103 # first convert input to array, possibly keeping subclass

104 x = np.array(x, copy=None, subok=subok)

105 interface = dict(x.__array_interface__)

106 if shape is not None:

107 interface['shape'] = tuple(shape)

108 if strides is not None:

109 interface['strides'] = tuple(strides)

110

111 array = np.asarray(DummyArray(interface, base=x))

112 # The route via `__interface__` does not preserve structured

113 # dtypes. Since dtype should remain unchanged, we set it explicitly.

114 array.dtype = x.dtype

115

116 view = _maybe_view_as_subclass(x, array)

117

118 if view.flags.writeable and not writeable:

119 view.flags.writeable = False

120

121 return view

122

123

124def _sliding_window_view_dispatcher(x, window_shape, axis=None, *,

125 subok=None, writeable=None):

126 return (x,)

127

128

129@array_function_dispatch(

130 _sliding_window_view_dispatcher, module="numpy.lib.stride_tricks"

131)

132def sliding_window_view(x, window_shape, axis=None, *,

133 subok=False, writeable=False):

134 """

135 Create a sliding window view into the array with the given window shape.

136

137 Also known as rolling or moving window, the window slides across all

138 dimensions of the array and extracts subsets of the array at all window

139 positions.

140

141 .. versionadded:: 1.20.0

142

143 Parameters

144 ----------

145 x : array_like

146 Array to create the sliding window view from.

147 window_shape : int or tuple of int

148 Size of window over each axis that takes part in the sliding window.

149 If `axis` is not present, must have same length as the number of input

150 array dimensions. Single integers `i` are treated as if they were the

151 tuple `(i,)`.

152 axis : int or tuple of int, optional

153 Axis or axes along which the sliding window is applied.

154 By default, the sliding window is applied to all axes and

155 `window_shape[i]` will refer to axis `i` of `x`.

156 If `axis` is given as a `tuple of int`, `window_shape[i]` will refer to

157 the axis `axis[i]` of `x`.

158 Single integers `i` are treated as if they were the tuple `(i,)`.

159 subok : bool, optional

160 If True, sub-classes will be passed-through, otherwise the returned

161 array will be forced to be a base-class array (default).

162 writeable : bool, optional

163 When true, allow writing to the returned view. The default is false,

164 as this should be used with caution: the returned view contains the

165 same memory location multiple times, so writing to one location will

166 cause others to change.

167

168 Returns

169 -------

170 view : ndarray

171 Sliding window view of the array. The sliding window dimensions are

172 inserted at the end, and the original dimensions are trimmed as

173 required by the size of the sliding window.

174 That is, ``view.shape = x_shape_trimmed + window_shape``, where

175 ``x_shape_trimmed`` is ``x.shape`` with every entry reduced by one less

176 than the corresponding window size.

177

178 See Also

179 --------

180 lib.stride_tricks.as_strided: A lower-level and less safe routine for

181 creating arbitrary views from custom shape and strides.

182 broadcast_to: broadcast an array to a given shape.

183

184 Notes

185 -----

186 For many applications using a sliding window view can be convenient, but

187 potentially very slow. Often specialized solutions exist, for example:

188

189 - `scipy.signal.fftconvolve`

190

191 - filtering functions in `scipy.ndimage`

192

193 - moving window functions provided by

194 `bottleneck <https://github.com/pydata/bottleneck>`_.

195

196 As a rough estimate, a sliding window approach with an input size of `N`

197 and a window size of `W` will scale as `O(N*W)` where frequently a special

198 algorithm can achieve `O(N)`. That means that the sliding window variant

199 for a window size of 100 can be a 100 times slower than a more specialized

200 version.

201

202 Nevertheless, for small window sizes, when no custom algorithm exists, or

203 as a prototyping and developing tool, this function can be a good solution.

204

205 Examples

206 --------

207 >>> from numpy.lib.stride_tricks import sliding_window_view

208 >>> x = np.arange(6)

209 >>> x.shape

210 (6,)

211 >>> v = sliding_window_view(x, 3)

212 >>> v.shape

213 (4, 3)

214 >>> v

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

216 [1, 2, 3],

217 [2, 3, 4],

218 [3, 4, 5]])

219

220 This also works in more dimensions, e.g.

221

222 >>> i, j = np.ogrid[:3, :4]

223 >>> x = 10*i + j

224 >>> x.shape

225 (3, 4)

226 >>> x

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

228 [10, 11, 12, 13],

229 [20, 21, 22, 23]])

230 >>> shape = (2,2)

231 >>> v = sliding_window_view(x, shape)

232 >>> v.shape

233 (2, 3, 2, 2)

234 >>> v

235 array([[[[ 0, 1],

236 [10, 11]],

237 [[ 1, 2],

238 [11, 12]],

239 [[ 2, 3],

240 [12, 13]]],

241 [[[10, 11],

242 [20, 21]],

243 [[11, 12],

244 [21, 22]],

245 [[12, 13],

246 [22, 23]]]])

247

248 The axis can be specified explicitly:

249

250 >>> v = sliding_window_view(x, 3, 0)

251 >>> v.shape

252 (1, 4, 3)

253 >>> v

254 array([[[ 0, 10, 20],

255 [ 1, 11, 21],

256 [ 2, 12, 22],

257 [ 3, 13, 23]]])

258

259 The same axis can be used several times. In that case, every use reduces

260 the corresponding original dimension:

261

262 >>> v = sliding_window_view(x, (2, 3), (1, 1))

263 >>> v.shape

264 (3, 1, 2, 3)

265 >>> v

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

267 [ 1, 2, 3]]],

268 [[[10, 11, 12],

269 [11, 12, 13]]],

270 [[[20, 21, 22],

271 [21, 22, 23]]]])

272

273 Combining with stepped slicing (`::step`), this can be used to take sliding

274 views which skip elements:

275

276 >>> x = np.arange(7)

277 >>> sliding_window_view(x, 5)[:, ::2]

278 array([[0, 2, 4],

279 [1, 3, 5],

280 [2, 4, 6]])

281

282 or views which move by multiple elements

283

284 >>> x = np.arange(7)

285 >>> sliding_window_view(x, 3)[::2, :]

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

287 [2, 3, 4],

288 [4, 5, 6]])

289

290 A common application of `sliding_window_view` is the calculation of running

291 statistics. The simplest example is the

292 `moving average <https://en.wikipedia.org/wiki/Moving_average>`_:

293

294 >>> x = np.arange(6)

295 >>> x.shape

296 (6,)

297 >>> v = sliding_window_view(x, 3)

298 >>> v.shape

299 (4, 3)

300 >>> v

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

302 [1, 2, 3],

303 [2, 3, 4],

304 [3, 4, 5]])

305 >>> moving_average = v.mean(axis=-1)

306 >>> moving_average

307 array([1., 2., 3., 4.])

308

309 Note that a sliding window approach is often **not** optimal (see Notes).

310 """

311 window_shape = (tuple(window_shape)

312 if np.iterable(window_shape)

313 else (window_shape,))

314 # first convert input to array, possibly keeping subclass

315 x = np.array(x, copy=None, subok=subok)

316

317 window_shape_array = np.array(window_shape)

318 if np.any(window_shape_array < 0):

319 raise ValueError('`window_shape` cannot contain negative values')

320

321 if axis is None:

322 axis = tuple(range(x.ndim))

323 if len(window_shape) != len(axis):

324 raise ValueError(f'Since axis is `None`, must provide '

325 f'window_shape for all dimensions of `x`; '

326 f'got {len(window_shape)} window_shape elements '

327 f'and `x.ndim` is {x.ndim}.')

328 else:

329 axis = normalize_axis_tuple(axis, x.ndim, allow_duplicate=True)

330 if len(window_shape) != len(axis):

331 raise ValueError(f'Must provide matching length window_shape and '

332 f'axis; got {len(window_shape)} window_shape '

333 f'elements and {len(axis)} axes elements.')

334

335 out_strides = x.strides + tuple(x.strides[ax] for ax in axis)

336

337 # note: same axis can be windowed repeatedly

338 x_shape_trimmed = list(x.shape)

339 for ax, dim in zip(axis, window_shape):

340 if x_shape_trimmed[ax] < dim:

341 raise ValueError(

342 'window shape cannot be larger than input array shape')

343 x_shape_trimmed[ax] -= dim - 1

344 out_shape = tuple(x_shape_trimmed) + window_shape

345 return as_strided(x, strides=out_strides, shape=out_shape,

346 subok=subok, writeable=writeable)

347

348

349def _broadcast_to(array, shape, subok, readonly):

350 shape = tuple(shape) if np.iterable(shape) else (shape,)

351 array = np.array(array, copy=None, subok=subok)

352 if not shape and array.shape:

353 raise ValueError('cannot broadcast a non-scalar to a scalar array')

354 if any(size < 0 for size in shape):

355 raise ValueError('all elements of broadcast shape must be non-'

356 'negative')

357 extras = []

358 it = np.nditer(

359 (array,), flags=['multi_index', 'refs_ok', 'zerosize_ok'] + extras,

360 op_flags=['readonly'], itershape=shape, order='C')

361 with it:

362 # never really has writebackifcopy semantics

363 broadcast = it.itviews[0]

364 result = _maybe_view_as_subclass(array, broadcast)

365 # In a future version this will go away

366 if not readonly and array.flags._writeable_no_warn:

367 result.flags.writeable = True

368 result.flags._warn_on_write = True

369 return result

370

371

372def _broadcast_to_dispatcher(array, shape, subok=None):

373 return (array,)

374

375

376@array_function_dispatch(_broadcast_to_dispatcher, module='numpy')

377def broadcast_to(array, shape, subok=False):

378 """Broadcast an array to a new shape.

379

380 Parameters

381 ----------

382 array : array_like

383 The array to broadcast.

384 shape : tuple or int

385 The shape of the desired array. A single integer ``i`` is interpreted

386 as ``(i,)``.

387 subok : bool, optional

388 If True, then sub-classes will be passed-through, otherwise

389 the returned array will be forced to be a base-class array (default).

390

391 Returns

392 -------

393 broadcast : array

394 A readonly view on the original array with the given shape. It is

395 typically not contiguous. Furthermore, more than one element of a

396 broadcasted array may refer to a single memory location.

397

398 Raises

399 ------

400 ValueError

401 If the array is not compatible with the new shape according to NumPy's

402 broadcasting rules.

403

404 See Also

405 --------

406 broadcast

407 broadcast_arrays

408 broadcast_shapes

409

410 Notes

411 -----

412 .. versionadded:: 1.10.0

413

414 Examples

415 --------

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

417 >>> np.broadcast_to(x, (3, 3))

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

419 [1, 2, 3],

420 [1, 2, 3]])

421 """

422 return _broadcast_to(array, shape, subok=subok, readonly=True)

423

424

425def _broadcast_shape(*args):

426 """Returns the shape of the arrays that would result from broadcasting the

427 supplied arrays against each other.

428 """

429 # use the old-iterator because np.nditer does not handle size 0 arrays

430 # consistently

431 b = np.broadcast(*args[:32])

432 # unfortunately, it cannot handle 32 or more arguments directly

433 for pos in range(32, len(args), 31):

434 # ironically, np.broadcast does not properly handle np.broadcast

435 # objects (it treats them as scalars)

436 # use broadcasting to avoid allocating the full array

437 b = broadcast_to(0, b.shape)

438 b = np.broadcast(b, *args[pos:(pos + 31)])

439 return b.shape

440

441

442@set_module('numpy')

443def broadcast_shapes(*args):

444 """

445 Broadcast the input shapes into a single shape.

446

447 :ref:`Learn more about broadcasting here <basics.broadcasting>`.

448

449 .. versionadded:: 1.20.0

450

451 Parameters

452 ----------

453 *args : tuples of ints, or ints

454 The shapes to be broadcast against each other.

455

456 Returns

457 -------

458 tuple

459 Broadcasted shape.

460

461 Raises

462 ------

463 ValueError

464 If the shapes are not compatible and cannot be broadcast according

465 to NumPy's broadcasting rules.

466

467 See Also

468 --------

469 broadcast

470 broadcast_arrays

471 broadcast_to

472

473 Examples

474 --------

475 >>> np.broadcast_shapes((1, 2), (3, 1), (3, 2))

476 (3, 2)

477

478 >>> np.broadcast_shapes((6, 7), (5, 6, 1), (7,), (5, 1, 7))

479 (5, 6, 7)

480 """

481 arrays = [np.empty(x, dtype=[]) for x in args]

482 return _broadcast_shape(*arrays)

483

484

485def _broadcast_arrays_dispatcher(*args, subok=None):

486 return args

487

488

489@array_function_dispatch(_broadcast_arrays_dispatcher, module='numpy')

490def broadcast_arrays(*args, subok=False):

491 """

492 Broadcast any number of arrays against each other.

493

494 Parameters

495 ----------

496 *args : array_likes

497 The arrays to broadcast.

498

499 subok : bool, optional

500 If True, then sub-classes will be passed-through, otherwise

501 the returned arrays will be forced to be a base-class array (default).

502

503 Returns

504 -------

505 broadcasted : tuple of arrays

506 These arrays are views on the original arrays. They are typically

507 not contiguous. Furthermore, more than one element of a

508 broadcasted array may refer to a single memory location. If you need

509 to write to the arrays, make copies first. While you can set the

510 ``writable`` flag True, writing to a single output value may end up

511 changing more than one location in the output array.

512

513 .. deprecated:: 1.17

514 The output is currently marked so that if written to, a deprecation

515 warning will be emitted. A future version will set the

516 ``writable`` flag False so writing to it will raise an error.

517

518 See Also

519 --------

520 broadcast

521 broadcast_to

522 broadcast_shapes

523

524 Examples

525 --------

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

527 >>> y = np.array([[4],[5]])

528 >>> np.broadcast_arrays(x, y)

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

530 [1, 2, 3]]),

531 array([[4, 4, 4],

532 [5, 5, 5]]))

533

534 Here is a useful idiom for getting contiguous copies instead of

535 non-contiguous views.

536

537 >>> [np.array(a) for a in np.broadcast_arrays(x, y)]

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

539 [1, 2, 3]]),

540 array([[4, 4, 4],

541 [5, 5, 5]])]

542

543 """

544 # nditer is not used here to avoid the limit of 32 arrays.

545 # Otherwise, something like the following one-liner would suffice:

546 # return np.nditer(args, flags=['multi_index', 'zerosize_ok'],

547 # order='C').itviews

548

549 args = tuple(np.array(_m, copy=None, subok=subok) for _m in args)

550

551 shape = _broadcast_shape(*args)

552

553 if all(array.shape == shape for array in args):

554 # Common case where nothing needs to be broadcasted.

555 return args

556

557 return tuple(_broadcast_to(array, shape, subok=subok, readonly=False)

558 for array in args)

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

92 statements