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.
#base_utc_offset ⇒ Series
Base offset from UTC.
#cast_time_unit(time_unit) ⇒ Series
Cast the underlying data to another time unit.
#convert_time_zone(time_zone) ⇒ Series
Set time zone a Series of type Datetime.
#day ⇒ Series
Extract the day from the underlying date representation.
#dst_offset ⇒ Series
Additional offset currently in effect (typically due to daylight saving time).
#epoch(time_unit = "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.
#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.
#millisecond ⇒ Series
Extract the milliseconds from the underlying DateTime representation.
#min ⇒ Object
Return minimum as Ruby object.
#minute ⇒ Series
Extract the minutes from the underlying DateTime representation.
#month ⇒ Series
Extract the month from the underlying date representation.
#month_end ⇒ Series
Roll forward to the last day of the month.
#month_start ⇒ Series
Roll backward to the first day of the month.
#nanosecond ⇒ Series
Extract the nanoseconds from the underlying DateTime representation.
#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(time_zone, ambiguous: "raise", non_existent: "raise") ⇒ Series
Cast time zone for a Series of type Datetime.
#round(every) ⇒ Series
Divide the date/ datetime range into buckets.
#second(fractional: false) ⇒ Series
Extract seconds from underlying DateTime representation.
#strftime(fmt) ⇒ Series
Format Date/datetime with a formatting rule.
#timestamp(time_unit = "us") ⇒ Series
Return a timestamp in the given time unit.
#to_string(format) ⇒ Series
Convert a Date/Time/Datetime column into a String column with the given format.
#total_days ⇒ Series (also: #days)
Extract the days from a Duration type.
#total_hours ⇒ Series (also: #hours)
Extract the hours from a Duration type.
#total_microseconds ⇒ Series (also: #microseconds)
Extract the microseconds from a Duration type.
#total_milliseconds ⇒ Series (also: #milliseconds)
Extract the milliseconds from a Duration type.
#total_minutes ⇒ Series (also: #minutes)
Extract the minutes from a Duration type.
#total_nanoseconds ⇒ Series (also: #nanoseconds)
Extract the nanoseconds from a Duration type.
#total_seconds ⇒ Series (also: #seconds)
Extract the seconds from a Duration type.
#truncate(every) ⇒ 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(time_unit) ⇒ 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

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

(Series)



1347
1348
1349

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

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:

(Series)



705
706
707

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

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

(Series)



739
740
741

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

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

(Series)



319
320
321

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

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:

(Series)



1370
1371
1372

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

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:

(Series)



623
624
625

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

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:

(Series)



371
372
373

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

def hour
  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)



182
183
184

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

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:

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

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:

(Object)



84
85
86

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

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:

(Object)



65
66
67

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

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:

(Series)



504
505
506

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

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

(Series)



475
476
477

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

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:

(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.datetime_range(start, stop, "2m", eager: true).alias("datetime")
date.dt.minute
# =>
# shape: (3,)
# Series: 'datetime' [i8]
# [
#         0
#         2
#         4
# ]

Returns:

(Series)



396
397
398

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

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:

(Series)



235
236
237

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

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:

(Series)



1319
1320
1321

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

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:

(Series)



1297
1298
1299

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

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:

(Series)



533
534
535

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

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:

(Series)



1125
1126
1127

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

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:

(Series)



345
346
347

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

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:

(Series)



208
209
210

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

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

(Series)



824
825
826

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

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:

(Series)



1275
1276
1277

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

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:

(Series)



446
447
448

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

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:

(Series)



138
139
140

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

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

(Series)



578
579
580

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

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:

(Series)



114
115
116

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

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:

(Series)



858
859
860

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

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:

(Series)



890
891
892

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

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:

(Series)



1022
1023
1024

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

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:

(Series)



990
991
992

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

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:

(Series)



922
923
924

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

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:

(Series)



1054
1055
1056

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

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:

(Series)



958
959
960

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

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:

(Series)



1194
1195
1196

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

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:

(Series)



837
838
839

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

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:

(Series)



262
263
264

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

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:

(Series)



291
292
293

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

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:

(Series)



660
661
662

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

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:

(Series)



160
161
162

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

def year
  super
end

Class: Polars::DateTimeNameSpace

Overview

Instance Method Summary collapse

Dynamic Method Handling

Instance Method Details

#[](item) ⇒ Object

#base_utc_offset ⇒ Series

Examples:

#cast_time_unit(time_unit) ⇒ Series

Examples:

#convert_time_zone(time_zone) ⇒ Series

Examples:

#day ⇒ Series

Examples:

#dst_offset ⇒ Series

Examples:

#epoch(time_unit = "us") ⇒ Series

Examples:

#hour ⇒ Series

Examples:

#iso_year ⇒ Series

Examples:

#max ⇒ Object

Examples:

#mean ⇒ Object

Examples:

#median ⇒ Object

Examples:

#microsecond ⇒ Series

Examples:

#millisecond ⇒ Series

Examples:

#min ⇒ Object

Examples:

#minute ⇒ Series

Examples:

#month ⇒ Series

Examples:

#month_end ⇒ Series

Examples:

#month_start ⇒ Series

Examples:

#nanosecond ⇒ Series

Examples:

#offset_by(by) ⇒ Series

Examples:

#ordinal_day ⇒ Series

Examples:

#quarter ⇒ Series

Examples:

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

Examples:

Timestamps have not changed after convert_time_zone

Timestamps have changed after replace_time_zone

#round(every) ⇒ Series

Examples:

#second(fractional: false) ⇒ Series

Examples:

#strftime(fmt) ⇒ Series

Examples:

#timestamp(time_unit = "us") ⇒ Series

Examples:

#to_string(format) ⇒ Series

Examples:

#total_days ⇒ Series Also known as: days

Examples:

#total_hours ⇒ Series Also known as: hours

Examples:

#total_microseconds ⇒ Series Also known as: microseconds

Examples:

#total_milliseconds ⇒ Series Also known as: milliseconds

Examples:

#total_minutes ⇒ Series Also known as: minutes

Examples:

#total_nanoseconds ⇒ Series Also known as: nanoseconds

Examples:

#total_seconds ⇒ Series Also known as: seconds

Examples:

#truncate(every) ⇒ Series

Examples:

#[](item) ⇒ `Object`

#base_utc_offset ⇒ `Series`

#cast_time_unit(time_unit) ⇒ `Series`

#convert_time_zone(time_zone) ⇒ `Series`

#day ⇒ `Series`

#dst_offset ⇒ `Series`

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

#hour ⇒ `Series`

#iso_year ⇒ `Series`

#max ⇒ `Object`

#mean ⇒ `Object`

#median ⇒ `Object`

#microsecond ⇒ `Series`

#millisecond ⇒ `Series`

#min ⇒ `Object`

#minute ⇒ `Series`

#month ⇒ `Series`

#month_end ⇒ `Series`

#month_start ⇒ `Series`

#nanosecond ⇒ `Series`

#offset_by(by) ⇒ `Series`

#ordinal_day ⇒ `Series`

#quarter ⇒ `Series`

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

#round(every) ⇒ `Series`

#second(fractional: false) ⇒ `Series`

#strftime(fmt) ⇒ `Series`

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

#to_string(format) ⇒ `Series`

#total_days ⇒ `Series` Also known as: days

#total_hours ⇒ `Series` Also known as: hours

#total_microseconds ⇒ `Series` Also known as: microseconds

#total_milliseconds ⇒ `Series` Also known as: milliseconds

#total_minutes ⇒ `Series` Also known as: minutes

#total_nanoseconds ⇒ `Series` Also known as: nanoseconds

#total_seconds ⇒ `Series` Also known as: seconds

#truncate(every) ⇒ `Series`

#tz_localize(tz) ⇒ `Series`

#week ⇒ `Series`

#weekday ⇒ `Series`

#with_time_unit(time_unit) ⇒ `Series`

#year ⇒ `Series`