diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt index 472d9f214..8a7f1a8c7 100644 --- a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt +++ b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt @@ -120,7 +120,7 @@ internal interface AccessApi { * * For example: * ```kotlin - * val df = DataFrame.read("titanic.csv") + * val df /* : AnyFrame */ = DataFrame.read("titanic.csv") * ``` */ interface ExtensionPropertiesApi diff --git a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt index 8a70a02e8..429638923 100644 --- a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt +++ b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt @@ -142,7 +142,7 @@ class ApiLevels { @TransformDataFrameExpressions fun extensionProperties1() { // SampleStart - val df = DataFrame.read("titanic.csv") + val df /* : AnyFrame */ = DataFrame.read("titanic.csv") // SampleEnd } } diff --git a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt index 67e6ae038..7cd98f487 100644 --- a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt +++ b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt @@ -1,9 +1,12 @@ package org.jetbrains.kotlinx.dataframe.samples.api import org.jetbrains.kotlinx.dataframe.AnyFrame +import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.api.dataFrameOf +import org.jetbrains.kotlinx.dataframe.api.take import org.jetbrains.kotlinx.dataframe.explainer.WritersideFooter import org.jetbrains.kotlinx.dataframe.explainer.WritersideStyle +import org.jetbrains.kotlinx.dataframe.io.read import org.jetbrains.kotlinx.dataframe.io.toStandaloneHTML import org.junit.Test import java.io.File @@ -11,9 +14,10 @@ import java.io.File // To display code together with a table, we can use TransformDataFrameExpressions annotation together with korro // This class provides an ability to save only a table that can be embedded anywhere in the documentation class OtherSamples { + @Test fun extensionPropertiesApi1() { - val df = dataFrameOf("example")(123) + val df = DataFrame.read("../data/titanic.csv", delimiter = ';').take(5) writeTable(df, "extensionPropertiesApi1") } diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt index 8a70a02e8..429638923 100644 --- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt +++ b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/ApiLevels.kt @@ -142,7 +142,7 @@ class ApiLevels { @TransformDataFrameExpressions fun extensionProperties1() { // SampleStart - val df = DataFrame.read("titanic.csv") + val df /* : AnyFrame */ = DataFrame.read("titanic.csv") // SampleEnd } } diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt index 67e6ae038..c889e416d 100644 --- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt +++ b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt @@ -1,9 +1,11 @@ package org.jetbrains.kotlinx.dataframe.samples.api import org.jetbrains.kotlinx.dataframe.AnyFrame -import org.jetbrains.kotlinx.dataframe.api.dataFrameOf +import org.jetbrains.kotlinx.dataframe.DataFrame +import org.jetbrains.kotlinx.dataframe.api.take import org.jetbrains.kotlinx.dataframe.explainer.WritersideFooter import org.jetbrains.kotlinx.dataframe.explainer.WritersideStyle +import org.jetbrains.kotlinx.dataframe.io.read import org.jetbrains.kotlinx.dataframe.io.toStandaloneHTML import org.junit.Test import java.io.File @@ -11,10 +13,11 @@ import java.io.File // To display code together with a table, we can use TransformDataFrameExpressions annotation together with korro // This class provides an ability to save only a table that can be embedded anywhere in the documentation class OtherSamples { + @Test - fun extensionPropertiesApi1() { - val df = dataFrameOf("example")(123) - writeTable(df, "extensionPropertiesApi1") + fun example() { + val df = DataFrame.read("../data/titanic.csv", delimiter = ';').take(5) + // writeTable(df, "exampleName") } private fun writeTable(df: AnyFrame, name: String) { diff --git a/docs/StardustDocs/topics/apiLevels.md b/docs/StardustDocs/topics/apiLevels.md index 7551a8610..4f0756eef 100644 --- a/docs/StardustDocs/topics/apiLevels.md +++ b/docs/StardustDocs/topics/apiLevels.md @@ -28,7 +28,7 @@ Here's a list of all APIs in order of increasing safety. Columns accessed by the [`KProperty`](https://kotlinlang.org/docs/reflection.html#property-references) of some class. The name and type of column should match the name and type of property, respectively. -* [**Extension Properties API**](extensionPropertiesApi.md) +* [**Extension Properties API**](extensionPropertiesApi.md)
Extension access properties are generated based on the dataframe schema. The name and type of properties are inferred from the name and type of the corresponding columns. @@ -114,7 +114,7 @@ val passengers = DataFrame.read("titanic.csv") ```kotlin -val df = DataFrame.read("titanic.csv") +val df /* : AnyFrame */ = DataFrame.read("titanic.csv") ``` diff --git a/docs/StardustDocs/topics/extensionPropertiesApi.md b/docs/StardustDocs/topics/extensionPropertiesApi.md index 51a591e03..8bbd73b09 100644 --- a/docs/StardustDocs/topics/extensionPropertiesApi.md +++ b/docs/StardustDocs/topics/extensionPropertiesApi.md @@ -1,39 +1,24 @@ -[//]: # (title: Extension properties API) +[//]: # (title: Extension Properties API) -When [`DataFrame`](DataFrame.md) is used within Jupyter Notebooks or Datalore with Kotlin Kernel, -after every cell execution all new global variables of type DataFrame are analyzed and replaced -with typed [`DataFrame`](DataFrame.md) wrapper with auto-generated extension properties for data access: - - +Auto-generated extension properties are the safest and easiest way to access columns in a [`DataFrame`](DataFrame.md). +They are generated based on a [dataframe schema](schemas.md), +with the name and type of properties inferred from the name and type of the corresponding columns. +Having these, it allows you to work with your dataframe like: ```kotlin -val df = DataFrame.read("titanic.csv") +val peopleDf /* : DataFrame */ = DataFrame.read("people.csv").cast() +val nameColumn /* : DataColumn */ = peopleDf.name +val ageColumn /* : DataColumn */ = peopleDf.personData.age ``` - - - -Now data can be accessed by `.` member accessor - - - +and of course ```kotlin -df.add("lastName") { name.split(",").last() } - .dropNulls { age } - .filter { survived && home.endsWith("NY") && age in 10..20 } +peopleDf.add("lastName") { name.split(",").last() } + .dropNulls { personData.age } + .filter { survived && home.endsWith("NY") && personData.age in 10..20 } ``` - - -The `titanic.csv` file could be found [here](https://github.com/Kotlin/dataframe/blob/master/data/titanic.csv). - -In notebooks, extension properties are generated for [`DataSchema`](schemas.md) that is extracted from [`DataFrame`](DataFrame.md) -instance after REPL line execution. -After that [`DataFrame`](DataFrame.md) variable is typed with its own [`DataSchema`](schemas.md), so only valid extension properties corresponding to actual columns in DataFrame will be allowed by the compiler and suggested by completion. - -Extension properties can be generated in IntelliJ IDEA using the [Kotlin DataFrame Gradle plugin](schemasGradle.md#configuration). - - -In notebooks generated properties won't appear and be updated until the cell has been executed. It often means that you have to introduce new variable frequently to sync extension properties with actual schema - +To find out how to use this API in your environment, check out [Working with Data Schemas](schemas.md) +or jump straight to [Data Schemas in Gradle projects](schemasGradle.md), +or [Data Schemas in Jupyter notebooks](schemasJupyter.md).