# Migration to 1.0

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

## Deprecations and removals

As we move toward version 1.0, many functions have been changed, deprecated, or removed. This section provides a complete overview of all API changes to help you migrate to 1.0.

### Renamed functions and classes to the correct CamelCase spelling

All functions and classes in Kotlin DataFrame have been renamed to [the correct CamelCase spelling](https://developer.android.com/kotlin/style-guide#camel_case).

See below for a complete list of the renamed functions and classes.

### Migration to Deephaven CSV

All CSV (as well as TSV) IO was migrated to a new, fast, and efficient [Deephaven CSV](https://github.com/deephaven/deephaven-csv) implementation. It significantly improves CSV IO performance and brings many new parametrization options.

All related methods are now located in the separate [dataframe-csv](modules.html#dataframe-csv) module (which is included by default in the general [dataframe](modules.html#dataframe-general) artifact and in `%use dataframe` in [Kotlin Notebook](setupkotlinnotebook.html)).

Functions were also renamed to [the correct CamelCase spelling](#camelCase).

All new functions keep the same arguments as before and additionally introduce new ones. Also, [there are new arguments that expose Deephaven CSV features](read.html#unlocking-deephaven-csv-features).

See [Read from CSV](read.html#read-from-csv).

> **Tip:**
> All outdated CSV IO functions raise `WARNING` in 1.0 and will raise `ERROR` in 1.1.

| 0.15 | 1.0 |
| --- | --- |
| `CSV`/`TSV` | `CsvDeephaven`/`TsvDeephaven` |
| `DataFrame.readCSV(..)`/`DataFrame.readTSV(..)` | `DataFrame.readCsv(..)`/`DataFrame.readTsv(..)` |
| `DataFrame.read(delimiter=.., ..)` | `DataFrame.readCsv(delimiter=.., ..)` |
| `df.writeCSV(..)`/`df.writeTSV(..)` | `df.writeCsv(..)`/`df.writeTsv(..)` |
| `df.toCSV(..)` | `df.toCsvStr(..)` |

###  Deprecation of `BigDecimal` and `BigInteger` statistics 

The [statistical operations](summarystatistics.html) that compute with values — [sum](sum.html), [mean](mean.html), [std](std.html), and [cumSum](cumsum.html) — no longer support `java.math.BigDecimal` and `java.math.BigInteger` columns, due to their type-specific arithmetic semantics and to maintain consistent behavior across numeric types. Calling them on columns of either type now throws an exception at runtime.

Convert the column to a list and use Kotlin standard library functions and Java big numbers arithmetic instead. Alternatively, you can [convert](convert.html) them to primitive types before calling the statistical operations.

The operations that only compare values — [min/max](minmax.html), including their `by` overloads — keep working with big numbers. [median](median.html) and [percentile](percentile.html) are no longer explicitly supported for big numbers: some of their overloads still return a non-interpolated value, while others throw at runtime.

The following examples assume that `bigIntCol` and `bigDecimalCol` are nullable columns of `BigInteger` and `BigDecimal`.

| 0.15 | 1.0 |
| --- | --- |
| `df.bigIntCol.sum()` | `df.bigIntCol.toList().filterNotNull().sumOf { it }` |
| `df.bigDecimalCol.sum()` | `df.bigDecimalCol.toList().filterNotNull().sumOf { it }` |
| `df.sum { bigIntCol and bigDecimalCol }` | `df.bigIntCol.toList().filterNotNull().sumOf { it }.toBigDecimal() + df.bigDecimalCol.toList().filterNotNull().sumOf { it }` |
| `df.bigIntCol.mean()` | `df.bigIntCol.toList().filterNotNull().let { values -> values.sumOf { it }.toBigDecimal().divide(values.size.toBigDecimal(), MathContext.DECIMAL128) }` |
| `df.bigDecimalCol.mean()` | `df.bigDecimalCol.toList().filterNotNull().let { values -> values.sumOf { it }.divide(values.size.toBigDecimal(), MathContext.DECIMAL128) }` |

Java arithmetics:

| 0.15 | 1.0 |
| --- | --- |
| `df.bigIntCol.sum()` | `df.bigIntCol.toList().filterNotNull().fold(BigInteger.ZERO, BigInteger::add)` |
| `df.bigDecimalCol.sum()` | `df.bigDecimalCol.toList().filterNotNull().fold(BigDecimal.ZERO, BigDecimal::add)` |

All other Kotlin DataFrame operations continue to work as usual:

```KOTLIN
df.filter { bigDecimalCol?.let { it > BigDecimal.valueOf(150.0) } == true }
```

###  Column name repair standardization and `NameRepairStrategy` deprecation 

Now all `DataFrame` creation / reading methods handle duplicating column names the same way.

`NameRepairStrategy` and `readExcel()` overloads that use it are deprecated.

| 0.15 | 1.0 |
| --- | --- |
| `DataFrame.readExcel(nameRepairStrategy = ..)` | Deprecated |

###  Migration to Standard Library `Instant` 

Since Kotlin 2.1.20, [Instant is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)

(as `kotlin.time.Instant`). You can still use the old (deprecated) `kotlinx.datetime.Instant` type, but its support will be removed in Kotlin DataFrame 1.1.

> **Note:**
> New `Instant` in the Kotlin Standard Library becomes stable in 2.3.0. In earlier versions, all related operations should be marked with the `@OptIn(ExperimentalTime::class)` annotation.

For now, each `Instant`-related operation has been split into two new ones — one for the new stdlib `kotlin.time.Instant` and one for the old deprecated `kotlinx.datetime.Instant`. The behavior of old operations remains unchanged: they work with `kotlinx.datetime.Instant` and raise `ERROR` in 1.0. In version 1.1, they will be returned and will operate on the new stdlib `kotlin.time.Instant`.

| 0.15 | 1.0 | Note |
| --- | --- | --- |
| `col.convertToInstant()` | `col.convertToDeprecatedInstant()` | `WARNING` in 1.0, `ERROR` in 1.1 |
| `col.convertToStdlibInstant()` | Will be renamed back into `convertToInstant()` in 1.1 |
| `df.convert { columns }.toInstant()` | `df.convert { columns }.convertToDeprecatedInstant()` | `WARNING` in 1.0, `ERROR` in 1.1 |
| `df.convert { columns }.convertToStdlibInstant()` | Will be renamed back into `convertToInstant()` in 1.1 |
| `ColType.Instant` | `ColType.DeprecatedInstant` | `WARNING` in 1.0, `ERROR` in 1.1 |
| `ColType.StdlibInstant` | Will be renamed back into `Instant` in 1.1 |

In version 1.0-Beta5 and later, all parsing operations convert `Instant` values into the new standard library `kotlin.time.Instant` type by default. To enable parsing into the deprecated `kotlinx.datetime.Instant`, set the corresponding parsing option `ParserOptions.parseExperimentalInstant = false` (before 1.0-Beta5, this option was `false`, from 1.0-Beta5 onwards it is `true` by default).

For example:

```KOTLIN
DataFrame.readCsv(
    ...,
parserOptions = ParserOptions(parseExperimentalInstant = false)
)
```

###  Deprecation of `cols()` and other methods in Columns Selection DSL 

`cols()` overloads without arguments, which select all columns of a DataFrame or all subcolumns inside a column group in the [Columns Selection DSL](columnselectors.html), are deprecated in favor of `all()` and `allCols()` respectively. These replacements allow the [Compiler Plugin](compiler-plugin.html) to fully support such selections.

`colsAtAnyDepth()`, `colsInGroups()`, and `single()` overloads with a `predicate` argument that filters columns are also deprecated for better Compiler Plugin support. Use `.filter(predicate)` for filtering instead.

| 0.15 | 1.0 |
| --- | --- |
| `df.select { cols() }` | `df.select { all() }` |
| `df.select { colGroup.cols() }` | `df.select { colGroup.allCols() }` |
| `df.select { colsAtAnyDepth { predicate } }` | `df.select { colsAtAnyDepth().filter { predicate } }` |
| `df.select { colsInGroups { predicate } }` | `df.select { colsInGroups().filter { predicate } }` |
| `df.select { single { predicate } }` | `df.select { cols().filter { predicate }.single() }` |
| `df.select { colGroup.singleCol { predicate } }` | `df.select { colGroup.allCols().filter { predicate }.single() }` |
| `df.select { colSet.single { predicate } }` | `df.select { colSet.filter { predicate }.single() }` |

###  `reorderColumnsBy` and `reorderColumnsByName` no longer reorder inside frame columns by default 

With `atAnyDepth = true` (the default), [reorderColumnsBy](reorder.html#reordercolumnsby) and [reorderColumnsByName](reorder.html#reordercolumnsbyname) now reorder the columns inside column groups only, like `colsAtAnyDepth()`. The columns inside the dataframes of frame columns keep their order. To reorder them too, as before, pass `inFrameColumns = true`: `df.reorderColumnsByName(inFrameColumns = true)`.

###  `GroupBy.sortBy` and `sortByDesc` no longer reorder groups 

[GroupBy.sortBy](sortby.html#sorting-within-groups) and `GroupBy.sortByDesc` now sort rows only within each group and preserve the order of key-group pairs. To sort the groups themselves by their keys, use `sortByKey` or `sortByKeyDesc` instead. If both the groups and their rows need to be sorted, call the corresponding operations separately.

| 0.15 | 1.0 |
| --- | --- |
| `df.groupBy { city }.sortBy { city and day }` | `df.groupBy { city }.sortByKey().sortBy { day }` |

### Removed functions and classes

The following functions and classes raise `ERROR` in 1.0 and will be removed in 1.1.

| 0.15 | 1.0 | Reason |
| --- | --- | --- |
| `DataColumn.createFrameColumn(name, df, startIndices)` | `df.chunked(name, startIndices)` | Replaced with another function. |
| `DataColumn.createWithTypeInference(name, values, nullable)` | `DataColumn.createByInference(name, values, TypeSuggestion.Infer, nullable)` | Replaced with another function. |
| `DataColumn.create(name, values, infer)` | `DataColumn.createByType(name, values, infer)` | Replaced with another function. |
| `col.isComparable()` | `col.valuesAreComparable()` | Renamed to better reflect its purpose. |
| `df.minus { columns }` | `df.remove { columns }` | Replaced with another function. |
| `df.move { columns }.toLeft()`/`df.moveToLeft{ columns }` | `df.move { columns }.toStart()`/`df.moveToStart { columns }` | Renamed to better reflect its purpose. |
| `df.move { columns }.toRight()`/`df.moveToRight{ columns }` | `df.move { columns }.toEnd()`/`df.moveToEnd{ columns }` | Renamed to better reflect its purpose. |
| `row.rowMin()`/`row.rowMinOrNull()` | `row.rowMinOf()`/`row.rowMinOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowMax()`/`row.rowMaxOrNull()` | `row.rowMaxOf()`/`AnyRow.rowMaxOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowPercentile()`/`row.rowPercentileOrNull()` | `row.rowPercentileOf()`/`row.rowPercentileOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowMedian()`/`row.rowMedianOrNull()` | `row.rowMedianOf()`/`row.rowMedianOfOrNull()` | Renamed to better reflect its purpose. |
| `df.convert { columns }.to { converter }` | `df.convert { columns }.asColumn { converter }` | Renamed to better reflect its purpose. |
| `df.toHTML(..)`/`df.toStandaloneHTML()` | `df.toHtml(..)`/`df.toStandaloneHtml()` | Renamed to the correct CamelCase. |
| `df.writeHTML()` | `df.writeHtml()` | Renamed to the correct CamelCase. |
| `asURL(fileOrUrl)`/`isURL(path)` | `asUrl(fileOrUrl)`/`isUrl(path)` | Renamed to the correct CamelCase. |
| `df.convert { columns }.toURL()`/`df.convertToURL { columns }` | `df.convert { columns }.toUrl()`/`df.convertToUrl { columns }` | Renamed to the correct CamelCase. |
| `df.filterBy(column)` | `df.filter { column }` | Replaced with another function. |
| `FormattingDSL` | `FormattingDsl` | Renamed to the correct CamelCase. |
| `RGBColor` | `RgbColor` | Renamed to the correct CamelCase. |
| `df.insert(column).after(columnPath)` | `df.insert(column).after { columnPath }` | Replaced with another overload. |
| `df.insert(column).under(columnPath)` | `df.insert(column).under { columnPath }` | Replaced with another overload. |
| `CompareResult.Equals` / `CompareResult.isEqual()` | `CompareResult.Matches` / `CompareResult.matches()` | Renamed to better reflect its purpose. |
| `CompareResult.isSuperOrEqual()` | `CompareResult.isSuperOrMatches()` | Renamed to better reflect its purpose. |

The following functions and classes raise `WARNING` in 1.0 and `ERROR` in 1.1.

| 0.15 | 1.0 | Reason |
| --- | --- | --- |
| `df.split { columns }.default(..)` / `df.split { columns }.into(..)` / `df.split { columns }.inward(..)` | `df.split { columns }.by(..).default(..)` / `df.split { columns }.by(..).into(..)` / `df.split { columns }.by(..).inward(..)` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `dataFrameOf(header, values)` | `dataFrameOf(header).withValues(values)` | Replaced with another function. |
| `df.generateCode(..)` | `df.generateInterfaces(..)` | Replaced with another function. |
| `df.select { mapToColumn(name, infer) { body } }` | `df.select { expr(name, infer) { body } }` | Removed duplicated functionality. |
| `stringCol.length()` | `stringCol.map { it?.length ?: 0 }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `stringCol.lowercase()` / `stringCol.uppercase()` | `stringCol.map { it?.lowercase() }` / `stringCol.map { it?.uppercase() }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `df.add(columns)` / `df.add(dataframes)` | `df.addAll(columns)` / `df.addAll(dataframes)` | Renamed to improve completion. |
| `row.isEmpty()` / `row.isNotEmpty()` | `row.values().all { it == null }` / `row.values().any { it != null }` | Removed a shortcut to clarify the behaviour; |
| `row.getRow(index)` /  `row.getRowOrNull(index)` / `row.getRows(indices)` | `row.df().getRow(index)` /  `row.df().getRowOrNull(index)` / `row.df().getRows(indices)` | Removed a shortcut to clarify the behaviour; |
| `df.copy()` | `df.columns().toDataFrame().cast()` | Removed a shortcut to clarify the behaviour; |
| `KeyValueProperty<T>` | `NameValueProperty<T>` | Removed duplicated functionality. |
| `rename { columns }.into(..)` (will remain WARNING) | `rename { columns }.to(..)` | Renamed to better reflect the English sentence "rename this column to that". |
| `df.sortBy { col.desc() }` / `df.sortByDesc { col.desc() }` | `df.sortBy { col.reversed() }` / `df.sortByDesc { col.reversed() }` | Renamed to better reflect its purpose. |

## Parsing and Converting Date-Time

In 0.15 and up to 1.0-Beta4 we did support the [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime) types; however, they were still treated as second-class in DataFrame. [ParserOptions](parse.html#parser-options) were still built around the Java `DataTimeFormatter`-paradigm. Starting from 1.0-Beta5, [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime) types now become first-class citizens, while still allowing you to use Java types if you need them.

| 0.15 | 1.0 | Reason |
| --- | --- | --- |
|    ```KOTLIN df.parse() ```    |    ```KOTLIN df.parse() ```    | Default parsing behavior remains largely unchanged. |
|    ```KOTLIN df.parse(     ParserOptions(         skipTypes = setOf(             typeOf<kotlinx.datetime.LocalDate>(),             ...,     ), ), ) ```    |    ```KOTLIN df.parse(     ParserOptions(dateTime = DateTimeParserOptions.Java), ) ```    | If you want to force parsing to Java date-time types, you no longer have to use skipTypes; you can simply change the `dateTime` argument. |
|    ```KOTLIN DataFrame.parser.addSkipType(     typeOf<kotlinx.datetime.LocalDate>(), ) ```    |    ```KOTLIN DataFrame.parser.dateTimeLibrary = ParseDateTimeLibrary.JAVA ```    | The same logic applies for the [global parser options](parse.html#global-parser-options). |
|    ```KOTLIN ParserOptions(dateTimeFormatter = myFormatter) ```    |  Kotlin:   ```KOTLIN ParserOptions(     dateTime = DateTimeParserOptions.Kotlin         .withFormat<_>(myKotlinFormat), ) ```    | You now need to explicitly specify you expect Java or Kotlin date-time types via `DateTimeParserOptions.X`. Then you can specify the relevant options, like a `kotlinx.datetime.format.DateTimeFormat` or `java.time.DateTimeFormatter`. These are typed now too, optionally for Java. |
|  Java:   ```KOTLIN ParserOptions(     dateTime = DateTimeParserOptions.Java         .withFormatter<java.time.LocalDateTime>(myJavaFormatter), ) ```    |
|    ```KOTLIN ParserOptions(     locale = myLocale,     dateTimeFormatter = myFormatter, ) ```    |    ```KOTLIN ParserOptions(     dateTime = DateTimeParserOptions.Java         .withLocale(myLocale)         .withFormatter<java.time.LocalDateTime>(myFormatter), ) ```    | Locale for date-time only works for Java types. If you need Kotlin types and a locale, use [convert](convert.html) to convert to Kotlin types afterwards. |
|    ```KOTLIN ParserOptions(dateTimePattern = "MM/dd yyyy") ```    |  Kotlin:   ```KOTLIN @OptIn(FormatStringsInDatetimeFormats::class) ParserOptions(     dateTime = DateTimeParserOptions.Kotlin         .withPattern<kotlinx.datetime.LocalDate>("MM/dd yyyy"), ) ```    | Again, you now need to specify the target date-time library and the expected type for your pattern (optionally for Java). In Kotlin you also need to opt-in, because using `DateTimeFormat` instead is [recommended](https://github.com/Kotlin/kotlinx-datetime#using-unicode-format-strings-like-yyyy-mm-dd). |
|  Java:   ```KOTLIN ParserOptions(     dateTime = DateTimeParserOptions.Java         .withPattern<java.time.LocalDate>("MM/dd yyyy"), ) ```    |
|    ```KOTLIN DataFrame.parser.addDateTimePattern("MM/dd yyyy") ```    |  Kotlin:   ```KOTLIN @OptIn(FormatStringsInDatetimeFormats::class) DataFrame.parser     .addDateTimeUnicodePattern<kotlinx.datetime.LocalDate>("MM/dd yyyy") ```    | Same idea. Though you can now also use `...addDateTimeFormat()` / `...addJavaDateTimeFormatter()`, which we would recommend more. |
|  Java:   ```KOTLIN DataFrame.parser     .addJavaDateTimePattern<java.time.LocalDate>("MM/dd yyyy") ```    |
|    ```KOTLIN convert { stringCols }.toLocalDate(pattern = "MM/dd yyyy") ```    |  Kotlin:   ```KOTLIN @OptIn(FormatStringsInDatetimeFormats::class) convert { stringCols }.toLocalDate(pattern = "MM/dd yyyy") ```    | Same logic applies to convert: you need to opt-in to use patterns for Kotlin types and specify "Java" for Java types. |
|  Java:   ```KOTLIN convert { stringCols }.toJavaLocalDate(pattern = "MM/dd yyyy") ```    |
|    ```KOTLIN stringCol.convertToLocalDate(locale = Locale.GERMAN) ```    |    ```KOTLIN stringCol     .convertToJavaLocalDate(locale = Locale.GERMAN)     .convertToLocalDate() ```    | If you need to supply a locale to be able to parse date-time types, parse to Java types first, then convert to Kotlin ones. |

For more information, check out [Parsing Date-time Strings](parse.html#parsing-date-time-strings).

