geossm.data_preparation.check_regular_timestamps

geossm.data_preparation.check_regular_timestamps(timestamps)[source]

Check whether a collection of timestamps is regularly spaced.

The unique timestamps are sorted and the gaps between consecutive values are compared. A single fixed gap (in seconds down to microseconds, or in whole days) is reported as a (delta, unit) pair; failing that, a calendar-aware frequency (month or year, which do not have a constant number of seconds) is tried via pandas.infer_freq().

Parameters:

timestamps (array-like) – Sequence of timestamp-like values (e.g. strings, datetime objects, or a pandas.Series/column) to check. Values are parsed with pandas.to_datetime().

Returns:

  • is_regular (bool) – True if the (unique) timestamps are evenly spaced, False if parsing failed or the spacing is irregular.

  • delta (int, float or None) – The size of the regular step, in the unit given by unit. 0 if there is only one unique timestamp, None if is_regular is False.

  • unit (str or None) – One of "None" (single timestamp), "month", "year", "day", "hour", "minute", "second", "millisecond" or "microsecond". None if is_regular is False.

Notes

  • Uses UNIQUE timestamps (important for panel data with repeated times per geometry).

  • Handles parsing errors robustly: unparsable values make the function return (False, None, None) rather than raising.

  • Supports fixed deltas (sec/min/hour/day) and calendar frequencies (month/year) when inferable.