[Numpy-discussion] numpy.filled, again

[josef.pktd at gmail.com]

On Wed, Jun 12, 2013 at 10:45 AM, Warren Weckesser
<warren.weckesser at gmail.com> wrote:
>
>
>
> On Wed, Jun 12, 2013 at 10:18 AM, Nathaniel Smith <njs at pobox.com> wrote:
>>
>> On Wed, Jun 12, 2013 at 1:28 PM, Matthew Brett <matthew.brett at gmail.com>
>> wrote:
>> > On Wed, Jun 12, 2013 at 1:10 PM, Nathaniel Smith <njs at pobox.com> wrote:
>> >> Personally I think that overloading np.empty is horribly ugly, will
>> >> continue confusing newbies and everyone else indefinitely, and I'm
>> >> 100% convinced that we'll regret implementing such a warty interface
>> >> for something that should be so idiomatic. (Unfortunately I got busy
>> >> and didn't actually say this in the previous thread though.)
>> >
>> > Maybe you could unpack this, as I seem to remember this was the option
>> > with the most support previously.
>>
>> Indeed it was, which is why I brought it up :-).
>>
>> I'm not sure what more there is to unpack, though. It's just...
>> offensive to every sense of API design I have, I don't know how to
>> explain more than I have. I speculate that it's only attraction is
>> that it showed up at the end of a 50 email thread and offered the
>> promise of ending things, but I don't know.
>>
>> Well, here's maybe another way of getting at the ugliness.
>>
>> Here's the current doc page listing all the options for creating an
>> array -- a very useful reference, esp. while learning:
>>   http://docs.scipy.org/doc/numpy/reference/routines.array-creation.html
>>
>> Now imagine a new version of this page, if we add 'filled'. There will
>> be a list at the top with functions named:
>>   empty
>>   filled
>>   ones
>>   zeros
>> It's immediately obvious what all of these things do, and how they
>> differ from each other, and in which situation you might want each,
>> just from the names, even before you read the one-line synopses. Even
>> more so if you know about the existence of np.fill(). The synopses for
>> 'ones' and 'zeros' don't even have to change, they already use the
>> word 'filled' to describe what they do. It all just works.
>>
>> Now imagine a different new version of this page, if we overload
>> 'empty' to add a fill= option. I don't even know how we document that
>> on this page. The list will remain:
>>   empty
>>   ones
>>   zeros
>> So there will be no clue there how you get an array filled with NaNs
>> or whatever, or even any hint that it's possible. Then there's the
>> prose on the right. Right now the synopsis for 'empty' is:
>>   Return a new array of given shape and type, without initializing
>> entries.
>> I guess we change this to
>>   Return a new array of given shape and type, without initializing
>> entries, OR return a new array of given shape and type, with values
>> initialized to some specific value.
>> ? IMO probably the single best criterion for judging whether your API
>> is good, is whether you can write clean and pretty docs for it. This
>> fails that test horribly...
>>
>> We probably should advertise the ndarray constructor more, and
>> possibly make it more generally useful, but the current situation for
>> better or worse is that we've spent many years telling people that
>> it's a weird low-level thing that they shouldn't use. (I didn't even
>> know how it worked until 10 minutes ago!) Adding this functionality
>> there means it'll still be hidden away, so it's not a great solution
>> to the 'filled' problem, and it doesn't really move us any closer to
>> having a coherent story on when you should use the ndarray constructor
>> either.
>>
>> So IMO the best (least bad) solution on offer is still to just add a
>> 'filled' function, and live with the np.ma inconsistency.

+2 on this.
I like a good name like `filled` for a function that I expect to use regularly.
it's short and descriptive.

Josef

>>
>
>
> Another idea (also imperfect): call the new functions `filledwith` and
> `filledwith_like`.  Not as concise as `filled`, but the meaning is still
> clear, and it avoids the clash with `ma.filled`.
>
> Warren
>
>
>>
>> -n
>> _______________________________________________
>> NumPy-Discussion mailing list
>> NumPy-Discussion at scipy.org
>> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>