temporian.duration

Duration module-attribute

Duration = Union[float, int]

A duration in seconds, stored as a float64.

In Temporian, timestamps and durations are float64 values, and it is up to the user to choose the semantic of this value.

However, some functions are datetime-related (such as the functions defined in this module, calendar operators, plotting functions, and more) and assume that durations are expressed in seconds (see Time units), so it is recommended to use seconds as timestamps where possible.

shortest module-attribute

shortest = np.nextafter(0, 1)

Shortest interval between events that can be represented using float64.

This number can be used as the shortest window length to unify events with the same timestamp, ensuring that two different timestamps will never be aggregated.

days

days(value: Union[int, float]) -> Duration

Converts input value from number of days to a Duration in seconds.

Example

>>> a = tp.event_set(
...    # Dates are converted to unix timestamps
...    timestamps=["2020-01-01", "2020-01-02", "2020-01-31"],
...    features={"f1": [1, 5, -5]}
... )

>>> a.moving_sum(window_length=tp.duration.days(2))
indexes: ...
        timestamps: ['2020-01-01T00:00:00' '2020-01-02T00:00:00'
                     '2020-01-31T00:00:00']
        'f1': [ 1 6 -5]
...

Parameters:

Name	Type	Description	Default
value	Union[int, float]	number of days.	required

Returns:

Type	Description
Duration	Equivalent number of seconds.

hours

hours(value: Union[int, float]) -> Duration

Converts input value from hours to a Duration in seconds.

Example

>>> timestamps = [tp.duration.hours(i) for i in [1, 2, 10]]
>>> timestamps
[3600.0, 7200.0, 36000.0]

>>> # Usage in a window operation
>>> a = tp.event_set(timestamps=timestamps, features={"f1": [1, 5, -5]})
>>> a.moving_sum(window_length=tp.duration.hours(2))
indexes: ...
        timestamps: [ 3600. 7200. 36000.]
        'f1': [ 1 6 -5]
...

Parameters:

Name	Type	Description	Default
value	Union[int, float]	Number of hours.	required

Returns:

Type	Description
Duration	Equivalent number of seconds.

milliseconds

milliseconds(value: Union[int, float]) -> Duration

Converts input value from milliseconds to a Duration in seconds.

Example

>>> duration = tp.duration.milliseconds(250)
>>> duration
0.25

>>> # Usage in a window operation
>>> a = tp.event_set(
...     timestamps=[0.5, 1.0, 1.2],
...     features={"f1": [1, 5, -5]}
... )
>>> a.moving_sum(window_length=duration)
indexes: ...
        timestamps: [0.5 1.  1.2]
        'f1': [1 5 0]
...

Parameters:

Name	Type	Description	Default
value	Union[int, float]	Number of milliseconds.	required

Returns:

Type	Description
Duration	Equivalent number of seconds.

minutes

minutes(value: Union[int, float]) -> Duration

Converts input value from minutes to a Duration in seconds.

Example

>>> timestamps = [tp.duration.minutes(i) for i in [5, 10, 30]]
>>> timestamps
[300.0, 600.0, 1800.0]

>>> # Usage in a window operation
>>> a = tp.event_set(timestamps=timestamps, features={"f1": [1, 5, -5]})
>>> a.moving_sum(window_length=tp.duration.minutes(6))
indexes: ...
        timestamps: [ 300. 600. 1800.]
        'f1': [ 1 6 -5]
...

Parameters:

Name	Type	Description	Default
value	Union[int, float]	Number of minutes.	required

Returns:

Type	Description
Duration	Equivalent number of seconds.

seconds

seconds(value: Union[int, float]) -> Duration

Converts input value from seconds to a Duration in seconds.

Since the Duration object is equivalent to a float value in seconds, this method does nothing else than casting the input to float. It may be used in order to make the code more explicit.

Explicit time units

>>> duration = tp.duration.seconds(3)
>>> duration
3.0

>>> # Usage in a window operation
>>> a = tp.event_set(
...     timestamps=[1, 2, 6],
...     features={"f1": [1, 5, -5]},
... )
>>> a.moving_sum(window_length=duration)
indexes: ...
        timestamps: [1. 2. 6.]
        'f1': [ 1 6 -5]
...

Parameters:

Name	Type	Description	Default
value	Union[int, float]	Number of seconds.	required

Returns:

Type	Description
Duration	Same number of seconds.

to_string

to_string(
    duration: Duration,
    cutoff: Union[str, TimeUnit] = "milliseconds",
) -> str

Returns the abbreviation for a duration.

Parameters:

Name	Type	Description	Default
duration	Duration	Duration in seconds.	required
cutoff	Union[str, TimeUnit]	Cutoff for the abbreviation. For example, if cutoff is "day", the smallest unit will be days. Possible options are "week", "day", "hour" and "minute", "seconds" and "milliseconds". Default is "milliseconds".	'milliseconds'

Returns:

Type	Description
str	Abbreviation for the duration.

weeks

weeks(value: Union[int, float]) -> Duration

Converts input value from number of weeks to a Duration in seconds.

```python
>>> a = tp.event_set(
...    # Dates are converted to unix timestamps
...    timestamps=["2020-01-01", "2020-01-07", "2020-01-31"],
...    features={"f1": [1, 5, -5]}
... )

>>> a.moving_sum(window_length=tp.duration.weeks(2))
indexes: ...
        timestamps: ['2020-01-01T00:00:00' '2020-01-07T00:00:00'
                     '2020-01-31T00:00:00']
        'f1': [ 1 6 -5]
...

```

Parameters:

Name	Type	Description	Default
value	Union[int, float]	Number of weeks.	required

Returns:

Type	Description
Duration	Equivalent number of seconds.