obspy.core.stream.Stream

class Stream(traces=None)

Bases: object

List like object of multiple ObsPy Trace objects.

Parameters:

traces (list of Trace, optional) – Initial list of ObsPy Trace objects.

Basic Usage

>>> trace1 = Trace()
>>> trace2 = Trace()
>>> stream = Stream(traces=[trace1, trace2])
>>> print(stream)  
2 Trace(s) in Stream:
...

Supported Operations

stream = streamA + streamB

Merges all traces within the two Stream objects streamA and streamB into the new Stream object stream. See also: Stream.__add__().

stream += streamA

Extends the Stream object stream with all traces from streamA. See also: Stream.__iadd__().

len(stream)

Returns the number of Traces in the Stream object stream. See also: Stream.__len__().

str(stream)

Contains the number of traces in the Stream object and returns the value of each Trace’s __str__ method. See also: Stream.__str__().

Public Methods

append	Append a single Trace object to the current Stream object.
attach_response	Search for and attach channel response to each trace as trace.stats.response.
clear	Clear trace list (convenience method).
copy	Return a deepcopy of the Stream object.
count	Return the number of Traces in the Stream object.
cutout	Cut the given time range out of all traces of this Stream object.
decimate	Downsample data in all traces of stream by an integer factor.
detrend	Remove a trend from all traces.
differentiate	Differentiate all traces with respect to time.
extend	Extend the current Stream object with a list of Trace objects.
filter	Filter the data of all traces in the Stream.
get_gaps	Determine all trace gaps/overlaps of the Stream object.
insert	Insert either a single Trace or a list of Traces before index.
integrate	Integrate all traces with respect to time.
interpolate	Interpolate all Traces in a Stream.
max	Get the values of the absolute maximum amplitudes of all traces in the stream.
merge	Merge ObsPy Trace objects with same IDs.
normalize	Normalize all Traces in the Stream.
plot	Create a waveform plot of the current ObsPy Stream object.
pop	Remove and return the Trace object specified by index from the Stream.
print_gaps	Print gap/overlap list summary information of the Stream object.
remove	Remove the first occurrence of the specified Trace object in the Stream object.
remove_response	Deconvolve instrument response for all Traces in Stream.
remove_sensitivity	Remove instrument sensitivity for all Traces in Stream.
resample	Resample data in all traces of stream using Fourier method.
reverse	Reverse the Traces of the Stream object in place.
rotate	Rotate stream objects.
select	Return new Stream object only with these traces that match the given stats criteria (e.g.
simulate	Correct for instrument response / Simulate new instrument response.
slice	Return new Stream object cut to the given start and end time.
slide	Generator yielding equal length sliding windows of the Stream.
sort	Sort the traces in the Stream object.
spectrogram	Create a spectrogram plot for each trace in the stream.
split	Split any trace containing gaps into contiguous unmasked traces.
stack	Stack traces by the same selected metadata.
std	Calculate standard deviations of all Traces in the Stream.
taper	Taper all Traces in Stream.
trigger	Run a triggering algorithm on all traces in the stream.
trim	Cut all traces of this Stream object to given start and end time.
verify	Verify all traces of current Stream against available meta data.
write	Save stream into a file.

Private Methods

Warning

Private methods are mainly for internal/developer use and their API might change without notice.

Stream._cleanup(misalignment_threshold=0.01)

Merge consistent trace objects but leave everything else alone.

This can mean traces with matching header that are directly adjacent or are contained/equal/overlapping traces with exactly the same waveform data in the overlapping part. If option misalignment_threshold is non-zero then contained/overlapping/directly adjacent traces with the sampling points misaligned by less than misalignment_threshold times the sampling interval are aligned on the same sampling points (see example below).

Notes

Traces with overlapping data parts that do not match are not merged:

before:
Trace 1: AAAAAAAA
Trace 2:     BBBBBBBB

after:
Trace 1: AAAAAAAA
Trace 2:     BBBBBBBB

Traces with overlapping data parts that do match are merged:

before:
Trace 1: AAAAAAAA
Trace 2:     AAAABBBB

after:
Trace 1: AAAAAAAABBBB

Contained traces are handled the same way. If common data does not match, nothing is done:

before:
Trace 1: AAAAAAAAAAAA
Trace 2:     BBBB

after:
Trace 1: AAAAAAAAAAAA
Trace 2:     BBBB

If the common data part matches they are merged:

before:
Trace 1: AAAAAAAAAAAA
Trace 2:     AAAA

after:
Trace 1: AAAAAAAAAAAA

Directly adjacent traces are merged:

before:
Trace 1: AAAAAAA
Trace 2:        BBBBB

after:
Trace 1: AAAAAAABBBBB

Misaligned traces are aligned, depending on set parameters, e.g. for a directly adjacent trace with slight misalignment (with two common samples at start of Trace 2 for better visualization):

before:
Trace 1: A---------A---------A
Trace 2:            A---------A---------B---------B

after:
Trace 1: A---------A---------A---------B---------B

Parameters:

misalignment_threshold (float) – Threshold value for sub-sample misalignments of sampling points of two traces that should be merged together (fraction of sampling interval, from 0 to 0.5). 0 means traces with even just the slightest misalignment will not be merged together, 0.5 means traces will be merged together disregarding of any sub-sample shifts of sampling points.

static Stream._dummy_stream_from_string(s)

Helper method to create a dummy Stream object (with data always equal to one) from a string representation of the Stream, mostly for debugging purposes. >>> import os >>> s = [‘’, ‘’, ‘3 Trace(s) in Stream:’, … ‘IU.GRFO..HH2 | 2016-01-07T00:00:00.008300Z - ‘ … ‘2016-01-07T00:00:30.098300Z | 10.0 Hz, 301 samples’, … ‘XX.GRFO..HH1 | 2016-01-07T00:00:02.668393Z - ‘ … ‘2016-01-07T00:00:09.518393Z | 100.0 Hz, 686 samples’, … ‘IU.ABCD..EH2 | 2016-01-07T00:00:09.528393Z - ‘ … ‘2016-01-07T00:00:50.378393Z | 100.0 Hz, 4086 samples’, … ‘’, ‘’] >>> s = os.linesep.join(s) >>> st = Stream._dummy_stream_from_string(s) >>> print(st) # doctest: +ELLIPSIS 3 Trace(s) in Stream: IU.GRFO..HH2 | 2016-01-07T00:00:00.008300Z … | 10.0 Hz, 301 samples XX.GRFO..HH1 | 2016-01-07T00:00:02.668393Z … | 100.0 Hz, 686 samples IU.ABCD..EH2 | 2016-01-07T00:00:09.528393Z … | 100.0 Hz, 4086 samples

Stream._get_common_channels_info()

Returns a dictionary with information on common channels.

Stream._groupby(group_by)

Group traces by same metadata.

Parameters:

group_by – Group traces together which have the same metadata given by this parameter. The parameter should name the corresponding keys of the stats object, e.g. '{network}.{station}'. This parameter can take the value 'id' which groups the traces by SEED id.

Returns:

dictionary {group: stream}

Stream._ltrim(starttime, pad=False, nearest_sample=True)

Cut all traces of this Stream object to given start time. For more info see _ltrim().

Stream._merge_checks()

Sanity checks for merging.

Stream._repr_pretty_(p, cycle)

Stream._rotate_specific_channels_to_zne(network, station, location, channels, inventory)

Rotate three explicitly specified channels to ZNE.

>>> from obspy import read, read_inventory
>>> st = read("/path/to/ffbx_unrotated_gaps.mseed")
>>> inv = read_inventory("/path/to/ffbx.stationxml")
>>> st._rotate_specific_channels_to_zne(
...     "BW", "FFB1", "", ["HHZ", "HH1", "HH2"],
...     inv)  
<obspy.core.stream.Stream object at 0x...>

Parameters:

• network (str) – Network code of channels that should be rotated.

• station (str) – Station code of channels that should be rotated.

• location (str) – Location code of channels that should be rotated.

• channels (list) – The three channel codes of channels that should be rotated.

• inventory (Inventory or Parser) – Inventory or Parser with metadata of channels.

Stream._rotate_to_zne(inventory, components=('Z12', '123'))

Rotate all matching traces to ZNE, specifying sets of component codes.

>>> from obspy import read, read_inventory
>>> st = read("/path/to/ffbx_unrotated_gaps.mseed")
>>> inv = read_inventory("/path/to/ffbx.stationxml")
>>> st._rotate_to_zne(inv)  
<obspy.core.stream.Stream object at 0x...>

Parameters:

• inventory (Inventory or Parser) – Inventory or Parser with metadata of channels.

• components (list or tuple or str) – List of combinations of three (case sensitive) component characters. Rotations are executed in this order, so order might matter in very strange cases (e.g. if traces with more than three component codes are present for the same SEED ID down to the component code). For example, specifying components "Z12" would rotate sets of “BHZ”, “BH1”, “BH2” (and “HHZ”, “HH1”, “HH2”, etc.) channels at the same station. If only a single set of component codes is used, this option can also be specified as a string (e.g. components='Z12').

Stream._rtrim(endtime, pad=False, nearest_sample=True)

Cut all traces of this Stream object to given end time. For more info see _rtrim().

Stream._trim_common_channels()

Trim all channels that have the same ID down to the component character to the earliest common start time and latest common end time. Works in place.

Special Methods

Stream.__add__(other)

Add two streams or a stream with a single trace.

Parameters:

other (Stream or Trace) – Stream or Trace object to add.

Return type:

Stream

Returns:

New Stream object containing references to the traces of the original streams

Examples

1. Adding two Streams

   >>> st1 = Stream([Trace(), Trace(), Trace()])
   >>> len(st1)
   3
   >>> st2 = Stream([Trace(), Trace()])
   >>> len(st2)
   2
   >>> stream = st1 + st2
   >>> len(stream)
   5
   

2. Adding Stream and Trace

   >>> stream2 = st1 + Trace()
   >>> len(stream2)
   4
   

Stream.__delattr__(name, /)

Implement delattr(self, name).

Stream.__delitem__(index)

Passes on the __delitem__ method to the underlying list of traces.

Stream.__dir__()

Default dir() implementation.

Stream.__eq__(other)

Implements rich comparison of Stream objects for “==” operator.

Trace order does not effect the comparison because the traces are sorted beforehand.

This function strictly compares the data and stats objects of each trace contained by the streams. If less strict behavior is desired, which may be the case for testing, consider using the streams_almost_equal() function.

Parameters:

other (Stream) – Stream object for comparison.

Return type:

bool

Returns:

True if both Streams contain the same traces, i.e. after a sort operation going through both streams every trace should be equal according to Trace’s __eq__() operator.

Example

>>> from obspy import read
>>> st = read()
>>> st2 = st.copy()
>>> st is st2
False
>>> st == st2
True

Stream.__format__(format_spec, /)

Default object formatter.

Stream.__ge__(other)

Too ambiguous, throw an Error.

Stream.__getattribute__(name, /)

Return getattr(self, name).

Stream.__getitem__(index)

__getitem__ method of obspy.Stream objects.

Returns:

Trace objects

Stream.__getslice__(i, j, k=1)

__getslice__ method of obspy.Stream objects.

Returns:

Stream object

Stream.__gt__(other)

Too ambiguous, throw an Error.

Stream.__iadd__(other)

Add two streams with self += other.

It will extend the current Stream object with the traces of the given Stream. Traces will not be copied but references to the original traces will be appended.

Parameters:

other (Stream or Trace) – Stream or Trace object to add.

Example

>>> stream = Stream([Trace(), Trace(), Trace()])
>>> len(stream)
3

>>> stream += Stream([Trace(), Trace()])
>>> len(stream)
5

>>> stream += Trace()
>>> len(stream)
6

Stream.__init__(traces=None)

Stream.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

Stream.__iter__()

Return a robust iterator for stream.traces.

Doing this it is safe to remove traces from streams inside of for-loops using stream’s remove() method. Actually this creates a new iterator every time a trace is removed inside the for-loop.

Example

>>> from obspy import Stream
>>> st = Stream()
>>> for component in ["1", "Z", "2", "3", "Z", "N", "E", "4", "5"]:
...     channel = "EH" + component
...     tr = Trace(header={'station': 'TEST', 'channel': channel})
...     st.append(tr)  
<...Stream object at 0x...>
>>> print(st)  
9 Trace(s) in Stream:
.TEST..EH1 | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHZ | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EH2 | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EH3 | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHZ | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHN | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHE | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EH4 | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EH5 | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples

>>> for tr in st:
...     if tr.stats.channel[-1] not in ["Z", "N", "E"]:
...         st.remove(tr)  
<...Stream object at 0x...>
>>> print(st)  
4 Trace(s) in Stream:
.TEST..EHZ | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHZ | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHN | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples
.TEST..EHE | 1970-01-01T00:00:00.000000Z - ... | 1.0 Hz, 0 samples

Stream.__le__(other)

Too ambiguous, throw an Error.

Stream.__len__()

Return the number of Traces in the Stream object.

Example

>>> stream = Stream([Trace(), Trace(), Trace()])
>>> len(stream)
3

Stream.__lt__(other)

Too ambiguous, throw an Error.

Stream.__mul__(num)

Create a new Stream containing num copies of this stream.

Rtype num:

int

Parameters:

num – Number of copies.

Returns:

New ObsPy Stream object.

Example

>>> from obspy import read
>>> st = read()
>>> len(st)
3
>>> st2 = st * 5
>>> len(st2)
15

Stream.__ne__(other)

Implements rich comparison of Stream objects for “!=” operator.

Example

>>> from obspy import read
>>> st = read()
>>> st2 = st.copy()
>>> st is st2
False
>>> st != st2
False

Stream.__new__(**kwargs)

Stream.__nonzero__()

A Stream is considered zero if has no Traces.

Stream.__reduce__()

Helper for pickle.

Stream.__reduce_ex__(protocol, /)

Helper for pickle.

Stream.__repr__()

Return repr(self).

Stream.__setattr__(name, value, /)

Implement setattr(self, name, value).

Stream.__setitem__(index, trace)

__setitem__ method of obspy.Stream objects.

Stream.__sizeof__()

Size of object in memory, in bytes.

Stream.__str__(extended=False)

Return short summary string of the current stream.

It will contain the number of Traces in the Stream and the return value of each Trace’s __str__() method.

Parameters:

extended (bool, optional) – This method will show only 20 traces by default. Enable this option to show all entries.

Example

>>> stream = Stream([Trace(), Trace()])
>>> print(stream)  
2 Trace(s) in Stream:
...

Stream.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).