DOC: Add examples to the method MultiIndex.is_lexsorted()

[raisadz]

• xref MultiIndex.is_monotonic_increasing #32179
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[WillAyd]

Hmm not sure about this one in particular so we collectively should clarify

I don't know that the is_lexsorted implementation is really well defined for a MultiIndex. For instance, I think it only (as a bug) ever looks at the first two levels of a MultiIndex, failing conditions like this:

>>> pd.MultiIndex.from_arrays([['a', 'b', 'c', 'd'],['e', 'f', 'g', 'h'],["z", "y", "x", "w"]]).is_lexsorted()
True
>>> pd.MultiIndex.from_arrays([['a', 'b', 'c', 'd'],['e', 'f', 'g', 'h'],["w", "x", "y", "z"]]).is_lexsorted()
True

@toobaz any thoughts on this?

[MarcoGorelli]

For instance, I think it only (as a bug) ever looks at the first two levels of a MultiIndex, failing conditions like this:

@WillAyd isn't it correct there, though? The first level (Index(['a', 'b', 'c', 'd'], dtype='object')) is sorted, and so the whole MultiIndex is also lexically sorted.

From what I understand about lexical sorting, the third level only needs to be looked at if there's a tie in the first two, e.g.

>>> pd.MultiIndex.from_arrays([['a', 'a', 'c', 'd'],['e', 'e', 'g', 'h'],["x", "y", "y", "z"]]).is_lexsorted()                                                                                               
True

>>> pd.MultiIndex.from_arrays([['a', 'a', 'c', 'd'],['e', 'e', 'g', 'h'],["y", "x", "y", "z"]]).is_lexsorted()                                                                                               
False

[WillAyd]

I don't think the first level alone should be the decider here - maybe @TomAugspurger or @jreback know more of the history / intent

[raisadz]

In the wikipedia page https://en.wikipedia.org/wiki/Lexicographical_order it is said: "Given two different sequences of the same length, a1, a2,...,ak and b1,b2,...,bk, the first one is smaller than the second one for the lexicographical order, if ai < bi (for the order of A), for the first i where ai and bi differ."

>>> pd.MultiIndex.from_arrays([['a', 'b', 'c', 'd'],['e', 'f', 'g', 'h'],["z", "y", "x", "w"]]).is_lexsorted()
True

In the above example, as I understand, the first level is sorted because a<b<c<d, so lexical sorting does not need to look in the next level.

[TomAugspurger]

Yep, this is correct.

But I think this discussion highlights that a sentence describing why this index is lex-sorted would be helpful.

[raisadz]

Sure, happy to add more clarification to this function. I added this example with some explanation, though just made it shorter, so it would be easier to follow.

[jreback]

can you put the expl that you have on 1636-137 before the above example

[WillAyd]

lgtm - @jreback

[WillAyd]

Thanks @raisadz