qats.cli
#
Command line interface to app (GUI).
Functions overview
|
Start desktop application. |
|
Create start menu item and desktop shortcut to qats desktop app (by invoking pythonw.exe with the necessary arguments, not the previous entry point qats-app.exe (or .cmd)). |
|
Launch desktop application from command line with parameters. |
Remove start menu item and desktop shortcut to qats desktop application. |
API
- link_app()#
Create start menu item and desktop shortcut to qats desktop app (by invoking pythonw.exe with the necessary arguments, not the previous entry point qats-app.exe (or .cmd)).
- unlink_app()#
Remove start menu item and desktop shortcut to qats desktop application.
- launch_app(home=True, files=None, log_level='info')#
Start desktop application.
- main()#
Launch desktop application from command line with parameters.
qats.motions
#
Transformations and operations related to motion.
Functions overview
|
Numerical time differentiation to obtain acceleration of signal(s). |
|
Transform motion to new reference position. |
|
Numerical time differentiation to obtain velocity of signal(s). |
API
- transform_motion(motion, newref, rotunit='deg')#
Transform motion to new reference position.
The following sequence of rotation is used: z-y-z (known as yaw-pitch-roll). For more detailed description, see https://en.wikipedia.org/wiki/Euler_angles or SIMO Theory Manual (ch. 6.2 in version 4.14.0).
- Parameters:
motion (tuple or np.ndarray) –
- Motion of old reference point, 6 dofs (hence shape (6, nt), where nt is number of time steps):
x (position of old reference point in global coord. system)
y (position of old reference point in global coord. system)
z (position of old reference point in global coord. system)
rx (rotation about local x-axis, aka. roll)
ry (rotation about local x-axis, aka. roll)
rz (rotation about local x-axis, aka. roll)
newref (3-tuple) – Position vector (in body coordinate system) of new reference point: (x, y, z).
rotunit ({'deg', 'rad'}) – Unit of rotations. Default is degrees.
- Returns:
xyz – Position vector for new reference position, shape (3, n).
- Return type:
np.ndarray
- acceleration(x, t)#
Numerical time differentiation to obtain acceleration of signal(s).
- Parameters:
x (list or np.array) – Signal(s) to perform time derivation on. See requirements given for function
velocity()
.t (float or np.array) – Time step or time array.
- Returns:
acc – Acceleration of input signal(s); same shape as input.
- Return type:
np.array
Notes
In practice, acceleration is calculated by calling function velocity twice.
See also
- velocity(x, t)#
Numerical time differentiation to obtain velocity of signal(s).
- Parameters:
x (list or np.array) – Signal to perform time derivation on. If a 2-D array is given, it is required to be of shape (n, nt), where n is number of signals and nt is number of time steps. Time differentiation is then performed for each of the signals independently.
t (float or np.array) – Time step or time array.
- Returns:
vel – Velocity of input signal(s); same shape as input.
- Return type:
np.array
Notes
Velocity is calculated using second order central differences, with first order backwards and forward differences at start/end of signals. See numpy.gradient.
See also
qats.signal
#
Module with functions for signal processing.
Functions overview
|
Estimation of the auto-correlation coefficients of series |
|
Average frequency of mean level crossings. |
|
Band block filter data signal x at cut off frequencies flow and fupp, blocking harmonic content inside the frequency band [flow, fupp] |
|
Band pass filter data signal x at cut off frequencies flow and fupp, blocking harmonic content outside the frequency band [flow, fupp] |
|
Estimate the magnitude squared coherence estimate of discrete-time signals X and Y using Welch’s method. |
|
Estimate cross power spectral density of discrete-time signals X and Y using Welch’s method. |
|
Extend the signal ends with n values to mitigate the edge effect. |
|
Return sorted maxima |
|
High pass filter data signal x at cut off frequency fc, blocking harmonic content below fc. |
|
Low pass filter data signal x at cut off frequency fc, blocking harmonic content above fc. |
|
Estimate power spectral density of discrete time signal X using Welch’s method. |
|
Smooth time serie based on convolution of a window function and the time serie. |
|
Taper the input time serie using a window function |
|
Estimate the transfer function between two discrete-time signals X and Y using Welch’s method. |
|
Allow only frequency components whose amplitudes are between the lower threshold value and the upper threshold value to pass. |
API
- extend_signal_ends(x: ndarray, n: int) ndarray #
Extend the signal ends with n values to mitigate the edge effect.
- Parameters:
x (array_like) – Signal
n (int) – Number of values prepended and appended to signal.
Notes
At each end of the signal n values of the signal are replicated, flipped and joined with the signal to maintain continuity in the signal level and slope at the joining points. This should mitigate end effects when filterin the signal.
The original signal is retrieved as x[n:-n:1].
- smooth(x: ndarray, window_len: int = 11, window: str = 'rectangular', mode: str = 'same') ndarray #
Smooth time serie based on convolution of a window function and the time serie.
- Parameters:
x (array) – The input signal.
window_len (int, optional) – The dimension of the smoothing window.
window ({'rectangular', 'hanning', 'hamming', 'bartlett', 'blackman'}, optional) – The type of window. Rectangular window will produce a moving average smoothing.
mode ({‘same’, ‘valid’, ‘full’}, optional) –
- full:
This returns the convolution at each point of overlap, with an output shape of (N+M-1,). At the end-points of the convolution, the signals do not overlap completely, and boundary effects may be seen.
- same:
By default mode is ‘same’ which returns output of length max(M, N). Boundary effects are still visible.
- valid:
Mode valid returns output of length max(M, N) - min(M, N) + 1. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect
- Returns:
The smoothed signal.
- Return type:
array
Notes
This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) in both ends so that transient parts are minimized in the beginning and end of the output signal.
Examples
>>> from numpy import linspace >>> from numpy.random import randn >>> t = linspace(-2,2,0.1) >>> x = sin(t)+randn(len(t))*0.1 >>> y = smooth(x)
References
Wikipedia, http://en.wikipedia.org/wiki/Convolution
See also
- taper(x: ~numpy.ndarray, window: str = 'tukey', alpha: float = 0.001) -> (<class 'numpy.ndarray'>, <class 'float'>)#
Taper the input time serie using a window function
- Parameters:
x (array) – Time series (without time vector), dimension n*1.
window ({'tukey','cosine','hanning', 'flat', ....}) – Window function type. See numpy documentation for more windows
alpha (float, optional) – Fraction of time domain signal to be tapered. Applies only to tukey and kaiser windows.
- Returns:
array – Tapered time domain signal
float – correction factor to prevent FFT components from diminishing after the windowing.
Notes
All FFT based measurements assume that the signal is periodic in the time frame. When the measured signal is not periodic then leakage occurs. Leakage results in misleading information about the spectral amplitude and frequency. A window is shaped so that it is exactly zero at the beginning and end of the data block and has some special shape in between. This function is then multiplied with the time data block forcing the signal to be periodic and ultimately reduces the effects of leakage. There are many windows to choose from, each with advantages for specific applications. You must understand the effects of leakage and know the tradeoffs and advantages of the various windowing functions to accurately interpret frequency domain measurements.
The cosine window is also known as the sine window.
The Tukey window is also known as the tapered cosine window.
See also
numpy.bartlett
,numpy.blackman
,numpy.hamming
,numpy.hanning
,numpy.kaiser
References
Wikipedia, http://en.wikipedia.org/wiki/Window_function
Melbourne G. Briscoe (1972), Energy loss in surface wave spectra due to data windowing, North Atlantic Treaty Organization (NATO), Saclant ASW Research Centre,
- lowpass(x: ndarray, dt: float, fc: float, order: int = 5) ndarray #
Low pass filter data signal x at cut off frequency fc, blocking harmonic content above fc.
- Parameters:
- Returns:
Filtered signal
- Return type:
array
See also
- highpass(x: ndarray, dt: float, fc: float, order: int = 5) ndarray #
High pass filter data signal x at cut off frequency fc, blocking harmonic content below fc.
- Parameters:
- Returns:
Filtered signal
- Return type:
array
See also
- bandpass(x: ndarray, dt: float, flow: float, fupp: float, order: int = 5) ndarray #
Band pass filter data signal x at cut off frequencies flow and fupp, blocking harmonic content outside the frequency band [flow, fupp]
- Parameters:
- Returns:
Filtered signal
- Return type:
array
See also
- bandblock(x: ndarray, dt: float, flow: float, fupp: float, order: int = 5) ndarray #
Band block filter data signal x at cut off frequencies flow and fupp, blocking harmonic content inside the frequency band [flow, fupp]
- Parameters:
- Returns:
Filtered signal
- Return type:
array
Notes
SciPy bandpass/bandstop filters designed with b, a are unstable and may result in erroneous filters at higher filter orders. Here we use sos (second-order sections) output of filter design instead.
See also
- threshold(x: ndarray, thresholds: tuple) ndarray #
Allow only frequency components whose amplitudes are between the lower threshold value and the upper threshold value to pass.
- Parameters:
x (array_like) – input data signal
thresholds (tuple) – passing amplitude range, thresholds as fraction of maximum frequency component amplitude
- Returns:
filtered data signal
- Return type:
array
Notes
FFT filter.
See also
- autocorrelation(series: ndarray) list #
Estimation of the auto-correlation coefficients of series
- Parameters:
series (array_like) – data series
- Returns:
arrays of autocorrelation coefficients for the entire series for lags in the range [dt, dt, duration]
- Return type:
Notes
I took a part of code from pandas autocorrelation_plot() function. I checked the answers and the values are matching exactly. The auto-correlation coefficients can be plotted against the time vector associated with series.
References
Wikipedia, http://en.wikipedia.org/wiki/Autocorrelation
- average_frequency(t: ndarray, x: ndarray, up: bool = True) float #
Average frequency of mean level crossings.
- find_maxima(x, local: bool = False, threshold: float | None = None, up: bool = True) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)#
Return sorted maxima
- Parameters:
x (array) – Signal.
local (bool, optional) – If True, local maxima are also included (see notes below). Default is to include only global maxima.
threshold (float, optional) – Include only maxima larger than specified treshold. Default is not to remove any of the maxima identified.
up (bool, optional) – This parameter is deprecated and has no effect on the peak/maxima identification.
- Returns:
array – Signal maxima, sorted from smallest to largest.
array – Indices of signal maxima.
Notes
By default only ‘global’ maxima are considered, i.e. the largest maximum between each mean-level up-crossing. If
local=True
, local maxima are also included (first derivative is zero, second derivative is negative).Changes from version 4.12. When extracting global maxima (
local=False
, the default), positive half-cycles at the beginning or end of the time series are included. For example, if there is a mean-level up-crossing before the first down-crossing, the maximum value between these crossings is included. Similarly, if there is a down-crossing after the last up-crossing, the maximum value between these crossings is included. This also implies that there is no difference in considering mean level up-crossings (up=True) vs. down-crossings (up=False). The up parameter is therefore deprecated.Examples
Extract global maxima from time series signal x:
>>> maxima, _ = find_maxima(x)
Extract global maxima and corresponding indices:
>>> maxima, indices = find_maxima(x)
Assuming time is the time vector (numpy array) for signal x, the following example will provide an array of time instants associated with the maxima sample:
>>> time_maxima = time[indices]
Note that the returned maxima (and corresponding indices) are sorted in ascending order. To reverse this and obtain an array with the maxima arranged in order of appearance, the following code may be used:
>>> indsort = np.argsort(indices) >>> maxima = maxima[indsort] >>> indices = indices[indsort] >>> time_maxima = time[indices]
- psd(x: ~numpy.ndarray, dt: float, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)#
Estimate power spectral density of discrete time signal X using Welch’s method.
- Parameters:
x (array_like) – Time series data.
dt (float) – Time step.
kwargs (optional) – See scipy.signal.welch documentation for available options.
- Returns:
array – Frequencies
array – Corresponding power spectral density
Notes
This function basically wraps scipy.signal.welch to control defaults etc.
See also
- csd(x: ~numpy.ndarray, y: ~numpy.ndarray, dt: float, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)#
Estimate cross power spectral density of discrete-time signals X and Y using Welch’s method.
- Parameters:
x (array_like) – Time series data.
y (array_like) – Time series data.
dt (float) – Time step.
kwargs (optional) – See scipy.signal.csd documentation for available options.
- Returns:
array – Frequencies
array – Corresponding cross power spectral density
Notes
This function basically wraps scipy.signal.csd to control defaults etc.
See also
- coherence(x: ~numpy.ndarray, y: ~numpy.ndarray, dt: float, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)#
Estimate the magnitude squared coherence estimate of discrete-time signals X and Y using Welch’s method.
- Parameters:
x (array_like) – Time series data.
y (array_like) – Time series data.
dt (float) – Time step.
kwargs (optional) – See scipy.signal.coherence documentation for available options.
- Returns:
array – Frequencies
array – Corresponding cross power spectral density
Notes
This function basically wraps scipy.signal.coherence to control defaults etc.
See also
- tfe(x: ~numpy.ndarray, y: ~numpy.ndarray, dt: float, clim: float | None = None, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)#
Estimate the transfer function between two discrete-time signals X and Y using Welch’s method.
- Parameters:
x (array_like) – Time series data.
y (array_like) – Time series data.
dt (float) – Time step.
clim (float, optional) – Discard transfer function estimates where the magnitude squared coherence estimate is below this limit.
kwargs (optional) – See scipy.signal.welch, scipy.signal.csd and scipy.signal.coherence documentation for available options.
- Returns:
array – Frequencies
array – Corresponding transfer function estimate
Examples
Estimate the transfer function between wave elevation and vessel heave motion recorded to a file “somefile.mat”. >>> from qats import TsDB >>> from qats.signal import tfe >>> import matplotlib.pyplot as plt >>> >>> db = TsDB.fromfile(“somefile.mat”) >>> wave = db.get(“wave_2”) >>> heave = db.get(“heave”) >>> >>> # discard the transient signal >>> t, w = wave.get(twin=(1000, 1e8)) >>> _, h = heave.get(twin=(1000, 1e8)) >>> dt = t[1] - t[0] >>> # discard part of signals with poor coherence and smooth using Welch’s method with 1000 values per segment. >>> f, tf = tfe(w, h, dt, clim=0.3, nperseg=1000) >>> # plot transfer function against period and limit to periods larger than 2 seconds (0.5Hz) >>> plt.plot(1. / f[(0. < f) & (f <= 0.5)], abs(tf[(0. < f) & (f <= 0.5)])) >>> plt.xlabel(“Period (Hz)”) >>> plt.ylabel(“Transfer function (-)”) >>> plt.grid() >>> plt.show()
Notes
For single input/single-output systems like this the transfer function is estimated as Pyx / Pxx where Pxx is the power spectral density of x and Pyx is the complex conjugate of the cross power spectral density of x and y.
See also