pyfar.dsp.fft#

The following documents the FFT functionality. More details and background including a complete list and explanation of available FFT normalizations is given in the FFT notebook of the pyfar gallery.

Functions:

add_mirror_spectrum(data_single_sided, ...)

Adds mirror spectrum to single-sided frequency data and applies fftshift.

fft(data, n_samples, sampling_rate, fft_norm)

Calculate the double-sided FFT of a time signal.

fftfreq(n_samples, sampling_rate)

Returns the negative and positive discrete frequencies for which the FFT is calculated.

ifft(spec, n_samples, sampling_rate, fft_norm)

Calculate the IFFT of a double-sided Fourier spectrum.

irfft(spec, n_samples, sampling_rate, fft_norm)

Calculate the IFFT of a single-sided Fourier spectrum.

normalization(spec, n_samples, sampling_rate)

Normalize a Fourier spectrum.

remove_mirror_spectrum(data_double_sided)

Checks if the data are conjugate symmetric and removes the redundand mirror spectrum of double-sided frequency data.

rfft(data, n_samples, sampling_rate, fft_norm)

Calculate the FFT of a real-valued time-signal.

rfftfreq(n_samples, sampling_rate)

Returns the positive discrete frequencies for which the FFT is calculated.

pyfar.dsp.fft.add_mirror_spectrum(data_single_sided, even_samples)[source]#

Adds mirror spectrum to single-sided frequency data and applies fftshift. The output is a double-sided spectrum that matches the format of fft.

Parameters:
  • data_single_sided (numpy array) – M-dimensional array of single-sided spectrum of shape (…, N) containing N frequency bins.

  • even_samples (bool) – flag which indicates if the number of samples of the time data were even.

Returns:

data – M-dimensional array of double-sided spectrum of shape (…, N) containing N frequency bins.

Return type:

numpy array

pyfar.dsp.fft.fft(data, n_samples, sampling_rate, fft_norm)[source]#

Calculate the double-sided FFT of a time signal.

The function returns the double sided spectrum. The normalization is considered according to 'fft_norm' as described in normalization and FFT concepts.

Parameters:
  • data (array, double) – Array containing the time domain signal with dimensions (…, 'n_samples')

  • n_samples (int) – The number of samples

  • sampling_rate (number) – sampling rate in Hz

  • fft_norm ('none', 'unitary', 'amplitude', 'rms', 'power', 'psd') – See documentation of normalization.

Returns:

spec – The complex valued right-hand side of the spectrum with dimensions (…, n_bins)

Return type:

array, complex

pyfar.dsp.fft.fftfreq(n_samples, sampling_rate)[source]#

Returns the negative and positive discrete frequencies for which the FFT is calculated. The number of frequency bins equals n_samples. The zero frequency is shifted to the center.

Parameters:
  • n_samples (int) – The number of samples in the signal

  • sampling_rate (int) – The sampling rate of the signal

Returns:

frequencies – The discrete frequencies in Hz for which the FFT is calculated.

Return type:

array, double

pyfar.dsp.fft.ifft(spec, n_samples, sampling_rate, fft_norm)[source]#

Calculate the IFFT of a double-sided Fourier spectrum.

The function takes double-sided spectrum and returns a time signal. The normalization is considered according to 'fft_norm' as described in normalization and FFT concepts.

Parameters:
  • spec (array, complex) – The complex valued right-hand side of the spectrum with dimensions (…, n_bins)

  • n_samples (int) – The number of samples of the corresponding time signal. This is crucial to allow for the correct transform of time signals with an odd number of samples.

  • sampling_rate (number) – sampling rate in Hz

  • fft_norm ('none', 'unitary', 'amplitude', 'rms', 'power', 'psd') – See normalization.

Returns:

data – Array containing the time domain signal with dimensions (…, 'n_samples')

Return type:

array, double

pyfar.dsp.fft.irfft(spec, n_samples, sampling_rate, fft_norm)[source]#

Calculate the IFFT of a single-sided Fourier spectrum.

The function takes only the right-hand side of the spectrum and returns a real-valued time signal. Details on the FFT normalization given by fft_norm are given found above.

Parameters:
  • spec (array, complex) – The complex valued right-hand side of the spectrum with dimensions (…, n_bins)

  • n_samples (int) – The number of samples of the corresponding time signal. This is crucial to allow for the correct transform of time signals with an odd number of samples.

  • sampling_rate (number) – sampling rate in Hz

  • fft_norm ('none', 'unitary', 'amplitude', 'rms', 'power', 'psd') – See normalization.

Returns:

data – Array containing the time domain signal with dimensions (…, 'n_samples')

Return type:

array, double

pyfar.dsp.fft.normalization(spec, n_samples, sampling_rate, fft_norm='none', inverse=False, single_sided=True, window=None)[source]#

Normalize a Fourier spectrum.

Apply normalizations defined in [1] to the DFT spectrum. Note that the phase is maintained in all cases, i.e., instead of taking the squared absolute values for 'power' and 'psd', the complex spectra are multiplied with their absolute values to ensure a correct renormalization. Details on the FFT normalization given by fft_norm are given above.

Parameters:
  • spec (numpy array) – N dimensional array which has the frequency bins in the last dimension. E.g., spec.shape == (10,2,129) holds 10 times 2 spectra with 129 frequency bins each.

  • n_samples (int) – number of samples of the corresponding time signal

  • sampling_rate (number) – sampling rate of the corresponding time signal in Hz

  • fft_norm (string, optional) –

    'none'

    Do not apply any normalization. Appropriate for energy signals such as impulse responses.

    'unitary'

    Multiply spec by factor of two as in [1] Eq. (8) (except for 0 Hz and the Nyquist frequency at half the sampling rate) to obtain the single-sided spectrum.

    'amplitude'

    Scale spectrum by 1/n_samples as in [1] Eq. (4) to obtain the amplitude spectrum.

    ’rms’

    Scale spectrum by \(1/\sqrt{2}\) as in [1] Eq.(10) to obtain the RMS spectrum.

    ’power’

    Power spectrum, which equals the squared RMS spectrum (except for the retained phase).

    ’psd’

    The power spectrum is scaled by n_samples/sampling_rate as in [1] Eq. (6)

    Note that the unitary normalization is also applied for amplitude, rms, power, and psd if the input spectrum is single sided (see single_sided).

  • inverse (bool, optional) – apply the inverse normalization. The default is False.

  • single_sided (bool, optional) – denotes if spec is a single sided spectrum up to half the sampling rate or a both sided (full) spectrum. If single_sided=True the unitary normalization according to [1] Eq. (8) is applied unless fft_norm='none'. The default is True.

  • window (None, array like) – window that was applied to the time signal before performing the FFT. Affects the normalization as in [1] Eqs. (11-13). The window must be an array-like with n_samples length and. The default is None, which denotes that no window was applied.

Returns:

spec – normalized input spectrum

Return type:

numpy array

References

pyfar.dsp.fft.remove_mirror_spectrum(data_double_sided)[source]#

Checks if the data are conjugate symmetric and removes the redundand mirror spectrum of double-sided frequency data. The output is a single-sided spectrum that matches the format of rfft.

Parameters:

data_double_sided (numpy array) – M-dimensional array of double-sided spectrum of shape (…, N) containing N frequency bins. The 0 Hz bin must always be at index data.shape[-1] // 2.

Returns:

data – M-dimensional array of single-sided spectrum of shape (…, N//2+1) containing N//2+1 frequency bins.

Return type:

numpy array

pyfar.dsp.fft.rfft(data, n_samples, sampling_rate, fft_norm)[source]#

Calculate the FFT of a real-valued time-signal.

The function returns only the right-hand side of the axis-symmetric spectrum. Details on the FFT normalization given by fft_norm are given above.

Parameters:
  • data (array, double) – Array containing the time domain signal with dimensions (…, 'n_samples')

  • n_samples (int) – The number of samples

  • sampling_rate (number) – sampling rate in Hz

  • fft_norm ('none', 'unitary', 'amplitude', 'rms', 'power', 'psd') – See documentation of normalization.

Returns:

spec – The complex valued right-hand side of the spectrum with dimensions (…, n_bins)

Return type:

array, complex

pyfar.dsp.fft.rfftfreq(n_samples, sampling_rate)[source]#

Returns the positive discrete frequencies for which the FFT is calculated.

If the number of samples \(N\) is even the number of frequency bins will be \(2/N+1\), if \(N\) is odd, the number of bins will be \((N+1)/2\).

Parameters:
  • n_samples (int) – The number of samples in the signal

  • sampling_rate (int) – The sampling rate of the signal

Returns:

frequencies – The positive discrete frequencies in Hz for which the FFT is calculated.

Return type:

array, double