Skip to content

smart_geocubes.core.toi

Time of Interest (TOI) utilities.

Functions:

  • extract_toi_range –

    Extract the datetime range or a specific datetime from the time of interest (toi).

  • normalize_toi –

    Normalize the time of interest (toi) to the given temporal extent.

extract_toi_range 

extract_toi_range(
    toi: TOI,
) -> (
    str
    | datetime
    | tuple[str, str]
    | tuple[datetime | datetime]
    | None
)

Extract the datetime range or a specific datetime from the time of interest (toi).

Parameters:

  • toi

    (TOI) –

    The time of interest.

Returns:

Raises:

  • ValueError –

    If the time of interest is of an invalid type.

Source code in src/smart_geocubes/core/toi.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def extract_toi_range(toi: TOI) -> str | datetime | tuple[str, str] | tuple[datetime | datetime] | None:
    """Extract the datetime range or a specific datetime from the time of interest (toi).

    Args:
        toi (TOI): The time of interest.

    Returns:
        str | datetime | tuple[str, str] | tuple[datetime, datetime] | None: The extracted datetime or datetime range.

    Raises:
        ValueError: If the time of interest is of an invalid type.

    """
    if toi is None or isinstance(toi, str | datetime):
        return toi
    elif isinstance(toi, pd.Timestamp):
        return toi.to_pydatetime()
    elif isinstance(toi, slice):
        return toi.start, toi.stop
    else:
        raise ValueError(f"Cannot extract range from toi of type {type(toi)}.")

normalize_toi 

normalize_toi(
    extent: DatetimeIndex, toi: TOI, method="nearest"
) -> pd.DatetimeIndex

Normalize the time of interest (toi) to the given temporal extent.

Parameters:

  • extent

    (DatetimeIndex) –

    The temporal extent to normalize against.

  • toi

    (TOI) –

    The time of interest to normalize.

  • method

    (str, default: 'nearest' ) –

    The method to use for normalization. Defaults to "nearest". Other options are "pad", "backfill", "ffill", "bfill".

Returns:

  • DatetimeIndex –

    pd.DatetimeIndex: The normalized time of interest.

Raises:

  • ValueError –

    If the time of interest is not found in the temporal extent.

Source code in src/smart_geocubes/core/toi.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def normalize_toi(extent: pd.DatetimeIndex, toi: TOI, method="nearest") -> pd.DatetimeIndex:
    """Normalize the time of interest (toi) to the given temporal extent.

    Args:
        extent (pd.DatetimeIndex): The temporal extent to normalize against.
        toi (TOI): The time of interest to normalize.
        method (str, optional): The method to use for normalization. Defaults to "nearest".
            Other options are "pad", "backfill", "ffill", "bfill".

    Returns:
        pd.DatetimeIndex: The normalized time of interest.

    Raises:
        ValueError: If the time of interest is not found in the temporal extent.

    """
    # Normalize the extent
    extent = extent.normalize()

    if toi is None:
        return extent

    if isinstance(toi, str | datetime | pd.Timestamp):
        idxr = extent.get_indexer([toi], method=method)
    elif isinstance(toi, slice):
        idxr = extent.slice_indexer(toi.start, toi.stop)
    elif isinstance(toi, list):
        idxr = extent.get_indexer(toi, method=method)

    toi_norm = extent[idxr]
    if len(toi_norm) == 0:
        raise ValueError(f"Time {toi} not found in temporal extent.")
    return toi_norm