add allcombinations

[bkamins]

Fixes #3027

Before I finalize this PR (add tests and NEWS.md) please comment if we like the design.
In particular do you think that the set of proposed signatures is OK.

Thank you!

[nalimilan]

Could we find a name more closely related to fillcombinations, which is similar? Maybe this should even be a method of fillcombinations?

It would also make sense to mention the relationship between the two functions in their docstrings (dplyr does that IIRC).

[bkamins]

dplyr mentions that expandgrid is internally used in their fillcombinations equivalent. However, it was not possible in DataFrames.jl (the reason is that in dplyr everything is a vector, and in Julia we have scalars and need pseudo-broadcasting).

Conceptually this is very different, as fillcombinations requires input to have equal lengths of vectors passed (that is why they are stored in a data frame), while here each input can (and usually has) a different length.

We could name this function or just product and not export it, but document that users can write DataFrames.product. This would be consistent with Iterators.product as it does exactly the same thing (but with a set of rules that is consistent with pseudo-broadcasting).

[bkamins]

or we could use expandcombinations as a name if we want the name to be similar (and then export it).
However, I tend to prefer DataFrames.product that is documented as part of API but unexported.

[bkamins]

(as for the reason why I cannot call expandgrid in fillcombinations you can have a look at their codes and compare the internals of the core loop that does the expansion - there are subtle differences since there we repeat levels, but need to allocate columns from source vector - e.g. for CategoricalArray it makes a difference and cannot be handled correctly if passed to expandgrid)

[bkamins]

OK - so what do we do about the name? Keep expandgrid (a la R), use DataFrames.product or something else e.g. allcombinations?

[nalimilan]

The drawback of DataFrames.product is that it would be the only unexported function in the API, thus introducing a new pattern. "grid" isn't a common term in Julia AFAICT so expandgrid sounds weird. Maybe something based on "combinations" would be more consistent with fillcombinations. allcombinations or expandcombinations?

[bkamins]

I will go for allcombinations then (it seems R docstring uses a similar terminology, although technically speaking "combinations" is something different and here we are doing cartesian product)

[bkamins]

@nalimilan - the PR should be ready for a final review. Thank you!

[bkamins]

@nalimilan - so in the end do we stick with allcombinations? (being aware that some mathematicians might complain?)

[bkamins]

@nalimilan - I have added DataFrame as a first argument requirement. The PR should be updated when JuliaData/DataAPI.jl#47 is merged and released. But if other things are OK for you I will write the tests of the current functionality, so please let me know. Thank you!

[bkamins]

Thank you!

[vjd]

🎉

[andreasnoack]

Isn't this a different API for the same functionality that crossjoin provides? If both at needed then it might be useful to cross reference.

[bkamins]

allcombinations(DataFrame, "a" => 1:2, "b" => 'a':'c', "c" => "const")

is the same as

crossjoin(DataFrame("a" => 1:2), DataFrame("b" => 'a':'c'), DataFrame("c" => "const"))

Most users find the latter a bit inconvenient to write.

What would you propose exactly to add to the documentation?

[andreasnoack]

I was thinking a "See also" entry.

Most users find the latter a bit inconvenient to write.

The new function might be a bit simpler to type. I was mostly surprised that crossjoin wasn't mentioned in the issue. It made it look like the functionality wasn't already available and I'm pretty sure that some of people asking for an expand.grid function weren't aware of crossjoin.

[bkamins]

OK - I will add a link to crossjoin