Add a migration guide from Pandas
- 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
Assessment
This issue has not been assessed yet.