Skip to content

time

time #

Circular time-of-day distance between two moments.

Measures distance between times accounting for the circular nature of the 24-hour clock. Midnight is close to 11:59 PM.

TimeOfDayDistanceFunction #

Bases: BatchedDistanceFunction[datetime]

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

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class TimeOfDayDistanceFunction(BatchedDistanceFunction[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 __call__(self, a: datetime, b: datetime) -> float:
        """Shortest separation on the 24-hour clock between ``a`` and ``b``."""
        diff = abs(_hours_of_day(a) - _hours_of_day(b))
        return min(diff, 24.0 - diff) / self.sigma_hours

    def extract(self, items: cg.Array[Any]) -> np.ndarray:
        """Extract each moment's fractional hour-of-day as a single-column array."""
        return np.array(
            [_hours_of_day(moment) for moment in items],
            dtype=np.float64,
        ).reshape(-1, 1)

    def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
        """Compute pairwise circular time-of-day distances from extracted features."""
        diff = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :])
        return np.minimum(diff, 24.0 - diff) / self.sigma_hours

__call__(a, b) #

Shortest separation on the 24-hour clock between a and b.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
30
31
32
33
def __call__(self, a: datetime, b: datetime) -> float:
    """Shortest separation on the 24-hour clock between ``a`` and ``b``."""
    diff = abs(_hours_of_day(a) - _hours_of_day(b))
    return min(diff, 24.0 - diff) / 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 
26
27
28
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(items) #

Extract each moment's fractional hour-of-day as a single-column array.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
35
36
37
38
39
40
def extract(self, items: cg.Array[Any]) -> np.ndarray:
    """Extract each moment's fractional hour-of-day as a single-column array."""
    return np.array(
        [_hours_of_day(moment) for moment in items],
        dtype=np.float64,
    ).reshape(-1, 1)

pairwise(features_a, features_b) #

Compute pairwise circular time-of-day distances from extracted features.

Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
42
43
44
45
def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
    """Compute pairwise circular time-of-day distances from extracted features."""
    diff = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :])
    return np.minimum(diff, 24.0 - diff) / self.sigma_hours

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

Create a circular time-of-day distance function.

Measures the angular distance on the 24-hour clock, treating time as circular (so 11:59 PM is close to 12:01 AM).

Parameters:

Name Type Description Default
sigma timedelta

Normalization factor as timedelta. The returned distance is normalized 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 with batch support.
Example 
import capturegraph.scheduling as cgsh
from datetime import timedelta

# Sessions within 2 hours are "close"
dist_fn = cgsh.distance.time_of_day(sigma=timedelta(hours=2))

# Use with combine for custom attribute
combined = cgsh.distance.combine(
    time_of_day=cgsh.distance.time_of_day(sigma=timedelta(hours=1))
)
Source code in capturegraph-lib/capturegraph/scheduling/distance/time.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def time_of_day(
    sigma: timedelta = timedelta(hours=1),
) -> TimeOfDayDistanceFunction:
    """Create a circular time-of-day distance function.

    Measures the angular distance on the 24-hour clock, treating time
    as circular (so 11:59 PM is close to 12:01 AM).

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

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

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

        # Sessions within 2 hours are "close"
        dist_fn = cgsh.distance.time_of_day(sigma=timedelta(hours=2))

        # Use with combine for custom attribute
        combined = cgsh.distance.combine(
            time_of_day=cgsh.distance.time_of_day(sigma=timedelta(hours=1))
        )
        ```
    """
    return TimeOfDayDistanceFunction(sigma)