`ssb_timeseries.dates`¶

Helper module for date and time utility functions.

Notable examples include converting between UTC and local time, standardised string formats for file names, and (planned for future use) intervals.

date_cet(some_date, **kwargs)¶

Convert date to time_zone Europe/Oslo which provides automatic shifts between CET and CEST.

The output can be rounded to the precision specified by kwarg ‘rounding’. Default precision ‘minute’ will be used if none is provided.

Return type:: datetime
Parameters:: some_date (datetime | str)

date_local(some_date, **kwargs)¶

Convert date to default timezone.

If not configured otherwise the default is Europe/Oslo which provides automatic shifts between CET and CEST. The output can be rounded to the precision specified by kwarg ‘rounding’. Default precision ‘minute’ will be used if none is provided.

Return type:: datetime
Parameters:: some_date (datetime | str)

date_round(d, **kwargs)¶

Round date to specified by kwarg ‘rounding’ or default precision MAX_TIME_PRECISION.

Rounding can take the values ‘none’, ‘day’, ‘d’, ‘hour’, ‘h’, ‘minute’, ‘min’, ‘m’, ‘second’, ‘sec’, or ‘s’.

Default precision ‘minute’ is used if none is provided.

Return type:: datetime
Parameters:: d (datetime)

date_utc(some_date, **kwargs)¶

Convert datetime or date string to UTC.

If date has no timezone information, the data is assumed to be in default timezone (CET).

The output will be rounded to the precision specified by kwarg ‘rounding’. Max precision ‘second’ will be used if none is provided.

Return type:: datetime
Parameters:: some_date (datetime | str | None)

datelike_convert_timezone(df, target_tz='', unlocalized_tz='')¶

Convert all datelike columns of a dataframe to target timezone.

Ensures all datetime columns of a dataframe are timezone aware in the manner of datetime_localize: Columns without timezone information are first localized using the ‘unlocalized_tz’ parameter if it is provided, otherwise the localization will fall back to default.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
target_tz (ZoneInfo | str | None)
unlocalized_tz (ZoneInfo | str | None)

datelike_localize(df, target_tz='')¶

Convert all datelike columns of a dataframe to timezone aware Narwhals Datetime.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
target_tz (ZoneInfo | str | None)

Equivalent to

>>> # xdoctest: +SETUP
>>> import pandas as pd
>>> from ssb_timeseries.dates import datelike_to_datetime
>>> # ------------------------------------------------------------

>>> df = pd.DataFrame({'time': ['2022-01-01','2022-01-01','2022-01-01','2022-01-01']})
>>> datetime_localize(datelike_to_datetime(df))

datelike_to_datetime(df)¶

Convert all datelike columns of a dataframe to Narwhals Datetime.

Any timezone information (or lack there of) is passed through without explicit transformation. Note that this does not guarantee time zone information is completely untouched. Implicit localizations (typically to UTC) may still be triggered by Narwhals type transitions for some backends.

Return type:: TypeVar(IntoFrameT, bound= IntoFrame)
Parameters:: df (IntoFrameT)

datelike_to_utc(df, unlocalized_tz='')¶

Convert all datelike columns of a dataframe to UTC.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
unlocalized_tz (ZoneInfo | str | None)

datetime_convert_timezone(df, target_tz='', unlocalized_tz='')¶

Convert all datetime columns of a dataframe to target timezone.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
target_tz (ZoneInfo | str | None)
unlocalized_tz (ZoneInfo | str | None)

datetime_localize(df, target_tz='')¶

Ensure all datetime columns of a dataframe are timezone aware.

Columns without timezone information are localized using ‘target_tz’ parameter if provided, otherwise falling back to default.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
target_tz (ZoneInfo | str | None)

If the dataframe contains datelike columns of types other than Datetime, ie. Date, Object or string representations, see the twin function ‘datelike_localize()’

>>> # xdoctest: +SETUP
>>> import pandas as pd
>>> from ssb_timeseries.dates import datelike_to_datetime
>>> # ------------------------------------------------------------

>>> df = pd.DataFrame({'time': [
...     '2022-01-01 11:30',
...     '2022-01-01 12:00',
...     '2022-01-01 12:30,
...     '2022-01-01 13:00'
]})
>>> datetime_localize(datelike_to_datetime(df))

datetime_time_unit(df, time_unit='ns')¶

Ensure all datetime columns of a dataframe use the same time unit.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
time_unit (str)

datetime_to_utc(df, unlocalized_tz='')¶

Convert datetime columns of a dataframe to UTC.

If dates have no timezone information, the data is assumed to be in the default timezone (CET if not configured otherwise).

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
unlocalized_tz (ZoneInfo | str | None)

ensure_datetime(some_date_representation, **kwargs)¶

Make sure that we are dealing with a datetime object, convert if possible.

If input is None or empty strings will be converted to now_utc().

Return type:: datetime
Parameters:: some_date_representation (Any)

ensure_tz_aware(some_date)¶

Make sure that our datetime object is timezone aware.

Assume CET if timezone information is missing.

Return type:: datetime
Parameters:: some_date (datetime)

is_tz_aware(d)¶

Return type:: bool
Parameters:: d (datetime)

is_tz_naive(d)¶

Return type:: bool
Parameters:: d (datetime)

local_timezone()¶

Return the local timezone of the computer.

Return type:: ZoneInfo

now_cet(**kwargs)¶

Return now in CET.

Return type:: datetime

now_utc(**kwargs)¶

Return now in UTC.

Return type:: datetime

period_index(col, freq)¶

Returns a period index for a date or datetime series.

Return type:

PeriodIndex

Parameters:

col (IntoSeriesT)
freq (str)

prepend_as_of(df, as_of)¶

Prepend column ‘as_of’ to dataframe.

Return type:

TypeVar(IntoFrameT, bound= IntoFrame)

Parameters:

df (IntoFrameT)
as_of (datetime)

standardize_dates(df, as_of=None, time_unit='ns')¶

Ensure that all date columns conform to the same standards. :rtype: TypeVar(IntoFrameT, bound= IntoFrame)

Same datatype –> nw.dt.Timestamp?
Time zone aware + UTC for storage.
Configurable max precision?

Other questions/ideas include: * Pandas Period indexes are nice -> consider conversions? * Pendulum or other libraries?

Parameters:

df (IntoFrameT)
as_of (datetime | None)
time_unit (str)

Return type:

IntoFrameT

utc_iso(d, timespec='seconds')¶

Convert date to UTC and return as an ISO formatted string.

Return type:

str

Parameters:

d (Any)
timespec (str)

utc_iso_no_colon(d, timespec='seconds')¶

Convert date to UTC and return as an ISO formatted string without the colons.

Return type:

str

Parameters:

d (datetime)
timespec (str)

validate_dates(df, date_columns, throw_error=False)¶

Check that all expected date columns are defined, are time zone aware dates and in UTC.

Return type:

bool

Parameters:

df (IntoFrameT)
date_columns (Iterable[str])
throw_error (bool)

validate_timezone(tz='')¶

Return a valid time zone as string or ‘DEFAULT_TZ’ for the empty string or ‘None’.

Return type:: str
Parameters:: tz (ZoneInfo | str | None)

ssb_timeseries.dates¶

`ssb_timeseries.dates`¶