dft

function of dascore.transform.fourier source

dft(
    patch: Patch ,
    dim: str | None | collections.abc.Sequence[str, None, collections.abc.Sequence[str]] ,
    real: str | bool | None[str, bool, None] = None,
    pad: bool = True,
    output: Literal[‘FFT’, ‘PSD’, ‘PS’, ‘AS’] = FFT,
    db: bool = False,
)-> ‘PatchType’

Perform the discrete Fourier transform (dft) on specified dimension(s).

Parameters

Parameter Description
patch Patch to transform.
dim A single, or multiple dimensions over which to perform dft. If
None, perform dft over all dimensions.
real Either 1) The name of the axis over which to perform a rfft, 2)
True, which means the last (possibly only) dimenson should have an
rfft performed, or 3) None, meaning no rfft.
pad If True, pad patch before performing dft along desired dimensions to
the next fast length. This can avoid major slow-downs when dimension
lengths are prime numbers.
output Spectral representation to return for each frequency bin
- 'FFT': Complex Fourier coefficients scaled by sample spacing.
- 'AS': Amplitude spectrum in the original data units.
- 'PS': Power spectrum whose bin sum gives mean square.
- 'PSD': Spectral density whose bin-width-weighted sum gives
mean square.
db If True, converts the output into decibel units, if output is not FFT.
This applies 20 * log10 to 'AS' and 10 * log10 to 'PS'
or 'PSD' without a reference value.
Note

  • Simply uses numpy’s fft module but outputs are scaled by the sample spacing along each transformed dimension and coordinates corresponding to frequency bins are shifted so they remain ordered.

  • Each transformed dimension is renamed with a preceding ft_. e.g., time becomes ft_time (ft stands for fourier transform).

  • Each transformed dimension has units of 1/original units.

  • For output='FFT', output data units are the original data units multiplied by the units of each transformed dimension. Other output types are normalized as described in the output parameter.

  • For output='AS', 'PS', or 'PSD' with real=True, the non-DC and non-Nyquist bins have not been converted to one-sided spectra. Depending on your use case, you may need to multiply non-zero bins by 2.

  • If all requested dimensions are already transformed, dft returns the input patch unchanged, regardless of the requested output.

  • Non-dimensional coordinates associated with transformed coordinates will be dropped in the output.

  • See the FFT notes for more details.

See Also

Examples

import dascore as dc
patch = dc.get_example_patch()
# perform dft (fft) on time axis
dft_time = patch.dft(dim="time")
# make it a real fft (no negative frequencies)
dft_time_real = patch.dft(dim="time", real=True)
# dft on specified dimensions, specify real dimension
dft_some_real = patch.dft(dim=("time", "distance"), real="time")
# calculate a power spectral density along time
psd = patch.dft(dim="time", real=True, output="PSD")