Add another Trace object to current trace.

Parameters: method (int, optional) Method to handle overlaps of traces. Defaults to 0. See the Handling Overlaps section below for further details. fill_value (int, float, str or None, optional) Fill value for gaps. Defaults to None. Traces will be converted to NumPy masked arrays if no value is given and gaps are present. If the keyword 'latest' is provided it will use the latest value before the gap. If keyword 'interpolate' is provided, missing values are linearly interpolated (not changing the data type e.g. of integer valued traces). See the Handling Gaps section below for further details. interpolation_samples (int, optional) Used only for method=1. It specifies the number of samples which are used to interpolate between overlapping traces. Defaults to 0. If set to -1 all overlapping samples are interpolated. sanity_checks (bool, optional) Enables some sanity checks before merging traces. Defaults to True.

Trace data will be converted into a NumPy masked array data type if any gaps are present. This behavior may be prevented by setting the fill_value parameter. The method argument controls the handling of overlapping data values.

Sampling rate, data type and trace.id of both traces must match.

Handling Overlaps

Method Description
0

Discard overlapping data. Overlaps are essentially treated the same way as gaps:

Trace 1: AAAAAAAA
Trace 2:     FFFFFFFF
1 + 2  : AAAA----FFFF


Contained traces with differing data will be marked as gap:

Trace 1: AAAAAAAAAAAA
Trace 2:     FF
1 + 2  : AAAA--AAAAAA


Missing data can be merged in from a different trace:

Trace 1: AAAA--AAAAAA (contained trace, missing samples)
Trace 2:     FF
1 + 2  : AAAAFFAAAAAA

1

Discard data of the previous trace assuming the following trace contains data with a more correct time value. The parameter interpolation_samples specifies the number of samples used to linearly interpolate between the two traces in order to prevent steps. Note that if there are gaps inside, the returned array is still a masked array, only if fill_value is set, the returned array is a normal array and gaps are filled with fill value.

No interpolation (interpolation_samples=0):

Trace 1: AAAAAAAA
Trace 2:     FFFFFFFF
1 + 2  : AAAAFFFFFFFF


Interpolate first two samples (interpolation_samples=2):

Trace 1: AAAAAAAA
Trace 2:     FFFFFFFF
1 + 2  : AAAACDFFFFFF (interpolation_samples=2)


Interpolate all samples (interpolation_samples=-1):

Trace 1: AAAAAAAA
Trace 2:     FFFFFFFF
1 + 2  : AAAABCDEFFFF


Any contained traces with different data will be discarded:

Trace 1: AAAAAAAAAAAA (contained trace)
Trace 2:     FF
1 + 2  : AAAAAAAAAAAA


Missing data can be merged in from a different trace:

Trace 1: AAAA--AAAAAA (contained trace, missing samples)
Trace 2:     FF
1 + 2  : AAAAFFAAAAAA


Handling gaps

1. Traces with gaps and fill_value=None (default):

Trace 1: AAAA
Trace 2:         FFFF
1 + 2  : AAAA----FFFF

2. Traces with gaps and given fill_value=0:

Trace 1: AAAA
Trace 2:         FFFF
1 + 2  : AAAA0000FFFF

3. Traces with gaps and given fill_value='latest':

Trace 1: ABCD
Trace 2:         FFFF
1 + 2  : ABCDDDDDFFFF

4. Traces with gaps and given fill_value='interpolate':

Trace 1: AAAA
Trace 2:         FFFF
1 + 2  : AAAABCDEFFFF