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:



1367
1368
1369
 
# File 'lib/polars/date_time_expr.rb', line 1367

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:



875
876
877
 
# File 'lib/polars/date_time_expr.rb', line 875

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:



917
918
919
 
# File 'lib/polars/date_time_expr.rb', line 917

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

#date ⇒ Expr

Date

Returns:



577
578
579
 
# File 'lib/polars/date_time_expr.rb', line 577

def date
  Utils.wrap_expr(_rbexpr.dt_date)
end

#datetime ⇒ Expr

Datetime

Returns:



584
585
586
 
# File 'lib/polars/date_time_expr.rb', line 584

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:



525
526
527
 
# File 'lib/polars/date_time_expr.rb', line 525

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:



1393
1394
1395
 
# File 'lib/polars/date_time_expr.rb', line 1393

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:



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

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:



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

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:



331
332
333
 
# File 'lib/polars/date_time_expr.rb', line 331

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:



364
365
366
 
# File 'lib/polars/date_time_expr.rb', line 364

def iso_year
  Utils.wrap_expr(_rbexpr.dt_iso_year)
end

#microsecond ⇒ Expr

Extract microseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



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

def microsecond
  Utils.wrap_expr(_rbexpr.dt_microsecond)
end

#millisecond ⇒ Expr

Extract milliseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



735
736
737
 
# File 'lib/polars/date_time_expr.rb', line 735

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:



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

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:



421
422
423
 
# File 'lib/polars/date_time_expr.rb', line 421

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:



1337
1338
1339
 
# File 'lib/polars/date_time_expr.rb', line 1337

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:



1298
1299
1300
 
# File 'lib/polars/date_time_expr.rb', line 1298

def month_start
  Utils.wrap_expr(_rbexpr.dt_month_start)
end

#nanosecond ⇒ Expr

Extract nanoseconds from underlying DateTime representation.

Applies to Datetime columns.

Returns:



753
754
755
 
# File 'lib/polars/date_time_expr.rb', line 753

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:



1258
1259
1260
1261
 
# File 'lib/polars/date_time_expr.rb', line 1258

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:



563
564
565
 
# File 'lib/polars/date_time_expr.rb', line 563

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:



392
393
394
 
# File 'lib/polars/date_time_expr.rb', line 392

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,

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:



934
935
936
937
938
939
 
# File 'lib/polars/date_time_expr.rb', line 934

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:



721
722
723
724
725
726
727
728
 
# File 'lib/polars/date_time_expr.rb', line 721

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.

Returns:



272
273
274
 
# File 'lib/polars/date_time_expr.rb', line 272

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

#time ⇒ Expr

Time

Returns:



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

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:



825
826
827
 
# File 'lib/polars/date_time_expr.rb', line 825

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:



970
971
972
 
# File 'lib/polars/date_time_expr.rb', line 970

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:



1005
1006
1007
 
# File 'lib/polars/date_time_expr.rb', line 1005

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:



1160
1161
1162
 
# File 'lib/polars/date_time_expr.rb', line 1160

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:



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

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:



1040
1041
1042
 
# File 'lib/polars/date_time_expr.rb', line 1040

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:



1202
1203
1204
 
# File 'lib/polars/date_time_expr.rb', line 1202

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:



1076
1077
1078
 
# File 'lib/polars/date_time_expr.rb', line 1076

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:



450
451
452
 
# File 'lib/polars/date_time_expr.rb', line 450

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:



487
488
489
 
# File 'lib/polars/date_time_expr.rb', line 487

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.

Parameters:

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

    Time unit for the Datetime Series.

Returns:



838
839
840
 
# File 'lib/polars/date_time_expr.rb', line 838

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:



303
304
305
 
# File 'lib/polars/date_time_expr.rb', line 303

def year
  Utils.wrap_expr(_rbexpr.dt_year)
end