Interpolate an incomplete spectrum to a complete single sided spectrum.
This is intended to interpolate transfer functions, for example sparse
spectra that are defined only at octave frequencies or incomplete spectra
from numerical simulations.
Parameters:
data (FrequencyData) – Input data to be interpolated.
method (string) –
Specifies the input data for the interpolation
'complex'
Separate interpolation of the real and imaginary part
'magnitude_phase'
Separate interpolation if the magnitude and unwrapped phase values
'magnitude'
Interpolate the magnitude values only. Results in a zero phase
signal, which is symmetric around the first sample. This phase
response might not be ideal for many applications. Minimum and
linear phase responses can be generated with
minimum_phase and
linear_phase.
kind (tuple) –
Three element tuple ('first','second','third') that specifies the
kind of inter/extrapolation below the lowest frequency (first), between
the lowest and highest frequency (second), and above the highest
frequency (third).
The individual strings have to be
'zero', slinear, 'quadratic', 'cubic'
Spline interpolation of zeroth, first, second or third order
'previous', 'next'
Simply return the previous or next value of the point
'nearest-up', 'nearest'
Differ when interpolating half-integers (e.g. 0.5, 1.5) in that
'nearest-up' rounds up and 'nearest' rounds down.
The interpolation is done using scipy.interpolate.interp1d.
fscale (string, optional) –
'linear'
Interpolate on a linear frequency axis.
'log'
Interpolate on a logarithmic frequency axis.
The default is 'linear'.
clip (bool, tuple) – The interpolated magnitude response is clipped to the range specified
by this two element tuple. E.g., clip=(0,1) will assure that no
values smaller than 0 and larger than 1 occur in the interpolated
magnitude response. The clipping is applied after the interpolation.
The default is False which does not clip the data.
Returns:
interpolator – The interpolator can be called to interpolate the data (see examples
below). It returns a Signal and has
the following parameters
n_samplesint
Length of the interpolated time signal in samples
sampling_rate: int
Sampling rate of the output signal in Hz
showbool, optional
Show a plot of the input and output data. The default is False.
Interpolate a magnitude spectrum, add an artificial linear phase and
inspect the results.
Note that a similar plot can be created by the interpolator object by
signal=interpolator(64,44100,show=True)
>>> importpyfaraspf>>> importmatplotlib.pyplotasplt>>> importnumpyasnp>>>>>> pf.plot.use()>>> _,ax=plt.subplots(2,3)>>>>>> # generate data>>> data=pf.FrequencyData([1,0],[5e3,20e3])>>>>>> # interpolate and plot>>> forff,fscaleinenumerate(["linear","log"]):>>> interpolator=pf.dsp.InterpolateSpectrum(... data,'magnitude',('nearest','linear','nearest'),... fscale)>>>>>> # interpolate to 64 samples linear phase impulse response>>> signal=interpolator(64,44100)>>> signal=pf.dsp.linear_phase(signal,32)>>>>>> # time signal (linear and logarithmic amplitude)>>> pf.plot.time(signal,ax=ax[ff,0],unit='ms',dB=True)>>> # frequency plot (linear x-axis)>>> pf.plot.freq(... signal,dB=False,freq_scale="linear",ax=ax[ff,1])>>> pf.plot.freq(data,dB=False,freq_scale="linear",... ax=ax[ff,1],c='r',ls='',marker='.')>>> ax[ff,1].set_xlim(0,signal.sampling_rate/2)>>> ax[ff,1].set_title(... f"Interpolated on {fscale} frequency scale")>>> # frequency plot (log x-axis)>>> pf.plot.freq(signal,dB=False,ax=ax[ff,2],label='input')>>> pf.plot.freq(data,dB=False,ax=ax[ff,2],... c='r',ls='',marker='.',label='output')>>> ax[ff,2].set_xlim(2e3,signal.sampling_rate/2)>>> ax[ff,2].legend(loc='best')
Average signal.time if the signal is in the time domain and
signal.freq if the signal is in the frequency domain. Note that
these operations are equivalent for Signal objects due to the
linearity of the averaging and the FFT.
'magnitude_zerophase'
Average the magnitude spectra and discard the phase.
'magnitude_phase'
Average the magnitude spectra and the unwrapped phase separatly.
'power'
Average the power spectra \(|X|^2\) and discard the phase. The
squaring of the spectra is reversed before returning the averaged
signal.
'log_magnitude_zerophase'
Average the logarithmic magnitude spectra using
decibel and discard the phase. The logarithm
is reversed before returning the averaged signal.
The default is 'linear'
caxis (None, int, or tuple of ints, optional) – Channel axes along which the averaging is done. The default None
averages across all channels. See
audioclasses for more
information.
weights (array like) – Array with channel weights for averaging the data. Must be
broadcastable to signal.cshape. The default is None, which
applies equal weights to all channels.
keepdims (bool, optional) – If this is True, the axes which are reduced during the averaging
are kept as a dimension with size one. Otherwise, singular dimensions
will be squeezed after averaging. The default is False.
nan_policy (string, optional) –
Define how to handle NaNs in input signal.
'propagate'
If the input signal includes NaNs, the corresponding averaged output
signal value will be NaN.
'omit'
NaNs will be omitted while averaging. For each NaN value, the number
of values used for the average operation is also reduced by one. If
a signal contains only NaN values in a specific dimensions, the
output will be zero. For example if the second sample of a multi
channel signal is always NaN, the average will be zero at the
second sample.
'raise'
A 'ValueError' will be raised, if the input signal includes
NaNs.
signal2 (Signal) – The second signal. The cshape
of this signal must be broadcastable to the
cshape of the first signal.
mode (string, optional) –
A string indicating the size of the output:
'full'
Compute the full discrete linear convolution of
the input signals. The output has the length
'signal1.n_samples+signal2.n_samples-1' (Default).
'cut'
Compute the complete convolution with full and truncate the
result to the length of the longer signal.
'cyclic'
The output is the cyclic convolution of the signals, where the
shorter signal is zero-padded to fit the length of the longer
one. This is done by computing the complete convolution with
'full', adding the tail (i.e., the part that is truncated
for mode='cut' to the beginning of the result) and
truncating the result to the length of the longer signal.
method (str {'overlap_add', 'fft'}, optional) –
A string indicating which method to use to calculate the convolution:
'overlap_add'
Convolve using the overlap-add algorithm based
on scipy.signal.oaconvolve. (Default)
'fft'
Convolve using FFT based on scipy.signal.fftconvolve.
See Notes for more details.
Returns:
signal – The result of the convolution. The
cdim matches the bigger cdim
of the two input signals.
The overlap-add method is generally much faster than fft convolution when
one signal is much larger than the other, but can be slower when only a few
output values are needed or when the signals have a very similar length.
For method='overlap_add', integer data will be cast to float.
Convert data of the selected signal domain into decibels (dB).
The converted data is calculated by the base 10 logarithmic scale:
data_in_dB=log_prefix*numpy.log10(data/log_reference). By using a
logarithmic scale, the deciBel is able to compare quantities that
may have vast ratios between them. As an example, the sound pressure in
dB can be calculated as followed:
\[L_p = 20\log_{10}\biggl(\frac{p}{p_0}\biggr),\]
where \(20\) is the logarithmic prefix for sound field quantities and
\(p_0\) would be the reference for the sound pressure level. A list
of commonly used reference values can be found in the ‘log_reference’
parameters section.
Convert normalized frequency domain data. Signal must be of type
‘Signal’ or ‘FrequencyData’.
'time'
Convert time domain data. Signal must be of type
‘Signal’ or ‘TimeData’.
'freq_raw'
Convert frequency domain data without normalization. Signal must be
of type ‘Signal’.
The default is 'freq'.
log_prefix (int) – The prefix for the dB calculation. The default None, uses 10
for signals with 'psd' and 'power' FFT normalization and
20 otherwise.
log_reference (int or float) –
Reference for the logarithm calculation.
List of commonly used values:
log_reference
value
Digital signals (dBFs)
1
Sound pressure \(L_p\) (dB)
2e-5 Pa
Voltage \(L_V\) (dBu)
0.7746 volt
Sound intensity \(L_I\) (dB)
1e-12 W/m²
Voltage \(L_V\) (dBV)
1 volt
Electric power \(L_P\) (dB)
1 watt
The default is 1.
return_prefix (bool, optional) – If return_prefix is True, the function will also return the
log_prefix value. This can be used to delogrithmize the data. The
default is False.
Returns:
decibel (numpy.ndarray) – The given signal in decibel in chosen domain.
log_prefix (int or float) – Will be returned if return_prefix is set to True.
Calculate transfer functions by spectral deconvolution of two signals.
The transfer function \(H(\omega)\) is calculated by spectral
deconvolution (spectral division).
\[H(\omega) = \frac{Y(\omega)}{X(\omega)},\]
where \(X(\omega)\) is the system input signal and \(Y(\omega)\)
the system output. Regularized inversion is used to avoid numerical issues
in calculating \(X(\omega)^{-1} = 1/X(\omega)\) for small values of
\(X(\omega)\)
(see regularized_spectrum_inversion).
The system response (transfer function) is thus calculated as
system_output (Signal) – The system output signal (e.g., recorded after passing a device under
test).
The system output signal is zero padded, if it is shorter than the
system input signal.
system_input (Signal) – The system input signal (e.g., used to perform a measurement).
The system input signal is zero padded, if it is shorter than the
system output signal.
freq_range (tuple, array_like, double) – The upper and lower frequency limits outside of which the
regularization factor is to be applied. The default None
bypasses the regularization, which might cause numerical
instabilities in case of band-limited system_input. Also see
regularized_spectrum_inversion.
fft_length (int or None) – The length the signals system_output and system_input are zero padded
to before deconvolving. The default is None. In this case only the
shorter signal is padded to the length of the longer signal, no padding
is applied when both signals have the same length.
kwargs (key value arguments) – Key value arguments to control the inversion of \(H(\omega)\) are
passed to to regularized_spectrum_inversion.
Returns:
system_response – The resulting signal after deconvolution, representing the system
response (the transfer function).
The fft_norm of is set to 'none'.
Due to the calculation based on the time data, the returned energy is
independent of the signal’s fft_norm.
power and rms can be used
to compute the power and the rms of a signal.
Find the delay in sub-sample values of an impulse response.
The method relies on the analytic part of the cross-correlation function
of the impulse response and it’s minimum-phase equivalent, which is zero
for the maximum of the correlation function. For sub-sample root finding,
the analytic signal is approximated using a polynomial of order N.
The algorithm is based on [3] with the following modifications:
Values with negative gradient used for polynolmial fitting are
rejected, allowing to use larger part of the signal for fitting.
By default a first order polynomial is used, as the slope of the
analytic signal should in theory be linear.
The start sample is identified as the first sample which is below the
threshold level relative to the maximum level of the impulse response.
For room impulse responses, ISO 3382 [4] specifies a threshold of 20 dB.
This function is primary intended to be used when processing room impulse
responses.
Alternatively see pyfar.dsp.find_impulse_response_delay.
Parameters:
impulse_response (pyfar.Signal) – The impulse response
threshold (float, optional) – The threshold level in dB, by default 20, which complies with ISO 3382.
Returns:
start_sample – Sample at which the impulse response starts
The function tries to estimate the PSNR in the IR based on the signal
power in the last 10 percent of the IR. The automatic estimation may fail
if the noise spectrum is not white or the impulse response contains
non-linear distortions. If the PSNR is lower than the specified threshold,
the function will issue a warning.
References
Examples
Create a band-limited impulse shifted by 0.5 samples and estimate the
starting sample of the impulse and plot.
Create a train of weighted impulses with levels below and above the
threshold, serving as a very abstract room impulse response. The starting
sample is identified as the last sample below the threshold relative to the
maximum of the impulse response.
This function uses a windowed Sinc filter (Method FIR-2 in [5] according
to Equations 21 and 22) to apply fractional delays, i.e., non-integer
delays to an input signal. A Kaiser window according to [6] Equations
(10.12) and (10.13) is used, which offers the possibility to control the
side lobe suppression.
shift (float, array like) – The fractional shift in samples (positive or negative). If this is a
float, the same shift is applied to all channels of signal. If this
is an array like different delays are applied to the channels of
signal. In this case it must broadcast to signal.cshape (see
Numpy broadcasting)
unit (str, optional) – The unit of the shift. Either ‘samples’ or ‘s’. Defaults to ‘samples’.
order (int, optional) – The order of the fractional shift (sinc) filter. The precision of the
filter increases with the order. High frequency errors decrease with
increasing order. The order must be smaller than
signal.n_samples. The default is 30.
side_lobe_suppression (float, optional) – The side lobe suppression of the Kaiser window in dB. The default is
60.
mode (str, optional) –
The filtering mode
"linear"
Apply linear shift, i.e., parts of the signal that are shifted to
times smaller than 0 samples and larger than signal.n_samples
disappear.
"cyclic"
Apply a cyclic shift, i.e., parts of the signal that are shifted to
values smaller than 0 are wrapped around to the end, and parts that
are shifted to values larger than signal.n_samples are wrapped
around to the beginning.
signal (Signal) – An audio signal object from the pyfar signal class
frequencies (array-like) – Frequency or frequencies in Hz at which the group delay is calculated.
The default is None, in which case signal.frequencies is used.
method ('scipy', 'fft', optional) – Method to calculate the group delay of a Signal. Both methods calculate
the group delay using the method presented in [7] avoiding issues
due to discontinuities in the unwrapped phase. Note that the scipy
version additionally allows to specify frequencies for which the
group delay is evaluated. The default is 'fft', which is faster.
Returns:
group_delay – Frequency dependent group delay in samples. The array is flattened if
a single channel signal was passed to the function.
with \(H\) the complex spectrum of the input data, \(|\cdot|\) the
absolute values, \(\omega\) the frequency in radians and \(\tau\)
the group delay in seconds.
group_delay (float, array like) – The desired group delay of the linear phase signal according to unit.
A reasonable value for most cases is signal.n_samples/2 samples,
which results in a time signal that is symmetric around the center. If
group delay is a list or array it must broadcast with the channel
layout of the signal (signal.cshape).
unit (string, optional) – Unit of the group delay. Can be 'samples' or 's' for seconds.
The default is 'samples'.
Calculate the minimum phase equivalent of a finite impulse response.
The method is based on the Hilbert transform of the real-valued cepstrum
of the finite impulse response, that is the cepstrum of the magnitude
spectrum only. As a result the magnitude spectrum is not distorted.
Potential aliasing errors can occur due to the Fourier transform based
calculation of the magnitude spectrum, which however are negligible if the
length of Fourier transform n_fft is sufficiently high. [9]
(Section 8.5.4)
Parameters:
signal (Signal) – The finite impulse response for which the minimum-phase version is
computed.
n_fft (int, optional) – The FFT length used for calculating the cepstrum. Should be at least a
few times larger than signal.n_samples. The default None uses
eight times the signal length rounded up to the next power of two,
that is: 2**int(np.ceil(np.log2(n_samples*8))).
truncate (bool, optional) – If truncate is True, the resulting minimum phase impulse
response is truncated to a length of
signal.n_samples//2+signal.n_samples%2. This avoids
aliasing described above in any case but might distort the magnitude
response if signal.n_samples is to low. If truncate is False
the output signal has the same length as the input signal. The default
is True.
Returns:
signal_minphase – The minimum phase version of the input data.
In the default case, the normalization ensures that the maximum absolute
amplitude of the signal after normalization is 1. This is achieved by
the multiplication
signal_normalized=signal*target/reference,
where target equals 1 and reference is the maximum absolute amplitude
before the normalization.
Several normalizations are possible, which in fact are different ways
of computing the reference value (e.g. based on the spectrum).
See the parameters for details.
Determines which data is used to compute the reference value.
'time'
Use the absolute of the time domain data np.abs(signal.time).
'freq'
Use the magnitude spectrum np.abs(`signal.freq)`. Note that the
normalized magnitude spectrum used
(cf.:py:mod:FFT concepts <pyfar._concepts.fft>).
The default is 'time'.
channel_handling (string, optional) –
Define how channel-wise reference values are handeled for multi-
channel signals. This parameter does not affect single-channel signals.
'individual'
Separate normalization of each channel individually.
'max'
Normalize to the maximum reference value across channels.
'min'
Normalize to the minimum reference value across channels.
'mean'
Normalize to the mean reference value across the channels.
The default is 'individual'.
target (scalar, array) – The target to which the signal is normalized. Can be a scalar or an
array. In the latter case the shape of target must be broadcastable
to signal.cshape. The default is 1.
limits (tuple, array_like) – Restrict the time or frequency range that is used to compute the
reference value. Two element tuple specifying upper and lower limit
according to domain and unit. A None element means no upper or
lower limitation. The default (None,None) uses the entire signal.
Note that in case of limiting in samples or bins with unit=None,
the second value defines the first sample/bin that is excluded.
Also note that limits need to be (None,None) if
reference_method is rms, power or energy.
unit (string, optional) –
Unit of limits.
's'
Set limits in seconds in case of time domain normalization. Uses
find_nearest_time to find the limits.
'Hz'
Set limits in hertz in case of frequency domain normalization. Uses
find_nearest_frequency
The default None assumes that limits is given in samples in case
of time domain normalization and in bins in case of frequency domain
normalization.
return_reference (bool) – If return_reference=True, the function also returns the reference
values for the channels. The default is False.
nan_policy (string, optional) –
Define how to handle NaNs in input signal.
'propagate'
If the input signal includes NaNs within the time or frequency range
, NaN will be used as normalization reference. The resulting output
signal values are NaN.
'omit'
NaNs will be omitted in the normalization. Cshape will still remain,
as the normalized signal still includes the NaNs.
'raise'
A 'ValueError' will be raised, if the input signal includes
NaNs.
The default is ‘raise’.
Returns:
normalized_signal (Signal, TimeData, FrequencyData) – The normalized input signal.
reference_norm (numpy.ndarray) – The reference values used for normalization. Only returned if
return_reference is True.
Due to the calculation based on the time data, the returned power is
independent of the signal’s fft_norm.
The power equals the squared RMS of a signal. energy
and rms can be used to compute the energy and the
RMS.
Invert the spectrum of a signal applying frequency dependent
regularization.
Regularization can either be specified within a given
frequency range using two different regularization factors, or for each
frequency individually using the parameter regu_final. In the first case
the regularization factors for the frequency regions are cross-faded using
a raised cosine window function with a width of \(\sqrt{2}f\) above and
below the given frequency range. Note that the resulting regularization
function is adjusted to the quadratic maximum of the given signal.
In case the regu_final parameter is used, all remaining options are
ignored and an array matching the number of frequency bins of the signal
needs to be given. In this case, no normalization of the regularization
function is applied.
Finally, the inverse spectrum is calculated as [10], [11],
signal (Signal) – The signals which spectra are to be inverted.
freq_range (tuple, array_like, double) – The upper and lower frequency limits outside of which the
regularization factor is to be applied.
regu_outside (float, optional) – The normalized regularization factor outside the frequency range.
The default is 1.
regu_inside (float, optional) – The normalized regularization factor inside the frequency range.
The default is 10**(-200/20) (-200 dB).
regu_final (float, array_like, optional) – The final regularization factor for each frequency, default None.
If this parameter is set, the remaining regularization factors are
ignored.
normalized (bool) – Flag to indicate if the normalized spectrum (according to
signal.fft_norm) should be inverted. The default is True.
The SciPy function scipy.signal.resample_poly is used for resampling.
The resampling ratio L=sampling_rate/signal.sampling_rate
is approximated by a fraction of two integer numbers up/down to first
upsample the signal by up and then downsample by down. This way up
and down are smaller than the respective new and old sampling rates.
Note
sampling_rate should be divisible by 10, otherwise it can cause an
infinite loop in the resample_poly function.
The amplitudes of the resampled signal can match the amplitude of the
input signal in the time or frequency domain. See the parameter
match_amplitude and the examples for more information.
sampling_rate (number) – The new sampling rate in Hz
match_amplitude (string) –
Define the domain to match the amplitude of the resampled data.
'auto'
Chooses domain to maintain the amplitude automatically, depending
on the signal.signal_type. Sets match_amplitude=='freq'
for signal.signal_type='energy' like impulse responses and
match_amplitude=='time' for other signals.
'time'
Maintains the amplitude in the time domain. This is useful for
recordings such as speech or music and must be used if
signal.signal_type='power'.
'freq'
Maintains the amplitude in the frequency domain by multiplying the
resampled signal by 1/L (see above). This is often desired
when resampling impulse responses.
The default is 'auto'.
frac_limit (int) –
Limit the denominator for approximating the resampling factor L
(see above). This can be used in case the resampling gets stuck in an
infinite loop (see note above) at the potenital cost of not exactly
realizing the target sampling rate.
The default is None, which uses frac_limit=1e6.
post_filter (bool, optional) – In some cases the up-sampling causes artifacts above the Nyquist
frequency of the input signal, i.e., signal.sampling_rate/2. If
True the artifacts are suppressed by applying a zero-phase Elliptic
filter with a pass band ripple of 0.1 dB, a stop band attenuation of 60
dB. The pass band edge frequency is signal.sampling_rate/2. The
stop band edge frequency is the minimum of 1.05 times the pass band
frequency and the new Nyquist frequency (sampling_rate/2). The
default is False. Note that this is only applied in case of
up-sampling.
Returns:
signal – The resampled signal of the input data with a length of
up/down * signal.n_samples samples.
Return type:
pyfar.Signal
Examples
For power signals, the amplitude of the resampled signal is automatically
correct in the time and frequency domain if match_amplitude="time"
With some energy signals, such as impulse responses, the amplitude can only
be correct in the time or frequency domain due to the lack of
normalization by the number of samples. In such cases, it is often desired
to match the amplitude in the frequency domain
The smoothing is done according to Tylka et al. 2017 [12] (method 2) in
three steps:
Interpolate the spectrum to a logarithmically spaced frequency scale
Smooth the spectrum by convolution with a smoothing window
Interpolate the spectrum to the original linear frequency scale
Parameters:
signal (pyfar.Signal) – The input data.
num_fractions (number) – The width of the smoothing window in fractional octaves, e.g., 3 will
apply third octave smoothing and 1 will apply octave smoothing.
mode (str, optional) –
"magnitude_zerophase"
Only the magnitude response, i.e., the absolute spectrum is
smoothed. Note that this return a zero-phase signal. It might be
necessary to generate a minimum or linear phase if the data is
subject to further processing after the smoothing (cf.
minimum_phase and
linear_phase)
"magnitude"
Smooth the magnitude and keep the phase of the input signal.
"magnitude_phase"
Separately smooth the magnitude and unwrapped phase response.
"complex"
Separately smooth the real and imaginary part of the spectrum.
Note that the modes magnitude_zerophase and magnitude make sure
that the smoothed magnitude response is as expected at the cost of an
artificial phase response. This is often desired, e.g., when plotting
signals or designing compensation filters. The modes magnitude_phase
and complex smooth all information but might cause a high frequency
energy loss in the smoothed magnitude response. The default is
"magnitude_zerophase".
window (str, optional) – String that defines the smoothing window. All windows from
time_window that do not require an additional
parameter can be used. The default is “boxcar”, which uses the
most commonly used rectangular window.
Returns:
signal (pyfar.Signal) – The smoothed output data
window_stats (tuple) – A tuple containing information about the smoothing process
n_window
The window length in (logarithmically spaced) samples
num_fractions
The actual width of the window in fractional octaves. This can
deviate from the desired width because the smoothing window must
have an integer sample length
Notes
Method 3 in Tylka at al. 2017 is mathematically more elegant at the
price of a largely increased computational and memory cost. In most
practical cases, methods 2 and 3 yield close to identical results (cf. Fig.
2 and 3 in Tylka et al. 2017). If the spectrum contains extreme
discontinuities, however, method 3 is superior (see examples below).
References
Examples
Octave smoothing of continuous spectrum consisting of two bell filters.
Octave smoothing of the discontinuous spectrum of a sine signal causes
artifacts at the edges due to the intermediate interpolation steps (cf.
Tylka et al. 2017, Fig. 4). However this is a rather unusual application
and is mentioned only for the sake of completeness.
This is a wrapper for scipy.signal.spectogram with two differences.
First, the returned times refer to the start of the FFT blocks, i.e., the
first time is always 0 whereas it is window_length/2 in scipy. Second, the
returned spectrogram is normalized according to signal.fft_norm if the
normalize parameter is set to True.
Parameters:
signal (Signal) – Signal to compute spectrogram of.
window (str) – Specifies the window (see scipy.signal.windows). The default is
'hann'.
window_length (integer) – Window length in samples, the default ist 1024.
window_overlap_fct (double) – Ratio of points to overlap between FFT segments [0…1]. The default is
0.5.
normalize (bool) – Flag to indicate if the FFT normalization should be applied to the
spectrogram according to signal.fft_norm. The default is True.
Returns:
frequencies (numpy array) – Frequencies in Hz at which the magnitude spectrum was computed
times (numpy array) – Times in seconds at which the magnitude spectrum was computed
This function only allows integer value sample shifts. If unit 'time'
is used, the shift samples will be rounded to the nearest integer value.
For a shift using fractional sample values see
fractional_time_shift.
shift (int, float) – The time-shift value. A positive value will result in right shift on
the time axis (delaying of the signal), whereas a negative value
yields a left shift on the time axis (non-causal shift to a earlier
time). If a single value is given, the same time shift will be applied
to each channel of the signal. Individual time shifts for each channel
can be performed by passing an array matching the signals channel
dimensions cshape.
mode (str, optional) –
The shifting mode
"linear"
Apply linear shift, i.e., parts of the signal that are shifted to
times smaller than 0 samples and larger than signal.n_samples
disappear. To maintain the shape of the signal, the signal is
padded at the respective other end. The pad value is determined by
pad_type.
"cyclic"
Apply a cyclic shift, i.e., parts of the signal that are shifted to
values smaller than 0 are wrapped around to the end, and parts that
are shifted to values larger than signal.n_samples are wrapped
around to the beginning.
The default is "cyclic"
unit (str, optional) – Unit of the shift variable, this can be either 'samples' or 's'
for seconds. By default 'samples' is used. Note that in the case
of specifying the shift time in seconds, the value is rounded to the
next integer sample value to perform the shift.
pad_type (numeric, optional) – The pad value for linear shifts, by default 0. is used.
Pad numpy.nan to the respective channels if the rms value of the
signal is to be maintained for block-wise rms estimation of the noise
power of a signal. Note that if NaNs are padded, the returned data
will be a TimeData instead of
Signal object.
Returns:
The time-shifted signal. This is a
TimeData object in case a linear shift
was done and the signal was padded with Nans. In all other cases, a
Signal object is returend.
interval (array_like) – If interval has two entries, these specify the beginning and the end
of the symmetric window or the fade-in / fade-out (see parameter
shape).
If interval has four entries, a window with fade-in between
the first two entries and a fade-out between the last two is created,
while it is constant in between (ignores shape).
The unit of interval is specified by the parameter unit.
See below for more details.
window (string, float, or tuple, optional) – The type of the window. See below for a list of implemented
windows. The default is 'hann'.
shape (string, optional) –
'symmetric'
General symmetric window, the two values in interval define the
first and last samples of the window.
'symmetric_zero'
Symmetric window with respect to t=0, the two values in interval
define the first and last samples of fade-out. crop is ignored.
'left'
Fade-in, the beginning and the end of the fade is defined by the
two values in interval. See Notes for more details.
'right'
Fade-out, the beginning and the end of the fade is defined by the
two values in interval. See Notes for more details.
The default is 'symmetric'.
unit (string, optional) – Unit of interval. Can be set to 'samples' or 's' (seconds).
Time values are rounded to the nearest sample. The default is
'samples'.
crop (string, optional) –
'none'
The length of the windowed signal stays the same.
'window'
The signal is truncated to the windowed part.
'end'
Only the zeros at the end of the windowed signal are
cropped, so the original phase is preserved.
The default is 'none'.
return_window (bool, optional) – If True, both the windowed signal and the time window are returned.
The default is False.
Returns:
signal_windowed (Signal) – Windowed signal object
window (Signal) – Time window used to create the windowed signal, only returned if
return_window=True.
Notes
For a fade-in, the indexes of the samples given in interval denote the
first sample of the window which is non-zero and the first which is one.
For a fade-out, the samples given in interval denote the last sample
which is one and the last which is non-zero.
This function calls scipy.signal.windows.get_window to create the
window.
Available window types:
taylor (needs number of constant sidelobes, sidelobe level)
If the window requires no parameters, then window can be a string.
If the window requires parameters, then window must be a tuple
with the first argument the string name of the window, and the next
arguments the needed parameters.