[BREAKING] Multicolumn transformations for GoupedDataFrame

[bkamins]

Fixes #2410

I am opening now to make sure that 0.22 branch of a13db50 does not get lost.

This PR is not finished. I have implemented all (in particular allowing returning multiple columns from functions) except handling AsTable and multipe Symbols as destination columns (this still needs to be implemented as it requires new logic)

[bkamins]

OK - this PR is not cleaned, tested, nor documented yet, but the promised functionality seems (remember - not tested 😄)) to work, so please feel free to experiment with it and comment if you catch something surprising. Thank you!

[bkamins]

@pdeffebach - with this PR we ensure the following invariant (which I think is relevant for DataFramesMeta.jl design). The result of:

transform(df, args...)

is always the same as the result of

transform(groupby(df, cols), args...)

(also up to errors - if one errors the other also errors)

if args is ByRow transformation.

[pdeffebach]

Wait, why would we want that?

What if I want to perform the operation x .- mean(x)? We put a lot of effort into ensuring transform works by groups.

[bkamins]

Right - I forgotten to add that args must be ByRow. I will update.

[pdeffebach]

Oh good. You scared me! Yes having the same with ByRow is the correct behavior. Thanks!

[bkamins]

I still have a lot of tests to write (but now the PR should pass the tests) and documentation to update.
However, @nalimilan - can you please review the changes in docs/src/man/split_apply_combine.md as correcting the documentation is usually a lengthy process, and probably we can reuse things we work-out there in the docstrings later. Thank you!

(all others: feel free to have a look at docs/src/man/split_apply_combine.md if you are interested as it specifies how new rules work)

[bkamins]

@nalimilan - documentation updates part 2 (and hopefully final) is pushed here. I made adjustments to the manual per the comments given + I have refactored the docstrings. Now they are consistent with the manual and reuse the same template. This has three benefits I believe:

1. it will be easier to maintain
2. the docstrings take less space (which is relevant as the files are very large anyway)
3. the docstrings show a comparison of similarities and differences between available functions

Another review of documentation would be appreciated (after it is done I will review the tests of the functionality to make sure we cover everything and the PR then will be good for a final review).

[bkamins]

I have added additional tests of correctness of the functionality we expose. This should be good for a whole code review.

[bkamins]

This PR is holding implementation of where PR.

EDIT: I managed to get it without needing this, see #2496

[bkamins]

@nalimilan I have incorportated all the recommended changes apart from syncing manual and docs - I will do it when manual is finalized. It should be ready for another round of reviews. Thank you!

[nalimilan]

I don't think that's true: in general the order is really undefined due to the dict-like grouping fallback. And the pool of PooledDataArray isn't exposed to users so it's not really useful to tell give them this information.

EDIT: I was wrong, for some reason I hadn't realize that the fallback grouping method uses the order of appearance.

[bkamins]

I have updated the description to make it more precise.

[nalimilan]

But how about making this part specific to each function's docstring so that we never mention an argument that a function doesn't support?

(BTW I don't see the change to "signature".)

[bkamins]

@nalimilan - I have incorporated the comments. Let me know if it is OK to move the descriptions from the manual to the docstring. Thank you!

[bkamins]

TODO: add NEWS.md entry (when @nalimilan approves moving the manual text into the docstrings).

[bkamins]

All suggestions are applied, manual and dosstrings are synchronized, and NEWS.md is updated.

[bkamins]

Thank you!