ENH: Implement sliding window

[zklaus]

This is an updated version of #10771. It implements the sliding window function discussed in #7753 according to the slightly changed API as suggested by @eric-wieser in #10771 (comment).

The case for a sliding window function

A sliding window function is a longstanding open demand. Issue #7753 has been open since 2016 and the discussion about this feature has come up several times since then. Additionally, several downstream libraries, such as dask, scikit-image, pandas, etc. need this functionality; some of them already have their own version, see eg skimage.utils.view_as_windows() and skimage.utils.view_as_blocks(). However, due to the general nature of this functionality it is believed to have a place in numpy itself.

The one counter-argument to the inclusion into numpy that has been made is that in many cases where this function could be used, more efficient algorithms are available (see e.g. #7753 (comment), #7753 (comment)). Nevertheless, the consensus reached in #7753 seems to be that, while often more efficient algorithms would be available, people rarely implement these problem-specific optimizations, but rather opt for a simpler approach, either based on explicit loops or on one of several sliding window implementations that are "in the wild" (see e.g. https://gist.github.com/teoliphant/96eb779a16bd038e374f2703da62f06d). In both of these cases having a well-documented, standardized function in numpy will enhance readability, reduce code duplication, and potentially improve performance.

In summary, a sliding window function is a worthwhile addition to numpy and will close a longstanding open issue.

The specific API

The API as proposed in this PR is the result of a discussion in the ancestral PR #10771. It is similar to the one used in skimage, but adds the axis keyword to allow flexible windows over any combination of axes, including repeated axes. Several use-cases are demonstrated here; a possible implementation of the skimage functions based on this API is given here.

Closes #7753.

[eric-wieser]

Thanks for picking this back up.

Would you be able to add some tests for the error cases? In case you're not familiar with pytest, you can do that with

with pytest.raises(ValueError, match="cannot be larger"):
    sliding_window_view(...)

[BvB93]

The module-level __all__ should probably be updated as well.

[BvB93]

I assume this will need a release note?
Instructions and a few release note examples are contained within doc/release/upcoming_changes.

[BvB93]

There are currently a few CI errors caused by the doctests,
the latter throwing a NameError when encountering sliding_window_view.

Replacing all references to sliding_window_view with np.sliding_window_view in the code blocks should fix the issue.

File "build/testenv/lib/python3.6/site-packages/numpy/__init__.py", line 95, in sliding_window_view
Failed example:
    sliding_window_view(x, (2, 3), (1, 1))
Exception raised:
    Traceback (most recent call last):
      File "/Users/runner/hostedtoolcache/Python/3.6.12/x64/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest sliding_window_view[8]>", line 1, in <module>
        sliding_window_view(x, (2, 3), (1, 1))
    NameError: name 'sliding_window_view' is not defined

[zklaus]

SEGFAULT in test_umath? That doesn't feel like it comes from this PR, right?

[BvB93]

SEGFAULT in test_umath? That doesn't feel like it comes from this PR, right?

Let's assume for know that this is a fluke; restarting the test will probably fix it.

More importantly, there is still a doctest-related error:

numpy.lib.sliding_window_view
-----------------------------

File "build/testenv/lib/python3.6/site-packages/numpy/__init__.py", line 115, in sliding_window_view
Failed example:
    np.sliding_window_view(x, 5)[::2, :]
Expected:
    array([[0, 1, 2],
           [2, 3, 4],
           [4, 5, 6]])
Got:
    array([[0, 1, 2, 3, 4],
           [2, 3, 4, 5, 6]])


ERROR:  failed checking numpy.lib

[zklaus]

While trying to improve the documentation for the return value, I decided to change the name of the shape argument to window_shape. Is that a good idea? Do you oppose it?

[charris]

Close/reopen

[zklaus]

Addressed the last comment on subok test, rebased on current master, made sure all checks pass. The previous travis ci problem was most likely due to the move to travis-ci.com, now everything seems ok.

@seberg, good to go?

[zklaus]

@seberg, @shoyer, @eric-wieser, is there anything left for me to do here? How can we move forward?

[seberg]

Thanks @zklaus, I am sure we can always find some nitpicks, but it seems all good to me. If there are any followups we can open a new PR. Thanks everyone who reviewed this!

[shoyer]

Thank you @zklaus!

[zklaus]

Cheers guys! Nice working with you 😃