Operator tick_calendar

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features
 
+- Added `EventSet.tick_calendar()` operator.
 - Added `EventSet.where()` operator.
 - Add `filter_moving_count` operator.
 

docs/src/reference/index.md

@@ -63,6 +63,7 @@ Check the index on the left for a more detailed description of any symbol.
 | [`EventSet.set_index()`][temporian.EventSet.set_index]                                                     | Replaces the indexes in an [`EventSet`][temporian.EventSet].                                                 |
 | [`EventSet.since_last()`][temporian.EventSet.since_last]                                                   | Computes the amount of time since the last distinct timestamp.                                               |
 | [`EventSet.tick()`][temporian.EventSet.tick]                                                               | Generates timestamps at regular intervals in the range of a guide.                                           |
+| [`EventSet.tick_calendar()`][temporian.EventSet.tick]                                                      | Generates timestamps at the specified calendar date-time events.                                             |
 | [`EventSet.timestamps()`][temporian.EventSet.timestamps]                                                   | Creates a feature from the events timestamps (`float64`).                                                    |
 | [`EventSet.unique_timestamps()`][temporian.EventSet.unique_timestamps]                                     | Removes events with duplicated timestamps from an [`EventSet`][temporian.EventSet].                          |
 | [`EventSet.until_next()`][temporian.EventSet.until_next]                                                   | Duration until the next sampling event.                                                                      |

docs/src/reference/temporian/operators/tick_calendar.md

@@ -0,0 +1 @@
+::: temporian.EventSet.tick_calendar

temporian/core/event_set_ops.py

@@ -15,7 +15,7 @@
 # pylint: disable=import-outside-toplevel
 
 from __future__ import annotations
-from typing import Any, Dict, List, Optional, Union, TYPE_CHECKING
+from typing import Any, Dict, List, Literal, Optional, Union, TYPE_CHECKING
 
 from temporian.core.data.duration import Duration
 
@@ -2423,6 +2423,146 @@ def tick(
 
         return tick(self, interval=interval, align=align)
 
+    def tick_calendar(
+        self: EventSetOrNode,
+        second: Optional[Union[int, Literal["*"]]] = None,
+        minute: Optional[Union[int, Literal["*"]]] = None,
+        hour: Optional[Union[int, Literal["*"]]] = None,
+        mday: Optional[Union[int, Literal["*"]]] = None,
+        month: Optional[Union[int, Literal["*"]]] = None,
+        wday: Optional[Union[int, Literal["*"]]] = None,
+    ) -> EventSetOrNode:
+        """Generates events periodically at fixed times or dates e.g. each month.
+
+        Events are generated in the range of the input
+        [`EventSet`][temporian.EventSet] independently for each index.
+
+        The usability is inspired in the crontab format, where arguments can
+        take a value of `'*'` to tick at all values, or a fixed integer to
+        tick only at that precise value.
+
+        Non-specified values (`None`), are set to `'*'` if a finer
+        resolution argument is specified, or fixed to the first valid value if
+        a lower resolution is specified. For example, setting only
+        `tick_calendar(hour='*')`
+        is equivalent to:
+        `tick_calendar(second=0, minute=0, hour='*', mday='*', month='*')`
+        , resulting in one tick at every exact hour of every day/month/year in
+        the input guide range.
+
+        The datetime timezone is always assumed to be UTC.
+
+        Examples:
+            ```python
+            >>> # Every day (at 00:00:00) in the period (exactly one year)
+            >>> a = tp.event_set(timestamps=["2021-01-01", "2021-12-31 23:59:59"])
+            >>> b = a.tick_calendar(hour=0)
+            >>> b
+            indexes: ...
+            events:
+                (365 events):
+                    timestamps: [...]
+            ...
+
+
+            >>> # Every day at 2:30am
+            >>> b = a.tick_calendar(hour=2, minute=30)
+            >>> tp.glue(b.calendar_hour(), b.calendar_minute())
+            indexes: ...
+            events:
+                (365 events):
+                    timestamps: [...]
+                    'calendar_hour': [2 2 2 ... 2 2 2]
+                    'calendar_minute': [30 30 30 ... 30 30 30]
+            ...
+
+
+            >>> # Day 5 of every month (at 00:00)
+            >>> b = a.tick_calendar(mday=5)
+            >>> b.calendar_day_of_month()
+            indexes: ...
+            events:
+                (12 events):
+                    timestamps: [...]
+                    'calendar_day_of_month': [5 5 5 ... 5 5 5]
+            ...
+
+
+            >>> # 1st of February of every year
+            >>> a = tp.event_set(timestamps=["2020-01-01", "2021-12-31"])
+            >>> b = a.tick_calendar(month=2)
+            >>> tp.glue(b.calendar_day_of_month(), b.calendar_month())
+            indexes: ...
+            events:
+                (2 events):
+                    timestamps: [...]
+                    'calendar_day_of_month': [1 1]
+                    'calendar_month': [2 2]
+            ...
+
+            >>> # Every second in the period  (2 hours -> 7200 seconds)
+            >>> a = tp.event_set(timestamps=["2020-01-01 00:00:00",
+            ...                              "2020-01-01 01:59:59"])
+            >>> b = a.tick_calendar(second='*')
+            >>> b
+            indexes: ...
+            events:
+                (7200 events):
+                    timestamps: [...]
+            ...
+
+            >>> # Every second of the minute 30 of every hour (00:30 and 01:30)
+            >>> a = tp.event_set(timestamps=["2020-01-01 00:00",
+            ...                              "2020-01-01 02:00"])
+            >>> b = a.tick_calendar(second='*', minute=30)
+            >>> b
+            indexes: ...
+            events:
+                (120 events):
+                    timestamps: [...]
+            ...
+
+            >>> # Not allowed: intermediate arguments (minute, hour) not specified
+            >>> b = a.tick_calendar(second=1, mday=1)  # ambiguous meaning
+            Traceback (most recent call last):
+                ...
+            ValueError: Can't set argument to None because previous and
+            following arguments were specified. Set to '*' or an integer ...
+
+            ```
+
+        Args:
+            second: '*' (any second), None (auto) or number in range `[0-59]`
+                    to tick at specific second of each minute.
+            minute: '*' (any minute), None (auto) or number in range `[0-59]`
+                    to tick at specific minute of each hour.
+            hour: '*' (any hour), None (auto), or number in range `[0-23]` to
+                    tick at specific hour of each day.
+            mday: '*' (any day), None (auto) or number in range `[1-31]`
+                        to tick at specific day of each month. Note that months
+                        without some particular day may not have any tick
+                        (e.g: day 31 on February).
+            month: '*' (any month), None (auto) or number in range `[1-12]` to
+                    tick at one particular month of each year.
+            wday: '*' (any day), None (auto) or number in range `[0-6]`
+                    (Sun-Sat) to tick at particular day of week. Can only be
+                    specified if `day_of_month` is `None`.
+
+        Returns:
+            A feature-less EventSet with timestamps at specified interval.
+        """
+        from temporian.core.operators.tick_calendar import tick_calendar
+
+        return tick_calendar(
+            self,
+            second=second,
+            minute=minute,
+            hour=hour,
+            mday=mday,
+            month=month,
+            wday=wday,
+        )
+
     def timestamps(self: EventSetOrNode) -> EventSetOrNode:
         """Converts an [`EventSet`][temporian.EventSet]'s timestamps into a
         `float64` feature.

temporian/core/operators/BUILD

@@ -362,6 +362,22 @@ py_library(
     ],
 )
 
+py_library(
+    name = "tick_calendar",
+    srcs = ["tick_calendar.py"],
+    srcs_version = "PY3",
+    deps = [
+        ":base",
+        "//temporian/core:compilation",
+        "//temporian/core:operator_lib",
+        "//temporian/core:typing",
+        "//temporian/core/data:dtype",
+        "//temporian/core/data:node",
+        "//temporian/proto:core_py_proto",
+        "//temporian/utils:typecheck",
+    ],
+)
+
 py_library(
     name = "select_index_values",
     srcs = ["select_index_values.py"],

temporian/core/operators/test/BUILD

@@ -53,3 +53,15 @@ py_test(
         "//temporian/core/operators:until_next",
     ],
 )
+
+py_test(
+    name = "tick_calendar_test",
+    srcs = ["tick_calendar_test.py"],
+    srcs_version = "PY3",
+    deps = [
+        # already_there/absl/testing:absltest
+        "//temporian/core/data:dtype",
+        "//temporian/core/data:node",
+        "//temporian/core/operators:tick_calendar",
+    ],
+)

temporian/core/operators/test/tick_calendar_test.py

@@ -0,0 +1,154 @@
+# Copyright 2021 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from absl.testing import absltest
+
+from temporian.core.data.node import input_node
+from temporian.core.operators.tick_calendar import tick_calendar, TickCalendar
+
+
+class TickCalendarOperatorTest(absltest.TestCase):
+    def setUp(self):
+        self._in = input_node([], is_unix_timestamp=True)
+
+    def test_free_seconds_month(self):
+        output = tick_calendar(self._in, second="*", minute=1, hour=1, mday=31)
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, "*")
+        self.assertEqual(op.minute, 1)
+        self.assertEqual(op.hour, 1)
+        self.assertEqual(op.mday, 31)
+        self.assertEqual(op.month, "*")
+        self.assertEqual(op.wday, "*")
+
+    def test_free_minutes(self):
+        output = tick_calendar(self._in, minute="*")
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, "*")
+        self.assertEqual(op.hour, "*")
+        self.assertEqual(op.mday, "*")
+        self.assertEqual(op.month, "*")
+        self.assertEqual(op.wday, "*")
+
+    def test_month_day(self):
+        output = tick_calendar(self._in, mday=5)
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, 0)
+        self.assertEqual(op.hour, 0)
+        self.assertEqual(op.mday, 5)
+        self.assertEqual(op.month, "*")
+        self.assertEqual(op.wday, "*")
+
+    def test_month(self):
+        output = tick_calendar(self._in, month=8)
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, 0)
+        self.assertEqual(op.hour, 0)
+        self.assertEqual(op.mday, 1)
+        self.assertEqual(op.month, 8)
+        self.assertEqual(op.wday, "*")
+
+    def test_weekdays(self):
+        output = tick_calendar(self._in, wday=6)
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, 0)
+        self.assertEqual(op.hour, 0)
+        self.assertEqual(op.mday, "*")
+        self.assertEqual(op.month, "*")
+        self.assertEqual(op.wday, 6)
+
+    def test_weekdays_month(self):
+        output = tick_calendar(self._in, wday=6, month=3)
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, 0)
+        self.assertEqual(op.hour, 0)
+        self.assertEqual(op.mday, "*")
+        self.assertEqual(op.month, 3)
+        self.assertEqual(op.wday, 6)
+
+    def test_weekdays_all_hours(self):
+        output = tick_calendar(self._in, wday=6, hour="*")
+        op = output.creator
+        assert isinstance(op, TickCalendar)
+        self.assertEqual(op.second, 0)
+        self.assertEqual(op.minute, 0)
+        self.assertEqual(op.hour, "*")
+        self.assertEqual(op.mday, "*")
+        self.assertEqual(op.month, "*")
+        self.assertEqual(op.wday, 6)
+
+    def test_invalid_ranges(self):
+        for kwargs in (
+            {"second": -1},
+            {"second": 60},
+            {"minute": -1},
+            {"minute": 60},
+            {"hour": -1},
+            {"hour": 24},
+            {"mday": 0},
+            {"mday": 32},
+            {"mday": -1},  # may be supported in the future
+            {"month": -1},
+            {"month": 13},
+            {"wday": -1},
+            {"wday": 7},
+        ):
+            with self.assertRaisesRegex(
+                ValueError, "Value should be '\*' or integer in range"
+            ):
+                _ = tick_calendar(self._in, **kwargs)  # type: ignore
+
+    def test_invalid_types(self):
+        for kwargs in (
+            {"second": "1"},
+            {"minute": "00"},
+            {"hour": "00:00"},
+            {"month": "January"},
+            {"wday": "Sat"},
+        ):
+            with self.assertRaisesRegex(ValueError, "Non matching type"):
+                _ = tick_calendar(self._in, **kwargs)  # type: ignore
+
+    def test_undefined_args(self):
+        with self.assertRaisesRegex(
+            ValueError,
+            "Can't set argument to None because previous and following",
+        ):
+            _ = tick_calendar(self._in, second=1, hour=1)  # undefined min
+
+        with self.assertRaisesRegex(
+            ValueError,
+            "Can't set argument to None because previous and following",
+        ):
+            _ = tick_calendar(self._in, second=1, month=1)
+
+        with self.assertRaisesRegex(
+            ValueError,
+            "Can't set argument to None because previous and following",
+        ):
+            _ = tick_calendar(self._in, hour=0, month=1)
+
+
+if __name__ == "__main__":
+    absltest.main()