Skip to content

Commit 9af7421

Browse files
JolanrensenJolanrensen
committed
format refactoring, adding at/notNull, and kdocs
1 parent 61cdd98 commit 9af7421

File tree

13 files changed

+1694
-148
lines changed

13 files changed

+1694
-148
lines changed

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ internal interface FillNulls {
5555
* `[ `__`.`__[**`at`**][org.jetbrains.kotlinx.dataframe.api.Update.at]**`(`**[`rowIndices`][org.jetbrains.kotlinx.dataframe.api.CommonUpdateAtFunctionDoc.RowIndicesParam]**`)`**` ]`
5656
*
5757
*     
58+
* `[ `__`.`__[**`notNull`**][org.jetbrains.kotlinx.dataframe.api.Update.notNull]**`()`**` ]`
59+
*
60+
*     
5861
* __`.`__[**`with`**][org.jetbrains.kotlinx.dataframe.api.Update.with]**` { `**[`rowExpression`][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowValueExpression.WithExample]**` }`**
5962
*
6063
*     
@@ -389,6 +392,9 @@ internal interface FillNaNs {
389392
* `[ `__`.`__[**`at`**][org.jetbrains.kotlinx.dataframe.api.Update.at]**`(`**[`rowIndices`][org.jetbrains.kotlinx.dataframe.api.CommonUpdateAtFunctionDoc.RowIndicesParam]**`)`**` ]`
390393
*
391394
*     
395+
* `[ `__`.`__[**`notNull`**][org.jetbrains.kotlinx.dataframe.api.Update.notNull]**`()`**` ]`
396+
*
397+
*     
392398
* __`.`__[**`with`**][org.jetbrains.kotlinx.dataframe.api.Update.with]**` { `**[`rowExpression`][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowValueExpression.WithExample]**` }`**
393399
*
394400
*     
@@ -662,6 +668,9 @@ internal interface FillNA {
662668
* `[ `__`.`__[**`at`**][org.jetbrains.kotlinx.dataframe.api.Update.at]**`(`**[`rowIndices`][org.jetbrains.kotlinx.dataframe.api.CommonUpdateAtFunctionDoc.RowIndicesParam]**`)`**` ]`
663669
*
664670
*     
671+
* `[ `__`.`__[**`notNull`**][org.jetbrains.kotlinx.dataframe.api.Update.notNull]**`()`**` ]`
672+
*
673+
*     
665674
* __`.`__[**`with`**][org.jetbrains.kotlinx.dataframe.api.Update.with]**` { `**[`rowExpression`][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowValueExpression.WithExample]**` }`**
666675
*
667676
*     

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

Lines changed: 904 additions & 45 deletions
Large diffs are not rendered by default.

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package org.jetbrains.kotlinx.dataframe.api
33
import org.jetbrains.kotlinx.dataframe.AnyRow
44
import org.jetbrains.kotlinx.dataframe.ColumnExpression
55
import org.jetbrains.kotlinx.dataframe.ColumnsSelector
6+
import org.jetbrains.kotlinx.dataframe.DataColumn
67
import org.jetbrains.kotlinx.dataframe.DataFrame
78
import org.jetbrains.kotlinx.dataframe.DataFrameExpression
89
import org.jetbrains.kotlinx.dataframe.DataRow
@@ -11,6 +12,7 @@ import org.jetbrains.kotlinx.dataframe.RowValueFilter
1112
import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
1213
import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
1314
import org.jetbrains.kotlinx.dataframe.annotations.Refine
15+
import org.jetbrains.kotlinx.dataframe.api.mean
1416
import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
1517
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
1618
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
@@ -69,6 +71,9 @@ public class Update<T, C>(
6971
* `[ `__`.`__[**`at`**][Update.at]**`(`**[`rowIndices`][CommonUpdateAtFunctionDoc.RowIndicesParam]**`)`**` ]`
7072
*
7173
* &nbsp;&nbsp;&nbsp;&nbsp;
74+
* `[ `__`.`__[**`notNull`**][Update.notNull]**`()`**` ]`
75+
*
76+
* &nbsp;&nbsp;&nbsp;&nbsp;
7277
* __`.`__[**`with`**][Update.with]**` { `**[`rowExpression`][ExpressionsGivenRow.RowValueExpression.WithExample]**` }`**
7378
*
7479
* &nbsp;&nbsp;&nbsp;&nbsp;
@@ -611,25 +616,21 @@ internal infix fun <T, C> RowValueFilter<T, C>?.and(other: RowValueFilter<T, C>)
611616
return { thisExp(this, it) && other(this, it) }
612617
}
613618

614-
/** ## Not Null
615-
*
616-
* Selects only the rows where the values in the selected columns are not null.
619+
/**
620+
* ## Not Null
621+
* Filters the update-selection to only include cells where the value is not null.
617622
*
618-
* Shorthand for: [update][org.jetbrains.kotlinx.dataframe.api.update]` { ... }.`[where][org.jetbrains.kotlinx.dataframe.api.Update.where]` { it != null }`
623+
* This is shorthand for `.`[where][Update.where]` { it != null }`.
619624
*
620625
* For example:
621626
*
622-
* `df.`[update][org.jetbrains.kotlinx.dataframe.api.update]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.colsOf]`<`[Number][Number]`?>() }.`[notNull][org.jetbrains.kotlinx.dataframe.api.notNull]`().`[perCol][org.jetbrains.kotlinx.dataframe.api.Update.perCol]` { `[mean][org.jetbrains.kotlinx.dataframe.api.mean]`() }`
627+
* `df.`[update][update]` { `[colsOf][colsOf]`<`[Int][Int]`?>() }.`[notNull][notNull]`().`[perRowCol][Update.perRowCol]` { row, col ->`
623628
*
624-
* ### Optional
625-
* Provide an [expression] to update the rows with.
626-
* This combines [with][org.jetbrains.kotlinx.dataframe.api.Update.with] with [notNull][org.jetbrains.kotlinx.dataframe.api.notNull].
627-
*
628-
* For example:
629+
* &nbsp;&nbsp;&nbsp;&nbsp;`row[col] / col.`[mean][DataColumn.mean]`(skipNA = true)`
629630
*
630-
* `df.`[update][org.jetbrains.kotlinx.dataframe.api.update]` { city }.`[notNull][org.jetbrains.kotlinx.dataframe.api.Update.notNull]` { it.`[toUpperCase][String.toUpperCase]`() }`
631-
*
632-
* @param expression Optional [Row Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowExpression.WithExample] to update the rows with. */
631+
* `}`
632+
*/
633+
@Suppress("UNCHECKED_CAST")
633634
@Interpretable("UpdateNotNullDefault")
634635
public fun <T, C> Update<T, C?>.notNull(): Update<T, C> = where { it != null } as Update<T, C>
635636

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/format.kt

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ package org.jetbrains.kotlinx.dataframe.impl.api
33
import org.jetbrains.kotlinx.dataframe.api.CellAttributes
44
import org.jetbrains.kotlinx.dataframe.api.FormatClause
55
import org.jetbrains.kotlinx.dataframe.api.FormattedFrame
6-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL
7-
import org.jetbrains.kotlinx.dataframe.api.RGBColor
6+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
7+
import org.jetbrains.kotlinx.dataframe.api.RgbColor
88
import org.jetbrains.kotlinx.dataframe.api.RowColFormatter
99
import org.jetbrains.kotlinx.dataframe.api.and
1010
import org.jetbrains.kotlinx.dataframe.api.cast
@@ -24,10 +24,10 @@ internal fun encRgb(r: Short, g: Short, b: Short): String = "#${encHex(r)}${encH
2424

2525
internal fun encHex(v: Short): String = "${(v / 16).toString(16)}${(v % 16).toString(16)}"
2626

27-
internal fun RGBColor.encode() = encRgb(r, g, b)
27+
internal fun RgbColor.encode() = encRgb(r, g, b)
2828

29-
internal fun componentWise(color1: RGBColor, color2: RGBColor, f: (Short, Short) -> Short) =
30-
RGBColor(
29+
internal fun componentWise(color1: RgbColor, color2: RgbColor, f: (Short, Short) -> Short) =
30+
RgbColor(
3131
f(color1.r, color2.r),
3232
f(color1.g, color2.g),
3333
f(color1.b, color2.b),
@@ -36,35 +36,37 @@ internal fun componentWise(color1: RGBColor, color2: RGBColor, f: (Short, Short)
3636
internal fun linearGradient(
3737
x: Double,
3838
minValue: Double,
39-
minColor: RGBColor,
39+
minColor: RgbColor,
4040
maxValue: Double,
41-
maxColor: RGBColor,
42-
): RGBColor {
41+
maxColor: RgbColor,
42+
): RgbColor {
4343
if (x < minValue) return minColor
4444
if (x > maxValue) return maxColor
4545
val t = (x - minValue) / (maxValue - minValue)
46-
return componentWise(minColor, maxColor) { cmin, cmax ->
47-
(cmin + t * (cmax - cmin)).toInt().toShort()
46+
return componentWise(minColor, maxColor) { cMin, cMax ->
47+
(cMin + t * (cMax - cMin)).toInt().toShort()
4848
}
4949
}
5050

51+
@Suppress("UNCHECKED_CAST")
5152
internal inline fun <T, C> FormatClause<T, C>.formatImpl(
5253
crossinline formatter: RowColFormatter<T, C>,
5354
): FormattedFrame<T> {
55+
val clause = this
5456
val columns =
55-
if (columns != null) {
56-
df.getColumnsWithPaths(columns)
57+
if (clause.columns != null) {
58+
clause.df.getColumnsWithPaths(clause.columns)
5759
.mapNotNull { if (it.depth == 0) it.name else null }
5860
.toSet()
5961
} else {
6062
null
6163
}
62-
return FormattedFrame(df) { row, col ->
63-
val oldAttributes = oldFormatter?.invoke(FormattingDSL, row, col.cast())
64+
return FormattedFrame(clause.df) { row, col ->
65+
val oldAttributes = clause.oldFormatter?.invoke(FormattingDsl, row, col.cast())
6466
if (columns == null || columns.contains(col.name())) {
65-
val value = row[col] as C
66-
if (filter == null || filter(row, value)) {
67-
oldAttributes and formatter(FormattingDSL, row.cast(), col.cast())
67+
val value = row[col.name] as C
68+
if (clause.filter(row, value)) {
69+
oldAttributes and formatter(FormattingDsl, row.cast(), col.cast())
6870
} else {
6971
oldAttributes
7072
}

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@ import org.jetbrains.kotlinx.dataframe.AnyFrame
66
import org.jetbrains.kotlinx.dataframe.AnyRow
77
import org.jetbrains.kotlinx.dataframe.DataFrame
88
import org.jetbrains.kotlinx.dataframe.api.FormattedFrame
9-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL
9+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
1010
import org.jetbrains.kotlinx.dataframe.api.RowColFormatter
1111
import org.jetbrains.kotlinx.dataframe.api.asColumnGroup
1212
import org.jetbrains.kotlinx.dataframe.api.asNumbers
13+
import org.jetbrains.kotlinx.dataframe.api.format
1314
import org.jetbrains.kotlinx.dataframe.api.getColumnsWithPaths
1415
import org.jetbrains.kotlinx.dataframe.api.isColumnGroup
1516
import org.jetbrains.kotlinx.dataframe.api.isEmpty
@@ -185,7 +186,7 @@ internal fun AnyFrame.toHtmlData(
185186
val html =
186187
formatter.format(downsizeBufferedImageIfNeeded(value, renderConfig), cellRenderer, renderConfig)
187188
val style = renderConfig.cellFormatter
188-
?.invoke(FormattingDSL, it, col)
189+
?.invoke(FormattingDsl, it, col)
189190
?.attributes()
190191
?.ifEmpty { null }
191192
?.joinToString(";") { "${it.first}:${it.second}" }
@@ -546,6 +547,9 @@ public fun <T> DataFrame<T>.toStandaloneHTML(
546547
* By default, cell content is formatted as text
547548
* Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
548549
*
550+
* To change the formatting of certain cells or columns in the dataframe,
551+
* use [DataFrame.format].
552+
*
549553
* The [DataFrameHtmlData] be saved as an *.html file and displayed in the browser.
550554
* If you save it as a file and find it in the project tree,
551555
* the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure) feature of IntelliJ IDEA will automatically reload the file content when it's updated
@@ -560,6 +564,10 @@ public fun <T> DataFrame<T>.toStandaloneHtml(
560564
/**
561565
* By default, cell content is formatted as text
562566
* Use [RenderedContent.media] or [IMG], [IFRAME] if you need custom HTML inside a cell.
567+
*
568+
* To change the formatting of certain cells or columns in the dataframe,
569+
* use [DataFrame.format].
570+
*
563571
* @return DataFrameHtmlData without additional definitions. Can be rendered in Jupyter kernel environments
564572
*/
565573
public fun <T> DataFrame<T>.toHtml(
@@ -597,8 +605,10 @@ public fun <T> DataFrame<T>.toHtml(
597605
}
598606

599607
/**
600-
* Container for HTML page data in the form of a String
601-
* Can be used to compose rendered dataframe tables with additional HTML elements
608+
* Container for HTML data, often containing a dataframe table.
609+
*
610+
* It can be used to compose rendered dataframe tables with additional HTML elements,
611+
* or to simply print the HTML or write it to file.
602612
*/
603613
public class DataFrameHtmlData(
604614
@Language("css") public val style: String = "",
@@ -735,6 +745,9 @@ public class DataFrameHtmlData(
735745
}
736746

737747
/**
748+
* A collection of settings for rendering dataframes as HTML tables or native
749+
* Kotlin Notebook table output.
750+
*
738751
* @param rowsLimit null to disable rows limit
739752
* @param cellContentLimit -1 to disable content trimming
740753
* @param enableFallbackStaticTables true to add additional pure HTML table that will be visible only if JS is disabled;

‎core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/JoinWith.kt

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ import kotlinx.datetime.toJavaLocalDate
88
import org.jetbrains.kotlinx.dataframe.AnyFrame
99
import org.jetbrains.kotlinx.dataframe.DataFrame
1010
import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
11-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL
11+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
1212
import org.jetbrains.kotlinx.dataframe.api.Infer
1313
import org.jetbrains.kotlinx.dataframe.api.JoinedDataRow
14-
import org.jetbrains.kotlinx.dataframe.api.RGBColor
14+
import org.jetbrains.kotlinx.dataframe.api.RgbColor
1515
import org.jetbrains.kotlinx.dataframe.api.and
1616
import org.jetbrains.kotlinx.dataframe.api.cast
1717
import org.jetbrains.kotlinx.dataframe.api.colsOf
@@ -73,7 +73,7 @@ class JoinWith : TestBase() {
7373
LocalDate(2023, 7, 10), 2,
7474
).cast<Visits>()
7575

76-
class ColoredValue<T>(val value: T, val backgroundColor: RGBColor, val textColor: RGBColor) {
76+
class ColoredValue<T>(val value: T, val backgroundColor: RgbColor, val textColor: RgbColor) {
7777
override fun equals(other: Any?): Boolean {
7878
if (this === other) return true
7979
if (javaClass != other?.javaClass) return false
@@ -108,18 +108,18 @@ class JoinWith : TestBase() {
108108
colsAtAnyDepth().colsOf<ColoredValue<*>?>()
109109
}.with(Infer.Type) { it?.value }
110110

111-
private fun <T> T.colored(background: RGBColor, text: RGBColor) = ColoredValue(this, background, text)
111+
private fun <T> T.colored(background: RgbColor, text: RgbColor) = ColoredValue(this, background, text)
112112

113-
private fun <T> T.winter(background: RGBColor = RGBColor(179, 205, 224), text: RGBColor = RGBColor(0, 0, 51)) =
113+
private fun <T> T.winter(background: RgbColor = RgbColor(179, 205, 224), text: RgbColor = RgbColor(0, 0, 51)) =
114114
ColoredValue(this, background, text)
115115

116-
private fun <T> T.spring(background: RGBColor = RGBColor(204, 235, 197), text: RGBColor = RGBColor(0, 51, 0)) =
116+
private fun <T> T.spring(background: RgbColor = RgbColor(204, 235, 197), text: RgbColor = RgbColor(0, 51, 0)) =
117117
ColoredValue(this, background, text)
118118

119-
private fun <T> T.summer(background: RGBColor = RGBColor(176, 224, 230), text: RGBColor = RGBColor(25, 25, 112)) =
119+
private fun <T> T.summer(background: RgbColor = RgbColor(176, 224, 230), text: RgbColor = RgbColor(25, 25, 112)) =
120120
ColoredValue(this, background, text)
121121

122-
private fun <T> T.autumn(background: RGBColor = RGBColor(221, 160, 221), text: RGBColor = RGBColor(85, 26, 139)) =
122+
private fun <T> T.autumn(background: RgbColor = RgbColor(221, 160, 221), text: RgbColor = RgbColor(85, 26, 139)) =
123123
ColoredValue(this, background, text)
124124

125125
private val coloredCampaigns = dataFrameOf("name", "startDate", "endDate")(
@@ -134,7 +134,7 @@ class JoinWith : TestBase() {
134134
LocalDate(2023, 1, 10).winter(), 1.winter(),
135135
LocalDate(2023, 1, 20).winter(), 2.winter(),
136136
LocalDate(2023, 4, 15).spring(), 1.spring(),
137-
LocalDate(2023, 5, 1).colored(FormattingDSL.white, FormattingDSL.black), 3.colored(FormattingDSL.white, FormattingDSL.black),
137+
LocalDate(2023, 5, 1).colored(FormattingDsl.white, FormattingDsl.black), 3.colored(FormattingDsl.white, FormattingDsl.black),
138138
LocalDate(2023, 7, 10).summer(), 2.summer(),
139139
)
140140

‎core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/FormattingTests.kt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@ package org.jetbrains.kotlinx.dataframe.testSets.person
22

33
import io.kotest.matchers.shouldBe
44
import io.kotest.matchers.string.shouldContain
5-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL
6-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL.gray
7-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL.green
8-
import org.jetbrains.kotlinx.dataframe.api.FormattingDSL.red
5+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
6+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.gray
7+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.green
8+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.red
99
import org.jetbrains.kotlinx.dataframe.api.and
1010
import org.jetbrains.kotlinx.dataframe.api.colsOf
1111
import org.jetbrains.kotlinx.dataframe.api.format
@@ -33,7 +33,7 @@ class FormattingTests : BaseTest() {
3333

3434
val formatter = formattedFrame.formatter!!
3535
for (row in 0 until typed.nrow) {
36-
FormattingDSL.formatter(typed[row], typed.age)!!.attributes().size shouldBe
36+
FormattingDsl.formatter(typed[row], typed.age)!!.attributes().size shouldBe
3737
if (typed[row].age > 10) 3 else 2
3838
}
3939

@@ -48,12 +48,12 @@ class FormattingTests : BaseTest() {
4848
.formatter!!
4949

5050
for (row in 0 until typed.nrow step 2) {
51-
FormattingDSL.formatter(typed[row], typed.age)!!.attributes() shouldBe
51+
FormattingDsl.formatter(typed[row], typed.age)!!.attributes() shouldBe
5252
listOf("background-color" to gray.encode())
5353
}
5454

5555
for (row in 1 until typed.nrow step 2) {
56-
FormattingDSL.formatter(typed[row], typed.age)!!.attributes() shouldBe
56+
FormattingDsl.formatter(typed[row], typed.age)!!.attributes() shouldBe
5757
listOf("background-color" to linearGradient(typed[row].age.toDouble(), 20.0, green, 80.0, red).encode())
5858
}
5959
}

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -516,7 +516,7 @@ private interface SeeAlsoConvertWith
516516
* ```kotlin
517517
* // Convert values in all columns to `String` and add their column name to the end
518518
* df.convert { all() }.perRowCol { row, col ->
519-
* row[col].toString() + col.name()
519+
* col[row].toString() + col.name()
520520
* }
521521
* ```
522522
*

0 commit comments

Comments
 (0)