Class: Polars::DateTimeNameSpace

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

Overview

Series.dt namespace.

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Polars::ExprDispatch

Instance Method Details

#[](item) ⇒ Object

Get item.

Returns:



16
17
18
19
 
# File 'lib/polars/date_time_name_space.rb', line 16

def [](item)
  s = Utils.wrap_s(_s)
  s[item]
end

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

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.

roll 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

Examples:

s = Polars::Series.new("start", [Date.new(2020, 1, 1), Date.new(2020, 1, 2)])
s.dt.add_business_days(5)
# =>
# shape: (2,)
# Series: 'start' [date]
# [
#         2020-01-08
#         2020-01-09
# ]

You can pass a custom weekend - for example, if you only take Sunday off:

week_mask = [true, true, true, true, true, true, false]
s.dt.add_business_days(5, week_mask: week_mask)
# =>
# shape: (2,)
# Series: 'start' [date]
# [
#         2020-01-07
#         2020-01-08
# ]

Roll all dates forwards to the next business day:

s = Polars::Series.new("start", [Date.new(2020, 1, 5), Date.new(2020, 1, 6)])
s.dt.add_business_days(0, roll: "forward")
# =>
# shape: (2,)
# Series: 'start' [date]
# [
#         2020-01-06
#         2020-01-06
# ]

Parameters:

  • n (Object) —

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

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



75
76
77
78
79
80
81
 
# File 'lib/polars/date_time_name_space.rb', line 75

def add_business_days(
  n,
  week_mask: [true, true, true, true, true, false, false],
  roll: "raise"
)
  super
end

#base_utc_offset ⇒ Series

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:

s = Polars.datetime_range(
  DateTime.new(2011, 12, 29),
  DateTime.new(2012, 1, 1),
  "2d",
  time_zone: "Pacific/Apia",
  eager: true,
).alias("datetime")
s.dt.base_utc_offset
# =>
# shape: (2,)
# Series: 'datetime' [duration[ms]]
# [
#         -11h
#         13h
# ]

Returns:



1565
1566
1567
 
# File 'lib/polars/date_time_name_space.rb', line 1565

def base_utc_offset
  super
end

#cast_time_unit(time_unit) ⇒ Series

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

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
# =>
# shape: (3,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]
date.dt.cast_time_unit("ms").alias("tu_ms")
# =>
# shape: (3,)
# Series: 'tu_ms' [datetime[ms]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]
date.dt.cast_time_unit("ns").alias("tu_ns")
# =>
# shape: (3,)
# Series: 'tu_ns' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]

Parameters:

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

    Time unit for the Datetime Series.

Returns:



891
892
893
 
# File 'lib/polars/date_time_name_space.rb', line 891

def cast_time_unit(time_unit)
  super
end

#century ⇒ Series

Extract the century from underlying representation.

Applies to Date and Datetime columns.

Returns the century number in the calendar date.

Examples:

s = Polars::Series.new(
  "dt",
  [
    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)
  ]
)
s.dt.century
# =>
# shape: (5,)
# Series: 'dt' [i32]
# [
#         10
#         19
#         20
#         21
#         31
# ]

Returns:



230
231
232
 
# File 'lib/polars/date_time_name_space.rb', line 230

def century
  super
end

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

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.

Examples:

s = Polars::Series.new(
  "dtm",
  [DateTime.new(2022, 12, 31, 10, 30, 45), DateTime.new(2023, 7, 5, 23, 59, 59)]
)
s.dt.combine(Time.new(2000, 1, 1, 1, 2, 3.456))
# =>
# shape: (2,)
# Series: 'dtm' [datetime[μs]]
# [
#         2022-12-31 01:02:03.456
#         2023-07-05 01:02:03.456
# ]

Parameters:

  • time (Object) —

    A Ruby time literal or Series of the same length as this Series.

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

    Unit of time.

Returns:



1493
1494
1495
 
# File 'lib/polars/date_time_name_space.rb', line 1493

def combine(time, time_unit: "us")
  super
end

#convert_time_zone(time_zone) ⇒ Series

Set time zone a Series of type Datetime.

Examples:

start = DateTime.new(2020, 3, 1)
stop = DateTime.new(2020, 5, 1)
date = Polars.datetime_range(start, stop, "1mo", time_zone: "UTC", eager: true).alias("datetime")
# =>
# shape: (3,)
# Series: 'datetime' [datetime[ns, UTC]]
# [
#         2020-03-01 00:00:00 UTC
#         2020-04-01 00:00:00 UTC
#         2020-05-01 00:00:00 UTC
# ]
date.dt.convert_time_zone("Europe/London").alias("London")
# =>
# shape: (3,)
# Series: 'London' [datetime[ns, Europe/London]]
# [
#         2020-03-01 00:00:00 GMT
#         2020-04-01 01:00:00 BST
#         2020-05-01 01:00:00 BST
# ]

Parameters:

  • time_zone (String) —

    Time zone for the Datetime Series.

Returns:



925
926
927
 
# File 'lib/polars/date_time_name_space.rb', line 925

def convert_time_zone(time_zone)
  super
end

#date ⇒ Series

Extract (local) date.

Applies to Date/Datetime columns.

Examples:

ser = Polars::Series.new([DateTime.new(2021, 1, 2, 5)]).dt.replace_time_zone(
  "Asia/Kathmandu"
)
ser.dt.date
# =>
# shape: (1,)
# Series: '' [date]
# [
#         2021-01-02
# ]

Returns:



568
569
570
 
# File 'lib/polars/date_time_name_space.rb', line 568

def date
  super
end

#day ⇒ Series

Extract the day from the 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:

s = Polars.date_range(
  Date.new(2001, 1, 1), Date.new(2001, 1, 9), "2d", eager: true
).alias("date")
s.dt.day
# =>
# shape: (5,)
# Series: 'date' [i8]
# [
#         1
#         3
#         5
#         7
#         9
# ]

Returns:



500
501
502
 
# File 'lib/polars/date_time_name_space.rb', line 500

def day
  super
end

#days_in_month ⇒ Series

Extract the number of days in the month from the underlying date representation.

Applies to Date and Datetime columns.

Returns the number of days in the month. The return value ranges from 28 to 31.

Examples:

s = Polars::Series.new(
  "date", [Date.new(2001, 1, 1), Date.new(2001, 2, 1), Date.new(2000, 2, 1)]
)
s.dt.days_in_month
# =>
# shape: (3,)
# Series: 'date' [i8]
# [
#         31
#         28
#         29
# ]

Returns:



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

def days_in_month
  super
end

#dst_offset ⇒ Series

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

Examples:

s = Polars.datetime_range(
  DateTime.new(2020, 10, 25),
  DateTime.new(2020, 10, 26),
  time_zone: "Europe/London",
  eager: true,
).alias("datetime")
s.dt.dst_offset
# =>
# shape: (2,)
# Series: 'datetime' [duration[ms]]
# [
#         1h
#         0ms
# ]

Returns:



1588
1589
1590
 
# File 'lib/polars/date_time_name_space.rb', line 1588

def dst_offset
  super
end

#epoch(time_unit = "us") ⇒ Series

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

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
# =>
# shape: (3,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]
date.dt.epoch.alias("epoch_ns")
# =>
# shape: (3,)
# Series: 'epoch_ns' [i64]
# [
#         978307200000000
#         978393600000000
#         978480000000000
# ]
date.dt.epoch("s").alias("epoch_s")
# =>
# shape: (3,)
# Series: 'epoch_s' [i64]
# [
#         978307200
#         978393600
#         978480000
# ]

Parameters:

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

    Time unit.

Returns:



846
847
848
 
# File 'lib/polars/date_time_name_space.rb', line 846

def epoch(time_unit = "us")
  super
end

#hour ⇒ Series

Extract the hour from the underlying DateTime representation.

Applies to Datetime columns.

Returns the hour number from 0 to 23.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 3)
date = Polars.datetime_range(start, stop, "1h", eager: true).alias("datetime")
date.dt.hour
# =>
# shape: (4,)
# Series: 'datetime' [i8]
# [
#         0
#         1
#         2
#         3
# ]

Returns:



594
595
596
 
# File 'lib/polars/date_time_name_space.rb', line 594

def hour
  super
end

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

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:

s = Polars::Series.new([Date.new(2020, 1, 3), Date.new(2020, 1, 5)])
s.dt.is_business_day
# =>
# shape: (2,)
# Series: '' [bool]
# [
#         true
#         false
# ]

You can pass a custom weekend - for example, if you only take Sunday off:

week_mask = [true, true, true, true, true, true, false]
s.dt.is_business_day(week_mask: week_mask)
# =>
# shape: (2,)
# Series: '' [bool]
# [
#         true
#         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:



290
291
292
293
294
 
# File 'lib/polars/date_time_name_space.rb', line 290

def is_business_day(
  week_mask: [true, true, true, true, true, false, false]
)
  super
end

#is_leap_year ⇒ Series

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

Applies to Date and Datetime columns.

Examples:

s = Polars::Series.new(
  "date", [Date.new(2000, 1, 1), Date.new(2001, 1, 1), Date.new(2002, 1, 1)]
)
s.dt.is_leap_year
# =>
# shape: (3,)
# Series: 'date' [bool]
# [
#         true
#         false
#         false
# ]

Returns:



315
316
317
 
# File 'lib/polars/date_time_name_space.rb', line 315

def is_leap_year
  super
end

#iso_year ⇒ Series

Extract ISO year from underlying Date representation.

Applies to Date and Datetime columns.

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

Examples:

dt = DateTime.new(2022, 1, 1, 7, 8, 40)
Polars::Series.new([dt]).dt.iso_year
# =>
# shape: (1,)
# Series: '' [i32]
# [
#         2021
# ]

Returns:



337
338
339
 
# File 'lib/polars/date_time_name_space.rb', line 337

def iso_year
  super
end

#max ⇒ Object

Return maximum as Ruby object.

Examples:

s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2), Date.new(2001, 1, 3)])
s.dt.max
# => Wed, 03 Jan 2001

Returns:



103
104
105
 
# File 'lib/polars/date_time_name_space.rb', line 103

def max
  Utils.wrap_s(_s).max
end

#microsecond ⇒ Series

Extract the microseconds from the underlying DateTime representation.

Applies to Datetime columns.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
date.dt.microsecond
# =>
# shape: (9,)
# Series: 'datetime' [i32]
# [
#         0
#         500000
#         0
#         500000
#         0
#         500000
#         0
#         500000
#         0
# ]

Returns:



727
728
729
 
# File 'lib/polars/date_time_name_space.rb', line 727

def microsecond
  super
end

#millennium ⇒ Series

Extract the millennium from underlying representation.

Applies to Date and Datetime columns.

Returns the millennium number in the calendar date.

Examples:

s = Polars::Series.new(
  "dt",
  [
    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)
  ]
)
s.dt.millennium
# =>
# shape: (5,)
# Series: 'dt' [i32]
# [
#         1
#         2
#         2
#         3
#         4
# ]

Returns:



196
197
198
 
# File 'lib/polars/date_time_name_space.rb', line 196

def millennium
  super
end

#millisecond ⇒ Series

Extract the milliseconds from the underlying DateTime representation.

Applies to Datetime columns.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
date.dt.millisecond
# =>
# shape: (9,)
# Series: 'datetime' [i32]
# [
#         0
#         500
#         0
#         500
#         0
#         500
#         0
#         500
#         0
# ]

Returns:



698
699
700
 
# File 'lib/polars/date_time_name_space.rb', line 698

def millisecond
  super
end

#min ⇒ Object

Return minimum as Ruby object.

Examples:

s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2), Date.new(2001, 1, 3)])
s.dt.min
# => Mon, 01 Jan 2001

Returns:



91
92
93
 
# File 'lib/polars/date_time_name_space.rb', line 91

def min
  Utils.wrap_s(_s).min
end

#minute ⇒ Series

Extract the minutes from the underlying DateTime representation.

Applies to Datetime columns.

Returns the minute number from 0 to 59.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 4, 0)
date = Polars.datetime_range(start, stop, "2m", eager: true).alias("datetime")
date.dt.minute
# =>
# shape: (3,)
# Series: 'datetime' [i8]
# [
#         0
#         2
#         4
# ]

Returns:



619
620
621
 
# File 'lib/polars/date_time_name_space.rb', line 619

def minute
  super
end

#month ⇒ Series

Extract the month from the 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:

date = Polars.date_range(
  Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
).alias("date")
date.dt.month
# =>
# shape: (4,)
# Series: 'date' [i8]
# [
#         1
#         2
#         3
#         4
# ]

Returns:



390
391
392
 
# File 'lib/polars/date_time_name_space.rb', line 390

def month
  super
end

#month_end ⇒ Series

Roll forward to the last day of the month.

Examples:

s = Polars.datetime_range(
  DateTime.new(2000, 1, 2, 2), DateTime.new(2000, 4, 2, 2), "1mo", time_unit: "us", eager: true
).alias("datetime")
s.dt.month_end
# =>
# shape: (4,)
# Series: 'datetime' [datetime[μs]]
# [
#         2000-01-31 02:00:00
#         2000-02-29 02:00:00
#         2000-03-31 02:00:00
#         2000-04-30 02:00:00
# ]

Returns:



1537
1538
1539
 
# File 'lib/polars/date_time_name_space.rb', line 1537

def month_end
  super
end

#month_start ⇒ Series

Roll backward to the first day of the month.

Examples:

s = Polars.datetime_range(
  DateTime.new(2000, 1, 2, 2), DateTime.new(2000, 4, 2, 2), "1mo", time_unit: "us", eager: true
).alias("datetime")
s.dt.month_start
# =>
# shape: (4,)
# Series: 'datetime' [datetime[μs]]
# [
#         2000-01-01 02:00:00
#         2000-02-01 02:00:00
#         2000-03-01 02:00:00
#         2000-04-01 02:00:00
# ]

Returns:



1515
1516
1517
 
# File 'lib/polars/date_time_name_space.rb', line 1515

def month_start
  super
end

#nanosecond ⇒ Series

Extract the nanoseconds from the underlying DateTime representation.

Applies to Datetime columns.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
date.dt.nanosecond
# =>
# shape: (9,)
# Series: 'datetime' [i32]
# [
#         0
#         500000000
#         0
#         500000000
#         0
#         500000000
#         0
#         500000000
#         0
# ]

Returns:



756
757
758
 
# File 'lib/polars/date_time_name_space.rb', line 756

def nanosecond
  super
end

#offset_by(by) ⇒ Series

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:

dates = Polars.datetime_range(
  DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y", eager: true
).alias("datetime")
# =>
# shape: (6,)
# Series: 'datetime' [datetime[ns]]
# [
#         2000-01-01 00:00:00
#         2001-01-01 00:00:00
#         2002-01-01 00:00:00
#         2003-01-01 00:00:00
#         2004-01-01 00:00:00
#         2005-01-01 00:00:00
# ]
dates.dt.offset_by("1y").alias("date_plus_1y")
# =>
# shape: (6,)
# Series: 'date_plus_1y' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2002-01-01 00:00:00
#         2003-01-01 00:00:00
#         2004-01-01 00:00:00
#         2005-01-01 00:00:00
#         2006-01-01 00:00:00
# ]
dates.dt.offset_by("-1y2mo").alias("date_minus_1y_2mon")
# =>
# shape: (6,)
# Series: 'date_minus_1y_2mon' [datetime[ns]]
# [
#         1998-11-01 00:00:00
#         1999-11-01 00:00:00
#         2000-11-01 00:00:00
#         2001-11-01 00:00:00
#         2002-11-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:



1314
1315
1316
 
# File 'lib/polars/date_time_name_space.rb', line 1314

def offset_by(by)
  super
end

#ordinal_day ⇒ Series

Extract ordinal day from underlying date representation.

Applies to Date and Datetime columns.

Returns the day of year starting from 1. The return value ranges from 1 to 366. (The last day of year differs by years.)

Examples:

s = Polars.date_range(
  Date.new(2001, 1, 1), Date.new(2001, 3, 1), "1mo", eager: true
).alias("date")
s.dt.ordinal_day
# =>
# shape: (3,)
# Series: 'date' [i16]
# [
#         1
#         32
#         60
# ]

Returns:



526
527
528
 
# File 'lib/polars/date_time_name_space.rb', line 526

def ordinal_day
  super
end

#quarter ⇒ Series

Extract quarter from underlying Date representation.

Applies to Date and Datetime columns.

Returns the quarter ranging from 1 to 4.

Examples:

date = Polars.date_range(
  Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
).alias("date")
date.dt.quarter
# =>
# shape: (4,)
# Series: 'date' [i8]
# [
#         1
#         1
#         1
#         2
# ]

Returns:



363
364
365
 
# File 'lib/polars/date_time_name_space.rb', line 363

def quarter
  super
end

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

Replace time unit.

Examples:

s = Polars::Series.new("date", [Date.new(2013, 1, 1), Date.new(2024, 1, 2)])
s.dt.replace(year: 1800)
# =>
# shape: (2,)
# Series: 'date' [date]
# [
#         1800-01-01
#         1800-01-02
# ]

Parameters:

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

    Literal or Series.

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

    Literal or Series, ranging from 1-12.

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

    Literal or Series, ranging from 1-31.

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

    Literal or Series, ranging from 0-23.

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

    Literal or Series, ranging from 0-59.

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

    Literal or Series, ranging from 0-59.

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

    Literal or Series, 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:



1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
 
# File 'lib/polars/date_time_name_space.rb', line 1628

def replace(
  year: nil,
  month: nil,
  day: nil,
  hour: nil,
  minute: nil,
  second: nil,
  microsecond: nil,
  ambiguous: "raise"
)
  super
end

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

Cast time zone for a Series of type Datetime.

Different from with_time_zone, this will also modify the underlying timestamp.

Examples:

start = DateTime.new(2020, 3, 1)
stop = DateTime.new(2020, 5, 1)
date = Polars.datetime_range(start, stop, "1mo", time_zone: "UTC", eager: true).alias("datetime")
# =>
# shape: (3,)
# Series: 'datetime' [datetime[ns, UTC]]
# [
#         2020-03-01 00:00:00 UTC
#         2020-04-01 00:00:00 UTC
#         2020-05-01 00:00:00 UTC
# ]
date.dt.epoch("s")
# =>
# shape: (3,)
# Series: 'datetime' [i64]
# [
#         1583020800
#         1585699200
#         1588291200
# ]
date = date.dt.convert_time_zone("Europe/London").alias("London")
# =>
# shape: (3,)
# Series: 'London' [datetime[ns, Europe/London]]
# [
#         2020-03-01 00:00:00 GMT
#         2020-04-01 01:00:00 BST
#         2020-05-01 01:00:00 BST
# ]

Timestamps have not changed after convert_time_zone

date.dt.epoch("s")
# =>
# shape: (3,)
# Series: 'London' [i64]
# [
#         1583020800
#         1585699200
#         1588291200
# ]
date = date.dt.replace_time_zone("America/New_York").alias("NYC")
# =>
# shape: (3,)
# Series: 'NYC' [datetime[ns, America/New_York]]
# [
#         2020-03-01 00:00:00 EST
#         2020-04-01 01:00:00 EDT
#         2020-05-01 01:00:00 EDT
# ]

Timestamps have changed after replace_time_zone

date.dt.epoch("s")
# =>
# shape: (3,)
# Series: 'NYC' [i64]
# [
#         1583038800
#         1585717200
#         1588309200
# ]

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:



1010
1011
1012
 
# File 'lib/polars/date_time_name_space.rb', line 1010

def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
  super
end

#round(every) ⇒ Series

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.

The every and offset argument are created with the 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

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

Examples:

start = Time.utc(2001, 1, 1)
stop = Time.utc(2001, 1, 2)
s = Polars.datetime_range(
  start, stop, "165m", eager: true
).alias("datetime")
s.dt.round("1h")
# =>
# shape: (9,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 03:00:00
#         2001-01-01 06:00:00
#         2001-01-01 08:00:00
#         2001-01-01 11:00:00
#         2001-01-01 14:00:00
#         2001-01-01 17:00:00
#         2001-01-01 19:00:00
#         2001-01-01 22:00:00
# ]
round_str = s.dt.round("1h")
round_td = s.dt.round("1h")
round_str.equals(round_td)
# => true
start = Time.utc(2001, 1, 1)
stop = Time.utc(2001, 1, 1, 1)
s = Polars.datetime_range(start, stop, "10m", eager: true).alias("datetime")
s.dt.round("30m")
# =>
# shape: (7,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00
#         2001-01-01 00:30:00
#         2001-01-01 00:30: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:



1464
1465
1466
 
# File 'lib/polars/date_time_name_space.rb', line 1464

def round(every)
  super
end

#second(fractional: false) ⇒ Series

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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 0, 0, 4)
date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
date.dt.second
# =>
# shape: (9,)
# Series: 'datetime' [i8]
# [
#         0
#         0
#         1
#         1
#         2
#         2
#         3
#         3
#         4
# ]
date.dt.second(fractional: true)
# =>
# shape: (9,)
# Series: 'datetime' [f64]
# [
#         0.0
#         0.5
#         1.0
#         1.5
#         2.0
#         2.5
#         3.0
#         3.5
#         4.0
# ]

Returns:



669
670
671
 
# File 'lib/polars/date_time_name_space.rb', line 669

def second(fractional: false)
  super
end

#strftime(format) ⇒ Series

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:

s = Polars::Series.new(
  "datetime",
  [DateTime.new(2020, 3, 1), DateTime.new(2020, 4, 1), DateTime.new(2020, 5, 1)]
)
s.dt.strftime("%Y/%m/%d")
# =>
# shape: (3,)
# Series: 'datetime' [str]
# [
#         "2020/03/01"
#         "2020/04/01"
#         "2020/05/01"
# ]

Parameters:

Returns:



162
163
164
 
# File 'lib/polars/date_time_name_space.rb', line 162

def strftime(format)
  super
end

#time ⇒ Object

Extract (local) time.

Applies to Date/Datetime/Time columns.

Examples:

ser = Polars::Series.new([DateTime.new(2021, 1, 2, 5)]).dt.replace_time_zone(
  "Asia/Kathmandu"
)
ser.dt.time
# =>
# shape: (1,)
# Series: '' [time]
# [
#         05:00:00
# ]

Returns:



547
548
549
 
# File 'lib/polars/date_time_name_space.rb', line 547

def time
  super
end

#timestamp(time_unit = "us") ⇒ Series

Return a timestamp in the given time unit.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
# =>
# shape: (3,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]
date.dt.timestamp.alias("timestamp_us")
# =>
# shape: (3,)
# Series: 'timestamp_us' [i64]
# [
#         978307200000000
#         978393600000000
#         978480000000000
# ]
date.dt.timestamp("ns").alias("timestamp_ns")
# =>
# shape: (3,)
# Series: 'timestamp_ns' [i64]
# [
#         978307200000000000
#         978393600000000000
#         978480000000000000
# ]

Parameters:

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

    Time unit.

Returns:



801
802
803
 
# File 'lib/polars/date_time_name_space.rb', line 801

def timestamp(time_unit = "us")
  super
end

#to_string(format = nil) ⇒ Series

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:

s = Polars::Series.new(
  "datetime",
  [DateTime.new(2020, 3, 1), DateTime.new(2020, 4, 1), DateTime.new(2020, 5, 1)],
)
s.dt.to_string("%Y/%m/%d")
# =>
# shape: (3,)
# Series: 'datetime' [str]
# [
#         "2020/03/01"
#         "2020/04/01"
#         "2020/05/01"
# ]

Parameters:

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

    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:



133
134
135
 
# File 'lib/polars/date_time_name_space.rb', line 133

def to_string(format = nil)
  super
end

#total_days(fractional: false) ⇒ Series

Extract the days from a Duration type.

Examples:

date = Polars.datetime_range(
  Time.utc(2020, 3, 1), Time.utc(2020, 5, 1), "1mo", eager: true
).alias("datetime")
date.diff.dt.total_days
# =>
# shape: (3,)
# Series: 'datetime' [i64]
# [
#         null
#         31
#         30
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the day.

Returns:



1034
1035
1036
 
# File 'lib/polars/date_time_name_space.rb', line 1034

def total_days(fractional: false)
  super
end

#total_hours(fractional: false) ⇒ Series

Extract the hours from a Duration type.

Examples:

date = Polars.datetime_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", time_unit: "us", eager: true).alias("datetime")
# =>
# shape: (4,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-02 00:00:00
#         2020-01-03 00:00:00
#         2020-01-04 00:00:00
# ]
date.diff.dt.total_hours
# =>
# shape: (4,)
# Series: 'datetime' [i64]
# [
#         null
#         24
#         24
#         24
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the hour.

Returns:



1068
1069
1070
 
# File 'lib/polars/date_time_name_space.rb', line 1068

def total_hours(fractional: false)
  super
end

#total_microseconds(fractional: false) ⇒ Series

Extract the microseconds from a Duration type.

Examples:

date = Polars.datetime_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
).alias("datetime")[0..2]
# =>
# shape: (3,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-01 00:00:00.001
#         2020-01-01 00:00:00.002
# ]
date.diff.dt.total_microseconds
# =>
# shape: (3,)
# Series: 'datetime' [i64]
# [
#         null
#         1000
#         1000
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the microsecond.

Returns:



1208
1209
1210
 
# File 'lib/polars/date_time_name_space.rb', line 1208

def total_microseconds(fractional: false)
  super
end

#total_milliseconds(fractional: false) ⇒ Series

Extract the milliseconds from a Duration type.

Examples:

date = Polars.datetime_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
).alias("datetime")[0..2]
# =>
# shape: (3,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-01 00:00:00.001
#         2020-01-01 00:00:00.002
# ]
date.diff.dt.total_milliseconds
# =>
# shape: (3,)
# Series: 'datetime' [i64]
# [
#         null
#         1
#         1
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the millisecond.

Returns:



1174
1175
1176
 
# File 'lib/polars/date_time_name_space.rb', line 1174

def total_milliseconds(fractional: false)
  super
end

#total_minutes(fractional: false) ⇒ Series

Extract the minutes from a Duration type.

Examples:

date = Polars.datetime_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", time_unit: "us", eager: true).alias("datetime")
# =>
# shape: (4,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-02 00:00:00
#         2020-01-03 00:00:00
#         2020-01-04 00:00:00
# ]
date.diff.dt.total_minutes
# =>
# shape: (4,)
# Series: 'datetime' [i64]
# [
#         null
#         1440
#         1440
#         1440
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the minute.

Returns:



1102
1103
1104
 
# File 'lib/polars/date_time_name_space.rb', line 1102

def total_minutes(fractional: false)
  super
end

#total_nanoseconds(fractional: false) ⇒ Series

Extract the nanoseconds from a Duration type.

Examples:

date = Polars.datetime_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
).alias("datetime")[0..2]
# =>
# shape: (3,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-01 00:00:00.001
#         2020-01-01 00:00:00.002
# ]
date.diff.dt.total_nanoseconds
# =>
# shape: (3,)
# Series: 'datetime' [i64]
# [
#         null
#         1000000
#         1000000
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include return the result as a Float64. Because the smallest TimeUnit is 'ns', the fractional component will always be zero.

Returns:



1244
1245
1246
 
# File 'lib/polars/date_time_name_space.rb', line 1244

def total_nanoseconds(fractional: false)
  super
end

#total_seconds(fractional: false) ⇒ Series

Extract the seconds from a Duration type.

Examples:

date = Polars.datetime_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m", time_unit: "us", eager: true
).alias("datetime")
# =>
# shape: (5,)
# Series: 'datetime' [datetime[μs]]
# [
#         2020-01-01 00:00:00
#         2020-01-01 00:01:00
#         2020-01-01 00:02:00
#         2020-01-01 00:03:00
#         2020-01-01 00:04:00
# ]
date.diff.dt.total_seconds
# =>
# shape: (5,)
# Series: 'datetime' [i64]
# [
#         null
#         60
#         60
#         60
#         60
# ]

Parameters:

  • fractional (Boolean) (defaults to: false) —

    Whether to include the fractional component of the second.

Returns:



1140
1141
1142
 
# File 'lib/polars/date_time_name_space.rb', line 1140

def total_seconds(fractional: false)
  super
end

#truncate(every) ⇒ Series

Divide the date/ datetime range into buckets.

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

The every and offset argument are created with the 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

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

Examples:

s = Polars.datetime_range(
  Time.utc(2001, 1, 1),
  Time.utc(2001, 1, 2),
  "165m",
  eager: true
).alias("datetime")
s.dt.truncate("1h")
# =>
# shape: (9,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 02:00:00
#         2001-01-01 05:00:00
#         2001-01-01 08:00:00
#         2001-01-01 11:00:00
#         2001-01-01 13:00:00
#         2001-01-01 16:00:00
#         2001-01-01 19:00:00
#         2001-01-01 22:00:00
# ]
s = Polars.datetime_range(
  Time.utc(2001, 1, 1), Time.utc(2001, 1, 1, 1), "10m", eager: true
).alias("datetime")
s.dt.truncate("30m")
# =>
# shape: (7,)
# Series: 'datetime' [datetime[ns]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00
#         2001-01-01 00:30:00
#         2001-01-01 00:30:00
#         2001-01-01 00:30:00
#         2001-01-01 01:00:00
# ]

Parameters:

  • every (String) —

    Every interval start and period length.

Returns:



1383
1384
1385
 
# File 'lib/polars/date_time_name_space.rb', line 1383

def truncate(every)
  super
end

#week ⇒ Series

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:

date = Polars.date_range(
  Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
).alias("date")
date.dt.week
# =>
# shape: (4,)
# Series: 'date' [i8]
# [
#         1
#         5
#         9
#         13
# ]

Returns:



443
444
445
 
# File 'lib/polars/date_time_name_space.rb', line 443

def week
  super
end

#weekday ⇒ Series

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:

s = Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 7), eager: true).alias(
  "date"
)
s.dt.weekday
# =>
# shape: (7,)
# Series: 'date' [i8]
# [
#         1
#         2
#         3
#         4
#         5
#         6
#         7
# ]

Returns:



472
473
474
 
# File 'lib/polars/date_time_name_space.rb', line 472

def weekday
  super
end

#year ⇒ Series

Extract the year from the underlying date representation.

Applies to Date and Datetime columns.

Returns the year number in the calendar date.

Examples:

s = Polars::Series.new("date", [Date.new(2001, 1, 1), Date.new(2002, 1, 1)])
s.dt.year
# =>
# shape: (2,)
# Series: 'date' [i32]
# [
#         2001
#         2002
# ]

Returns:



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

def year
  super
end