obsplus.utils.time module

Obsplus utilities for working with times.

obsplus.utils.time.get_reference_time(obj)

Get a reference time inferred from an object.

Parameters:

obj (Union[UTCDateTime, Catalog, Event, float, Stream, Trace, None]) –

The argument that will indicate a start time. Types and corresponding behavior are as follows:

float:

Convert to UTCDateTime object, interpret as a timestamp.

UTCDateTime:

Return a new UTCDateTime as a copy.

catalog:

Return the earliest reference time of all events.

event:

First check for a preferred origin, if found return its origin time. If not found, iterate through the events picks and return the earliest pick time. If None are found raise a ValueError.

stream:

Return the earliest reference time of all traces.

trace:

Return the starttime in the stats object.

Raises:

• TypeError if the type is not supported. –

• ValueError if the type is supported but no reference time could be determined. –

Return type:

obspy.UTCDateTime

obsplus.utils.time.make_time_chunks(utc1, utc2, duration, overlap=0.0)

Yield time intervals fitting in given datetime range.

Function takes two utc date time objects and create a generator to yield all time in between by intervals of duration. Overlap is number of seconds segment n will overlap into segment n + 1.

Parameters:

• utc1 (obspy.UTCDateTime compatible object) – The start time of the entire interval

• utc2 (obspy.UTCDateTime compatible object) – The end time of the entire interval

• duration (float) – The duration of each chunk

• overlap (float) – The overlap each chunk should have (added at end)

Yields:

(time1, time2)

Return type:

Generator[Tuple[UTCDateTime, UTCDateTime], None, None]

Examples

>>> t1 = obspy.UTCDateTime('2016-01-01')
>>> t2 = t1 + 2 * 3600
>>> out = list(make_time_chunks(t1, t2, 3600))
>>> assert out == [(t1, t1 + 3600), (t1 + 3600, t2)]

obsplus.utils.time.to_datetime64(value, default=NaT)

Convert time value to a numpy datetime64, or array of such.

This function essentially uses the same logic as ~:class:obspy.UTCDateTime but also accounts for native numpy types.

Parameters:

• value (Union[str, UTCDateTime, float, datetime64, Timestamp, Sequence[Union[str, UTCDateTime, float, datetime64, Timestamp]], None]) – Any value that can be interpreted as a time. If a sequence is passed an ndarray of type “datetime64[ns]” is returned.

• default – A value for missing data. pandas.NaT is used by default.

Return type:

Union[datetime64, ndarray, Series]

Examples

>>> import obspy
>>> import pandas as pd
>>> timestr = '2020-01-03T11:00:00'
>>> inputs = [obspy.UTCDateTime(timestr), None, 2525, np.datetime64(timestr)]
>>> out = to_datetime64(inputs)
>>> for t in out:
...     assert isinstance(t, np.datetime64) or pd.isnull(t)
>>> assert pd.isnull(out[1])

obsplus.utils.time.to_timedelta64(value, default=numpy.timedelta64(0, 's'))

Convert a value to a timedelta[ns].

Numpy does not gracefully handle non-ints so we need to do some rounding first.

Parameters:

• value (Union[timedelta64, int, float, Sequence[Union[timedelta64, int, float]], ndarray, Series, None]) – A float or an int to convert to datetime.

• default (Any) – The default to return if the input value is not truthy.

Return type:

Union[timedelta64, ndarray, Series]

Examples

>>> import numpy as np
>>> # get array of timedelta64[ns] from various input types
>>> inputs = [1, 2.3232, np.timedelta64(5, 'Y')]
>>> out = to_timedelta64(inputs)
>>> assert isinstance(out, np.ndarray)

obsplus.utils.time.to_utc(value)

Convert an object or sequence to a UTCDateTime object.

Parameters:

value (Union[str, UTCDateTime, float, datetime64, Timestamp, Sequence[Union[str, UTCDateTime, float, datetime64, Timestamp]]]) – Any value readable by ~:class:obspy.UTCDateTime, ~:class:numpy.datetime64 or a sequence of such.

Return type:

Union[UTCDateTime, ndarray]

Examples

>>> import numpy as np
>>> import obspy
>>> inputs = [1, '2017-09-18', np.datetime64('2020-01-03')]
>>> out = to_utc(inputs)
>>> for utc in out:
...     assert isinstance(utc, obspy.UTCDateTime)