`riptable.rt_datetime`

Classes

`Date`	Date arrays have an underlying int32 array. The array values are number of days since January 1st. 1970.
`DateScalar`	Derived from np.int32
`DateSpan`	DateSpan arrays have an underlying int32 array. The array values are in number of days.
`DateSpanScalar`	Derived from np.int32
`DateTimeBase`	Base class for DateTimeNano and TimeSpan.
`DateTimeNano`	Date and timezone-aware time information, stored to nanosecond precision.
`DateTimeNanoScalar`	Derived from np.int64
`TimeSpan`	Array of time delta in nanoseconds, held in float64.
`TimeSpanScalar`	Derived from np.float64

Functions

`DateTimeUTC`(arr[, to_tz, from_matlab, format, ...])	Forces DateTimeNano `from_tz` keyword to 'UTC'.
`datestring_to_nano`(datestring[, time, from_tz, to_tz])	Converts date string to DateTimeNano object (default midnight).
`datetimestring_to_nano`(dtstring[, from_tz, to_tz])	Converts datetime string to DateTimeNano object.
`parse_epoch`(etime[, to_tz])	Days since epoch and milliseconds since midnight from nanosecond timestamps.
`strptime_to_nano`(dtstrings, format[, from_tz, to_tz])	Converts datetime string to DateTimeNano object with user-specified format.
`timestring_to_nano`(timestring[, date, from_tz, to_tz])	Converts timestring to TimeSpan or DateTimeNano object.

class riptable.rt_datetime.Date(arr, from_matlab=False, format=None)[source]

Bases: DateBase, TimeStampBase

Date arrays have an underlying int32 array. The array values are number of days since January 1st. 1970. Can be initialized from integer date values, strings, or matlab ordinal dates.

Parameters:

arr (array, categorical, list, or scalar) –
from_matlab (indicates that values are from matlab datenum) –
format (if initialized with string, specify a format string for strptime to parse date information) – otherwise, will assume format is YYYYMMDD

Examples

From strings:

>>> datestrings = tile(np.array(['2018-02-01', '2018-03-01', '2018-04-01']), 3)
>>> Date(datestrings)
Date([2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01])

From riptable.Categorical (sometimes Matlab data comes in this way):

>>> c = Categorical(datestrings)
>>> c
Categorical([2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01]) Length: 9
  FastArray([1, 2, 3, 1, 2, 3, 1, 2, 3], dtype=int8) Base Index: 1
  FastArray(['2018-02-01', '2018-03-01', '2018-04-01'], dtype='<U10') Unique count: 3
>>> d = Date(c)
>>> d
Date([2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01, 2018-02-01, 2018-03-01, 2018-04-01])

From Matlab datenum:

>>> d = FA([737061.0, 737062.0, 737063.0, 737064.0, 737065.0])
>>> Date(dates, from_matlab=True)
Date([2018-01-01, 2018-01-02, 2018-01-03, 2018-01-04, 2018-01-05])

From riptable DateTimeNano:

>>> dtn = DateTimeNano.random(5)
>>> dtn
DateTimeNano([20150318 13:28:01.853344227, 20150814 17:34:43.991344669, 19761204 04:30:52.680683459, 20120524 06:44:13.482424912, 19830803 17:12:54.771824294])
>>> Date(dtn)
Date([2015-03-18, 2015-08-14, 1976-12-04, 2012-05-24, 1983-08-03])

property _year_splits: Midnght on Jan. 1st from 1970 - 2099 in utc nanoseconds.

property _yearday_splits: Midnight on the 1st of the month in dayssince the beginning of the year.

property _yearday_splits_leap: Midnight on the 1st of the month in days since the beginning of the year during a leap year.

property day_of_month

The day of the month of each Date element.

Days are represented as integers: 1 = Jan 1, 31 = Jan 31, etc.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT).

Returns:: A FastArray of integers representing the day of the month of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2019-01-01', '2020-02-29', '2021-12-31'])
>>> d.day_of_month
FastArray([ 1, 29, 31])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.day_of_month
FastArray([-2147483648, -2147483648,          31])

property day_of_week

The day of the week of each Date element.

Days are represented as integers: 0 = Monday, 1 = Tuesday, …, 6 = Sunday.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT).

Returns:: A FastArray of integers representing the day of the week of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2019-02-11', '2019-02-12', '2019-02-13',
...              '2019-02-14', '2019-02-15', '2019-02-16', '2019-02-17'])
>>> d.day_of_week
FastArray([0, 1, 2, 3, 4, 5, 6])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.day_of_week
FastArray([-2147483648, -2147483648,           2,           3,
             4,           5,           6])

property day_of_year

The day of the year of each Date element.

Days are represented as integers: 1 = Jan 1, 32 = Feb 1, etc.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT).

Returns:: A FastArray of integers representing the day of the year of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2019-01-01', '2020-02-29', '2021-12-31'])
>>> d.day_of_year
FastArray([  1,  60, 365])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.day_of_year
FastArray([-2147483648, -2147483648,         365])

property is_leapyear

Return a boolean array that’s True for each Date element that’s in a leap year, False otherwise.

NaN or invalid Date values return False.

Returns:: A FastArray of booleans that’s True for each Date element that’s in a leap year, False otherwise.
Return type:: FastArray

See also

Date.is_weekend, Date.is_weekday

Examples

>>> d = rt.Date(['1996-01-01', '2000-01-01', '2004-01-01', '2022-01-01'])
>>> d.is_leapyear
FastArray([ True,  True,  True, False])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.is_leapyear
FastArray([False, False,  True, False])

property is_weekday

Return a boolean array that’s True for each Date element that’s a weekday (Monday-Friday), False otherwise.

NaN or invalid Date values return False.

Returns:: A FastArray of booleans that’s True for each Date element that’s a weekday, False otherwise.
Return type:: FastArray

See also

Date.is_weekend, Date.is_leapyear

Examples

>>> d = rt.Date(['2019-02-11', '2019-02-12', '2019-02-13',
...              '2019-02-14', '2019-02-15', '2019-02-16', '2019-02-17'])
>>> d.is_weekday
FastArray([ True,  True,  True,  True,  True, False, False])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.is_weekday
FastArray([False, False,  True,  True,  True, False, False])

property is_weekend

Return a boolean array that’s True for each Date element that’s a Saturday or Sunday, False otherwise.

NaN or invalid Date values return False.

Returns:: A FastArray of booleans that’s True for each Date element that’s a Saturday or Sunday, False otherwise.
Return type:: FastArray

See also

Date.is_weekday, Date.is_leapyear

Examples

>>> d = rt.Date(['2019-02-09', '2019-02-10', '2019-02-11', '2019-02-12',
...              '2019-02-13', '2019-02-14', '2019-02-15', '2019-02-16', '2019-02-17'])
>>> d.is_weekend
FastArray([ True,  True, False, False, False, False, False,  True,  True])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.is_weekend
FastArray([False, False, False, False, False, False, False,  True,  True])

property month

The month of each Date element.

Months are represented as integers: 1 = Jan, 2 = Feb, etc.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT).

Returns:: A FastArray of integers representing the month of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2016-02-01', '2017-03-01', '2018-04-01'])
>>> d.month
FastArray([2, 3, 4])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.month
FastArray([-2147483648, -2147483648,           4])

property monthyear

The month and year of each Date element.

Each month-year value is a byte string with a three-letter month abbreviation concatenated with a four-digit year.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT) as a byte string.

Returns:: A FastArray of byte strings containing the month and year of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2000-02-29', '2018-12-25', '2019-03-18'])
>>> d.monthyear
FastArray([b'Feb2000', b'Dec2018', b'Mar2019'], dtype='|S14')

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.monthyear
FastArray([b'-2147483648', b'-2147483648', b'Mar2019'], dtype='|S14')

property seconds_since_epoch: Many existing python datetime routines expect seconds since epoch. This call is to eliminate “magic numbers” like 3600 from code.

property start_of_month: rtype: rt.Date array of first of self’s month

property start_of_week: rtype: rt.Date array of previous Monday

property year

The year of each Date element.

Years are currently limited to 1970-2099. To expand the range, add to the UTC_1970_DAY_SPLITS table.

NaN or invalid Date values return Riptable’s int32 sentinel value (-MAXINT).

Returns:: A FastArray of integers representing the year of each Date element.
Return type:: FastArray

Examples

>>> d = rt.Date(['2016-02-01', '2017-02-01', '2018-02-01'])
>>> d.year
FastArray([2016, 2017, 2018])

With NaN and invalid values:

>>> d[0] = 0
>>> d[1] = d.inv
>>> d.year
FastArray([-2147483648, -2147483648,        2018])

property yyyymmdd

MetaDefault

MetaVersion = 1

forbidden_mathops = ('__mul__', '__imul__')

abstract __abs__()[source]

__add__(value)[source]

Addition rules

Date + Date = TypeError Date + DateTimeNano = TypeError Date + DateSpan = Date Date + TimeSpan = DateTimeNano

All other operands will be treated as DateSpan and return Date.

abstract __and__(other)[source]

__arrow_array__(type=None)[source]

Implementation of the __arrow_array__ protocol for conversion to a pyarrow array.

Parameters:: type (pyarrow.DataType, optional, defaults to None) –
Return type:: pyarrow.Array or pyarrow.ChunkedArray

Notes

https://arrow.apache.org/docs/python/extending_types.html#controlling-conversion-to-pyarrow-array-with-the-arrow-array-protocol

abstract __ceil__()[source]

abstract __complex__()[source]

__eq__(other)[source]: Return self==value.

abstract __float__()[source]

abstract __floor__()[source]

__ge__(other)[source]: Return self>=value.

__gt__(other)[source]: Return self>value.

__iadd__(value)[source]

abstract __iand__(other)[source]

abstract __ifloordiv__(other)[source]

abstract __ilshift__(other)[source]

abstract __imatmul__(other)[source]

abstract __imod__(other)[source]

abstract __imul__(other)[source]

abstract __int__()[source]

abstract __invert__()[source]

abstract __ior__(other)[source]

abstract __ipow__(other, modulo=None)[source]

abstract __irshift__(other)[source]

__isub__(value)[source]

abstract __itruediv__(other)[source]

abstract __ixor__(other)[source]

__le__(other)[source]: Return self<=value.

abstract __lshift__(other)[source]

__lt__(other)[source]: Return self<value.

abstract __matmul__(other)[source]

abstract __mul__(other)[source]

__ne__(other)[source]: Return self!=value.

abstract __neg__()[source]

abstract __or__(other)[source]

abstract __pos__()[source]

abstract __pow__(other, modulo=None)[source]

__radd__(value)[source]

abstract __rand__(other)[source]

abstract __rdivmod__(other)[source]

abstract __rfloordiv__(other)[source]

abstract __rlshift__(other)[source]

abstract __rmatmul__(other)[source]

abstract __rmod__(other)[source]

abstract __rmul__(other)[source]

abstract __ror__(other)[source]

abstract __round__(ndigits=0)[source]

abstract __rpow__(other)[source]

abstract __rrshift__(other)[source]

abstract __rshift__(other)[source]

__rsub__(value)[source]

abstract __rtruediv__(other)[source]

abstract __rxor__(other)[source]

__sub__(value)[source]

Subtraction rules

Date - Date = DateSpan Date - DateSpan = Date Date - DateTimeNano = TimeSpan Date - TimeSpan = DateTimeNano

All other operands will be treated as DateSpan and return Date.

abstract __trunc__()[source]

abstract __xor__(other)[source]

_check_mathops(funcname, value)[source]

This gets called after a math operation has been performed on the Date’s FastArray. Return type may differ based on operation. Preserves invalids from original input.

Parameters:

funcname (name of ufunc) –
value (original operand in math operation) –
return_type (returns) –
other_inv_mask –

_check_mathops_nano(funcname, value, other_inv_mask, return_type, caller)[source]

Operations with TimeSpan and DateTimeNano will flip to nano precision, or raise an error.

Parameters:

funcname (name of ufunc) –
value (original operand in math operation) –
other_inv_mask (None, might be set in this routine) –
return_type (None, might be set to TimeSpan or DateTimeNano) –
caller (FastArray view of Date object.) –

classmethod _convert_datestring(arr, format=None)[source]: For construction from array of strings or categorical.

classmethod _convert_matlab_days(arr)[source]

TODO: move this to a more generic superclass - almost exactly the same as DateTimeNano._convert_matlab_days

Parameters:

arr (array of matlab datenums (1 is 1-Jan-0000)) –
timezone (TimeZone object from DateTimeNano constructor) –

Converts matlab datenums to an array of int64 containing utc nanoseconds.

_date_compare_check(funcname, other)[source]: Funnel for all comparison operations. Helps Date interact with DateTimeNano, TimeSpan.

static _from_arrow(arr, zero_copy_only=True, writable=False)[source]

Create a Date instance from a “date32” or “date64”-typed pyarrow.Array.

Parameters:

arr (pyarrow.Array or pyarrow.ChunkedArray) – Must be a “date32”- or “date64”-typed pyarrow array.
zero_copy_only (bool, optional, defaults to False) –
writable (bool, optional, defaults to False) –

Return type:

Date

classmethod _load_from_sds_meta_data(name, arr, cols, meta)[source]: Restore Date class after loading from .sds file.

static _parse_item_format(itemformat)[source]

diff(periods=1)[source]

Return type:: DateSpan

static display_convert_func(date_num, itemformat)[source]

fill_invalid(shape=None, dtype=None, inplace=True)[source]

Replace all values of the input FastArray with an invalid value.

The invalid value used is determined by the input array’s dtype or a user-specified dtype.

Warning: By default, this operation is in place.

Parameters:

shape (int or sequence of int, optional) – Shape of the new array, for example: (2, 3) or 2. Note that although multi-dimensional arrays are technically supported by Riptable, you may get unexpected results when working with them.
dtype (str, optional) – The desired dtype for the returned array.
inplace (bool, default True) – If True (the default), modify original data. If False, return a copy of the array.

Returns:

If inplace=False, a copy of the input FastArray is returned that has all values replaced with an invalid value. Otherwise, nothing is returned.

Return type:

FastArray, optional

See also

FastArray.inv: Return the invalid value for the input array’s dtype.
FastArray.copy_invalid: Return a copy of a FastArray filled with the invalid value for the array’s dtype.

Examples

Replace an integer array’s values with the invalid value for the array’s dtype. By default, the returned array is the same size and dtype as the input array, and the operation is performed in place:

>>> a = rt.FA([1, 2, 3, 4, 5])
>>> a
FastArray([1, 2, 3, 4, 5])
>>> a.fill_invalid()
>>> a
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Replace a floating-point array’s values with the invalid value for the int32 dtype:

>>> a2 = rt.FA([0., 1., 2., 3., 4.])
>>> a2
FastArray([0., 1., 2., 3., 4.])
>>> a2.fill_invalid(dtype="int32", inplace=False)
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Specify the size and dtype of the output array:

>>> a3 = rt.FA(["AMZN", "IBM", "MSFT", "AAPL"])
>>> a3
FastArray([b'AMZN', b'IBM', b'MSFT', b'AAPL'], dtype='|S4')
>>> a3.fill_invalid(2, dtype="bool", inplace=False)
FastArray([False, False])

static format_date_num(date_num, itemformat)[source]

get_classname()[source]

get_scalar(scalarval)[source]

classmethod hstack(dates)[source]

hstacks Date objects and returns a new Date object. Will be called by riptable.hstack() if the first item in the sequence is a Date object.

Parameters:: dates (list or tuple of Date objects) –

>>> d1 = Date('2015-02-01')
>>> d2 = Date(['2016-02-01', '2017-02-01', '2018-02-01'])
>>> hstack([d1, d2])
Date([2015-02-01, 2016-02-01, 2017-02-01, 2018-02-01])

isfinite()[source]

Return a boolean array that’s True for each Date element that’s not a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int32 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each non-NaN element, False otherwise.
Return type:: FastArray

See also

Date.isnan, DateTimeNano.isnan, DateTimeNano.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> d = rt.Date.range('20190201', days = 3, step = 2)
>>> d[0] = 0
>>> d[1] = d.inv
>>> d
Date(['Inv', 'Inv', '2019-02-05'])
>>> d.isfinite()
FastArray([False, False,  True])

isnan()[source]

Return a boolean array that’s True for each Date element that’s a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int32 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each NaN element, False otherwise.
Return type:: FastArray

See also

Date.isnotnan, DateTimeNano.isnan, DateTimeNano.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> d = rt.Date.range('20190201', days = 3, step = 2)
>>> d[0] = 0
>>> d[1] = d.inv
>>> d
Date(['Inv', 'Inv', '2019-02-05'])
>>> d.isnan()
FastArray([ True,  True, False])

isnotfinite()[source]

Return a boolean array that’s True for each Date element that’s a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int32 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each NaN element, False otherwise.
Return type:: FastArray

See also

Date.isnotnan, DateTimeNano.isnan, DateTimeNano.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> d = rt.Date.range('20190201', days = 3, step = 2)
>>> d[0] = 0
>>> d[1] = d.inv
>>> d
Date(['Inv', 'Inv', '2019-02-05'])
>>> d.isnotfinite()
FastArray([ True,  True, False])

isnotnan()[source]

Return a boolean array that’s True for each Date element that’s not a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int32 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each non-NaN element, False otherwise.
Return type:: FastArray

See also

Date.isnan, DateTimeNano.isnan, DateTimeNano.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> d = rt.Date.range('20190201', days = 3, step = 2)
>>> d[0] = 0
>>> d[1] = d.inv
>>> d
Date(['Inv', 'Inv', '2019-02-05'])
>>> d.isnotnan()
FastArray([False, False,  True])

classmethod range(start, end=None, days=None, step=1, format=None, closed=None)[source]

Return a Date object of dates within a given interval, spaced by step.

Note: Either end or days must be provided, but providing both results in unexpected behavior. In future versions, an error will be raised.

Parameters:

start (int or str) – Start date as an integer (YYYYMMDD) or string. If the string is not in ‘YYYYMMDD’ format, format is required.
end (int or str, optional) – End date as an integer (YYYYMMDD) or string. If the string is not in ‘YYYYMMDD’ format, format is required. If end is not provided, the number of dates to generate must be specified with days.
days (int, optional) – Instead of using end, use days to specify the number of dates to generate. Required if end isn’t provided. Providing both end and days results in unexpected behavior.
step (int, default 1) – The number of days between generated dates.
format (str, optional) – For a string start or end value, one or more format codes supported by the datetime.strptime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior. The format code is used to parse the string representation and convert it to a Date element.
closed ({None, 'left', 'right'}, default None) –
Determines whether the start and end dates are included in the result. Applies only when start and end are specified and step=1.
- left: Start date is included, end date is excluded.
- right: End date is included, start date is excluded.
- None (the default): Both the start and end dates are included.

Returns:

A Date object of dates within a given interval, spaced by step.

Return type:

Date

See also

DateTimeNano.random: Return an array of randomly generated DateTimeNano values.
riptable.arange: Return an array of evenly spaced values within a specified interval.

Examples

With integer start and end dates:

>>> rt.Date.range(20230101, 20230105)
Date(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05'])

With string start and end dates, and a format code:

>>> rt.Date.range('01 January, 2023', '05 January, 2023', format='%d %B, %Y')
Date(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05'])

If end isn’t specified, days is required:

>>> rt.Date.range(20230101, days=5)
Date(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04', '2023-01-05'])

Changing the step:

>>> rt.Date.range(20230101, 20230105, step=2)
Date(['2023-01-01', '2023-01-03'])

A left-inclusive, right-exclusive range:

>>> rt.Date.range(20230101, 20230105, closed='left')
Date(['2023-01-01', '2023-01-02', '2023-01-03', '2023-01-04'])

strftime(format, dtype='O')[source]

Convert each Date element to a formatted string representation.

Parameters:

format (str) – One or more format codes supported by the datetime.date.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
dtype ({"O", "S", "U"}, default "O") –
The data type of the returned array elements:
- ”O”: object string
- ”S”: byte string
- ”U”: unicode string

Returns:

An ndarray of strings.

Return type:

ndarray

Notes

This routine has not been sped up yet. It’s also not NaN-aware: NaNs are converted to the timestamp of the epoch (01-01-1970), then formatted.

Examples

>>> d = rt.Date(['20210101', '20210519', '20220308'])
>>> d.strftime('%D')
array(['01/01/21', '05/19/21', '03/08/22'], dtype=object)

to_arrow(type=None, *, preserve_fixed_bytes=False, empty_strings_to_null=True)[source]

Convert this Date to a pyarrow.Array.

Parameters:

type (pyarrow.DataType, optional, defaults to None) – Unused.
preserve_fixed_bytes (bool, optional, defaults to False) – Unused.
empty_strings_to_null (bool, optional, defaults To True) – Unused.

Return type:

pyarrow.Array or pyarrow.ChunkedArray

class riptable.rt_datetime.DateScalar(**kwargs)[source]

Bases: numpy.int32

Derived from np.int32 days since unix epoch in 1970 TODO: need to inherit math functions

property _fa

property _np

__slots__ = '_display_length'

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

get_classname()[source]

get_item_format()[source]

repeat(repeats, axis=None)[source]

strftime(format)[source]

Convert a DateScalar to a formatted string representation.

Parameters:: format (str) – One or more format codes supported by the datetime.date.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
Returns:: A string representation of the reformatted DateScalar.
Return type:: str

Notes

This routine has not been sped up yet. It also raises an error on NaNs.

Examples

>>> d = rt.Date(['20210101', '20210519', '20220308'])
>>> d[0].strftime('%D')
'01/01/21'

tile(repeats)[source]

class riptable.rt_datetime.DateSpan(arr, unit=None)[source]

Bases: DateBase

DateSpan arrays have an underlying int32 array. The array values are in number of days. These are created as the result of certain math operations on Date objects.

Parameters:

arr (numeric array, list, or scalar) –
unit (can set units to 'd' (day) or 'w' (week)) –

property format_long

property format_short

MetaDefault

MetaVersion = 1

NAN_DATE

forbidden_mathops = ()

__add__(value)[source]

__eq__(other)[source]: Return self==value.

__ge__(other)[source]: Return self>=value.

__gt__(other)[source]: Return self>value.

__iadd__(value)[source]

__isub__(value)[source]

__le__(other)[source]: Return self<=value.

__lt__(other)[source]: Return self<value.

__ne__(other)[source]: Return self!=value.

__sub__(value)[source]

_check_mathops(funcname, value)[source]

This gets called after a math operation has been performed on the Date’s FastArray. Return type may differ based on operation. Preserves invalids from original input.

Parameters:

funcname (name of ufunc) –
value (original operand in math operation) –
return_type (returns) –
other_inv_mask –

_check_mathops_nano(funcname, value, other_inv_mask, return_type, caller)[source]

Operations with TimeSpan and DateTimeNano will flip to nano precision, or raise an error.

Parameters:

funcname (name of ufunc) –
value (original operand in math operation) –
other_inv_mask (None, might be set in this routine) –
return_type (None, might be set to TimeSpan or DateTimeNano) –
caller (FastArray view of Date object.) –

_datespan_compare_check(funcname, other)[source]: Funnel for all comparison operations. Helps Date interact with DateTimeNano, TimeSpan.

classmethod _load_from_sds_meta_data(name, arr, cols, meta)[source]: Restore Date class after loading from .sds file.

static display_convert_func(date_num, itemformat)[source]: Called by main rt_display() routine to format items in array correctly in Dataset display. Also called by DateSpan’s __str__() and __repr__().

fill_invalid(shape=None, dtype=None, inplace=True)[source]

Replace all values of the input FastArray with an invalid value.

The invalid value used is determined by the input array’s dtype or a user-specified dtype.

Warning: By default, this operation is in place.

Parameters:

shape (int or sequence of int, optional) – Shape of the new array, for example: (2, 3) or 2. Note that although multi-dimensional arrays are technically supported by Riptable, you may get unexpected results when working with them.
dtype (str, optional) – The desired dtype for the returned array.
inplace (bool, default True) – If True (the default), modify original data. If False, return a copy of the array.

Returns:

If inplace=False, a copy of the input FastArray is returned that has all values replaced with an invalid value. Otherwise, nothing is returned.

Return type:

FastArray, optional

See also

FastArray.inv: Return the invalid value for the input array’s dtype.
FastArray.copy_invalid: Return a copy of a FastArray filled with the invalid value for the array’s dtype.

Examples

Replace an integer array’s values with the invalid value for the array’s dtype. By default, the returned array is the same size and dtype as the input array, and the operation is performed in place:

>>> a = rt.FA([1, 2, 3, 4, 5])
>>> a
FastArray([1, 2, 3, 4, 5])
>>> a.fill_invalid()
>>> a
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Replace a floating-point array’s values with the invalid value for the int32 dtype:

>>> a2 = rt.FA([0., 1., 2., 3., 4.])
>>> a2
FastArray([0., 1., 2., 3., 4.])
>>> a2.fill_invalid(dtype="int32", inplace=False)
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Specify the size and dtype of the output array:

>>> a3 = rt.FA(["AMZN", "IBM", "MSFT", "AAPL"])
>>> a3
FastArray([b'AMZN', b'IBM', b'MSFT', b'AAPL'], dtype='|S4')
>>> a3.fill_invalid(2, dtype="bool", inplace=False)
FastArray([False, False])

static format_date_span(date_span, itemformat)[source]: Turn a single value in the DateSpan array into a string for display.

get_classname()[source]

get_scalar(scalarval)[source]

classmethod hstack(dates)[source]

hstacks DateSpan objects and returns a new DateSpan object. Will be called by riptable.hstack() if the first item in the sequence is a DateSpan object.

Parameters:: dates (list or tuple of DateSpan objects) –

>>> d1 = Date('2015-02-01')
>>> d2 = Date(['2016-02-01', '2017-02-01', '2018-02-01'])
>>> hstack([d1, d2])
Date([2015-02-01, 2016-02-01, 2017-02-01, 2018-02-01])

strftime(format, dtype='O')[source]

Convert each DateSpan element to a formatted string representation.

Deprecated since version 1.3: DateSpan.strftime is deprecated will be removed in the future.

Note that because each DateSpan element is converted to a timestamp relative to the epoch before it is formatted (for example, a DateSpan of “2 days” is converted to 01-03-1970), you may need to adjust the data before calling this method.

Negative DateSpan values (for example, “-10 days”) can’t be formatted with this method.

Parameters:

format (str) – One or more format codes supported by the datetime.date.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
dtype ({"O", "S", "U"}, default "O") –
The data type of the returned array elements.
- ”O”: object string
- ”S”: byte string
- ”U”: unicode string

Returns:

An ndarray of strings.

Return type:

ndarray

Notes

This routine has not been sped up yet. It’s also not NaN-aware: NaNs are converted to the timestamp of the epoch (01-01-1970), then formatted.

Examples

>>> d = rt.Date(['20210101', '20210519', '20220308'])
>>> ds = d - rt.Date('20201201')
>>> ds
DateSpan(['31 days', '169 days', '462 days'])
>>> ds.strftime('%D')
array(['02/01/70', '06/19/70', '04/08/71'], dtype=object)

class riptable.rt_datetime.DateSpanScalar(**kwargs)[source]

Bases: numpy.int32

Derived from np.int32 Number of days between two dates

property _fa

property _np

NAN_DATESPANSCALAR

__slots__ = '_display_length'

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

get_classname()[source]

get_item_format()[source]

isfinite()[source]

isnan()[source]

isnotfinite()[source]

isnotnan()[source]

repeat(repeats, axis=None)[source]

tile(repeats)[source]

class riptable.rt_datetime.DateTimeBase(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)[source]

Bases: riptable.rt_fastarray.FastArray

Base class for DateTimeNano and TimeSpan. Both of these subclasses have times with nanosecond precision.

property _fa

property display_length

DEFAULT_FORMATTER

NAN_TIME = 0

PRECISION = 9

__array_finalize__(obj)[source]: Finalizes self from other, called as part of ndarray.__new__()

__getitem__(fld)[source]: riptable has special routines to handle array input in the indexer. Everything else will go to numpy getitem.

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

static _add_nano_ext(utcnano, timestr)[source]

_as_meta_data(name=None)[source]

_build_sds_meta_data(name, **kwargs)[source]: Build meta data for DateTimeNano

_build_string()[source]

_funnel_mathops(funcname, value)[source]

Wrapper for all math operations on Date and DateSpan.

Both subclasses need to take over: _check_mathops_nano() _check_mathops()

maybe… still testing _build_mathops_result()

Easier to catch forbidden operations here.

_math_error_string(value, operator, reverse=False)[source]

abstract _meta_dict(name=None)[source]

copy(order='K')[source]

Return a copy of the input FastArray.

Parameters:: order ({'K', 'C', 'F', 'A'}, default 'K') – Controls the memory layout of the copy: ‘K’ means match the layout of the input array as closely as possible; ‘C’ means row-based (C-style) order; ‘F’ means column-based (Fortran-style) order; ‘A’ means ‘F’ if the input array is formatted as ‘F’, ‘C’ if not.
Returns:: A copy of the input FastArray.
Return type:: FastArray

See also

Categorical.copy: Return a copy of the input Categorical.
Dataset.copy: Return a copy of the input Dataset.
Struct.copy: Return a copy of the input Struct.

Examples

Copy a FastArray:

>>> a = rt.FA([1, 2, 3, 4, 5])
>>> a
FastArray([1, 2, 3, 4, 5])
>>> a2 = a.copy()
>>> a2
FastArray([1, 2, 3, 4, 5])
>>> a2 is a
False  # The copy is a separate object.

abstract display_item(utcnano)[source]

get_classname()[source]

class riptable.rt_datetime.DateTimeNano(arr, from_matlab=False, from_tz=None, to_tz=None, format=None, start_date=None, gmt=None)[source]

Bases: DateTimeBase, TimeStampBase, DateTimeCommon

Date and timezone-aware time information, stored to nanosecond precision.

DateTimeNano arrays have an underlying int64 array representing the number of nanoseconds since the Unix epoch (00:00:00 UTC on 01-01-1970). Dates before the Unix epoch are invalid.

In most cases, DateTimeNano objects default to display in Eastern/NYC time, accounting for Daylight Saving Time. The exception is when arr is an array of Date objects, in which case the default display timezone is UTC.

Parameters:

arr (array of int, str, Date, TimeSpan, datetime, numpy.datetime64) –
Datetimes to store in the DateTimeNano array.
- Integers represent nanoseconds since the Unix epoch (00:00:00 UTC on 01-01-1970).
- Datetime strings can generally be in YYYYMMDD HH:MM:SS.fffffffff format without format codes needing to be specified. Bytestrings, unicode strings, and strings in ISO 8601 format are supported. If your strings are in another format (for example, MMDDYY), specify it with format. Other notes for string input:
  - from_tz is required.
  - If start_date is provided, strings are parsed as TimeSpan objects before start_date is applied. See how this affects output in the Examples section below.
  - For NumPy vs. Riptable string parsing differences, see the Notes section below.
- For Date objects, both from_tz and to_tz are “UTC” by default.
- For TimeSpan objects, start_date needs to be specified.
- Using the DateTimeNano constructor is recommended for Date + TimeSpan operations.
- numpy.datetime64 values are converted to nanoseconds.
from_tz (str) –
The timezone the data in arr is stored in. Required if the DateTimeNano is created from strings, and recommended in other cases to ensure expected results. The default from_tz is “UTC” for all arr types except strings, for which a from_tz must be specified.

Timezones supported (Daylight Saving Time is accounted for):
- ”America/New_York”
- ”Australia/Sydney”
- ”Europe/Dublin”
- ”DUBLIN”: alias for “Europe/Dublin”
- ”GMT”: Greenwich Mean Time
- ”NYC”: US/Eastern
- ”UTC”: (not a timezone, but accepted as an alias for GMT)
to_tz (str) – The timezone the data is displayed in. If arr is Date objects, the default to_tz is “UTC”. For other arr types, the default to_tz is “NYC”.
from_matlab (bool, default False) – When set to True, indicates that arr contains Matlab datenums (the number of days since 0-Jan-0000). Because Matlab datenums may also include a fraction of a day, be sure to specify from_tz for accurate time data.
format (str) – Specify a format for string arr input. For format codes, see the Python strptime cheatsheet. This parameter is ignored for non-string arr input.
start_date (str or array of Date) –
- Required if constructing a DateTimeNano from a TimeSpan.
- If arr is strings, the values in arr are parsed as TimeSpan objects before start_date is applied. See how this affects output in the Examples section below. Otherwise, start_date is added (as nanos) to dates in arr.
- If start_date is a string, use YYYYMMDD format.
- If start_date is a Date array, it is broadcast to arr if possible; otherwise an error is raised.
- A start_date before the Unix epoch is converted to the Unix epoch.

Notes

The constructor does not attempt to preserve NaN times from Python datetime objects.
If the integer data in a DateTimeNano object is extracted, it is in the from_tz timezone. To initialize another DateTimeNano with the same underlying array, use the same from_tz.
DateTimeNano objects have no knowledge of timezones. All timezone operations are handled by the TimeZone class.

Math Operations

The following math operations can be performed:

Date + TimeSpan = DateTimeNano

Date - DateTimeNano = TimeSpan

Date - TimeSpan = DateTimeNano

DateTimeNano - DateTimeNano = TimeSpan

DateTimeNano - Date = TimeSpan

DateTimeNano - TimeSpan = DateTimeNano

DateTimeNano + TimeSpan = DateTimeNano

String Parsing Differences Between NumPy and Riptable

Riptable DateTimeNano string parsing is generally more forgiving than NumPy’s numpy.datetime64 array parsing.
In some cases where NumPy raises an error, Riptable returns an object.
The lower limit for DateTimeNano string parsing is Unix epoch time.
You can always guarantee that Riptable and NumPy get the same results by using the full ISO 8601 datetime format (YYYY-MM-DDTHH:MM:SS.fffffffff).

Riptable parses strings without leading zeros:

>>> import numpy as np
>>> rt.DateTimeNano(["2018-1-1"], from_tz="NYC")
DateTimeNano(['20180101 00:00:00.000000000'], to_tz='NYC')
>>> np.array(["2018-1-1"], dtype="datetime64[ns]")
ValueError: Error parsing datetime string "2018-1-1" at position 5

Riptable handles extra trailing spaces; NumPy incorrectly treats them as a timezone whose parsing will be deprecated soon:

>>> rt.DateTimeNano(["2018-10-11 10:11:00.123           "], from_tz="NYC")
DateTimeNano(['20181011 10:11:00.123000000'], to_tz='NYC')
>>> np.array(["2018-10-11 10:11:00.123           "], dtype="datetime64[ns]")
DeprecationWarning: parsing timezone aware datetimes is deprecated; this will
raise an error in the future
array(['2018-10-11T10:11:00.123000000'], dtype='datetime64[ns]')

Riptable correctly parses dates without delimiters:

>>> rt.DateTimeNano(["20181231"], from_tz="NYC")
DateTimeNano(['20181231 00:00:00.000000000'], to_tz='NYC')
>>> np.array(["20181231"], dtype="datetime64[ns]")
array(['1840-08-31T19:51:12.568664064'], dtype='datetime64[ns]')

To ensure that Riptable and NumPy get the same results, use the full ISO 8601 datetime format:

>>> rt.DateTimeNano(["2018-12-31T12:34:56.789123456"], from_tz="NYC")
DateTimeNano(['20181231 12:34:56.789123456'], to_tz='NYC')
>>> np.array(["2018-12-31T12:34:56.789123456"], dtype="datetime64[ns]")
array(['2018-12-31T12:34:56.789123456'], dtype='datetime64[ns]')

See also

DateTimeNano.info: See timezone info for a DateTimeNano object.
Date: Riptable’s Date class.
DateSpan: Riptable’s DateSpan class.
TimeSpan: Riptable’s TimeSpan class.
TimeZone: Riptable’s TimeZone class.

Examples

Create a DateTimeNano from an integer representing the nanoseconds since 00:00:00 UTC on 01-01-1970:

>>> rt.DateTimeNano([1514828730123456000], from_tz="UTC")
DateTimeNano(['20180101 12:45:30.123456000'], to_tz='NYC')

From a datetime string in NYC time:

>>> rt.DateTimeNano(["2018-01-01 12:45:30.123456000"], from_tz="NYC")
DateTimeNano(['20180101 12:45:30.123456000'], to_tz='NYC')

From numpy.datetime64 array (note that NumPy has less precision):

>>> dt = np.array(["2018-11-02 09:30:00.002201", "2018-11-02 09:30:00.004212"], dtype="datetime64[ns]")
>>> rt.DateTimeNano(dt, from_tz="NYC")
DateTimeNano(['20181102 09:30:00.002201000', '20181102 09:30:00.004212000'], to_tz='NYC')

If your datetime strings are nonstandard, specify the format using format with Python strptime codes.

>>> rt.DateTimeNano(["12/31/19 08:05:01", "6/30/19 14:20:35"], format="%m/%d/%y %H:%M:%S", from_tz="NYC")
DateTimeNano(['20191231 08:05:01.000000000', '20190630 14:20:35.000000000'], to_tz='NYC')

Convert Matlab datenums:

>>> rt.DateTimeNano([737426, 738251.75], from_matlab=True, from_tz="NYC")
DateTimeNano(['20190101 00:00:00.000000000', '20210405 18:00:00.000000000'], to_tz='NYC')

Note that if you create a DateTimeNano by adding a Date and a TimeSpan without using the DateTimeNano constructor, from_tz and to_tz will be “GMT”:

>>> d = rt.Date("20230305")
>>> ts = rt.TimeSpan("05:00")
>>> dtn = d + ts
>>> dtn.info()
DateTimeNano(['20230305 05:00:00.000000000'], to_tz='GMT')
Displaying in timezone: GMT
Origin: GMT
Offset: 0 hours

Create a DateTimeNano from a list of Python datetime objects:

>>> from datetime import datetime as dt
>>> pdt = [dt(2018, 7, 2, 14, 30), dt(2019, 6, 8, 8, 30)]
>>> rt.DateTimeNano(pdt)
UserWarning: FastArray contains an unsupported type 'object'.  Problems may occur.
Consider categoricals.
  warnings.warn(warning_string)
DateTimeNano(['20180702 10:30:00.000000000', '20190608 04:30:00.000000000', to_tz='NYC')

If you specify a start_date with an arr of strings, the strings are parsed as TimeSpan objects before start_date is applied. Note the first two examples in arr result in NaN TimeSpans, which are silently treated as zeros:

>>> arr = ["20180205", "20180205 14:30", "14:30"]
>>> rt.DateTimeNano(arr, from_tz="UTC", to_tz="UTC", start_date="20230601")
DateTimeNano(['20230601 00:00:00.000000000', '20230601 00:00:00.000000000', '20230601 14:30:00.000000000'], to_tz='UTC')

GetNanoTime gets the current Unix epoch time:

>>> rt.DateTimeNano([rt.GetNanoTime()], from_tz="UTC")
DateTimeNano(['20230615 18:36:58.378020700'], to_tz='NYC')

property display_length

FrequencyStrings

MetaDefault

MetaVersion = 0

_INVALID_FREQ_ERROR = 'Invalid frequency: {}'

__abs__()[source]

__add__(other, inplace=False)[source]

abstract __and__(other)[source]

__arrow_array__(type=None)[source]

Implementation of the __arrow_array__ protocol for conversion to a pyarrow array.

Parameters:: type (pyarrow.DataType, optional, defaults to None) –
Return type:: pyarrow.Array or pyarrow.ChunkedArray

Notes

https://arrow.apache.org/docs/python/extending_types.html#controlling-conversion-to-pyarrow-array-with-the-arrow-array-protocol

abstract __ceil__()[source]

abstract __complex__()[source]

__eq__(other)[source]: Return self==value.

abstract __float__()[source]

abstract __floor__()[source]

__floordiv__(value)[source]

__ge__(other)[source]: Return self>=value.

__gt__(other)[source]: Return self>value.

__iadd__(other)[source]

abstract __iand__(other)[source]

abstract __ifloordiv__(other)[source]

abstract __ilshift__(other)[source]

abstract __imatmul__(other)[source]

abstract __imod__(other)[source]

abstract __imul__(other)[source]

abstract __int__()[source]

abstract __invert__()[source]

abstract __ior__(other)[source]

abstract __ipow__(other, modulo=None)[source]

abstract __irshift__(other)[source]

__isub__(other)[source]

abstract __itruediv__(other)[source]

abstract __ixor__(other)[source]

__le__(other)[source]: Return self<=value.

abstract __lshift__(other)[source]

__lt__(other)[source]: Return self<value.

abstract __matmul__(other)[source]

__mul__(value)[source]

__ne__(other)[source]: Return self!=value.

abstract __neg__()[source]

abstract __or__(other)[source]

abstract __pos__()[source]

abstract __pow__(other, modulo=None)[source]

__radd__(other)[source]

abstract __rand__(other)[source]

abstract __rdivmod__(other)[source]

__repr__(verbose=False)[source]: Return repr(self).

abstract __rfloordiv__(other)[source]

abstract __rlshift__(other)[source]

abstract __rmatmul__(other)[source]

abstract __rmod__(other)[source]

abstract __rmul__(other)[source]

abstract __ror__(other)[source]

abstract __round__(ndigits=0)[source]

abstract __rpow__(other)[source]

abstract __rrshift__(other)[source]

abstract __rshift__(other)[source]

__rsub__(other)[source]

abstract __rtruediv__(other)[source]

abstract __rxor__(other)[source]

__sub__(other, inplace=False)[source]

__truediv__(value)[source]

abstract __trunc__()[source]

abstract __xor__(other)[source]

classmethod _convert_matlab_days(arr, timezone)[source]

Parameters:

arr (array of matlab datenums (1 is 1-Jan-0000)) –
timezone (TimeZone object from DateTimeNano constructor) –

Converts matlab datenums to an array of int64 containing utc nanoseconds.

_datetimenano_compare_check(funcname, other)[source]

static _from_arrow(arr, zero_copy_only=True, writable=False)[source]

Create a DateTimeNano instance from a “timestamp”-typed pyarrow.Array.

Parameters:

arr (pyarrow.Array or pyarrow.ChunkedArray) – Must be a “timestamp”-typed pyarrow array.
zero_copy_only (bool, optional, defaults to False) –
writable (bool, optional, defaults to False) –

Return type:

DateTimeNano

classmethod _from_meta_data(arrdict, arrflags, meta)[source]

_guard_math_op(value, op_name)[source]

classmethod _load_from_sds_meta_data(name, arr, cols, meta, tups=None)[source]

Note

This will be changed to a private method with a different name as it only pertains to the SDS file format.

Load DateTimeNano from an SDS file as the correct class. Restore formatting if different than default.

Parameters:

name (item's name in the calling container, or the classname 'DateTimeNano' by default) –
arr (underlying integer FastArray in UTC nanoseconds) –
cols (empty list (not used for this class)) –
meta (meta data generated by build_meeta_data() routine) –
tups (empty list (not used for this class)) –
object. (returns reconstructed DateTimeNano) –

_meta_dict(name=None)[source]: Meta dictionary for _build_sds_meta_data, _as_meta_data

classmethod _parse_item_format(itemformat)[source]: Translate a value in the DisplayLength enum into a time format string

classmethod _random(sz, to_tz='NYC', from_tz='NYC', inv=None, start=None, end=None)[source]: Internal routine for random(), random_invalid()

astimezone(tz)[source]

Returns a new DateTimeNano object in a different displayed timezone. The new object holds a reference to the same underlying array.

Parameters:: tz (str) – Abbreviated name of desired timezone. See rt.TimeZone.valid_timezones
Returns:: obj
Return type:: DateTimeNano

Notes

Unlike Python’s datetime.datetime.astimezone(), accepts strings, not timezone objects.

cut_time(buckets, start_time=None, end_time=None, add_pre_bucket=False, add_post_bucket=False, label='left', label_fmt=None, nyc=False)[source]

Analogous to rt.cut() but for times. We ignore the date part and cut based on time of day component only.

Parameters:

buckets (int or rt.TimeSpan or a list of for custom buckets) –
Specify your bucket size or buckets. Supply either an int for the common use case of equally sized minute buckets or a custom list

Acceptable lists formats:
[(h, m, s, ms)] - it’ll assume fields are 0 if length is less than 4
start_time (optional if buckets is explicitly supplied, (h, m) or (h, m, s) or (h, m , s, ms) tuple) – left end point of first bucket, this type may change in future
end_time – see start_time, right end point of last bucket
add_pre_bucket (bool) – add a pre-open bucket or treat as invalid ?
add_post_bucket (bool) – add a after close bucket or treat as invalid ?
label (optional str) – “left”: for left end points “right”: for right end points
label_fmt (optional str) – strftime format for label
nyc (bool, default is False) – convenience shortcut to default to NYC start and end time, ignored if buckets explicitly supplied

Return type:

rt.Categorical

See also

inspired

Examples

TODO - sanitize - add cut_time examples See the version history for structure of older examples.

diff(periods=1)[source]

Return type:: TimeSpan

diff(periods=1)[source]

Calculate the n-th discrete difference.

Parameters:: periods (int, optional) – The number of times values are differenced. If zero, the input is returned as-is.
Returns:: obj
Return type:: TimeSpan

static display_convert_func(utcnano, itemformat)[source]

Convert a utc nanosecond timestamp to a string for display.

Parameters:

utcnano (int) – Timestamp in nanoseconds, a single value from a DateTimeNano array
itemformat (obj:ItemFormat) – Style object retrieved from display callback.

Returns:

Timestamp as string.

Return type:

str

display_item(utcnano)[source]

Convert a utc nanosecond timestamp to a string for array repr.

Parameters:: utcnano (int) – Timestamp in nanoseconds, a single value from a DateTimeNano array
Returns:: Timestamp as string.
Return type:: str

display_query_properties()[source]

Call back for display functions to get the formatting function and style for timestrings. Each instance knows how to format its time strings. The formatter is specified in TIME_FORMATS The length property of item_format stores the index into TIME_FORMATS for the display_convert_func

Returns:

obj (ItemFormat) – See riptable.Utils.rt_display_properties
function – Callback function for formatting the timestring

fill_invalid(shape=None, dtype=None, inplace=True)[source]

Replace all values of the input FastArray with an invalid value.

The invalid value used is determined by the input array’s dtype or a user-specified dtype.

Warning: By default, this operation is in place.

Parameters:

shape (int or sequence of int, optional) – Shape of the new array, for example: (2, 3) or 2. Note that although multi-dimensional arrays are technically supported by Riptable, you may get unexpected results when working with them.
dtype (str, optional) – The desired dtype for the returned array.
inplace (bool, default True) – If True (the default), modify original data. If False, return a copy of the array.

Returns:

If inplace=False, a copy of the input FastArray is returned that has all values replaced with an invalid value. Otherwise, nothing is returned.

Return type:

FastArray, optional

See also

FastArray.inv: Return the invalid value for the input array’s dtype.
FastArray.copy_invalid: Return a copy of a FastArray filled with the invalid value for the array’s dtype.

Examples

Replace an integer array’s values with the invalid value for the array’s dtype. By default, the returned array is the same size and dtype as the input array, and the operation is performed in place:

>>> a = rt.FA([1, 2, 3, 4, 5])
>>> a
FastArray([1, 2, 3, 4, 5])
>>> a.fill_invalid()
>>> a
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Replace a floating-point array’s values with the invalid value for the int32 dtype:

>>> a2 = rt.FA([0., 1., 2., 3., 4.])
>>> a2
FastArray([0., 1., 2., 3., 4.])
>>> a2.fill_invalid(dtype="int32", inplace=False)
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Specify the size and dtype of the output array:

>>> a3 = rt.FA(["AMZN", "IBM", "MSFT", "AAPL"])
>>> a3
FastArray([b'AMZN', b'IBM', b'MSFT', b'AAPL'], dtype='|S4')
>>> a3.fill_invalid(2, dtype="bool", inplace=False)
FastArray([False, False])

static format_nano_time(utcnano, itemformat)[source]

Convert a utc nanosecond timestamp to a string for display.

Parameters:

utcnano (int) – Timestamp in nanoseconds, a single value from a DateTimeNano array
itemformat (obj:ItemFormat) – Style object retrieved from display callback.

Returns:

Timestamp as string.

Return type:

str

Notes

Uses Python’s datetime module for final string conversion.

get_classname()[source]

Return object’s class name for array repr.

Returns:: obj – Object’s class name.
Return type:: str

get_scalar(scalarval)[source]

classmethod hstack(dtlist)[source]

Performs an hstack on a list of DateTimeNano objects. All items in list must have their display set to the same timezone.

Parameters:: dtlist (obj:list of obj:DateTimeNano) – DateTimeNano objects to be stacked.

Examples

>>> dtn1 = DateTimeNano(['2019-01-01', '2019-01-02'], from_tz='NYC')
>>> dtn2 = DateTimeNano(['2019-01-03', '2019-01-04'], from_tz='NYC')
>>> DateTimeNano.hstack([dtn1, dtn2])
DateTimeNano([20190101 00:00:00.000000000, 20190102 00:00:00.000000000, 20190103 00:00:00.000000000, 20190104 00:00:00.000000000])

Returns:: obj
Return type:: DateTimeNano

info()[source]

Returns:: Verbose array repr with timezone information.
Return type:: str

isfinite()[source]

Return a boolean array that’s True for each DateTimeNano element that’s not a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int64 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each non-NaN element, False otherwise.
Return type:: FastArray

See also

DateTimeNano.isnan, Date.isnan, Date.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17',
...                        '20210713 02:44:19'], from_tz = 'NYC')
>>> dtn[0] = 0
>>> dtn[1] = dtn.inv
>>> dtn
DateTimeNano(['Inv', 'Inv', '20210712 22:44:19.000000000'], to_tz='NYC')
>>> dtn.isfinite()
FastArray([False, False,  True])

isnan()[source]

Return a boolean array that’s True for each DateTimeNano element that’s a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int64 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each NaN element, False otherwise.
Return type:: FastArray

See also

DateTimeNano.isnotnan, Date.isnan, Date.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17',
...                        '20210713 02:44:19'], from_tz = 'NYC')
>>> dtn[0] = 0
>>> dtn[1] = dtn.inv
>>> dtn
DateTimeNano(['Inv', 'Inv', '20210712 22:44:19.000000000'], to_tz='NYC')
>>> dtn.isnan()
FastArray([ True,  True, False])

isnotfinite()[source]

Return a boolean array that’s True for each DateTimeNano element that’s a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int64 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each NaN element, False otherwise.
Return type:: FastArray

See also

DateTimeNano.isnotnan, Date.isnan, Date.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17',
...                        '20210713 02:44:19'], from_tz = 'NYC')
>>> dtn[0] = 0
>>> dtn[1] = dtn.inv
>>> dtn
DateTimeNano(['Inv', 'Inv', '20210712 22:44:19.000000000'], to_tz='NYC')
>>> dtn.isnotfinite()
FastArray([ True,  True, False])

isnotnan()[source]

Return a boolean array that’s True for each DateTimeNano element that’s not a NaN (Not a Number), False otherwise.

Both the DateTime NaN (0) and Riptable’s int64 sentinel value are considered to be NaN.

Returns:: A FastArray of booleans that’s True for each non-NaN element, False otherwise.
Return type:: FastArray

See also

DateTimeNano.isnan, Date.isnan, Date.isnotnan, riptable.isnan, riptable.isnotnan, riptable.isnanorzero, FastArray.isnan, FastArray.isnotnan, FastArray.notna, FastArray.isnanorzero, Categorical.isnan, Categorical.isnotnan, Categorical.notna

Dataset.mask_or_isnan: Return a boolean array that’s True for each Dataset row that contains at least one NaN.
Dataset.mask_and_isnan: Return a boolean array that’s True for each all-NaN Dataset row.

Notes

Riptable currently uses 0 for the DateTime NaN value. This constant is held in the DateTimeBase class.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17',
...                        '20210713 02:44:19'], from_tz = 'NYC')
>>> dtn[0] = 0
>>> dtn[1] = dtn.inv
>>> dtn
DateTimeNano(['Inv', 'Inv', '20210712 22:44:19.000000000'], to_tz='NYC')
>>> dtn.isnotnan()
FastArray([False, False,  True])

max(**kwargs)[source]

The latest DateTimeNano in an array.

Returns:: A DateTimeNano array containing the latest DateTimeNano from the input array.
Return type:: DateTimeNano

See also

DateTimeNano.min, Date.min, Date.max, DateSpan.min, Datespan.max

Notes

This returns an array, not a scalar. However, broadcasting rules will apply to operations with it.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17'],
...                        from_tz='NYC', to_tz='NYC')
>>> dtn.max()
DateTimeNano(['20210101 09:31:15.000000000'], to_tz='NYC')

min(**kwargs)[source]

The earliest DateTimeNano in an array.

Note that until a reported bug is fixed, this method is not NaN-aware.

Returns:: A DateTimeNano array containing the earliest DateTimeNano from the input array.
Return type:: DateTimeNano

See also

DateTimeNano.max, Date.min, Date.max, DateSpan.min, Datespan.max

Notes

This returns an array, not a scalar. However, broadcasting rules will apply to operations with it.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17'],
...                        from_tz='NYC', to_tz='NYC')
>>> dtn.min()
DateTimeNano(['20210101 09:31:15.000000000'], to_tz='NYC')

classmethod newclassfrominstance(instance, origin)[source]: Restore timezone/length info.

classmethod random(sz, to_tz='NYC', from_tz='NYC', inv=None, start=None, end=None)[source]

Return an array of randomly generated DateTimeNano values.

If start and end are not provided, years range from 1971 to 2020.

Parameters:

sz (int) – The length of the generated array.
to_tz (str, default 'NYC') – The timezone for display. For valid timezone options, see TimeZone.valid_timezones.
from_tz (str, default 'NYC') – The timezone of origin. For valid timezone options, see TimeZone.valid_timezones.
inv (array of bool, optional) – Where True, an invalid DateTimeNano is in the returned array.
start (int, optional) – The start year for the range. If no end year is provided, all times are within the start year.
end (int, optional) – The end year for the range. Used only if start is provided.

Returns:

A DateTimeNano with randomly generated values.

Return type:

DateTimeNano

See also

DateTimeNano.random_invalid: Return a randomly generated DateTimeNano array with randomly placed invalid values.
Date.range: Return a Date object of dates within a given interval, spaced by step.
riptable.arange: Return an array of evenly spaced values within a given interval.

Examples

>>> rt.DateTimeNano.random(3)
DateTimeNano([19980912 15:31:08.025189457, 19931121 15:48:32.855425859, 19930915 14:58:31.376750294])  # random

If start is provided but end is not, all times are within the start year:

>>> rt.DateTimeNano.random(3, start=2015)
DateTimeNano(['20151011 12:15:45.588049363', '20150207 14:54:33.649991888', '20150131 18:58:13.543792210'], to_tz='NYC')  # random

With an inv mask. Where True, an invalid DateTimeNano is in the returned array:

>>> i = rt.FastArray([True, False, True])
>>> rt.DateTimeNano.random(3, inv=i)
DateTimeNano(['Inv', '19930915 02:39:29.621051630', 'Inv'], to_tz='NYC')

classmethod random_invalid(sz, to_tz='NYC', from_tz='NYC', start=None, end=None)[source]

Return a randomly generated DateTimeNano object with randomly placed invalid values.

This method is the same as DateTimeNano.random, except that a mask is randomly generated to place the invalid values.

If start and end are not provided, years for valid DateTimeNano values range from 1971 to 2020.

Parameters:

sz (int) – The length of the generated array.
to_tz (str, default 'NYC') – The timezone for display. For valid timezone options, see TimeZone.valid_timezones.
from_tz (str, default 'NYC') – The timezone of origin. For valid timezone options, see TimeZone.valid_timezones.
start (int, optional) – The start year for the range. If no end year is provided, all times are within the start year.
end (int, optional) – The end year for the range. Used only if start is provided.

Returns:

A DateTimeNano with randomly placed invalid values.

Return type:

DateTimeNano

See also

DateTimeNano.random: Return an array of randomly generated DateTimeNano values.
Date.range: Return a Date object of dates within a given interval, spaced by step.
riptable.arange: Return an array of evenly spaced values within a specified interval.

Examples

>>> rt.DateTimeNano.random_invalid(3)
DateTimeNano(['Inv', '19830405 15:24:01.815771855', 'Inv'], to_tz='NYC')  # random

resample(rule, dropna=False)[source]

Convenience method for frequency conversion and resampling of DateTimeNano arrays.

Parameters:

rule (string) – The offset string or object representing target conversion. Can also begin the string with a number e.g. ‘3H’ Currently supported: H hour T, min minute S second L, ms millisecond U, us microsecond N, ns nanosecond
dropna (bool, default False) – If True, returns a DateTimeNano the same length as caller, with all values rounded to specified frequency. If False, returns a DateTimeNano range from caller’s min to max with values at every specified frequency.

Examples

>>> dtn = DateTimeNano(['2015-04-15 14:26:54.735321368',
                        '2015-04-20 07:30:00.858219615',
                        '2015-04-23 13:15:24.526871083',
                        '2015-04-21 02:25:11.768548100',
                        '2015-04-24 07:47:54.737776979',
                        '2015-04-10 23:59:59.376589955'],
                             from_tz='UTC', to_tz='UTC')
>>> dtn.resample('L', dropna=True)
DateTimeNano(['20150415 14:26:54.735000000', '20150420 07:30:00.858000000', '20150423 13:15:24.526000000', '20150421 02:25:11.768000000', '20150424 07:47:54.737000000', '20150410 23:59:59.376000000'], to_tz='UTC')

>>> dtn = DateTimeNano(['20190417 17:47:00.000001',
                        '20190417 17:47:00.000003',
                        '20190417 17:47:00.000005'],
                                      from_tz='NYC')
>>> dtn.resample('1us')
DateTimeNano(['20190417 17:47:00.000001000', '20190417 17:47:00.000002000', '20190417 17:47:00.000003000', '20190417 17:47:00.000004000', '20190417 17:47:00.000005000'], to_tz='NYC')

Returns:: dtn
Return type:: DateTimeNano

set_timezone(tz)[source]

Changes the timezone that the times are displayed in. Different lookup array will be used for daylight savings fixups. Does not modify the underlying array.

Parameters:: tz (str) – Abbreviated name of desired timezone. See rt.TimeZone.valid_timezones

Examples

Normal: >>> dtn = DateTimeNano([‘2019-01-07 10:36’], from_tz=’NYC’, to_tz=’NYC’) >>> dtn DateTimeNano([20190107 10:36:00.000000000]) >>> dtn.set_timezone(‘DUBLIN’) >>> dtn DateTimeNano([20190107 15:36:00.000000000])

NYC is in daylight savings time, Dublin is not: >>> dtn = DateTimeNano([‘2019-03-15 10:36’], from_tz=’NYC’, to_tz=’NYC’) >>> dtn DateTimeNano([20190315 10:36:00.000000000]) >>> dtn.set_timezone(‘DUBLIN’) >>> dtn DateTimeNano([20190315 14:36:00.000000000])

shift(periods=1)[source]

Modeled on pandas.shift. Values in the array will be shifted to the right if periods is positive, to the left if negative. Spaces at either end will be filled with invalid. If abs(periods) >= the length of the array, the result will be full of invalid.

Parameters:: periods (int) – Number of periods to move, can be positive or negative
Returns:: obj
Return type:: DateTimeNano

strftime(format, dtype='O')[source]

Convert each DateTimeNano element to a formatted string representation.

Parameters:

format (str) – One or more format codes supported by the datetime.datetime.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
dtype ({"O", "S", "U"}, default "O") –
The data type of the returned array:
- ”O”: object string
- ”S”: byte string
- ”U”: unicode string

Returns:

An ndarray of strings.

Return type:

ndarray

Notes

This routine has not been sped up yet. It also raises an error on NaNs.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17'], from_tz='NYC')
>>> dtn
DateTimeNano(['20210101 09:31:15.000000000', '20210519 05:21:17.000000000'], to_tz='NYC')
>>> dtn.strftime('%c')
array(['Fri Jan  1 09:31:15 2021', 'Wed May 19 05:21:17 2021'], dtype=object)

to_arrow(type=None, *, preserve_fixed_bytes=False, empty_strings_to_null=True)[source]

Convert this DateTimeNano to a pyarrow.Array.

Parameters:

type (pyarrow.DataType, optional, defaults to None) – Unused.
preserve_fixed_bytes (bool, optional, defaults to False) – Unused.
empty_strings_to_null (bool, optional, defaults To True) – Unused.

Return type:

pyarrow.Array or pyarrow.ChunkedArray

to_iso()[source]

Generates a FastArray of ISO-8601 timestamp bytestrings. The string will match the time +/- timezone offset displayed in the output of the DateTimeNano object.

Examples

>>> dtn = DateTimeNano(['2019-01-22 12:34'],from_tz='NYC')
>>> dtn
DateTimeNano([20190122 12:34:00.000000000])
>>> dtn.to_iso()
FastArray([b'2019-01-22T12:34:00.000000000'], dtype='|S48')

>>> dtn = DateTimeNano(['2019-01-22'],from_tz='GMT',to_tz='NYC')
>>> dtn
DateTimeNano([20190121 19:00:00.000000000])
>>> dtn.to_iso()
FastArray([b'2019-01-21T19:00:00.000000000'], dtype='|S48')

Returns:: obj
Return type:: FastArray

class riptable.rt_datetime.DateTimeNanoScalar(**kwargs)[source]

Bases: numpy.int64, DateTimeCommon, TimeStampBase

Derived from np.int64 NOTE: np.int64 is a SLOT wrapper and does not have a __dict__ Number of nanoseconds since unix epoch 1970 in UTC

property _fa

property _np

__slots__ = ('_display_length', '_timezone')

__add__(value)[source]

__repr__()[source]: Return repr(self).

__str__()[source]: Return str(self).

__sub__(value)[source]

get_classname()[source]

get_item_format()[source]

isfinite()[source]

isnan()[source]

isnotfinite()[source]

isnotnan()[source]

repeat(repeats, axis=None)[source]

strftime(format)[source]

Convert a DateTimeNanoScalar to a formatted string representation.

Parameters:: format (str) – One or more format codes supported by the datetime.datetime.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
Returns:: A string representation of the reformatted DateTimeNanoScalar.
Return type:: str

Notes

This routine has not been sped up yet. It also raises an error on NaNs.

Examples

>>> dtn = rt.DateTimeNano(['20210101 09:31:15', '20210519 05:21:17'], from_tz='NYC')
>>> dtn
DateTimeNano(['20210101 09:31:15.000000000', '20210519 05:21:17.000000000'], to_tz='NYC')
>>> dtn[0].strftime('%c')
'Fri Jan  1 09:31:15 2021'

tile(repeats)[source]

class riptable.rt_datetime.TimeSpan(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)[source]

Bases: TimeSpanBase, DateTimeBase

Array of time delta in nanoseconds, held in float64.

Parameters:

values (numeric or string array or scalar) – If string, interpreted as HH:MM:SS.ffffff ( seconds/second fractions optional ) If numeric, interpreted as nanoseconds, unless unit provided. single number or array / list of numbers (unless unit is specified, will assume nanoseconds)
unit (str, optional, default 'ns') – Precision of data in the constructor. All will be converted to nanoseconds. Valid units: ‘Y’, ‘W’, ‘D’, ‘h’, ‘m’, ‘s’, ‘ms’, ‘us’, ‘ns’

Examples

From single string: >>> dts = TimeSpan(‘12:34’) >>> dts TimeSpan([12:34:00.000000000])

From milliseconds since midnight: >>> dts = TimeSpan(FA([34500000., 36500000., 38500000.,]), unit=’ms’) >>> dts TimeSpan([09:35:00.000000000, 10:08:20.000000000, 10:41:40.000000000])

From the result of DateTimeNano subtraction: >>> dtn1 = DateTimeNano([‘2018-01-01 09:35:00’], from_tz=’NYC’) >>> dtn2 = DateTimeNano([‘2018-01-01 07:15:00’], from_tz=’NYC’) >>> dtn1 - dtn2 TimeSpan([02:20:00.000000000])

Certain DateTimeNano properties can return a TimeSpan: >>> dtn = DateTimeNano([‘2018-01-01 09:35:00’], from_tz=’NYC’) >>> dtn.hour_span TimeSpan([09:35:00.000000000])

Can be added to DateTimeNano objects: >>> dtn = DateTimeNano([‘2018-01-01 09:35:00’], from_tz=’NYC’) >>> ts = TimeSpan(FA([8400000000000.0])) >>> dtn + ts DateTimeNano([20180101 11:55:00.000000000])

Can be multiplied / divided by scalars: >>> ts = TimeSpan(FA([8400000000000.0])) >>> ts TimeSpan([02:20:00.000000000]) >>> ts / 2 TimeSpan([01:10:00.000000000]) >>> ts * 5.6 TimeSpan([13:04:00.000000000])

__arrow_array__(type=None)[source]

Implementation of the __arrow_array__ protocol for conversion to a pyarrow array.

Parameters:: type (pyarrow.DataType, optional, defaults to None) –
Return type:: pyarrow.Array or pyarrow.ChunkedArray

Notes

https://arrow.apache.org/docs/python/extending_types.html#controlling-conversion-to-pyarrow-array-with-the-arrow-array-protocol

static _from_arrow(arr, zero_copy_only=True, writable=False)[source]

Create a TimeSpan instance from a “duration”-typed pyarrow.Array.

Parameters:

arr (pyarrow.Array or pyarrow.ChunkedArray) – Must be a “duration”-typed pyarrow array.
zero_copy_only (bool, optional, defaults to False) –
writable (bool, optional, defaults to False) –

Return type:

TimeSpan

classmethod _from_meta_data(arrdict, arrflags, meta)[source]

classmethod _load_from_sds_meta_data(name, arr, cols, meta, tups=None)[source]: Load DateTimeNano from an SDS file as the correct class. Restore formatting if different than default.

_meta_dict(name=None)[source]

fill_invalid(shape=None, dtype=None, inplace=True)[source]

Replace all values of the input FastArray with an invalid value.

The invalid value used is determined by the input array’s dtype or a user-specified dtype.

Warning: By default, this operation is in place.

Parameters:

shape (int or sequence of int, optional) – Shape of the new array, for example: (2, 3) or 2. Note that although multi-dimensional arrays are technically supported by Riptable, you may get unexpected results when working with them.
dtype (str, optional) – The desired dtype for the returned array.
inplace (bool, default True) – If True (the default), modify original data. If False, return a copy of the array.

Returns:

If inplace=False, a copy of the input FastArray is returned that has all values replaced with an invalid value. Otherwise, nothing is returned.

Return type:

FastArray, optional

See also

FastArray.inv: Return the invalid value for the input array’s dtype.
FastArray.copy_invalid: Return a copy of a FastArray filled with the invalid value for the array’s dtype.

Examples

Replace an integer array’s values with the invalid value for the array’s dtype. By default, the returned array is the same size and dtype as the input array, and the operation is performed in place:

>>> a = rt.FA([1, 2, 3, 4, 5])
>>> a
FastArray([1, 2, 3, 4, 5])
>>> a.fill_invalid()
>>> a
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Replace a floating-point array’s values with the invalid value for the int32 dtype:

>>> a2 = rt.FA([0., 1., 2., 3., 4.])
>>> a2
FastArray([0., 1., 2., 3., 4.])
>>> a2.fill_invalid(dtype="int32", inplace=False)
FastArray([-2147483648, -2147483648, -2147483648, -2147483648,
           -2147483648])

Specify the size and dtype of the output array:

>>> a3 = rt.FA(["AMZN", "IBM", "MSFT", "AAPL"])
>>> a3
FastArray([b'AMZN', b'IBM', b'MSFT', b'AAPL'], dtype='|S4')
>>> a3.fill_invalid(2, dtype="bool", inplace=False)
FastArray([False, False])

get_classname()[source]

get_scalar(scalarval)[source]

classmethod hstack(tspans)[source]: TODO: maybe add type checking? This is a very simple class, rewrap the hstack result in class.

classmethod newclassfrominstance(instance, origin)[source]

strftime(format, dtype='U')[source]

Convert each TimeSpan element to a formatted string representation.

Parameters:

format (str) – One or more format codes supported by the datetime.datetime.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
dtype ({"U", "S", "O"}, default "U") –
The data type of the returned array:
- ”U”: unicode string
- ”S”: byte string
- ”O”: object string

Returns:

An ndarray of strings.

Return type:

ndarray

Notes

This routine has not been sped up yet. It also raises an error on NaNs.

Examples

>>> ts = rt.TimeSpan(['09:00', '10:45', '02:30'])
>>> ts
TimeSpan(['09:00:00.000000000', '10:45:00.000000000', '02:30:00.000000000'])
>>> ts.strftime('%X')
array(['09:00:00', '10:45:00', '02:30:00'], dtype='<U8')

to_arrow(type=None, *, preserve_fixed_bytes=False, empty_strings_to_null=True)[source]

Convert this TimeSpan to a pyarrow.Array.

Parameters:

type (pyarrow.DataType, optional, defaults to None) – Unused.
preserve_fixed_bytes (bool, optional, defaults to False) – Unused.
empty_strings_to_null (bool, optional, defaults To True) – Unused.

Return type:

pyarrow.Array or pyarrow.ChunkedArray

class riptable.rt_datetime.TimeSpanScalar(**kwargs)[source]

Bases: numpy.float64, TimeSpanBase

Derived from np.float64 ******** not implemented Holds single float values for TimeSpan arrays. These will be returned from operations that currently return a TimeSpan of a single item.

property _fa

property _np

__slots__ = '_display_length'

__abs__()[source]: abs(self)

__add__(value)[source]: Return self+value.

__eq__(other)[source]: Return self==value.

__floordiv__(value)[source]: Return self//value.

__mul__(value)[source]: Return self*value.

__neg__()[source]: -self

__pos__()[source]: +self

__radd__(value)[source]: Return value+self.

__repr__()[source]: Return repr(self).

__rmul__(value)[source]: Return value*self.

__rsub__(value)[source]: Return value-self.

__str__()[source]: Return str(self).

__sub__(value)[source]: Return self-value.

__truediv__(value)[source]: Return self/value.

abs()[source]

get_classname()[source]

get_item_format()[source]

isfinite()[source]

isnan()[source]

isnotfinite()[source]

isnotnan()[source]

repeat(repeats, axis=None)[source]

strftime(format)[source]

Convert a TimeSpanScalar to a formatted string representation.

Parameters:: format (str) – One or more format codes supported by the datetime.datetime.strftime() function of the standard Python distribution. For codes, see strftime() and strptime() Behavior.
Returns:: A string representation of the reformatted TimeSpanScalar.
Return type:: str

Notes

This routine has not been sped up yet. It also raises an error on NaNs.

Examples

>>> ts = rt.TimeSpan(['09:00', '10:45', '02:30'])
>>> ts
TimeSpan(['09:00:00.000000000', '10:45:00.000000000', '02:30:00.000000000'])
>>> ts[0].strftime('%X')
'09:00:00'

tile(repeats)[source]

riptable.rt_datetime.DateTimeUTC(arr, to_tz='NYC', from_matlab=False, format=None, start_date=None, gmt=None)[source]: Forces DateTimeNano from_tz keyword to ‘UTC’. For more see DateTimeNano.

riptable.rt_datetime.datestring_to_nano(datestring, time=None, from_tz=None, to_tz='NYC')[source]

Converts date string to DateTimeNano object (default midnight). By default, the timestrings are assumed to be in Eastern Time. If they are already in UTC time, set gmt=True.

Parameters:

datestring (array of datestrings in format YYYY-MM-DD or YYYYMMDD (bytestrings/unicode supported)) –
time (a single string or array of strings in the format HH:MM:SS.ffffff (bytestrings/unicode supported)) –
from_tz (a string for the timezone of origin: 'NYC', 'GMT', 'DUBLIN', etc.) –
to_tz (a string for the timezone that the time will be displayed in) –
DateTimenano (returns) –
Also (See) –

Examples

Date only:

>>> dates = FA(['2018-01-01', '2018-01-02', '2018-01-03'])
>>> datestring_to_nano(dates, from_tz='NYC')
DateTimeNano([20180101 00:00:00.000000000, 20180102 00:00:00.000000000, 20180103 00:00:00.000000000])

With time:

>>> dates = FA(['2018-01-01', '2018-01-02', '2018-01-03'])
>>> datestring_to_nano(dates, time='9:30:00', from_tz='NYC')
DateTimeNano([20180101 09:30:00.000000000, 20180102 09:30:00.000000000, 20180103 09:30:00.000000000])

riptable.rt_datetime.datetimestring_to_nano(dtstring, from_tz=None, to_tz='NYC')[source]

Converts datetime string to DateTimeNano object. By default, the timestrings are assumed to be in Eastern Time. If they are already in UTC time, set gmt=True.

Parameters:

dtstring (array of timestrings in format YYYY-MM-DD HH:MM:SS, YYYYMMDD HH:MM:SS.ffffff, etc. (bytestrings/unicode supported)) –
from_tz (a string for the timezone of origin: 'NYC', 'GMT', 'DUBLIN', etc.) –
to_tz (a string for the timezone that the time will be displayed in) –
DateTimeNano (returns) –
Also (See) –

Examples

>>> dts = FA(['2012-12-12 12:34:56.001002', '20130303 1:14:15', '2008-07-06 15:14:13'])
>>> datetimestring_to_nano(dts, from_tz='NYC')
DateTimeNano([20121212 12:34:56.001002000, 20130303 01:14:15.000000000, 20080706 15:14:13.000000000])

riptable.rt_datetime.parse_epoch(etime, to_tz='NYC')[source]

Days since epoch and milliseconds since midnight from nanosecond timestamps.

Parameters:

etime (array-like) – UTC nanoseconds.
to_tz (str, default 'NYC') – TimeZone short string - see riptable.rt_timezone. This routine didn’t used to take a timezone, so it defaults to the previous setting.
loader. (Used in the phonyx data) –

Returns:

days (array (int32)) – Days since epoch.
millis (array (float64)) – Milliseconds since midnight.

riptable.rt_datetime.strptime_to_nano(dtstrings, format, from_tz=None, to_tz='NYC')[source]

Converts datetime string to DateTimeNano object with user-specified format.

Parameters:

dtstrings (array of timestrings) –
format (timestring format) –
Currently supports the following escape codes:

Date
- %y Year without century as zero-padded decimal number.
- %Y Year with century as decimal number.
- %m Month as a decimal number (with or without zero-padding).
- %B Full month name: [‘January’, ‘February’, ‘March’, ‘April’, ‘May’, ‘June’, ‘July’, ‘August’, ‘September’, ‘October’, ‘November’, ‘December’]
- %b Abbreviated month name: [‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’, ‘Jul’, ‘Aug’, ‘Sep’, ‘Oct’, ‘Nov’, ‘Dec’]
- %d Day of the month as a decimal number (with or without zero-padding).
Time
- %H Hour (24-hour clock) as a decimal number (with or without zero-padding). (Note: if a %p formatter is present, this will be interpretted as a 12-hour clock hour)
- %I Hour (12-hour clock) as a decimal number (with or without zero-padding). (Note: unlike %H, must be 1-12)
- %p Locale’s equivalent of either AM or PM.
- %M Minute as a decimal number (with or without zero-padding).
- %S Second as a decimal number (with or without zero-padding).
from_tz (str) – The timezone of origin: ‘NYC’, ‘GMT’, ‘DUBLIN’, etc.
to_tz (str) – The timezone that the time will be displayed in.

Notes

Works best with timestrings that include a date:

If no year is present in the string, an invalid time will be returned for all values.
If no form of year/month/day is present, values will yield a time in 1970.

Consider using timestring_to_nano(), which also will accept one datestring for all times.

If the timestring ends in a ‘.’, the following numbers will be parsed as a second fraction. This happens automatically, no escape character is required in the format string.

If no time escape characters are present, will return midnight at all date values. If formatted correctly, consider using datestring_to_nano().

Examples

Date, with/without padding:

>>> dt = FastArray(['02/01/1992', '2/1/1992'])
>>> fmt = '%m/%d/%Y'
>>> strptime_to_nano(dt, fmt, from_tz='NYC')
DateTimeNano([19920201 00:00:00.000000000, 19920201 00:00:00.000000000])

Date + 24-hour clock:

>>> dt = FastArray(['02/01/1992 7:48:30', '2/1/1992 19:48:30'])
>>> fmt = '%m/%d/%Y %H:%M:%S'
>>> strptime_to_nano(dt, fmt, from_tz='NYC')
DateTimeNano([19920201 07:48:30.000000000, 19920201 19:48:30.000000000])

Date + 12-hour clock + am/pm:

>>> dt = FastArray(['02/01/1992 7:48:30 AM', '2/1/1992 7:48:30 PM'])
>>> fmt = '%m/%d/%Y %I:%M:%S %p'
>>> strptime_to_nano(dt, fmt, from_tz='NYC')
DateTimeNano([19920201 07:48:30.000000000, 19920201 19:48:30.000000000])

Date + time + second fraction:

>>> dt = FastArray(['02/01/1992 7:48:30.123456789', '2/1/1992 15:48:30.000000006'])
>>> fmt = '%m/%d/%Y %H:%M:%S'
>>> strptime_to_nano(dt, fmt, from_tz='NYC')
DateTimeNano([19920201 07:48:30.123456789, 19920201 15:48:30.000000006])

riptable.rt_datetime.timestring_to_nano(timestring, date=None, from_tz=None, to_tz='NYC')[source]

Converts timestring to TimeSpan or DateTimeNano object. By default, the timestrings are assumed to be in Eastern Time. If they are already in UTC time, set gmt=True. If a date is specified, a DateTimeNano object will be returned. If a date is not specified, a TimeSpan will be returned.

Parameters:

timestring (array of timestrings in format HH:MM:SS, H:MM:SS, HH:MM:SS.ffffff (bytestrings/unicode supported)) –
date (a single string or array of date strings in format YYYY-MM-DD (bytestrings/unicode supported)) –
from_tz (a string for the timezone of origin: 'NYC', 'GMT', 'DUBLIN', etc.) –
to_tz (a string for the timezone that the time will be displayed in) –
DateTimeNano (returns TimeSpan or) –
Also (See) –

Examples

Return TimeSpan:

>>> ts = FA(['1:23:45', '12:34:56.000100', '       14:00:00'])
>>> timestring_to_nano(ts, from_tz='NYC')
TimeSpan([01:23:45.000000000, 12:34:56.000100000, 14:00:00.000000000])

With single date string:

>>> ts = FA(['1:23:45', '12:34:56', '23:22:21'])
>>> timestring_to_nano(ts, date='2018-02-01', from_tz='NYC')
DateTimeNano([20180201 01:23:45.000000000, 20180201 12:34:56.000000000, 20180201 23:22:21.000000000])

Multiple date strings:

>>> ts = FA(['1:23:45', '12:34:56', '23:22:21'])
>>> dts = FA(['2018-02-01', '2018-02-07', '2018-05-12'])
>>> timestring_to_nano(ts, date=dts, from_tz='NYC')
DateTimeNano([20180201 01:23:45.000000000, 20180207 12:34:56.000000000, 20180512 23:22:21.000000000])

riptable.rt_datetime

Classes

Functions

`riptable.rt_datetime`