Kotlin / Kotlin/dataframe

Add KDocs and tests for `PivotGroupBy.matches`

Open Beginner friendly
#1,970 0 comments 0 reactions 0 assignees View on GitHub
KDocs tests
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

## Add KDocs and tests for `PivotGroupBy.matches`

`core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/matches.kt` contains two small public APIs without KDocs:

```kotlin
public fun PivotGroupBy.matches(): DataFrame =
matches(yes = true, no = false)

public fun PivotGroupBy.matches(yes: R, no: R): DataFrame =
aggregate { yes default no }
```

The behavior is already documented on the site through `pivotMatches`:
https://kotlin.github.io/dataframe/pivot.html#pivotmatches

KDocs and tests should be aligned with that documented behavior.

### What it does

`matches()` creates a pivoted `DataFrame` where each cell contains `true` if the pivot value was present in the original data for the corresponding group, and `false` otherwise.

`matches(yes, no)` allows custom values instead of `true` and `false`.

### Scope

- Add concise KDocs for both `matches` overloads.
- Add focused tests for default and custom `yes/no` behavior.
- Align wording with the existing `pivotMatches` documentation.

### Test scenarios as an option

#### Positive scenario

- Given a dataframe grouped by `name` and pivoted by `city`.
- When calling `df.groupBy("name").pivot("city").matches()`.
- Then matching cells contain `true`.

#### Negative / missing-match scenario

- Given a group with no rows for one of the pivot values.
- When calling `matches()`.
- Then the corresponding cell contains `false`.

#### Custom values scenario

- Given the same grouped/pivoted dataframe.
- When calling `matches(yes = "yes", no = "no")`.
- Then matching cells contain `"yes"` and missing cells contain `"no"`.

### Suggested test sketch

```kotlin
@Test
fun `pivot group by matches returns booleans for present values`() {
val df = dataFrameOf("name", "city")(
"Alice", "London",
"Alice", "Paris",
"Bob", "London",
)

val result = df.groupBy("name").pivot("city").matches()

result["city"]["London"].toList() shouldBe listOf(true, true)
result["city"]["Paris"].toList() shouldBe listOf(true, false)
}

@Test
fun `pivot group by matches supports custom yes no values`() {
val df = dataFrameOf("name", "city")(
"Alice", "London",
"Alice", "Paris",
"Bob", "London",
)

val result = df.groupBy("name").pivot("city").matches(yes = "yes", no = "no")

result["city"]["London"].toList() shouldBe listOf("yes", "yes")
result["city"]["Paris"].toList() shouldBe listOf("yes", "no")
}
```

### Acceptance criteria

- `PivotGroupBy.matches()` and `PivotGroupBy.matches(yes, no)` have KDocs.
- KDocs are consistent with the existing `pivotMatches` site documentation.
- Tests verify actual boolean values for matching and missing cells.
- Tests verify custom `yes/no` values.

Contributor guide

Open the contributing guide

Research direction

Start with core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/matches.kt and compare its KDocs with the existing pivotMatches documentation. Locate the focused pivot tests, then cover default boolean and custom yes/no values, including missing matches. Done means both overloads have aligned KDocs and the tests verify matching and missing cells.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
data, documentation, testing-qa
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.