Struct spectrum_analyzer::FrequencySpectrum

pub struct FrequencySpectrum { /* private fields */ }

Convenient wrapper around the processed FFT result which describes each frequency and its value/amplitude in the analyzed slice of samples. It only consists of the frequencies which were desired, e.g. specified via crate::limit::FrequencyLimit when crate::samples_fft_to_spectrum was called.

This means, the spectrum can cover all data from the DC component (0Hz) to the Nyquist frequency.

All results are related to the sampling rate provided to the library function which creates objects of this struct!

Implementations

impl FrequencySpectrum

pub fn new(
    data: Vec<(Frequency, FrequencyValue)>,
    frequency_resolution: f32,
    samples_len: u32
) -> Self

Creates a new object. Calculates several metrics from the data in the given vector.

Parameters

• data Vector with all (Frequency, FrequencyValue)-tuples
• frequency_resolution Resolution in Hertz. This equals to data[1].0 - data[0].0.
• samples_len Number of samples. Might be bigger than data.len() if the spectrum is obtained with a frequency limit.

pub fn apply_scaling_fn(
    &self,
    scaling_fn: SpectrumScalingFunction<'_>
) -> Result<(), SpectrumAnalyzerError>

Applies the function scaling_fn to each element and updates min, max, etc. afterwards accordingly. It ensures that no value is NaN or Infinity afterwards (regarding IEEE-754).

Parameters

• scaling_fn See crate::scaling::SpectrumScalingFunction.

pub fn average(&self) -> FrequencyValue

Returns the average frequency value of the spectrum.

pub fn median(&self) -> FrequencyValue

Returns the median frequency value of the spectrum.

pub fn max(&self) -> (Frequency, FrequencyValue)

Returns the maximum (frequency, frequency value)-pair of the spectrum (regarding the frequency value).

pub fn min(&self) -> (Frequency, FrequencyValue)

Returns the minimum (frequency, frequency value)-pair of the spectrum (regarding the frequency value).

pub fn range(&self) -> FrequencyValue

Returns [FrequencySpectrum::max().1] - [FrequencySpectrum::min().1], i.e. the range of the frequency values (not the frequencies itself, but their amplitudes/values).

pub fn data(&self) -> Ref<'_, Vec<(Frequency, FrequencyValue)>>

Returns the underlying data.

pub const fn frequency_resolution(&self) -> f32

Returns the frequency resolution of this spectrum.

pub const fn samples_len(&self) -> u32

Returns the number of samples used to obtain this spectrum.

pub fn max_fr(&self) -> Frequency

Getter for the highest frequency that is captured inside this spectrum. Shortcut for spectrum.data()[spectrum.data().len() - 1].0. This corresponds to the crate::limit::FrequencyLimit of the spectrum.

This method could return the Nyquist frequency, if there was no Frequency limit while obtaining the spectrum.

pub fn min_fr(&self) -> Frequency

Getter for the lowest frequency that is captured inside this spectrum. Shortcut for spectrum.data()[0].0. This corresponds to the crate::limit::FrequencyLimit of the spectrum.

This method could return the DC component, see Self::dc_component.

pub fn dc_component(&self) -> Option<FrequencyValue>

Returns the DC Component or also called DC bias which corresponds to the FFT result at index 0 which corresponds to 0Hz. This is only present if the frequencies were not limited to for example 100 <= f <= 10000 when the libraries main function was called.

More information: https://dsp.stackexchange.com/questions/12972/discrete-fourier-transform-what-is-the-dc-term-really

Excerpt: As far as practical applications go, the DC or 0 Hz term is not particularly useful. In many cases it will be close to zero, as most signal processing applications will tend to filter out any DC component at the analogue level. In cases where you might be interested it can be calculated directly as an average in the usual way, without resorting to a DFT/FFT. - Paul R.

pub fn freq_val_exact(&self, search_fr: f32) -> FrequencyValue

Returns the value of the given frequency from the spectrum either exactly or approximated. If search_fr is not exactly given in the spectrum, i.e. due to the Self::frequency_resolution, this function takes the two closest neighbors/points (A, B), put a linear function through them and calculates the point C in the middle. This is done by the private function calculate_y_coord_between_points.

Panics

If parameter search_fr (frequency) is below the lowest or the maximum frequency, this function panics! This is because the user provide the min/max frequency when the spectrum is created and knows about it. This is similar to an intended “out of bounds”-access.

Parameters

• search_fr The frequency of that you want the amplitude/value in the spectrum.

Return

Either exact value of approximated value, determined by Self::frequency_resolution.

pub fn freq_val_closest(&self, search_fr: f32) -> (Frequency, FrequencyValue)

Returns the frequency closest to parameter search_fr in the spectrum. For example if the spectrum looks like this:

Vector:    [0]      [1]      [2]      [3]
Frequency  100 Hz   200 Hz   300 Hz   400 Hz
Fr Value   0.0      1.0      0.5      0.1

then get_frequency_value_closest(320) will return (300.0, 0.5).

Panics

If parameter search_fre (frequency) is below the lowest or the maximum frequency, this function panics!

Parameters

• search_fr The frequency of that you want the amplitude/value in the spectrum.

Return

Closest matching point in spectrum, determined by Self::frequency_resolution.

pub fn to_map(
    &self,
    scale_fn: Option<&dyn Fn(f32) -> u32>
) -> BTreeMap<u32, f32>

Returns a BTreeMap. The key is of type u32. (f32 is not Ord, hence we can’t use it as key.) You can optionally specify a scale function, e.g. multiply all frequencies with 1000 for better accuracy when represented as unsigned integer.

Parameters

• scale_fn optional scale function, e.g. multiply all frequencies with 1000 for better accuracy when represented as unsigned integer.

Return

New BTreeMap from frequency to frequency value.

Trait Implementations

impl Debug for FrequencySpectrum

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FrequencySpectrum

fn default() -> FrequencySpectrum

Returns the “default value” for a type.