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

#base_utc_offset ⇒ Expr

Base offset from UTC.

This is usually constant for all datetimes in a given time zone, but may vary in the rare case that a country switches time zone, like Samoa (Apia) did at the end of 2011.

Examples:

df = Polars::DataFrame.new(
  {
    "ts" => [DateTime.new(2011, 12, 29), DateTime.new(2012, 1, 1)],
  }
)
df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Pacific/Apia"))
df.with_columns(Polars.col("ts").dt.base_utc_offset.alias("base_utc_offset"))
# =>
# shape: (2, 2)
# ┌────────────────────────────┬─────────────────┐
# │ ts                         ┆ base_utc_offset │
# │ ---                        ┆ ---             │
# │ datetime[ns, Pacific/Apia] ┆ duration[ms]    │
# ╞════════════════════════════╪═════════════════╡
# │ 2011-12-29 00:00:00 -10    ┆ -11h            │
# │ 2012-01-01 00:00:00 +14    ┆ 13h             │
# └────────────────────────────┴─────────────────┘

Returns:



1611
1612
1613
 
# File 'lib/polars/date_time_expr.rb', line 1611

def base_utc_offset
  Utils.wrap_expr(_rbexpr.dt_base_utc_offset)
end

#cast_time_unit(time_unit) ⇒ Expr

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

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", eager: true
    )
  }
)
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[ns]        ┆ 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:

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

    Time unit for the Datetime Series.

Returns:



1054
1055
1056
 
# File 'lib/polars/date_time_expr.rb', line 1054

def cast_time_unit(time_unit)
  Utils.wrap_expr(_rbexpr.dt_cast_time_unit(time_unit))
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:



217
218
219
220
221
222
223
 
# File 'lib/polars/date_time_expr.rb', line 217

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.parse_into_expression(time)
  Utils.wrap_expr(_rbexpr.dt_combine(time, time_unit))
end

#convert_time_zone(time_zone) ⇒ Expr

Set time zone for a Series of type Datetime.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 5, 1),
      "1mo",
      time_zone: "UTC",
      eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date")
      .dt.convert_time_zone("Europe/London")
      .alias("London")
  ]
)
# =>
# shape: (3, 2)
# ┌─────────────────────────┬─────────────────────────────┐
# │ date                    ┆ London                      │
# │ ---                     ┆ ---                         │
# │ datetime[ns, UTC]       ┆ datetime[ns, 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:

  • time_zone (String) —

    Time zone for the Datetime Series.

Returns:



1096
1097
1098
 
# File 'lib/polars/date_time_expr.rb', line 1096

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

#date ⇒ Expr

Date

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(Polars.col("datetime").dt.date.alias("date"))
# =>
# shape: (3, 2)
# ┌─────────────────────────┬────────────┐
# │ datetime                ┆ date       │
# │ ---                     ┆ ---        │
# │ datetime[ns]            ┆ date       │
# ╞═════════════════════════╪════════════╡
# │ 1978-01-01 01:01:01     ┆ 1978-01-01 │
# │ 2024-10-13 05:30:14.500 ┆ 2024-10-13 │
# │ 2065-01-01 10:20:30.060 ┆ 2065-01-01 │
# └─────────────────────────┴────────────┘

Returns:



644
645
646
 
# File 'lib/polars/date_time_expr.rb', line 644

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#datetime ⇒ Expr

Datetime

Returns:



651
652
653
 
# File 'lib/polars/date_time_expr.rb', line 651

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:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  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: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



569
570
571
 
# File 'lib/polars/date_time_expr.rb', line 569

def day
  Utils.wrap_expr(_rbexpr.dt_day)
end

#dst_offset ⇒ Expr

Additional offset currently in effect (typically due to daylight saving time).

Examples:

df = Polars::DataFrame.new(
  {
    "ts" => [DateTime.new(2020, 10, 25), DateTime.new(2020, 10, 26)],
  }
)
df = df.with_columns(Polars.col("ts").dt.replace_time_zone("Europe/London"))
df.with_columns(Polars.col("ts").dt.dst_offset.alias("dst_offset"))
# =>
# shape: (2, 2)
# ┌─────────────────────────────┬──────────────┐
# │ ts                          ┆ dst_offset   │
# │ ---                         ┆ ---          │
# │ datetime[ns, Europe/London] ┆ duration[ms] │
# ╞═════════════════════════════╪══════════════╡
# │ 2020-10-25 00:00:00 BST     ┆ 1h           │
# │ 2020-10-26 00:00:00 GMT     ┆ 0ms          │
# └─────────────────────────────┴──────────────┘

Returns:



1637
1638
1639
 
# File 'lib/polars/date_time_expr.rb', line 1637

def dst_offset
  Utils.wrap_expr(_rbexpr.dt_dst_offset)
end

#epoch(time_unit = "us") ⇒ Expr

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

Examples:

df = (
  Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
  .alias("date")
  .to_frame
)
df.with_columns(
  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   │
# │ ---        ┆ ---             ┆ ---       │
# │ date       ┆ i64             ┆ i64       │
# ╞════════════╪═════════════════╪═══════════╡
# │ 2001-01-01 ┆ 978307200000000 ┆ 978307200 │
# │ 2001-01-02 ┆ 978393600000000 ┆ 978393600 │
# │ 2001-01-03 ┆ 978480000000000 ┆ 978480000 │
# └────────────┴─────────────────┴───────────┘

Parameters:

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

    Time unit.

Returns:



936
937
938
939
940
941
942
943
944
945
946
 
# File 'lib/polars/date_time_expr.rb', line 936

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

#hour ⇒ Expr

Extract hour from underlying DateTime representation.

Applies to Datetime columns.

Returns the hour number from 0 to 23.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



690
691
692
 
# File 'lib/polars/date_time_expr.rb', line 690

def hour
  Utils.wrap_expr(_rbexpr.dt_hour)
end

#is_leap_year ⇒ Expr

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

Applies to Date and Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2000, 1, 1), Date.new(2001, 1, 1), Date.new(2002, 1, 1)]}
)
df.with_columns(
  leap_year: Polars.col("date").dt.is_leap_year
)
# =>
# shape: (3, 2)
# ┌────────────┬───────────┐
# │ date       ┆ leap_year │
# │ ---        ┆ ---       │
# │ date       ┆ bool      │
# ╞════════════╪═══════════╡
# │ 2000-01-01 ┆ true      │
# │ 2001-01-01 ┆ false     │
# │ 2002-01-01 ┆ false     │
# └────────────┴───────────┘

Returns:



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

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.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
)
df.select(
  "date",
  Polars.col("date").dt.year.alias("calendar_year"),
  Polars.col("date").dt.iso_year.alias("iso_year")
)
# =>
# shape: (3, 3)
# ┌────────────┬───────────────┬──────────┐
# │ date       ┆ calendar_year ┆ iso_year │
# │ ---        ┆ ---           ┆ ---      │
# │ date       ┆ i32           ┆ i32      │
# ╞════════════╪═══════════════╪══════════╡
# │ 1977-01-01 ┆ 1977          ┆ 1976     │
# │ 1978-01-01 ┆ 1978          ┆ 1977     │
# │ 1979-01-01 ┆ 1979          ┆ 1979     │
# └────────────┴───────────────┴──────────┘

Returns:



408
409
410
 
# File 'lib/polars/date_time_expr.rb', line 408

def iso_year
  Utils.wrap_expr(_rbexpr.dt_iso_year)
end

#microsecond ⇒ Expr

Extract microseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.microsecond.alias("microsecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ microsecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000      │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000       │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



867
868
869
 
# File 'lib/polars/date_time_expr.rb', line 867

def microsecond
  Utils.wrap_expr(_rbexpr.dt_microsecond)
end

#millisecond ⇒ Expr

Extract milliseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



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

def millisecond
  Utils.wrap_expr(_rbexpr.dt_millisecond)
end

#minute ⇒ Expr

Extract minutes from underlying DateTime representation.

Applies to Datetime columns.

Returns the minute number from 0 to 59.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘

Returns:



729
730
731
 
# File 'lib/polars/date_time_expr.rb', line 729

def minute
  Utils.wrap_expr(_rbexpr.dt_minute)
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:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.month.alias("month"))
# =>
# shape: (3, 2)
# ┌────────────┬───────┐
# │ date       ┆ month │
# │ ---        ┆ ---   │
# │ date       ┆ i8    │
# ╞════════════╪═══════╡
# │ 2001-01-01 ┆ 1     │
# │ 2001-06-30 ┆ 6     │
# │ 2001-12-27 ┆ 12    │
# └────────────┴───────┘

Returns:



465
466
467
 
# File 'lib/polars/date_time_expr.rb', line 465

def month
  Utils.wrap_expr(_rbexpr.dt_month)
end

#month_end ⇒ Expr

Roll forward to the last day of the month.

Examples:

df = Polars::DataFrame.new(
  {
    "dates" => Polars.datetime_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo",
      eager: true
    )
  }
)
df.select(Polars.col("dates").dt.month_end)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 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-05-31 02:00:00 │
# │ …                   │
# │ 2000-08-31 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:



1581
1582
1583
 
# File 'lib/polars/date_time_expr.rb', line 1581

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.datetime_range(
      DateTime.new(2000, 1, 15, 2),
      DateTime.new(2000, 12, 15, 2),
      "1mo",
      eager: true
    )
  }
)
df.select(Polars.col("dates").dt.month_start)
# =>
# shape: (12, 1)
# ┌─────────────────────┐
# │ dates               │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 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-05-01 02:00:00 │
# │ …                   │
# │ 2000-08-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:



1542
1543
1544
 
# File 'lib/polars/date_time_expr.rb', line 1542

def month_start
  Utils.wrap_expr(_rbexpr.dt_month_start)
end

#nanosecond ⇒ Expr

Extract nanoseconds from underlying DateTime representation.

Applies to Datetime columns.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime": [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000),
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.nanosecond.alias("nanosecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ nanosecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---        │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32        │
# ╞═════════════════════════╪══════╪════════╪════════╪════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0          │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500000000  │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60000000   │
# └─────────────────────────┴──────┴────────┴────────┴────────────┘

Returns:



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

def nanosecond
  Utils.wrap_expr(_rbexpr.dt_nanosecond)
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.datetime_range(
      DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y", eager: true
    )
  }
)
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[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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:



1502
1503
1504
1505
 
# File 'lib/polars/date_time_expr.rb', line 1502

def offset_by(by)
  by = Utils.parse_into_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:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  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: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



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

def ordinal_day
  Utils.wrap_expr(_rbexpr.dt_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:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.quarter.alias("quarter"))
# =>
# shape: (3, 2)
# ┌────────────┬─────────┐
# │ date       ┆ quarter │
# │ ---        ┆ ---     │
# │ date       ┆ i8      │
# ╞════════════╪═════════╡
# │ 2001-01-01 ┆ 1       │
# │ 2001-06-30 ┆ 2       │
# │ 2001-12-27 ┆ 4       │
# └────────────┴─────────┘

Returns:



436
437
438
 
# File 'lib/polars/date_time_expr.rb', line 436

def quarter
  Utils.wrap_expr(_rbexpr.dt_quarter)
end

#replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise") ⇒ Expr

Cast time zone for a Series of type Datetime.

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

Examples:

df = Polars::DataFrame.new(
  {
    "london_timezone": Polars.datetime_range(
      Time.utc(2020, 3, 1),
      Time.utc(2020, 7, 1),
      "1mo",
      time_zone: "UTC",
      eager: true,
    ).dt.convert_time_zone("Europe/London")
  }
)
df.select(
  [
    Polars.col("london_timezone"),
    Polars.col("london_timezone")
    .dt.replace_time_zone("Europe/Amsterdam")
    .alias("London_to_Amsterdam")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────────────┬────────────────────────────────┐
# │ london_timezone             ┆ London_to_Amsterdam            │
# │ ---                         ┆ ---                            │
# │ datetime[ns, Europe/London] ┆ datetime[ns, Europe/Amsterdam] │
# ╞═════════════════════════════╪════════════════════════════════╡
# │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
# │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
# │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
# │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
# │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
# └─────────────────────────────┴────────────────────────────────┘

You can use ambiguous to deal with ambiguous datetimes:

dates = [
  "2018-10-28 01:30",
  "2018-10-28 02:00",
  "2018-10-28 02:30",
  "2018-10-28 02:00"
]
df = Polars::DataFrame.new(
  {
    "ts" => Polars::Series.new(dates).str.strptime(Polars::Datetime),
    "ambiguous" => ["earliest", "earliest", "latest", "latest"]
  }
)
df.with_columns(
  ts_localized: Polars.col("ts").dt.replace_time_zone(
    "Europe/Brussels", ambiguous: Polars.col("ambiguous")
  )
)
# =>
# shape: (4, 3)
# ┌─────────────────────┬───────────┬───────────────────────────────┐
# │ ts                  ┆ ambiguous ┆ ts_localized                  │
# │ ---                 ┆ ---       ┆ ---                           │
# │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
# ╞═════════════════════╪═══════════╪═══════════════════════════════╡
# │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
# │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
# │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
# │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
# └─────────────────────┴───────────┴───────────────────────────────┘

Parameters:

  • time_zone (String) —

    Time zone for the Datetime Series. Pass nil to unset time zone.

  • ambiguous (String) (defaults to: "raise") —

    Determine how to deal with ambiguous datetimes.

  • non_existent (String) (defaults to: "raise") —

    Determine how to deal with non-existent datetimes.

Returns:



1178
1179
1180
1181
1182
1183
 
# File 'lib/polars/date_time_expr.rb', line 1178

def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
  unless ambiguous.is_a?(Expr)
    ambiguous = Polars.lit(ambiguous)
  end
  Utils.wrap_expr(_rbexpr.dt_replace_time_zone(time_zone, ambiguous._rbexpr, non_existent))
end

#round(every) ⇒ 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:

df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1),
    DateTime.new(2001, 1, 2),
    "225m",
    eager: true
  )
  .alias("datetime")
  .to_frame
)
df.with_columns(Polars.col("datetime").dt.round("1h").alias("round"))
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
# │ 2001-01-01 03:45:00 ┆ 2001-01-01 04:00:00 │
# │ 2001-01-01 07:30:00 ┆ 2001-01-01 08:00:00 │
# │ 2001-01-01 11:15:00 ┆ 2001-01-01 11:00:00 │
# │ 2001-01-01 15:00:00 ┆ 2001-01-01 15:00:00 │
# │ 2001-01-01 18:45:00 ┆ 2001-01-01 19:00:00 │
# │ 2001-01-01 22:30:00 ┆ 2001-01-01 23:00:00 │
# └─────────────────────┴─────────────────────┘
df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
  )
  .alias("datetime")
  .to_frame
)
df.with_columns(Polars.col("datetime").dt.round("30m").alias("round"))
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ round               │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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

Returns:



201
202
203
204
 
# File 'lib/polars/date_time_expr.rb', line 201

def round(every)
  every = Utils.parse_into_expression(every, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_round(every))
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(
  {
    "datetime" => [
      Time.utc(1978, 1, 1, 1, 1, 1, 0),
      Time.utc(2024, 10, 13, 5, 30, 14, 500_000),
      Time.utc(2065, 1, 1, 10, 20, 30, 60_000)
    ]
  }
)
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second.alias("second"),
  Polars.col("datetime").dt.millisecond.alias("millisecond")
)
# =>
# shape: (3, 5)
# ┌─────────────────────────┬──────┬────────┬────────┬─────────────┐
# │ datetime                ┆ hour ┆ minute ┆ second ┆ millisecond │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    ┆ ---         │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ i8     ┆ i32         │
# ╞═════════════════════════╪══════╪════════╪════════╪═════════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1      ┆ 0           │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14     ┆ 500         │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30     ┆ 60          │
# └─────────────────────────┴──────┴────────┴────────┴─────────────┘
df.with_columns(
  Polars.col("datetime").dt.hour.alias("hour"),
  Polars.col("datetime").dt.minute.alias("minute"),
  Polars.col("datetime").dt.second(fractional: true).alias("second")
)
# =>
# shape: (3, 4)
# ┌─────────────────────────┬──────┬────────┬────────┐
# │ datetime                ┆ hour ┆ minute ┆ second │
# │ ---                     ┆ ---  ┆ ---    ┆ ---    │
# │ datetime[ns]            ┆ i8   ┆ i8     ┆ f64    │
# ╞═════════════════════════╪══════╪════════╪════════╡
# │ 1978-01-01 01:01:01     ┆ 1    ┆ 1      ┆ 1.0    │
# │ 2024-10-13 05:30:14.500 ┆ 5    ┆ 30     ┆ 14.5   │
# │ 2065-01-01 10:20:30.060 ┆ 10   ┆ 20     ┆ 30.06  │
# └─────────────────────────┴──────┴────────┴────────┘

Returns:



788
789
790
791
792
793
794
795
 
# File 'lib/polars/date_time_expr.rb', line 788

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

#strftime(fmt) ⇒ Expr

Format Date/datetime with a formatting rule.

See chrono strftime/strptime.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      Time.utc(2020, 3, 1),
      Time.utc(2020, 4, 1),
      Time.utc(2020, 5, 1)
    ]
  }
)
df.with_columns(
  Polars.col("datetime")
  .dt.strftime("%Y/%m/%d %H:%M:%S")
  .alias("datetime_string")
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ datetime_string     │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ str                 │
# ╞═════════════════════╪═════════════════════╡
# │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
# │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
# │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
# └─────────────────────┴─────────────────────┘

If you're interested in the day name / month name, you can use '%A' / '%B':

df.with_columns(
  day_name: Polars.col("datetime").dt.strftime("%A"),
  month_name: Polars.col("datetime").dt.strftime("%B")
)
# =>
# shape: (3, 3)
# ┌─────────────────────┬───────────┬────────────┐
# │ datetime            ┆ day_name  ┆ month_name │
# │ ---                 ┆ ---       ┆ ---        │
# │ datetime[ns]        ┆ str       ┆ str        │
# ╞═════════════════════╪═══════════╪════════════╡
# │ 2020-03-01 00:00:00 ┆ Sunday    ┆ March      │
# │ 2020-04-01 00:00:00 ┆ Wednesday ┆ April      │
# │ 2020-05-01 00:00:00 ┆ Friday    ┆ May        │
# └─────────────────────┴───────────┴────────────┘

Returns:



316
317
318
 
# File 'lib/polars/date_time_expr.rb', line 316

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

#time ⇒ Expr

Time

Returns:



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

def time
  Utils.wrap_expr(_rbexpr.dt_time)
end

#timestamp(time_unit = "us") ⇒ Expr

Return a timestamp in the given time unit.

Examples:

df = (
  Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 3), eager: true)
  .alias("date")
  .to_frame
)
df.with_columns(
  Polars.col("date").dt.timestamp.alias("timestamp_us"),
  Polars.col("date").dt.timestamp("ms").alias("timestamp_ms")
)
# =>
# shape: (3, 3)
# ┌────────────┬─────────────────┬──────────────┐
# │ date       ┆ timestamp_us    ┆ timestamp_ms │
# │ ---        ┆ ---             ┆ ---          │
# │ date       ┆ i64             ┆ i64          │
# ╞════════════╪═════════════════╪══════════════╡
# │ 2001-01-01 ┆ 978307200000000 ┆ 978307200000 │
# │ 2001-01-02 ┆ 978393600000000 ┆ 978393600000 │
# │ 2001-01-03 ┆ 978480000000000 ┆ 978480000000 │
# └────────────┴─────────────────┴──────────────┘

Parameters:

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

    Time unit.

Returns:



976
977
978
 
# File 'lib/polars/date_time_expr.rb', line 976

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

#to_string(format) ⇒ Expr

Convert a Date/Time/Datetime column into a String column with the given format.

Similar to cast(Polars::String), but this method allows you to customize the formatting of the resulting string.

Examples:

df = Polars::DataFrame.new(
  {
    "datetime" => [
      DateTime.new(2020, 3, 1),
      DateTime.new(2020, 4, 1),
      DateTime.new(2020, 5, 1)
    ]
  }
)
df.with_columns(
  Polars.col("datetime")
  .dt.to_string("%Y/%m/%d %H:%M:%S")
  .alias("datetime_string")
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ datetime_string     │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ str                 │
# ╞═════════════════════╪═════════════════════╡
# │ 2020-03-01 00:00:00 ┆ 2020/03/01 00:00:00 │
# │ 2020-04-01 00:00:00 ┆ 2020/04/01 00:00:00 │
# │ 2020-05-01 00:00:00 ┆ 2020/05/01 00:00:00 │
# └─────────────────────┴─────────────────────┘

Parameters:

  • format (String) —

    Format to use, refer to the chrono strftime documentation <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>_ for specification. Example: "%y-%m-%d".

Returns:



263
264
265
 
# File 'lib/polars/date_time_expr.rb', line 263

def to_string(format)
  Utils.wrap_expr(_rbexpr.dt_to_string(format))
end

#total_days ⇒ Expr Also known as: days

Extract the days from a Duration type.

Examples:

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

Returns:



1214
1215
1216
 
# File 'lib/polars/date_time_expr.rb', line 1214

def total_days
  Utils.wrap_expr(_rbexpr.dt_total_days)
end

#total_hours ⇒ Expr Also known as: hours

Extract the hours from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.hours.alias("hours_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬────────────┐
# │ date                ┆ hours_diff │
# │ ---                 ┆ ---        │
# │ datetime[ns]        ┆ 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:



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

def total_hours
  Utils.wrap_expr(_rbexpr.dt_total_hours)
end

#total_microseconds ⇒ Expr Also known as: microseconds

Extract the microseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.microseconds.alias("microseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ microseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[ns]            ┆ 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.004 ┆ 1000              │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.996 ┆ 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:



1404
1405
1406
 
# File 'lib/polars/date_time_expr.rb', line 1404

def total_microseconds
  Utils.wrap_expr(_rbexpr.dt_total_microseconds)
end

#total_milliseconds ⇒ Expr Also known as: milliseconds

Extract the milliseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.milliseconds.alias("milliseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬───────────────────┐
# │ date                    ┆ milliseconds_diff │
# │ ---                     ┆ ---               │
# │ datetime[ns]            ┆ 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.004 ┆ 1                 │
# │ …                       ┆ …                 │
# │ 2020-01-01 00:00:00.996 ┆ 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:



1362
1363
1364
 
# File 'lib/polars/date_time_expr.rb', line 1362

def total_milliseconds
  Utils.wrap_expr(_rbexpr.dt_total_milliseconds)
end

#total_minutes ⇒ Expr Also known as: minutes

Extract the minutes from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.minutes.alias("minutes_diff")
  ]
)
# =>
# shape: (4, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ minutes_diff │
# │ ---                 ┆ ---          │
# │ datetime[ns]        ┆ 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:



1284
1285
1286
 
# File 'lib/polars/date_time_expr.rb', line 1284

def total_minutes
  Utils.wrap_expr(_rbexpr.dt_total_minutes)
end

#total_nanoseconds ⇒ Expr Also known as: nanoseconds

Extract the nanoseconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1), "1ms", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.nanoseconds.alias("nanoseconds_diff")
  ]
)
# =>
# shape: (1_001, 2)
# ┌─────────────────────────┬──────────────────┐
# │ date                    ┆ nanoseconds_diff │
# │ ---                     ┆ ---              │
# │ datetime[ns]            ┆ 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.004 ┆ 1000000          │
# │ …                       ┆ …                │
# │ 2020-01-01 00:00:00.996 ┆ 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:



1446
1447
1448
 
# File 'lib/polars/date_time_expr.rb', line 1446

def total_nanoseconds
  Utils.wrap_expr(_rbexpr.dt_total_nanoseconds)
end

#total_seconds ⇒ Expr Also known as: seconds

Extract the seconds from a Duration type.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => Polars.datetime_range(
      DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m", eager: true
    )
  }
)
df.select(
  [
    Polars.col("date"),
    Polars.col("date").diff.dt.seconds.alias("seconds_diff")
  ]
)
# =>
# shape: (5, 2)
# ┌─────────────────────┬──────────────┐
# │ date                ┆ seconds_diff │
# │ ---                 ┆ ---          │
# │ datetime[ns]        ┆ 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:



1320
1321
1322
 
# File 'lib/polars/date_time_expr.rb', line 1320

def total_seconds
  Utils.wrap_expr(_rbexpr.dt_total_seconds)
end

#truncate(every) ⇒ Expr

Note:

The every argument is 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:

df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1),
    DateTime.new(2001, 1, 2),
    "225m",
    eager: true
  )
  .alias("datetime")
  .to_frame
)
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ datetime            │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 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("datetime").dt.truncate("1h"))
# =>
# shape: (7, 1)
# ┌─────────────────────┐
# │ datetime            │
# │ ---                 │
# │ datetime[ns]        │
# ╞═════════════════════╡
# │ 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 │
# └─────────────────────┘
df = (
  Polars.datetime_range(
    DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 1, 1), "10m", eager: true
  )
  .alias("datetime")
  .to_frame
)
df.select(["datetime", Polars.col("datetime").dt.truncate("30m").alias("truncate")])
# =>
# shape: (7, 2)
# ┌─────────────────────┬─────────────────────┐
# │ datetime            ┆ truncate            │
# │ ---                 ┆ ---                 │
# │ datetime[ns]        ┆ datetime[ns]        │
# ╞═════════════════════╪═════════════════════╡
# │ 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

Returns:



107
108
109
110
111
112
113
114
 
# File 'lib/polars/date_time_expr.rb', line 107

def truncate(every)
  if !every.is_a?(Expr)
    every = Utils.parse_as_duration_string(every)
  end

  every = Utils.parse_into_expression(every, str_as_lit: true)
  Utils.wrap_expr(_rbexpr.dt_truncate(every))
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:

df = Polars::DataFrame.new(
  {"date" => [Date.new(2001, 1, 1), Date.new(2001, 6, 30), Date.new(2001, 12, 27)]}
)
df.with_columns(Polars.col("date").dt.week.alias("week"))
# =>
# shape: (3, 2)
# ┌────────────┬──────┐
# │ date       ┆ week │
# │ ---        ┆ ---  │
# │ date       ┆ i8   │
# ╞════════════╪══════╡
# │ 2001-01-01 ┆ 1    │
# │ 2001-06-30 ┆ 26   │
# │ 2001-12-27 ┆ 52   │
# └────────────┴──────┘

Returns:



494
495
496
 
# File 'lib/polars/date_time_expr.rb', line 494

def week
  Utils.wrap_expr(_rbexpr.dt_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:

df = Polars::DataFrame.new(
  {
    "date" => Polars.date_range(
      Date.new(2001, 12, 22), Date.new(2001, 12, 25), eager: true
    )
  }
)
df.with_columns(
  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: (4, 4)
# ┌────────────┬─────────┬──────────────┬─────────────┐
# │ date       ┆ weekday ┆ day_of_month ┆ day_of_year │
# │ ---        ┆ ---     ┆ ---          ┆ ---         │
# │ date       ┆ i8      ┆ i8           ┆ i16         │
# ╞════════════╪═════════╪══════════════╪═════════════╡
# │ 2001-12-22 ┆ 6       ┆ 22           ┆ 356         │
# │ 2001-12-23 ┆ 7       ┆ 23           ┆ 357         │
# │ 2001-12-24 ┆ 1       ┆ 24           ┆ 358         │
# │ 2001-12-25 ┆ 2       ┆ 25           ┆ 359         │
# └────────────┴─────────┴──────────────┴─────────────┘

Returns:



531
532
533
 
# File 'lib/polars/date_time_expr.rb', line 531

def weekday
  Utils.wrap_expr(_rbexpr.dt_weekday)
end

#with_time_unit(time_unit) ⇒ 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.datetime_range(
      Time.utc(2001, 1, 1),
      Time.utc(2001, 1, 3),
      "1d",
      time_unit: "ns",
      eager: true
    )
  }
)
df.select(
  Polars.col("date"),
  Polars.col("date").dt.with_time_unit("us").alias("time_unit_us")
)
# =>
# shape: (3, 2)
# ┌─────────────────────┬───────────────────────┐
# │ date                ┆ time_unit_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:

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

    Time unit for the Datetime Series.

Returns:



1017
1018
1019
 
# File 'lib/polars/date_time_expr.rb', line 1017

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

#year ⇒ Expr

Extract year from underlying Date representation.

Applies to Date and Datetime columns.

Returns the year number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {"date" => [Date.new(1977, 1, 1), Date.new(1978, 1, 1), Date.new(1979, 1, 1)]}
)
df.with_columns(
  calendar_year: Polars.col("date").dt.year,
  iso_year: Polars.col("date").dt.iso_year
)
# =>
# shape: (3, 3)
# ┌────────────┬───────────────┬──────────┐
# │ date       ┆ calendar_year ┆ iso_year │
# │ ---        ┆ ---           ┆ ---      │
# │ date       ┆ i32           ┆ i32      │
# ╞════════════╪═══════════════╪══════════╡
# │ 1977-01-01 ┆ 1977          ┆ 1976     │
# │ 1978-01-01 ┆ 1978          ┆ 1977     │
# │ 1979-01-01 ┆ 1979          ┆ 1979     │
# └────────────┴───────────────┴──────────┘

Returns:



347
348
349
 
# File 'lib/polars/date_time_expr.rb', line 347

def year
  Utils.wrap_expr(_rbexpr.dt_year)
end