Merge branch 'master' into pivot_kdocs

Author: AndreiKingsley

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/AggregateDsl.kt

@@ -1,6 +1,7 @@
 package org.jetbrains.kotlinx.dataframe.aggregation
 
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.annotations.HasSchema
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
 import org.jetbrains.kotlinx.dataframe.api.ColumnSelectionDsl
@@ -9,6 +10,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.ValueWithDefault
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.receivers.internal
 import org.jetbrains.kotlinx.dataframe.impl.columnName
+import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
 import kotlin.reflect.KProperty
 import kotlin.reflect.typeOf
 
@@ -21,9 +23,13 @@ public abstract class AggregateDsl<out T> :
     public inline infix fun <reified R> R.into(name: String): NamedValue =
         internal().yield(pathOf(name), this, typeOf<R>())
 
+    @Deprecated(DEPRECATED_ACCESS_API)
+    @AccessApiOverload
     public inline infix fun <reified R> R.into(column: ColumnAccessor<R>): NamedValue =
         internal().yield(pathOf(column.name()), this, typeOf<R>())
 
+    @Deprecated(DEPRECATED_ACCESS_API)
+    @AccessApiOverload
     public inline infix fun <reified R> R.into(column: KProperty<R>): NamedValue =
         internal().yield(pathOf(column.columnName), this, typeOf<R>())
 

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

@@ -19,7 +19,8 @@ import kotlin.reflect.KProperty
 // region DataFrame
 
 /**
- * Groups the specified [columns] within the [DataFrame].
+ * Groups the specified [columns] within the [DataFrame] into
+ * [column group][ColumnGroup].
  *
  * This function does not immediately group the columns but instead select columns to group and
  * returns a [GroupClause],
@@ -142,7 +143,8 @@ internal interface GroupDocs {
 }
 
 /**
- * Groups the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame].
+ * Groups the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] into
+ * [column group][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup].
  *
  * This function does not immediately group the columns but instead select columns to group and
  * returns a [GroupClause][org.jetbrains.kotlinx.dataframe.api.GroupClause],
@@ -197,7 +199,8 @@ internal interface GroupDocs {
 public fun <T, C> DataFrame<T>.group(columns: ColumnsSelector<T, C>): GroupClause<T, C> = GroupClause(this, columns)
 
 /**
- * Groups the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame].
+ * Groups the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] into
+ * [column group][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup].
  *
  * This function does not immediately group the columns but instead select columns to group and
  * returns a [GroupClause][org.jetbrains.kotlinx.dataframe.api.GroupClause],

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

@@ -275,6 +275,37 @@ internal fun <T> Pivot<T>.reduce(reducer: Selector<DataFrame<T>, DataRow<T>?>):
 internal inline fun <T> Pivot<T>.delegate(crossinline body: PivotGroupBy<T>.() -> DataFrame<T>): DataRow<T> =
     body(groupBy { none() })[0]
 
+/**
+ * TODO (#1536)
+ */
+internal interface PivotGroupByDocs {
+
+    /**
+     * [PivotGroupBy] is a dataframe-like structure, combining [Pivot] and [GroupBy]
+     * and representing a matrix table with vertical [Pivot] groups (as columns)
+     * and horizontal [GroupBy] groups (as rows), and each cell
+     * represents a group corresponding both to [GroupBy] and [Pivot] key.
+     *
+     * Reversed order of `pivot` and `groupBy`
+     * (i.e., [DataFrame.pivot] + [Pivot.groupBy] or [DataFrame.groupBy] + [GroupBy.pivot])
+     * will produce the same result.
+     *
+     * [PivotGroupBy] can be [reduced][PivotGroupByDocs.Reducing]
+     * or [aggregated][PivotGroupByDocs.Aggregation].
+     *
+     * Check out [PivotGroupBy Grammar][PivotGroupByDocs.Grammar].
+     *
+     * For more information: [See "`pivot` + `groupBy`" on the documentation website.](https://kotlin.github.io/dataframe/groupby.html#pivot-groupby)
+     */
+    interface CommonDescription
+
+    interface Grammar
+
+    interface Reducing
+
+    interface Aggregation
+}
+
 public interface PivotGroupBy<out T> : Aggregatable<T> {
 
     public fun <R> aggregate(separate: Boolean = false, body: AggregateBody<T, R>): DataFrame<T>

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

@@ -38,7 +38,7 @@ import kotlin.reflect.KProperty
 /**
  * Groups the rows of this [DataFrame] based on the values in one or more specified [key columns][cols].
  * Each unique value in a key column — or a unique tuple of values for multiple columns —
- * defines a group consisting of all rows where the column(s) contain that value combination.
+ * defines the group consisting of all rows where the column(s) contain that value combination.
  *
  * Returns a [GroupBy] — a dataframe-like structure that contains all unique combinations of key values
  * along with the corresponding groups of rows (each represented as a [DataFrame]) as rows.
@@ -79,40 +79,40 @@ internal interface GroupByDocs {
      *
      * ### Create and transform [GroupBy]
      *
-     * [**`groupBy`**][groupBy]**`(`**`moveToTop: `[`Boolean`][Boolean]**` = true)  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**` }`**
+     * [**`groupBy`**][groupBy]**`(`**`moveToTop: `[`Boolean`][Boolean]**`  = true)  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**` }`**
      *
      * {@include [Indent]}
-     * `\[ `__`.`__[**`sortByGroup`**][GroupBy.sortByGroup]**`() `**
+     * `\[ `__`.`__[**`sortByGroup`**][GroupBy.sortByGroup]**`() `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByGroupDesc`**][GroupBy.sortByGroupDesc]**`() `**
+     * `\[ `__`.`__[**`sortByGroupDesc`**][GroupBy.sortByGroupDesc]**`() `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByCount`**][GroupBy.sortByCount]**`() `**
+     * `\[ `__`.`__[**`sortByCount`**][GroupBy.sortByCount]**`() `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByCountAsc`**][GroupBy.sortByCountAsc]**`() `**
+     * `\[ `__`.`__[**`sortByCountAsc`**][GroupBy.sortByCountAsc]**`() `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByKey`**][GroupBy.sortByKey]**`() `**
+     * `\[ `__`.`__[**`sortByKey`**][GroupBy.sortByKey]**`() `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByKeyDesc`**][GroupBy.sortByKeyDesc]**`() `**`]`
+     * `\[ `__`.`__[**`sortByKeyDesc`**][GroupBy.sortByKeyDesc]**`() `**`]`
      *
      * {@include [Indent]}
-     * `\[ `__`.`__[**`sortBy`**][GroupBy.sortBy]**`  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**` } `**
+     * `\[ `__`.`__[**`sortBy`**][GroupBy.sortBy]**`  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**`  }  `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`sortByDesc`**][GroupBy.sortByDesc]**`  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**` } `**`]`
+     * `\[ `__`.`__[**`sortByDesc`**][GroupBy.sortByDesc]**`  {  `**`columns: `[`ColumnsSelector`][ColumnsSelector]**`  }  `**`]`
      *
      * {@include [Indent]}
-     * `\[ `__`.`__[**`updateGroups`**][GroupBy.updateGroups]**`  {  `**`frameExpression`**` } `**`]`
+     * `\[ `__`.`__[**`updateGroups`**][GroupBy.updateGroups]**`  {  `**`frameExpression`**`  }  `**`]`
      *
      * {@include [Indent]}
-     * `\[ `__`.`__[**`filter`**][GroupBy.filter]**` {  `**`predicate: `[`GroupedRowFilter`][GroupedRowFilter]**` } `**`]`
+     * `\[ `__`.`__[**`filter`**][GroupBy.filter]**`  {  `**`predicate: `[`GroupedRowFilter`][GroupedRowFilter]**`  }  `**`]`
      *
      * {@include [Indent]}
-     * `\[ `__`.`__[**`add`**][GroupBy.add]**`(`**`column: `[`DataColumn`][DataColumn]**`)  {  `**`rowExpression: `[`RowExpression`][RowExpression]**` } `**`]`
+     * `\[ `__`.`__[**`add`**][GroupBy.add]**`(`**`column: `[`DataColumn`][DataColumn]**`)  {  `**`rowExpression: `[`RowExpression`][RowExpression]**`  }  `**`]`
      *
      * ### Reduce [GroupBy] into [DataFrame]
      *
@@ -123,10 +123,10 @@ internal interface GroupByDocs {
      * `| `__`.`__[**`maxBy`**][GroupBy.maxBy]**`  {  `**`column: `[`ColumnSelector`][ColumnSelector]**` }`**
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`first`**][GroupBy.first]`  \[ `**` {  `**`rowCondition: `[`RowFilter`][RowFilter]**` } `**`]`
+     * `| `__`.`__[**`first`**][GroupBy.first]`  \[ `**`  {  `**`rowCondition: `[`RowFilter`][RowFilter]**` } `**`]`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`last`**][GroupBy.last]`  \[ `**`{  `**`rowCondition: `[`RowFilter`][RowFilter]**` } `**`]`
+     * `| `__`.`__[**`last`**][GroupBy.last]`  \[ `**`  {  `**`rowCondition: `[`RowFilter`][RowFilter]**`  }  `**`]`
      *
      * {@include [Indent]}
      * __`.`__[**`concat`**][ReducedGroupBy.concat]**`() `**
@@ -234,7 +234,7 @@ internal interface GroupByDocs {
      * * [sortBy][GroupBy.sortBy] / [sortByDesc][GroupBy.sortByDesc] — sorts the **order of rows within each group**
      *   by one or more column values;
      * * [updateGroups][GroupBy.updateGroups] — transforms each group into a new one;
-     * * [filter][GroupBy.filter] — filters group rows by the given predicate (as usual [DataFrame.filter]).
+     * * [filter][GroupBy.filter] — filters group rows by the given predicate (as usual [DataFrame.filter]);
      * * [add][GroupBy.add] — adds a new column to each group.
      *
      * Each method returns a new [GroupBy] with updated group order or modified group content.
@@ -392,7 +392,7 @@ public fun <T> DataFrame<T>.groupBy(vararg cols: AnyColumnReference, moveToTop:
  * @include [PivotGroupByDocs.CommonDescription]
  */
 @ExcludeFromSources
-internal interface GroupByForPivotDocs
+private interface GroupByForPivotDocs
 
 /**
  * {@include [GroupByForPivotDocs]}
@@ -508,7 +508,7 @@ public val <T, G> GroupedDataRow<T, G>.group: DataFrame<G>
 public data class GroupWithKey<T, G>(val key: DataRow<T>, val group: DataFrame<G>)
 
 /**
- * A dataframe-like structure that contains all unique combinations of key values
+ * A dataframe-like structure that contains all unique combinations of key-values
  * along with the corresponding groups of rows (each represented as a [DataFrame]).
  *
  * Consists of two main parts:
@@ -571,7 +571,7 @@ public interface GroupBy<out T, out G> : Grouped<G> {
      * a row from [keys] and its corresponding group of rows (as [DataFrame]).
      *
      * If [groupedColumnName] is provided, the groups will be stored
-     * in a [FrameColumn] with that name; otherwise, a default name is used.
+     * in a [FrameColumn] with that name; otherwise, a default name "group" is used.
      *
      * @param groupedColumnName The name of the column in which to store grouped data;
      * if `null`, a default name will be used.

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

@@ -743,6 +743,9 @@ internal fun <T> Pivot<T>.reduce(reducer: Selector<DataFrame<T>, DataRow<T>?>):
 internal inline fun <T> Pivot<T>.delegate(crossinline body: PivotGroupBy<T>.() -> DataFrame<T>): DataRow<T> =
     body(groupBy { none() })[0]
 
+/**
+ * TODO (#1536)
+ */
 internal interface PivotGroupByDocs {
 
     /**

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

@@ -142,11 +142,7 @@ df.groupBy { name }.concat()
 <inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.concatGroupBy.html" width="100%"/>
 <!---END-->
 
-## Reducing
-
-TODO
-
-## Aggregation
+<!---TODO ## Reducing--->
 
 To compute one or several [statistics](summaryStatistics.md) per every group of `GroupBy` use `aggregate` function. 
 Its body will be executed for every data group and has a receiver of type [`DataFrame`](DataFrame.md) that represents current data group being aggregated.