Adds Series.in/2 function

[kimjoaoun]

This PR closes #273.
It creates the function Explorer.Series.in/2 that uses Polars' IsIn trait to check if values from a list are contained in a Series.

I really don't know how to describe the function in the docstring, can someone help me?

[josevalim]

I really don't know how to describe the function in the docstring, can someone help me?

Yeah, this is a good question. To be honest, I am not the biggest fan of the name. What does dplyr call it? It feels like within?, included?, etc would be better but I am not sure.

[kimjoaoun]

I really don't know how to describe the function in the docstring, can someone help me?

Yeah, this is a good question. To be honest, I am not the biggest fan of the name. What does dplyr call it? It feels like within?, included?, etc would be better but I am not sure.

In R we don't have this operation in dplyr, because it is natively supported by the %in% operator. But also in base R there's a rarely used function called within that does exactly the same.
Between within? and included?, I think the former is the better.

Note: Pandas has pd.Series.isin.

[josevalim]

I see. So I think we should simply call it in/2. We can document it as "Check if the elements of the series in the left exists in the series in the right."

[josevalim]

Note that, if we call it in, then you will have to write it as:

def %Series{} = left in %Series{} = right do

and

def %Series{} = left in right when is_list(right) do

The callback will be @callback (s() in s()) :: s() and so on.

[kimjoaoun]

I see. So I think we should simply call it in/2. We can document it as "Check if the elements of the series in the left exists in the series in the right."

Would not it be too similar to Kernel.in?

[josevalim]

I think that's the idea! Then it will automatically work in Explorer.Query as: series in [1, 2, 3] and left in right, similar to R.

[cigrainger]

Given that this is failing for 1.13... should we go ahead and bump Explorer to minimum 1.14 for the next release? I'm surprised we're not already doing that.

[josevalim]

@cigrainger fixing for v1.13 should be easy and mostly a matter of using K.in(left, right) instead of in(left, right). I believe the biggest blocker for this PR is if you actually agree with the API. :)

[cigrainger]

Hm okay. Jumping into this... it's a vectorised op right? So what we get back is a boolean series where each element is true if in the right and false if in the left? I like in/2. I think the confusion is coming from the fact that it's vectorised. But yeah... let's go with in/2

In terms of the docstring:

@doc """
Checks if each element of the series in the left exists in the series in the right, returning a boolean mask.

  ## Examples

      iex> left = Explorer.Series.from_list([1, 2, 3])
      iex> right = Explorer.Series.from_list([1, 2])
      iex> Series.in(left, right)
      #Explorer.Series<
        Polars[3]
        boolean [true, true, false]
      >
"""

[josevalim]

💚 💙 💜 💛 ❤️