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

#add_business_days(n, week_mask: [true, true, true, true, true, false, false], roll: "raise") ⇒ Expr

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Offset by n business days.

Examples:

df = Polars::DataFrame.new({"start" => [Date.new(2020, 1, 1), Date.new(2020, 1, 2)]})
df.with_columns(result: Polars.col("start").dt.add_business_days(5))
# =>
# shape: (2, 2)
# ┌────────────┬────────────┐
# │ start      ┆ result     │
# │ ---        ┆ ---        │
# │ date       ┆ date       │
# ╞════════════╪════════════╡
# │ 2020-01-01 ┆ 2020-01-08 │
# │ 2020-01-02 ┆ 2020-01-09 │
# └────────────┴────────────┘

Parameters:

  • n —

    Number of business days to offset by. Can be a single number of an expression.

  • week_mask (defaults to: [true, true, true, true, true, false, false]) —

    Which days of the week to count. The default is Monday to Friday. If you wanted to count only Monday to Thursday, you would pass [true, true, true, true, false, false, false].

  • roll (defaults to: "raise") —

    What to do when the start date lands on a non-business day. Options are:

    • 'raise': raise an error
    • 'forward': move to the next business day
    • 'backward': move to the previous business day

Returns:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/polars/date_time_expr.rb', line 47

def add_business_days(
  n,
  week_mask: [true, true, true, true, true, false, false],
  roll: "raise"
)
  n_rbexpr = Utils.parse_into_expression(n)
  Utils.wrap_expr(
    _rbexpr.dt_add_business_days(
      n_rbexpr,
      week_mask,
      [],
      roll
    )
  )
end

#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:



1862
1863
1864
 
# File 'lib/polars/date_time_expr.rb', line 1862

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:



1305
1306
1307
 
# File 'lib/polars/date_time_expr.rb', line 1305

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

#century ⇒ Expr

Extract the century from underlying representation.

Applies to Date and Datetime columns.

Returns the century number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [
      Date.new(999, 12, 31),
      Date.new(1897, 5, 7),
      Date.new(2000, 1, 1),
      Date.new(2001, 7, 5),
      Date.new(3002, 10, 20)
    ]
  }
)
df.with_columns(cent: Polars.col("date").dt.century)
# =>
# shape: (5, 2)
# ┌────────────┬──────┐
# │ date       ┆ cent │
# │ ---        ┆ ---  │
# │ date       ┆ i32  │
# ╞════════════╪══════╡
# │ 0999-12-31 ┆ 10   │
# │ 1897-05-07 ┆ 19   │
# │ 2000-01-01 ┆ 20   │
# │ 2001-07-05 ┆ 21   │
# │ 3002-10-20 ┆ 31   │
# └────────────┴──────┘

Returns:



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

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



355
356
357
358
359
360
361
 
# File 'lib/polars/date_time_expr.rb', line 355

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:



1347
1348
1349
 
# File 'lib/polars/date_time_expr.rb', line 1347

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:



895
896
897
 
# File 'lib/polars/date_time_expr.rb', line 895

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#datetime ⇒ Expr

Datetime

Returns:



902
903
904
 
# File 'lib/polars/date_time_expr.rb', line 902

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:



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

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:



1888
1889
1890
 
# File 'lib/polars/date_time_expr.rb', line 1888

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:



1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
 
# File 'lib/polars/date_time_expr.rb', line 1187

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:



941
942
943
 
# File 'lib/polars/date_time_expr.rb', line 941

def hour
  Utils.wrap_expr(_rbexpr.dt_hour)
end

#is_business_day(week_mask: [true, true, true, true, true, false, false]) ⇒ Expr

Note:

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Determine whether each day lands on a business day.

Examples:

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

Parameters:

  • week_mask (Array) (defaults to: [true, true, true, true, true, false, false]) —

    Which days of the week to count. The default is Monday to Friday. If you wanted to count only Monday to Thursday, you would pass [true, true, true, true, false, false, false].

Returns:



591
592
593
594
595
596
597
598
599
600
 
# File 'lib/polars/date_time_expr.rb', line 591

def is_business_day(
  week_mask: [true, true, true, true, true, false, false]
)
  Utils.wrap_expr(
    _rbexpr.dt_is_business_day(
      week_mask,
      []
    )
  )
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:



626
627
628
 
# File 'lib/polars/date_time_expr.rb', line 626

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:



659
660
661
 
# File 'lib/polars/date_time_expr.rb', line 659

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:



1118
1119
1120
 
# File 'lib/polars/date_time_expr.rb', line 1118

def microsecond
  Utils.wrap_expr(_rbexpr.dt_microsecond)
end

#millennium ⇒ Expr

Extract the millennium from underlying representation.

Applies to Date and Datetime columns.

Returns the millennium number in the calendar date.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [
      Date.new(999, 12, 31),
      Date.new(1897, 5, 7),
      Date.new(2000, 1, 1),
      Date.new(2001, 7, 5),
      Date.new(3002, 10, 20)
    ]
  }
)
df.with_columns(mlnm: Polars.col("date").dt.millennium)
# =>
# shape: (5, 2)
# ┌────────────┬──────┐
# │ date       ┆ mlnm │
# │ ---        ┆ ---  │
# │ date       ┆ i32  │
# ╞════════════╪══════╡
# │ 0999-12-31 ┆ 1    │
# │ 1897-05-07 ┆ 2    │
# │ 2000-01-01 ┆ 2    │
# │ 2001-07-05 ┆ 3    │
# │ 3002-10-20 ┆ 4    │
# └────────────┴──────┘

Returns:



492
493
494
 
# File 'lib/polars/date_time_expr.rb', line 492

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



1081
1082
1083
 
# File 'lib/polars/date_time_expr.rb', line 1081

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:



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

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:



716
717
718
 
# File 'lib/polars/date_time_expr.rb', line 716

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:



1832
1833
1834
 
# File 'lib/polars/date_time_expr.rb', line 1832

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:



1793
1794
1795
 
# File 'lib/polars/date_time_expr.rb', line 1793

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:



1155
1156
1157
 
# File 'lib/polars/date_time_expr.rb', line 1155

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:



1753
1754
1755
1756
 
# File 'lib/polars/date_time_expr.rb', line 1753

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:



858
859
860
 
# File 'lib/polars/date_time_expr.rb', line 858

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:



687
688
689
 
# File 'lib/polars/date_time_expr.rb', line 687

def quarter
  Utils.wrap_expr(_rbexpr.dt_quarter)
end

#replace(year: nil, month: nil, day: nil, hour: nil, minute: nil, second: nil, microsecond: nil, ambiguous: "raise") ⇒ Expr

Replace time unit.

Examples:

df = Polars::DataFrame.new(
  {
    "date" => [Date.new(2024, 4, 1), Date.new(2025, 3, 16)],
    "new_day" => [10, 15]
  }
)
df.with_columns(Polars.col("date").dt.replace(day: "new_day").alias("replaced"))
# =>
# shape: (2, 3)
# ┌────────────┬─────────┬────────────┐
# │ date       ┆ new_day ┆ replaced   │
# │ ---        ┆ ---     ┆ ---        │
# │ date       ┆ i64     ┆ date       │
# ╞════════════╪═════════╪════════════╡
# │ 2024-04-01 ┆ 10      ┆ 2024-04-10 │
# │ 2025-03-16 ┆ 15      ┆ 2025-03-15 │
# └────────────┴─────────┴────────────┘
df.with_columns(Polars.col("date").dt.replace(year: 1800).alias("replaced"))
# =>
# shape: (2, 3)
# ┌────────────┬─────────┬────────────┐
# │ date       ┆ new_day ┆ replaced   │
# │ ---        ┆ ---     ┆ ---        │
# │ date       ┆ i64     ┆ date       │
# ╞════════════╪═════════╪════════════╡
# │ 2024-04-01 ┆ 10      ┆ 1800-04-01 │
# │ 2025-03-16 ┆ 15      ┆ 1800-03-16 │
# └────────────┴─────────┴────────────┘

Parameters:

  • year (Object) (defaults to: nil) —

    Column or literal.

  • month (Object) (defaults to: nil) —

    Column or literal, ranging from 1-12.

  • day (Object) (defaults to: nil) —

    Column or literal, ranging from 1-31.

  • hour (Object) (defaults to: nil) —

    Column or literal, ranging from 0-23.

  • minute (Object) (defaults to: nil) —

    Column or literal, ranging from 0-59.

  • second (Object) (defaults to: nil) —

    Column or literal, ranging from 0-59.

  • microsecond (Object) (defaults to: nil) —

    Column or literal, ranging from 0-999999.

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

    Determine how to deal with ambiguous datetimes:

    • 'raise' (default): raise
    • 'earliest': use the earliest datetime
    • 'latest': use the latest datetime
    • 'null': set to null

Returns:



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/polars/date_time_expr.rb', line 314

def replace(
  year: nil,
  month: nil,
  day: nil,
  hour: nil,
  minute: nil,
  second: nil,
  microsecond: nil,
  ambiguous: "raise"
)
  day, month, year, hour, minute, second, microsecond = (
    Utils.parse_into_list_of_expressions(
      day, month, year, hour, minute, second, microsecond
    )
  )
  ambiguous_expr = Utils.parse_into_expression(ambiguous, str_as_lit: true)
  Utils.wrap_expr(
    _rbexpr.dt_replace(
      year,
      month,
      day,
      hour,
      minute,
      second,
      microsecond,
      ambiguous_expr
    )
  )
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:



1429
1430
1431
1432
1433
1434
 
# File 'lib/polars/date_time_expr.rb', line 1429

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:



252
253
254
255
 
# File 'lib/polars/date_time_expr.rb', line 252

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:



1039
1040
1041
1042
1043
1044
1045
1046
 
# File 'lib/polars/date_time_expr.rb', line 1039

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:



454
455
456
 
# File 'lib/polars/date_time_expr.rb', line 454

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

#time ⇒ Expr

Time

Returns:



865
866
867
 
# File 'lib/polars/date_time_expr.rb', line 865

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:



1227
1228
1229
 
# File 'lib/polars/date_time_expr.rb', line 1227

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:



401
402
403
 
# File 'lib/polars/date_time_expr.rb', line 401

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:



1465
1466
1467
 
# File 'lib/polars/date_time_expr.rb', line 1465

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:



1500
1501
1502
 
# File 'lib/polars/date_time_expr.rb', line 1500

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:



1655
1656
1657
 
# File 'lib/polars/date_time_expr.rb', line 1655

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:



1613
1614
1615
 
# File 'lib/polars/date_time_expr.rb', line 1613

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:



1535
1536
1537
 
# File 'lib/polars/date_time_expr.rb', line 1535

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:



1697
1698
1699
 
# File 'lib/polars/date_time_expr.rb', line 1697

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:



1571
1572
1573
 
# File 'lib/polars/date_time_expr.rb', line 1571

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:



158
159
160
161
162
163
164
165
 
# File 'lib/polars/date_time_expr.rb', line 158

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:



745
746
747
 
# File 'lib/polars/date_time_expr.rb', line 745

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:



782
783
784
 
# File 'lib/polars/date_time_expr.rb', line 782

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:



1268
1269
1270
 
# File 'lib/polars/date_time_expr.rb', line 1268

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:



561
562
563
 
# File 'lib/polars/date_time_expr.rb', line 561

def year
  Utils.wrap_expr(_rbexpr.dt_year)
end