CLN/DOC: _selected_obj vs _obj_with_exclusions

[jbrockmendel]

In the groupby code, when do/should we use self._obj_with_exclusions vs self._selected_obj?

[mroeschke]

cc @rhshadrach @jreback

[rhshadrach]

Current behavior

self._selected_obj:

• If self.obj is a Series, self._selected_obj is always equal to self.obj.
• Otherwise, if self._selection is not None, self._selected_obj is self._obj subset to self._selection.
• Otherwise, if self._group_selection is not None, self._selected_obj is self.obj subset to self._group_selection. self._group_selection is only set within the self._group_selection_context (and even then, only when certain conditions hold).
• Otherwise, self._selected_obj is self.obj

self._obj_with_exclusions:

• If self.obj is a Series, self._obj_with_exclusions is always equal to self.obj.
• Otherwise, if self._selection is not None, self._obj_with_exclusions is self.obj subset to self._selection.
• Otherwise if self.exclusions is non-empty, self._obj_with_exclusions is self.obj with exclusions columns dropped
• Otherwise self._obj_with_exclusions is self.obj

I don't have a good reason why both of these objects should exist, so I don't think I can say when to use one over the other. I have similar thoughts about _group_selection_context. I'd like to see one of them (and the context) removed. Looking at usage in the groupby code, I see 58 instances of _selected_obj and 27 instances of _obj_with_exclusions. As such, I would try to remove uses of _obj_with exclusions and add the self._group_selection_context wherever _selected_obj is used without one.

[rhshadrach]

To the _obj_with_exclusions method, I added

from pandas.core.groupby.groupby import BaseGroupBy
if isinstance(self, BaseGroupBy):
    from pandas._testing import assert_equal
    with self._group_selection_context():
        assert_equal(result, self._selected_obj)

where result is the result of this method and only 106 of the 8414 groupby tests failed. There were 32 distinct tests (ignoring parameterizations).