Datetimes

systematica.utils.datetimes

current_utc

current_utc() ‑> datetime.datetime

Current time in UTC.

Returns:

Type	Description
datetime	Current time in UTC as a datetime object.

current_utc_str

current_utc_str() ‑> str

Current time in UTC in string format.

Returns:

Type	Description
str	Current time in UTC as a string in the format %Y-%m-%dT%H:%M:%S.

to_offset

to_offset(
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta,
) ‑> pandas._libs.tslibs.offsets.BaseOffset

Convert a frequency-like object to pd.DateOffset.

Parameters:

Name	Type	Default	Description
freq	str, int, Offset, or pd.Timedelta	--	The frequency-like object to convert.

Returns:

Type	Description
Offset	The converted frequency as a pd.DateOffset.

to_timedelta

to_timedelta(
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta,
    approximate: bool = False,
) ‑> pandas._libs.tslibs.timedeltas.Timedelta

Convert a frequency-like object to a pandas Timedelta.

Parameters:

Name	Type	Default	Description
freq	str, int, Offset, pd.Timedelta	--	The frequency-like object to be converted.
approximate	bool	False	If True, approximate the frequency using _offset_to_timedelta.

Returns:

Type	Description
pd.Timedelta	The corresponding timedelta.

Examples:

>>> to_timedelta('3D')
Timedelta('3 days 00:00:00')

>>> to_timedelta(pd.offsets.Hour(3))
Timedelta('0 days 03:00:00')

to_timedelta64

to_timedelta64(
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta,
) ‑> numpy.timedelta64

Convert a frequency-like object to a numpy timedelta64.

Parameters:

Name	Type	Default	Description
freq	str, int, Offset, pd.Timedelta	--	The frequency-like object to be converted.

Returns:

Type	Description
np.timedelta64	The corresponding numpy timedelta64.

Examples:

>>> to_timedelta64('1D')
# numpy.timedelta64(1,'D')

>>> to_timedelta64(pd.offsets.Hour(3))
# numpy.timedelta64(10800000000000,'ns')

time_to_timedelta

time_to_timedelta(
    t: str | datetime.time | systematica.utils.datetimes.FreqHandler,
    **kwargs,
) ‑> pandas._libs.tslibs.timedeltas.Timedelta

Convert a time-like object into pd.Timedelta.

Parameters:

Name	Type	Default	Description
t	str, time, FreqHandler	--	The time-like object to be converted.
kwargs	tp.Kwargs	--	Additional arguments passed to FreqHandler.parse_time_str if t is a string.

Raises:

Type	Description
ValueError	If the time string has a date or weekday component, or lacks a time component.

Returns:

Type	Description
pd.Timedelta	The resulting pd.Timedelta.

Examples:

>>> time_to_timedelta("12:34:56")
Timedelta('0 days 12:34:56')

>>> time_to_timedelta(time(12, 34, 56))
Timedelta('0 days 12:34:56')

to_timestamp

to_timestamp(
    dt: str | int | pandas._libs.tslibs.timestamps.Timestamp,
    parse_with_dateparser: bool = True,
    dateparser_kwargs: Dict[str, Any] = None,
    unit: str = 'ns',
    **kwargs,
) ‑> pandas._libs.tslibs.timestamps.Timestamp

Parse the input as a pd.Timestamp.

Parameters:

Name	Type	Default	Description
dt	str, int, pd.Timestamp	--	The datetime-like object to be parsed.
parse_with_dateparser	bool	True	If True, use dateparser to parse string inputs.
dateparser_kwargs	dict	None	Additional arguments passed to dateparser.parse.
unit	str	ns	The unit of the input when dt is a number.
kwargs	tp.Kwargs	--	Additional arguments passed to pd.Timestamp.

Raises:

Type	Description
ValueError	If the input cannot be parsed as a pd.Timestamp.

Returns:

Type	Description
pd.Timestamp	The parsed pd.Timestamp.
<Note>	This function supports various datetime-like inputs and attempts to parse them into a pd.Timestamp. If the input is a string, both Pandas and dateparser (if enabled) will be used for parsing. The tz argument allows specifying the desired time zone for the output.
</Note>

Examples:

>>> to_timestamp("2023-01-01 00:00:00")
# Timestamp('2023-01-01 00:00:00')

>>> to_timestamp(1672531200000, unit='ms')
 #Timestamp('2023-01-01 00:00:00')

>>> to_timestamp("now")
# Timestamp('2023-06-19 12:34:56.789012')

to_datetime

to_datetime(
    dt: str | int | pandas._libs.tslibs.timestamps.Timestamp,
    **kwargs,
) ‑> datetime.datetime

Parse the input as a datetime.datetime.

Parameters:

Name	Type	Default	Description
dt	str, int, pd.Timestamp	--	The datetime-like object to be parsed.
kwargs	tp.Kwargs	--	Additional arguments passed to to_timestamp.

Returns:

Type	Description
datetime.datetime	The parsed datetime.datetime object.

Examples:

>>> to_datetime("2023-01-01 00:00:00")
datetime.datetime(2023, 1, 1, 0, 0)

>>> to_datetime(1672531200000, unit='ms')
datetime.datetime(2023, 1, 1, 0, 0)

to_freq

to_freq(
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta,
    allow_offset: bool = True,
    keep_offset: bool = False,
) ‑> pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta

Convert a frequency-like object to a pandas DateOffset or Timedelta.

Parameters:

Name	Type	Default	Description
freq	str, int, Offset, pd.Timedelta	--	The frequency-like object to be converted.
allow_offset	bool	True	If True, allow conversion to pandas DateOffset.
keep_offset	bool	False	If True, keep the original DateOffset if applicable.

Returns:

Type	Description
Offset or pd.Timedelta	The corresponding DateOffset or Timedelta.

Examples:

>>> to_freq('1D')
# Timedelta('1 days 00:00:00')

>>> to_freq(pd.offsets.Hour(3))
# Timedelta('0 days 03:00:00')

date_range

date_range(
    start: str | int | pandas._libs.tslibs.timestamps.Timestamp = None,
    end: str | int | pandas._libs.tslibs.timestamps.Timestamp = None,
    *,
    periods: int = None,
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timestamps.Timestamp = None,
    inclusive: str = 'left',
    timestamp_kwargs: Dict[str, Any] = None,
    freq_kwargs: Dict[str, Any] = None,
    **kwargs,
) ‑> pandas.core.indexes.datetimes.DatetimeIndex

Generate a fixed frequency DatetimeIndex, preprocessing the inputs.

Parameters:

Name	Type	Default	Description
start	str	None	The start time for the date range.
end	str	None	The end time for the date range.
periods	int	None	Number of periods to generate.
freq	str	None	Frequency string or frequency object.
tz	str	None	Time zone for the resulting DatetimeIndex.
inclusive	str	left	Include boundaries; left, right, both, or neither.
timestamp_kwargs	tp.Kwargs	None	Additional arguments passed to to_timestamp.
freq_kwargs	tp.Kwargs	None	Additional arguments passed to to_freq.
kwargs	tp.Kwargs	--	Additional arguments passed to pd.date_range.

Returns:

Type	Description
pd.DatetimeIndex	A fixed frequency DatetimeIndex.
<Note>
This function preprocesses startandendwithto_timestamp, freq“
with to_freq, and tzwithto_timezone.
If startandperiodsare None,start is set to the beginning of the
Unix epoch. Similarly, if endandperiodsare None,end is set to the
current date and time.
</Note>

Examples:

>>> date_range(start='2022-01-01', end='2022-01-10', freq='D')
# DatetimeIndex(['2022-01-01', '2022-01-02', '2022-01-03', '2022-01-04',
#                '2022-01-05', '2022-01-06', '2022-01-07', '2022-01-08',
#                '2022-01-09', '2022-01-10'],
#               dtype='datetime64[ns]', freq='D')

>>> date_range(periods=5, freq='H')
# DatetimeIndex(['1970-01-01 00:00:00+00:00', '1970-01-01 01:00:00+00:00',
#                '1970-01-01 02:00:00+00:00', '1970-01-01 03:00:00+00:00',
#                '1970-01-01 04:00:00+00:00'],
#               dtype='datetime64[ns, UTC]', freq='H')

prepare_dt_index

prepare_dt_index(
    index: range | Sequence[Any],
    parse_index: bool = True,
    parse_with_dateparser: bool = True,
    dateparser_kwargs: Dict[str, Any] = None,
    **kwargs,
) ‑> pandas.core.indexes.base.Index

Try converting an index to a datetime index.

Parameters:

Name	Type	Default	Description
index	range	--	or sequence of any The index to be converted to a datetime index.
parse_index	bool	True	If True, attempts to parse the index using Pandas and dateparser. Default is True.
parse_with_dateparser	bool	True	If True, uses dateparser for parsing in addition to Pandas. Default is True.
dateparser_kwargs	dict	None	Arguments to pass to dateparser.parse. Default is None.
kwargs	tp.Kwargs	--	Additional arguments to pass to pd.to_datetime.

Returns:

Type	Description
pd.Index	The converted datetime index.

Raises:

Type	Description
Exception	If parsing fails and parse_index and parse_with_dateparser are both True.
<Note>
“dateparser_kwargsare passed todateparser.parsewhile**kwargs are
passed to pd.to_datetime.
</Note>

Examples:

>>> prepare_dt_index(['2020-01-01', '2020-01-02'])
# DatetimeIndex(['2020-01-01', '2020-01-02'], dtype='datetime64[ns]', freq=None)
>>> prepare_dt_index(range(10))
# Index([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype='object')

try_align_to_dt_index

try_align_to_dt_index(
    source_index: pandas.core.indexes.base.Index,
    target_index: pandas.core.indexes.base.Index,
    **kwargs,
) ‑> pandas.core.indexes.base.Index

Try aligning an index to another datetime index.

Parameters:

Name	Type	Default	Description
source_index	pd.Index	--	The source index to be aligned.
target_index	pd.Index	--	The target datetime index to align to.
kwargs	tp.Kwargs	--	Additional arguments passed to prepare_dt_index.

Returns:

Type	Description
pd.Index	The aligned datetime index.
<Note>
Keyword arguments are passed to prepare_dt_index.
</Note>

Examples:

>>> source_index = ['2020-01-01', '2020-01-02']
>>> target_index = pd.date_range(start='2020-01-01', periods=2, freq='D')
>>> try_align_to_dt_index(source_index, target_index)
# DatetimeIndex(['2020-01-01', '2020-01-02'], dtype='datetime64[ns]', freq=None)

try_align_dt_to_index

try_align_dt_to_index(
    dt: str | int | pandas._libs.tslibs.timestamps.Timestamp,
    target_index: pandas.core.indexes.base.Index,
    **kwargs,
) ‑> str | int | pandas._libs.tslibs.timestamps.Timestamp

Try aligning a datetime-like object to another datetime index.

Parameters:

Name	Type	Default	Description
dt	str, int, or pd.Timestamp	--	The datetime-like object to align.
target_index	pd.Index	--	The target datetime index to align to.
kwargs	tp.Kwargs	--	Additional arguments passed to to_timestamp.

Returns:

Type	Description
str, int, or pd.Timestamp	The aligned datetime-like object.
<Note>
Keyword arguments are passed to to_timestamp.
</Note>

Examples:

>>> dt = '2020-01-01'
>>> target_index = pd.date_range(start='2020-01-01', periods=1, freq='D')
>>> try_align_dt_to_index(dt, target_index)
# Timestamp('2020-01-01 00:00:00', freq='D')

auto_detect_freq

auto_detect_freq(
    index: pandas.core.indexes.base.Index,
) ‑> pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta

Auto-detect frequency from a datetime index.

Parameters:

Name	Type	Default	Description
index	pd.Index	--	The datetime index from which to detect frequency.

Returns:

Type	Description
Offset or pd.Timedelta	The detected frequency.
<Note>
Returns the minimal frequency if it is encountered in most of the index.
</Note>

Examples:

>>> index = pd.date_range(start='2020-01-01', periods=10, freq='D')
>>> auto_detect_freq(index)
# Timedelta('1 days 00:00:00')

parse_index_freq

parse_index_freq(
    index: pandas.core.indexes.datetimes.DatetimeIndex,
) ‑> pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta

Parse frequency from a datetime index.

Parameters:

Name	Type	Default	Description
index	pd.DatetimeIndex	--	The datetime index from which to parse frequency.

Returns:

Type	Description
Offset or pd.Timedelta	The parsed frequency.

Examples:

>>> index = pd.date_range(start='2020-01-01', periods=10, freq='D')
>>> parse_index_freq(index)
# Timedelta('1 days 00:00:00')

infer_index_freq

infer_index_freq(
    index: pandas.core.indexes.base.Index,
    freq: str | int | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta = None,
    allow_offset: bool = True,
    allow_numeric: bool = True,
    freq_from_n: bool | int = 20,
) ‑> int | float | pandas._libs.tslibs.offsets.BaseOffset | pandas._libs.tslibs.timedeltas.Timedelta

Infer frequency of a datetime index if freq is None, otherwise convert to the required frequency.

Parameters:

Name	Type	Default	Description
index	pd.Index	--	The index from which to infer frequency.
freq	str	None	The frequency to be used or converted. If None, the frequency is inferred from the index. If auto, the frequency is automatically detected. If index_[method_name], the method is applied to the pd.TimedeltaIndex derived from the differences between each pair of index points.
allow_offset	bool	True	If True, allows the output frequency to be a Offset instance.
allow_numeric	bool	True	If True, allows the output frequency to be a numeric value (int or float).
freq_from_n	int	20	If an int, limits the index to the first or last N index points respectively for frequency inference. If None, the entire index is considered. If a boolean, raises a ValueError if True.

Raises:

Type	Description
ValueError	If freq_from_n is True.

Returns:

Type	Description
None, int, float, Offset, pd.Timedelta	The inferred or converted frequency of the index. The type of the return value depends on the input parameters and the inferred frequency. Returns None if the frequency cannot be determined.

Examples:

>>> index = pd.date_range(start='2020-01-01', periods=100, freq='D')
>>> infer_index_freq(index, freq='auto')
# 'D'

get_ann_factor

get_ann_factor(
    freq: pandas._libs.tslibs.timedeltas.Timedelta,
)

Get annualization factor

Parameters:

Name	Type	Default	Description
freq	pd.Timedelta	--	Frequency.

Returns:

Type	Description
float	Annualization factor.

resolve_dates

resolve_dates(
    start: pandas._libs.tslibs.timestamps.Timestamp = None,
    end: pandas._libs.tslibs.timestamps.Timestamp = None,
) ‑> Tuple[pandas._libs.tslibs.timestamps.Timestamp | None, pandas._libs.tslibs.timestamps.Timestamp | None]

Resolve the start and end dates of the data.

Parameters:

Name	Type	Default	Description
start	str	None	The start date. Defaults to None.
end	str	None	The end date. Defaults to None.

Returns:

Type	Description
tuple	Start and end dates of the data.

FreqHandler

FreqHandler(
    year: int | None = None,
    month: int | None = None,
    day: int | None = None,
    weekday: int | None = None,
    hour: int | None = None,
    minute: int | None = None,
    second: int | None = None,
    nanosecond: int | None = None,
)

Frequency handler.

Parameters:

Name	Type	Default	Description
year	Optional[int]	None	Year.
month	Optional[int]	None	Month.
day	Optional[int]	None	Day of month.
weekday	Optional[int]	None	Day of week.
hour	Optional[int]	None	Hour.
minute	Optional[int]	None	Minute.
second	Optional[int]	None	Second.
nanosecond	Optional[int]	None	Nanosecond.

Static methods

parse_time_str

parse_time_str(
    time_str: str,
    **parse_kwargs,
) ‑> systematica.utils.datetimes.FreqHandler

Parse DTC instance from a time string.

Parameters:

Name	Type	Default	Description
time_str	str	--	The time string to parse.
parse_kwargs	tp.Kwargs	--	Additional keyword arguments passed to the date parser.

Raises:

Type	Description
ValueError	If the time string has a date or weekday component, or lacks a time component.

Returns:

Type	Description
FreqHandler	A FreqHandler instance representing the parsed time.

Instance variables

• year: int | None: The type of the None singleton.

• month: int | None: The type of the None singleton.

• day: int | None: The type of the None singleton.

• weekday: int | None: The type of the None singleton.

• hour: int | None: The type of the None singleton.

• minute: int | None: The type of the None singleton.

• second: int | None: The type of the None singleton.

• nanosecond: int | None: The type of the None singleton.

Methods

has_date

has_date(
    self,
) ‑> bool

Whether any date component is set.

Returns:

Type	Description
bool	True if any of year, month, or day is set, False otherwise.

has_weekday

has_weekday(
    self,
) ‑> bool

Whether the weekday component is set.

Returns:

Type	Description
bool	True if weekday is set, False otherwise.

has_time

has_time(
    self,
) ‑> bool

Whether any time component is set.

Returns:

Type	Description
bool	True if any of hour, minute, second, or nanosecond is set, False otherwise.

to_time

to_time(
    self,
) ‑> datetime.time

Convert to a datetime.time instance.

Returns:

Type	Description
time	A datetime.time instance representing the time components.