Merge pull request #1226 from Kotlin/cs-dsl-links

Adding links to column selectors in docs

Author: Jolanrensen

docs/StardustDocs/topics/add.md

@@ -2,7 +2,7 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-Returns [`DataFrame`](DataFrame.md) which contains all columns from original [`DataFrame`](DataFrame.md) followed by newly added columns. 
+Returns [`DataFrame`](DataFrame.md) which contains all columns from the original [`DataFrame`](DataFrame.md) followed by newly added columns. 
 Original [`DataFrame`](DataFrame.md) is not modified.
 
 `add` appends columns to the end of the dataframe by default.

docs/StardustDocs/topics/convert.md

@@ -13,7 +13,8 @@ colExpression = DataFrame.(DataColumn) -> DataColumn
 frameExpression: DataFrame.(DataFrame) -> DataFrame
 ```
 
-See [column selectors](ColumnSelectors.md) and [row expressions](DataRow.md#row-expressions)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation and
+[row expressions](DataRow.md#row-expressions) for how to provide new values.
 
 <!---FUN convert-->
 

docs/StardustDocs/topics/corr.md

@@ -9,6 +9,8 @@ corr { columns1 }
     .with { columns2 } | .withItself()
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 To compute pairwise correlation between all columns in the [`DataFrame`](DataFrame.md) use `corr` without arguments:
 
 ```kotlin
@@ -19,7 +21,7 @@ The function is available for numeric- and `Boolean` columns.
 `Boolean` values are converted into `1` for `true` and `0` for `false`.
 All other columns are ignored.
 
-If a [`ColumnGroup`](DataColumn.md#columngroup) instance is passed as target column for correlation,
+If a [`ColumnGroup`](DataColumn.md#columngroup) instance is passed as the target column for correlation,
 it will be unpacked into suitable nested columns.
 
 The resulting [`DataFrame`](DataFrame.md) will have `n1` rows and `n2+1` columns,

docs/StardustDocs/topics/cumSum.md

@@ -10,6 +10,8 @@ cumSum(skipNA = true) [ { columns } ]
 
 Returns a [`DataFrame`](DataFrame.md) or [`DataColumn`](DataColumn.md) containing the cumulative sum.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 **Parameters:**
 * `skipNA` — when `true`, ignores [`NA` values](nanAndNa.md#na) (`null` or `NaN`). 
   When `false`, all values after first `NA` will be `NaN` (for `Double` and `Float` columns) or `null` (for integer columns).

docs/StardustDocs/topics/distinct.md

@@ -16,6 +16,8 @@ df.distinct()
 
 If columns are specified, resulting [`DataFrame`](DataFrame.md) will have only given columns with distinct values.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN distinctColumns-->
 <tabs>
 <tab title="Properties">
@@ -43,6 +45,8 @@ df.select("age", "name").distinct()
 
 Keep only the first row for every group of rows grouped by some condition.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN distinctBy-->
 <tabs>
 <tab title="Properties">

docs/StardustDocs/topics/drop.md

@@ -27,6 +27,8 @@ df.drop { it["weight"] == null || it["city"] == null }
 
 Remove rows with `null` values
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN dropNulls-->
 
 ```kotlin
@@ -44,6 +46,8 @@ df.dropNulls(whereAllNull = true) { city and weight } // remove rows with null v
 
 Remove rows with [`NaN` values](nanAndNa.md#nan) (`Double.NaN` or `Float.NaN`).
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN dropNaNs-->
 
 ```kotlin
@@ -61,6 +65,8 @@ df.dropNaNs(whereAllNaN = true) { age and weight } // remove rows where both 'ag
 
 Remove rows with [`NA` values](nanAndNa.md#na) (`null`, `Double.NaN`, or `Float.NaN`).
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN dropNA-->
 
 ```kotlin

docs/StardustDocs/topics/explode.md

@@ -8,6 +8,8 @@ Splits list-like values in given columns and spreads them vertically. Values in
 explode(dropEmpty = true) [ { columns } ]
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 **Parameters:**
 * `dropEmpty` — if `true`, removes rows with empty lists or [`DataFrame`](DataFrame.md) objects. Otherwise, they will be exploded into `null`.
 

docs/StardustDocs/topics/fill.md

@@ -8,6 +8,8 @@ Replace missing values.
 
 Replaces `null` values with given value or expression. 
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN fillNulls-->
 
 ```kotlin
@@ -23,6 +25,8 @@ df.update { colsOf<Int?>() }.where { it == null }.with { -1 }
 
 Replaces [`NaN` values](nanAndNa.md#nan) (`Double.NaN` and `Float.NaN`) with given value or expression.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN fillNaNs-->
 
 ```kotlin
@@ -36,6 +40,8 @@ df.fillNaNs { colsOf<Double>() }.withZero()
 
 Replaces [`NA` values](nanAndNa.md#na) (`null`, `Double.NaN`, and `Float.NaN`) with given value or expression.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN fillNA-->
 
 ```kotlin

docs/StardustDocs/topics/filter.md

@@ -25,7 +25,9 @@ df.filter { "age"<Int>() > 18 && "name"["firstName"]<String>().startsWith("A") }
 
 ## filterBy
 
-Returns [`DataFrame`](DataFrame.md) with rows that have value `true` in given column of type `Boolean`.
+Returns [`DataFrame`](DataFrame.md) with rows that have value `true` in the given column of type `Boolean`.
+
+See [column selectors](ColumnSelectors.md) for how to select the column for this operation.
 
 <!---FUN filterBy-->
 <tabs>

docs/StardustDocs/topics/flatten.md

@@ -8,7 +8,10 @@ Returns [`DataFrame`](DataFrame.md) without column groupings under selected colu
 flatten  [ { columns } ]
 ```
 
-Columns after flattening will keep their original names. Potential column name clashes are resolved by adding minimal possible name prefix from ancestor columns.
+Columns will keep their original names after flattening.
+Potential column name clashes are resolved by adding minimal possible name prefix from ancestor columns.
+
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
 <!---FUN flatten-->
 <tabs>

docs/StardustDocs/topics/gather.md

@@ -4,7 +4,7 @@
 
 Converts several columns into two columns `key` and `value`. `key` column will contain names of original columns, `value` column will contain values from original columns.
 
-This operation is reverse to [pivot](pivot.md)
+This operation is reverse to [](pivot.md)
 
 ```kotlin
 gather { columns }
@@ -21,7 +21,7 @@ keyTransform: (columnName: String) -> K
 valueTransform: (value) -> R 
 ```
 
-See [column selectors](ColumnSelectors.md)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
 Configuration options:
 * `explodeLists` — gathered values of type [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) will be exploded into their elements, so `where`, `cast`, `notNull` and `mapValues` will be applied to list elements instead of lists themselves

docs/StardustDocs/topics/group.md

@@ -15,6 +15,8 @@ groupNameExpression = DataColumn.(DataColumn) -> String
 
 It is a special case of [`move`](move.md) operation.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN group-->
 
 ```kotlin

docs/StardustDocs/topics/groupBy.md

@@ -24,7 +24,8 @@ pivot = .pivot { columns }
          pivotReducer | pivotAggregator  
 ```
 
-See [column selectors](ColumnSelectors.md), [groupBy transformations](#transformation), [groupBy aggregations](#aggregation), [pivot+groupBy](pivot.md#pivot-groupby)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation,
+[groupBy transformations](#transformation), [groupBy aggregations](#aggregation), and [pivot+groupBy](pivot.md#pivot-groupby).
 
 <!---FUN groupBy-->
 <tabs>

docs/StardustDocs/topics/implode.md

@@ -8,6 +8,8 @@ Returns [`DataFrame`](DataFrame.md) where values in given columns are merged int
 implode(dropNA = false) [ { columns } ]
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 **Parameters:**
 * `dropNA` — if `true`, removes `NA` values from merged lists.
 

docs/StardustDocs/topics/inferType.md

@@ -2,8 +2,10 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-Changes type of the selected columns based on actual values stored in these columns. Resulting type of the column will be a nearest common supertype of all column values.
+Changes the type of the selected columns based on the runtime values stored in these columns.
+The resulting type of the column will be the nearest common supertype of all column values.
 
 ```text
 inferType [ { columns } ]
 ```
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.

docs/StardustDocs/topics/mean.md

@@ -43,6 +43,8 @@ df.pivot { city }.groupBy { name.lastName }.mean()
 
 See [statistics](summaryStatistics.md#groupby-statistics) for details on complex data aggregations.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 ### Type Conversion
 
 The following automatic type conversions are performed for the `mean` operation:

docs/StardustDocs/topics/median.md

@@ -51,6 +51,8 @@ df.pivot { city }.groupBy { name.lastName }.median()
 
 See [statistics](summaryStatistics.md#groupby-statistics) for details on complex data aggregations.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 ### Type Conversion
 
 The following automatic type conversions are performed for the `median` operation.

docs/StardustDocs/topics/merge.md

@@ -15,6 +15,8 @@ merge { columns }
 merger: (DataRow).List<T> -> Any
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN merge-->
 
 ```kotlin

docs/StardustDocs/topics/minmax.md

@@ -42,6 +42,8 @@ df.pivot { city }.groupBy { name.lastName }.min()
 
 See [statistics](summaryStatistics.md#groupby-statistics) for details on complex data aggregations.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 ### Type Conversion
 
 The following automatic type conversions are performed for the `min` and `max` operations.

docs/StardustDocs/topics/move.md

@@ -11,9 +11,9 @@ move { columns }
 pathSelector: DataFrame.(DataColumn) -> ColumnPath
 ```
 
-See [Column Selectors](ColumnSelectors.md)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
-Can be used to change columns hierarchy by providing `ColumnPath` for every moved column
+Can be used to change column hierarchy by providing `ColumnPath` for every moved column.
 
 <!---FUN move-->
 

docs/StardustDocs/topics/percentile.md

@@ -73,6 +73,8 @@ df.pivot { city }.groupBy { name.lastName }.percentile(25.0)
 
 See [statistics](summaryStatistics.md#groupby-statistics) for details on complex data aggregations.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 ### Type Conversion
 
 The following automatic type conversions are performed for the `percentile` operation.

docs/StardustDocs/topics/pivot.md

@@ -2,7 +2,7 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Analyze-->
 
-Splits the rows of [`DataFrame`](DataFrame.md) and groups them horizontally into new columns based on values from one or several columns of original [`DataFrame`](DataFrame.md).
+Splits the rows of a [`DataFrame`](DataFrame.md) and groups them horizontally into new columns based on values from one or several columns of the original [`DataFrame`](DataFrame.md).
 
 ```text
 pivot (inward = true) { pivotColumns }
@@ -16,8 +16,10 @@ reducer = .minBy { column } | .maxBy { column } | .first [ { rowCondition } ] |
 aggregator = .count() | .matches() | .frames() | .with { rowExpression } | .values { valueColumns } | .aggregate { aggregations } | .<stat> [ { columns } ]
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 **Parameters:**
-* `inward` — if `true` generated columns will be nested inside original column, otherwise they will be top-level
+* `inward` — if `true` generated columns are nested inside the original column, otherwise they will be top-level
 * `pivotColumns` — columns with values for horizontal data grouping and generation of new columns
 * `indexColumns` — columns with values for vertical data grouping
 * `defaultValue` — value to fill mismatched pivot-index column pairs
@@ -42,7 +44,7 @@ df.pivot("city")
 <inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Analyze.pivot.html" width="100%"/>
 <!---END-->
 
-To pivot several columns at once you can combine them using `and` or `then` infix function:
+To pivot several columns at once, you can combine them using `and` or `then` infix function:
 * `and` will pivot columns independently
 * `then` will create column hierarchy from combinations of values from pivoted columns
 
@@ -69,7 +71,8 @@ df.pivot { "city" then "name"["firstName"] }
 
 ## pivot + groupBy
 
-To create matrix table that is expanded both horizontally and vertically, apply [`groupBy`](groupBy.md) transformation passing the columns for vertical grouping. 
+To create a matrix table that is expanded both horizontally and vertically,
+apply [`groupBy`](groupBy.md) transformation passing the columns for vertical grouping. 
 Reversed order of `pivot` and [`groupBy`](groupBy.md) will produce the same result.
 
 <!---FUN pivotGroupBy-->
@@ -264,7 +267,7 @@ df.pivot("city").groupBy("name").aggregate {
 ### Pivot inside aggregate
 
 pivot transformation can be used inside [`aggregate`](groupBy.md#aggregation) function of [`groupBy`](groupBy.md). 
-This allows to combine column pivoting with other [`groupBy`](groupBy.md) aggregations:
+This allows combining column pivoting with other [`groupBy`](groupBy.md) aggregations:
 
 <!---FUN pivotInAggregate-->
 <tabs>

docs/StardustDocs/topics/remove.md

@@ -8,7 +8,7 @@ Returns [`DataFrame`](DataFrame.md) without selected columns.
 remove { columns }
 ```
 
-See [Column Selectors](ColumnSelectors.md)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
 <!---FUN remove-->
 <tabs>

docs/StardustDocs/topics/rename.md

@@ -11,6 +11,8 @@ df.rename { columns }.into { nameExpression }
 nameExpression = (DataColumn) -> String
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN rename-->
 <tabs>
 <tab title="Properties">

docs/StardustDocs/topics/reorder.md

@@ -12,6 +12,8 @@ reorder { columns }
 columnExpression: DataColumn.(DataColumn) -> Value
 ```
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN reorder-->
 <tabs>
 <tab title="Properties">

docs/StardustDocs/topics/replace.md

@@ -10,7 +10,7 @@ replace { columns }
 columnExpression: DataFrame.(DataColumn) -> DataColumn
 ```
 
-See [column selectors](ColumnSelectors.md)
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
 <!---FUN replace-->
 

docs/StardustDocs/topics/reshape.md

@@ -8,6 +8,8 @@ By default, columns are sorted in ascending order with `null` values going first
 * `.desc` — changes column sort order from ascending to descending
 * `.nullsLast` — forces `null` values to be placed at the end of the order
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN sortBy-->
 <tabs>
 <tab title="Properties">
@@ -35,6 +37,8 @@ df.sortBy { "weight".nullsLast() }
 
 Returns [`DataFrame`](DataFrame.md) sorted by one or several columns in descending order.
 
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
+
 <!---FUN sortByDesc-->
 <tabs>
 <tab title="Properties">

docs/StardustDocs/topics/sortBy.md

@@ -2,7 +2,7 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-This operation splits every value in the given columns into several values,
+This operation splits every value in the given columns into several values 
 and optionally spreads them horizontally or vertically.
 
 ```text
@@ -15,10 +15,12 @@ df.split { columns }
 splitter = DataRow.(T) -> Iterable<Any>
 columnNamesGenerator = DataColumn.(columnIndex: Int) -> String
 ```
-The following types of columns can be split without any _splitter_ configuration:
-* `String`: split by `,` and trim
-* `List`: split into elements
-* [`DataFrame`](DataFrame.md): split into rows
+The following types of columns can be split easily:
+* `String`: for instance, by `","`
+* `List`: splits into elements, no `by` required!
+* [`DataFrame`](DataFrame.md): splits into rows, no `by` required!
+
+See [column selectors](ColumnSelectors.md) for how to select the columns for this operation.
 
 ## Split in place