DOC: Clarify rank documentation

[ptype]

• closes #xxxx
• tests added / passed
• Ensure all linting tests pass, see here for how to run them
• whatsnew entry

Example of top/bottom behaviour vs ascending:

x = np.array([np.nan, 3.1, 1.4, 2.1, np.nan, 5, 0.5])
pd.Series(x).rank(ascending=False, na_option='bottom', method='min') ->
0    6.0
1    2.0
2    4.0
3    3.0
4    6.0
5    1.0
6    5.0
dtype: float64

pd.Series(x).rank(ascending=True, na_option='bottom', method='min') ->
0    6.0
1    4.0
2    2.0
3    3.0
4    6.0
5    5.0
6    1.0
dtype: float64

pd.Series(x).rank(ascending=True, na_option='top', method='min') ->
0    1.0
1    6.0
2    4.0
3    5.0
4    1.0
5    7.0
6    3.0
dtype: float64

pd.Series(x).rank(ascending=False, na_option='top', method='min') ->
0    1.0
1    6.0
2    4.0
3    5.0
4    1.0
5    7.0
6    3.0
dtype: float64

[attack68]

although irrelevant, the last example is wrong, actually gives:

0    1.0
1    4.0
2    6.0
3    5.0
4    1.0
5    3.0
6    7.0
dtype: float64

but this lgtm, na_option is not impacted by ascending and it's strange wording in the docs.

[ptype]

Sorry @attack68, yes you are right, I copy pasted the wrong one. Thanks.

[WillAyd]

I think this is a bug rather than an issue with the documentation, no?

[ptype]

First I thought that as well, but the behaviour actually makes sense to me in the sense that a ranking goes from 1 (lowest/top) to n (highest/bottom), and na_option determines if you want your nans at the top or bottom of the ranking (regardless of ascending).

[attack68]

First I thought that as well, but the behaviour actually makes sense to me in the sense that a ranking goes from 1 (lowest/top) to n (highest/bottom), and na_option determines if you want your nans at the top or bottom of the ranking (regardless of ascending).

@WillAyd I think the issue is with semantics. If you rank values either 'ascending' or 'descending' and then insert an 'NaN' either at 'top' or 'bottom', does 'top' refer to assigning the highest 'value' to 'NaN' in which case 'ascending' places it with the highest rank and 'descending' the lowest? Or does it place the 'NaN' at the 'top' of the rankings (i.e. lowest rank) or the 'bottom'.

I think the use of 'top' and 'bottom' is terrible. I prefer the latter approach but would think 'na_rep' = {'lowest_rank', 'highest_rank'} is clearer and this is essentially what it is doing for {'top', 'bottom'}.

[ptype]

@attack68 Personally I think this can be solved with clearer documentation as it's all about terminology, rather than changing the API. I think it needs to be explained as in #40016 (comment). I'm not a maintainer so up to you guys. Happy to create PR on that though if that is the route you want to go down.

[attack68]

@ptype, sure but is top: assign the top rank (i.e. lowest value) to NaN values a bit clearer why top is used and what it corresponds to?

[ptype]

@ptype, sure but is top: assign the top rank (i.e. lowest value) to NaN values a bit clearer why top is used and what it corresponds to?

@attack68 yes, I think so

[github-actions]

This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.

[ptype]

This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.

I think it should still be considered for inclusion

[attack68]

i think this documentation is clearer, if not ideal. LGTM

[datapythonista]

@ptype can you merge master, and make sure the CI is green, so we can merge, please? Ping me once it's green, thanks!

[ptype]

@datapythonista thanks, I've fetched from master and reran CIs, all green

[datapythonista]

Thanks @ptype