Doc: Add warning to treat group chunks as immutable
State: closed

- [X] closes #14180 


Labels:
name: Docs
name: Groupby

Comments:
New clean pull request with only the changes for this issue.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=h1) Report
> Merging [#19175](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/913f71f74709e4d4814e50f21768b97ce2c6ef8d?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/19175/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #19175   +/-   ##
=======================================
  Coverage   92.19%   92.19%           
=======================================
  Files         169      169           
  Lines       50959    50959           
=======================================
  Hits        46980    46980           
  Misses       3979     3979
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <ø> (ø)` | :arrow_up: |
| #single | `42.29% <ø> (ø)` | :arrow_up: |


------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=footer). Last update [913f71f...b98e0ce](https://codecov.io/gh/pandas-dev/pandas/pull/19175?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Requested changes made.
@pandas-dev/pandas-core if someone wants to have a look here
As discussed in one of the other issues (https://github.com/pandas-dev/pandas/issues/14927), I think we should rather deprecate the special cased behaviour when the group is mutated, than documenting it.
> As discussed in one of the other issues (#14927), I think we should rather deprecate the special cased behaviour when the group is mutated, than documenting it.

If you mean "_the return value of ``apply()`` should not depend on whether the data was mutated, so the current special case is not worth documenting_", I agree.

But my understanding is that the actual changes to the original ``DataFrame`` are unpredictable/not guaranteed if you mutate the groups, and that this PR warns about that.

Did I misunderstand? If not, maybe the warning can be made more specific.
> But my understanding is that the actual changes to the original DataFrame are unpredictable/not guaranteed if you mutate the groups, and that this PR warns about that.

Ah, but I was not talking about changes to the *original* dataframe. Does that ever happen? (that would mean the group is a view on the original dataframe). I would like to see a code example for that. 

What I thought it was about that mutating the group (inplace), so the same *object* is returned from the function, leads to a different behaviour of how the results are back combined together. 
And it is this different behaviour that I would want to deprecate.

> Ah, but I was not talking about changes to the original dataframe. Does that ever happen?

To be honest I have no idea. If it does not happen, we might then say (after fixing #14927 ) that mutating the chunks can be freely done, because/but it won't affect the original df.

(if it _can_ possibly happen, we might want to keep the warning, and make it refer specifically to the original df)
How does this look?
@toobaz @jorisvandenbossche are you happy to merge the latest version of this, or should we close the PR instead?
Closing this if it's not going to be merged, feel free to reopen if anyone is interested in this.