Skip to content

time

time #

Circular time-of-day distance, where midnight is close to 11:59 PM.

TimeOfDayDistanceFunction #

Bases: DistanceFunction[datetime]

Shortest separation on the 24-hour clock, normalized by sigma.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class TimeOfDayDistanceFunction(DistanceFunction[datetime]):
    """Shortest separation on the 24-hour clock, normalized by ``sigma``."""

    def __init__(self, sigma: timedelta = timedelta(hours=1)) -> None:
        """Normalize the 24-hour clock separation by ``sigma``."""
        self.sigma_hours = sigma.total_seconds() / 3600.0

    def extract(self, values: cg.Array) -> np.ndarray:
        """Each moment's fractional hour of day, the date discarded."""
        hours = [np.nan if is_missing(value) else _hours_of_day(value) for value in values]
        return np.array(hours, dtype=np.float64).reshape(len(hours), 1)

    def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
        """The shortest separations between two sets of times of day."""
        gap = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :])
        return np.minimum(gap, 24.0 - gap) / self.sigma_hours

__init__(sigma=timedelta(hours=1)) #

Normalize the 24-hour clock separation by sigma.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
17
18
19
def __init__(self, sigma: timedelta = timedelta(hours=1)) -> None:
    """Normalize the 24-hour clock separation by ``sigma``."""
    self.sigma_hours = sigma.total_seconds() / 3600.0

extract(values) #

Each moment's fractional hour of day, the date discarded.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
21
22
23
24
def extract(self, values: cg.Array) -> np.ndarray:
    """Each moment's fractional hour of day, the date discarded."""
    hours = [np.nan if is_missing(value) else _hours_of_day(value) for value in values]
    return np.array(hours, dtype=np.float64).reshape(len(hours), 1)

pairwise(features_a, features_b) #

The shortest separations between two sets of times of day.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
26
27
28
29
def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
    """The shortest separations between two sets of times of day."""
    gap = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :])
    return np.minimum(gap, 24.0 - gap) / self.sigma_hours

time_of_day(sigma=timedelta(hours=1)) #

Create a circular time-of-day distance function.

Parameters:

Name Type Description Default
sigma timedelta

Normalization factor as a timedelta, so times within sigma apart have distance < 1.0. Default is 1 hour.

 timedelta(hours=1)

Returns:

Type Description
TimeOfDayDistanceFunction

A distance function (time_a, time_b) -> float.
Example 
import capturegraph.scheduling as cgsh
from datetime import timedelta

combined = cgsh.distance.combine(
    date=cgsh.distance.time_of_day(sigma=timedelta(hours=2)),
)
Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def time_of_day(
    sigma: timedelta = timedelta(hours=1),
) -> TimeOfDayDistanceFunction:
    """Create a circular time-of-day distance function.

    Args:
        sigma: Normalization factor as a timedelta, so times within `sigma`
            apart have distance < 1.0. Default is 1 hour.

    Returns:
        A distance function `(time_a, time_b) -> float`.

    Example:
        ```python
        import capturegraph.scheduling as cgsh
        from datetime import timedelta

        combined = cgsh.distance.combine(
            date=cgsh.distance.time_of_day(sigma=timedelta(hours=2)),
        )
        ```
    """
    return TimeOfDayDistanceFunction(sigma)