Make axis keyword to squeeze() positional

[rgommers]

As suggested by @shoyer in #97 (comment). This makes it possible to predict resulting rank of output array, which is otherwise undetermined (see discussion in gh-97).

Using squeeze without specifying the axis in library code often results in unintuitive behaviour. For the common use case of turning a size-1 2-D array into a 0-D, this gets a little more verbose (e.g. np.squeeze(np.array([[1]]), axis=(0, 1))), but that's probably a price worth paying for the extra clarity.

Also changes specified behaviour for a given axis not having size 1 to raising a ValueError, which is what NumPy does. This wasn't considered before, and the current description seems simply incorrect.

Finally, this makes squeeze the exact inverse of expand_dims, which is probably a good thing.

The caveats:

• This deviates from what libraries currently do
• Most existing uses of squeeze (e.g. in SciPy) do not use the axis keyword. The counter-argument for that is that many of those instances are hard to understand and have no comment for why squeeze is used.

[kgryte]

@rgommers I believe the "unchanged behavior" stems from Torch, as documented here. I missed that NumPy raised a ValueError. This should probably be discussed.

[shoyer]

Looks great to me, thanks!

[rgommers]

@rgommers I believe the "unchanged behavior" stems from Torch, as documented here. I missed that NumPy raised a ValueError. This should probably be discussed.

I did a bit of searching, NumPy has done this for a very long time, the axis keyword was added 10 years ago in numpy/numpy@a112fc4, and it behaved like this already. It's a separate function in C, PyArray_SqueezeSelected. Also note that that was in the pre-GitHub days, so there may not have been a thorough discussion on raising yes or no.

The PyTorch docs have a warning: "If the tensor has a batch dimension of size 1, then squeeze(input) will also remove the batch dimension, which can lead to unexpected errors."

So there's two things to decide:

1. Is axis=None allowed?
2. Raise or not if a specified axis is not of size 1?

The PR in its current state (which answers with "No, Raise") makes squeeze the inverse of expand_dims. Being more flexible makes it potentially more useful for end users, but is also a bit of a footgun as the pytorch docs warning shows.

There's not much data on (2) - I haven't seen any complaints from numpy users, but that's because they mostly use the default axis=None. Either way, the semantics being "inverse of expand_dims" or "clean up size-1 dimensions if they exist" are very different; likely those should have been two separate functions.

[kgryte]

Given the divergence in semantics, would it make sense to do a bit of innovating here and actually split the use cases as separate APIs?

[shoyer]

I don't think we need "clean up size-1 dimensions if they exist" in the API standard. Squeezing without an axis really only makes sense in an interactive context, but our primary audience here is library developers.

[rgommers]

I don't think we need "clean up size-1 dimensions if they exist" in the API standard. Squeezing without an axis really only makes sense in an interactive context, but our primary audience here is library developers.

I agree. Although the proof will be in the pudding. There's quite a bit of squeeze() usage floating around in the likes of SciPy. A lot of that will be design mistakes, so not supporting it may flush out if there's an actual need.

How about we merge this as is, and then see how it works in practice? We can always add something later, but once we put a function in we can't remove it anymore.

[shoyer]

I agree. Although the proof will be in the pudding. There's quite a bit of squeeze() usage floating around in the likes of SciPy. A lot of that will be design mistakes, so not supporting it may flush out if there's an actual need.

Agreed about both!

How about we merge this as is, and then see how it works in practice? We can always add something later, but once we put a function in we can't remove it anymore.

Sounds good to me.

To be honest, it is somewhat questionable whether we need squeeze() in either form. The canonical implementation of either version is ~5 lines of code. The most annoying part is probably formatting the error message :)

[rgommers]

To be honest, it is somewhat questionable whether we need squeeze() in either form.

Agreed, I'd say it's borderline. The symmetry with expand_dims and it being already commonly implemented are probably the main argument for leaving it in.

Okay, this has been open for a long time, let's push the button on it:)