High-level query for Explorer.

Explorer.DataFrame vs DF

All examples below assume you have defined aliased Explorer.DataFrame to DF as shown below:

alias Explorer.DataFrame, as: DF

Queries convert regular Elixir code which compile to efficient dataframes operations. Inside a query, only the limited set of Series operations are available and identifiers, such as strs and nums, represent dataframe column names:

iex> df = DF.new(strs: ["a", "b", "c"], nums: [1, 2, 3])
iex> DF.filter(df, nums > 2)
#Explorer.DataFrame<
  Polars[1 x 2]
  strs string ["c"]
  nums integer [3]
>

If a column has unusual format, you can either rename it before-hand, or use col/1 inside queries:

iex> df = DF.new("unusual nums": [1, 2, 3])
iex> DF.filter(df, col("unusual nums") > 2)
#Explorer.DataFrame<
  Polars[1 x 1]
  unusual nums integer [3]
>

All operations from Explorer.Series are imported inside queries. This module also provides operators to use in queries, which are also imported into queries.

Supported operations

Queries are supported in the following operations:

• Explorer.DataFrame.arrange/2
• Explorer.DataFrame.filter/2
• Explorer.DataFrame.mutate/2
• Explorer.DataFrame.summarise/2

Interpolation

If you want to access variables defined outside of the query or get access to all Elixir constructs, you must use ^:

iex> min = 2
iex> df = DF.new(strs: ["a", "b", "c"], nums: [1, 2, 3])
iex> DF.filter(df, nums > ^min)
#Explorer.DataFrame<
  Polars[1 x 2]
  strs string ["c"]
  nums integer [3]
>

iex> min = 2
iex> df = DF.new(strs: ["a", "b", "c"], nums: [1, 2, 3])
iex> DF.filter(df, nums < ^if(min > 0, do: 10, else: -10))
#Explorer.DataFrame<
  Polars[3 x 2]
  strs string ["a", "b", "c"]
  nums integer [1, 2, 3]
>

^ can be used with col to access columns dynamically:

iex> df = DF.new("unusual nums": [1, 2, 3])
iex> name = "unusual nums"
iex> DF.filter(df, col(^name) > 2)
#Explorer.DataFrame<
  Polars[1 x 1]
  unusual nums integer [3]
>

Conditionals

Queries support both if/2 and unless/2 operations inside queries.

cond/1 can be used to write multi-clause conditions:

iex> df = DF.new(a: [10, 4, 6])
iex> DF.mutate(df,
...>   b:
...>     cond do
...>       a > 9 -> "Exceptional"
...>       a > 5 -> "Passed"
...>       true -> "Failed"
...>     end
...> )
#Explorer.DataFrame<
  Polars[3 x 2]
  a integer [10, 4, 6]
  b string ["Exceptional", "Failed", "Passed"]
>

Across and comprehensions

Explorer.Query leverages the power behind Elixir for-comprehensions to provide a powerful syntax for traversing several columns in a dataframe at once. For example, imagine you want to standardization the data on the iris dataset, you could write this:

iex> iris = Explorer.Datasets.iris()
iex> DF.mutate(iris,
...>   sepal_width: (sepal_width - mean(sepal_width)) / variance(sepal_width),
...>   sepal_length: (sepal_length - mean(sepal_length)) / variance(sepal_length),
...>   petal_length: (petal_length - mean(petal_length)) / variance(petal_length),
...>   petal_width: (petal_width - mean(petal_width)) / variance(petal_width)
...> )
#Explorer.DataFrame<
  Polars[150 x 5]
  sepal_length float [-1.0840606189132314, -1.3757361217598396, -1.6674116246064494, -1.8132493760297548, -1.2298983703365356, ...]
  sepal_width float [2.372289612531505, -0.28722789030650403, 0.7765791108287006, 0.24467561026109824, 2.904193113099107, ...]
  petal_length float [-0.7576391687443842, -0.7576391687443842, -0.7897606710936372, -0.725517666395131, -0.7576391687443842, ...]
  petal_width float [-1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, ...]
  species string ["Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", ...]
>

While the code above does its job, it is quite repetitive. With across and for-comprehensions, we could instead write:

iex> iris = Explorer.Datasets.iris()
iex> DF.mutate(iris,
...>   for col <- across(["sepal_width", "sepal_length", "petal_length", "petal_width"]) do
...>     {col.name, (col - mean(col)) / variance(col)}
...>   end
...> )
#Explorer.DataFrame<
  Polars[150 x 5]
  sepal_length float [-1.0840606189132314, -1.3757361217598396, -1.6674116246064494, -1.8132493760297548, -1.2298983703365356, ...]
  sepal_width float [2.372289612531505, -0.28722789030650403, 0.7765791108287006, 0.24467561026109824, 2.904193113099107, ...]
  petal_length float [-0.7576391687443842, -0.7576391687443842, -0.7897606710936372, -0.725517666395131, -0.7576391687443842, ...]
  petal_width float [-1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, ...]
  species string ["Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", ...]
>

Which achieves the same result in a more concise and maintainable way. across/1 may receive any of the following input as arguments:

• a list of columns indexes or names as atoms and strings

• a range

• a regex that keeps only the names matching the regex

For example, since we know the width and length columns are the first four, we could also have written (remember ranges in Elixir are inclusive):

DF.mutate(iris,
  for col <- across(0..3) do
    {col.name, (col - mean(col)) / variance(col)}
  end
)

Or using a regex:

DF.mutate(iris,
  for col <- across(~r/(sepal|petal)_(length|width)/) do
    {col.name, (col - mean(col)) / variance(col)}
  end
)

For those new to Elixir, for-comprehensions have the following format:

for PATTERN <- GENERATOR, FILTER do
  EXPR
end

A comprehension filter is a mechanism that allows us to keep only columns based on additional properties, such as its dtype. A for-comprehension can have multiple generators and filters. For instance, if you want to apply standardization to all float columns, we can use across/0 to access all columns and then use a filter to keep only the float ones:

iex> iris = Explorer.Datasets.iris()
iex> DF.mutate(iris,
...>   for col <- across(), col.dtype == :float do
...>     {col.name, (col - mean(col)) / variance(col)}
...>   end
...> )
#Explorer.DataFrame<
  Polars[150 x 5]
  sepal_length float [-1.0840606189132314, -1.3757361217598396, -1.6674116246064494, -1.8132493760297548, -1.2298983703365356, ...]
  sepal_width float [2.372289612531505, -0.28722789030650403, 0.7765791108287006, 0.24467561026109824, 2.904193113099107, ...]
  petal_length float [-0.7576391687443842, -0.7576391687443842, -0.7897606710936372, -0.725517666395131, -0.7576391687443842, ...]
  petal_width float [-1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, -1.7147014356654704, ...]
  species string ["Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", "Iris-setosa", ...]
>

For-comprehensions works with all dataframe verbs. As we have seen above, for mutations we must return tuples as pair with the mutation name and its value. summarise works similarly. Note in both cases the name could also be generated dynamically. For example, to compute the mean per species, you could write:

iex> Explorer.Datasets.iris()
...> |> DF.group_by("species")
...> |> DF.summarise(
...>   for col <- across(), col.dtype == :float do
...>     {"#{col.name}_mean", mean(col)}
...>   end
...> )
#Explorer.DataFrame<
  Polars[3 x 5]
  species string ["Iris-setosa", "Iris-versicolor", "Iris-virginica"]
  sepal_length_mean float [5.005999999999999, 5.936, 6.587999999999998]
  sepal_width_mean float [3.4180000000000006, 2.7700000000000005, 2.9739999999999998]
  petal_length_mean float [1.464, 4.26, 5.552]
  petal_width_mean float [0.2439999999999999, 1.3259999999999998, 2.026]
>

arrange expects a list of columns to sort by, while for-comprehensions in filter generate a list of conditions, which are joined using and. For example, to filter all entries have both sepal and petal length above average, using a filter on the column name, one could write:

iex> iris = Explorer.Datasets.iris()
iex> DF.filter(iris,
...>   for col <- across(), String.ends_with?(col.name, "_length") do
...>     col > mean(col)
...>   end
...> )
#Explorer.DataFrame<
  Polars[70 x 5]
  sepal_length float [7.0, 6.4, 6.9, 6.5, 6.3, ...]
  sepal_width float [3.2, 3.2, 3.1, 2.8, 3.3, ...]
  petal_length float [4.7, 4.5, 4.9, 4.6, 4.7, ...]
  petal_width float [1.4, 1.5, 1.5, 1.5, 1.6, ...]
  species string ["Iris-versicolor", "Iris-versicolor", "Iris-versicolor", "Iris-versicolor", "Iris-versicolor", ...]
>

Do not mix comprehension and queries

The filter inside a for-comprehension works at the meta level: it can only filter columns based on their names and dtypes, but not on their values. For example, this code does not make any sense and it will fail to compile:

|> DF.filter(
  for col <- across(), col > mean(col) do
    col
  end
end)

Another way to think about it, the comprehensions traverse on the columns themselves, the contents inside the comprehension do-block traverse on the values inside the columns.

Implementation details

Queries simply become lazy dataframe operations at runtime. For example, the following query

Explorer.DataFrame.filter(df, nums > 2)

is equivalent to

Explorer.DataFrame.filter_with(df, fn df -> Explorer.Series.greater(df["nums"], 2) end)

This means that, whenever you want to generate queries programatically, you can fallback to the regular _with APIs.