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:



1597
1598
1599
 
# File 'lib/polars/date_time_name_space.rb', line 1597

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:



940
941
942
 
# File 'lib/polars/date_time_name_space.rb', line 940

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:



268
269
270
 
# File 'lib/polars/date_time_name_space.rb', line 268

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.

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:



1525
1526
1527
 
# File 'lib/polars/date_time_name_space.rb', line 1525

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:



974
975
976
 
# File 'lib/polars/date_time_name_space.rb', line 974

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:



580
581
582
 
# File 'lib/polars/date_time_name_space.rb', line 580

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:



512
513
514
 
# File 'lib/polars/date_time_name_space.rb', line 512

def day
  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:



1620
1621
1622
 
# File 'lib/polars/date_time_name_space.rb', line 1620

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:



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

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:



606
607
608
 
# File 'lib/polars/date_time_name_space.rb', line 606

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:



328
329
330
331
332
 
# File 'lib/polars/date_time_name_space.rb', line 328

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:



353
354
355
 
# File 'lib/polars/date_time_name_space.rb', line 353

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:



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

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

#mean ⇒ Object

Return mean as Ruby object.

Examples:

s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2)])
s.dt.mean
# => 2001-01-01 12:00:00 UTC
s = Polars::Series.new(
  [DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 2), DateTime.new(2001, 1, 3)]
)
s.dt.mean
# => 2001-01-02 00:00:00 UTC

Returns:



146
147
148
 
# File 'lib/polars/date_time_name_space.rb', line 146

def mean
  _s.mean
end

#median ⇒ Object

Return median as Ruby object.

Examples:

date = Polars.datetime_range(
  DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "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.median
# => 2001-01-02 00:00:00 UTC

Returns:



127
128
129
 
# File 'lib/polars/date_time_name_space.rb', line 127

def median
  _s.median
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:



739
740
741
 
# File 'lib/polars/date_time_name_space.rb', line 739

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:



234
235
236
 
# File 'lib/polars/date_time_name_space.rb', line 234

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:



710
711
712
 
# File 'lib/polars/date_time_name_space.rb', line 710

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:



631
632
633
 
# File 'lib/polars/date_time_name_space.rb', line 631

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:



428
429
430
 
# File 'lib/polars/date_time_name_space.rb', line 428

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:



1569
1570
1571
 
# File 'lib/polars/date_time_name_space.rb', line 1569

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:



1547
1548
1549
 
# File 'lib/polars/date_time_name_space.rb', line 1547

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:



768
769
770
 
# File 'lib/polars/date_time_name_space.rb', line 768

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:



1360
1361
1362
 
# File 'lib/polars/date_time_name_space.rb', line 1360

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:



538
539
540
 
# File 'lib/polars/date_time_name_space.rb', line 538

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:



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

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:



1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
 
# File 'lib/polars/date_time_name_space.rb', line 1660

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:



1059
1060
1061
 
# File 'lib/polars/date_time_name_space.rb', line 1059

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:



1510
1511
1512
 
# File 'lib/polars/date_time_name_space.rb', line 1510

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:



681
682
683
 
# File 'lib/polars/date_time_name_space.rb', line 681

def second(fractional: false)
  super
end

#strftime(fmt) ⇒ Series

Format Date/datetime with a formatting rule.

See chrono strftime/strptime.

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"
# ]

Returns:



200
201
202
 
# File 'lib/polars/date_time_name_space.rb', line 200

def strftime(fmt)
  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:



559
560
561
 
# File 'lib/polars/date_time_name_space.rb', line 559

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:



813
814
815
 
# File 'lib/polars/date_time_name_space.rb', line 813

def timestamp(time_unit = "us")
  super
end

#to_string(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.to_string("%Y/%m/%d")
# =>
# shape: (3,)
# Series: 'datetime' [str]
# [
#         "2020/03/01"
#         "2020/04/01"
#         "2020/05/01"
# ]

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:



176
177
178
 
# File 'lib/polars/date_time_name_space.rb', line 176

def to_string(format)
  super
end

#total_days ⇒ Series Also known as: days

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

Returns:



1093
1094
1095
 
# File 'lib/polars/date_time_name_space.rb', line 1093

def total_days
  super
end

#total_hours ⇒ Series Also known as: hours

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

Returns:



1125
1126
1127
 
# File 'lib/polars/date_time_name_space.rb', line 1125

def total_hours
  super
end

#total_microseconds ⇒ Series Also known as: microseconds

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

Returns:



1257
1258
1259
 
# File 'lib/polars/date_time_name_space.rb', line 1257

def total_microseconds
  super
end

#total_milliseconds ⇒ Series Also known as: milliseconds

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

Returns:



1225
1226
1227
 
# File 'lib/polars/date_time_name_space.rb', line 1225

def total_milliseconds
  super
end

#total_minutes ⇒ Series Also known as: minutes

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

Returns:



1157
1158
1159
 
# File 'lib/polars/date_time_name_space.rb', line 1157

def total_minutes
  super
end

#total_nanoseconds ⇒ Series Also known as: nanoseconds

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

Returns:



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

def total_nanoseconds
  super
end

#total_seconds ⇒ Series Also known as: seconds

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

Returns:



1193
1194
1195
 
# File 'lib/polars/date_time_name_space.rb', line 1193

def total_seconds
  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:



1429
1430
1431
 
# File 'lib/polars/date_time_name_space.rb', line 1429

def truncate(every)
  super
end

#tz_localize(tz) ⇒ Series

Localize tz-naive Datetime Series to tz-aware Datetime Series.

This method takes a naive Datetime Series and makes this time zone aware. It does not move the time to another time zone.

Parameters:

  • tz (String) —

    Time zone for the Datetime Series.

Returns:



1072
1073
1074
 
# File 'lib/polars/date_time_name_space.rb', line 1072

def tz_localize(tz)
  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:



455
456
457
 
# File 'lib/polars/date_time_name_space.rb', line 455

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:



484
485
486
 
# File 'lib/polars/date_time_name_space.rb', line 484

def weekday
  super
end

#with_time_unit(time_unit) ⇒ Series

Set time unit a Series of dtype Datetime or Duration.

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

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 3)
date = Polars.datetime_range(start, stop, "1d", time_unit: "ns", 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.with_time_unit("us").alias("tu_us")
# =>
# shape: (3,)
# Series: 'tu_us' [datetime[μs]]
# [
#         +32971-04-28 00:00:00
#         +32974-01-22 00:00:00
#         +32976-10-18 00:00:00
# ]

Parameters:

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

    Time unit for the Datetime Series.

Returns:



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

def with_time_unit(time_unit)
  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:



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

def year
  super
end