Make region a keyword argument for dimension reducing methods

[ararslan]

If possible, I think we should make the region argument in the dimension reduction methods of any and all a keyword argument. map has an incredibly handy method for multiple iterators, e.g. map(<, a, b). Currently any(<, a, b) will use the method any(f, itr, region), but it would be great to be able to reclaim any(<, a, b) to do what it looks like it should do. That would require making region a keyword argument in 0.7 with a deprecation, and introducing the new method in 1.0.

The downside to this is that we have to come up with a default value for region in order to use it as a keyword argument, and when region isn't specified then we want it to dispatch to the simpler, short-circuiting method not based on mapreducedim.

A similar argument could be made for other functions with mapreducedim-based methods, such as sum(f, A, region), but I mostly care about any/all for now. We're doin' 'em all.

[nalimilan]

We could use region=nothing as a default.

I'm fine with doing this, but then let's use keyword arguments for all similar functions (sum, etc.). Are we also sure region is the best term? It could also be e.g. dim/dims?

[JeffBezanson]

Are we also sure region is the best term? It could also be e.g. dim/dims?

💯 "Region" to me means something like A[m:n, m:n]. dims would be fine. We should try to standardize on dims for "which dimensions" and size or sizes for "the sizes of dimensions".

[JeffBezanson]

Triage says 👍 . Should be applied to all relevant functions though. Issue of what name to use still somewhat up in the air.

[ararslan]

The steps are:

1. Figure out which functions have this kind of API
2. Pick a name for the keyword argument
3. Apply the change to all of them, not just any and all

[malmaud]

TensorFlow uses axis, as another name candidate.

[ararslan]

Methods which perform dimension reduction using this kind of API:

• mapreducedim(f, op, A, region, v0)
• reducedim(op, A, region, v0)
• sum(A, dims) / sum(f, A, region)
• prod(A, dims) / prod(f, A, region)
• maximum(A, dims) / maximum(f, A, region)
• minimum(A, dims) / minimum(f, A, region)
• all(A, dims) / all(f, A, region)
• any(A, dims) / any(f, A, region)

Interestingly, we seem to opt for the "region" terminology only for methods which map prior to reduction, and for those that don't we use "dims." (reducedim is the exception here; it uses "region" and does not map.)

To me, "dims" seems like the most obvious and immediately descriptive term, and it's consistent both with the names of the functions used underneath, i.e. (map)reducedim, as well as with our Dims type alias. With that in mind, here is what I would propose: for each reducing function r in the above list, deprecate the methods to r(A; dims=Colon()) and r(f, A; dims=Colon()). Using : seems like the most natural way to request the current behavior when no dimension is specified, in my opinion.

I'm indifferent as to whether (map)reducedim should be folded into (map)reduce with dims and v0 as keyword arguments, but that would seem reasonable to me.

[nalimilan]

FWIW, Numpy also uses axis (see e.g. here). So if we decide to keep the axes function, we could as well adopt the axis terminology everywhere.

(Though I also like dims.)

[StefanKarpinski]

On the one hand, we now use axes to get a description of the axes/dimensions of an array, which suggests axis. On the other hand, we still have the following dim names:

• flipdim
• ndims
• permutedims
• permutedims!
• reducedim
• slicedim
• mapreducedim

So we're a bit internally split on this terminology. Are these reduction region arguments more similar to what axes tells you about or what ndims, etc. tells you about?

[JeffBezanson]

Given what axes does, for us an "axis" is something like -10:10, telling you that the index values for a dimension (see what I did there) range from -10 to 10. So I think dims is a good choice.