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.
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(<data>) rather than
pl$DataFrame(<data>).
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.
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 = "<value>"). See
?polars_options() for more details.
Object data typeObject 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:
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:
geos::as_geos_geometry("LINESTRING (0 1, 3 9)")
#> <geos_geometry[1]>
#> [1] <LINESTRING (0 1, 3 9)>
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