BUG, DEP, DOC: Patch and Align Categorical's Sorting API
State: closed

Clarifies the meaning of 'sort' in the context of `Categorical` to mean 'organization' rather than 'order',
as it is possible to call this method (as well as `sort_values`) when the `Categorical` is unordered.

Also patches a bug in `Categorical.sort_values` in which `na_position` was not being respected when
`ascending` was set to `True`. This commit aligns the behaviour with that of `Series`.

Finally, deprecates `sort` in favor of `sort_values`, which is in alignment with what was done with `Series` back in #10726.

Closes #12785.


Labels:
name: Docs
name: Categorical
description: Categorical Data Type

Comments:
yeah I am pretty sure that `Categorical.sort` was supposed to be deprecated (IOW, it should actually be calling `.order` rather than `.sort_values`. It was added for method compat with Series/Index, and never actually exposed in api.rst.

so @gfyoung pls change the doc-string, have it call `.order`, add a tests for the deprecation, and a note in the Deprecation section. It was a never advertised method, so I don't think this is a big deal.

@jreback : Wait...so the wrong method was deprecated then?  Because in the documentation, `order` is deprecated but not `sort`.

no `.order` was ALSO deprecated

Read your comment above

all `.sort` and `.order` are deprecated in favor of `.sort_values`. https://github.com/pydata/pandas/pull/10726/files back in 0.17.0

Okay, so everyone calls `sort_values` now!  Got it.

Is it possible there was a reason why `sort` was _not_ deprecated? I can imagine it was done on purpose because a Categorical is actually more array-like than series-like, and then following the numpy 'rules' does make some sense. 
But, I can't really remember if this was the reason to be honest, or whether it was an oversight.

@jorisvandenbossche no it was ADDED in that PR for conformity. with the Series/Index API. I _think_ it was for conforming with a numpy-like object (which DOES have sort). But I don't think it really makes sense.

@jreback : Agreed.  Judging from what I have seen with `Series` and `DataFrame`, the term `sort` is also a tad too generic to describe the types of ordering you can do with `pandas` objects.

Looking back at PR #10726 (the sort unification PR), my conclusion is that `sort` was already implemented (it was not added in that PR) and it was explicitly left alone for the reason I stated above. `Categorical` is an ndarray-substitute, so it makes sense to follow its API (at least for the methods with the same name, of course no problem to have an additional `sort_values`)

@jorisvandenbossche :

1) Could you explain what you mean by that?  I don't quite understand how `Categorical` can substitute for `ndarray`.

2) Given that `pandas` is trying to move away from `numpy`, doesn't it make more sense to align the API with `pandas` objects and not `numpy` ones?

@jorisvandenbossche hmm, ok maybe I am wrong about when this was added. But we have removed (well deprecated) `.sort` from everything except `Index` (where it raises). So not sure we really need this addtl method.

`.sort` was added when we originally added `Categorical` (or well updated it): https://github.com/pydata/pandas/commit/0f62d3fc62f317538044ed3d349bfb89fb7ee9de

@jreback : Travis is giving a green light once more, and I have addressed all of the changes / comments so far.  Ready to merge if everyone is happy.

thanks!