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], holidays: [], 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].

  • holidays (Object) (defaults to: []) —

    Holidays to exclude from the count.

Returns:



77
78
79
80
81
82
83
84
 
# File 'lib/polars/date_time_name_space.rb', line 77

def add_business_days(
  n,
  week_mask: [true, true, true, true, true, false, false],
  holidays: [],
  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:



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

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:



897
898
899
 
# File 'lib/polars/date_time_name_space.rb', line 897

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:



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

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:



1499
1500
1501
 
# File 'lib/polars/date_time_name_space.rb', line 1499

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:



931
932
933
 
# File 'lib/polars/date_time_name_space.rb', line 931

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:



574
575
576
 
# File 'lib/polars/date_time_name_space.rb', line 574

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:



506
507
508
 
# File 'lib/polars/date_time_name_space.rb', line 506

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:



422
423
424
 
# File 'lib/polars/date_time_name_space.rb', line 422

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:



1594
1595
1596
 
# File 'lib/polars/date_time_name_space.rb', line 1594

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:



852
853
854
 
# File 'lib/polars/date_time_name_space.rb', line 852

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:



600
601
602
 
# File 'lib/polars/date_time_name_space.rb', line 600

def hour
  super
end

#is_business_day(week_mask: [true, true, true, true, true, false, false], holidays: []) ⇒ 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].

  • holidays (Object) (defaults to: []) —

    Holidays to exclude from the count.

Returns:



295
296
297
298
299
300
 
# File 'lib/polars/date_time_name_space.rb', line 295

def is_business_day(
  week_mask: [true, true, true, true, true, false, false],
  holidays: []
)
  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:



321
322
323
 
# File 'lib/polars/date_time_name_space.rb', line 321

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:



343
344
345
 
# File 'lib/polars/date_time_name_space.rb', line 343

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:



106
107
108
 
# File 'lib/polars/date_time_name_space.rb', line 106

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:



733
734
735
 
# File 'lib/polars/date_time_name_space.rb', line 733

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:



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

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:



704
705
706
 
# File 'lib/polars/date_time_name_space.rb', line 704

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:



94
95
96
 
# File 'lib/polars/date_time_name_space.rb', line 94

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:



625
626
627
 
# File 'lib/polars/date_time_name_space.rb', line 625

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:



396
397
398
 
# File 'lib/polars/date_time_name_space.rb', line 396

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:



1543
1544
1545
 
# File 'lib/polars/date_time_name_space.rb', line 1543

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:



1521
1522
1523
 
# File 'lib/polars/date_time_name_space.rb', line 1521

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:



762
763
764
 
# File 'lib/polars/date_time_name_space.rb', line 762

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:



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

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:



532
533
534
 
# File 'lib/polars/date_time_name_space.rb', line 532

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:



369
370
371
 
# File 'lib/polars/date_time_name_space.rb', line 369

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:



1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
 
# File 'lib/polars/date_time_name_space.rb', line 1634

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:



1016
1017
1018
 
# File 'lib/polars/date_time_name_space.rb', line 1016

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:



1470
1471
1472
 
# File 'lib/polars/date_time_name_space.rb', line 1470

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:



675
676
677
 
# File 'lib/polars/date_time_name_space.rb', line 675

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:



165
166
167
 
# File 'lib/polars/date_time_name_space.rb', line 165

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:



553
554
555
 
# File 'lib/polars/date_time_name_space.rb', line 553

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:



807
808
809
 
# File 'lib/polars/date_time_name_space.rb', line 807

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:



136
137
138
 
# File 'lib/polars/date_time_name_space.rb', line 136

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:



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

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:



1074
1075
1076
 
# File 'lib/polars/date_time_name_space.rb', line 1074

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:



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

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:



1180
1181
1182
 
# File 'lib/polars/date_time_name_space.rb', line 1180

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:



1108
1109
1110
 
# File 'lib/polars/date_time_name_space.rb', line 1108

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:



1250
1251
1252
 
# File 'lib/polars/date_time_name_space.rb', line 1250

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:



1146
1147
1148
 
# File 'lib/polars/date_time_name_space.rb', line 1146

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:



1389
1390
1391
 
# File 'lib/polars/date_time_name_space.rb', line 1389

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:



449
450
451
 
# File 'lib/polars/date_time_name_space.rb', line 449

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:



478
479
480
 
# File 'lib/polars/date_time_name_space.rb', line 478

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:



255
256
257
 
# File 'lib/polars/date_time_name_space.rb', line 255

def year
  super
end