Docs update & DynamicDataFrameBuilder

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

@@ -15,6 +15,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
 import org.jetbrains.kotlinx.dataframe.exceptions.DuplicateColumnNamesException
 import org.jetbrains.kotlinx.dataframe.exceptions.UnequalColumnSizesException
+import org.jetbrains.kotlinx.dataframe.impl.ColumnNameGenerator
 import org.jetbrains.kotlinx.dataframe.impl.DataFrameImpl
 import org.jetbrains.kotlinx.dataframe.impl.asList
 import org.jetbrains.kotlinx.dataframe.impl.columnName
@@ -23,6 +24,7 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.createColumn
 import org.jetbrains.kotlinx.dataframe.impl.columns.createComputedColumnReference
 import org.jetbrains.kotlinx.dataframe.impl.columns.forceResolve
 import org.jetbrains.kotlinx.dataframe.impl.columns.unbox
+import org.jetbrains.kotlinx.dataframe.impl.unnamedColumnPrefix
 import org.jetbrains.kotlinx.dataframe.size
 import kotlin.random.Random
 import kotlin.random.nextInt
@@ -348,6 +350,34 @@ public class DataFrameBuilder(private val header: List<String>) {
     public fun randomBoolean(nrow: Int): AnyFrame = fillNotNull(nrow) { Random.nextBoolean() }
 }
 
+/**
+ * Helper class for implementing operations when column names can be potentially duplicated.
+ * For example, operations involving multiple dataframes, computed columns or parsing some third-party data
+ */
+public class DynamicDataFrameBuilder {
+    private var cols: MutableList<AnyCol> = mutableListOf()
+    private val generator = ColumnNameGenerator()
+
+    public fun add(col: AnyCol): String {
+        val uniqueName = if (col.name().isEmpty()) {
+            generator.addUnique(unnamedColumnPrefix)
+        } else {
+            generator.addUnique(col.name())
+        }
+        val renamed = if (uniqueName != col.name()) {
+            col.rename(uniqueName)
+        } else {
+            col
+        }
+        cols.add(renamed)
+        return uniqueName
+    }
+
+    public fun toDataFrame(): AnyFrame {
+        return dataFrameOf(cols)
+    }
+}
+
 /**
  * Returns [DataFrame] with no rows and no columns.
  *

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/DataFrameImpl.kt

@@ -27,7 +27,7 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.resolveSingle
 import org.jetbrains.kotlinx.dataframe.io.renderToString
 import kotlin.reflect.KProperty
 
-private const val unnamedColumnPrefix = "untitled"
+internal const val unnamedColumnPrefix = "untitled"
 
 internal open class DataFrameImpl<T>(cols: List<AnyCol>, val nrow: Int) : DataFrame<T>, AggregatableInternal<T> {
 

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

@@ -0,0 +1,27 @@
+package org.jetbrains.kotlinx.dataframe.api
+
+import io.kotest.matchers.shouldBe
+import org.junit.Test
+
+class ConstructorsTests {
+
+    @Test
+    fun `untitled column naming`() {
+        val builder = DynamicDataFrameBuilder()
+        repeat(5) {
+            builder.add(columnOf(1, 2, 3))
+        }
+        builder.toDataFrame() shouldBe dataFrameOf(List(5) { columnOf(1, 2, 3) })
+    }
+
+    @Test
+    fun `duplicated name`() {
+        val builder = DynamicDataFrameBuilder()
+        val column by columnOf(1, 2, 3)
+        builder.add(column)
+        builder.add(column)
+        val df = builder.toDataFrame()
+        df.columnsCount() shouldBe 2
+        df.columnNames() shouldBe listOf(column.name(), "${column.name()}1")
+    }
+}

core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer/PluginCallbackProxy.kt

@@ -118,7 +118,7 @@ object PluginCallbackProxy : PluginCallback {
                             body =
                             """
                             <details>
-                            <summary>${expressions.joinToString(".") { it.source }
+                            <summary>${expressions.joinToSource()
                                 .also {
                                     if (it.length > 95) TODO("expression is too long ${it.length}. better to split sample in multiple snippets")
                                 }
@@ -155,50 +155,67 @@ object PluginCallbackProxy : PluginCallback {
         )
     }
 
+    private fun List<Expression>.joinToSource(): String =
+        joinToString(".") { it.source }
+
     private fun statementOutput(
         expressions: List<Expression>,
     ): DataFrameHtmlData {
         var data = DataFrameHtmlData()
-        if (expressions.size < 2) error("Sample without output or input (i.e. function returns some value)")
-        for ((i, expression) in expressions.withIndex()) {
-            when (i) {
-                0 -> {
-                    val table = convertToHTML(expression.df)
-                    val description = table.copy(
-                        body = """
+        val allow = setOf(
+            "toDataFrame", "peek(dataFrameOf(col), dataFrameOf(col))"
+        )
+        if (expressions.isEmpty()) {
+            error("No dataframe expressions in sample")
+        }
+        if (expressions.size == 1) {
+            if (allow.any { expressions[0].source.contains(it) }) {
+                val expression = expressions[0]
+                data += convertToHTML(expression.df)
+            } else {
+                error("${expressions.joinToSource()} Sample without output or input (i.e. function returns some value)")
+            }
+        } else {
+            for ((i, expression) in expressions.withIndex()) {
+                when (i) {
+                    0 -> {
+                        val table = convertToHTML(expression.df)
+                        val description = table.copy(
+                            body = """
                                     <details>
                                     <summary>Input ${convertToDescription(expression.df)}</summary>
                                      ${table.body}
                                     </details>
-                        """.trimIndent()
-                    )
-                    data += description
-                }
+                            """.trimIndent()
+                        )
+                        data += description
+                    }
 
-                expressions.lastIndex -> {
-                    val table = convertToHTML(expression.df)
-                    val description = table.copy(
-                        body = """
+                    expressions.lastIndex -> {
+                        val table = convertToHTML(expression.df)
+                        val description = table.copy(
+                            body = """
                                     <details>
                                     <summary>Output ${convertToDescription(expression.df)}</summary>
                                      ${table.body}
                                     </details>
-                        """.trimIndent()
-                    )
-                    data += description
-                }
+                            """.trimIndent()
+                        )
+                        data += description
+                    }
 
-                else -> {
-                    val table = convertToHTML(expression.df)
-                    val description = table.copy(
-                        body = """
+                    else -> {
+                        val table = convertToHTML(expression.df)
+                        val description = table.copy(
+                            body = """
                                     <details>
                                     <summary>Step $i: ${convertToDescription(expression.df)}</summary>
                                      ${table.body}
                                     </details>
-                        """.trimIndent()
-                    )
-                    data += description
+                            """.trimIndent()
+                        )
+                        data += description
+                    }
                 }
             }
         }

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

@@ -1,7 +1,9 @@
 package org.jetbrains.kotlinx.dataframe.samples.api
 
 import io.kotest.matchers.shouldBe
+import org.jetbrains.kotlinx.dataframe.AnyFrame
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.api.DynamicDataFrameBuilder
 import org.jetbrains.kotlinx.dataframe.api.Infer
 import org.jetbrains.kotlinx.dataframe.api.ValueProperty
 import org.jetbrains.kotlinx.dataframe.api.add
@@ -431,4 +433,21 @@ class Create : TestBase() {
         df["scores"].kind shouldBe ColumnKind.Frame
         df["summary"]["min score"].values() shouldBe listOf(3, 5)
     }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun duplicatedColumns() {
+        // SampleStart
+        fun peek(vararg dataframes: AnyFrame): AnyFrame {
+            val builder = DynamicDataFrameBuilder()
+            for (df in dataframes) {
+                df.columns().firstOrNull()?.let { builder.add(it) }
+            }
+            return builder.toDataFrame()
+        }
+
+        val col by columnOf(1, 2, 3)
+        peek(dataFrameOf(col), dataFrameOf(col))
+        // SampleEnd
+    }
 }

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

@@ -469,7 +469,7 @@ class Modify : TestBase() {
     @TransformDataFrameExpressions
     fun splitInplace_properties() {
         // SampleStart
-        df.split { name.firstName }.by { it.chars().toList() }.inplace()
+        df.split { name.firstName }.by { it.asIterable() }.inplace()
         // SampleEnd
     }
 
@@ -480,25 +480,23 @@ class Modify : TestBase() {
         val name by columnGroup()
         val firstName by name.column<String>()
 
-        df.split { firstName }.by { it.chars().toList() }.inplace()
+        df.split { firstName }.by { it.asIterable() }.inplace()
         // SampleEnd
     }
 
     @Test
     @TransformDataFrameExpressions
     fun splitInplace_strings() {
         // SampleStart
-        df.split { "name"["firstName"]<String>() }.by { it.chars().toList() }.inplace()
+        df.split { "name"["firstName"]<String>() }.by { it.asIterable() }.inplace()
         // SampleEnd
     }
 
     @Test
     @TransformDataFrameExpressions
     fun split_properties() {
         // SampleStart
-        df.split { name }.by { it.values() }.into("nameParts")
-
-        df.split { name.lastName }.by(" ").default("").inward { "word$it" }
+        df.split { name.lastName }.by { it.asIterable() }.into("char1", "char2")
         // SampleEnd
     }
 
@@ -509,28 +507,69 @@ class Modify : TestBase() {
         val name by columnGroup()
         val lastName by name.column<String>()
 
-        df.split { name }.by { it.values() }.into("nameParts")
-
-        df.split { lastName }.by(" ").default("").inward { "word$it" }
+        df.split { lastName }.by { it.asIterable() }.into("char1", "char2")
         // SampleEnd
     }
 
     @Test
     @TransformDataFrameExpressions
     fun split_strings() {
         // SampleStart
-        df.split { name }.by { it.values() }.into("nameParts")
+        df.split { "name"["lastName"]<String>() }.by { it.asIterable() }.into("char1", "char2")
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun split1_properties() {
+        // SampleStart
+        df.split { name.lastName }
+            .by { it.asIterable() }.default(' ')
+            .inward { "char$it" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun split1_accessors() {
+        // SampleStart
+        val name by columnGroup()
+        val lastName by name.column<String>()
 
-        df.split { "name"["lastName"] }.by(" ").default("").inward { "word$it" }
+        df.split { lastName }
+            .by { it.asIterable() }.default(' ')
+            .inward { "char$it" }
+        // SampleEnd
+    }
+
+    @Test
+    @TransformDataFrameExpressions
+    fun split1_strings() {
+        // SampleStart
+        df.split { "name"["lastName"]<String>() }
+            .by { it.asIterable() }.default(' ')
+            .inward { "char$it" }
         // SampleEnd
     }
 
     @Test
     @TransformDataFrameExpressions
     fun splitRegex() {
-        val merged = df.merge { name.lastName and name.firstName }.by { it[0] + " (" + it[1] + ")" }.into("name")
-        val name by column<String>()
         // SampleStart
+        val merged = df.merge { name.lastName and name.firstName }
+            .by { it[0] + " (" + it[1] + ")" }
+            .into("name")
+        // SampleEnd
+    }
+
+    private val merged = df.merge { name.lastName and name.firstName }.by { it[0] + " (" + it[1] + ")" }.into("name")
+
+    @Test
+    @TransformDataFrameExpressions
+    fun splitRegex1() {
+        // SampleStart
+        val name by column<String>()
+
         merged.split { name }
             .match("""(.*) \((.*)\)""")
             .inward("firstName", "lastName")
@@ -562,7 +601,7 @@ class Modify : TestBase() {
     @TransformDataFrameExpressions
     fun splitIntoRows_properties() {
         // SampleStart
-        df.split { name.firstName }.by { it.chars().toList() }.intoRows()
+        df.split { name.firstName }.by { it.asIterable() }.intoRows()
 
         df.split { name }.by { it.values() }.intoRows()
         // SampleEnd
@@ -575,7 +614,7 @@ class Modify : TestBase() {
         val name by columnGroup()
         val firstName by name.column<String>()
 
-        df.split { firstName }.by { it.chars().toList() }.intoRows()
+        df.split { firstName }.by { it.asIterable() }.intoRows()
 
         df.split { name }.by { it.values() }.intoRows()
         // SampleEnd
@@ -585,7 +624,7 @@ class Modify : TestBase() {
     @TransformDataFrameExpressions
     fun splitIntoRows_strings() {
         // SampleStart
-        df.split { "name"["firstName"]<String>() }.by { it.chars().toList() }.intoRows()
+        df.split { "name"["firstName"]<String>() }.by { it.asIterable() }.intoRows()
 
         df.split { colGroup("name") }.by { it.values() }.intoRows()
         // SampleEnd