mth5.timeseries package

Submodules

mth5.timeseries.channel_ts module

lists and arrays that goes on, seems easiest to convert all lists to strings and then convert them back if read in.

copyright

Jared Peacock (jpeacock@usgs.gov)

license

MIT

class mth5.timeseries.channel_ts.ChannelTS(channel_type='auxiliary', data=None, channel_metadata=None, station_metadata=None, run_metadata=None, **kwargs)[source]

Bases: object

Note

Assumes equally spaced samples from the start time.

The time series is stored in an xarray.Dataset that has coordinates of time and is a 1-D array labeled ‘data’. The xarray.Dataset can be accessed and set from the :attribute:`ts`. The data is stored in :attribute:’ts.data’ and the time index is a coordinate of :attribute:`ts`.

The time coordinate is made from the start time, sample rate and number of samples. Currently, End time is a derived property and cannot be set.

Channel time series object is based on xarray and mth5.metadata therefore any type of interpolation, resampling, groupby, etc can be done using xarray methods.

There are 3 metadata classes that hold important metadata

  • mth5.metadata.Station holds information about the station

  • mth5.metadata.Run holds information about the run the channel

belongs to. * :class`mth5.metadata.Channel` holds information specific to the channel.

This way a single channel will hold all information needed to represent the channel.

Rubric

Example

>>> from mth5.timeseries import ChannelTS
>>> ts_obj = ChannelTS('auxiliary')
>>> ts_obj.sample_rate = 8
>>> ts_obj.start = '2020-01-01T12:00:00+00:00'
>>> ts_obj.ts = range(4096)
>>> ts_obj.station_metadata.id = 'MT001'
>>> ts_obj.run_metadata.id = 'MT001a'
>>> ts_obj.component = 'temperature'
>>> print(ts_obj)
        Station      = MT001
        Run          = MT001a
        Channel Type = auxiliary
    Component    = temperature
        Sample Rate  = 8.0
        Start        = 2020-01-01T12:00:00+00:00
        End          = 2020-01-01T12:08:31.875000+00:00
        N Samples    = 4096
>>> p = ts_obj.ts.plot()
property channel_response_filter

Full channel response filter

Returns

DESCRIPTION

Return type

TYPE

property channel_type

Channel Type

property component
property end

MTime object

from_obspy_trace(obspy_trace)[source]

Fill data from an obspy.core.Trace

Parameters

obspy_trace (obspy.core.trace) – Obspy trace object

get_slice(start, end)[source]

Get a slice from the time series given a start and end time.

Looks for >= start & <= end

Uses loc to be exact with milliseconds

Parameters
  • start (TYPE) – DESCRIPTION

  • end (TYPE) – DESCRIPTION

Returns

DESCRIPTION

Return type

TYPE

property has_data

check to see if there is an index in the time series

property n_samples

number of samples

resample(dec_factor=1, inplace=False)[source]

decimate the data by using scipy.signal.decimate

Parameters

dec_factor (int) – decimation factor

  • refills ts.data with decimated data and replaces sample_rate

property sample_rate

sample rate in samples/second

property start

MTime object

to_obspy_trace()[source]

Convert the time series to an obspy.core.trace.Trace object. This will be helpful for converting between data pulled from IRIS and data going into IRIS.

Returns

DESCRIPTION

Return type

TYPE

to_xarray()[source]

Returns a xarray.DataArray object of the channel timeseries this way metadata from the metadata class is updated upon return.

Returns

Returns a xarray.DataArray object of the channel timeseries

this way metadata from the metadata class is updated upon return. :rtype: xarray.DataArray

>>> import numpy as np
>>> from mth5.timeseries import ChannelTS
>>> ex = ChannelTS("electric")
>>> ex.start = "2020-01-01T12:00:00"
>>> ex.sample_rate = 16
>>> ex.ts = np.random.rand(4096)
property ts
mth5.timeseries.channel_ts.make_dt_coordinates(start_time, sample_rate, n_samples, logger)[source]

get the date time index from the data

Parameters
  • start_time (string) – start time in time format

  • sample_rate (float) – sample rate in samples per seconds

  • n_samples (int) – number of samples in time series

:param logging.logger logger: logger class object

Returns

date-time index

mth5.timeseries.run_ts module

lists and arrays that goes on, seems easiest to convert all lists to strings and then convert them back if read in.

copyright

Jared Peacock (jpeacock@usgs.gov)

license

MIT

class mth5.timeseries.run_ts.RunTS(array_list=None, run_metadata=None, station_metadata=None)[source]

Bases: object

holds all run ts in one aligned array

components –> {‘ex’: ex_xarray, ‘ey’: ey_xarray}

add_channel(channel)[source]

Add a channel to the dataset, can be an xarray.DataArray or mth5.timeseries.ChannelTS object.

Need to be sure that the coordinates and dimensions are the same as the existing dataset, namely coordinates are time, and dimensions are the same, if the dimesions are larger than the existing dataset then the added channel will be clipped to the dimensions of the existing dataset.

If the start time is not the same nan’s will be placed at locations where the timing does not match the current start time. This is a feature of xarray.

Parameters

channel (xarray.DataArray or mth5.timeseries.ChannelTS) – a channel xarray or ChannelTS to add to the run

property channels
property dataset
property end
from_obspy_stream(obspy_stream)[source]

Get a run from an obspy.core.stream which is a list of obspy.core.Trace objects.

Parameters

obspy_stream (obspy.core.Stream) – Obspy Stream object

property has_data

check to see if there is data

plot()[source]

plot the time series probably slow for large data sets

Returns

DESCRIPTION

Return type

TYPE

property sample_rate
set_dataset(array_list, align_type='outer')[source]
Parameters
  • array_list (list of mth5.timeseries.ChannelTS objects) – list of xarrays

  • align_type (string) – how the different times will be aligned * ’outer’: use the union of object indexes * ’inner’: use the intersection of object indexes * ’left’: use indexes from the first object with each dimension * ’right’: use indexes from the last object with each dimension * ’exact’: instead of aligning, raise ValueError when indexes to be aligned are not equal * ’override’: if indexes are of same size, rewrite indexes to be those of the first object with that dimension. Indexes for the same dimension must have the same size in all objects.

property start
property summarize_metadata

Get a summary of all the metadata

Returns

DESCRIPTION

Return type

TYPE

to_obspy_stream()[source]

convert time series to an obspy.core.Stream which is like a list of obspy.core.Trace objects.

Returns

An Obspy Stream object from the time series data

Return type

obspy.core.Stream

validate_metadata()[source]

Check to make sure that the metadata matches what is in the data set.

updates metadata from the data.

Check the start and end times, channels recorded :return: DESCRIPTION :rtype: TYPE

Module contents

class mth5.timeseries.ChannelTS(channel_type='auxiliary', data=None, channel_metadata=None, station_metadata=None, run_metadata=None, **kwargs)[source]

Bases: object

Note

Assumes equally spaced samples from the start time.

The time series is stored in an xarray.Dataset that has coordinates of time and is a 1-D array labeled ‘data’. The xarray.Dataset can be accessed and set from the :attribute:`ts`. The data is stored in :attribute:’ts.data’ and the time index is a coordinate of :attribute:`ts`.

The time coordinate is made from the start time, sample rate and number of samples. Currently, End time is a derived property and cannot be set.

Channel time series object is based on xarray and mth5.metadata therefore any type of interpolation, resampling, groupby, etc can be done using xarray methods.

There are 3 metadata classes that hold important metadata

  • mth5.metadata.Station holds information about the station

  • mth5.metadata.Run holds information about the run the channel

belongs to. * :class`mth5.metadata.Channel` holds information specific to the channel.

This way a single channel will hold all information needed to represent the channel.

Rubric

Example

>>> from mth5.timeseries import ChannelTS
>>> ts_obj = ChannelTS('auxiliary')
>>> ts_obj.sample_rate = 8
>>> ts_obj.start = '2020-01-01T12:00:00+00:00'
>>> ts_obj.ts = range(4096)
>>> ts_obj.station_metadata.id = 'MT001'
>>> ts_obj.run_metadata.id = 'MT001a'
>>> ts_obj.component = 'temperature'
>>> print(ts_obj)
        Station      = MT001
        Run          = MT001a
        Channel Type = auxiliary
    Component    = temperature
        Sample Rate  = 8.0
        Start        = 2020-01-01T12:00:00+00:00
        End          = 2020-01-01T12:08:31.875000+00:00
        N Samples    = 4096
>>> p = ts_obj.ts.plot()
property channel_response_filter

Full channel response filter

Returns

DESCRIPTION

Return type

TYPE

property channel_type

Channel Type

property component
property end

MTime object

from_obspy_trace(obspy_trace)[source]

Fill data from an obspy.core.Trace

Parameters

obspy_trace (obspy.core.trace) – Obspy trace object

get_slice(start, end)[source]

Get a slice from the time series given a start and end time.

Looks for >= start & <= end

Uses loc to be exact with milliseconds

Parameters
  • start (TYPE) – DESCRIPTION

  • end (TYPE) – DESCRIPTION

Returns

DESCRIPTION

Return type

TYPE

property has_data

check to see if there is an index in the time series

property n_samples

number of samples

resample(dec_factor=1, inplace=False)[source]

decimate the data by using scipy.signal.decimate

Parameters

dec_factor (int) – decimation factor

  • refills ts.data with decimated data and replaces sample_rate

property sample_rate

sample rate in samples/second

property start

MTime object

to_obspy_trace()[source]

Convert the time series to an obspy.core.trace.Trace object. This will be helpful for converting between data pulled from IRIS and data going into IRIS.

Returns

DESCRIPTION

Return type

TYPE

to_xarray()[source]

Returns a xarray.DataArray object of the channel timeseries this way metadata from the metadata class is updated upon return.

Returns

Returns a xarray.DataArray object of the channel timeseries

this way metadata from the metadata class is updated upon return. :rtype: xarray.DataArray

>>> import numpy as np
>>> from mth5.timeseries import ChannelTS
>>> ex = ChannelTS("electric")
>>> ex.start = "2020-01-01T12:00:00"
>>> ex.sample_rate = 16
>>> ex.ts = np.random.rand(4096)
property ts
class mth5.timeseries.RunTS(array_list=None, run_metadata=None, station_metadata=None)[source]

Bases: object

holds all run ts in one aligned array

components –> {‘ex’: ex_xarray, ‘ey’: ey_xarray}

add_channel(channel)[source]

Add a channel to the dataset, can be an xarray.DataArray or mth5.timeseries.ChannelTS object.

Need to be sure that the coordinates and dimensions are the same as the existing dataset, namely coordinates are time, and dimensions are the same, if the dimesions are larger than the existing dataset then the added channel will be clipped to the dimensions of the existing dataset.

If the start time is not the same nan’s will be placed at locations where the timing does not match the current start time. This is a feature of xarray.

Parameters

channel (xarray.DataArray or mth5.timeseries.ChannelTS) – a channel xarray or ChannelTS to add to the run

property channels
property dataset
property end
from_obspy_stream(obspy_stream)[source]

Get a run from an obspy.core.stream which is a list of obspy.core.Trace objects.

Parameters

obspy_stream (obspy.core.Stream) – Obspy Stream object

property has_data

check to see if there is data

plot()[source]

plot the time series probably slow for large data sets

Returns

DESCRIPTION

Return type

TYPE

property sample_rate
set_dataset(array_list, align_type='outer')[source]
Parameters
  • array_list (list of mth5.timeseries.ChannelTS objects) – list of xarrays

  • align_type (string) – how the different times will be aligned * ’outer’: use the union of object indexes * ’inner’: use the intersection of object indexes * ’left’: use indexes from the first object with each dimension * ’right’: use indexes from the last object with each dimension * ’exact’: instead of aligning, raise ValueError when indexes to be aligned are not equal * ’override’: if indexes are of same size, rewrite indexes to be those of the first object with that dimension. Indexes for the same dimension must have the same size in all objects.

property start
property summarize_metadata

Get a summary of all the metadata

Returns

DESCRIPTION

Return type

TYPE

to_obspy_stream()[source]

convert time series to an obspy.core.Stream which is like a list of obspy.core.Trace objects.

Returns

An Obspy Stream object from the time series data

Return type

obspy.core.Stream

validate_metadata()[source]

Check to make sure that the metadata matches what is in the data set.

updates metadata from the data.

Check the start and end times, channels recorded :return: DESCRIPTION :rtype: TYPE