Column arithmetics review fixes (tests for functions on ColumnAccessor, expr usage)

Author: Allex-Nik

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnArithmetics.kt

@@ -22,16 +22,14 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `not on ColumnAccessor`() {
-        val isClosed = column<Boolean>("isClosed")
         val df = dataFrameOf("isClosed")(true, false)
-        df.getColumn { !isClosed } shouldBe columnOf(false, true).named("isClosed")
+        df.getColumn { !col<Boolean>("isClosed") } shouldBe columnOf(false, true).named("isClosed")
     }
 
     @Test
     fun `not on ColumnAccessor with null`() {
-        val isClosed = column<Boolean?>("isClosed")
         val df = dataFrameOf("isClosed")(true, null)
-        df.getColumn { !isClosed } shouldBe columnOf(false, null).named("isClosed")
+        df.getColumn { !col<Boolean?>("isClosed") } shouldBe columnOf(false, null).named("isClosed")
     }
 
     // endregion
@@ -59,11 +57,10 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `plus on ColumnAccessor of Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(1, 2, 3)
         val expected = columnOf(2, 3, 4).named("age")
-        df.getColumn { age + 1 } shouldBe expected
-        df.getColumn { 1 + age } shouldBe expected
+        df.getColumn { col<Int>("age") + 1 } shouldBe expected
+        df.getColumn { 1 + col<Int>("age") } shouldBe expected
     }
 
     @Test
@@ -123,10 +120,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `plus on ColumnAccessor with String`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(1, 2, 3)
         val expected = columnOf("11", "21", "31").named("age")
-        df.getColumn { age + "1" } shouldBe expected
+        df.getColumn { col<Int>("age") + "1" } shouldBe expected
     }
 
     // endregion
@@ -142,10 +138,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `ColumnAccessor of Int minus Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 3, 4)
         val expected = columnOf(1, 2, 3).named("age")
-        df.getColumn { age - 1 } shouldBe expected
+        df.getColumn { col<Int>("age") - 1 } shouldBe expected
     }
 
     @Test
@@ -210,10 +205,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `Int minus ColumnAccessor of Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 3, 4)
         val expected = columnOf(8, 7, 6).named("age")
-        df.getColumn { 10 - age } shouldBe expected
+        df.getColumn { 10 - col<Int>("age") } shouldBe expected
     }
 
     @Test
@@ -278,10 +272,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `unary minus on ColumnAccessor of Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(1, 2, 3)
         val expected = columnOf(-1, -2, -3).named("age")
-        df.getColumn { -age } shouldBe expected
+        df.getColumn { -col<Int>("age") } shouldBe expected
     }
 
     @Test
@@ -332,10 +325,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `times on ColumnAccessor of Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(1, 2, 3)
         val expected = columnOf(2, 4, 6).named("age")
-        df.getColumn { age * 2 } shouldBe expected
+        df.getColumn { col<Int>("age") * 2 } shouldBe expected
     }
 
     @Test
@@ -402,10 +394,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `ColumnAccessor of Int div Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 4, 6)
         val expected = columnOf(1, 2, 3).named("age")
-        df.getColumn { age / 2 } shouldBe expected
+        df.getColumn { col<Int>("age") / 2 } shouldBe expected
     }
 
     @Test
@@ -470,9 +461,8 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `ColumnAccessor of Int div zero`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 4, 6)
-        shouldThrow<ArithmeticException> { df.getColumn { age / 0 } }
+        shouldThrow<ArithmeticException> { df.getColumn { col<Int>("age") / 0 } }
     }
 
     @Test
@@ -527,10 +517,9 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `Int div ColumnAccessor of Int`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 4, 6)
         val expected = columnOf(6, 3, 2).named("age")
-        df.getColumn { 12 / age } shouldBe expected
+        df.getColumn { 12 / col<Int>("age") } shouldBe expected
     }
 
     @Test
@@ -590,9 +579,8 @@ class DataColumnArithmeticsTests {
 
     @Test
     fun `Int div ColumnAccessor with zero`() {
-        val age = column<Int>("age")
         val df = dataFrameOf("age")(2, 0, 6)
-        shouldThrow<ArithmeticException> { df.getColumn { 10 / age } }
+        shouldThrow<ArithmeticException> { df.getColumn { 10 / col<Int>("age") } }
     }
 
     @Test

docs/StardustDocs/topics/columnArithmetics.md

@@ -9,9 +9,35 @@ to each cell in a column, multiplying a column by a value, and comparing element
 ## When useful
 
 In most transformations, these column operations are usually not the preferred approach in Kotlin DataFrame, 
-because the library provides row-based APIs such as [`add`](add.md), [`update`](update.md), [`map`](map.md), and `expr`, 
+because the library provides row-based APIs such as [`add`](add.md), [`update`](update.md), and [`map`](map.md), 
 which are usually recommended.
 
+Also, the [`expr`](ColumnSelectors.md#expr-column-expression) function 
+is particularly useful in this context, as it allows you to write row expressions 
+inside the [`Columns Selection DSL`](ColumnSelectors.md).
+In other words, [`expr`](ColumnSelectors.md#expr-column-expression) works as an adapter 
+between a column selector and a row expression.
+
+For example,
+<!---FUN columnArithmetics_groupBy_without_expr-->
+
+```kotlin
+orders.groupBy { status + " orders"  }
+```
+
+<!---END-->
+is equivalent to
+<!---FUN columnArithmetics_groupBy_with_expr-->
+
+```kotlin
+orders.groupBy { expr("status") { status + " orders" } }
+```
+
+<!---END-->
+
+but in the first case, `status` is used as a [`DataColumn`](DataColumn.md) of String values, 
+and in the second case, `status` is treated as a String.
+
 However, column arithmetics might still be useful in some cases. 
 For example, when building temporary plotting expressions. 
 If distance is stored in meters, but you need to [`plot`](https://kotlin.github.io/kandy/welcome.html) it in kilometers, 

samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt

@@ -7,8 +7,10 @@ import org.jetbrains.kotlinx.dataframe.api.columnOf
 import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
 import org.jetbrains.kotlinx.dataframe.api.div
 import org.jetbrains.kotlinx.dataframe.api.eq
+import org.jetbrains.kotlinx.dataframe.api.expr
 import org.jetbrains.kotlinx.dataframe.api.format
 import org.jetbrains.kotlinx.dataframe.api.getColumnIndex
+import org.jetbrains.kotlinx.dataframe.api.groupBy
 import org.jetbrains.kotlinx.dataframe.api.gt
 import org.jetbrains.kotlinx.dataframe.api.linearBg
 import org.jetbrains.kotlinx.dataframe.api.lt
@@ -299,4 +301,30 @@ class Modify : DataFrameSampleHelper("operations", "modify") {
         orders.cost lt 20.0
         // SampleEnd
     }
+
+    @Test
+    fun columnArithmetics_groupBy_without_expr() {
+        val orders = dataFrameOf(
+            "id" to columnOf("1", "2", "3"),
+            "status" to columnOf("completed", "completed", "canceled"),
+            "cost" to columnOf(10.0, 200.0, 1500.0),
+        )
+
+        // SampleStart
+        orders.groupBy { status + " orders"  }
+        // SampleEnd
+    }
+
+    @Test
+    fun columnArithmetics_groupBy_with_expr() {
+        val orders = dataFrameOf(
+            "id" to columnOf("1", "2", "3"),
+            "status" to columnOf("completed", "completed", "canceled"),
+            "cost" to columnOf(10.0, 200.0, 1500.0),
+        )
+
+        // SampleStart
+        orders.groupBy { expr("status") { status + " orders" } }
+        // SampleEnd
+    }
 }