polars-df 0.13.0-aarch64-linux-musl

Sign up to get free protection for your applications and to get access to all the features.
Files changed (80) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +3 -0
  3. data/CHANGELOG.md +208 -0
  4. data/Cargo.lock +2556 -0
  5. data/Cargo.toml +6 -0
  6. data/LICENSE-THIRD-PARTY.txt +39059 -0
  7. data/LICENSE.txt +20 -0
  8. data/README.md +437 -0
  9. data/lib/polars/3.1/polars.so +0 -0
  10. data/lib/polars/3.2/polars.so +0 -0
  11. data/lib/polars/3.3/polars.so +0 -0
  12. data/lib/polars/array_expr.rb +537 -0
  13. data/lib/polars/array_name_space.rb +423 -0
  14. data/lib/polars/batched_csv_reader.rb +104 -0
  15. data/lib/polars/binary_expr.rb +77 -0
  16. data/lib/polars/binary_name_space.rb +66 -0
  17. data/lib/polars/cat_expr.rb +36 -0
  18. data/lib/polars/cat_name_space.rb +88 -0
  19. data/lib/polars/config.rb +530 -0
  20. data/lib/polars/convert.rb +98 -0
  21. data/lib/polars/data_frame.rb +5191 -0
  22. data/lib/polars/data_types.rb +466 -0
  23. data/lib/polars/date_time_expr.rb +1397 -0
  24. data/lib/polars/date_time_name_space.rb +1287 -0
  25. data/lib/polars/dynamic_group_by.rb +52 -0
  26. data/lib/polars/exceptions.rb +38 -0
  27. data/lib/polars/expr.rb +7256 -0
  28. data/lib/polars/expr_dispatch.rb +22 -0
  29. data/lib/polars/functions/aggregation/horizontal.rb +246 -0
  30. data/lib/polars/functions/aggregation/vertical.rb +282 -0
  31. data/lib/polars/functions/as_datatype.rb +271 -0
  32. data/lib/polars/functions/col.rb +47 -0
  33. data/lib/polars/functions/eager.rb +182 -0
  34. data/lib/polars/functions/lazy.rb +1329 -0
  35. data/lib/polars/functions/len.rb +49 -0
  36. data/lib/polars/functions/lit.rb +35 -0
  37. data/lib/polars/functions/random.rb +16 -0
  38. data/lib/polars/functions/range/date_range.rb +136 -0
  39. data/lib/polars/functions/range/datetime_range.rb +149 -0
  40. data/lib/polars/functions/range/int_range.rb +51 -0
  41. data/lib/polars/functions/range/time_range.rb +141 -0
  42. data/lib/polars/functions/repeat.rb +144 -0
  43. data/lib/polars/functions/whenthen.rb +96 -0
  44. data/lib/polars/functions.rb +57 -0
  45. data/lib/polars/group_by.rb +613 -0
  46. data/lib/polars/io/avro.rb +24 -0
  47. data/lib/polars/io/csv.rb +696 -0
  48. data/lib/polars/io/database.rb +73 -0
  49. data/lib/polars/io/ipc.rb +275 -0
  50. data/lib/polars/io/json.rb +29 -0
  51. data/lib/polars/io/ndjson.rb +80 -0
  52. data/lib/polars/io/parquet.rb +233 -0
  53. data/lib/polars/lazy_frame.rb +2708 -0
  54. data/lib/polars/lazy_group_by.rb +181 -0
  55. data/lib/polars/list_expr.rb +791 -0
  56. data/lib/polars/list_name_space.rb +449 -0
  57. data/lib/polars/meta_expr.rb +222 -0
  58. data/lib/polars/name_expr.rb +198 -0
  59. data/lib/polars/plot.rb +109 -0
  60. data/lib/polars/rolling_group_by.rb +35 -0
  61. data/lib/polars/series.rb +4444 -0
  62. data/lib/polars/slice.rb +104 -0
  63. data/lib/polars/sql_context.rb +194 -0
  64. data/lib/polars/string_cache.rb +75 -0
  65. data/lib/polars/string_expr.rb +1495 -0
  66. data/lib/polars/string_name_space.rb +811 -0
  67. data/lib/polars/struct_expr.rb +98 -0
  68. data/lib/polars/struct_name_space.rb +96 -0
  69. data/lib/polars/testing.rb +507 -0
  70. data/lib/polars/utils/constants.rb +9 -0
  71. data/lib/polars/utils/convert.rb +97 -0
  72. data/lib/polars/utils/parse.rb +89 -0
  73. data/lib/polars/utils/various.rb +76 -0
  74. data/lib/polars/utils/wrap.rb +19 -0
  75. data/lib/polars/utils.rb +130 -0
  76. data/lib/polars/version.rb +4 -0
  77. data/lib/polars/whenthen.rb +83 -0
  78. data/lib/polars-df.rb +1 -0
  79. data/lib/polars.rb +91 -0
  80. metadata +138 -0
@@ -0,0 +1,1287 @@
1
+ module Polars
2
+ # Series.dt namespace.
3
+ class DateTimeNameSpace
4
+ include ExprDispatch
5
+
6
+ self._accessor = "dt"
7
+
8
+ # @private
9
+ def initialize(series)
10
+ self._s = series._s
11
+ end
12
+
13
+ # Get item.
14
+ #
15
+ # @return [Object]
16
+ def [](item)
17
+ s = Utils.wrap_s(_s)
18
+ s[item]
19
+ end
20
+
21
+ # Return minimum as Ruby object.
22
+ #
23
+ # @return [Object]
24
+ #
25
+ # @example
26
+ # s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2), Date.new(2001, 1, 3)])
27
+ # s.dt.min
28
+ # # => Mon, 01 Jan 2001
29
+ def min
30
+ Utils.wrap_s(_s).min
31
+ end
32
+
33
+ # Return maximum as Ruby object.
34
+ #
35
+ # @return [Object]
36
+ #
37
+ # @example
38
+ # s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2), Date.new(2001, 1, 3)])
39
+ # s.dt.max
40
+ # # => Wed, 03 Jan 2001
41
+ def max
42
+ Utils.wrap_s(_s).max
43
+ end
44
+
45
+ # Return median as Ruby object.
46
+ #
47
+ # @return [Object]
48
+ #
49
+ # @example
50
+ # date = Polars.datetime_range(
51
+ # DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", eager: true
52
+ # ).alias("datetime")
53
+ # # =>
54
+ # # shape: (3,)
55
+ # # Series: 'datetime' [datetime[ns]]
56
+ # # [
57
+ # # 2001-01-01 00:00:00
58
+ # # 2001-01-02 00:00:00
59
+ # # 2001-01-03 00:00:00
60
+ # # ]
61
+ #
62
+ # @example
63
+ # date.dt.median
64
+ # # => 2001-01-02 00:00:00 UTC
65
+ def median
66
+ _s.median
67
+ end
68
+
69
+ # Return mean as Ruby object.
70
+ #
71
+ # @return [Object]
72
+ #
73
+ # @example
74
+ # s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2)])
75
+ # s.dt.mean
76
+ # # => 2001-01-01 12:00:00 UTC
77
+ #
78
+ # @example
79
+ # s = Polars::Series.new(
80
+ # [DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 2), DateTime.new(2001, 1, 3)]
81
+ # )
82
+ # s.dt.mean
83
+ # # => 2001-01-02 00:00:00 UTC
84
+ def mean
85
+ _s.mean
86
+ end
87
+
88
+ # Convert a Date/Time/Datetime column into a String column with the given format.
89
+ #
90
+ # Similar to `cast(Polars::String)`, but this method allows you to customize the
91
+ # formatting of the resulting string.
92
+ #
93
+ # @param format [String]
94
+ # Format to use, refer to the `chrono strftime documentation
95
+ # <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>`_
96
+ # for specification. Example: `"%y-%m-%d"`.
97
+ #
98
+ # @return [Series]
99
+ #
100
+ # @example
101
+ # s = Polars::Series.new(
102
+ # "datetime",
103
+ # [DateTime.new(2020, 3, 1), DateTime.new(2020, 4, 1), DateTime.new(2020, 5, 1)],
104
+ # )
105
+ # s.dt.to_string("%Y/%m/%d")
106
+ # # =>
107
+ # # shape: (3,)
108
+ # # Series: 'datetime' [str]
109
+ # # [
110
+ # # "2020/03/01"
111
+ # # "2020/04/01"
112
+ # # "2020/05/01"
113
+ # # ]
114
+ def to_string(format)
115
+ super
116
+ end
117
+
118
+ # Format Date/datetime with a formatting rule.
119
+ #
120
+ # See [chrono strftime/strptime](https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html).
121
+ #
122
+ # @return [Series]
123
+ #
124
+ # @example
125
+ # s = Polars::Series.new(
126
+ # "datetime",
127
+ # [DateTime.new(2020, 3, 1), DateTime.new(2020, 4, 1), DateTime.new(2020, 5, 1)]
128
+ # )
129
+ # s.dt.strftime("%Y/%m/%d")
130
+ # # =>
131
+ # # shape: (3,)
132
+ # # Series: 'datetime' [str]
133
+ # # [
134
+ # # "2020/03/01"
135
+ # # "2020/04/01"
136
+ # # "2020/05/01"
137
+ # # ]
138
+ def strftime(fmt)
139
+ super
140
+ end
141
+
142
+ # Extract the year from the underlying date representation.
143
+ #
144
+ # Applies to Date and Datetime columns.
145
+ #
146
+ # Returns the year number in the calendar date.
147
+ #
148
+ # @return [Series]
149
+ #
150
+ # @example
151
+ # s = Polars::Series.new("date", [Date.new(2001, 1, 1), Date.new(2002, 1, 1)])
152
+ # s.dt.year
153
+ # # =>
154
+ # # shape: (2,)
155
+ # # Series: 'date' [i32]
156
+ # # [
157
+ # # 2001
158
+ # # 2002
159
+ # # ]
160
+ def year
161
+ super
162
+ end
163
+
164
+ # Extract ISO year from underlying Date representation.
165
+ #
166
+ # Applies to Date and Datetime columns.
167
+ #
168
+ # Returns the year number according to the ISO standard.
169
+ # This may not correspond with the calendar year.
170
+ #
171
+ # @return [Series]
172
+ #
173
+ # @example
174
+ # dt = DateTime.new(2022, 1, 1, 7, 8, 40)
175
+ # Polars::Series.new([dt]).dt.iso_year
176
+ # # =>
177
+ # # shape: (1,)
178
+ # # Series: '' [i32]
179
+ # # [
180
+ # # 2021
181
+ # # ]
182
+ def iso_year
183
+ super
184
+ end
185
+
186
+ # Extract quarter from underlying Date representation.
187
+ #
188
+ # Applies to Date and Datetime columns.
189
+ #
190
+ # Returns the quarter ranging from 1 to 4.
191
+ #
192
+ # @return [Series]
193
+ #
194
+ # @example
195
+ # date = Polars.date_range(
196
+ # Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
197
+ # ).alias("date")
198
+ # date.dt.quarter
199
+ # # =>
200
+ # # shape: (4,)
201
+ # # Series: 'date' [i8]
202
+ # # [
203
+ # # 1
204
+ # # 1
205
+ # # 1
206
+ # # 2
207
+ # # ]
208
+ def quarter
209
+ super
210
+ end
211
+
212
+ # Extract the month from the underlying date representation.
213
+ #
214
+ # Applies to Date and Datetime columns.
215
+ #
216
+ # Returns the month number starting from 1.
217
+ # The return value ranges from 1 to 12.
218
+ #
219
+ # @return [Series]
220
+ #
221
+ # @example
222
+ # date = Polars.date_range(
223
+ # Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
224
+ # ).alias("date")
225
+ # date.dt.month
226
+ # # =>
227
+ # # shape: (4,)
228
+ # # Series: 'date' [i8]
229
+ # # [
230
+ # # 1
231
+ # # 2
232
+ # # 3
233
+ # # 4
234
+ # # ]
235
+ def month
236
+ super
237
+ end
238
+
239
+ # Extract the week from the underlying date representation.
240
+ #
241
+ # Applies to Date and Datetime columns.
242
+ #
243
+ # Returns the ISO week number starting from 1.
244
+ # The return value ranges from 1 to 53. (The last week of year differs by years.)
245
+ #
246
+ # @return [Series]
247
+ #
248
+ # @example
249
+ # date = Polars.date_range(
250
+ # Date.new(2001, 1, 1), Date.new(2001, 4, 1), "1mo", eager: true
251
+ # ).alias("date")
252
+ # date.dt.week
253
+ # # =>
254
+ # # shape: (4,)
255
+ # # Series: 'date' [i8]
256
+ # # [
257
+ # # 1
258
+ # # 5
259
+ # # 9
260
+ # # 13
261
+ # # ]
262
+ def week
263
+ super
264
+ end
265
+
266
+ # Extract the week day from the underlying date representation.
267
+ #
268
+ # Applies to Date and Datetime columns.
269
+ #
270
+ # Returns the ISO weekday number where monday = 1 and sunday = 7
271
+ #
272
+ # @return [Series]
273
+ #
274
+ # @example
275
+ # s = Polars.date_range(Date.new(2001, 1, 1), Date.new(2001, 1, 7), eager: true).alias(
276
+ # "date"
277
+ # )
278
+ # s.dt.weekday
279
+ # # =>
280
+ # # shape: (7,)
281
+ # # Series: 'date' [i8]
282
+ # # [
283
+ # # 1
284
+ # # 2
285
+ # # 3
286
+ # # 4
287
+ # # 5
288
+ # # 6
289
+ # # 7
290
+ # # ]
291
+ def weekday
292
+ super
293
+ end
294
+
295
+ # Extract the day from the underlying date representation.
296
+ #
297
+ # Applies to Date and Datetime columns.
298
+ #
299
+ # Returns the day of month starting from 1.
300
+ # The return value ranges from 1 to 31. (The last day of month differs by months.)
301
+ #
302
+ # @return [Series]
303
+ #
304
+ # @example
305
+ # s = Polars.date_range(
306
+ # Date.new(2001, 1, 1), Date.new(2001, 1, 9), "2d", eager: true
307
+ # ).alias("date")
308
+ # s.dt.day
309
+ # # =>
310
+ # # shape: (5,)
311
+ # # Series: 'date' [i8]
312
+ # # [
313
+ # # 1
314
+ # # 3
315
+ # # 5
316
+ # # 7
317
+ # # 9
318
+ # # ]
319
+ def day
320
+ super
321
+ end
322
+
323
+ # Extract ordinal day from underlying date representation.
324
+ #
325
+ # Applies to Date and Datetime columns.
326
+ #
327
+ # Returns the day of year starting from 1.
328
+ # The return value ranges from 1 to 366. (The last day of year differs by years.)
329
+ #
330
+ # @return [Series]
331
+ #
332
+ # @example
333
+ # s = Polars.date_range(
334
+ # Date.new(2001, 1, 1), Date.new(2001, 3, 1), "1mo", eager: true
335
+ # ).alias("date")
336
+ # s.dt.ordinal_day
337
+ # # =>
338
+ # # shape: (3,)
339
+ # # Series: 'date' [i16]
340
+ # # [
341
+ # # 1
342
+ # # 32
343
+ # # 60
344
+ # # ]
345
+ def ordinal_day
346
+ super
347
+ end
348
+
349
+ # Extract the hour from the underlying DateTime representation.
350
+ #
351
+ # Applies to Datetime columns.
352
+ #
353
+ # Returns the hour number from 0 to 23.
354
+ #
355
+ # @return [Series]
356
+ #
357
+ # @example
358
+ # start = DateTime.new(2001, 1, 1)
359
+ # stop = DateTime.new(2001, 1, 1, 3)
360
+ # date = Polars.datetime_range(start, stop, "1h", eager: true).alias("datetime")
361
+ # date.dt.hour
362
+ # # =>
363
+ # # shape: (4,)
364
+ # # Series: 'datetime' [i8]
365
+ # # [
366
+ # # 0
367
+ # # 1
368
+ # # 2
369
+ # # 3
370
+ # # ]
371
+ def hour
372
+ super
373
+ end
374
+
375
+ # Extract the minutes from the underlying DateTime representation.
376
+ #
377
+ # Applies to Datetime columns.
378
+ #
379
+ # Returns the minute number from 0 to 59.
380
+ #
381
+ # @return [Series]
382
+ #
383
+ # @example
384
+ # start = DateTime.new(2001, 1, 1)
385
+ # stop = DateTime.new(2001, 1, 1, 0, 4, 0)
386
+ # date = Polars.datetime_range(start, stop, "2m", eager: true).alias("datetime")
387
+ # date.dt.minute
388
+ # # =>
389
+ # # shape: (3,)
390
+ # # Series: 'datetime' [i8]
391
+ # # [
392
+ # # 0
393
+ # # 2
394
+ # # 4
395
+ # # ]
396
+ def minute
397
+ super
398
+ end
399
+
400
+ # Extract seconds from underlying DateTime representation.
401
+ #
402
+ # Applies to Datetime columns.
403
+ #
404
+ # Returns the integer second number from 0 to 59, or a floating
405
+ # point number from 0 < 60 if `fractional: true` that includes
406
+ # any milli/micro/nanosecond component.
407
+ #
408
+ # @return [Series]
409
+ #
410
+ # @example
411
+ # start = DateTime.new(2001, 1, 1)
412
+ # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
413
+ # date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
414
+ # date.dt.second
415
+ # # =>
416
+ # # shape: (9,)
417
+ # # Series: 'datetime' [i8]
418
+ # # [
419
+ # # 0
420
+ # # 0
421
+ # # 1
422
+ # # 1
423
+ # # 2
424
+ # # 2
425
+ # # 3
426
+ # # 3
427
+ # # 4
428
+ # # ]
429
+ #
430
+ # @example
431
+ # date.dt.second(fractional: true)
432
+ # # =>
433
+ # # shape: (9,)
434
+ # # Series: 'datetime' [f64]
435
+ # # [
436
+ # # 0.0
437
+ # # 0.5
438
+ # # 1.0
439
+ # # 1.5
440
+ # # 2.0
441
+ # # 2.5
442
+ # # 3.0
443
+ # # 3.5
444
+ # # 4.0
445
+ # # ]
446
+ def second(fractional: false)
447
+ super
448
+ end
449
+
450
+ # Extract the milliseconds from the underlying DateTime representation.
451
+ #
452
+ # Applies to Datetime columns.
453
+ #
454
+ # @return [Series]
455
+ #
456
+ # @example
457
+ # start = DateTime.new(2001, 1, 1)
458
+ # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
459
+ # date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
460
+ # date.dt.millisecond
461
+ # # =>
462
+ # # shape: (9,)
463
+ # # Series: 'datetime' [i32]
464
+ # # [
465
+ # # 0
466
+ # # 500
467
+ # # 0
468
+ # # 500
469
+ # # 0
470
+ # # 500
471
+ # # 0
472
+ # # 500
473
+ # # 0
474
+ # # ]
475
+ def millisecond
476
+ super
477
+ end
478
+
479
+ # Extract the microseconds from the underlying DateTime representation.
480
+ #
481
+ # Applies to Datetime columns.
482
+ #
483
+ # @return [Series]
484
+ #
485
+ # @example
486
+ # start = DateTime.new(2001, 1, 1)
487
+ # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
488
+ # date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
489
+ # date.dt.microsecond
490
+ # # =>
491
+ # # shape: (9,)
492
+ # # Series: 'datetime' [i32]
493
+ # # [
494
+ # # 0
495
+ # # 500000
496
+ # # 0
497
+ # # 500000
498
+ # # 0
499
+ # # 500000
500
+ # # 0
501
+ # # 500000
502
+ # # 0
503
+ # # ]
504
+ def microsecond
505
+ super
506
+ end
507
+
508
+ # Extract the nanoseconds from the underlying DateTime representation.
509
+ #
510
+ # Applies to Datetime columns.
511
+ #
512
+ # @return [Series]
513
+ #
514
+ # @example
515
+ # start = DateTime.new(2001, 1, 1)
516
+ # stop = DateTime.new(2001, 1, 1, 0, 0, 4)
517
+ # date = Polars.datetime_range(start, stop, "500ms", eager: true).alias("datetime")
518
+ # date.dt.nanosecond
519
+ # # =>
520
+ # # shape: (9,)
521
+ # # Series: 'datetime' [i32]
522
+ # # [
523
+ # # 0
524
+ # # 500000000
525
+ # # 0
526
+ # # 500000000
527
+ # # 0
528
+ # # 500000000
529
+ # # 0
530
+ # # 500000000
531
+ # # 0
532
+ # # ]
533
+ def nanosecond
534
+ super
535
+ end
536
+
537
+ # Return a timestamp in the given time unit.
538
+ #
539
+ # @param time_unit ["us", "ns", "ms"]
540
+ # Time unit.
541
+ #
542
+ # @return [Series]
543
+ #
544
+ # @example
545
+ # start = DateTime.new(2001, 1, 1)
546
+ # stop = DateTime.new(2001, 1, 3)
547
+ # date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
548
+ # # =>
549
+ # # shape: (3,)
550
+ # # Series: 'datetime' [datetime[ns]]
551
+ # # [
552
+ # # 2001-01-01 00:00:00
553
+ # # 2001-01-02 00:00:00
554
+ # # 2001-01-03 00:00:00
555
+ # # ]
556
+ #
557
+ # @example
558
+ # date.dt.timestamp.alias("timestamp_us")
559
+ # # =>
560
+ # # shape: (3,)
561
+ # # Series: 'timestamp_us' [i64]
562
+ # # [
563
+ # # 978307200000000
564
+ # # 978393600000000
565
+ # # 978480000000000
566
+ # # ]
567
+ #
568
+ # @example
569
+ # date.dt.timestamp("ns").alias("timestamp_ns")
570
+ # # =>
571
+ # # shape: (3,)
572
+ # # Series: 'timestamp_ns' [i64]
573
+ # # [
574
+ # # 978307200000000000
575
+ # # 978393600000000000
576
+ # # 978480000000000000
577
+ # # ]
578
+ def timestamp(time_unit = "us")
579
+ super
580
+ end
581
+
582
+ # Get the time passed since the Unix EPOCH in the give time unit.
583
+ #
584
+ # @param time_unit ["us", "ns", "ms", "s", "d"]
585
+ # Time unit.
586
+ #
587
+ # @return [Series]
588
+ #
589
+ # @example
590
+ # start = DateTime.new(2001, 1, 1)
591
+ # stop = DateTime.new(2001, 1, 3)
592
+ # date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
593
+ # # =>
594
+ # # shape: (3,)
595
+ # # Series: 'datetime' [datetime[ns]]
596
+ # # [
597
+ # # 2001-01-01 00:00:00
598
+ # # 2001-01-02 00:00:00
599
+ # # 2001-01-03 00:00:00
600
+ # # ]
601
+ #
602
+ # @example
603
+ # date.dt.epoch.alias("epoch_ns")
604
+ # # =>
605
+ # # shape: (3,)
606
+ # # Series: 'epoch_ns' [i64]
607
+ # # [
608
+ # # 978307200000000
609
+ # # 978393600000000
610
+ # # 978480000000000
611
+ # # ]
612
+ #
613
+ # @example
614
+ # date.dt.epoch("s").alias("epoch_s")
615
+ # # =>
616
+ # # shape: (3,)
617
+ # # Series: 'epoch_s' [i64]
618
+ # # [
619
+ # # 978307200
620
+ # # 978393600
621
+ # # 978480000
622
+ # # ]
623
+ def epoch(time_unit = "us")
624
+ super
625
+ end
626
+
627
+ # Set time unit a Series of dtype Datetime or Duration.
628
+ #
629
+ # This does not modify underlying data, and should be used to fix an incorrect
630
+ # time unit.
631
+ #
632
+ # @param time_unit ["ns", "us", "ms"]
633
+ # Time unit for the `Datetime` Series.
634
+ #
635
+ # @return [Series]
636
+ #
637
+ # @example
638
+ # start = DateTime.new(2001, 1, 1)
639
+ # stop = DateTime.new(2001, 1, 3)
640
+ # date = Polars.datetime_range(start, stop, "1d", time_unit: "ns", eager: true).alias("datetime")
641
+ # # =>
642
+ # # shape: (3,)
643
+ # # Series: 'datetime' [datetime[ns]]
644
+ # # [
645
+ # # 2001-01-01 00:00:00
646
+ # # 2001-01-02 00:00:00
647
+ # # 2001-01-03 00:00:00
648
+ # # ]
649
+ #
650
+ # @example
651
+ # date.dt.with_time_unit("us").alias("tu_us")
652
+ # # =>
653
+ # # shape: (3,)
654
+ # # Series: 'tu_us' [datetime[μs]]
655
+ # # [
656
+ # # +32971-04-28 00:00:00
657
+ # # +32974-01-22 00:00:00
658
+ # # +32976-10-18 00:00:00
659
+ # # ]
660
+ def with_time_unit(time_unit)
661
+ super
662
+ end
663
+
664
+ # Cast the underlying data to another time unit. This may lose precision.
665
+ #
666
+ # @param time_unit ["ns", "us", "ms"]
667
+ # Time unit for the `Datetime` Series.
668
+ #
669
+ # @return [Series]
670
+ #
671
+ # @example
672
+ # start = DateTime.new(2001, 1, 1)
673
+ # stop = DateTime.new(2001, 1, 3)
674
+ # date = Polars.datetime_range(start, stop, "1d", eager: true).alias("datetime")
675
+ # # =>
676
+ # # shape: (3,)
677
+ # # Series: 'datetime' [datetime[ns]]
678
+ # # [
679
+ # # 2001-01-01 00:00:00
680
+ # # 2001-01-02 00:00:00
681
+ # # 2001-01-03 00:00:00
682
+ # # ]
683
+ #
684
+ # @example
685
+ # date.dt.cast_time_unit("ms").alias("tu_ms")
686
+ # # =>
687
+ # # shape: (3,)
688
+ # # Series: 'tu_ms' [datetime[ms]]
689
+ # # [
690
+ # # 2001-01-01 00:00:00
691
+ # # 2001-01-02 00:00:00
692
+ # # 2001-01-03 00:00:00
693
+ # # ]
694
+ #
695
+ # @example
696
+ # date.dt.cast_time_unit("ns").alias("tu_ns")
697
+ # # =>
698
+ # # shape: (3,)
699
+ # # Series: 'tu_ns' [datetime[ns]]
700
+ # # [
701
+ # # 2001-01-01 00:00:00
702
+ # # 2001-01-02 00:00:00
703
+ # # 2001-01-03 00:00:00
704
+ # # ]
705
+ def cast_time_unit(time_unit)
706
+ super
707
+ end
708
+
709
+ # Set time zone a Series of type Datetime.
710
+ #
711
+ # @param time_zone [String]
712
+ # Time zone for the `Datetime` Series.
713
+ #
714
+ # @return [Series]
715
+ #
716
+ # @example
717
+ # start = DateTime.new(2020, 3, 1)
718
+ # stop = DateTime.new(2020, 5, 1)
719
+ # date = Polars.datetime_range(start, stop, "1mo", time_zone: "UTC", eager: true).alias("datetime")
720
+ # # =>
721
+ # # shape: (3,)
722
+ # # Series: 'datetime' [datetime[ns, UTC]]
723
+ # # [
724
+ # # 2020-03-01 00:00:00 UTC
725
+ # # 2020-04-01 00:00:00 UTC
726
+ # # 2020-05-01 00:00:00 UTC
727
+ # # ]
728
+ #
729
+ # @example
730
+ # date.dt.convert_time_zone("Europe/London").alias("London")
731
+ # # =>
732
+ # # shape: (3,)
733
+ # # Series: 'London' [datetime[ns, Europe/London]]
734
+ # # [
735
+ # # 2020-03-01 00:00:00 GMT
736
+ # # 2020-04-01 01:00:00 BST
737
+ # # 2020-05-01 01:00:00 BST
738
+ # # ]
739
+ def convert_time_zone(time_zone)
740
+ super
741
+ end
742
+
743
+ # Cast time zone for a Series of type Datetime.
744
+ #
745
+ # Different from `with_time_zone`, this will also modify
746
+ # the underlying timestamp.
747
+ #
748
+ # @param time_zone [String]
749
+ # Time zone for the `Datetime` Series. Pass `nil` to unset time zone.
750
+ # @param ambiguous [String]
751
+ # Determine how to deal with ambiguous datetimes.
752
+ # @param non_existent [String]
753
+ # Determine how to deal with non-existent datetimes.
754
+ #
755
+ # @return [Series]
756
+ #
757
+ # @example
758
+ # start = DateTime.new(2020, 3, 1)
759
+ # stop = DateTime.new(2020, 5, 1)
760
+ # date = Polars.datetime_range(start, stop, "1mo", time_zone: "UTC", eager: true).alias("datetime")
761
+ # # =>
762
+ # # shape: (3,)
763
+ # # Series: 'datetime' [datetime[ns, UTC]]
764
+ # # [
765
+ # # 2020-03-01 00:00:00 UTC
766
+ # # 2020-04-01 00:00:00 UTC
767
+ # # 2020-05-01 00:00:00 UTC
768
+ # # ]
769
+ #
770
+ # @example
771
+ # date.dt.epoch("s")
772
+ # # =>
773
+ # # shape: (3,)
774
+ # # Series: 'datetime' [i64]
775
+ # # [
776
+ # # 1583020800
777
+ # # 1585699200
778
+ # # 1588291200
779
+ # # ]
780
+ #
781
+ # @example
782
+ # date = date.dt.convert_time_zone("Europe/London").alias("London")
783
+ # # =>
784
+ # # shape: (3,)
785
+ # # Series: 'London' [datetime[ns, Europe/London]]
786
+ # # [
787
+ # # 2020-03-01 00:00:00 GMT
788
+ # # 2020-04-01 01:00:00 BST
789
+ # # 2020-05-01 01:00:00 BST
790
+ # # ]
791
+ #
792
+ # @example Timestamps have not changed after convert_time_zone
793
+ # date.dt.epoch("s")
794
+ # # =>
795
+ # # shape: (3,)
796
+ # # Series: 'London' [i64]
797
+ # # [
798
+ # # 1583020800
799
+ # # 1585699200
800
+ # # 1588291200
801
+ # # ]
802
+ #
803
+ # @example
804
+ # date = date.dt.replace_time_zone("America/New_York").alias("NYC")
805
+ # # =>
806
+ # # shape: (3,)
807
+ # # Series: 'NYC' [datetime[ns, America/New_York]]
808
+ # # [
809
+ # # 2020-03-01 00:00:00 EST
810
+ # # 2020-04-01 01:00:00 EDT
811
+ # # 2020-05-01 01:00:00 EDT
812
+ # # ]
813
+ #
814
+ # @example Timestamps have changed after replace_time_zone
815
+ # date.dt.epoch("s")
816
+ # # =>
817
+ # # shape: (3,)
818
+ # # Series: 'NYC' [i64]
819
+ # # [
820
+ # # 1583038800
821
+ # # 1585717200
822
+ # # 1588309200
823
+ # # ]
824
+ def replace_time_zone(time_zone, ambiguous: "raise", non_existent: "raise")
825
+ super
826
+ end
827
+
828
+ # Localize tz-naive Datetime Series to tz-aware Datetime Series.
829
+ #
830
+ # This method takes a naive Datetime Series and makes this time zone aware.
831
+ # It does not move the time to another time zone.
832
+ #
833
+ # @param tz [String]
834
+ # Time zone for the `Datetime` Series.
835
+ #
836
+ # @return [Series]
837
+ def tz_localize(tz)
838
+ super
839
+ end
840
+
841
+ # Extract the days from a Duration type.
842
+ #
843
+ # @return [Series]
844
+ #
845
+ # @example
846
+ # date = Polars.datetime_range(
847
+ # Time.utc(2020, 3, 1), Time.utc(2020, 5, 1), "1mo", eager: true
848
+ # ).alias("datetime")
849
+ # date.diff.dt.total_days
850
+ # # =>
851
+ # # shape: (3,)
852
+ # # Series: 'datetime' [i64]
853
+ # # [
854
+ # # null
855
+ # # 31
856
+ # # 30
857
+ # # ]
858
+ def total_days
859
+ super
860
+ end
861
+ alias_method :days, :total_days
862
+
863
+ # Extract the hours from a Duration type.
864
+ #
865
+ # @return [Series]
866
+ #
867
+ # @example
868
+ # date = Polars.datetime_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", time_unit: "us", eager: true).alias("datetime")
869
+ # # =>
870
+ # # shape: (4,)
871
+ # # Series: 'datetime' [datetime[μs]]
872
+ # # [
873
+ # # 2020-01-01 00:00:00
874
+ # # 2020-01-02 00:00:00
875
+ # # 2020-01-03 00:00:00
876
+ # # 2020-01-04 00:00:00
877
+ # # ]
878
+ #
879
+ # @example
880
+ # date.diff.dt.total_hours
881
+ # # =>
882
+ # # shape: (4,)
883
+ # # Series: 'datetime' [i64]
884
+ # # [
885
+ # # null
886
+ # # 24
887
+ # # 24
888
+ # # 24
889
+ # # ]
890
+ def total_hours
891
+ super
892
+ end
893
+ alias_method :hours, :total_hours
894
+
895
+ # Extract the minutes from a Duration type.
896
+ #
897
+ # @return [Series]
898
+ #
899
+ # @example
900
+ # date = Polars.datetime_range(DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 4), "1d", time_unit: "us", eager: true).alias("datetime")
901
+ # # =>
902
+ # # shape: (4,)
903
+ # # Series: 'datetime' [datetime[μs]]
904
+ # # [
905
+ # # 2020-01-01 00:00:00
906
+ # # 2020-01-02 00:00:00
907
+ # # 2020-01-03 00:00:00
908
+ # # 2020-01-04 00:00:00
909
+ # # ]
910
+ #
911
+ # @example
912
+ # date.diff.dt.total_minutes
913
+ # # =>
914
+ # # shape: (4,)
915
+ # # Series: 'datetime' [i64]
916
+ # # [
917
+ # # null
918
+ # # 1440
919
+ # # 1440
920
+ # # 1440
921
+ # # ]
922
+ def total_minutes
923
+ super
924
+ end
925
+ alias_method :minutes, :total_minutes
926
+
927
+ # Extract the seconds from a Duration type.
928
+ #
929
+ # @return [Series]
930
+ #
931
+ # @example
932
+ # date = Polars.datetime_range(
933
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 4, 0), "1m", time_unit: "us", eager: true
934
+ # ).alias("datetime")
935
+ # # =>
936
+ # # shape: (5,)
937
+ # # Series: 'datetime' [datetime[μs]]
938
+ # # [
939
+ # # 2020-01-01 00:00:00
940
+ # # 2020-01-01 00:01:00
941
+ # # 2020-01-01 00:02:00
942
+ # # 2020-01-01 00:03:00
943
+ # # 2020-01-01 00:04:00
944
+ # # ]
945
+ #
946
+ # @example
947
+ # date.diff.dt.total_seconds
948
+ # # =>
949
+ # # shape: (5,)
950
+ # # Series: 'datetime' [i64]
951
+ # # [
952
+ # # null
953
+ # # 60
954
+ # # 60
955
+ # # 60
956
+ # # 60
957
+ # # ]
958
+ def total_seconds
959
+ super
960
+ end
961
+ alias_method :seconds, :total_seconds
962
+
963
+ # Extract the milliseconds from a Duration type.
964
+ #
965
+ # @return [Series]
966
+ #
967
+ # @example
968
+ # date = Polars.datetime_range(
969
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
970
+ # ).alias("datetime")[0..2]
971
+ # # =>
972
+ # # shape: (3,)
973
+ # # Series: 'datetime' [datetime[μs]]
974
+ # # [
975
+ # # 2020-01-01 00:00:00
976
+ # # 2020-01-01 00:00:00.001
977
+ # # 2020-01-01 00:00:00.002
978
+ # # ]
979
+ #
980
+ # @example
981
+ # date.diff.dt.total_milliseconds
982
+ # # =>
983
+ # # shape: (3,)
984
+ # # Series: 'datetime' [i64]
985
+ # # [
986
+ # # null
987
+ # # 1
988
+ # # 1
989
+ # # ]
990
+ def total_milliseconds
991
+ super
992
+ end
993
+ alias_method :milliseconds, :total_milliseconds
994
+
995
+ # Extract the microseconds from a Duration type.
996
+ #
997
+ # @return [Series]
998
+ #
999
+ # @example
1000
+ # date = Polars.datetime_range(
1001
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
1002
+ # ).alias("datetime")[0..2]
1003
+ # # =>
1004
+ # # shape: (3,)
1005
+ # # Series: 'datetime' [datetime[μs]]
1006
+ # # [
1007
+ # # 2020-01-01 00:00:00
1008
+ # # 2020-01-01 00:00:00.001
1009
+ # # 2020-01-01 00:00:00.002
1010
+ # # ]
1011
+ #
1012
+ # @example
1013
+ # date.diff.dt.total_microseconds
1014
+ # # =>
1015
+ # # shape: (3,)
1016
+ # # Series: 'datetime' [i64]
1017
+ # # [
1018
+ # # null
1019
+ # # 1000
1020
+ # # 1000
1021
+ # # ]
1022
+ def total_microseconds
1023
+ super
1024
+ end
1025
+ alias_method :microseconds, :total_microseconds
1026
+
1027
+ # Extract the nanoseconds from a Duration type.
1028
+ #
1029
+ # @return [Series]
1030
+ #
1031
+ # @example
1032
+ # date = Polars.datetime_range(
1033
+ # DateTime.new(2020, 1, 1), DateTime.new(2020, 1, 1, 0, 0, 1, 0), "1ms", time_unit: "us", eager: true
1034
+ # ).alias("datetime")[0..2]
1035
+ # # =>
1036
+ # # shape: (3,)
1037
+ # # Series: 'datetime' [datetime[μs]]
1038
+ # # [
1039
+ # # 2020-01-01 00:00:00
1040
+ # # 2020-01-01 00:00:00.001
1041
+ # # 2020-01-01 00:00:00.002
1042
+ # # ]
1043
+ #
1044
+ # @example
1045
+ # date.diff.dt.total_nanoseconds
1046
+ # # =>
1047
+ # # shape: (3,)
1048
+ # # Series: 'datetime' [i64]
1049
+ # # [
1050
+ # # null
1051
+ # # 1000000
1052
+ # # 1000000
1053
+ # # ]
1054
+ def total_nanoseconds
1055
+ super
1056
+ end
1057
+ alias_method :nanoseconds, :total_nanoseconds
1058
+
1059
+ # Offset this date by a relative time offset.
1060
+ #
1061
+ # This differs from `Polars.col("foo") + timedelta` in that it can
1062
+ # take months and leap years into account. Note that only a single minus
1063
+ # sign is allowed in the `by` string, as the first character.
1064
+ #
1065
+ # @param by [String]
1066
+ # The offset is dictated by the following string language:
1067
+ #
1068
+ # - 1ns (1 nanosecond)
1069
+ # - 1us (1 microsecond)
1070
+ # - 1ms (1 millisecond)
1071
+ # - 1s (1 second)
1072
+ # - 1m (1 minute)
1073
+ # - 1h (1 hour)
1074
+ # - 1d (1 day)
1075
+ # - 1w (1 week)
1076
+ # - 1mo (1 calendar month)
1077
+ # - 1y (1 calendar year)
1078
+ # - 1i (1 index count)
1079
+ #
1080
+ # @return [Series]
1081
+ #
1082
+ # @example
1083
+ # dates = Polars.datetime_range(
1084
+ # DateTime.new(2000, 1, 1), DateTime.new(2005, 1, 1), "1y", eager: true
1085
+ # ).alias("datetime")
1086
+ # # =>
1087
+ # # shape: (6,)
1088
+ # # Series: 'datetime' [datetime[ns]]
1089
+ # # [
1090
+ # # 2000-01-01 00:00:00
1091
+ # # 2001-01-01 00:00:00
1092
+ # # 2002-01-01 00:00:00
1093
+ # # 2003-01-01 00:00:00
1094
+ # # 2004-01-01 00:00:00
1095
+ # # 2005-01-01 00:00:00
1096
+ # # ]
1097
+ #
1098
+ # @example
1099
+ # dates.dt.offset_by("1y").alias("date_plus_1y")
1100
+ # # =>
1101
+ # # shape: (6,)
1102
+ # # Series: 'date_plus_1y' [datetime[ns]]
1103
+ # # [
1104
+ # # 2001-01-01 00:00:00
1105
+ # # 2002-01-01 00:00:00
1106
+ # # 2003-01-01 00:00:00
1107
+ # # 2004-01-01 00:00:00
1108
+ # # 2005-01-01 00:00:00
1109
+ # # 2006-01-01 00:00:00
1110
+ # # ]
1111
+ #
1112
+ # @example
1113
+ # dates.dt.offset_by("-1y2mo").alias("date_minus_1y_2mon")
1114
+ # # =>
1115
+ # # shape: (6,)
1116
+ # # Series: 'date_minus_1y_2mon' [datetime[ns]]
1117
+ # # [
1118
+ # # 1998-11-01 00:00:00
1119
+ # # 1999-11-01 00:00:00
1120
+ # # 2000-11-01 00:00:00
1121
+ # # 2001-11-01 00:00:00
1122
+ # # 2002-11-01 00:00:00
1123
+ # # 2003-11-01 00:00:00
1124
+ # # ]
1125
+ def offset_by(by)
1126
+ super
1127
+ end
1128
+
1129
+ # Divide the date/ datetime range into buckets.
1130
+ #
1131
+ # Each date/datetime is mapped to the start of its bucket.
1132
+ #
1133
+ # The `every` and `offset` argument are created with the
1134
+ # the following string language:
1135
+ #
1136
+ # 1ns # 1 nanosecond
1137
+ # 1us # 1 microsecond
1138
+ # 1ms # 1 millisecond
1139
+ # 1s # 1 second
1140
+ # 1m # 1 minute
1141
+ # 1h # 1 hour
1142
+ # 1d # 1 day
1143
+ # 1w # 1 week
1144
+ # 1mo # 1 calendar month
1145
+ # 1y # 1 calendar year
1146
+ #
1147
+ # 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds
1148
+ #
1149
+ # @param every [String]
1150
+ # Every interval start and period length.
1151
+ #
1152
+ # @return [Series]
1153
+ def truncate(every)
1154
+ super
1155
+ end
1156
+
1157
+ # Divide the date/ datetime range into buckets.
1158
+ #
1159
+ # Each date/datetime in the first half of the interval
1160
+ # is mapped to the start of its bucket.
1161
+ # Each date/datetime in the seconod half of the interval
1162
+ # is mapped to the end of its bucket.
1163
+ #
1164
+ # The `every` and `offset` argument are created with the
1165
+ # the following string language:
1166
+ #
1167
+ # 1ns # 1 nanosecond
1168
+ # 1us # 1 microsecond
1169
+ # 1ms # 1 millisecond
1170
+ # 1s # 1 second
1171
+ # 1m # 1 minute
1172
+ # 1h # 1 hour
1173
+ # 1d # 1 day
1174
+ # 1w # 1 week
1175
+ # 1mo # 1 calendar month
1176
+ # 1y # 1 calendar year
1177
+ #
1178
+ # 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds
1179
+ #
1180
+ # @param every [String]
1181
+ # Every interval start and period length.
1182
+ #
1183
+ # @return [Series]
1184
+ #
1185
+ # @note
1186
+ # This functionality is currently experimental and may
1187
+ # change without it being considered a breaking change.
1188
+ def round(every)
1189
+ super
1190
+ end
1191
+
1192
+ # Roll backward to the first day of the month.
1193
+ #
1194
+ # @return [Series]
1195
+ #
1196
+ # @example
1197
+ # s = Polars.datetime_range(
1198
+ # DateTime.new(2000, 1, 2, 2), DateTime.new(2000, 4, 2, 2), "1mo", time_unit: "us", eager: true
1199
+ # ).alias("datetime")
1200
+ # s.dt.month_start
1201
+ # # =>
1202
+ # # shape: (4,)
1203
+ # # Series: 'datetime' [datetime[μs]]
1204
+ # # [
1205
+ # # 2000-01-01 02:00:00
1206
+ # # 2000-02-01 02:00:00
1207
+ # # 2000-03-01 02:00:00
1208
+ # # 2000-04-01 02:00:00
1209
+ # # ]
1210
+ def month_start
1211
+ super
1212
+ end
1213
+
1214
+ # Roll forward to the last day of the month.
1215
+ #
1216
+ # @return [Series]
1217
+ #
1218
+ # @example
1219
+ # s = Polars.datetime_range(
1220
+ # DateTime.new(2000, 1, 2, 2), DateTime.new(2000, 4, 2, 2), "1mo", time_unit: "us", eager: true
1221
+ # ).alias("datetime")
1222
+ # s.dt.month_end
1223
+ # # =>
1224
+ # # shape: (4,)
1225
+ # # Series: 'datetime' [datetime[μs]]
1226
+ # # [
1227
+ # # 2000-01-31 02:00:00
1228
+ # # 2000-02-29 02:00:00
1229
+ # # 2000-03-31 02:00:00
1230
+ # # 2000-04-30 02:00:00
1231
+ # # ]
1232
+ def month_end
1233
+ super
1234
+ end
1235
+
1236
+ # Base offset from UTC.
1237
+ #
1238
+ # This is usually constant for all datetimes in a given time zone, but
1239
+ # may vary in the rare case that a country switches time zone, like
1240
+ # Samoa (Apia) did at the end of 2011.
1241
+ #
1242
+ # @return [Series]
1243
+ #
1244
+ # @example
1245
+ # s = Polars.datetime_range(
1246
+ # DateTime.new(2011, 12, 29),
1247
+ # DateTime.new(2012, 1, 1),
1248
+ # "2d",
1249
+ # time_zone: "Pacific/Apia",
1250
+ # eager: true,
1251
+ # ).alias("datetime")
1252
+ # s.dt.base_utc_offset
1253
+ # # =>
1254
+ # # shape: (2,)
1255
+ # # Series: 'datetime' [duration[ms]]
1256
+ # # [
1257
+ # # -11h
1258
+ # # 13h
1259
+ # # ]
1260
+ def base_utc_offset
1261
+ super
1262
+ end
1263
+
1264
+ # Additional offset currently in effect (typically due to daylight saving time).
1265
+ #
1266
+ # @return [Series]
1267
+ #
1268
+ # @example
1269
+ # s = Polars.datetime_range(
1270
+ # DateTime.new(2020, 10, 25),
1271
+ # DateTime.new(2020, 10, 26),
1272
+ # time_zone: "Europe/London",
1273
+ # eager: true,
1274
+ # ).alias("datetime")
1275
+ # s.dt.dst_offset
1276
+ # # =>
1277
+ # # shape: (2,)
1278
+ # # Series: 'datetime' [duration[ms]]
1279
+ # # [
1280
+ # # 1h
1281
+ # # 0ms
1282
+ # # ]
1283
+ def dst_offset
1284
+ super
1285
+ end
1286
+ end
1287
+ end