DOC: Series.idxmax actually returns a label, not an index

[AllenDowney]

In https://github.com/pandas-dev/pandas/blob/master/pandas/core/series.py, the DocStrings for idxmax and idxmin are misleading (in my opinion). They say they return the index of the max/min, but they actually return the label (if I've got my Pandas lingo right).

Same with DataFrame.idxmax and DataFrame.idxmin.

Also, is there a reason Series provides argmax as a synonym for idxmax, and DataFrame does not?

One more thought: I find it surprising that idxmax and argmax do the same thing. I expected idxmax to return an index and argmax to return a label. I suppose it's too late to make that change.

[TomAugspurger]

Agreed that changing to label would be clearer.

For the idxmax vs. argmax, I think that was accidentally broken once Series no longer inherited from ndarray, see #6214.
I think we could issue a FutureWarning in 0.21.0, saying to use .idxmax instead of .argmax, and then followup to change .argmax to always be positional.

[TomAugspurger]

Let's leave this issue for the documentation, and I'll open a new one for the argmax.

edit: #16830

[AllenDowney]

Thanks, Tom. Please let me know if there's anything I can do to help.

…

On Wed, Jul 5, 2017 at 10:22 AM, Tom Augspurger ***@***.***> wrote: Let's leave this issue for the documentation, and I'll open a new one for the argmax. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#16829 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABy37fO8EHOFEnYcCGnnBqgMcxUi63jLks5sK5wJgaJpZM4OOYys> .

[iuliakhomenko]

Hi! I will correct idxmax and idxmin documentation for both Series and DataFrame

[gfyoung]

@iuliakhomenko : Go for it! Thanks for volunteering!

[TomAugspurger]

Hi @iuliakhomenko. I think the ongoing work in #16955 will make the changes here unnecessary, so this may not be a good issue to work on.

We have plenty of other issues to take on if you're interested in contributing though :) Let us know if you need help finding one.

[iuliakhomenko]

@TomAugspurger ok, I will look into other issues. Thanks :)

[gfyoung]

I think the ongoing work in #16955 will make the changes here unnecessary

@TomAugspurger : Except that the work isn't going ATM ;)

I don't see why we shouldn't address this issue unless we definitely plan on pushing #16955 through, which judging from the lack of tagging, isn't going to happen for now.

[jorisvandenbossche]

@gfyoung I think that PR should certainly go in, and is in fact almost ready. In the submitter doesn't respond the coming week(s), we can easily fix up and merge.

[gfyoung]

@jorisvandenbossche : Sounds good. I didn't know where that PR stood currently in the pipeline. Thanks for clarifying!

[jorisvandenbossche]

Just my personal opinion :-) But I have tagged it now as such to make it clear

[jorisvandenbossche]

This is fixed in the meantime by #16955