API: MultiIndex.labels -> codes

[chris-b1]

The boat may have long sailed on this, but just for consideration.

I semi-frequently get the .levels and .labels of a MultiIndex backwards. Maybe it's just me, but I think labels is the culprit, because in other pandas contexts, "labels" refer to the actual value of the thing. E.g.

• .loc indexes by "labels" (values)
• the values inside of a single row index or columns are the "labels" for those items

So, consistent with Categorical, would it make sense for the integer mapping inside a MultiIndex to also be called .codes?

[jreback]

IIRC this originally came from R land. I actually have no problem with this, esp for consistency.

its a tiny bit tricky to do this because you have to accept both args for a while.

[jorisvandenbossche]

I personally also find the current naming confusing (but indeed separate question is if there is something better that is workable to change to)

Besides labels, I also find levels confusing. The levels are actually what we now call the categories in the Categorical API (I even find labels a better name for levels). I find this confusing because of the usage of the level= keyword argument in many functions (so the idea that the MultiIndex has several 'levels').

[shoyer]

+1 for the attribute names .categories and .codes. This is mostly internal/advanced API, so I don't think this will be too painful. The level= keyword argument can stay -- it means something entirely different.

[jorisvandenbossche]

The level= keyword argument can stay -- it means something entirely different.

Yes certainly (I didn't want to imply that). That is the logical use for this name, and that is what makes the 'other' levels a confusing name.

BTW, I also think that the current repr is not the best one. As @shoyer put, the levels/labels are 'mostly internal', so then we shouldn't show them by default in repr? But will open a separate issue for that. EDIT -> #13480

[jorisvandenbossche]

+1 for the attribute names .categories and .codes

codes is certainly OK, but I am personally a bit less enthusiastic about categories. I know implementation wise (codes/labels and categories/levels) they are very similar, but for a lot of users, I don't think they see it that way. So calling it categories may be confusing as well.
(although, since we are just arguing it is more internal-like, it maybe does not matter that much)

[jreback]

anyone have appetite for changing .labels -> .codes? This is purely internal.

I think this would be a positive change here. (let's leave levels as is though).