--- title: "Differences with Python Polars" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Differences with Python Polars} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` We try to mimic the Python Polars API as much as possible so that one can quickly switch and copy code between the two languages with as little adjustments to make as possible (most of the time switching `.` and `$` to chain methods). Still, there are a few places where the API diverges. This is often due to differences in the language itself. This vignette provides a list of those differences. ## Converting data between Polars and R ### From R to Polars The R package provides functions to create polars `DataFrame`, `LazyFrame`, and `Series`. Like most of the functions, those are designed to be close to their Python counterparts. Still, R users are more used to `as.*` or `as_*` functions to convert from or to other R objects. Therefore, in the documentation, we sometimes prefer using `as_polars_df()` rather than `pl$DataFrame()`. ### From Polars to R While Python Polars has `to_pandas()`, we provide methods to convert Polars data to standard R objects, such as `$to_list()` or `$to_data_frame()`. However, the standard R user might find it more familiar to call `as.data.frame()`, `as.list()` or `as.vector()` on Polars structures. ## 64-bit integers R doesn't natively support 64-bit integers (Int64) but this is a completely valid data type in Polars, which is based on the Arrow specification. This means that handling Int64 values in `polars` objects doesn't deviate from the Python setting. However, we need to implement some extra arguments when we want to pass data from Polars to R. In particular, all functions that convert some polars data to R (`as.data.frame()` and other methods such as `$to_list()`) have an argument `int64_conversion` which specifies how Int64 values should be handled. The default is to convert those Int64 to Float64, but it is also possible to convert them to character or to keep them as Int64 by using the package `bit64` under the hood. This option can be set globally using `options(polars.int64_conversion = "")`. See `?polars_options()` for more details. ## The `Object` data type `Object` is a data type for wrapping arbitrary Python objects. Therefore, it doesn't have an equivalent in R. When the user passes R objects with unsupported class to `polars`, it will first try to convert them to a supported data type. For example, so far the class `hms` from the eponymous package is not supported, so we try to convert it to a numeric class: ``` r hms::hms(56, 34, 12) #> 12:34:56 pl$DataFrame(x = hms::hms(56, 34, 12)) #> shape: (1, 1) #> ┌─────────┐ #> │ x │ #> │ --- │ #> │ f64 │ #> ╞═════════╡ #> │ 45296.0 │ #> └─────────┘ ``` In some cases, there's no conversion possible. For example, one cannot convert a `geos` geometry to any supported data type. In this case, it will raise an error: ``` r geos::as_geos_geometry("LINESTRING (0 1, 3 9)") #> #> [1] pl$DataFrame(x = geos::as_geos_geometry("LINESTRING (0 1, 3 9)")) #> Error: Execution halted with the following contexts #> 0: In R: in $DataFrame(): #> 0: During function call [pl$DataFrame(x = geos::as_geos_geometry("LINESTRING (0 1, 3 9)"))] #> 1: When constructing polars literal from Robj #> 2: Encountered the following error in Rust-Polars: #> expected Series ```