[Numpy-discussion] Raveling, reshape order keyword unnecessarily confuses index and memory ordering

Fri Apr 5 23:31:18 EDT 2013

On Fri, Apr 5, 2013 at 10:47 PM, Matthew Brett <matthew.brett at gmail.com> wrote:
> Hi,
>
> On Fri, Apr 5, 2013 at 7:39 PM,  <josef.pktd at gmail.com> wrote:
>> On Fri, Apr 5, 2013 at 9:50 PM, Matthew Brett <matthew.brett at gmail.com> wrote:
>>> Hi,
>>>
>>> On Fri, Apr 5, 2013 at 4:27 PM,  <josef.pktd at gmail.com> wrote:
>>>> On Fri, Apr 5, 2013 at 6:09 PM, Matthew Brett <matthew.brett at gmail.com> wrote:
>>>>> Hi,
>>>>>
>>>>> On Fri, Apr 5, 2013 at 12:53 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Fri, Apr 5, 2013 at 9:21 PM, Matthew Brett <matthew.brett at gmail.com>
>>>>>> wrote:
>>>>>>>
>>>>>>> Hi,
>>>>>>>
>>>>>>> On Fri, Apr 5, 2013 at 3:09 PM, Ralf Gommers <ralf.gommers at gmail.com>
>>>>>>> wrote:
>>>>>>> >
>>>>>>> >
>>>>>>> >
>>>>>>> > On Fri, Apr 5, 2013 at 5:13 PM, Matthew Brett <matthew.brett at gmail.com>
>>>>>>> > wrote:
>>>>>>> >>
>>>>>>> >> Hi,
>>>>>>> >>
>>>>>>> >> On Fri, Apr 5, 2013 at 2:20 AM, Sebastian Berg
>>>>>>> >> <sebastian at sipsolutions.net> wrote:
>>>>>>> >> > Hey
>>> <snip>
>>>>>>> >> I completely agree that we'd have to be gentle with the change.  The
>>>>>>> >> problem we'd want to avoid is people innocently using 'layout' and
>>>>>>> >> finding to their annoyance that the code doesn't work with other
>>>>>>> >> people's numpy.
>>>>>>> >>
>>>>>>> >> How about:
>>>>>>> >>
>>>>>>> >> Step 1:  'order' remains as named keyword, layout added as alias,
>>>>>>> >> comment on the lines of "layout will become the default keyword for
>>>>>>> >> this option in later versions of numpy; please consider updating any
>>>>>>> >> code that does not need to remain backwards compatible'.
>>>>>>> >>
>>>>>>> >> Step 2: default keyword becomes 'layout' with 'order' as alias,
>>>>>>> >> comment like "order is an alias for 'layout' to maintain backwards
>>>>>>> >> compatibility with numpy <= 1.7.1', please update any code that does
>>>>>>> >> not need to maintain backwards compatibility with these numpy
>>>>>>> >> versions'
>>>>>>> >>
>>>>>>> >> Step 3: Add deprecation warning for 'order', "order will be removed as
>>>>>>> >> an alias in future versions of numpy"
>>>>>>> >>
>>>>>>> >> Step 4: (distant future) Remove alias
>>>>>>> >>
>>>>>>> >> ?
>>>>>>> >
>>>>>>> >
>>>>>>> > A very strong -1 from me. Now we're talking about deprecation warnings
>>>>>>> > and a
>>>>>>> > backwards compatibility break after all. I thought we agreed that this
>>>>>>> > was a
>>>>>>> > very bad idea, so why are you proposing it now?
>>>>>>> >
>>>>>>> > Here's how I see it: deprecation of "order" is a no go. Therefore we
>>>>>>> > have
>>>>>>> > two choices here:
>>>>>>> > 1. Simply document the current "order" keyword better and leave it at
>>>>>>> > that.
>>>>>>> > 2. Add a "layout" (or "index_order") keyword, and live with both "order"
>>>>>>> > and
>>>>>>> > "layout" keywords forever.
>>>>>>> >
>>>>>>> > (2) is at least as confusing as (1), more work and poor design.
>>>>>>> > Therefore I
>>>>>>> > propose to go with (1).
>>>>>>>
>>>>>>> You are saying that deprecation of 'order' at any stage in the next 10
>>>>>>> years of numpy's lifetime is a no go?
>>>>>>
>>>>>>
>>>>>> For something like this? Yes.
>>>>>
>>>>> You are saying I think that I am wrong in thinking this is an
>>>>> important change that will make numpy easier to explain and use in the
>>>>> long term.
>>>>>
>>>>> You'd probably expect me to disagree, and I do.  I think I am right in
>>>>> thinking the change is important - I've tried to make that case in
>>>>> this thread, as well as I can.
>>>>>
>>>>>>> I think that is short-sighted and I think it will damage numpy.
>>>>>>
>>>>>>
>>>>>> It will damage numpy to be conservative and not change a name for a little
>>>>>> bit of clarity for some people that avoids reading the docs maybe a little
>>>>>> more carefully? There's a lot of things that can damage numpy, but this
>>>>>> isn't even close in my book. Too few developers, continuous backwards
>>>>>> compatibility issues, faster alternative libraries surpassing numpy - that's
>>>>>> the kind of thing that causes damage.
>>>>>
>>>>> We're talked about consensus on this list.  Of course it can be very
>>>>> hard to achieve.
>>>>
>>>> So far the consensus is that the documentation needs improvement.
>>>
>>> The only thing all of the No camp agree with is documentation
>>> improvement, I think that's fair.
>>>
>>>> After that ???
>>>
>>> Well I think we have:
>>>
>>> Flat-no - the change not important, almost any cost is too high
>>
>> It's not *any* cost, this goes deep and wide, it's one of the basic
>> concepts of numpy that you want to rename.
>
> The proposal I last made was to change the default name to 'layout'
> after some period to be agreed - say - P - with suitable warning in
> the docstring up until that time, and after, and leave 'order' as an
> alias forever.
>
> The only problem I can see with this, is that if someone, after period
> P, does not read the docstring, and uses 'layout' instead of 'order',
> then they will find that their code is not backwards compatible with
> versions of numpy of greater age than P. They can fix this, forever,
> by reverting to 'order'.  That's certainly not zero cost, but it's not
> much cost either, and the cost will depend on P.

You edit large parts of the numpy tutorial and explanations,
you add a second keyword to (rough guess) 10 functions and
a similar number of methods (even wilder guess), the methods
are in C, so you have to change it both on the c and the python
level.
Two keywords will confuse users for a long time
(and which one is in the tutorial documentation)

I'm just guessing and I have no idea about the c-level.

Josef

>
>> Note, I'm just a user of numpy
>> My main objection was to "N" and "Z", which would have affected me
>> (and statsmodels developers)
>
> Right.
>
>> I don't really care about the "layout" change. I have no or almost no
>> code depending on it. And, I don't have to implement it, nor do I have
>> to struggle with the low level numpy behavior that would be affected
>> by this. (And renaming doesn't change the concept.)
>
> No, right, the renaming is to clarify and distinguish the concepts.
>
> Cheers,
>
> Matthew
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion