Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Ralf Gommers]

On Fri, Feb 12, 2021 at 3:32 AM Juan Nunez-Iglesias 
wrote:

> both napari and scikit-image use atleast_ a few times. I don’t have many
> examples of where I used nd because it didn’t exist. But I have the very
> distinct impression of needing it repeatedly. In some places, I’ve used
> `np.broadcast_to` to signal the same intention, where `atleast_nd` would
> have been the more readable solution.
>
> I don’t buy the argument that it’s just a way to mask errors. NumPy
> broadcasting also has that same potential but I hope no one would seriously
> consider deprecating it. Indeed, even if we accept that we (library
> authors) should force users to provide an array of the right
> dimensionality, that still argues for making it convenient for users to do
> that!
>
> I don’t feel super strongly about this. But I think atleast_nd is a move
> in a positive direction and I’d prefer  it to what’s there now:
>
> In [1]: import numpy as np
> In [2]: np.atleast_3d(np.ones(4)).shape
> Out[2]: (1, 4, 1)
>
> There might be some linear algebraic reason why those axis positions make
> sense, but I’m not aware of it...
>

Yes that's pretty weird. I'm also not sure there's a reason.

It would be good that, if atleast_nd is not going to replicate this
behavior, atleast_3d was deprecated (perhaps a release or two after
introduction of atleast_nd).

Not having `atleast_3d(x) == atleast_nd(x, pos=3)` is unnecessarily
confusing.

Ralf


> Juan.
>
> On 12 Feb 2021, at 5:32 am, Eric Wieser 
> wrote:
>
> I did a quick search of matplotlib, and found a few uses of all three
> functions:
>
> *
> https://github.com/matplotlib/matplotlib/blob/fed55c63a314351cd39a12783f385009782c06e1/lib/matplotlib/_layoutgrid.py#L441-L446
>   This one isn't really numpy at all, and is really just a shorthand for
> normalizing an argument `x=n` to `x=[n, n]`
> *
> https://github.com/matplotlib/matplotlib/blob/dd249744270f6abe3f540f81b7a77c0cb728ddbb/lib/matplotlib/mlab.py#L888
>This one is the classic "either multivariate or single-variable data"
> thing endemic to the SciPy ecosystem.
> *
> https://github.com/matplotlib/matplotlib/blob/1eef019109b64ee4085732544cb5e310e69451ab/lib/matplotlib/cbook/__init__.py#L1325-L1326
>   Matplotlib has their own `_check_1d` function for input sanitization,
> although github says it's only used to parse the arguments to `plot`, which
> at this point are fairly established as being flexible.
> *
> https://github.com/matplotlib/matplotlib/blob/f72adc49092fe0233a8cd21aa0f317918dafb18d/lib/matplotlib/transforms.py#L631
>   This just looks like "defensive programming", and if the argument isn't
> already 3d then something is probably wrong.
>
> This isn't an exhaustive list, just a handful of different situations the
> functions were used.
>
> Eric
>
>
>
> On Thu, 11 Feb 2021 at 18:15, Stephan Hoyer  wrote:
>
>> On Thu, Feb 11, 2021 at 9:42 AM Benjamin Root 
>> wrote:
>>
>>> for me, I find that the at_least{1,2,3}d functions are useful for
>>> sanitizing inputs. Having an at_leastnd() function can be viewed as a step
>>> towards cleaning up the API, not cluttering it (although, deprecations of
>>> the existing functions probably should be long given how long they have
>>> existed).
>>>
>>
>> I would love to see examples of this -- perhaps in matplotlib?
>>
>> My thinking is that in most cases it's probably a better idea to keep the
>> interface simpler, and raise an error for lower-dimensional arrays.
>> Automatic conversion is convenient (and endemic within the SciPy
>> ecosystem), but is also a common source of bugs.
>>
>> On Thu, Feb 11, 2021 at 1:56 AM Stephan Hoyer  wrote:
>>>
 On Wed, Feb 10, 2021 at 9:48 PM Juan Nunez-Iglesias 
 wrote:

> I totally agree with the namespace clutter concern, but honestly, I
> would use `atleast_nd` with its `pos` argument (I might rename it to
> `position`, `axis`, or `axis_position`) any day over `at_least{1,2,3}d`,
> for which I had no idea where the new axes would end up.
>
> So, I’m in favour of including it, and optionally deprecating
> `atleast_{1,2,3}d`.
>
>
 I appreciate that `atleast_nd` feels more sensible than
 `at_least{1,2,3}d`, but I don't think "better" than a pattern we would not
 recommend is a good enough reason for inclusion in NumPy. It needs to stand
 on its own.

 What would be the recommended use-cases for this new function?
 Have any libraries building on top of NumPy implemented a version of
 this?


> Juan.
>
> On 11 Feb 2021, at 9:48 am, Sebastian Berg 
> wrote:
>
> On Wed, 2021-02-10 at 17:31 -0500, Joseph Fox-Rabinovitz wrote:
>
> I've created PR#18386 to add a function called atleast_nd to numpy and
> numpy.ma. This would generalize the existing atleast_1d, atleast_2d,
> and
> atleast_3d functions.
>
> I proposed a similar idea about four and a half years ago:
>
> https://mail.python.org/pipermail/numpy-dis

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Eric Wieser]

> There might be some linear algebraic reason why those axis positions make
sense, but I’m not aware of it...

My guess is that the historical motivation was to allow grayscale `(H, W)`
images to be converted into `(H, W, 1)` images so that they can be
broadcast against `(H, W, 3)` RGB images.

Eric

On Fri, 12 Feb 2021 at 02:32, Juan Nunez-Iglesias  wrote:

> both napari and scikit-image use atleast_ a few times. I don’t have many
> examples of where I used nd because it didn’t exist. But I have the very
> distinct impression of needing it repeatedly. In some places, I’ve used
> `np.broadcast_to` to signal the same intention, where `atleast_nd` would
> have been the more readable solution.
>
> I don’t buy the argument that it’s just a way to mask errors. NumPy
> broadcasting also has that same potential but I hope no one would seriously
> consider deprecating it. Indeed, even if we accept that we (library
> authors) should force users to provide an array of the right
> dimensionality, that still argues for making it convenient for users to do
> that!
>
> I don’t feel super strongly about this. But I think atleast_nd is a move
> in a positive direction and I’d prefer  it to what’s there now:
>
> In [1]: import numpy as np
> In [2]: np.atleast_3d(np.ones(4)).shape
> Out[2]: (1, 4, 1)
>
> There might be some linear algebraic reason why those axis positions make
> sense, but I’m not aware of it...
>
> Juan.
>
> On 12 Feb 2021, at 5:32 am, Eric Wieser 
> wrote:
>
> I did a quick search of matplotlib, and found a few uses of all three
> functions:
>
> *
> https://github.com/matplotlib/matplotlib/blob/fed55c63a314351cd39a12783f385009782c06e1/lib/matplotlib/_layoutgrid.py#L441-L446
>   This one isn't really numpy at all, and is really just a shorthand for
> normalizing an argument `x=n` to `x=[n, n]`
> *
> https://github.com/matplotlib/matplotlib/blob/dd249744270f6abe3f540f81b7a77c0cb728ddbb/lib/matplotlib/mlab.py#L888
>This one is the classic "either multivariate or single-variable data"
> thing endemic to the SciPy ecosystem.
> *
> https://github.com/matplotlib/matplotlib/blob/1eef019109b64ee4085732544cb5e310e69451ab/lib/matplotlib/cbook/__init__.py#L1325-L1326
>   Matplotlib has their own `_check_1d` function for input sanitization,
> although github says it's only used to parse the arguments to `plot`, which
> at this point are fairly established as being flexible.
> *
> https://github.com/matplotlib/matplotlib/blob/f72adc49092fe0233a8cd21aa0f317918dafb18d/lib/matplotlib/transforms.py#L631
>   This just looks like "defensive programming", and if the argument isn't
> already 3d then something is probably wrong.
>
> This isn't an exhaustive list, just a handful of different situations the
> functions were used.
>
> Eric
>
>
>
> On Thu, 11 Feb 2021 at 18:15, Stephan Hoyer  wrote:
>
>> On Thu, Feb 11, 2021 at 9:42 AM Benjamin Root 
>> wrote:
>>
>>> for me, I find that the at_least{1,2,3}d functions are useful for
>>> sanitizing inputs. Having an at_leastnd() function can be viewed as a step
>>> towards cleaning up the API, not cluttering it (although, deprecations of
>>> the existing functions probably should be long given how long they have
>>> existed).
>>>
>>
>> I would love to see examples of this -- perhaps in matplotlib?
>>
>> My thinking is that in most cases it's probably a better idea to keep the
>> interface simpler, and raise an error for lower-dimensional arrays.
>> Automatic conversion is convenient (and endemic within the SciPy
>> ecosystem), but is also a common source of bugs.
>>
>> On Thu, Feb 11, 2021 at 1:56 AM Stephan Hoyer  wrote:
>>>
 On Wed, Feb 10, 2021 at 9:48 PM Juan Nunez-Iglesias 
 wrote:

> I totally agree with the namespace clutter concern, but honestly, I
> would use `atleast_nd` with its `pos` argument (I might rename it to
> `position`, `axis`, or `axis_position`) any day over `at_least{1,2,3}d`,
> for which I had no idea where the new axes would end up.
>
> So, I’m in favour of including it, and optionally deprecating
> `atleast_{1,2,3}d`.
>
>
 I appreciate that `atleast_nd` feels more sensible than
 `at_least{1,2,3}d`, but I don't think "better" than a pattern we would not
 recommend is a good enough reason for inclusion in NumPy. It needs to stand
 on its own.

 What would be the recommended use-cases for this new function?
 Have any libraries building on top of NumPy implemented a version of
 this?


> Juan.
>
> On 11 Feb 2021, at 9:48 am, Sebastian Berg 
> wrote:
>
> On Wed, 2021-02-10 at 17:31 -0500, Joseph Fox-Rabinovitz wrote:
>
> I've created PR#18386 to add a function called atleast_nd to numpy and
> numpy.ma. This would generalize the existing atleast_1d, atleast_2d,
> and
> atleast_3d functions.
>
> I proposed a similar idea about four and a half years ago:
>
> https://mail.python.org/pipermail/numpy-discussion/2016-Jul

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Sebastian Berg]

On Fri, 2021-02-12 at 11:13 +0100, Ralf Gommers wrote:
> On Fri, Feb 12, 2021 at 3:32 AM Juan Nunez-Iglesias
> 
> wrote:
> 
> > both napari and scikit-image use atleast_ a few times. I don’t have
> > many
> > examples of where I used nd because it didn’t exist. But I have the
> > very
> > distinct impression of needing it repeatedly. In some places, I’ve
> > used
> > `np.broadcast_to` to signal the same intention, where `atleast_nd`
> > would
> > have been the more readable solution.
> > 
> > I don’t buy the argument that it’s just a way to mask errors. NumPy
> > broadcasting also has that same potential but I hope no one would
> > seriously
> > consider deprecating it. Indeed, even if we accept that we (library
> > authors) should force users to provide an array of the right
> > dimensionality, that still argues for making it convenient for
> > users to do
> > that!
> > 
> > I don’t feel super strongly about this. But I think atleast_nd is a
> > move
> > in a positive direction and I’d prefer  it to what’s there now:
> > 
> > In [1]: import numpy as np
> > In [2]: np.atleast_3d(np.ones(4)).shape
> > Out[2]: (1, 4, 1)
> > 
> > There might be some linear algebraic reason why those axis
> > positions make
> > sense, but I’m not aware of it...
> > 
> 
> Yes that's pretty weird. I'm also not sure there's a reason.
> 
> It would be good that, if atleast_nd is not going to replicate this
> behavior, atleast_3d was deprecated (perhaps a release or two after
> introduction of atleast_nd).
> 

Planning to replace `atleast_3d` (not right now but soon), sounds like
a good way forward. "1, 2, nd" is pretty good. `atleast_3d` seems not
used all that much and is an odd one out. Having the `nd` version
should make a future deprecation painless, so long term we will be
better off.

- Sebastian


> Not having `atleast_3d(x) == atleast_nd(x, pos=3)` is unnecessarily
> confusing.
> 
> Ralf
> 
> 
> > Juan.
> > 
> > On 12 Feb 2021, at 5:32 am, Eric Wieser <
> > wieser.eric+nu...@gmail.com>
> > wrote:
> > 
> > I did a quick search of matplotlib, and found a few uses of all
> > three
> > functions:
> > 
> > *
> > https://github.com/matplotlib/matplotlib/blob/fed55c63a314351cd39a12783f385009782c06e1/lib/matplotlib/_layoutgrid.py#L441-L446
> >   This one isn't really numpy at all, and is really just a
> > shorthand for
> > normalizing an argument `x=n` to `x=[n, n]`
> > *
> > https://github.com/matplotlib/matplotlib/blob/dd249744270f6abe3f540f81b7a77c0cb728ddbb/lib/matplotlib/mlab.py#L888
> >    This one is the classic "either multivariate or single-variable
> > data"
> > thing endemic to the SciPy ecosystem.
> > *
> > https://github.com/matplotlib/matplotlib/blob/1eef019109b64ee4085732544cb5e310e69451ab/lib/matplotlib/cbook/__init__.py#L1325-L1326
> >   Matplotlib has their own `_check_1d` function for input
> > sanitization,
> > although github says it's only used to parse the arguments to
> > `plot`, which
> > at this point are fairly established as being flexible.
> > *
> > https://github.com/matplotlib/matplotlib/blob/f72adc49092fe0233a8cd21aa0f317918dafb18d/lib/matplotlib/transforms.py#L631
> >   This just looks like "defensive programming", and if the argument
> > isn't
> > already 3d then something is probably wrong.
> > 
> > This isn't an exhaustive list, just a handful of different
> > situations the
> > functions were used.
> > 
> > Eric
> > 
> > 
> > 
> > On Thu, 11 Feb 2021 at 18:15, Stephan Hoyer 
> > wrote:
> > 
> > > On Thu, Feb 11, 2021 at 9:42 AM Benjamin Root <
> > > ben.v.r...@gmail.com>
> > > wrote:
> > > 
> > > > for me, I find that the at_least{1,2,3}d functions are useful
> > > > for
> > > > sanitizing inputs. Having an at_leastnd() function can be
> > > > viewed as a step
> > > > towards cleaning up the API, not cluttering it (although,
> > > > deprecations of
> > > > the existing functions probably should be long given how long
> > > > they have
> > > > existed).
> > > > 
> > > 
> > > I would love to see examples of this -- perhaps in matplotlib?
> > > 
> > > My thinking is that in most cases it's probably a better idea to
> > > keep the
> > > interface simpler, and raise an error for lower-dimensional
> > > arrays.
> > > Automatic conversion is convenient (and endemic within the SciPy
> > > ecosystem), but is also a common source of bugs.
> > > 
> > > On Thu, Feb 11, 2021 at 1:56 AM Stephan Hoyer 
> > > wrote:
> > > > 
> > > > > On Wed, Feb 10, 2021 at 9:48 PM Juan Nunez-Iglesias <
> > > > > j...@fastmail.com>
> > > > > wrote:
> > > > > 
> > > > > > I totally agree with the namespace clutter concern, but
> > > > > > honestly, I
> > > > > > would use `atleast_nd` with its `pos` argument (I might
> > > > > > rename it to
> > > > > > `position`, `axis`, or `axis_position`) any day over
> > > > > > `at_least{1,2,3}d`,
> > > > > > for which I had no idea where the new axes would end up.
> > > > > > 
> > > > > > So, I’m in favour of including it, and optionally
> > > > > > deprecating
> > > > > > `atleast_{1,2

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Robert Kern]

On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser 
wrote:

> > There might be some linear algebraic reason why those axis positions
> make sense, but I’m not aware of it...
>
> My guess is that the historical motivation was to allow grayscale `(H, W)`
> images to be converted into `(H, W, 1)` images so that they can be
> broadcast against `(H, W, 3)` RGB images.
>

Correct. If you do introduce atleast_nd(), I'm not sure why you'd deprecate
and remove the one existing function that *isn't* made redundant thereby.

-- 
Robert Kern
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Joseph Fox-Rabinovitz]

On Fri, Feb 12, 2021, 09:32 Robert Kern  wrote:

> On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser 
> wrote:
>
>> > There might be some linear algebraic reason why those axis positions
>> make sense, but I’m not aware of it...
>>
>> My guess is that the historical motivation was to allow grayscale `(H,
>> W)` images to be converted into `(H, W, 1)` images so that they can be
>> broadcast against `(H, W, 3)` RGB images.
>>
>
> Correct. If you do introduce atleast_nd(), I'm not sure why you'd
> deprecate and remove the one existing function that *isn't* made redundant
> thereby.
>

`atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
argument lets you tell it where to put the new axes. What's unintuitive to
my is that the 1D case gets promoted to from shape `(x,)` to shape `(1, x,
1)`. It takes two calls to `atleast_nd` to replicate that behavior.

One modification to `atleast_nd` I've thought about is making `pos` refer
to the position of the existing axes in the new array rather than the
position of the new axes, but that's likely not a useful way to go about it.

- Joe


> --
> Robert Kern
> ___
> NumPy-Discussion mailing list
> NumPy-Discussion@python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Robert Kern]

On Fri, Feb 12, 2021 at 9:45 AM Joseph Fox-Rabinovitz <
jfoxrabinov...@gmail.com> wrote:

>
>
> On Fri, Feb 12, 2021, 09:32 Robert Kern  wrote:
>
>> On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser 
>> wrote:
>>
>>> > There might be some linear algebraic reason why those axis positions
>>> make sense, but I’m not aware of it...
>>>
>>> My guess is that the historical motivation was to allow grayscale `(H,
>>> W)` images to be converted into `(H, W, 1)` images so that they can be
>>> broadcast against `(H, W, 3)` RGB images.
>>>
>>
>> Correct. If you do introduce atleast_nd(), I'm not sure why you'd
>> deprecate and remove the one existing function that *isn't* made redundant
>> thereby.
>>
>
> `atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
> argument lets you tell it where to put the new axes. What's unintuitive to
> my is that the 1D case gets promoted to from shape `(x,)` to shape `(1, x,
> 1)`. It takes two calls to `atleast_nd` to replicate that behavior.
>

When thinking about channeled images, the channel axis is not of the same
kind as the H and W axes. Really, you tend to want to think about an RGB
image as a (H, W) array of colors rather than an (H, W, 3) ndarray of
intensity values. As much as possible, you want to treat RGB images similar
to (H, W)-shaped grayscale images. Let's say I want to make a separable
filter to convolve with my image, that is, we have a 1D filter for each of
the H and W axes, and they are repeated for each channel, if RGB. Setting
up a separable filter for (H, W) grayscale is straightforward with
broadcasting semantics. I can use (ntaps,)-shaped vector for the W axis and
(ntaps, 1)-shaped filter for the H axis. Now, when I go to the RGB case, I
want the same thing. atleast_3d() adapts those correctly for the (H, W,
nchannels) case.

-- 
Robert Kern
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Sebastian Berg]

On Fri, 2021-02-12 at 10:08 -0500, Robert Kern wrote:
> On Fri, Feb 12, 2021 at 9:45 AM Joseph Fox-Rabinovitz <
> jfoxrabinov...@gmail.com> wrote:
> 
> > 
> > 
> > On Fri, Feb 12, 2021, 09:32 Robert Kern 
> > wrote:
> > 
> > > On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser <
> > > wieser.eric+nu...@gmail.com>
> > > wrote:
> > > 
> > > > > There might be some linear algebraic reason why those axis
> > > > > positions
> > > > make sense, but I’m not aware of it...
> > > > 
> > > > My guess is that the historical motivation was to allow
> > > > grayscale `(H,
> > > > W)` images to be converted into `(H, W, 1)` images so that they
> > > > can be
> > > > broadcast against `(H, W, 3)` RGB images.
> > > > 
> > > 
> > > Correct. If you do introduce atleast_nd(), I'm not sure why you'd
> > > deprecate and remove the one existing function that *isn't* made
> > > redundant
> > > thereby.
> > > 
> > 
> > `atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
> > argument lets you tell it where to put the new axes. What's
> > unintuitive to
> > my is that the 1D case gets promoted to from shape `(x,)` to shape
> > `(1, x,
> > 1)`. It takes two calls to `atleast_nd` to replicate that behavior.
> > 
> 
> When thinking about channeled images, the channel axis is not of the
> same
> kind as the H and W axes. Really, you tend to want to think about an
> RGB
> image as a (H, W) array of colors rather than an (H, W, 3) ndarray of
> intensity values. As much as possible, you want to treat RGB images
> similar
> to (H, W)-shaped grayscale images. Let's say I want to make a
> separable
> filter to convolve with my image, that is, we have a 1D filter for
> each of
> the H and W axes, and they are repeated for each channel, if RGB.
> Setting
> up a separable filter for (H, W) grayscale is straightforward with
> broadcasting semantics. I can use (ntaps,)-shaped vector for the W
> axis and
> (ntaps, 1)-shaped filter for the H axis. Now, when I go to the RGB
> case, I
> want the same thing. atleast_3d() adapts those correctly for the (H,
> W,
> nchannels) case.

Right, my initial feeling it that without such context `atleast_3d` is
pretty surprising.  So I wonder if we can design `atleast_nd` in a way
that it is explicit about this context.

The `pos` argument is the current solution to this, but maybe is a
better way [2]?  Meshgrid for example defaults to `indexing='xy'` and
has `indexing='ij'` for a similar purpose [1].

Of course, if `atleast_3d` is common enough, I guess that argument
could also swing to adding a keyword-only argument to `atleast_3d`
(that way we can/will never change the default).

- Sebastian


[1] Not sure the purposes are comparable, but in both cases, they
provide information about the "context" in which meshgrid/atleast_3d
are used.

[2] It feels a bit like you may have to think about what `pos=3` will
actually do (in the sense, that we will all just end up doing trial and
error :)). At which point I am not sure there is too much gained over
the surprise of `atleast_3d`. 

> 
> ___
> NumPy-Discussion mailing list
> NumPy-Discussion@python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion



signature.asc
Description: This is a digitally signed message part
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Ralf Gommers]

On Fri, Feb 12, 2021 at 7:25 PM Sebastian Berg 
wrote:

> On Fri, 2021-02-12 at 10:08 -0500, Robert Kern wrote:
> > On Fri, Feb 12, 2021 at 9:45 AM Joseph Fox-Rabinovitz <
> > jfoxrabinov...@gmail.com> wrote:
> >
> > >
> > >
> > > On Fri, Feb 12, 2021, 09:32 Robert Kern 
> > > wrote:
> > >
> > > > On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser <
> > > > wieser.eric+nu...@gmail.com>
> > > > wrote:
> > > >
> > > > > > There might be some linear algebraic reason why those axis
> > > > > > positions
> > > > > make sense, but I’m not aware of it...
> > > > >
> > > > > My guess is that the historical motivation was to allow
> > > > > grayscale `(H,
> > > > > W)` images to be converted into `(H, W, 1)` images so that they
> > > > > can be
> > > > > broadcast against `(H, W, 3)` RGB images.
> > > > >
> > > >
> > > > Correct. If you do introduce atleast_nd(), I'm not sure why you'd
> > > > deprecate and remove the one existing function that *isn't* made
> > > > redundant
> > > > thereby.
> > > >
> > >
> > > `atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
> > > argument lets you tell it where to put the new axes. What's
> > > unintuitive to
> > > my is that the 1D case gets promoted to from shape `(x,)` to shape
> > > `(1, x,
> > > 1)`. It takes two calls to `atleast_nd` to replicate that behavior.
> > >
> >
> > When thinking about channeled images, the channel axis is not of the
> > same
> > kind as the H and W axes. Really, you tend to want to think about an
> > RGB
> > image as a (H, W) array of colors rather than an (H, W, 3) ndarray of
> > intensity values. As much as possible, you want to treat RGB images
> > similar
> > to (H, W)-shaped grayscale images. Let's say I want to make a
> > separable
> > filter to convolve with my image, that is, we have a 1D filter for
> > each of
> > the H and W axes, and they are repeated for each channel, if RGB.
> > Setting
> > up a separable filter for (H, W) grayscale is straightforward with
> > broadcasting semantics. I can use (ntaps,)-shaped vector for the W
> > axis and
> > (ntaps, 1)-shaped filter for the H axis. Now, when I go to the RGB
> > case, I
> > want the same thing. atleast_3d() adapts those correctly for the (H,
> > W,
> > nchannels) case.
>
> Right, my initial feeling it that without such context `atleast_3d` is
> pretty surprising.  So I wonder if we can design `atleast_nd` in a way
> that it is explicit about this context.
>

Agreed. I think such a use case is probably too specific to design a single
function for, at least in such a hardcoded way. There's also "channels
first" and "channels last" versions of RGB images as 3-D arrays, and
"channels first" is the default in most deep learning frameworks - so the
choice atleast_3d makes is a little outdated by now.

Cheers,
Ralf


> The `pos` argument is the current solution to this, but maybe is a
> better way [2]?  Meshgrid for example defaults to `indexing='xy'` and
> has `indexing='ij'` for a similar purpose [1].
>
> Of course, if `atleast_3d` is common enough, I guess that argument
> could also swing to adding a keyword-only argument to `atleast_3d`
> (that way we can/will never change the default).
>
> - Sebastian
>
>
> [1] Not sure the purposes are comparable, but in both cases, they
> provide information about the "context" in which meshgrid/atleast_3d
> are used.
>
> [2] It feels a bit like you may have to think about what `pos=3` will
> actually do (in the sense, that we will all just end up doing trial and
> error :)). At which point I am not sure there is too much gained over
> the surprise of `atleast_3d`.
>
> >
> > ___
> > NumPy-Discussion mailing list
> > NumPy-Discussion@python.org
> > https://mail.python.org/mailman/listinfo/numpy-discussion
>
> ___
> NumPy-Discussion mailing list
> NumPy-Discussion@python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Robert Kern]

On Fri, Feb 12, 2021 at 1:47 PM Ralf Gommers  wrote:

>
> On Fri, Feb 12, 2021 at 7:25 PM Sebastian Berg 
> wrote:
>
>> On Fri, 2021-02-12 at 10:08 -0500, Robert Kern wrote:
>> > On Fri, Feb 12, 2021 at 9:45 AM Joseph Fox-Rabinovitz <
>> > jfoxrabinov...@gmail.com> wrote:
>> >
>> > >
>> > >
>> > > On Fri, Feb 12, 2021, 09:32 Robert Kern 
>> > > wrote:
>> > >
>> > > > On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser <
>> > > > wieser.eric+nu...@gmail.com>
>> > > > wrote:
>> > > >
>> > > > > > There might be some linear algebraic reason why those axis
>> > > > > > positions
>> > > > > make sense, but I’m not aware of it...
>> > > > >
>> > > > > My guess is that the historical motivation was to allow
>> > > > > grayscale `(H,
>> > > > > W)` images to be converted into `(H, W, 1)` images so that they
>> > > > > can be
>> > > > > broadcast against `(H, W, 3)` RGB images.
>> > > > >
>> > > >
>> > > > Correct. If you do introduce atleast_nd(), I'm not sure why you'd
>> > > > deprecate and remove the one existing function that *isn't* made
>> > > > redundant
>> > > > thereby.
>> > > >
>> > >
>> > > `atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
>> > > argument lets you tell it where to put the new axes. What's
>> > > unintuitive to
>> > > my is that the 1D case gets promoted to from shape `(x,)` to shape
>> > > `(1, x,
>> > > 1)`. It takes two calls to `atleast_nd` to replicate that behavior.
>> > >
>> >
>> > When thinking about channeled images, the channel axis is not of the
>> > same
>> > kind as the H and W axes. Really, you tend to want to think about an
>> > RGB
>> > image as a (H, W) array of colors rather than an (H, W, 3) ndarray of
>> > intensity values. As much as possible, you want to treat RGB images
>> > similar
>> > to (H, W)-shaped grayscale images. Let's say I want to make a
>> > separable
>> > filter to convolve with my image, that is, we have a 1D filter for
>> > each of
>> > the H and W axes, and they are repeated for each channel, if RGB.
>> > Setting
>> > up a separable filter for (H, W) grayscale is straightforward with
>> > broadcasting semantics. I can use (ntaps,)-shaped vector for the W
>> > axis and
>> > (ntaps, 1)-shaped filter for the H axis. Now, when I go to the RGB
>> > case, I
>> > want the same thing. atleast_3d() adapts those correctly for the (H,
>> > W,
>> > nchannels) case.
>>
>> Right, my initial feeling it that without such context `atleast_3d` is
>> pretty surprising.  So I wonder if we can design `atleast_nd` in a way
>> that it is explicit about this context.
>>
>
> Agreed. I think such a use case is probably too specific to design a
> single function for, at least in such a hardcoded way.
>

That might be an argument for not designing a new one (or at least not
giving it such a name). Not sure it's a good argument for removing a
long-standing one.

Broadcasting is a very powerful convention that makes coding with arrays
tolerable. It makes some choices (namely, prepending 1s to the shape) to
make some common operations with mixed-dimension arrays work "by default".
But it doesn't cover all of the desired operations conveniently.
atleast_3d() bridges the gap to an important convention for a major
use-case of arrays.

There's also "channels first" and "channels last" versions of RGB images as
> 3-D arrays, and "channels first" is the default in most deep learning
> frameworks - so the choice atleast_3d makes is a little outdated by now.
>

DL frameworks do not constitute the majority of image processing code,
which has a very strong channels-last contingent. But nonetheless, the very
popular Tensorflow defaults to channels-last.

-- 
Robert Kern
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

[Numpy-discussion] Documentation Team meeting - Monday February 15

[Melissa Mendonça]

Hi all!

Our next Documentation Team meeting will be on *Monday, February 15* at ***4PM
UTC***. All are welcome - you don't need to already be a contributor to
join. If you have questions or are curious about what we're doing, we'll be
happy to meet you!

If you wish to join on Zoom, use this link:

https://zoom.us/j/96219574921?pwd=VTRNeGwwOUlrYVNYSENpVVBRRjlkZz09#success

Here's the permanent hackmd document with the meeting notes (still being
updated in the next few days!):

https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg


Hope to see you around!

** You can click this link to get the correct time at your timezone:
https://www.timeanddate.com/worldclock/fixedtime.html?msg=NumPy+Documentation+Team+Meeting&iso=20210215T16&p1=1440&ah=1

- Melissa
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Ralf Gommers]

On Fri, Feb 12, 2021 at 9:21 PM Robert Kern  wrote:

> On Fri, Feb 12, 2021 at 1:47 PM Ralf Gommers 
> wrote:
>
>>
>> On Fri, Feb 12, 2021 at 7:25 PM Sebastian Berg <
>> sebast...@sipsolutions.net> wrote:
>>
>>> On Fri, 2021-02-12 at 10:08 -0500, Robert Kern wrote:
>>> > On Fri, Feb 12, 2021 at 9:45 AM Joseph Fox-Rabinovitz <
>>> > jfoxrabinov...@gmail.com> wrote:
>>> >
>>> > >
>>> > >
>>> > > On Fri, Feb 12, 2021, 09:32 Robert Kern 
>>> > > wrote:
>>> > >
>>> > > > On Fri, Feb 12, 2021 at 5:15 AM Eric Wieser <
>>> > > > wieser.eric+nu...@gmail.com>
>>> > > > wrote:
>>> > > >
>>> > > > > > There might be some linear algebraic reason why those axis
>>> > > > > > positions
>>> > > > > make sense, but I’m not aware of it...
>>> > > > >
>>> > > > > My guess is that the historical motivation was to allow
>>> > > > > grayscale `(H,
>>> > > > > W)` images to be converted into `(H, W, 1)` images so that they
>>> > > > > can be
>>> > > > > broadcast against `(H, W, 3)` RGB images.
>>> > > > >
>>> > > >
>>> > > > Correct. If you do introduce atleast_nd(), I'm not sure why you'd
>>> > > > deprecate and remove the one existing function that *isn't* made
>>> > > > redundant
>>> > > > thereby.
>>> > > >
>>> > >
>>> > > `atleast_nd` handles the promotion of 2D to 3D correctly. The `pos`
>>> > > argument lets you tell it where to put the new axes. What's
>>> > > unintuitive to
>>> > > my is that the 1D case gets promoted to from shape `(x,)` to shape
>>> > > `(1, x,
>>> > > 1)`. It takes two calls to `atleast_nd` to replicate that behavior.
>>> > >
>>> >
>>> > When thinking about channeled images, the channel axis is not of the
>>> > same
>>> > kind as the H and W axes. Really, you tend to want to think about an
>>> > RGB
>>> > image as a (H, W) array of colors rather than an (H, W, 3) ndarray of
>>> > intensity values. As much as possible, you want to treat RGB images
>>> > similar
>>> > to (H, W)-shaped grayscale images. Let's say I want to make a
>>> > separable
>>> > filter to convolve with my image, that is, we have a 1D filter for
>>> > each of
>>> > the H and W axes, and they are repeated for each channel, if RGB.
>>> > Setting
>>> > up a separable filter for (H, W) grayscale is straightforward with
>>> > broadcasting semantics. I can use (ntaps,)-shaped vector for the W
>>> > axis and
>>> > (ntaps, 1)-shaped filter for the H axis. Now, when I go to the RGB
>>> > case, I
>>> > want the same thing. atleast_3d() adapts those correctly for the (H,
>>> > W,
>>> > nchannels) case.
>>>
>>> Right, my initial feeling it that without such context `atleast_3d` is
>>> pretty surprising.  So I wonder if we can design `atleast_nd` in a way
>>> that it is explicit about this context.
>>>
>>
>> Agreed. I think such a use case is probably too specific to design a
>> single function for, at least in such a hardcoded way.
>>
>
> That might be an argument for not designing a new one (or at least not
> giving it such a name). Not sure it's a good argument for removing a
> long-standing one.
>

I agree. I'm not sure deprecating is best. But introducing new
functionality where `nd(pos=3) != 3d` is also not great.

At the very least, atleast_3d should be better documented. It also is
telling that Juan (a long-time) scikit-image dev doesn't like atleast_3d
and there's very little usage of it in scikit-image.

Cheers,
Ralf


> Broadcasting is a very powerful convention that makes coding with arrays
> tolerable. It makes some choices (namely, prepending 1s to the shape) to
> make some common operations with mixed-dimension arrays work "by default".
> But it doesn't cover all of the desired operations conveniently.
> atleast_3d() bridges the gap to an important convention for a major
> use-case of arrays.
>
> There's also "channels first" and "channels last" versions of RGB images
>> as 3-D arrays, and "channels first" is the default in most deep learning
>> frameworks - so the choice atleast_3d makes is a little outdated by now.
>>
>
> DL frameworks do not constitute the majority of image processing code,
> which has a very strong channels-last contingent. But nonetheless, the very
> popular Tensorflow defaults to channels-last.
>
> --
> Robert Kern
> ___
> NumPy-Discussion mailing list
> NumPy-Discussion@python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion

Re: [Numpy-discussion] ENH: Proposal to add atleast_nd function

[Robert Kern]

On Fri, Feb 12, 2021 at 3:42 PM Ralf Gommers  wrote:

>
> On Fri, Feb 12, 2021 at 9:21 PM Robert Kern  wrote:
>
>> On Fri, Feb 12, 2021 at 1:47 PM Ralf Gommers 
>> wrote:
>>
>>>
>>> On Fri, Feb 12, 2021 at 7:25 PM Sebastian Berg <
>>> sebast...@sipsolutions.net> wrote:
>>>

 Right, my initial feeling it that without such context `atleast_3d` is
 pretty surprising.  So I wonder if we can design `atleast_nd` in a way
 that it is explicit about this context.

>>>
>>> Agreed. I think such a use case is probably too specific to design a
>>> single function for, at least in such a hardcoded way.
>>>
>>
>> That might be an argument for not designing a new one (or at least not
>> giving it such a name). Not sure it's a good argument for removing a
>> long-standing one.
>>
>
> I agree. I'm not sure deprecating is best. But introducing new
> functionality where `nd(pos=3) != 3d` is also not great.
>
> At the very least, atleast_3d should be better documented. It also is
> telling that Juan (a long-time) scikit-image dev doesn't like atleast_3d
> and there's very little usage of it in scikit-image.
>

I'm fairly neutral on atleast_nd(). I think that for n=1 and n=2, you can
derive The One Way to Do It from broadcasting semantics, but for n>=3, I'm
not sure there's much value in trying to systematize it to a single
convention. I think that once you get up to those dimensions, you start to
want to have domain-specific semantics. I do agree that, in retrospect,
atleast_3d() probably should have been named more specifically. It was of a
piece of other conveniences like dstack() that did special things to
support channel-last images (and implicitly treat 3D arrays as such). For
example, DL frameworks that assemble channeled images into minibatches
(with different conventions like BHWC and BCHW), you'd want the n=4
behavior to do different things. I _think_ you'd just want to do those with
different functions than a complicated set of arguments to one function.

-- 
Robert Kern
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion