> ## Documentation Index > Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Custom Datetime > systematica.utils.custom_datetime ## `current_utc` ```python theme={null} current_utc() ‑> datetime.datetime ``` Current time in UTC. **Returns**: | Type | Description | | ---------- | ------------------------------------------- | | `datetime` | Current time in UTC as a `datetime` object. | ## `current_utc_str` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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**: ```python theme={null} >>> to_timedelta('3D') Timedelta('3 days 00:00:00') >>> to_timedelta(pd.offsets.Hour(3)) Timedelta('0 days 03:00:00') ``` ## `to_timedelta64` ```python theme={null} 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**: ```python theme={null} >>> to_timedelta64('1D') # numpy.timedelta64(1,'D') >>> to_timedelta64(pd.offsets.Hour(3)) # numpy.timedelta64(10800000000000,'ns') ``` ## `time_to_timedelta` ```python theme={null} time_to_timedelta( t: str | datetime.time | systematica.utils.custom_datetime.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**: ```python theme={null} >>> 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` ```python theme={null} 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`. | | `` | 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. | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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**: ```python theme={null} >>> 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` ```python theme={null} 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**: ```python theme={null} >>> to_freq('1D') # Timedelta('1 days 00:00:00') >>> to_freq(pd.offsets.Hour(3)) # Timedelta('0 days 03:00:00') ``` ## `date_range` ```python theme={null} 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. | | `` | | | `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.` | | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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. | | `` | | | \`\`dateparser\_kwargs`are passed to`dateparser.parse`while`\*\*kwargs` are` | | | `passed to `pd.to\_datetime`.` | | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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. | | `` | | | `Keyword arguments are passed to `prepare\_dt\_index`.` | | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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. | | `` | | | `Keyword arguments are passed to `to\_timestamp`.` | | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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. | | `` | | | `Returns the minimal frequency if it is encountered in most of the index.` | | | `` | | **Examples**: ```python theme={null} >>> 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` ```python theme={null} 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**: ```python theme={null} >>> 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` ```python theme={null} 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**: ```python theme={null} >>> index = pd.date_range(start='2020-01-01', periods=100, freq='D') >>> infer_index_freq(index, freq='auto') # 'D' ``` ## `get_ann_factor` ```python theme={null} 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. | ## `FreqHandler` ```python theme={null} 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` ```python theme={null} parse_time_str( time_str: str, **parse_kwargs, ) ‑> systematica.utils.custom_datetime.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` ```python theme={null} 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` ```python theme={null} has_weekday( self, ) ‑> bool ``` Whether the weekday component is set. **Returns**: | Type | Description | | ------ | ---------------------------------------- | | `bool` | True if weekday is set, False otherwise. | #### `has_time` ```python theme={null} 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` ```python theme={null} to_time( self, ) ‑> datetime.time ``` Convert to a `datetime.time` instance. **Returns**: | Type | Description | | ------ | ------------------------------------------------------------ | | `time` | A `datetime.time` instance representing the time components. |