Kotlin / Kotlin/dataframe

Add a migration guide from Pandas

Open
#1,299 1 comment 0 reactions 1 assignee Claimed by @zaleslaw View on GitHub
documentation
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

## Problem

Many potential Kotlin DataFrame users come from a Python/Pandas background.

During the 1.0 public launch, these users need a clear migration guide that helps them understand how familiar Pandas workflows map to Kotlin DataFrame, and where the mental model is intentionally different.

Without such a guide, users may evaluate Kotlin DataFrame by trying to translate Pandas code mechanically and become confused by differences around:

- type-safe access;
- schemas and generated extension properties;
- immutable dataframe transformations;
- Kotlin DSLs;
- row expressions vs column selectors;
- grouped operations and aggregations;
- IO setup and dependency/module choices;
- notebooks vs Gradle/Maven projects.

Other ecosystems provide similar migration guides, for example:

- Ktor: [Migration from Express](https://ktor.io/docs/migration-from-express-js.html)
- Polars: [Coming from Pandas](https://docs.pola.rs/user-guide/migration/pandas/)

Kotlin DataFrame should have a similar entry point for Pandas users before the 1.0 release.

## Expected

Add a “Migration from Pandas” / “Coming from Pandas” guide to the documentation.

The guide should focus on practical onboarding and conceptual differences, not just a table of function names.

## Suggested Content

Cover common Pandas workflows and their Kotlin DataFrame equivalents:

- creating a dataframe;
- reading CSV/JSON/Excel/Parquet;
- selecting columns;
- filtering rows;
- adding and updating columns;
- renaming columns;
- handling missing values;
- sorting;
- grouping and aggregation;
- joins;
- reshaping/pivoting where applicable;
- describing / summary statistics;
- writing data.

Also explain Kotlin DataFrame-specific concepts:

- `DataFrame` and schemas;
- extension properties and when they are available;
- compiler plugin support;
- string access vs type-safe access;
- column selector DSL;
- row expressions;
- immutable operations returning new dataframes;
- differences between Notebook and Gradle/Maven usage.

## References

Possible starting points / inspiration:

- Ktor migration-style guide: https://ktor.io/docs/migration-from-express-js.html
- Polars “Coming from Pandas”: https://docs.pola.rs/user-guide/migration/pandas/
- Kotlin DataFrame article: https://tech.dentsusoken.com/entry/kotlin_dataframe
- Python to Kotlin resources:
- https://github.com/Khan/kotlin-for-python-developers
- https://kotlin-for-python.readthedocs.io/en/latest/

## Definition of Done

- Add a dedicated documentation page for users coming from Pandas.
- Include side-by-side examples for the most common Pandas workflows.
- Explain key conceptual differences, not only syntax differences.
- Link the guide from onboarding / docs navigation where new users can find it.
- Cross-link to relevant Kotlin DataFrame pages:
- setup;
- schemas;
- extension properties;
- column selectors;
- row expressions;
- grouping/aggregation;
- IO.
- Ensure all Kotlin DataFrame examples compile or are covered by the docs sample validation workflow where possible.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.