Skip to content

Commit 165e755

Browse files
JolanrensenJolanrensen
authored
Merge pull request #1441 from Kotlin/beta3-docs-example-bumps
readying examples and docs for Beta3
2 parents 4f36517 + fdb4a5d commit 165e755

File tree

25 files changed

+606801
-16701
lines changed

25 files changed

+606801
-16701
lines changed

‎README.md‎

Lines changed: 65 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Kotlin DataFrame: typesafe in-memory structured data processing for JVM
2+
23
[![JetBrains incubator project](https://jb.gg/badges/incubator.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
34
[![Kotlin component beta stability](https://img.shields.io/badge/project-beta-kotlin.svg?colorA=555555&colorB=DB3683&label=&logo=kotlin&logoColor=ffffff&logoWidth=10)](https://kotlinlang.org/docs/components-stability.html)
45
[![Kotlin](https://img.shields.io/badge/kotlin-2.0.20-blue.svg?logo=kotlin)](http://kotlinlang.org)
@@ -8,29 +9,37 @@
89
[![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
910
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Kotlin/dataframe/HEAD)
1011

11-
Kotlin DataFrame aims to reconcile Kotlin's static typing with the dynamic nature of data by utilizing both the full power of the Kotlin language and the opportunities provided by intermittent code execution in Jupyter notebooks and REPL.
12+
Kotlin DataFrame aims to reconcile Kotlin's static typing with the dynamic nature of data by utilizing both the full
13+
power of the Kotlin language and the opportunities provided by intermittent code execution in Jupyter notebooks and
14+
REPL.
1215

1316
* **Hierarchical** — represents hierarchical data structures, such as JSON or a tree of JVM objects.
1417
* **Functional** — the data processing pipeline is organized in a chain of `DataFrame` transformation operations.
15-
* **Immutable** — every operation returns a new instance of `DataFrame` reusing underlying storage wherever it's possible.
18+
* **Immutable** — every operation returns a new instance of `DataFrame` reusing underlying storage wherever it's
19+
possible.
1620
* **Readable** — data transformation operations are defined in DSL close to natural language.
1721
* **Practical** — provides simple solutions for common problems and the ability to perform complex tasks.
1822
* **Minimalistic** — simple, yet powerful data model of three column kinds.
19-
* **Interoperable** — convertable with Kotlin data classes and collections. This also means conversion to/from other libraries' data structures is usually quite straightforward!
23+
* **Interoperable** — convertable with Kotlin data classes and collections. This also means conversion to/from other
24+
libraries' data structures is usually quite straightforward!
2025
* **Generic** — can store objects of any type, not only numbers or strings.
21-
* **Typesafe** — on-the-fly [generation of extension properties](https://kotlin.github.io/dataframe/extensionpropertiesapi.html) for type safe data access with Kotlin-style care for null safety.
22-
* **Polymorphic** — type compatibility derives from column schema compatibility. You can define a function that requires a special subset of columns in a dataframe but doesn't care about other columns.
26+
* **Typesafe** —
27+
on-the-fly [generation of extension properties](https://kotlin.github.io/dataframe/extensionpropertiesapi.html) for
28+
type safe data access with Kotlin-style care for null safety.
29+
* **Polymorphic** — type compatibility derives from column schema compatibility. You can define a function that requires
30+
a special subset of columns in a dataframe but doesn't care about other columns.
2331
In notebooks this works out-of-the-box. In ordinary projects this requires casting (for now).
2432

25-
Integrates with [Kotlin Notebook](https://kotlinlang.org/docs/kotlin-notebook-overview.html).
26-
Inspired by [krangl](https://github.com/holgerbrandl/krangl), Kotlin Collections and [pandas](https://pandas.pydata.org/)
33+
Integrates with [Kotlin Notebook](https://kotlinlang.org/docs/kotlin-notebook-overview.html).
34+
Inspired by [krangl](https://github.com/holgerbrandl/krangl), Kotlin Collections
35+
and [pandas](https://pandas.pydata.org/)
2736

2837
## 🚀 Quickstart
2938

3039
Looking for a fast and simple way to learn the basics?
3140
Get started in minutes with our [Quickstart Guide](https://kotlin.github.io/dataframe/quickstart.html).
3241

33-
It walks you through the core features of Kotlin DataFrame with minimal setup and clear examples
42+
It walks you through the core features of Kotlin DataFrame with minimal setup and clear examples
3443
— perfect for getting up to speed in just a few minutes.
3544

3645
[![quickstart_preview](docs/StardustDocs/images/guides/quickstart_preview.png)](https://kotlin.github.io/dataframe/quickstart.html)
@@ -54,7 +63,7 @@ You could find the following articles there:
5463

5564
### What's new
5665

57-
1.0.0-Beta2: [Release notes](https://github.com/Kotlin/dataframe/releases/tag/v1.0.0-Beta2)
66+
1.0.0-Beta3: [Release notes](https://github.com/Kotlin/dataframe/releases/tag/v1.0.0-Beta3)
5867

5968
Check out this [notebook with new features](examples/notebooks/feature_overviews/0.15/new_features.ipynb) in v0.15.
6069

@@ -66,7 +75,7 @@ Check out this [notebook with new features](examples/notebooks/feature_overviews
6675
### Kotlin Notebook
6776

6877
You can use Kotlin DataFrame in [Kotlin Notebook](https://kotlinlang.org/docs/kotlin-notebook-overview.html),
69-
or other interactive environment with [Kotlin Jupyter Kernel](https://github.com/Kotlin/kotlin-jupyter) support,
78+
or other interactive environment with [Kotlin Jupyter Kernel](https://github.com/Kotlin/kotlin-jupyter) support,
7079
such as [Datalore](https://datalore.jetbrains.com/),
7180
and [Jupyter Notebook](https://jupyter.org/).
7281

@@ -90,7 +99,7 @@ Or manually specify the version:
9099
%use dataframe($dataframe_version)
91100
```
92101

93-
Refer to the
102+
Refer to the
94103
[Get started with Kotlin DataFrame in Kotlin Notebook](https://kotlin.github.io/dataframe/gettingstartedkotlinnotebook.html)
95104
for details.
96105

@@ -100,7 +109,7 @@ Add dependencies in the build.gradle.kts script:
100109

101110
```kotlin
102111
dependencies {
103-
implementation("org.jetbrains.kotlinx:dataframe:1.0.0-Beta2")
112+
implementation("org.jetbrains.kotlinx:dataframe:1.0.0-Beta3")
104113
}
105114
```
106115

@@ -115,7 +124,7 @@ repositories {
115124
Refer to the
116125
[Get started with Kotlin DataFrame on Gradle](https://kotlin.github.io/dataframe/gettingstartedgradle.html)
117126
for details.
118-
Also, check out the [custom setup page](https://kotlin.github.io/dataframe/gettingstartedgradleadvanced.html)
127+
Also, check out the [custom setup page](https://kotlin.github.io/dataframe/gettingstartedgradleadvanced.html)
119128
if you don't need some formats as dependencies,
120129
for Groovy, and for configurations specific to Android projects.
121130

@@ -124,32 +133,32 @@ for Groovy, and for configurations specific to Android projects.
124133
This example of Kotlin DataFrame code with
125134
the [Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) enabled.
126135
See [the full project](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-example).
127-
See also
136+
See also
128137
[this example in Kotlin Notebook](https://github.com/Kotlin/dataframe/tree/master/examples/notebooks/readme_example.ipynb).
129138

130139
```kotlin
131140
val df = DataFrame
132-
// Read DataFrame from the CSV file.
133-
.readCsv("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
134-
// And convert it to match the `Repositories` schema.
135-
.convertTo<Repositories>()
141+
// Read DataFrame from the CSV file.
142+
.readCsv("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
143+
// And convert it to match the `Repositories` schema.
144+
.convertTo<Repositories>()
136145

137146
// Update the DataFrame.
138147
val reposUpdated = repos
139-
// Rename columns to CamelCase.
140-
.renameToCamelCase()
141-
// Rename "stargazersCount" column to "stars".
142-
.rename { stargazersCount }.into("stars")
143-
// Filter by the number of stars:
144-
.filter { stars > 50 }
145-
// Convert values in the "topic" column (which were `String` initially)
146-
// to the list of topics.
147-
.convert { topics }.with {
148-
val inner = it.removeSurrounding("[", "]")
148+
// Rename columns to CamelCase.
149+
.renameToCamelCase()
150+
// Rename "stargazersCount" column to "stars".
151+
.rename { stargazersCount }.into("stars")
152+
// Filter by the number of stars:
153+
.filter { stars > 50 }
154+
// Convert values in the "topic" column (which were `String` initially)
155+
// to the list of topics.
156+
.convert { topics }.with {
157+
val inner = it.removeSurrounding("[", "]")
149158
if (inner.isEmpty()) emptyList() else inner.split(',').map(String::trim)
150-
}
151-
// Add a new column with the number of topics.
152-
.add("topicCount") { topics.size }
159+
}
160+
// Add a new column with the number of topics.
161+
.add("topicCount") { topics.size }
153162

154163
// Write the updated DataFrame to a CSV file.
155164
reposUpdated.writeCsv("jetbrains_repositories_new.csv")
@@ -158,39 +167,45 @@ reposUpdated.writeCsv("jetbrains_repositories_new.csv")
158167
Explore [**more examples here**](https://kotlin.github.io/dataframe/guides-and-examples.html).
159168

160169
## Data model
170+
161171
* `DataFrame` is a list of columns with equal sizes and distinct names.
162172
* `DataColumn` is a named list of values. Can be one of three kinds:
163-
* `ValueColumn` — contains data
164-
* `ColumnGroup` — contains columns
165-
* `FrameColumn` — contains dataframes
173+
* `ValueColumn` — contains data
174+
* `ColumnGroup` — contains columns
175+
* `FrameColumn` — contains dataframes
166176

167177
## Visualizations
168178

169-
[Kandy](https://kotlin.github.io/kandy/welcome.html) plotting library provides seamless visualizations
179+
[Kandy](https://kotlin.github.io/kandy/welcome.html) plotting library provides seamless visualizations
170180
for your dataframes.
171181

172182
![kandy_preview](docs/StardustDocs/images/guides/kandy_gallery_preview.png)
173183

174184
## Kotlin, Kotlin Jupyter, Arrow, and JDK versions
175185

176-
This table shows the mapping between main library component versions and minimum supported Java versions.
177-
178-
| Kotlin DataFrame Version | Minimum Java Version | Kotlin Version | Kotlin Jupyter Version | Apache Arrow version |
179-
|--------------------------|----------------------|----------------|------------------------|----------------------|
180-
| 0.10.0 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 |
181-
| 0.10.1 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 |
182-
| 0.11.0 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 |
183-
| 0.11.1 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 |
184-
| 0.12.0 | 8 | 1.9.0 | 0.11.0-358 | 11.0.0 |
185-
| 0.12.1 | 8 | 1.9.0 | 0.11.0-358 | 11.0.0 |
186-
| 0.13.1 | 8 | 1.9.22 | 0.12.0-139 | 15.0.0 |
187-
| 0.14.1 | 8 | 2.0.20 | 0.12.0-139 | 17.0.0 |
188-
| 0.15.0 | 8 | 2.0.20 | 0.12.0-139 | 18.1.0 |
189-
| 1.0.0-Beta2 | 8 / 11 | 2.0.20 | 0.12.0-383 | 18.1.0 |
186+
This table shows the mapping between main library component versions and minimum supported Java versions, along with
187+
other recommended versions.
188+
189+
| Kotlin DataFrame Version | Minimum Java Version | Kotlin Version | Kotlin Jupyter Version | Apache Arrow Version | Compiler Plugin Version | Compatible Kandy version |
190+
|--------------------------|----------------------|----------------|------------------------|----------------------|-------------------------|--------------------------|
191+
| 0.10.0 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 | | |
192+
| 0.10.1 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 | | |
193+
| 0.11.0 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 | | |
194+
| 0.11.1 | 8 | 1.8.20 | 0.11.0-358 | 11.0.0 | | |
195+
| 0.12.0 | 8 | 1.9.0 | 0.11.0-358 | 11.0.0 | | |
196+
| 0.12.1 | 8 | 1.9.0 | 0.11.0-358 | 11.0.0 | | |
197+
| 0.13.1 | 8 | 1.9.22 | 0.12.0-139 | 15.0.0 | | |
198+
| 0.14.1 | 8 | 2.0.20 | 0.12.0-139 | 17.0.0 | | |
199+
| 0.15.0 | 8 | 2.0.20 | 0.12.0-139 | 18.1.0 | | 0.8.0 |
200+
| 1.0.0-Beta2 | 8 / 11 | 2.0.20 | 0.12.0-383 | 18.1.0 | 2.2.20-dev-3524 | 0.8.1-dev-66 |
201+
| 1.0.0-Beta3n (notebooks) | 8 / 11 | 2.2.20 | 0.15.0-587 (K1 only) | 18.3.0 | - | 0.8.1n |
202+
| 1.0.0-Beta3 | 8 / 11 | 2.2.20 | 0.15.0-587 | 18.3.0 | 2.2.20 / IDEA 2025.2+ | 0.8.1 |
190203

191204
## Code of Conduct
192205

193-
This project and the corresponding community are governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). Please make sure you read it.
206+
This project and the corresponding community are governed by
207+
the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct).
208+
Please make sure you read it.
194209

195210
## License
196211

‎dataframe-jupyter/build.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ group = "org.jetbrains.kotlinx"
1616
repositories {
1717
// geo repository should come before Maven Central
1818
maven("https://repo.osgeo.org/repository/release")
19+
maven("https://packages.jetbrains.team/maven/p/kds/kotlin-ds-maven")
1920
mavenCentral()
2021
}
2122

@@ -35,6 +36,8 @@ dependencies {
3536

3637
testImplementation(projects.dataframeJupyter)
3738
testImplementation(projects.dataframeGeoJupyter)
39+
testImplementation(libs.kandy.notebook)
40+
testImplementation(libs.kandy.stats)
3841

3942
testImplementation(libs.kotestAssertions) {
4043
exclude("org.jetbrains.kotlin", "kotlin-stdlib-jdk8")

‎dataframe-jupyter/src/test/kotlin/org/jetbrains/kotlinx/dataframe/jupyter/DataFrameJupyterTest.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import org.jetbrains.kotlinx.jupyter.testkit.ReplProvider
77
abstract class DataFrameJupyterTest :
88
JupyterReplTestCase(
99
ReplProvider.forLibrariesTesting(
10-
libraries = setOf("dataframe", "kandy-geo"),
10+
libraries = setOf("dataframe", "kandy-geo", "kandy"),
1111
extraCompilerArguments = listOf(
1212
"-Xopt-in=kotlin.time.ExperimentalTime",
1313
"-Xopt-in=kotlin.uuid.ExperimentalUuidApi",

‎docs/StardustDocs/resources/guides/quickstart.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
},
5151
"cell_type": "code",
5252
"source": [
53-
"val df = DataFrame.readCSV(\n",
53+
"val df = DataFrame.readCsv(\n",
5454
" \"https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv\"\n",
5555
")"
5656
],

‎docs/StardustDocs/topics/setup/Modules.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -512,7 +512,7 @@ To enable the plugin in your Gradle project, add it to the `plugins` section:
512512

513513
```kotlin
514514
plugins {
515-
kotlin("plugin.dataframe") version "2.2.20-Beta1"
515+
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
516516
}
517517
```
518518

@@ -522,7 +522,7 @@ plugins {
522522

523523
```groovy
524524
plugins {
525-
id 'org.jetbrains.kotlin.plugin.dataframe' version '2.2.20-Beta1'
525+
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
526526
}
527527
```
528528

‎docs/StardustDocs/topics/setup/SetupAndroid.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ To enable the plugin in your Gradle project, add it to the `plugins` section:
109109

110110
```kotlin
111111
plugins {
112-
kotlin("plugin.dataframe") version "2.2.20-Beta1"
112+
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
113113
}
114114
```
115115

@@ -119,7 +119,7 @@ plugins {
119119

120120
```groovy
121121
plugins {
122-
id 'org.jetbrains.kotlin.plugin.dataframe' version '2.2.20-Beta1'
122+
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
123123
}
124124
```
125125

‎docs/StardustDocs/topics/setup/SetupGradle.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ To enable the plugin in your Gradle project, add it to the `plugins` section:
103103

104104
```kotlin
105105
plugins {
106-
kotlin("plugin.dataframe") version "2.2.20-Beta1"
106+
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
107107
}
108108
```
109109

@@ -113,7 +113,7 @@ plugins {
113113

114114
```groovy
115115
plugins {
116-
id 'org.jetbrains.kotlin.plugin.dataframe' version '2.2.20-Beta1'
116+
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
117117
}
118118
```
119119

‎docs/StardustDocs/topics/setup/SetupKotlinNotebook.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,13 @@ You can explicitly define the version you want:
7171
Or use the latest stable version of Kotlin DataFrame
7272
(specified in [Kotlin Jupyter descriptors](https://github.com/Kotlin/kotlin-jupyter-libraries)):
7373

74+
<warning>
75+
For version `1.0.0-Beta3`, in notebooks use version `1.0.0-Beta3n` instead.
76+
This uses the patch of [#1435](https://github.com/Kotlin/dataframe/pull/1435) for issue
77+
[#1116](https://github.com/Kotlin/dataframe/issues/1116), avoiding `DefinitelyNotNullable` errors.
78+
79+
When using `%use dataframe` this version is applied automatically.
80+
</warning>
7481

7582
```
7683
%useLatestDescriptors

‎docs/StardustDocs/v.list‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
33
<vars>
4-
<var name="dataFrameVersion" value="1.0.0-Beta2" type="string"/>
5-
<var name="compilerPluginKotlinVersion" value="2.2.20-Beta1" type="string"/>
4+
<var name="dataFrameVersion" value="1.0.0-Beta3" type="string"/>
5+
<var name="compilerPluginKotlinVersion" value="2.2.20" type="string"/>
66
</vars>

‎examples/android-example/app/build.gradle.kts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ plugins {
44
alias(libs.plugins.android.application)
55
alias(libs.plugins.kotlin.android)
66
alias(libs.plugins.kotlin.compose)
7-
kotlin("plugin.dataframe") version "2.2.20-Beta2"
7+
8+
// DataFrame Compiler plugin, matching the Kotlin version
9+
alias(libs.plugins.dataframe)
810
}
911

1012
android {
@@ -66,9 +68,9 @@ dependencies {
6668
// Core Kotlin DataFrame API, JSON and CSV IO.
6769
// See custom Gradle setup:
6870
// https://kotlin.github.io/dataframe/setupcustomgradle.html
69-
implementation("org.jetbrains.kotlinx:dataframe-core:1.0.0-dev-8314")
70-
implementation("org.jetbrains.kotlinx:dataframe-json:1.0.0-dev-8314")
71-
implementation("org.jetbrains.kotlinx:dataframe-csv:1.0.0-dev-8314")
71+
implementation("org.jetbrains.kotlinx:dataframe-core:1.0.0-Beta3")
72+
implementation("org.jetbrains.kotlinx:dataframe-json:1.0.0-Beta3")
73+
implementation("org.jetbrains.kotlinx:dataframe-csv:1.0.0-Beta3")
7274
// You can add any additional IO modules you like, except for 'dataframe-arrow'.
7375
// Apache Arrow is not supported well on Android.
7476
}

0 commit comments

Comments
 (0)