Class: Polars::DateTimeNameSpace

Inherits:

Object

Object
Polars::DateTimeNameSpace

show all

Defined in:: lib/polars/date_time_name_space.rb

Overview

Series.dt namespace.

Instance Method Summary collapse

#[](item) ⇒ Object
Get item.
#cast_time_unit(tu) ⇒ Series
Cast the underlying data to another time unit.
#convert_time_zone(tz) ⇒ Series
Set time zone a Series of type Datetime.
#day ⇒ Series
Extract the day from the underlying date representation.
#days ⇒ Series
Extract the days from a Duration type.
#epoch(tu = "us") ⇒ Series
Get the time passed since the Unix EPOCH in the give time unit.
#hour ⇒ Series
Extract the hour from the underlying DateTime representation.
#hours ⇒ Series
Extract the hours from a Duration type.
#iso_year ⇒ Series
Extract ISO year from underlying Date representation.
#max ⇒ Object
Return maximum as Ruby object.
#mean ⇒ Object
Return mean as Ruby object.
#median ⇒ Object
Return median as Ruby object.
#microsecond ⇒ Series
Extract the microseconds from the underlying DateTime representation.
#microseconds ⇒ Series
Extract the microseconds from a Duration type.
#millisecond ⇒ Series
Extract the milliseconds from the underlying DateTime representation.
#milliseconds ⇒ Series
Extract the milliseconds from a Duration type.
#min ⇒ Object
Return minimum as Ruby object.
#minute ⇒ Series
Extract the minutes from the underlying DateTime representation.
#minutes ⇒ Series
Extract the minutes from a Duration type.
#month ⇒ Series
Extract the month from the underlying date representation.
#nanosecond ⇒ Series
Extract the nanoseconds from the underlying DateTime representation.
#nanoseconds ⇒ Series
Extract the nanoseconds from a Duration type.
#offset_by(by) ⇒ Series
Offset this date by a relative time offset.
#ordinal_day ⇒ Series
Extract ordinal day from underlying date representation.
#quarter ⇒ Series
Extract quarter from underlying Date representation.
#replace_time_zone(tz) ⇒ Series
Cast time zone for a Series of type Datetime.
#round(every, offset: nil) ⇒ Series
Divide the date/ datetime range into buckets.
#second(fractional: false) ⇒ Series
Extract seconds from underlying DateTime representation.
#seconds ⇒ Series
Extract the seconds from a Duration type.
#strftime(fmt) ⇒ Series
Format Date/datetime with a formatting rule.
#timestamp(tu = "us") ⇒ Series
Return a timestamp in the given time unit.
#truncate(every, offset: nil, use_earliest: nil) ⇒ Series
Divide the date/ datetime range into buckets.
#tz_localize(tz) ⇒ Series
Localize tz-naive Datetime Series to tz-aware Datetime Series.
#week ⇒ Series
Extract the week from the underlying date representation.
#weekday ⇒ Series
Extract the week day from the underlying date representation.
#with_time_unit(tu) ⇒ Series
Set time unit a Series of dtype Datetime or Duration.
#year ⇒ Series
Extract the year from the underlying date representation.

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:

(Object)

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

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

#cast_time_unit(tu) ⇒ `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.date_range(start, stop, "1d")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         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:

tu ("ns", "us", "ms") —
Time unit for the Datetime Series.

Returns:

(Series)



870
871
872

# File 'lib/polars/date_time_name_space.rb', line 870

def cast_time_unit(tu)
  super
end

#convert_time_zone(tz) ⇒ `Series`

Set time zone a Series of type Datetime.

Examples:

start = DateTime.new(2020, 3, 1)
stop = DateTime.new(2020, 5, 1)
date = Polars.date_range(start, stop, "1mo", time_zone: "UTC")
# =>
# shape: (3,)
# Series: '' [datetime[μs, 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[μs, Europe/London]]
# [
#         2020-03-01 00:00:00 GMT
#         2020-04-01 01:00:00 BST
#         2020-05-01 01:00:00 BST
# ]

Parameters:

tz (String) —
Time zone for the Datetime Series.

Returns:

(Series)



904
905
906

# File 'lib/polars/date_time_name_space.rb', line 904

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

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 9)
date = Polars.date_range(start, stop, "2d")
# =>
# shape: (5,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-03 00:00:00
#         2001-01-05 00:00:00
#         2001-01-07 00:00:00
#         2001-01-09 00:00:00
# ]

date.dt.day
# =>
# shape: (5,)
# Series: '' [i8]
# [
#         1
#         3
#         5
#         7
#         9
# ]

Returns:

(Series)



389
390
391

# File 'lib/polars/date_time_name_space.rb', line 389

def day
  super
end

#days ⇒ `Series`

Extract the days from a Duration type.

Examples:

date = Polars.date_range(DateTime.new(2020, 3, 1), DateTime.new(2020, 5, 1), "1mo")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         2020-03-01 00:00:00
#         2020-04-01 00:00:00
#         2020-05-01 00:00:00
# ]

date.diff.dt.days
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         null
#         31
#         30
# ]

Returns:

(Series)



1027
1028
1029

# File 'lib/polars/date_time_name_space.rb', line 1027

def days
  super
end

#epoch(tu = "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.date_range(start, stop, "1d")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         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:

tu ("us", "ns", "ms", "s", "d") (defaults to: "us") —
Time unit.

Returns:

(Series)



788
789
790

# File 'lib/polars/date_time_name_space.rb', line 788

def epoch(tu = "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.date_range(start, stop, "1h")
# =>
# shape: (4,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 01:00:00
#         2001-01-01 02:00:00
#         2001-01-01 03:00:00
# ]

date.dt.hour
# =>
# shape: (4,)
# Series: '' [i8]
# [
#         0
#         1
#         2
#         3
# ]

Returns:

(Series)



462
463
464

# File 'lib/polars/date_time_name_space.rb', line 462

def hour
  super
end

#hours ⇒ `Series`

Extract the hours from a Duration type.

Examples:

date = Polars.date_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d")
# =>
# shape: (4,)
# Series: '' [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.hours
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         null
#         24
#         24
#         24
# ]

Returns:

(Series)



1058
1059
1060

# File 'lib/polars/date_time_name_space.rb', line 1058

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

(Series)



193
194
195

# File 'lib/polars/date_time_name_space.rb', line 193

def iso_year
  super
end

#max ⇒ `Object`

Return maximum as Ruby object.

Examples:

s = Polars.date_range(DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d")
s.dt.max
# => 2001-01-03 00:00:00 UTC

Returns:

(Object)



41
42
43

# File 'lib/polars/date_time_name_space.rb', line 41

def max
  Utils.wrap_s(_s).max
end

#mean ⇒ `Object`

Return mean as Ruby object.

Examples:

date = Polars.date_range(DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
# ]

date.dt.mean
# => 2001-01-02 00:00:00 UTC

Returns:

(Object)

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

def mean
  s = Utils.wrap_s(_s)
  out = s.mean.to_i
  if !out.nil?
    if s.dtype == Date
      return Utils._to_ruby_date(out.to_i)
    else
      return Utils._to_ruby_datetime(out.to_i, s.time_unit)
    end
  end
  nil
end

#median ⇒ `Object`

Return median as Ruby object.

Examples:

date = Polars.date_range(DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         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:

(Object)

# File 'lib/polars/date_time_name_space.rb', line 63

def median
  s = Utils.wrap_s(_s)
  out = s.median
  if !out.nil?
    if s.dtype == Date
      return Utils._to_ruby_date(out.to_i)
    else
      return Utils._to_ruby_datetime(out.to_i, s.time_unit)
    end
  end
  nil
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.date_range(start, stop, "500ms")
# =>
# shape: (9,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00.500
#         2001-01-01 00:00:01
#         2001-01-01 00:00:01.500
#         2001-01-01 00:00:02
#         2001-01-01 00:00:02.500
#         2001-01-01 00:00:03
#         2001-01-01 00:00:03.500
#         2001-01-01 00:00:04
# ]

date.dt.microsecond
# =>
# shape: (9,)
# Series: '' [i32]
# [
#         0
#         500000
#         0
#         500000
#         0
#         500000
#         0
#         500000
#         0
# ]

Returns:

(Series)



653
654
655

# File 'lib/polars/date_time_name_space.rb', line 653

def microsecond
  super
end

#microseconds ⇒ `Series`

Extract the microseconds from a Duration type.

Examples:

date = Polars.date_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms"
)[0..2]
# =>
# shape: (3,)
# Series: '' [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.microseconds
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         null
#         1000
#         1000
# ]

Returns:

(Series)



1186
1187
1188

# File 'lib/polars/date_time_name_space.rb', line 1186

def microseconds
  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.date_range(start, stop, "500ms")
# =>
# shape: (9,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00.500
#         2001-01-01 00:00:01
#         2001-01-01 00:00:01.500
#         2001-01-01 00:00:02
#         2001-01-01 00:00:02.500
#         2001-01-01 00:00:03
#         2001-01-01 00:00:03.500
#         2001-01-01 00:00:04
# ]

date.dt.millisecond
# =>
# shape: (9,)
# Series: '' [i32]
# [
#         0
#         500
#         0
#         500
#         0
#         500
#         0
#         500
#         0
# ]

Returns:

(Series)



608
609
610

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

def millisecond
  super
end

#milliseconds ⇒ `Series`

Extract the milliseconds from a Duration type.

Examples:

date = Polars.date_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms"
)[0..2]
# =>
# shape: (3,)
# Series: '' [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.milliseconds
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         null
#         1
#         1
# ]

Returns:

(Series)



1155
1156
1157

# File 'lib/polars/date_time_name_space.rb', line 1155

def milliseconds
  super
end

#min ⇒ `Object`

Return minimum as Ruby object.

Examples:

s = Polars.date_range(DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d")
s.dt.min
# => 2001-01-01 00:00:00 UTC

Returns:

(Object)



29
30
31

# File 'lib/polars/date_time_name_space.rb', line 29

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.date_range(start, stop, "2m")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:02:00
#         2001-01-01 00:04:00
# ]

date.dt.minute
# =>
# shape: (3,)
# Series: '' [i8]
# [
#         0
#         2
#         4
# ]

Returns:

(Series)



497
498
499

# File 'lib/polars/date_time_name_space.rb', line 497

def minute
  super
end

#minutes ⇒ `Series`

Extract the minutes from a Duration type.

Examples:

date = Polars.date_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d")
# =>
# shape: (4,)
# Series: '' [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.minutes
# =>
# shape: (4,)
# Series: '' [i64]
# [
#         null
#         1440
#         1440
#         1440
# ]

Returns:

(Series)



1089
1090
1091

# File 'lib/polars/date_time_name_space.rb', line 1089

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

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
date = Polars.date_range(start, stop, "1mo")
# =>
# shape: (4,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-02-01 00:00:00
#         2001-03-01 00:00:00
#         2001-04-01 00:00:00
# ]

date.dt.month
# =>
# shape: (4,)
# Series: '' [i8]
# [
#         1
#         2
#         3
#         4
# ]

Returns:

(Series)



268
269
270

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

def month
  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.date_range(start, stop, "500ms")
# =>
# shape: (9,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00.500
#         2001-01-01 00:00:01
#         2001-01-01 00:00:01.500
#         2001-01-01 00:00:02
#         2001-01-01 00:00:02.500
#         2001-01-01 00:00:03
#         2001-01-01 00:00:03.500
#         2001-01-01 00:00:04
# ]

date.dt.nanosecond
# =>
# shape: (9,)
# Series: '' [i32]
# [
#         0
#         500000000
#         0
#         500000000
#         0
#         500000000
#         0
#         500000000
#         0
# ]

Returns:

(Series)



698
699
700

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

def nanosecond
  super
end

#nanoseconds ⇒ `Series`

Extract the nanoseconds from a Duration type.

Examples:

date = Polars.date_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms"
)[0..2]
# =>
# shape: (3,)
# Series: '' [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.nanoseconds
# =>
# shape: (3,)
# Series: '' [i64]
# [
#         null
#         1000000
#         1000000
# ]

Returns:

(Series)



1217
1218
1219

# File 'lib/polars/date_time_name_space.rb', line 1217

def nanoseconds
  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.date_range(DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y")
# =>
# shape: (6,)
# Series: '' [datetime[μs]]
# [
#         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[μs]]
# [
#         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[μs]]
# [
#         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:

(Series)



1285
1286
1287

# File 'lib/polars/date_time_name_space.rb', line 1285

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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 3, 1)
date = Polars.date_range(start, stop, "1mo")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-02-01 00:00:00
#         2001-03-01 00:00:00
# ]

date.dt.ordinal_day
# =>
# shape: (3,)
# Series: '' [i16]
# [
#         1
#         32
#         60
# ]

Returns:

(Series)



425
426
427

# File 'lib/polars/date_time_name_space.rb', line 425

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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
date = Polars.date_range(start, stop, "1mo")
# =>
# shape: (4,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-02-01 00:00:00
#         2001-03-01 00:00:00
#         2001-04-01 00:00:00
# ]

date.dt.quarter
# =>
# shape: (4,)
# Series: '' [i8]
# [
#         1
#         1
#         1
#         2
# ]

Returns:

(Series)



230
231
232

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

def quarter
  super
end

#replace_time_zone(tz) ⇒ `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.date_range(start, stop, "1mo", time_zone: "UTC")
# =>
# shape: (3,)
# Series: '' [datetime[μs, 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: '' [i64]
# [
#         1583020800
#         1585699200
#         1588291200
# ]

date = date.dt.convert_time_zone("Europe/London").alias("London")
# =>
# shape: (3,)
# Series: 'London' [datetime[μs, 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[μs, 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:

tz (String) —
Time zone for the Datetime Series.

Returns:

(Series)



985
986
987

# File 'lib/polars/date_time_name_space.rb', line 985

def replace_time_zone(tz)
  super
end

#round(every, offset: nil) ⇒ `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 = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
s = Polars.date_range(start, stop, "165m", name: "dates")
# =>
# shape: (9,)
# Series: 'dates' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 02:45:00
#         2001-01-01 05:30:00
#         2001-01-01 08:15:00
#         2001-01-01 11:00:00
#         2001-01-01 13:45:00
#         2001-01-01 16:30:00
#         2001-01-01 19:15:00
#         2001-01-01 22:00:00
# ]

s.dt.round("1h")
# =>
# shape: (9,)
# Series: 'dates' [datetime[μs]]
# [
#         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
# ]

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
s = Polars.date_range(start, stop, "10m", name: "dates")
s.dt.round("30m")
# =>
# shape: (7,)
# Series: 'dates' [datetime[μs]]
# [
#         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.
offset (String) (defaults to: nil) —
Offset the window.

Returns:

(Series)



1474
1475
1476

# File 'lib/polars/date_time_name_space.rb', line 1474

def round(every, offset: nil)
  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.date_range(start, stop, "500ms")
# =>
# shape: (9,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:00:00.500
#         2001-01-01 00:00:01
#         2001-01-01 00:00:01.500
#         2001-01-01 00:00:02
#         2001-01-01 00:00:02.500
#         2001-01-01 00:00:03
#         2001-01-01 00:00:03.500
#         2001-01-01 00:00:04
# ]

date.dt.second
# =>
# shape: (9,)
# Series: '' [i8]
# [
#         0
#         0
#         1
#         1
#         2
#         2
#         3
#         3
#         4
# ]

date.dt.second(fractional: true)
# =>
# shape: (9,)
# Series: '' [f64]
# [
#         0.0
#         0.5
#         1.0
#         1.5
#         2.0
#         2.5
#         3.0
#         3.5
#         4.0
# ]

Returns:

(Series)



563
564
565

# File 'lib/polars/date_time_name_space.rb', line 563

def second(fractional: false)
  super
end

#seconds ⇒ `Series`

Extract the seconds from a Duration type.

Examples:

date = Polars.date_range(
  DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m"
)
# =>
# shape: (5,)
# Series: '' [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.seconds
# =>
# shape: (5,)
# Series: '' [i64]
# [
#         null
#         60
#         60
#         60
#         60
# ]

Returns:

(Series)



1124
1125
1126

# File 'lib/polars/date_time_name_space.rb', line 1124

def seconds
  super
end

#strftime(fmt) ⇒ `Series`

Format Date/datetime with a formatting rule.

See chrono strftime/strptime.

Examples:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 4)
date = Polars.date_range(start, stop, "1d")
# =>
# shape: (4,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
#         2001-01-04 00:00:00
# ]

date.dt.strftime("%Y-%m-%d")
# =>
# shape: (4,)
# Series: '' [str]
# [
#         "2001-01-01"
#         "2001-01-02"
#         "2001-01-03"
#         "2001-01-04"
# ]

Returns:

(Series)



138
139
140

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

def strftime(fmt)
  super
end

#timestamp(tu = "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.date_range(start, stop, "1d")
# =>
# shape: (3,)
# Series: '' [datetime[μs]]
# [
#         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:

tu ("us", "ns", "ms") (defaults to: "us") —
Time unit.

Returns:

(Series)



743
744
745

# File 'lib/polars/date_time_name_space.rb', line 743

def timestamp(tu = "us")
  super
end

#truncate(every, offset: nil, use_earliest: nil) ⇒ `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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 2)
s = Polars.date_range(start, stop, "165m", name: "dates")
# =>
# shape: (9,)
# Series: 'dates' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 02:45:00
#         2001-01-01 05:30:00
#         2001-01-01 08:15:00
#         2001-01-01 11:00:00
#         2001-01-01 13:45:00
#         2001-01-01 16:30:00
#         2001-01-01 19:15:00
#         2001-01-01 22:00:00
# ]

s.dt.truncate("1h")
# =>
# shape: (9,)
# Series: 'dates' [datetime[μs]]
# [
#         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
# ]

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 1, 1)
s = Polars.date_range(start, stop, "10m", name: "dates")
# =>
# shape: (7,)
# Series: 'dates' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-01 00:10:00
#         2001-01-01 00:20:00
#         2001-01-01 00:30:00
#         2001-01-01 00:40:00
#         2001-01-01 00:50:00
#         2001-01-01 01:00:00
# ]

s.dt.truncate("30m")
# =>
# shape: (7,)
# Series: 'dates' [datetime[μs]]
# [
#         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.
offset (String) (defaults to: nil) —
Offset the window.

Returns:

(Series)



1383
1384
1385

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

def truncate(every, offset: nil, use_earliest: nil)
  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:

(Series)



998
999
1000

# File 'lib/polars/date_time_name_space.rb', line 998

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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 4, 1)
date = Polars.date_range(start, stop, "1mo")
# =>
# shape: (4,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-02-01 00:00:00
#         2001-03-01 00:00:00
#         2001-04-01 00:00:00
# ]

date.dt.week
# =>
# shape: (4,)
# Series: '' [i8]
# [
#         1
#         5
#         9
#         13
# ]

Returns:

(Series)



306
307
308

# File 'lib/polars/date_time_name_space.rb', line 306

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:

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2001, 1, 7)
date = Polars.date_range(start, stop, "1d")
# =>
# shape: (7,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2001-01-02 00:00:00
#         2001-01-03 00:00:00
#         2001-01-04 00:00:00
#         2001-01-05 00:00:00
#         2001-01-06 00:00:00
#         2001-01-07 00:00:00
# ]

date.dt.weekday
# =>
# shape: (7,)
# Series: '' [i8]
# [
#         1
#         2
#         3
#         4
#         5
#         6
#         7
# ]

Returns:

(Series)



349
350
351

# File 'lib/polars/date_time_name_space.rb', line 349

def weekday
  super
end

#with_time_unit(tu) ⇒ `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.date_range(start, stop, "1d", time_unit: "ns")
# =>
# shape: (3,)
# Series: '' [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:

tu ("ns", "us", "ms") —
Time unit for the Datetime Series.

Returns:

(Series)



825
826
827

# File 'lib/polars/date_time_name_space.rb', line 825

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

start = DateTime.new(2001, 1, 1)
stop = DateTime.new(2002, 1, 1)
date = Polars.date_range(start, stop, "1y")
# =>
# shape: (2,)
# Series: '' [datetime[μs]]
# [
#         2001-01-01 00:00:00
#         2002-01-01 00:00:00
# ]

date.dt.year
# =>
# shape: (2,)
# Series: '' [i32]
# [
#         2001
#         2002
# ]

Returns:

(Series)



171
172
173

# File 'lib/polars/date_time_name_space.rb', line 171

def year
  super
end

Class: Polars::DateTimeNameSpace

Overview

Instance Method Summary collapse

Dynamic Method Handling

Instance Method Details

#[](item) ⇒ Object

#cast_time_unit(tu) ⇒ Series

#convert_time_zone(tz) ⇒ Series

#day ⇒ Series

#days ⇒ Series

#epoch(tu = "us") ⇒ Series

#hour ⇒ Series

#hours ⇒ Series

#iso_year ⇒ Series

#max ⇒ Object

#mean ⇒ Object

#median ⇒ Object

#microsecond ⇒ Series

#microseconds ⇒ Series

#millisecond ⇒ Series

#milliseconds ⇒ Series

#min ⇒ Object

#minute ⇒ Series

#minutes ⇒ Series

#month ⇒ Series

#nanosecond ⇒ Series

#nanoseconds ⇒ Series

#offset_by(by) ⇒ Series

#ordinal_day ⇒ Series

#quarter ⇒ Series

#replace_time_zone(tz) ⇒ Series

#round(every, offset: nil) ⇒ Series

#second(fractional: false) ⇒ Series

#seconds ⇒ Series

#strftime(fmt) ⇒ Series

#timestamp(tu = "us") ⇒ Series

#truncate(every, offset: nil, use_earliest: nil) ⇒ Series

#tz_localize(tz) ⇒ Series

#week ⇒ Series

#weekday ⇒ Series

#with_time_unit(tu) ⇒ Series

#year ⇒ Series

#[](item) ⇒ `Object`

#cast_time_unit(tu) ⇒ `Series`

#convert_time_zone(tz) ⇒ `Series`

#day ⇒ `Series`

#days ⇒ `Series`

#epoch(tu = "us") ⇒ `Series`

#hour ⇒ `Series`

#hours ⇒ `Series`

#iso_year ⇒ `Series`

#max ⇒ `Object`

#mean ⇒ `Object`

#median ⇒ `Object`

#microsecond ⇒ `Series`

#microseconds ⇒ `Series`

#millisecond ⇒ `Series`

#milliseconds ⇒ `Series`

#min ⇒ `Object`

#minute ⇒ `Series`

#minutes ⇒ `Series`

#month ⇒ `Series`

#nanosecond ⇒ `Series`

#nanoseconds ⇒ `Series`

#offset_by(by) ⇒ `Series`

#ordinal_day ⇒ `Series`

#quarter ⇒ `Series`

#replace_time_zone(tz) ⇒ `Series`

#round(every, offset: nil) ⇒ `Series`

#second(fractional: false) ⇒ `Series`

#seconds ⇒ `Series`

#strftime(fmt) ⇒ `Series`

#timestamp(tu = "us") ⇒ `Series`

#truncate(every, offset: nil, use_earliest: nil) ⇒ `Series`

#tz_localize(tz) ⇒ `Series`

#week ⇒ `Series`

#weekday ⇒ `Series`

#with_time_unit(tu) ⇒ `Series`

#year ⇒ `Series`