Class: Polars::DateTimeExpr

Inherits:
Object
  • Object
show all
Defined in:
lib/polars/date_time_expr.rb

Overview

Namespace for datetime related expressions.

Instance Method Summary collapse

Instance Method Details

#cast_time_unit(tu) ⇒ Expr

Cast the underlying data to another time unit. This may lose precision.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.cast_time_unit("ms").alias("tu_ms"),
    Polars.col("date").dt.cast_time_unit("ns").alias("tu_ns")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬─────────────────────┬─────────────────────┐
# │ date                ┆ tu_ms               ┆ tu_ns               │
# │ ---                 ┆ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[ms]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 ┆ 2001-01-02 00:00:00 │
# │ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 ┆ 2001-01-03 00:00:00 │
# └─────────────────────┴─────────────────────┴─────────────────────┘

Parameters:

  • tu ("ns", "us", "ms") —

    Time unit for the Datetime Series.

Returns:



980
981
982
 
# File 'lib/polars/date_time_expr.rb', line 980

def cast_time_unit(tu)
  Utils.wrap_expr(_rbexpr.dt_cast_time_unit(tu))
end

#combine(time, time_unit: "us") ⇒ Expr

Create a naive Datetime from an existing Date/Datetime expression and a Time.

If the underlying expression is a Datetime then its time component is replaced, and if it is a Date then a new Datetime is created by combining the two values.

Parameters:

  • time (Object) —

    A Ruby time literal or Polars expression/column that resolves to a time.

  • time_unit ("ns", "us", "ms") (defaults to: "us") —

    Unit of time.

Returns:



237
238
239
240
241
242
243
 
# File 'lib/polars/date_time_expr.rb', line 237

def combine(time, time_unit: "us")
  unless time.is_a?(Time) || time.is_a?(Expr)
    raise TypeError, "expected 'time' to be a Ruby time or Polars expression, found #{time}"
  end
  time = Utils.expr_to_lit_or_expr(time)
  Utils.wrap_expr(_rbexpr.dt_combine(time._rbexpr, time_unit))
end

#convert_time_zone(tz) ⇒ Expr

Set time zone for a Series of type Datetime.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 5, 1),
      "1mo",
      time_zone: "UTC"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date")
      .dt.convert_time_zone("Europe/London")
      .alias("London")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────────┬─────────────────────────────┐
# │ date                    ┆ London                      │
# │ ---                     ┆ ---                         │
# │ datetime[μs, UTC]       ┆ datetime[μs, Europe/London] │
# ╞═════════════════════════╪═════════════════════════════╡
# │ 2020-03-01 00:00:00 UTC ┆ 2020-03-01 00:00:00 GMT     │
# │ 2020-04-01 00:00:00 UTC ┆ 2020-04-01 01:00:00 BST     │
# │ 2020-05-01 00:00:00 UTC ┆ 2020-05-01 01:00:00 BST     │
# └─────────────────────────┴─────────────────────────────┘

Parameters:

  • tz (String) —

    Time zone for the Datetime Series.

Returns:



1021
1022
1023
 
# File 'lib/polars/date_time_expr.rb', line 1021

def convert_time_zone(tz)
  Utils.wrap_expr(_rbexpr.dt_convert_time_zone(tz))
end

#date ⇒ Expr

Date

Returns:



615
616
617
 
# File 'lib/polars/date_time_expr.rb', line 615

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#datetime ⇒ Expr

Datetime

Returns:



622
623
624
 
# File 'lib/polars/date_time_expr.rb', line 622

def datetime
  Utils.wrap_expr(_rbexpr.dt_datetime)
end

#day ⇒ Expr

Extract day from underlying Date representation.

Applies to Date and Datetime columns.

Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘
df.select(
  [
    Polars.col("date").dt.weekday.alias("weekday"),
    Polars.col("date").dt.day.alias("day_of_month"),
    Polars.col("date").dt.ordinal_day.alias("day_of_year")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:



553
554
555
 
# File 'lib/polars/date_time_expr.rb', line 553

def day
  Utils.wrap_expr(_rbexpr.day)
end

#days ⇒ Expr

Extract the days from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.days.alias("days_diff")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬───────────┐
# │ date                ┆ days_diff │
# │ ---                 ┆ ---       │
# │ datetime[μs]        ┆ i64       │
# ╞═════════════════════╪═══════════╡
# │ 2020-03-01 00:00:00 ┆ null      │
# │ 2020-04-01 00:00:00 ┆ 31        │
# │ 2020-05-01 00:00:00 ┆ 30        │
# └─────────────────────┴───────────┘

Returns:



1069
1070
1071
 
# File 'lib/polars/date_time_expr.rb', line 1069

def days
  Utils.wrap_expr(_rbexpr.duration_days)
end

#epoch(tu = "us") ⇒ Expr

Get the time passed since the Unix EPOCH in the give time unit.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.epoch.alias("epoch_ns"),
    Polars.col("date").dt.epoch("s").alias("epoch_s")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬─────────────────┬───────────┐
# │ date                ┆ epoch_ns        ┆ epoch_s   │
# │ ---                 ┆ ---             ┆ ---       │
# │ datetime[μs]        ┆ i64             ┆ i64       │
# ╞═════════════════════╪═════════════════╪═══════════╡
# │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200 │
# │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600 │
# │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000 │
# └─────────────────────┴─────────────────┴───────────┘

Parameters:

  • tu ("us", "ns", "ms", "s", "d") (defaults to: "us") —

    Time unit.

Returns:



863
864
865
866
867
868
869
870
871
872
873
 
# File 'lib/polars/date_time_expr.rb', line 863

def epoch(tu = "us")
  if Utils::DTYPE_TEMPORAL_UNITS.include?(tu)
    timestamp(tu)
  elsif tu == "s"
    Utils.wrap_expr(_rbexpr.dt_epoch_seconds)
  elsif tu == "d"
    Utils.wrap_expr(_rbexpr).cast(:date).cast(:i32)
  else
    raise ArgumentError, "tu must be one of {{'ns', 'us', 'ms', 's', 'd'}}, got #{tu}"
  end
end

#hour ⇒ Expr

Extract hour from underlying DateTime representation.

Applies to Datetime columns.

Returns the hour number from 0 to 23.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "12h")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 12:00:00 │
# │ 2001-01-02 00:00:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.hour)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 12   │
# │ 0    │
# └──────┘

Returns:



663
664
665
 
# File 'lib/polars/date_time_expr.rb', line 663

def hour
  Utils.wrap_expr(_rbexpr.hour)
end

#hours ⇒ Expr

Extract the hours from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.hours.alias("hours_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬────────────┐
# │ date                ┆ hours_diff │
# │ ---                 ┆ ---        │
# │ datetime[μs]        ┆ i64        │
# ╞═════════════════════╪════════════╡
# │ 2020-01-01 00:00:00 ┆ null       │
# │ 2020-01-02 00:00:00 ┆ 24         │
# │ 2020-01-03 00:00:00 ┆ 24         │
# │ 2020-01-04 00:00:00 ┆ 24         │
# └─────────────────────┴────────────┘

Returns:



1103
1104
1105
 
# File 'lib/polars/date_time_expr.rb', line 1103

def hours
  Utils.wrap_expr(_rbexpr.duration_hours)
end

#is_leap_year ⇒ Expr

Determine whether the year of the underlying date is a leap year.

Applies to Date and Datetime columns.

Examples:

start = DateTime.new(2000, 1, 1)
stop = DateTime.new(2002, 1, 1)
df = Polars::DataFrame.new(
  {"date" => Polars.date_range(start, stop, "1y")}
)
df.select(Polars.col("date").dt.is_leap_year)
# =>
# shape: (3, 1)
# ┌───────┐
# │ date  │
# │ ---   │
# │ bool  │
# ╞═══════╡
# │ true  │
# │ false │
# │ false │
# └───────┘

Returns:



321
322
323
 
# File 'lib/polars/date_time_expr.rb', line 321

def is_leap_year
  Utils.wrap_expr(_rbexpr.dt_is_leap_year)
end

#iso_year ⇒ Expr

Extract ISO year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the ISO standard. This may not correspond with the calendar year.

Returns:



333
334
335
 
# File 'lib/polars/date_time_expr.rb', line 333

def iso_year
  Utils.wrap_expr(_rbexpr.iso_year)
end

#microsecond ⇒ Expr

Extract microseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



821
822
823
 
# File 'lib/polars/date_time_expr.rb', line 821

def microsecond
  Utils.wrap_expr(_rbexpr.microsecond)
end

#microseconds ⇒ Expr

Extract the microseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.microseconds.alias("microseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ microseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[μs]            ┆ i64               │
# ╞═════════════════════════╪═══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null              │
# │ 2020-01-01 00:00:00.001 ┆ 1000              │
# │ 2020-01-01 00:00:00.002 ┆ 1000              │
# │ 2020-01-01 00:00:00.003 ┆ 1000              │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.997 ┆ 1000              │
# │ 2020-01-01 00:00:00.998 ┆ 1000              │
# │ 2020-01-01 00:00:00.999 ┆ 1000              │
# │ 2020-01-01 00:00:01     ┆ 1000              │
# └─────────────────────────┴───────────────────┘

Returns:



1250
1251
1252
 
# File 'lib/polars/date_time_expr.rb', line 1250

def microseconds
  Utils.wrap_expr(_rbexpr.duration_microseconds)
end

#millisecond ⇒ Expr

Extract milliseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



812
813
814
 
# File 'lib/polars/date_time_expr.rb', line 812

def millisecond
  Utils.wrap_expr(_rbexpr.millisecond)
end

#milliseconds ⇒ Expr

Extract the milliseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.milliseconds.alias("milliseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ milliseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[μs]            ┆ i64               │
# ╞═════════════════════════╪═══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null              │
# │ 2020-01-01 00:00:00.001 ┆ 1                 │
# │ 2020-01-01 00:00:00.002 ┆ 1                 │
# │ 2020-01-01 00:00:00.003 ┆ 1                 │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.997 ┆ 1                 │
# │ 2020-01-01 00:00:00.998 ┆ 1                 │
# │ 2020-01-01 00:00:00.999 ┆ 1                 │
# │ 2020-01-01 00:00:01     ┆ 1                 │
# └─────────────────────────┴───────────────────┘

Returns:



1211
1212
1213
 
# File 'lib/polars/date_time_expr.rb', line 1211

def milliseconds
  Utils.wrap_expr(_rbexpr.duration_milliseconds)
end

#minute ⇒ Expr

Extract minutes from underlying DateTime representation.

Applies to Datetime columns.

Returns the minute number from 0 to 59.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 4, 0)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "2m")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:02:00 │
# │ 2001-01-01 00:04:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.minute)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:



704
705
706
 
# File 'lib/polars/date_time_expr.rb', line 704

def minute
  Utils.wrap_expr(_rbexpr.minute)
end

#minutes ⇒ Expr

Extract the minutes from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.minutes.alias("minutes_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ minutes_diff │
# │ ---                 ┆ ---          │
# │ datetime[μs]        ┆ i64          │
# ╞═════════════════════╪══════════════╡
# │ 2020-01-01 00:00:00 ┆ null         │
# │ 2020-01-02 00:00:00 ┆ 1440         │
# │ 2020-01-03 00:00:00 ┆ 1440         │
# │ 2020-01-04 00:00:00 ┆ 1440         │
# └─────────────────────┴──────────────┘

Returns:



1137
1138
1139
 
# File 'lib/polars/date_time_expr.rb', line 1137

def minutes
  Utils.wrap_expr(_rbexpr.duration_minutes)
end

#month ⇒ Expr

Extract month from underlying Date representation.

Applies to Date and Datetime columns.

Returns the month number starting from 1. The return value ranges from 1 to 12.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-02-01 00:00:00 │
# │ 2001-03-04 00:00:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.month)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 2    │
# │ 3    │
# └──────┘

Returns:



416
417
418
 
# File 'lib/polars/date_time_expr.rb', line 416

def month
  Utils.wrap_expr(_rbexpr.month)
end

#month_end ⇒ Expr

Roll forward to the last day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.date_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo"
    )
  }
)
df.select(Polars.col("dates").dt.month_end)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2000-01-31 02:00:00 │
# │ 2000-02-29 02:00:00 │
# │ 2000-03-31 02:00:00 │
# │ 2000-04-30 02:00:00 │
# │ …                   │
# │ 2000-09-30 02:00:00 │
# │ 2000-10-31 02:00:00 │
# │ 2000-11-30 02:00:00 │
# │ 2000-12-31 02:00:00 │
# └─────────────────────┘

Returns:



1417
1418
1419
 
# File 'lib/polars/date_time_expr.rb', line 1417

def month_end
  Utils.wrap_expr(_rbexpr.dt_month_end)
end

#month_start ⇒ Expr

Roll backward to the first day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.date_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo"
    )
  }
)
df.select(Polars.col("dates").dt.month_start)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2000-01-01 02:00:00 │
# │ 2000-02-01 02:00:00 │
# │ 2000-03-01 02:00:00 │
# │ 2000-04-01 02:00:00 │
# │ …                   │
# │ 2000-09-01 02:00:00 │
# │ 2000-10-01 02:00:00 │
# │ 2000-11-01 02:00:00 │
# │ 2000-12-01 02:00:00 │
# └─────────────────────┘

Returns:



1381
1382
1383
 
# File 'lib/polars/date_time_expr.rb', line 1381

def month_start
  Utils.wrap_expr(_rbexpr.dt_month_start)
end

#nanosecond ⇒ Expr

Extract nanoseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



830
831
832
 
# File 'lib/polars/date_time_expr.rb', line 830

def nanosecond
  Utils.wrap_expr(_rbexpr.nanosecond)
end

#nanoseconds ⇒ Expr

Extract the nanoseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.nanoseconds.alias("nanoseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬──────────────────┐
# │ date                    ┆ nanoseconds_diff │
# │ ---                     ┆ ---              │
# │ datetime[μs]            ┆ i64              │
# ╞═════════════════════════╪══════════════════╡
# │ 2020-01-01 00:00:00     ┆ null             │
# │ 2020-01-01 00:00:00.001 ┆ 1000000          │
# │ 2020-01-01 00:00:00.002 ┆ 1000000          │
# │ 2020-01-01 00:00:00.003 ┆ 1000000          │
# │ …                       ┆ …                │
# │ 2020-01-01 00:00:00.997 ┆ 1000000          │
# │ 2020-01-01 00:00:00.998 ┆ 1000000          │
# │ 2020-01-01 00:00:00.999 ┆ 1000000          │
# │ 2020-01-01 00:00:01     ┆ 1000000          │
# └─────────────────────────┴──────────────────┘

Returns:



1289
1290
1291
 
# File 'lib/polars/date_time_expr.rb', line 1289

def nanoseconds
  Utils.wrap_expr(_rbexpr.duration_nanoseconds)
end

#offset_by(by) ⇒ Expr

Offset this date by a relative time offset.

This differs from Polars.col("foo") + timedelta in that it can take months and leap years into account. Note that only a single minus sign is allowed in the by string, as the first character.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.date_range(
      DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y"
    )
  }
)
df.select(
  [
    Polars.col("dates").dt.offset_by("1y").alias("date_plus_1y"),
    Polars.col("dates").dt.offset_by("-1y2mo").alias("date_min")
  ]
)
# =>
# shape: (6, 2)
# ┌─────────────────────┬─────────────────────┐
# │ date_plus_1y        ┆ date_min            │
# │ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 1998-11-01 00:00:00 │
# │ 2002-01-01 00:00:00 ┆ 1999-11-01 00:00:00 │
# │ 2003-01-01 00:00:00 ┆ 2000-11-01 00:00:00 │
# │ 2004-01-01 00:00:00 ┆ 2001-11-01 00:00:00 │
# │ 2005-01-01 00:00:00 ┆ 2002-11-01 00:00:00 │
# │ 2006-01-01 00:00:00 ┆ 2003-11-01 00:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • by (String) —

    The offset is dictated by the following string language:

    • 1ns (1 nanosecond)
    • 1us (1 microsecond)
    • 1ms (1 millisecond)
    • 1s (1 second)
    • 1m (1 minute)
    • 1h (1 hour)
    • 1d (1 day)
    • 1w (1 week)
    • 1mo (1 calendar month)
    • 1y (1 calendar year)
    • 1i (1 index count)

Returns:



1344
1345
1346
1347
 
# File 'lib/polars/date_time_expr.rb', line 1344

def offset_by(by)
  by = Utils.parse_as_expression(by, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_offset_by(by))
end

#ordinal_day ⇒ Expr

Extract ordinal day from underlying Date representation.

Applies to Date and Datetime columns.

Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.)

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘
df.select(
  [
    Polars.col("date").dt.weekday.alias("weekday"),
    Polars.col("date").dt.day.alias("day_of_month"),
    Polars.col("date").dt.ordinal_day.alias("day_of_year")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:



601
602
603
 
# File 'lib/polars/date_time_expr.rb', line 601

def ordinal_day
  Utils.wrap_expr(_rbexpr.ordinal_day)
end

#quarter ⇒ Expr

Extract quarter from underlying Date representation.

Applies to Date and Datetime columns.

Returns the quarter ranging from 1 to 4.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2002, 6, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-06-30 00:00:00 │
# │ 2001-12-27 00:00:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.quarter)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:



374
375
376
 
# File 'lib/polars/date_time_expr.rb', line 374

def quarter
  Utils.wrap_expr(_rbexpr.quarter)
end

#replace_time_zone(tz, use_earliest: nil, ambiguous: "raise") ⇒ Expr

Cast time zone for a Series of type Datetime.

Different from convert_time_zone, this will also modify the underlying timestamp,

Parameters:

  • tz (String) —

    Time zone for the Datetime Series.

Returns:



1034
1035
1036
1037
1038
 
# File 'lib/polars/date_time_expr.rb', line 1034

def replace_time_zone(tz, use_earliest: nil, ambiguous: "raise")
  ambiguous = Utils.rename_use_earliest_to_ambiguous(use_earliest, ambiguous)
  ambiguous = Polars.lit(ambiguous) unless ambiguous.is_a?(Expr)
  Utils.wrap_expr(_rbexpr.dt_replace_time_zone(tz, ambiguous._rbexpr))
end

#round(every, offset: nil) ⇒ Expr

Note:

The every and offset argument are created with the the following small string formatting language:

1ns # 1 nanosecond 1us # 1 microsecond 1ms # 1 millisecond 1s # 1 second 1m # 1 minute 1h # 1 hour 1d # 1 day 1w # 1 week 1mo # 1 calendar month 1y # 1 calendar year

eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds

Note:

This functionality is currently experimental and may change without it being considered a breaking change.

Divide the date/datetime range into buckets.

Each date/datetime in the first half of the interval is mapped to the start of its bucket. Each date/datetime in the seconod half of the interval is mapped to the end of its bucket.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars.date_range(
  start, stop, "225m", name: "dates"
).to_frame
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:45:00 │
# │ 2001-01-01 07:30:00 │
# │ 2001-01-01 11:15:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:45:00 │
# │ 2001-01-01 22:30:00 │
# └─────────────────────┘
df.select(Polars.col("dates").dt.round("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 04:00:00 │
# │ 2001-01-01 08:00:00 │
# │ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 19:00:00 │
# │ 2001-01-01 23:00:00 │
# └─────────────────────┘
start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
df.select(["dates", Polars.col("dates").dt.round("30m").alias("round")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ dates               ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
# │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • every (String) —

    Every interval start and period length

  • offset (String) (defaults to: nil) —

    Offset the window

Returns:



213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/polars/date_time_expr.rb', line 213

def round(every, offset: nil)
  if offset.nil?
    offset = "0ns"
  end

  Utils.wrap_expr(
    _rbexpr.dt_round(
      Utils._timedelta_to_pl_duration(every),
      Utils._timedelta_to_pl_duration(offset)
    )
  )
end

#second(fractional: false) ⇒ Expr

Extract seconds from underlying DateTime representation.

Applies to Datetime columns.

Returns the integer second number from 0 to 59, or a floating point number from 0 < 60 if fractional: true that includes any milli/micro/nanosecond component.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1, 0, 0, 0.456789),
      DateTime.new(2001, 1, 1, 0, 0, 6),
      "2s654321us"
    )
  }
)
# =>
# shape: (3, 1)
# ┌────────────────────────────┐
# │ date                       │
# │ ---                        │
# │ datetime[μs]               │
# ╞════════════════════════════╡
# │ 2001-01-01 00:00:00.456789 │
# │ 2001-01-01 00:00:03.111110 │
# │ 2001-01-01 00:00:05.765431 │
# └────────────────────────────┘
df.select(Polars.col("date").dt.second.alias("secs"))
# =>
# shape: (3, 1)
# ┌──────┐
# │ secs │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 3    │
# │ 5    │
# └──────┘

df.select(Polars.col("date").dt.second(fractional: true).alias("secs"))
# =>
# shape: (3, 1)
# ┌──────────┐
# │ secs     │
# │ ---      │
# │ f64      │
# ╞══════════╡
# │ 0.456789 │
# │ 3.11111  │
# │ 5.765431 │
# └──────────┘
start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
df = Polars::DataFrame.new(
  {"date" => Polars.date_range(start, stop, "2s")}
)
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:00:02 │
# │ 2001-01-01 00:00:04 │
# └─────────────────────┘
df.select(Polars.col("date").dt.second)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 0    │
# │ 2    │
# │ 4    │
# └──────┘

Returns:



798
799
800
801
802
803
804
805
 
# File 'lib/polars/date_time_expr.rb', line 798

def second(fractional: false)
  sec = Utils.wrap_expr(_rbexpr.second)
  if fractional
    sec + (Utils.wrap_expr(_rbexpr.nanosecond) / Utils.lit(1_000_000_000.0))
  else
    sec
  end
end

#seconds ⇒ Expr

Extract the seconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.seconds.alias("seconds_diff")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ seconds_diff │
# │ ---                 ┆ ---          │
# │ datetime[μs]        ┆ i64          │
# ╞═════════════════════╪══════════════╡
# │ 2020-01-01 00:00:00 ┆ null         │
# │ 2020-01-01 00:01:00 ┆ 60           │
# │ 2020-01-01 00:02:00 ┆ 60           │
# │ 2020-01-01 00:03:00 ┆ 60           │
# │ 2020-01-01 00:04:00 ┆ 60           │
# └─────────────────────┴──────────────┘

Returns:



1172
1173
1174
 
# File 'lib/polars/date_time_expr.rb', line 1172

def seconds
  Utils.wrap_expr(_rbexpr.duration_seconds)
end

#strftime(fmt) ⇒ Expr

Format Date/datetime with a formatting rule.

See chrono strftime/strptime.

Returns:



250
251
252
 
# File 'lib/polars/date_time_expr.rb', line 250

def strftime(fmt)
  Utils.wrap_expr(_rbexpr.strftime(fmt))
end

#time ⇒ Expr

Time

Returns:



608
609
610
 
# File 'lib/polars/date_time_expr.rb', line 608

def time
  Utils.wrap_expr(_rbexpr.dt_time)
end

#timestamp(tu = "us") ⇒ Expr

Return a timestamp in the given time unit.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "1d")})
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.timestamp.alias("timestamp_ns"),
    Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬─────────────────┬──────────────┐
# │ date                ┆ timestamp_ns    ┆ timestamp_ms │
# │ ---                 ┆ ---             ┆ ---          │
# │ datetime[μs]        ┆ i64             ┆ i64          │
# ╞═════════════════════╪═════════════════╪══════════════╡
# │ 2001-01-01 00:00:00 ┆ 978307200000000 ┆ 978307200000 │
# │ 2001-01-02 00:00:00 ┆ 978393600000000 ┆ 978393600000 │
# │ 2001-01-03 00:00:00 ┆ 978480000000000 ┆ 978480000000 │
# └─────────────────────┴─────────────────┴──────────────┘

Parameters:

  • tu ("us", "ns", "ms") (defaults to: "us") —

    Time unit.

Returns:



904
905
906
 
# File 'lib/polars/date_time_expr.rb', line 904

def timestamp(tu = "us")
  Utils.wrap_expr(_rbexpr.timestamp(tu))
end

#truncate(every, offset: nil, use_earliest: nil) ⇒ Expr

Note:

The every and offset argument are created with the the following small string formatting language:

1ns # 1 nanosecond 1us # 1 microsecond 1ms # 1 millisecond 1s # 1 second 1m # 1 minute 1h # 1 hour 1d # 1 day 1w # 1 week 1mo # 1 calendar month 1y # 1 calendar year

eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds

Divide the date/datetime range into buckets.

Each date/datetime is mapped to the start of its bucket.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
df = Polars.date_range(
  start, stop, "225m", name: "dates"
).to_frame
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:45:00 │
# │ 2001-01-01 07:30:00 │
# │ 2001-01-01 11:15:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:45:00 │
# │ 2001-01-01 22:30:00 │
# └─────────────────────┘
df.select(Polars.col("dates").dt.truncate("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:00:00 │
# │ 2001-01-01 07:00:00 │
# │ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:00:00 │
# │ 2001-01-01 22:00:00 │
# └─────────────────────┘
start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
df = Polars.date_range(start, stop, "10m", name: "dates").to_frame
df.select(["dates", Polars.col("dates").dt.truncate("30m").alias("truncate")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ dates               ┆ truncate            │
# │ ---                 ┆ ---                 │
# │ datetime[μs]        ┆ datetime[μs]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 00:50:00 ┆ 2001-01-01 00:30:00 │
# │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • every (String) —

    Every interval start and period length

  • offset (String) (defaults to: nil) —

    Offset the window

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/polars/date_time_expr.rb', line 100

def truncate(every, offset: nil, use_earliest: nil)
  if offset.nil?
    offset = "0ns"
  end

  if !every.is_a?(Expr)
    every = Utils._timedelta_to_pl_duration(every)
  end
  every = Utils.parse_as_expression(every, str_as_lit: true)

  Utils.wrap_expr(
    _rbexpr.dt_truncate(
      every,
      Utils._timedelta_to_pl_duration(offset),
    )
  )
end

#week ⇒ Expr

Extract the week from the underlying Date representation.

Applies to Date and Datetime columns.

Returns the ISO week number starting from 1. The return value ranges from 1 to 53. (The last week of year differs by years.)

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "31d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-02-01 00:00:00 │
# │ 2001-03-04 00:00:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.week)
# =>
# shape: (3, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i8   │
# ╞══════╡
# │ 1    │
# │ 5    │
# │ 9    │
# └──────┘

Returns:



458
459
460
 
# File 'lib/polars/date_time_expr.rb', line 458

def week
  Utils.wrap_expr(_rbexpr.week)
end

#weekday ⇒ Expr

Extract the week day from the underlying Date representation.

Applies to Date and Datetime columns.

Returns the ISO weekday number where monday = 1 and sunday = 7

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "3d")})
# =>
# shape: (3, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-01-04 00:00:00 │
# │ 2001-01-07 00:00:00 │
# └─────────────────────┘
df.select(
  [
    Polars.col("date").dt.weekday.alias("weekday"),
    Polars.col("date").dt.day.alias("day_of_month"),
    Polars.col("date").dt.ordinal_day.alias("day_of_year")
  ]
)
# =>
# shape: (3, 3)
# ┌─────────┬──────────────┬─────────────┐
# │ weekday ┆ day_of_month ┆ day_of_year │
# │ ---     ┆ ---          ┆ ---         │
# │ i8      ┆ i8           ┆ i16         │
# ╞═════════╪══════════════╪═════════════╡
# │ 1       ┆ 1            ┆ 1           │
# │ 4       ┆ 4            ┆ 4           │
# │ 7       ┆ 7            ┆ 7           │
# └─────────┴──────────────┴─────────────┘

Returns:



505
506
507
 
# File 'lib/polars/date_time_expr.rb', line 505

def weekday
  Utils.wrap_expr(_rbexpr.weekday)
end

#with_time_unit(tu) ⇒ Expr

Set time unit of a Series of dtype Datetime or Duration.

This does not modify underlying data, and should be used to fix an incorrect time unit.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", time_unit: "ns"
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").dt.with_time_unit("us").alias("tu_us")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬───────────────────────┐
# │ date                ┆ tu_us                 │
# │ ---                 ┆ ---                   │
# │ datetime[ns]        ┆ datetime[μs]          │
# ╞═════════════════════╪═══════════════════════╡
# │ 2001-01-01 00:00:00 ┆ +32971-04-28 00:00:00 │
# │ 2001-01-02 00:00:00 ┆ +32974-01-22 00:00:00 │
# │ 2001-01-03 00:00:00 ┆ +32976-10-18 00:00:00 │
# └─────────────────────┴───────────────────────┘

Parameters:

  • tu ("ns", "us", "ms") —

    Time unit for the Datetime Series.

Returns:



943
944
945
 
# File 'lib/polars/date_time_expr.rb', line 943

def with_time_unit(tu)
  Utils.wrap_expr(_rbexpr.dt_with_time_unit(tu))
end

#year ⇒ Expr

Extract year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the calendar date.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2002, 7, 1)
df = Polars::DataFrame.new({"date" => Polars.date_range(start, stop, "180d")})
# =>
# shape: (4, 1)
# ┌─────────────────────┐
# │ date                │
# │ ---                 │
# │ datetime[μs]        │
# ╞═════════════════════╡
# │ 2001-01-01 00:00:00 │
# │ 2001-06-30 00:00:00 │
# │ 2001-12-27 00:00:00 │
# │ 2002-06-25 00:00:00 │
# └─────────────────────┘
df.select(Polars.col("date").dt.year)
# =>
# shape: (4, 1)
# ┌──────┐
# │ date │
# │ ---  │
# │ i32  │
# ╞══════╡
# │ 2001 │
# │ 2001 │
# │ 2001 │
# │ 2002 │
# └──────┘

Returns:



293
294
295
 
# File 'lib/polars/date_time_expr.rb', line 293

def year
  Utils.wrap_expr(_rbexpr.year)
end