Create a Polars Series from an R object

Description

The as_polars_series() function creates a polars Series from various R objects. The Data Type of the Series is determined by the class of the input object.

Usage

as_polars_series(x, name = NULL, ...)

# Default S3 method:
as_polars_series(x, name = NULL, ...)

# S3 method for class 'polars_series'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'polars_data_frame'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'polars_lazy_frame'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'double'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'integer'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'character'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'logical'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'raw'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'factor'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'Date'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'POSIXct'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'POSIXlt'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'difftime'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'numeric_version'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'hms'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'blob'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'array'
as_polars_series(x, name = NULL, ...)

# S3 method for class ''NULL''
as_polars_series(x, name = NULL, ...)

# S3 method for class 'list'
as_polars_series(x, name = NULL, ..., strict = FALSE)

# S3 method for class 'AsIs'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'data.frame'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'nanoarrow_array_stream'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'nanoarrow_array'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'RecordBatchReader'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'ArrowTabular'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'integer64'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'ITime'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'vctrs_unspecified'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'vctrs_rcrd'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'clock_time_point'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'clock_sys_time'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'clock_zoned_time'
as_polars_series(x, name = NULL, ...)

# S3 method for class 'clock_duration'
as_polars_series(x, name = NULL, ...)

Arguments

x An R object.

name A single string or NULL. Name of the Series. Will be used as a column name when used in a polars DataFrame. When not specified, name is set to an empty string.

… Additional arguments passed to the methods.

strict A logical value to indicate whether throwing an error when the input list’s elements have different data types. If FALSE (default), all elements are automatically cast to the super type, or, casting to the super type is failed, the value will be null. If TRUE, the first non-NULL element’s data type is used as the data type of the inner Series.

Details

The default method of as_polars_series() throws an error, so we need to define S3 methods for the classes we want to support.

S3 method for list and list based classes

In R, a list can contain elements of different types, but in Polars (Apache Arrow), all elements must have the same type. So the as_polars_series() function automatically casts all elements to the same type or throws an error, depending on the strict argument. We can check the data type of the Series that will be created from the list by using the infer_polars_dtype() function in advance. If you want to create a list with all elements of the same type in R, consider using the vctrs::list_of() function.

Since a list can contain another list, the strict argument is also used when creating Series from the inner list in the case of classes constructed on top of a list, such as data.frame or vctrs_rcrd.

S3 method for Date

Sub-day values will be ignored (floored to the day).

S3 method for POSIXct

Sub-millisecond values will be ignored (floored to the millisecond).

If the tzone attribute is not present or an empty string (““), the Series’ dtype will be Datetime without timezone.

S3 method for POSIXlt

Sub-nanosecond values will be ignored (floored to the nanosecond).

S3 method for difftime

Sub-millisecond values will be rounded to milliseconds.

S3 method for hms

Sub-nanosecond values will be ignored (floored to the nanosecond).

If the hms vector contains values greater-equal to 24-oclock or less than 0-oclock, an error will be thrown.

S3 method for clock_duration

Calendrical durations (years, quarters, months) are treated as chronologically with the internal representation of seconds. Please check the clock_duration documentation for more details.

S3 methods for polars_data_frame, polars_lazy_frame,

and data.frame

These methods are shortcuts for as_polars_df(x, …)$to_struct(). See as_polars_df() and \<DataFrame>$to_struct() for more details.

Value

A polars Series

Examples

library("polars")

# double
as_polars_series(c(NA, 1, 2))

#> shape: (3,)
#> Series: '' [f64]
#> [
#>  null
#>  1.0
#>  2.0
#> ]

# integer
as_polars_series(c(NA, 1:2))

#> shape: (3,)
#> Series: '' [i32]
#> [
#>  null
#>  1
#>  2
#> ]

# character
as_polars_series(c(NA, "foo", "bar"))

#> shape: (3,)
#> Series: '' [str]
#> [
#>  null
#>  "foo"
#>  "bar"
#> ]

# logical
as_polars_series(c(NA, TRUE, FALSE))

#> shape: (3,)
#> Series: '' [bool]
#> [
#>  null
#>  true
#>  false
#> ]

# raw
as_polars_series(as.raw(c(0, 16, 255)))

#> shape: (3,)
#> Series: '' [u8]
#> [
#>  0
#>  16
#>  255
#> ]

# factor
as_polars_series(factor(c(NA, "a", "b")))

#> shape: (3,)
#> Series: '' [cat]
#> [
#>  null
#>  "a"
#>  "b"
#> ]

# Date
as_polars_series(as.Date(c(NA, "2021-01-01")))

#> shape: (2,)
#> Series: '' [date]
#> [
#>  null
#>  2021-01-01
#> ]

# Sub-day precision will be ignored
as.Date(c(-0.5, 0, 0.5)) |>
  as_polars_series()

#> shape: (3,)
#> Series: '' [date]
#> [
#>  1969-12-31
#>  1970-01-01
#>  1970-01-01
#> ]

# POSIXct with timezone
as_polars_series(as.POSIXct(c(NA, "2021-01-01 00:00:00.123456789"), "UTC"))

#> shape: (2,)
#> Series: '' [datetime[ms, UTC]]
#> [
#>  null
#>  2021-01-01 00:00:00.123 UTC
#> ]

# POSIXct without timezone
as_polars_series(as.POSIXct(c(NA, "2021-01-01 00:00:00.123456789")))

#> shape: (2,)
#> Series: '' [datetime[ms]]
#> [
#>  null
#>  2021-01-01 00:00:00.123
#> ]

# POSIXlt
as_polars_series(as.POSIXlt(c(NA, "2021-01-01 00:00:00.123456789"), "UTC"))

#> shape: (2,)
#> Series: '' [datetime[ns, UTC]]
#> [
#>  null
#>  2021-01-01 00:00:00.123456789 UTC
#> ]

# difftime
as_polars_series(as.difftime(c(NA, 1), units = "days"))

#> shape: (2,)
#> Series: '' [duration[ms]]
#> [
#>  null
#>  1d
#> ]

# Sub-millisecond values will be rounded to milliseconds
as.difftime(c(0.0005, 0.0010, 0.0015, 0.0020), units = "secs") |>
  as_polars_series()

#> shape: (4,)
#> Series: '' [duration[ms]]
#> [
#>  0ms
#>  1ms
#>  2ms
#>  2ms
#> ]

as.difftime(c(0.0005, 0.0010, 0.0015, 0.0020), units = "weeks") |>
  as_polars_series()

#> shape: (4,)
#> Series: '' [duration[ms]]
#> [
#>  5m 2s 400ms
#>  10m 4s 800ms
#>  15m 7s 200ms
#>  20m 9s 600ms
#> ]

# numeric_version
as_polars_series(getRversion())

#> shape: (1,)
#> Series: '' [list[i32]]
#> [
#>  [4, 5, 1]
#> ]

# NULL
as_polars_series(NULL)

#> shape: (0,)
#> Series: '' [null]
#> [
#> ]

# list
as_polars_series(list(NA, NULL, list(), 1, "foo", TRUE))

#> shape: (6,)
#> Series: '' [list[str]]
#> [
#>  [null]
#>  null
#>  []
#>  ["1.0"]
#>  ["foo"]
#>  ["true"]
#> ]

# 1st element will be `null` due to the casting failure
as_polars_series(list(list("bar"), "foo"))

#> shape: (2,)
#> Series: '' [list[str]]
#> [
#>  null
#>  ["foo"]
#> ]

# data.frame
as_polars_series(
  data.frame(x = 1:2, y = c("foo", "bar"), z = I(list(1, 2)))
)

#> shape: (2,)
#> Series: '' [struct[3]]
#> [
#>  {1,"foo",[1.0]}
#>  {2,"bar",[2.0]}
#> ]

# vctrs_unspecified
if (requireNamespace("vctrs", quietly = TRUE)) {
  as_polars_series(vctrs::unspecified(3L))
}

#> shape: (3,)
#> Series: '' [null]
#> [
#>  null
#>  null
#>  null
#> ]

# hms
if (requireNamespace("hms", quietly = TRUE)) {
  as_polars_series(hms::as_hms(c(NA, "01:00:00")))
}

#> shape: (2,)
#> Series: '' [time]
#> [
#>  null
#>  01:00:00
#> ]

# blob
if (requireNamespace("blob", quietly = TRUE)) {
  as_polars_series(blob::as_blob(c(NA, "foo", "bar")))
}

#> shape: (3,)
#> Series: '' [binary]
#> [
#>  null
#>  b"foo"
#>  b"bar"
#> ]

# integer64
if (requireNamespace("bit64", quietly = TRUE)) {
  as_polars_series(bit64::as.integer64(c(NA, "9223372036854775807")))
}

#> shape: (2,)
#> Series: '' [i64]
#> [
#>  null
#>  9223372036854775807
#> ]

# clock_naive_time
if (requireNamespace("clock", quietly = TRUE)) {
  as_polars_series(clock::naive_time_parse(c(
    NA,
    "1900-01-01T12:34:56.123456789",
    "2020-01-01T12:34:56.123456789"
  ), precision = "nanosecond"))
}

#> shape: (3,)
#> Series: '' [datetime[ns]]
#> [
#>  null
#>  1900-01-01 12:34:56.123456789
#>  2020-01-01 12:34:56.123456789
#> ]

# clock_duration
if (requireNamespace("clock", quietly = TRUE)) {
  as_polars_series(clock::duration_nanoseconds(c(NA, 1)))
}

#> shape: (2,)
#> Series: '' [duration[ns]]
#> [
#>  null
#>  1ns
#> ]

# Calendrical durations are treated as chronologically
if (requireNamespace("clock", quietly = TRUE)) {
  as_polars_series(clock::duration_years(c(NA, 1)))
}

#> shape: (2,)
#> Series: '' [duration[ms]]
#> [
#>  null
#>  365d 5h 49m 12s
#> ]