init research

dataframe/docs/StardustDocs/topics/add.md

@@ -0,0 +1,191 @@
+[//]: # (title: add)
+
+<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
+
+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.
+If you want to add a single column to a specific position in the dataframe, use [insert](insert.md).
+
+**Related operations**: [](addRemove.md)
+
+## Create a new column and add it to [`DataFrame`](DataFrame.md)
+
+```text
+add(columnName: String) { rowExpression }
+
+rowExpression: DataRow.(DataRow) -> Value
+```
+
+<!---FUN add-->
+<tabs>
+<tab title="Properties">
+
+```kotlin
+df.add("year of birth") { 2021 - age }
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+df.add("year of birth") { 2021 - "age"<Int>() }
+```
+
+</tab></tabs>
+<inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.add.html" width="100%"/>
+<!---END-->
+
+See [row expressions](DataRow.md#row-expressions)
+
+You can use the `newValue()` function to access value that was already calculated for the preceding row.
+It is helpful for recurrent computations:
+
+<!---FUN addRecurrent-->
+
+```kotlin
+df.add("fibonacci") {
+    if (index() < 2) 1
+    else prev()!!.newValue<Int>() + prev()!!.prev()!!.newValue<Int>()
+}
+```
+
+<inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.addRecurrent.html" width="100%"/>
+<!---END-->
+
+## Create and add several columns to [`DataFrame`](DataFrame.md)
+
+```kotlin
+add { 
+    columnMapping
+    columnMapping
+    ...
+}
+
+columnMapping = column into columnName 
+    | columnName from column 
+    | columnName from { rowExpression }
+    | columnGroupName { 
+        columnMapping
+        columnMapping
+        ...
+    }
+```
+
+<!---FUN addMany-->
+<tabs>
+<tab title="Properties">
+
+```kotlin
+df.add {
+    "year of birth" from { 2021 - age }
+    expr { age > 18 } into "is adult"
+    "details" {
+        name.lastName.map { it.length } into "last name length"
+        "full name" from { name.firstName + " " + name.lastName }
+    }
+}
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+df.add {
+    "year of birth" from { 2021 - "age"<Int>() }
+    expr { "age"<Int>() > 18 } into "is adult"
+    "details" {
+        "name"["lastName"]<String>().map { it.length } into "last name length"
+        "full name" from { "name"["firstName"]<String>() + " " + "name"["lastName"]<String>() }
+    }
+}
+```
+
+</tab></tabs>
+<inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.addMany.html" width="100%"/>
+<!---END-->
+
+### Create columns using intermediate result
+
+Consider this API:
+
+<!---FUN addCalculatedApi-->
+
+```kotlin
+class CityInfo(val city: String?, val population: Int, val location: String)
+
+fun queryCityInfo(city: String?): CityInfo = CityInfo(city, city?.length ?: 0, "35.5 32.2")
+```
+
+<!---END-->
+
+Use the following approach to add multiple columns by calling the given API only once per row:
+
+<!---FUN addCalculated-->
+<tabs>
+<tab title="Properties">
+
+```kotlin
+val personWithCityInfo = df.add {
+    val cityInfo = city.map { queryCityInfo(it) }
+    "cityInfo" {
+        cityInfo.map { it.location } into "location"
+        cityInfo.map { it.population } into "population"
+    }
+}
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+val personWithCityInfo = df.add {
+    val cityInfo = "city"<String?>().map { queryCityInfo(it) }
+    "cityInfo" {
+        cityInfo.map { it.location } into "location"
+        cityInfo.map { it.population } into "population"
+    }
+}
+```
+
+</tab></tabs>
+<!---END-->
+
+## Add existing column to [`DataFrame`](DataFrame.md)
+
+<!---FUN addExisting-->
+
+```kotlin
+val score by columnOf(4, 3, 5, 2, 1, 3, 5)
+
+df.addAll(score)
+df + score
+```
+
+<inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.addExisting.html" width="100%"/>
+<!---END-->
+
+## Add all columns from another [`DataFrame`](DataFrame.md)
+
+<!---FUN addDataFrames-->
+
+```kotlin
+df.addAll(df1, df2)
+```
+
+<inline-frame src="resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.addDataFrames.html" width="100%"/>
+<!---END-->
+
+## addId
+
+Adds a column with sequential values 0, 1, 2,...
+The new column will be added in the beginning of the column list
+and will become the first column in [`DataFrame`](DataFrame.md).
+
+```
+addId(name: String = "id")
+```
+
+**Parameters:**
+* `name: String = "id"` - name of the new column.