update groupBy documentation

add docs for moveToTop + emphasize important groupBy use case

Author: koperagen

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt

@@ -17,6 +17,16 @@ import kotlin.reflect.KProperty
 
 // region DataFrame
 
+/**
+ *
+ * @param cols key columns; Column for grouping can be created inplace
+ *
+ * `df.groupBy { expr("columnName") { "someColumn"<Int>() + 15 } }`
+ *
+ * is equivalent to
+ *
+ * `df.add("columnName") { "someColumn"<Int>() + 15 }.groupBy("columnName")`
+ */
 public fun <T> DataFrame<T>.groupBy(moveToTop: Boolean = true, cols: ColumnsSelector<T, *>): GroupBy<T, T> =
     groupByImpl(moveToTop, cols)
 

core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Analyze.kt

@@ -577,7 +577,6 @@ class Analyze : TestBase() {
         df.groupBy { name }
         df.groupBy { city and name.lastName }
         df.groupBy { age / 10 named "ageDecade" }
-        df.groupBy { expr { name.firstName.length + name.lastName.length } named "nameLength" }
         // SampleEnd
     }
 
@@ -601,7 +600,6 @@ class Analyze : TestBase() {
 
         df.groupBy { age / 10 named "ageDecade" }
 
-        df.groupBy { expr { firstName().length + lastName().length } named "nameLength" }
         // SampleEnd
     }
 
@@ -612,10 +610,53 @@ class Analyze : TestBase() {
         df.groupBy("name")
         df.groupBy { "city" and "name"["lastName"] }
         df.groupBy { "age"<Int>() / 10 named "ageDecade" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_properties() {
+        // SampleStart
+        df.groupBy { expr { name.firstName.length + name.lastName.length } named "nameLength" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_accessors() {
+        // SampleStart
+        val name by columnGroup()
+        val lastName by name.column<String>()
+        val firstName by name.column<String>()
+
+        df.groupBy { expr { firstName().length + lastName().length } named "nameLength" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_strings() {
+        // SampleStart
         df.groupBy { expr { "name"["firstName"]<String>().length + "name"["lastName"]<String>().length } named "nameLength" }
         // SampleEnd
     }
 
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByMoveToTop() {
+        // SampleStart
+        df.groupBy(moveToTop = true) { name.lastName }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByMoveToTopFalse() {
+        // SampleStart
+        df.groupBy(moveToTop = false) { name.lastName }
+        // SampleEnd
+    }
+
     @Test
     @TransformDataFrameExpressions
     fun dataFrameToGroupBy() {

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt

@@ -17,6 +17,16 @@ import kotlin.reflect.KProperty
 
 // region DataFrame
 
+/**
+ *
+ * @param cols key columns; Column for grouping can be created inplace
+ *
+ * `df.groupBy { expr("columnName") { "someColumn"<Int>() + 15 } }`
+ *
+ * is equivalent to
+ *
+ * `df.add("columnName") { "someColumn"<Int>() + 15 }.groupBy("columnName")`
+ */
 public fun <T> DataFrame<T>.groupBy(moveToTop: Boolean = true, cols: ColumnsSelector<T, *>): GroupBy<T, T> =
     groupByImpl(moveToTop, cols)
 

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

@@ -577,7 +577,6 @@ class Analyze : TestBase() {
         df.groupBy { name }
         df.groupBy { city and name.lastName }
         df.groupBy { age / 10 named "ageDecade" }
-        df.groupBy { expr { name.firstName.length + name.lastName.length } named "nameLength" }
         // SampleEnd
     }
 
@@ -601,7 +600,6 @@ class Analyze : TestBase() {
 
         df.groupBy { age / 10 named "ageDecade" }
 
-        df.groupBy { expr { firstName().length + lastName().length } named "nameLength" }
         // SampleEnd
     }
 
@@ -612,10 +610,53 @@ class Analyze : TestBase() {
         df.groupBy("name")
         df.groupBy { "city" and "name"["lastName"] }
         df.groupBy { "age"<Int>() / 10 named "ageDecade" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_properties() {
+        // SampleStart
+        df.groupBy { expr { name.firstName.length + name.lastName.length } named "nameLength" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_accessors() {
+        // SampleStart
+        val name by columnGroup()
+        val lastName by name.column<String>()
+        val firstName by name.column<String>()
+
+        df.groupBy { expr { firstName().length + lastName().length } named "nameLength" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByExpr_strings() {
+        // SampleStart
         df.groupBy { expr { "name"["firstName"]<String>().length + "name"["lastName"]<String>().length } named "nameLength" }
         // SampleEnd
     }
 
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByMoveToTop() {
+        // SampleStart
+        df.groupBy(moveToTop = true) { name.lastName }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun groupByMoveToTopFalse() {
+        // SampleStart
+        df.groupBy(moveToTop = false) { name.lastName }
+        // SampleEnd
+    }
+
     @Test
     @TransformDataFrameExpressions
     fun dataFrameToGroupBy() {

docs/StardustDocs/snippets/org.jetbrains.kotlinx.dataframe.samples.api.Analyze.groupBy.html

@@ -188,11 +188,6 @@
 
 
 
-
-
-
-
-
             </style>
         </head>
         <body>
@@ -245,23 +240,6 @@
                                     <summary>Output GroupBy</summary>
                                      <table class="dataframe" id="df_19"></table>
 
-<p class="dataframe_description"></p>
-                                    </details>
-                            </details>
-                            <br>
-                            <details>
-                            <summary>df.groupBy { expr { name.firstName.length + name.lastName.length } named &quot;nameLength&quot; }</summary>
-                            
-                                    <details>
-                                    <summary>Input DataFrame: rowsCount = 7, columnsCount = 5</summary>
-                                     <table class="dataframe" id="df_24"></table>
-
-<p class="dataframe_description"></p>
-                                    </details>
-                                    <details>
-                                    <summary>Output GroupBy</summary>
-                                     <table class="dataframe" id="df_25"></table>
-
 <p class="dataframe_description"></p>
                                     </details>
                             </details>
@@ -816,73 +794,5 @@
 call_DataFrame(function() { DataFrame.renderTable(19) });
 
 
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice","Bob","Charlie","Charlie","Bob","Alice","Charlie"] }, 
-{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper","Dylan","Daniels","Chaplin","Marley","Wolf","Byrd"] }, 
-{ name: "<span title=\"name: DataRow<*>\">name</span>", children: [0, 1], rightAlign: false, values: ["<span class=\"formatted\" title=\"firstName: Alice\nlastName: Cooper\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Alice<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Cooper<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Bob\nlastName: Dylan\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Bob<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Dylan<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Daniels\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Dan<span class=\"structural\">...</span><span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Chaplin\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Cha<span class=\"structural\">...</span><span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Bob\nlastName: Marley\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Bob<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Marley<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Alice\nlastName: Wolf\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Alice<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Wolf<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Byrd\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Byrd<span class=\"structural\"> }</span></span>"] }, 
-{ name: "<span title=\"age: Int\">age</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">15</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">45</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">20</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">40</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">30</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">20</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">30</span></span>"] }, 
-{ name: "<span title=\"city: String?\">city</span>", children: [], rightAlign: false, values: ["London","Dubai","Moscow","Milan","Tokyo","<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>","Moscow"] }, 
-{ name: "<span title=\"weight: Int?\">weight</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">54</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">87</span></span>","<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>","<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">68</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">55</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">90</span></span>"] }, 
-{ name: "<span title=\"isHappy: Boolean\">isHappy</span>", children: [], rightAlign: false, values: ["true","true","false","true","true","false","true"] }, 
-], id: 24, rootId: 24, totalRows: 7 } ) });
-/*-->*/
-
-call_DataFrame(function() { DataFrame.renderTable(24) });
-
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"nameLength: Int\">nameLength</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">11</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">8</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">14</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">9</span></span>"] }, 
-{ name: "<span title=\"group: DataFrame<*>\">group</span>", children: [], rightAlign: false, values: [{ frameId: 26, value: "<b>DataFrame 2 x 5</b>" },{ frameId: 27, value: "<b>DataFrame 1 x 5</b>" },{ frameId: 28, value: "<b>DataFrame 2 x 5</b>" },{ frameId: 29, value: "<b>DataFrame 2 x 5</b>" }] }, 
-], id: 25, rootId: 25, totalRows: 4 } ) });
-/*-->*/
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice","Charlie"] }, 
-{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper","Byrd"] }, 
-{ name: "<span title=\"name: DataRow<*>\">name</span>", children: [0, 1], rightAlign: false, values: ["<span class=\"formatted\" title=\"firstName: Alice\nlastName: Cooper\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Alice<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Cooper<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Byrd\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Byrd<span class=\"structural\"> }</span></span>"] }, 
-{ name: "<span title=\"age: Int\">age</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">15</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">30</span></span>"] }, 
-{ name: "<span title=\"city: String\">city</span>", children: [], rightAlign: false, values: ["London","Moscow"] }, 
-{ name: "<span title=\"weight: Int\">weight</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">54</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">90</span></span>"] }, 
-{ name: "<span title=\"isHappy: Boolean\">isHappy</span>", children: [], rightAlign: false, values: ["true","true"] }, 
-], id: 26, rootId: 25, totalRows: 2 } ) });
-/*-->*/
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Bob"] }, 
-{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Dylan"] }, 
-{ name: "<span title=\"name: DataRow<*>\">name</span>", children: [0, 1], rightAlign: false, values: ["<span class=\"formatted\" title=\"firstName: Bob\nlastName: Dylan\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Bob<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Dylan<span class=\"structural\"> }</span></span>"] }, 
-{ name: "<span title=\"age: Int\">age</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">45</span></span>"] }, 
-{ name: "<span title=\"city: String\">city</span>", children: [], rightAlign: false, values: ["Dubai"] }, 
-{ name: "<span title=\"weight: Int\">weight</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">87</span></span>"] }, 
-{ name: "<span title=\"isHappy: Boolean\">isHappy</span>", children: [], rightAlign: false, values: ["true"] }, 
-], id: 27, rootId: 25, totalRows: 1 } ) });
-/*-->*/
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Charlie","Charlie"] }, 
-{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Daniels","Chaplin"] }, 
-{ name: "<span title=\"name: DataRow<*>\">name</span>", children: [0, 1], rightAlign: false, values: ["<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Daniels\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Dan<span class=\"structural\">...</span><span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Charlie\nlastName: Chaplin\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Charlie<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Cha<span class=\"structural\">...</span><span class=\"structural\"> }</span></span>"] }, 
-{ name: "<span title=\"age: Int\">age</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">20</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">40</span></span>"] }, 
-{ name: "<span title=\"city: String\">city</span>", children: [], rightAlign: false, values: ["Moscow","Milan"] }, 
-{ name: "<span title=\"weight: Int?\">weight</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>","<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>"] }, 
-{ name: "<span title=\"isHappy: Boolean\">isHappy</span>", children: [], rightAlign: false, values: ["false","true"] }, 
-], id: 28, rootId: 25, totalRows: 2 } ) });
-/*-->*/
-
-/*<!--*/
-call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Bob","Alice"] }, 
-{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Marley","Wolf"] }, 
-{ name: "<span title=\"name: DataRow<*>\">name</span>", children: [0, 1], rightAlign: false, values: ["<span class=\"formatted\" title=\"firstName: Bob\nlastName: Marley\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Bob<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Marley<span class=\"structural\"> }</span></span>","<span class=\"formatted\" title=\"firstName: Alice\nlastName: Wolf\"><span class=\"structural\">{ </span><span class=\"structural\">firstName: </span>Alice<span class=\"structural\">, </span><span class=\"structural\">lastName: </span>Wolf<span class=\"structural\"> }</span></span>"] }, 
-{ name: "<span title=\"age: Int\">age</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">30</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">20</span></span>"] }, 
-{ name: "<span title=\"city: String?\">city</span>", children: [], rightAlign: false, values: ["Tokyo","<span class=\"formatted\" title=\"\"><span class=\"null\">null</span></span>"] }, 
-{ name: "<span title=\"weight: Int\">weight</span>", children: [], rightAlign: true, values: ["<span class=\"formatted\" title=\"\"><span class=\"numbers\">68</span></span>","<span class=\"formatted\" title=\"\"><span class=\"numbers\">55</span></span>"] }, 
-{ name: "<span title=\"isHappy: Boolean\">isHappy</span>", children: [], rightAlign: false, values: ["true","false"] }, 
-], id: 29, rootId: 25, totalRows: 2 } ) });
-/*-->*/
-
-call_DataFrame(function() { DataFrame.renderTable(25) });
-
-
         </script>
         </html>