DOC: Categorical sort_values and sort Documentation

[gfyoung]

In categorical.py, we enforce the fact that self must be ordered when calling min or max. However, self can be unordered when calling sort_values. This doesn't make sense in my mind, for if you can sort the values for unordered self, then I can then find a minimum value of self. The same comment applies to argsort as well.

[jreback]

prob an overight, should be using check_for_ordered(..) internally there.

[gfyoung]

Given how straightforward the PR is, would it be for v0.18.1 or v0.19.0?

[jreback]

its a bug, why would it not be 0.18.1?

[gfyoung]

Just wanted to double check. 😄

[jorisvandenbossche]

Are we sure this is a bug?
We have had a lot of discussions about the API, and certainly also about the ordered implication, min() raising etc. But I can't really remember if we discussed this specific issue.

In any case, I think it can be quite annoying if you cannot sort values (eg to just group them).
And as a comparison, R does allow to sort, but raises for min() in case of unordered factors.

[jreback]

you could be right @jorisvandenbossche, I don't really remember.

cc @JanSchulz

[gfyoung]

@jorisvandenbossche : Is calling .as_ordered() that problematic? How about my explanation above?

@everyone : Regardless of whether this is a bug or not, something will have to give. The documentation insists that argsort and sort can only be called on ordered Categorical objects, but the internals do not match.

[jankatins]

That was a consious descision sometime after implementing categoricals (and I just saw that the docstring was not changed: https://github.com/pydata/pandas/blob/master/pandas/core/categorical.py#L205)

commit is here: 87fec5b

[jreback]

#9347 and #9611

[jankatins]

Yep, I think it started here: #9611 (comment)