Tools

Spectral analysis and miscellaneous DOLfYN functions are stored here. These functions are used throughout DOLfYN’s core code and may also be helpful to users in general.

FFT-based Functions:

psd_freq	Compute the frequency for vector for a nfft and fs.
stepsize	Calculates the fft-step size for a length l array.
coherence	Computes the magnitude-squared coherence of a and b.
phase_angle	Compute the phase difference between signals a and b.
psd	Compute the power spectral density (PSD).
cpsd	Compute the cross power spectral density (CPSD) of the signals a and b.
cpsd_quasisync	Compute the cross power spectral density (CPSD) of the signals a and b.

Other Functions:

detrend	Remove a linear trend from arr.
group	Find continuous segments in a boolean array.
slice1d_along_axis	Return an iterator object for looping over 1-D slices, along axis, of an array of shape arr_shape.
fillgaps	Linearly fill NaN value in an array.
interpgaps	Fill gaps (NaN values) in a by linear interpolation along dimension dim with the point spacing specified in t.
medfiltnan	Do a running median filter of the data.
convert_degrees	Converts between the 'cartesian angle' (counter-clockwise from East) and the 'polar angle' in (degrees clockwise from North)

dolfyn.tools.psd.psd_freq(nfft, fs, full=False)

Compute the frequency for vector for a nfft and fs.

Parameters:

• fs (float) – The sampling frequency (e.g. samples/sec)

• nfft (int) – The number of samples in a window.

• full (bool (default: False)) – Whether to return half frequencies (positive), or the full frequencies.

Returns:

freq (|np.ndarray|) – The frequency vector, in same units as ‘fs’

dolfyn.tools.psd.stepsize(l, nfft, nens=None, step=None)

Calculates the fft-step size for a length l array.

If nens is None, the step size is chosen to maximize data use, minimize nens and have a minimum of 50% overlap.

If nens is specified, the step-size is computed directly.

Parameters:

• l (The length of the array.) –

• nfft (The number of points in the fft.) –

• nens (The number of nens to perform (default compute this).) –

Returns:

• step (The step size.)

• nens (The number of ensemble ffts to average together.)

• nfft (The number of points in the fft (set to l if nfft>l).)

dolfyn.tools.psd.coherence(a, b, nfft, window='hann', debias=True, noise=(0, 0))

Computes the magnitude-squared coherence of a and b.

Parameters:

• a (numpy.ndarray) – The first array over which to compute coherence.

• b (numpy.ndarray) – The second array over which to compute coherence.

• nfft (int) – The number of points to use in the fft.

• window (string, np.ndarray (default 'hann')) – The window to use for ffts.

• debias (bool (default: True)) – Specify whether to debias the signal according to Benignus1969.

• noise (tuple(2), or float) – The noise keyword may be used to specify the signals’ noise levels (std of noise in a,b). If noise is a two element tuple or list, the first and second elements specify the noise levels of a and b, respectively. default: noise=(0,0)

Returns:

out (|np.ndarray|) – Coherence between a and b

Notes

Coherence is defined as:

\[C_{ab} = \frac{|S_{ab}|^2}{S_{aa} * S_{bb}}\]

Here \(S_{ab}\), \(S_{aa}\) and \(S_{bb}\) are the cross, and auto spectral densities of the signal a and b.

dolfyn.tools.psd.cpsd_quasisync(a, b, nfft, fs, window='hann')

Compute the cross power spectral density (CPSD) of the signals a and b.

Parameters:

• a (numpy.ndarray) – The first signal.

• b (numpy.ndarray) – The second signal.

• nfft (int) – The number of points in the fft.

• fs (float) – The sample rate (e.g. sample/second).

• window ({None, 1, ‘hann’, numpy.ndarray}) – The window to use (default: ‘hann’). Valid entries are: - None,1 : uses a ‘boxcar’ or ones window. - ‘hann’ : hanning window. - a length(nfft) array : use this as the window directly.

Returns:

cpsd (|np.ndarray|) – The cross-spectral density of a and b.

See also

psd(), coherence(), cpsd(), numpy.fft

Notes

a and b do not need to be ‘tightly’ synchronized, and can even be different lengths, but the first- and last-index of both series should be synchronized (to whatever degree you want unbiased phases).

This performs:

\[fft(a)*conj(fft(b))\]

Note that this is consistent with numpy.correlate().

It detrends the data and uses a minimum of 50% overlap for the shorter of a and b. For the longer, the overlap depends on the difference in size. 1-(l_short/l_long) data will be underutilized (where l_short and l_long are the length of the shorter and longer series, respectively).

The units of the spectra is the product of the units of a and b, divided by the units of fs.

dolfyn.tools.psd.cpsd(a, b, nfft, fs, window='hann', step=None)

Compute the cross power spectral density (CPSD) of the signals a and b.

Parameters:

• a (numpy.ndarray) – The first signal.

• b (numpy.ndarray) – The second signal.

• nfft (int) – The number of points in the fft.

• fs (float) – The sample rate (e.g. sample/second).

• window ({None, 1, ‘hann’, numpy.ndarray}) – The window to use (default: ‘hann’). Valid entries are: - None,1 : uses a ‘boxcar’ or ones window. - ‘hann’ : hanning window. - a length(nfft) array : use this as the window directly.

• step (int) – Use this to specify the overlap. For example: - step : nfft/2 specifies a 50% overlap. - step : nfft specifies no overlap. - step=2*nfft means that half the data will be skipped. By default, step is calculated to maximize data use, have at least 50% overlap and minimize the number of ensembles.

Returns:

cpsd (|np.ndarray|) – The cross-spectral density of a and b.

See also

psd(), coherence(), None

Notes

cpsd removes a linear trend from the signals.

The two signals should be the same length, and should both be real.

This performs:

\[fft(a)*conj(fft(b))\]

This implementation is consistent with the numpy.correlate definition of correlation. (The conjugate of D.B. Chelton’s definition of correlation.)

The units of the spectra is the product of the units of a and b, divided by the units of fs.

dolfyn.tools.psd.psd(a, nfft, fs, window='hann', step=None)

Compute the power spectral density (PSD).

This function computes the one-dimensional n-point PSD.

The units of the spectra is the product of the units of a and b, divided by the units of fs.

Parameters:

• a (numpy.ndarray) – The first signal, as a 1D vector

• nfft (int) – The number of points in the fft.

• fs (float) – The sample rate (e.g. sample/second).

• window ({None, 1, ‘hann’, numpy.ndarray}) – The window to use (default: ‘hann’). Valid entries are: - None,1 : uses a ‘boxcar’ or ones window. - ‘hann’ : hanning window. - a length(nfft) array : use this as the window directly.

• step (int) – Use this to specify the overlap. For example: - step : nfft/2 specifies a 50% overlap. - step : nfft specifies no overlap. - step=2*nfft means that half the data will be skipped. By default, step is calculated to maximize data use, have at least 50% overlap and minimize the number of ensembles.

Returns:

psd (|np.ndarray|) – The power spectral density of a and b.

Notes

Credit: This function’s line of code was copied from JN’s fast_psd.m routine.

See also

cpsd(), coherence(), None

dolfyn.tools.psd.phase_angle(a, b, nfft, window='hann', step=None)

Compute the phase difference between signals a and b. This is the complimentary function to coherence and cpsd.

Positive angles means that b leads a, i.e. this does, essentially:

angle(b) - angle(a)

This function computes one-dimensional n-point PSD.

The angles are output as magnitude = 1 complex numbers (to simplify averaging). Therefore, use numpy.angle to actually output the angle.

Parameters:

• a (1d-array_like, the signal. Currently only supports vectors.) –

• nfft (The number of points in the fft.) –

• window (The window to use (default: 'hann'). Valid entries are:) – None,1 : uses a ‘boxcar’ or ones window. ‘hann’ : hanning window. a length(nfft) array : use this as the window directly.

• step (Use this to specify the overlap. For example:) –

  • step=nfft/2 specifies a 50% overlap.

  • step=nfft specifies no overlap.

  • step=2*nfft means that half the data will be skipped.

  By default, step is calculated to maximize data use, have at least 50% overlap and minimize the number of ensembles.

Returns:

ang (complex |np.ndarray| (unit magnitude values))

See also

None, coherence(), cpsd()

dolfyn.tools.misc.detrend(arr, axis=-1, in_place=False)

Remove a linear trend from arr.

Parameters:

• arr (array_like) – The array from which to remove a linear trend.

• axis (int) – The axis along which to operate.

Notes

This method is copied from the matplotlib.mlab library, but implements the covariance calcs explicitly for added speed.

This works much faster than mpl.mlab.detrend for multi-dimensional arrays, and is also faster than linalg.lstsq methods.

dolfyn.tools.misc.group(bl, min_length=0)

Find continuous segments in a boolean array.

Parameters:

• bl (numpy.ndarray (dtype=’bool’)) – The input boolean array.

• min_length (int (optional)) – Specifies the minimum number of continuous points to consider a group (i.e. that will be returned).

Returns:

out (np.ndarray(slices,)) – a vector of slice objects, which indicate the continuous sections where bl is True.

Notes

This function has funny behavior for single points. It will return the same two indices for the beginning and end.

dolfyn.tools.misc.slice1d_along_axis(arr_shape, axis=0)

Return an iterator object for looping over 1-D slices, along axis, of an array of shape arr_shape.

Parameters:

• arr_shape (tuple,list) – Shape of the array over which the slices will be made.

• axis (integer) – Axis along which arr is sliced.

Returns:

Iterator (object) – The iterator object returns slice objects which slices arrays of shape arr_shape into 1-D arrays.

Examples

>> out=np.empty(replace(arr.shape,0,1)) >> for slc in slice1d_along_axis(arr.shape,axis=0): >> out[slc]=my_1d_function(arr[slc])

dolfyn.tools.misc.fillgaps(a, maxgap=inf, dim=0, extrapFlg=False)

Linearly fill NaN value in an array.

Parameters:

• a (numpy.ndarray) – The array to be filled.

• maxgap (numpy.ndarray (optional: inf)) – The maximum gap to fill.

• dim (int (optional: 0)) – The dimension to operate along.

• extrapFlg (bool (optional: False)) – Whether to extrapolate if NaNs are found at the ends of the array.

See also

dolfyn.tools.misc.interpgaps

Linearly interpolates in time.

Notes

This function interpolates assuming spacing/timestep between successive points is constant. If the spacing is not constant, use interpgaps.

dolfyn.tools.misc.interpgaps(a, t, maxgap=inf, dim=0, extrapFlg=False)

Fill gaps (NaN values) in a by linear interpolation along dimension dim with the point spacing specified in t.

Parameters:

• a (numpy.ndarray) – The array containing NaN values to be filled.

• t (numpy.ndarray (len(t) == a.shape[dim])) – Independent variable of the points in a, e.g. timestep

• maxgap (numpy.ndarray (optional: inf)) – The maximum gap to fill.

• dim (int (optional: 0)) – The dimension to operate along.

• extrapFlg (bool (optional: False)) – Whether to extrapolate if NaNs are found at the ends of the array.

See also

dolfyn.tools.misc.fillgaps

Linearly interpolates in array-index space.

dolfyn.tools.misc.medfiltnan(a, kernel, thresh=0)

Do a running median filter of the data. Regions where more than thresh fraction of the points are NaN are set to NaN.

Parameters:

• a (numpy.ndarray) – 2D array containing data to be filtered.

• kernel_size (numpy.ndarray or list, optional) – A scalar or a list of length 2, giving the size of the median filter window in each dimension. Elements of kernel_size should be odd. If kernel_size is a scalar, then this scalar is used as the size in each dimension.

• thresh (int) – Maximum gap in a to filter over

Returns:

out (|np.ndarray|) – 2D array of same size containing filtered data

See also

scipy.signal.medfilt2d

dolfyn.tools.misc.convert_degrees(deg, tidal_mode=True)

Converts between the ‘cartesian angle’ (counter-clockwise from East) and the ‘polar angle’ in (degrees clockwise from North)

Parameters:

• deg (float or array-like) – Number or array in ‘degrees CCW from East’ or ‘degrees CW from North’

• tidal_mode (bool (default: True)) – If true, range is set from 0 to +/-180 degrees. If false, range is 0 to 360 degrees

Returns:

out (float or array-like) – Input data transformed to ‘degrees CW from North’ or ‘degrees CCW from East’, respectively (based on deg)

Notes

The same algorithm is used to convert back and forth between ‘CCW from E’ and ‘CW from N’