# gather

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

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.

API reference: [gather](https://kotlin.github.io/dataframe/api-docs/core/org.jetbrains.kotlinx.dataframe.api/gather.html)

Reverse operation: [pivot](pivot.html)

```KOTLIN
gather { columns }
    [.explodeLists()]
    [.cast<Type>()]
    [.notNull()]
    [.where { valueFilter }]
    [.mapKeys { keyTransform }]
    [.mapValues { valueTransform }]
    .into(keyColumn, valueColumn) | .keysInto(keyColumn) | .valuesInto(valueColumn)

valueFilter: (value) -> Boolean
keyTransform: (columnName: String) -> K
valueTransform: (value) -> R 
```

See [column selectors](columnselectors.html) 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

* `cast` — inform the compiler about the expected type of gathered elements. This type will be passed to the `where`, `notNull` and `mapValues` lambdas

* `notNull` — skip gathered `null` values

* `where` — filter gathered values

* `mapKeys` — transform gathered column names (keys)

* `mapValues` — transform gathered column values

Storage options:

* `into(keyColumn, valueColumn)` — store gathered key-value pairs in two new columns with names `keyColumn` and `valueColumn`

* `keysInto(keyColumn)` — store only gathered keys (column names) in a new column `keyColumn`

* `valuesInto(valueColumn)` — store only gathered values in a new column `valueColumn`

```KOTLIN
pivoted.gather { "London".."Tokyo" }.into("city", "population")
```

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.gather.html)

```KOTLIN
pivoted.gather { "London".."Tokyo" }
    .cast<Int>()
    .where { it == 1 }
    .mapKeys { it.lowercase() }
    .mapValues { 1.0 / it }
    .into("city", "density")
```

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.gatherWithMapping.html)