Docs for hi/lo are confusing

[letmaik]

On the README, I understand the description for hi/lo as:

lo() is just a start offset for each dimension. hi() is the opposite, that is, it truncates by the amount for each dimension. But in fact, hi() is also based on absolute indices and not by an amount. So, I think this should be changed also examples with output added.

[letmaik]

Also, I think lo() is inclusive and hi() is exclusive in the indices, which is common but should be mentioned.

[rreusser]

Unless you're talking about something different, they both just clip the array. So note in particular that

.lo(1,1).hi(4,4)

is NOT the same as

.hi(4,4).lo(1,1)

They operate on the previous command's result, the first:

• .lo(1,1) trims off the first row and column
• .hi(4,4) trims off all the last rows and columns, leaving a 4x4 array

For the second:

• .hi(4,4) trims off all the last rows and columns, leaving a 4x4 array
• .lo(1,1) trims off the first row and column, leaving a 3x3 array

So in other words, the don't commute. The docs specify "Note: hi and lo do not commute. In general: a.hi(3,3).lo(3,3) != a.lo(3,3).hi(3,3)"

Is there additional wording or explanation you think would help prevent confusion?

[letmaik]

I just think the doc description for lo and hi is extremely misleading, if not wrong.

Let's start with lo:

This creates a shifted view of the array. Think of it as taking the upper left corner of the image and dragging it inward by an amount equal to (i,j,k...).

First thing that confuses me is the word "shift". Shifting for me means that something changes but not the size of it, which would be wrong here.

Now hi:

This does the dual of array.lo(). Instead of shifting from the top-left, it truncates from the bottom-right of the array, returning a smaller array object.

Here it says that it is a different operation basically, not shifting but truncating, and making the array smaller, which however is the case for both hi and lo. Also, it doesn't say how truncation exactly works. The description of lo speaks of "amount" and so I would assume that hi (since it is the "dual") just truncates by an amount, but that's not it, it's not the length or size or number of elements that get killed off.

The way I could make sense of it was to just try it out and figure out how it maps to numpy slicing syntax: a.hi(4).lo(2) => a[2:4]

[rreusser]

Haha, yeah, maybe the answer is to word it in terms of more common operators:

a.lo(2,3) => a[2:, 3:]
a.hi(8,7) => a[:8, :7]

I added a couple resources links right at the top of ndarray. The goal of this document was to clarify some of this, but I think it's too buried and frankly not good enough. The numpy version was a great resource when I was figuring out numpy. Oh man, I have a lot of cleanup work to do....

I'll see if I can clean up the lo/hi docs and run it by you.

[huan]

I love this:

a.lo(2,3) => a[2:, 3:]
a.hi(8,7) => a[:8, :7]

Because when I first see lo and hi, I totally have no idea about what is happening.

[wangzhuwei212003]

I wonder “lo” and “hi” are short for what？

[huan]

Hmm... I begin to forget what I learned before after a year...

I can't agree more that lo/hi are really confusing...

[mmomtchev]

Yes, I just came here trying to understand it - and in fact in the beginning I was cursing that hi() was so impractical to use when in fact it is perfect - but the doc is somewhat confusing

This does the dual of array.lo(). Instead of shifting from the top-left, it truncates from the bottom-right of the array, returning a smaller array object.

should be

This does the dual of array.lo(). Instead of shifting from the top-left, it truncates from the bottom-right of the array, returning a smaller array object of (i, j, k) shape.