Infer Polars DataType corresponding to a given R object
Description
infer_polars_dtype() is a helper function used to quickly
find the DataType corresponding to an R object, in order words, it
infers the type of the Polars Series that would be constructed from the
object. In many cases, this function simply performs something like
head(x, 0) |> as_polars_series(). It is much faster than
actually constructing a Series using the entire object. This function is
similar to nanoarrow::infer_nanoarrow_schema().
is_convertible_to_polars_series() and
is_convertible_to_polars_expr() are helper functions that
check if the object can be converted to a Series or Expr respectively.
These functions call infer_polars_dtype() internally and
return TRUE if the type can be inferred without error. (Or,
that object is already a Polars Expr for
is_convertible_to_polars_expr().)
Usage
infer_polars_dtype(x, ...)
is_convertible_to_polars_series(x, ...)
is_convertible_to_polars_expr(x, ...)
# Default S3 method:
infer_polars_dtype(x, ...)
# S3 method for class 'polars_series'
infer_polars_dtype(x, ...)
# S3 method for class 'polars_data_frame'
infer_polars_dtype(x, ...)
# S3 method for class 'polars_lazy_frame'
infer_polars_dtype(x, ...)
# S3 method for class ''NULL''
infer_polars_dtype(x, ...)
# S3 method for class 'list'
infer_polars_dtype(x, ..., strict = FALSE, infer_dtype_length = 10L)
# S3 method for class 'AsIs'
infer_polars_dtype(x, ...)
# S3 method for class 'data.frame'
infer_polars_dtype(x, ...)
# S3 method for class 'nanoarrow_array_stream'
infer_polars_dtype(x, ...)
# S3 method for class 'nanoarrow_array'
infer_polars_dtype(x, ...)
# S3 method for class 'RecordBatchReader'
infer_polars_dtype(x, ...)
# S3 method for class 'ArrowTabular'
infer_polars_dtype(x, ...)
# S3 method for class 'vctrs_vctr'
infer_polars_dtype(x, ...)
Arguments
x
|
An R object. |
…
|
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.
|
infer_dtype_length
|
The number of non-NULL elements to use for type inference.
Must be a single positive integer-ish value. The default is
10. If you want to infer the type of the entire list, set
this to Inf, but be aware that it may be slow.
|
Details
S3 objects based on atomic vectors or classes built on the vctrs package
will work accurately if the S3 method of the
as_polars_series() function is defined.
Value
A polars DataType
See Also
-
as_polars_series() - check_polars: Functions to check if the object is a polars object.
Examples
#> Int32
# The type inference is also fast for objects
# that would take a long time to construct a Series.
infer_polars_dtype(1:100000000)
#> Int32
# For lists, it is not possible to infer the type
# without inspecting all elements.
# However, this function can be configured to inspect only a few elements
# via the `infer_dtype_length` argument.
# If a sufficient length is specified, the correct type can be inferred.
# (By default, the length is set to 10.)
mixed_list <- list(1, NULL, "foo")
infer_polars_dtype(mixed_list)
#> List(String)
#> List(String)
# But if the length is too short, an incorrect type may be inferred.
infer_polars_dtype(mixed_list, infer_dtype_length = 1)
#> List(Float64)
# is_convertible_to_polars_* functions are useful for checking if
# the object can be converted to a Series or Expr quickly.
try(infer_polars_dtype(1i))
#> Error in infer_polars_dtype(0+1i) :
#> Can't infer polars dtype of the complex number 0+1i
#> Caused by error in `as_polars_series()` at neo-r-polars/R/infer_polars_dtype.R:84:3:
#> ! an empty complex vector can't be converted to a polars Series.
#> [1] FALSE
#> [1] FALSE
# For polars Expr objects, infer_polars_dtype() will raise an error
# because Expr can't be converted to a Series by `as_polars_series()`.
try(infer_polars_dtype(pl$lit(1)))
#> Error in infer_polars_dtype(pl$lit(1)) :
#> Passing Polars expression objects to `infer_polars_dtype()` is not
#> supported.
#> ℹ You may want to eval the expression with `pl$select()` first.
#> [1] FALSE
#> [1] TRUE