Datetimes - Systematica - Blockforce Capital

`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` start`and`end`with`to_timestamp`,` freq“
`with` to_freq`, and` tz`with`to_timezone`.`
`If` start`and`periods`are None,`start `is set to the beginning of the`
`Unix epoch. Similarly, if` end`and`periods`are 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_kwargs`are passed to`dateparser.parse`while`**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.

​current_utc

​current_utc_str

​to_offset

​to_timedelta

​to_timedelta64

​time_to_timedelta

​to_timestamp

​to_datetime

​to_freq

​date_range

​prepare_dt_index

​try_align_to_dt_index

​try_align_dt_to_index

​auto_detect_freq

​parse_index_freq

​infer_index_freq

​get_ann_factor

​resolve_dates

​FreqHandler

​Static methods

​parse_time_str

​Instance variables

​Methods

​has_date

​has_weekday

​has_time

​to_time

`current_utc`

`current_utc_str`

`to_offset`

`to_timedelta`

`to_timedelta64`

`time_to_timedelta`

`to_timestamp`

`to_datetime`

`to_freq`

`date_range`

`prepare_dt_index`

`try_align_to_dt_index`

`try_align_dt_to_index`

`auto_detect_freq`

`parse_index_freq`

`infer_index_freq`

`get_ann_factor`

`resolve_dates`

`FreqHandler`

Static methods

`parse_time_str`

Instance variables

Methods

`has_date`

`has_weekday`

`has_time`

`to_time`