Macaw.Data.FFT (macaw_data v0.12.0)
View SourceThe fast Fourier transform of a real or complex sequence (spec/04 §4.11): a radix-2
Cooley–Tukey decimation in time over lists, O(N log N), pure Elixir. The engine of the
spectrum transform, ported from visualize's Visualize.Data.FFT.
A time series becomes its frequency spectrum through spectrum/3: the newest power of
two of samples, tapered by a window, transformed, and read as one-sided amplitudes —
what the spectrum transform of spec/04 §4.11 answers.
iex> Macaw.Data.FFT.fft!([1, 0, 0, 0])
[{1.0, 0.0}, {1.0, 0.0}, {1.0, 0.0}, {1.0, 0.0}]
Summary
Types
A complex number as {re, im}.
One line of a spectrum.
Why a transform or a spectrum is refused (format_error/1).
Functions
The discrete Fourier transform of a sequence whose length is a power of two: numbers
are taken as real, {re, im} pairs as complex, {:ok, terms}. Any other length is
{:error, {:samples, n}}, and a term that is neither {:error, {:values, :number}}
(spec/00 §5); fft!/1 answers the terms or raises.
As fft/1, the terms alone, raising Macaw.Data.Error in format_error/1's words.
A refusal's words.
The magnitude sqrt(re² + im²) of every term.
The one-sided amplitude spectrum of a series sampled every every seconds: the newest
samples values (the largest power of two not above the count when not given), tapered
by window (:hann), transformed, and read as samples / 2 lines — frequency is
k / (samples · every) hertz, magnitude the amplitude |X_k| · 2 / (samples · gain)
with the window's mean gain divided out (the DC line not doubled), phase the argument
of X_k, as {:ok, lines}. Fewer than two values yield {:ok, []}. A refusal is
{:error, reason} (spec/00 §5): {:samples, s}, {:window, kind}, {:every, every}
or {:values, :number}; spectrum!/3 answers the lines or raises.
As spectrum/3, the lines alone, raising Macaw.Data.Error in format_error/1's words.
The sequence tapered by a window: :hann (0.5 − 0.5 cos(2πi/(N−1))), :hamming
(0.54 − 0.46 cos(2πi/(N−1))) or :none; a sequence shorter than four is not tapered.
Types
A complex number as {re, im}.
One line of a spectrum.
Why a transform or a spectrum is refused (format_error/1).
Functions
The discrete Fourier transform of a sequence whose length is a power of two: numbers
are taken as real, {re, im} pairs as complex, {:ok, terms}. Any other length is
{:error, {:samples, n}}, and a term that is neither {:error, {:values, :number}}
(spec/00 §5); fft!/1 answers the terms or raises.
iex> {:ok, terms} = Macaw.Data.FFT.fft([0, 1, 0, -1])
iex> Enum.map(terms, fn {re, im} -> {Float.round(re, 9) + 0.0, Float.round(im, 9) + 0.0} end)
[{0.0, 0.0}, {0.0, -2.0}, {0.0, 0.0}, {0.0, 2.0}]
iex> Macaw.Data.FFT.fft([1, 2, 3])
{:error, {:samples, 3}}
As fft/1, the terms alone, raising Macaw.Data.Error in format_error/1's words.
A refusal's words.
iex> Macaw.Data.FFT.format_error({:samples, 12})
"the FFT takes a power of two of samples, not 12"
The magnitude sqrt(re² + im²) of every term.
The one-sided amplitude spectrum of a series sampled every every seconds: the newest
samples values (the largest power of two not above the count when not given), tapered
by window (:hann), transformed, and read as samples / 2 lines — frequency is
k / (samples · every) hertz, magnitude the amplitude |X_k| · 2 / (samples · gain)
with the window's mean gain divided out (the DC line not doubled), phase the argument
of X_k, as {:ok, lines}. Fewer than two values yield {:ok, []}. A refusal is
{:error, reason} (spec/00 §5): {:samples, s}, {:window, kind}, {:every, every}
or {:values, :number}; spectrum!/3 answers the lines or raises.
Options
:samples- the window length, a power of two:window- one ofwindows/0(default:hann):detrend- subtract the window's mean before transforming, so an offset does not leak from the DC line into its neighbors (defaultfalse)iex> every = 1 / 64 iex> values = for i <- 0..63, do: :math.sin(2 :math.pi() 8 i every) iex> {:ok, lines} = Macaw.Data.FFT.spectrum(values, every, window: :none) iex> peak = Enum.max_by(lines, & &1.magnitude) iex> {length(lines), Float.round(peak.frequency, 6), Float.round(peak.magnitude, 6)} {32, 8.0, 1.0}
As spectrum/3, the lines alone, raising Macaw.Data.Error in format_error/1's words.
The sequence tapered by a window: :hann (0.5 − 0.5 cos(2πi/(N−1))), :hamming
(0.54 − 0.46 cos(2πi/(N−1))) or :none; a sequence shorter than four is not tapered.
iex> Macaw.Data.FFT.window([1, 1, 1, 1, 1], :hann) |> Enum.map(&Float.round(&1, 3))
[0.0, 0.5, 1.0, 0.5, 0.0]
@spec windows() :: [atom(), ...]
The window functions window/2 applies, :hann first.