DOC: Clarify how groupby forms groups for mixed-value columns

[gabuzi]

DOC: Clarify how groupby forms groups for mixed-value columns

[rhshadrach]

Should I insert that here at current L97?

I think this should go in the notes section which is below See Also; L190 here.

When you say hash-based, I assume this means that it always uses hash()? eq() is never considered? Should this be mentioned?

No - hash is used to produce a non-necessarily unique but often distinct number; __eq__ is then used in the case of conflicts. This is why a requirement for writing a hash function is that two objects that are equal must have equal hashes.

I also just realized that the string workaround obviously has its own drawbacks, as it would now group the string '1' and the int 1 as equals, but I guess we don't have to provide a general solution.

That's a good point - this makes me quite hesitant to mention the workaround.

[rhshadrach]

Thanks for the report, I think a line in the notes section of the docstring on DataFrame.groupby and Series.groupby would be appropriate, something like:

The implementation of groupby is hash-based, meaning in particular that objects that compare as equal will be considered as the same group. An exception to this is that pandas has special handling of NA values: any NA values will be collapsed to a single group, regardless of how they compare. See the user guide for more details.

An example in the user guide and your suggested workaround could then be linked to in the last sentence.

Would you be interested in submitting a PR?

[gabuzi]

Thanks for the suggestion. I'd be happy to open a PR on this. Should I insert that here at current L97?

pandas/pandas/core/shared_docs.py

Lines 95 to 99 in bdc79c1

	used to group large amounts of data and compute operations on these
	groups.
	Parameters
	----------

Should I add an example?

I just have another follow-up question: When you say hash-based, I assume this means that it always uses __hash__()? __eq__() is never considered? Should this be mentioned? Maybe in the linked user guide? The implication is that a simple a == b test during debugging as I did above is not actually the right thing to look at (although proper code should maintain a.__eq__(b) == True => a.__hash__() == b.__hash__(), but bugs do happen...).

I also just realized that the string workaround obviously has its own drawbacks, as it would now group the string '1' and the int 1 as equals, but I guess we don't have to provide a general solution.