Kotlin / Kotlin/dataframe

Documentation for toDataFrame

Open
#1,479 1 comment 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

I put together a draft, but it needs further improvements:
1. Expand on multiple properties in toDataFrame lambda use case:
```
list.toDataFrame {
properties(A::prop1, A::prop2) {
/* subgraph settings go here */
}
properties(A::prop3, A::prop4) {
/* subgraph settings go here */
}
}
```
2. Verify `Values and lists of values of a type annotated with [DataSchema] are expanded ignoring maxDepth, but can be preserved?..`
3. Provide example with multiple exclude/preserve, maxDepth
4. Merge with info from existing documentation
5. Note that exclude is similar to remove, but exclude might be useful if computation of property is expensive
6. Note about that GRAPH of objects is being converted and can result in stack overflow or OOM exceptions
7. Update `Iterable` sample with class hierarchy. I propose to use Konsist as a reference: they represect Kotlin functions as object with many many fields and most of them are nested. We could take this hierarchy, simplify it a bit for our purpose and inline some data
```
8. Maybe extensive examples should go to the website, and be linked to from kdocs
9. `toDataFrame` should be in "Interop with collections", now it's only under https://kotlin.github.io/dataframe/createdataframe.html#todataframe

/** Converts `Iterable` to DataFrame, each element becomes a row in DataFrame.

*
* Performs expansion of value T according to its properties and getter-like functions, recursively
* or according to props
*
* Additional columns can be added [CreateDataFrameDsl].
*
* If the value of `property3: NestedObject` can be expanded recursively, it becomes a ColumnGroup.
*
* If the value of `property4: List` can be expanded recursively, it becomes a FrameColumn.
*
* Rules for expansions:
* 1. Values and lists of values of a type annotated with [DataSchema] are expanded ignoring maxDepth, but can be preserved?..
* 2. Value types are always preserved [org.jetbrains.kotlinx.dataframe.impl.api.isValueType].
* 3. Given `Iterable`, if T itself is a value type, a DataFrame with column `value: T` is created
* 4. maxDepth is checked. Below, property1, 2, 3 is maxDepth = 1. nestedProperty1, 2, 3 is maxDepth = 2
* 5. Additional classes and properties can be preserved [preserve], [TraversePropertiesDsl.preserve]
* 6. Classes and properties can be excluded from conversion whatsoever [TraversePropertiesDsl.exclude]
*
*
* ```
* Iterable
* property1: Int
* property2: String?
* property3: NestedObject
* nestedProperty1: String
* nestedProperty2: List
* nestedProperty3: Map
* nestedProperty4: List
* property4: List
* ```
*
* To put it all together:
* ```
* list.toDataFrame {
* properties(maxDepth = 0)
* }
* ```
* ```
* property1: Int
* property2: String?
* property3: NestedObject // preserved because of maxDepth
* property4: List
* ```
*
*
*/
```

Contributor guide

Open the contributing guide

Research direction

Start with the existing toDataFrame documentation at createdataframe.html#todataframe and the KDoc draft in the issue, then compare it with the “Interop with collections” section. Review the listed lambda, expansion, preserve/exclude, maxDepth, hierarchy, and overflow cases. Done means the existing documentation is merged with the requested examples and links, and the toDataFrame entry is covered in the intended section.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.