Convert Series to R vector or list

Description

$to_r() automatically returns an R vector or list based on the Polars DataType. It is possible to force the output type by using $to_vector() or $to_list().

Usage

<Series>$to_r(int64_conversion = polars_options()\$int64_conversion)

Series_to_vector(int64_conversion = polars_options()\$int64_conversion)

Series_to_list(int64_conversion = polars_options()\$int64_conversion)

Arguments

int64_conversion

How should Int64 values be handled when converting a polars object to R?

“double” (default) converts the integer values to double.
“bit64” uses bit64::as.integer64() to do the conversion (requires the package bit64 to be attached).
“string” converts Int64 values to character.

Value

R list or vector

Conversion to R data types considerations

When converting Polars objects, such as DataFrames to R objects, for example via the as.data.frame() generic function, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a Datetime type without a time zone. A Datetime type without a time zone in Polars is converted to the POSIXct type in R, which takes into account the time zone in which the R session is running (which can be checked with the Sys.timezone() function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using Sys.setenv(TZ = "UTC") and then perform the conversion, or use the $dt$replace_time_zone() method on the Datetime type column to explicitly specify the time zone before conversion.

# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am
# so this particular date-time doesn't exist
non_existent_time = as_polars_series("2020-03-08 02:00:00")\$str\$strptime(pl\$Datetime(), "%F %T")

withr::with_envvar(
  new = c(TZ = "America/New_York"),
  {
    tryCatch(
      # This causes an error due to the time zone (the `TZ` env var is affected).
      as.vector(non_existent_time),
      error = function(e) e
    )
  }
)
#> <error: in to_r: ComputeError(ErrString("datetime '2020-03-08 02:00:00' is non-existent in time zone 'America/New_York'. You may be able to use `non_existent='null'` to return `null` in this case.")) When calling: devtools::document()>

withr::with_envvar(
  new = c(TZ = "America/New_York"),
  {
    # This is safe.
    as.vector(non_existent_time\$dt\$replace_time_zone("UTC"))
  }
)
#> [1] "2020-03-08 02:00:00 UTC"

Examples

library(polars)

# Series with non-list type
series_vec = as_polars_series(letters[1:3])

series_vec$to_r() # as vector because Series DataType is not list (is String)

#> [1] "a" "b" "c"

series_vec$to_list() # implicit call as.list(), convert to list

#> [[1]]
#> [1] "a"
#> 
#> [[2]]
#> [1] "b"
#> 
#> [[3]]
#> [1] "c"

series_vec$to_vector() # implicit call unlist(), same as to_r() as already vector

#> [1] "a" "b" "c"

# make a Series with nested lists
series_list = as_polars_series(
  list(
    list(c(1:5, NA_integer_)),
    list(1:2, NA_integer_)
  )
)
series_list

#> polars Series: shape: (2,)
#> Series: '' [list[list[i32]]]
#> [
#>  [[1, 2, … null]]
#>  [[1, 2], [null]]
#> ]

series_list$to_r() # as list because Series DataType is list

#> [[1]]
#> [[1]][[1]]
#> [1]  1  2  3  4  5 NA
#> 
#> 
#> [[2]]
#> [[2]][[1]]
#> [1] 1 2
#> 
#> [[2]][[2]]
#> [1] NA

series_list$to_list() # implicit call as.list(), same as to_r() as already list

#> [[1]]
#> [[1]][[1]]
#> [1]  1  2  3  4  5 NA
#> 
#> 
#> [[2]]
#> [[2]][[1]]
#> [1] 1 2
#> 
#> [[2]][[2]]
#> [1] NA

series_list$to_vector() # implicit call unlist(), append into a vector

#> [1]  1  2  3  4  5 NA  1  2 NA