viscid.npdatetime module

This is a shim to use numpy datetime64 and timedelta64 types

Times must be given in ISO 8601 format as per numpy >= 1.7.

All arguments as strings are assumed to be ZULU (UTC) time. This keeps the interface the same for numpy versions both before and after 1.11 when datetime64 became timezone agnostic.

Note

There is some trickery here. For numpy versions prior to 1.11, this module will force ZULU (UTC) time. Note that when these datetimes are printed, numpy will display the local time. This will not be a problem for matplotlib plots if arr.astype(datetime.datetime) is used. This is because python’s datetime objects are timezone agnostic, so matplotlib won’t know a thing about your local TZ.

See also

Information about the time span of each time unit is available at [1].

References

[1]	http://docs.scipy.org/doc/numpy/reference/arrays.datetime.html#datetime-units

This module is completely orthogonal to Viscid, so that it can be ripped out and used more generally. Please note that Viscid is MIT licensed, which requires attribution.

The MIT License (MIT) Copyright (c) 2017 Kristofor Maynard

exception viscid.npdatetime.PrecisionError

Bases: exceptions.ArithmeticError

Used if conversion to a time unit truncates value to 0

viscid.npdatetime.as_datetime64(time, unit=None)

Convert to a Numpy datetime64 scalar or array

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}

Returns:

np.datetime64[unit] or array with dtype np.datetime64[unit]

viscid.npdatetime.as_timedelta64(time, unit=None)

Convert to a timedelta64 type

Parameters:

• time (timedelta-like) – an int/float/string/… to convert
• unit (None) – This is the unit of the input, the result will be the most coarse unit that can store the time

viscid.npdatetime.as_datetime(time, unit=None)

Convert time to a Numpy ndarray of datetime.datetime objects

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}

Returns:

np.ndarray of native datetime.datetime objects (dtype = object)

viscid.npdatetime.as_timedelta(time, unit=None, allow0=True)

Convert time to a Numpy ndarray of datetime.datetime objects

Note

Python timedelta objects are accurate up to microseconds

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}
• allow0 (bool) – If False, then raise PrecisionError if a value has been rounded to 0

Returns:

np.ndarray of native datetime.datetime objects (dtype = object)

viscid.npdatetime.to_datetime64(time, unit=None)

Convert to a Numpy datetime64 scalar or array

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}

Returns:

np.datetime64[unit] or array with dtype np.datetime64[unit]

viscid.npdatetime.to_timedelta64(time, unit=None)

Convert to a timedelta64 type

Parameters:

• time (timedelta-like) – an int/float/string/… to convert
• unit (None) – This is the unit of the input, the result will be the most coarse unit that can store the time

viscid.npdatetime.to_datetime(time, unit=None)

Convert time to a Numpy ndarray of datetime.datetime objects

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}

Returns:

np.ndarray of native datetime.datetime objects (dtype = object)

viscid.npdatetime.to_timedelta(time, unit=None, allow0=True)

Convert time to a Numpy ndarray of datetime.datetime objects

Note

Python timedelta objects are accurate up to microseconds

Parameters:

• time – some python datetime or string in ISO 8601 format, could also be a sequence of these to return a Numpy ndarray
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}
• allow0 (bool) – If False, then raise PrecisionError if a value has been rounded to 0

Returns:

np.ndarray of native datetime.datetime objects (dtype = object)

viscid.npdatetime.as_isotime(time)

Try to convert times in string format to ISO 8601

Raises:

• TypeError – Elements are not strings
• ValueError – numpy.datetime64(time) fails

viscid.npdatetime.to_isotime(time)

Try to convert times in string format to ISO 8601

Raises:

• TypeError – Elements are not strings
• ValueError – numpy.datetime64(time) fails

viscid.npdatetime.format_time(time, fmt='.02f', basetime=None)

Format time as a string

Parameters:

• t (float) – time
• style (str) –

  for this method, can be:

  -----------------------   -------   ----------------------------
  style                     time      string
  -----------------------   -------   ----------------------------
  'hms'                     90015.0   "25:00:15"
  'hmss'                    90015.0   "25:00:15 (090015)"
  'dhms'                      900.0   "0 days 00:15:00"
  'dhmss'                     900.0   "0 days 00:15:00 (000900)"
  '.02f'                      900.0   '900.00'
  '%Y-%m-%d %H:%M:%S'         900.0   '1970-01-01 00:15:00'
  '%Y-%m-%d %H:%M:%S.%1f'     900.0   '1970-01-01 00:15:00.0'
  -----------------------   -------   ----------------------------
  

  Note that the last one can involve any formatting strings understood by datetime.strftime

• basetime (np.datetime64) – if formatting just number of seconds from something like “.02f”, then use this time as 0 seconds

Returns:

str

viscid.npdatetime.format_datetime(time, fmt='%Y-%m-%d %H:%M:%S.%.02f')

Shortcut to format_time() for a datetime format

viscid.npdatetime.is_valid_datetime64(arr, unit=None)

Returns True iff arr can be made into a datetime64 array

viscid.npdatetime.is_valid_timedelta64(arr, unit=None)

Returns True iff arr can be made into a timedelta64 array

viscid.npdatetime.datetime_as_seconds(a, decimals=0, unit=None)

round datetime a to the nearest decimals seconds

viscid.npdatetime.timedelta_as_seconds(a, decimals=0, unit=None)

round timedelta a to the nearest decimals seconds

Note

works for ‘fs’, but not ‘as’

viscid.npdatetime.time_as_seconds(a, decimals=0, unit=None)

round a to the nearest decimal seconds

viscid.npdatetime.datetime64_as_years(time)

Get time as floating point years since the year 0

viscid.npdatetime.asarray_datetime64(arr, unit=None, conservative=False)

If is_valid_datetime64, then return a datetime64 array

Parameters:

• arr (sequence) – something that can become an arary
• unit (str) – one of {Y,M,W,D,h,m,s,m,s,us,ns,ps,fs,as}
• conservative (bool) – If True, then only turn arr into a date-time array if it really looks like it

viscid.npdatetime.linspace_datetime64(start, stop, n, endpoint=True, unit=None)

Make an evenly space ndarray from start to stop with n values

viscid.npdatetime.round_time(tlst, unit, allow0=True)

Round a time or list of times to minimum level of coarseness

Note

• When rounding, some values might be rounded to 0. If you rather raise a PrecisionError, then give allow0=False.

Parameters:

• tlst (timelike, list) – single or list of datetime64 or timedelta64
• unit (str) – units of result will be at least as coarse as this unit
• allow0 (bool) – If False, then raise PrecisionError if a value has been truncated to 0

Returns:

tlst rounded to a unit at least as coarse

as unit

Return type:

timelike or list

viscid.npdatetime.regularize_time(tlst, unit=None, most_precise=False, allow_rounding=True, allow0=True)

Convert a list of times to a common unit

Notes

• If some times are too fine to fit in the same unit as the rest of the times, then they will be rounded to a more coarse unit. If you rather raise an OverflowError, then give allow_rounding=False.
• When rounding, some values might be rounded to 0. If you rather raise a PrecisionError, then give allow0=False.

Parameters:

• tlst (timelike, list) – single or list of datetime64 or timedelta64
• unit (str) – If given, regularize all times to this unit, otherwise, regularize them to the most precise of the bunch
• most_precise (bool) – If True, then convert all times to the most precise unit that fits all the times
• allow_rounding (bool) – if any time is too small to be represented in the desired unit, then use a more coarse unit and round values so that everything fits
• allow0 (bool) – If False, then raise PrecisionError if a value has been rounded to 0

Returns:

single or list of times all in the same unit

Return type:

timelike or list

viscid.npdatetime.time_sum(t0, tdelta, unit=None, most_precise=False, allow_rounding=True, allow0=True)

Add timedelta64 to datetime64 at highest precision w/o overflow

Notes

• If allow_rounding, then the result may not be in unit. If you rather raise an OverflowError, give allow_rounding=False
• If t0 can not be represented using the same units as tdelta, then tdelta could be rounded to 0. If you rather raise a PrecisionError, then give allow0=False

Parameters:

• t0 (datetime64) – starting date
• tdelta (timedelta64) – timedelta to add
• unit (str) – If given, regularize all times to this unit, otherwise, regularize them to the most precise of the bunch
• most_precise (bool) – If True, then convert all times to the most precise unit that fits all the times
• allow_rounding (bool) – if tdelta is too small to be represented in the same unit as t0, then round it to the finest unit that fits both t0 and tdelta
• allow0 (bool) – If False, and a value is rounded to 0 in a given unit, then raise a PrecisionError

Returns:

t0 + tdelta

Return type:

datetime64

viscid.npdatetime.time_diff(t1, t2, unit=None, most_precise=False)

Diff two datetime64s at highest precision w/o overflow

Note

If allow_rounding, then the result may not be in unit. If you rather raise an OverflowError, give allow_rounding=False

Parameters:

• t1 (datetime64) – t1 for t1 - t2
• t2 (datetime64) – t2 for t1 - t2
• unit (str) – If given, regularize all times to this unit, otherwise, regularize them to the most precise of the bunch
• most_precise (bool) – If True, then convert all times to the most precise unit that fits all the times

Returns:

t1 - t2

Return type:

timedelta64

viscid.npdatetime.is_datetime_like(val, conservative=False)

Returns True iff val is datetime-like

viscid.npdatetime.is_timedelta_like(val, conservative=False)

Returns True iff val is timedelta-like

viscid.npdatetime.is_time_like(val, conservative=False)

Returns True iff val is datetime-like or timedelta-like