Skip to content

Remove deprecated and unused access api examples and migrate multi-column add/map #1649

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
koperagen wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Remove deprecated and unused access api examples and migrate multi-column add/map #1649

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
335dcb5
Remove deprecated and unused access api examples from ApiLevels.kt an…
koperagen Dec 18, 2025
42da378
Remove deprecated and unused access api examples from Access.kt and M…
koperagen Dec 18, 2025
173881e
Update deprecated addAll and into usages in Modify.kt
koperagen Dec 18, 2025
6e9f176
Update examples for multi-column add and map
koperagen Dec 18, 2025
c8d491a
Remove unused API example from Access.kt and Create.kt
koperagen Dec 18, 2025
4d44edf
Migrate deprecated API usages in Schemas.kt
koperagen Dec 18, 2025
60af2a7
Remove direct links to deprecated access APIs
koperagen Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 7 additions & 41 deletions ...erated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,8 @@ import org.jetbrains.kotlinx.dataframe.documentation.AccessApi.AnyApiLinks
* or deleted while wrangling. Kotlin, in contrast, is a statically typed language and all types are defined and verified
* ahead of execution. That's why creating a flexible, handy, and, at the same time, safe API to a dataframe is tricky.
*
* In `Kotlin DataFrame` we provide four different ways to access columns, and, while they're essentially different, they
* look pretty similar in the data wrangling DSL. These include:
* In `Kotlin DataFrame` we provide two different ways to access columns:
* - [Extension Properties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ExtensionPropertiesApi]
* - [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
* - [Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]
* - [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]
*
* For more information: [See Access APIs on the documentation website.](https://kotlin.github.io/dataframe/apilevels.html)
Expand All @@ -23,8 +20,6 @@ internal interface AccessApi {

/**
* - [Extension Properties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ExtensionPropertiesApi]
* - [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
* - [Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]
* - [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]
*/
interface AnyApiLinks
Expand Down Expand Up @@ -59,20 +54,6 @@ internal interface AccessApi {
* a variable that represents its name and type.
*
* For more information: [See Column Accessors API on the documentation website.](https://kotlin.github.io/dataframe/columnaccessorsapi.html)
*
* For example:
* ```kotlin
* val survived by column<Boolean>()
* val home by column<String>()
* val age by column<Int?>()
* val name by column<String>()
* val lastName by column<String>()
*
* DataFrame.read("titanic.csv")
* .add(lastName) { name().split(",").last() }
* .dropNulls { age }
* .filter { survived() && home().endsWith("NY") && age()!! in 10..20 }
* ```
*/
interface ColumnAccessorsApi

Expand All @@ -87,26 +68,6 @@ internal interface AccessApi {
* The name and type of column should match the name and type of property, respectively.
*
* For more information: [See KProperties API on the documentation website.](https://kotlin.github.io/dataframe/kpropertiesapi.html)
*
* For example:
* ```kotlin
* data class Passenger(
* val survived: Boolean,
* val home: String,
* val age: Int,
* val lastName: String
* )
*
* val passengers = DataFrame.read("titanic.csv")
* .add(Passenger::lastName) { "name"<String>().split(",").last() }
* .dropNulls(Passenger::age)
* .filter {
* it[Passenger::survived] &&
* it[Passenger::home].endsWith("NY") &&
* it[Passenger::age] in 10..20
* }
* .toListOf<Passenger>()
* ```
*/
interface KPropertiesApi

Expand All @@ -120,10 +81,15 @@ internal interface AccessApi {
*
* For more information: [See Extension Properties API on the documentation website.](https://kotlin.github.io/dataframe/extensionpropertiesapi.html)
*
* For example:
* For example, in notebooks extension properties are generated from runtime data after the cell is executed:
* ```kotlin
* val df /* : AnyFrame */ = DataFrame.read("titanic.csv")
* ```
* ```kotlin
* df.add("lastName") { name.split(",").last() }
* .dropNulls { age }
* .filter { survived && home.endsWith("NY") && age in 10..20 }
* ```
*/
interface ExtensionPropertiesApi

Expand Down
14 changes: 3 additions & 11 deletions core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ import org.jetbrains.kotlinx.dataframe.documentation.AccessApi.AnyApiLinks
* or deleted while wrangling. Kotlin, in contrast, is a statically typed language and all types are defined and verified
* ahead of execution. That's why creating a flexible, handy, and, at the same time, safe API to a dataframe is tricky.
*
* In `Kotlin DataFrame` we provide four different ways to access columns, and, while they're essentially different, they
* look pretty similar in the data wrangling DSL. These include:
* In `Kotlin DataFrame` we provide two different ways to access columns:
* @include [AnyApiLinks]
*
* For more information: {@include [DocumentationUrls.AccessApis]}
Expand All @@ -21,8 +20,6 @@ internal interface AccessApi {

/**
* - {@include [ExtensionPropertiesApiLink]}
* - {@include [KPropertiesApiLink]}
* - {@include [ColumnAccessorsApiLink]}
* - {@include [StringApiLink]}
*/
interface AnyApiLinks
Expand All @@ -48,9 +45,6 @@ internal interface AccessApi {
* a variable that represents its name and type.
*
* For more information: {@include [DocumentationUrls.AccessApis.ColumnAccessorsApi]}
*
* For example: {@comment This works if you include the test module when running KoDEx}
* @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.accessors3]
*/
interface ColumnAccessorsApi

Expand All @@ -65,9 +59,6 @@ internal interface AccessApi {
* The name and type of column should match the name and type of property, respectively.
*
* For more information: {@include [DocumentationUrls.AccessApis.KPropertiesApi]}
*
* For example: {@comment This works if you include the test module when running KoDEx}
* @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.kproperties1]
*/
interface KPropertiesApi

Expand All @@ -81,8 +72,9 @@ internal interface AccessApi {
*
* For more information: {@include [DocumentationUrls.AccessApis.ExtensionPropertiesApi]}
*
* For example: {@comment This works if you include the test module when running KoDEx}
* For example, in notebooks extension properties are generated from runtime data after the cell is executed: {@comment This works if you include the test module when running KoDEx}
Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can put the @comment on the next line, if you write it without {}, there should be no newline in between executed: and @sample

* @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties1]
* @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties2]
*/
interface ExtensionPropertiesApi

Expand Down
78 changes: 1 addition & 77 deletions core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Access.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,7 @@ import org.jetbrains.kotlinx.dataframe.api.add
import org.jetbrains.kotlinx.dataframe.api.after
import org.jetbrains.kotlinx.dataframe.api.chunked
import org.jetbrains.kotlinx.dataframe.api.colsOf
import org.jetbrains.kotlinx.dataframe.api.column
import org.jetbrains.kotlinx.dataframe.api.columnOf
import org.jetbrains.kotlinx.dataframe.api.countDistinct
import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
import org.jetbrains.kotlinx.dataframe.api.distinct
import org.jetbrains.kotlinx.dataframe.api.distinctBy
import org.jetbrains.kotlinx.dataframe.api.drop
Expand Down Expand Up @@ -37,13 +34,11 @@ import org.jetbrains.kotlinx.dataframe.api.maxByOrNull
import org.jetbrains.kotlinx.dataframe.api.minBy
import org.jetbrains.kotlinx.dataframe.api.minus
import org.jetbrains.kotlinx.dataframe.api.move
import org.jetbrains.kotlinx.dataframe.api.named
import org.jetbrains.kotlinx.dataframe.api.notNull
import org.jetbrains.kotlinx.dataframe.api.remove
import org.jetbrains.kotlinx.dataframe.api.rows
import org.jetbrains.kotlinx.dataframe.api.select
import org.jetbrains.kotlinx.dataframe.api.single
import org.jetbrains.kotlinx.dataframe.api.sortBy
import org.jetbrains.kotlinx.dataframe.api.take
import org.jetbrains.kotlinx.dataframe.api.takeLast
import org.jetbrains.kotlinx.dataframe.api.takeWhile
Expand Down Expand Up @@ -407,37 +402,6 @@ class Access : TestBase() {
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun namedAndRenameCol() {
// SampleStart
val unnamedCol = columnOf("Alice", "Bob")
val colRename = unnamedCol.rename("name")
val colNamed = columnOf("Alice", "Bob") named "name"
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun namedColumnWithoutValues() {
// SampleStart
val name by column<String>()
val col = column<String>("name")
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun colRefForTypedAccess() {
val df = dataFrameOf("name")("Alice", "Bob")
val name by column<String>()
val col = column<String>("name")
// SampleStart
df.filter { it[name].startsWith("A") }
df.sortBy { col }
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun iterableApi() {
Expand Down Expand Up @@ -570,41 +534,6 @@ class Access : TestBase() {
// SampleEnd
}

@Test
fun columnSelectors_kproperties() {
// SampleStart
// by column name
df.select { it[Person::name] }
df.select { (Person::name)() }
df.select { col(Person::name) }

// by column path
df.select { it[Person::name][Name::firstName] }
df.select { Person::name[Name::firstName] }

// with a new name
df.select { Person::name named "Full Name" }

// converted
df.select { Person::name[Name::firstName].map { it.lowercase() } }

// column arithmetics
df.select { 2021 - (Person::age)() }

// two columns
df.select { Person::name and Person::age }

// range of columns
df.select { Person::name..Person::age }

// all columns of ColumnGroup
df.select { Person::name.allCols() }

// traversal of columns at any depth from here excluding ColumnGroups
df.select { Person::name.colsAtAnyDepth().filter { !it.isColumnGroup() } }
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun columnSelectors_strings() {
Expand Down Expand Up @@ -688,19 +617,14 @@ class Access : TestBase() {
colGroup("name").lastCol { it.name().endsWith("Name") }
}

// find the single column inside a column group satisfying the condition
df.select {
Person::name.singleCol { it.name().startsWith("first") }
}

// traversal of columns at any depth from here excluding ColumnGroups
df.select { colsAtAnyDepth().filter { !it.isColumnGroup() } }

// traversal of columns at any depth from here including ColumnGroups
df.select { colsAtAnyDepth() }

// traversal of columns at any depth with condition
df.select { colsAtAnyDepth().filter() { it.name().contains(":") } }
df.select { colsAtAnyDepth().filter { it.name().contains(":") } }

// traversal of columns at any depth to find columns of given type
df.select { colsAtAnyDepth().colsOf<String>() }
Expand Down
27 changes: 0 additions & 27 deletions core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Analyze.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ import org.jetbrains.kotlinx.dataframe.api.asGroupBy
import org.jetbrains.kotlinx.dataframe.api.asNumbers
import org.jetbrains.kotlinx.dataframe.api.cast
import org.jetbrains.kotlinx.dataframe.api.colsOf
import org.jetbrains.kotlinx.dataframe.api.column
import org.jetbrains.kotlinx.dataframe.api.columnGroup
import org.jetbrains.kotlinx.dataframe.api.columnOf
import org.jetbrains.kotlinx.dataframe.api.concat
import org.jetbrains.kotlinx.dataframe.api.count
Expand Down Expand Up @@ -445,31 +443,6 @@ class Analyze : TestBase() {
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun columnsFor_accessors() {
// SampleStart
val name by columnGroup()
val firstName by name.column<String>()
val lastName by name.column<String>()
val age by column<Int>()
val weight by column<Int?>()

df.minFor { colsOf<Int>() }

df.maxFor { firstName and age }
// or
df.maxFor(firstName, lastName)

df.sumFor { age and weight }
// or
df.sum(age, weight)

df.mean { cols(1, 3).asNumbers() }
df.median<_, String> { name.allCols().cast() }
// SampleEnd
}

@Test
@TransformDataFrameExpressions
fun columnsFor_strings() {
Expand Down
Loading