API Reference

rfft!(y, x, cache=nothing)

Calculate the real-input FFT of `x` and store the result in half-complex format in `y`.

Just a wrapper of `FFTW.r2r!(y, FFTW.R2HC)`. The `cache` argument is
optional and not used, and is included to keep the function signiture the
same as the method that takes `Vector`s of `Dual`s.

irfft!(y, x, cache=nothing)

Calculate the inverse FFT of `x` and store the result in in `y`, where `x` is in the half-complex format.

Just a wrapper of `FFTW.r2r!(y, FFTW.HC2R)`. The `cache` argument is
optional and not used, and is included to keep the function signiture the
same as the method that takes `Vector`s of `Dual`s.

AbstractPressureTimeHistory{IsEven}

Supertype for a pressure time history, i.e., pressure as a function of time defined on evenly-spaced time samples.

The IsEven parameter is a Bool indicating if the length of the pressure time history is even or not.

PressureTimeHistory{IsEven} <: AbstractPressureTimeHistory{IsEven}

Pressure as a function of time defined on evenly-spaced time samples.

The IsEven parameter is a Bool indicating if the length of the pressure time history is even or not.

pressure(pth::AbstractPressureTimeHistory)

Return a vector of pressures associated with a pressure time history.

inputlength(pth::AbstractPressureTimeHistory)

Return a number of pressure samples associated with a pressure time history.

inputlength(sm::AbstractNarrowbandSpectrum)

Return a number of pressure time samples associated with a narrowband spectrum.

This is also the length of the discrete Fourier transform associated with the spectrum in half-complex format.

timestep(pth::AbstractPressureTimeHistory)

Return the time step size dt associated with a pressure time history.

starttime(pth::AbstractPressureTimeHistory)

Return the initial time t0 associated with a pressure time history.

time(pth::AbstractPressureTimeHistory)

Return a vector of times associated with a pressure time history.

AbstractNarrowbandSpectrum{IsEven,IsTonal,Tel} <: AbstractVector{Tel}

Supertype for a generic narrowband acoustic metric which will behave as an immutable AbstractVector of element type Tel.

The IsEven parameter is a Bool indicating if the length of the spectrum is even or not, affecting how the Nyquist frequency is calculated. IsTonal indicates how the acoustic energy is distributed through the frequency bands:

• IsTonal == false means the acoustic energy is assumed to be evenly distributed thoughout each band
• IsTonal == true means the acoustic energy is assumed to be concentrated at each band center

halfcomplex(sm::AbstractNarrowbandSpectrum)

Return a vector of the discrete Fourier transform of the pressure time history in half-complex format.

See the FFTW docs for the definition of the halfcomplex format.

timestep(sm::AbstractNarrowbandSpectrum)

Return the time step size dt associated with a narrowband spectrum.

starttime(sm::AbstractNarrowbandSpectrum)

Return the initial time t0 associated with a pressure time history.

samplerate(sm::AbstractNarrowbandSpectrum)

Return the sample rate (aka the inverse of the time step size) associated with a narrowband spectrum.

frequency(sm::AbstractNarrowbandSpectrum)

Return a vector of frequencies associated with the narrowband spectrum.

The frequencies are calculated using the rfftfreq function in the FFTW.jl package.

frequencystep(sm::AbstractNarrowbandSpectrum)

Return the frequency step size Δf associated with the narrowband spectrum.

istonal(sm::AbstractNarrowbandSpectrum)

Return true if the spectrum is tonal, false otherwise.

PressureSpectrumAmplitude{IsEven,IsTonal,Tel} <: AbstractNarrowbandSpectrum{IsEven,IsTonal,Tel}

Representation of acoustic pressure amplitude as a function of narrowband frequency.

The IsEven parameter is a Bool indicating if the length of the spectrum is even or not, affecting how the Nyquist frequency is calculated. The IsTonal Bool parameter, if true, indicates the pressure spectrum is tonal and thus concentrated at discrete frequencies. If false, the spectrum is assumed to be constant over each frequency band.

PressureSpectrumPhase{IsEven,IsTonal,Tel} <: AbstractNarrowbandSpectrum{IsEven,IsTonal,Tel}

Representation of acoustic pressure phase as a function of narrowband frequency.

The IsEven parameter is a Bool indicating if the length of the spectrum is even or not, affecting how the Nyquist frequency is calculated. The IsTonal Bool parameter, if true, indicates the phase spectrum is tonal and thus concentrated at discrete frequencies. If false, the spectrum is assumed to be constant over each frequency band.

MSPSpectrumAmplitude{IsEven,IsTonal,Tel} <: AbstractNarrowbandSpectrum{IsEven,IsTonal,Tel}

Representation of mean-squared pressure amplitude as a function of narrowband frequency.

The IsEven parameter is a Bool indicating if the length of the spectrum is even or not, affecting how the Nyquist frequency is calculated. The IsTonal Bool parameter, if true, indicates the mean-squared pressure spectrum is tonal and thus concentrated at discrete frequencies. If false, the pressure spectrum is assumed to be constant over each frequency band.

MSPSpectrumPhase

Alias for PressureSpectrumPhase.

PowerSpectralDensityAmplitude{IsEven,Tel} <: AbstractNarrowbandSpectrum{IsEven,false,Tel}

Representation of acoustic power spectral density amplitude as a function of narrowband frequency.

The IsEven parameter is a Bool indicating if the length of the spectrum is even or not, affecting how the Nyquist frequency is calculated. As the power spectral density is not well-defined for tones, the IsTonal parameter is always false.

PowerSpectralDensityPhase

Alias for PressureSpectrumPhase.

AbstractProportionalBands{NO,LCU,TF} <: AbstractVector{TF}

Abstract type representing the exact proportional frequency bands with band fraction NO and eltype TF.

The LCU parameter can take one of three values:

• :lower: The struct returns the lower edges of each frequency band.
• :center: The struct returns the center of each frequency band.
• :upper: The struct returns the upper edges of each frequency band.

octave_fraction(bands::AbstractProportionalBands{NO}) where {NO}

Return NO, the "octave fraction," e.g. 1 for octave bands, 3 for third-octave, 12 for twelfth-octave.

octave_fraction(pbs::AbstractProportionalBandSpectrum{NO}) where {NO}

Return NO, the "octave fraction," e.g. 1 for octave bands, 3 for third-octave, 12 for twelfth-octave.

lower_center_upper(bands::AbstractProportionalBands{NO,LCU,TF}) where {NO,LCU,TF}

Return LCU, which can be either :lower, :center, :upper, indicating if bands represents the lower edges, centers, or upper edges of proportional bands, respectively.

freq_scaler(bands::AbstractProportionalBands)

Return the factor each "standard" frequency band is scaled by.

For example, the approximate octave center bands include 1000 Hz, 2000 Hz, and 4000 Hz. If freq_scaler(bands) == 1.0, then these frequencies would be unchanged. If freq_scaler(bands) == 1.5, then bands would include 1500 Hz, 3000 Hz, and 6000 Hz instead. If freq_scaler(bands) == 0.5, then bands would include 500 Hz, 1000 Hz, and 2000 Hz in place of 1000 Hz, 2000 Hz, and 4000 Hz.

freq_scaler(pbs::AbstractProportionalBandSpectrum)

Return the factor each "standard" frequency band associated with the proportional band spectrum pbs is scaled by.

For example, the approximate octave center bands include 1000 Hz, 2000 Hz, and 4000 Hz. If freq_scaler(pbs) == 1.0, then these frequencies would be unchanged. If freq_scaler(pbs) == 1.5, then bands would include 1500 Hz, 3000 Hz, and 6000 Hz instead. If freq_scaler(pbs) == 0.5, then bands would include 500 Hz, 1000 Hz, and 2000 Hz in place of 1000 Hz, 2000 Hz, and 4000 Hz.

band_start(bands::AbstractProportionalBands)

Return the standard band index number for the first band in bands.

For example, it happens that the approximate octave center bands includes 1000 Hz, and that particular band is numbered 10. So if the first band contained in bands happens to be 1000 Hz (and freq_scaler(bands) == 1.0), then band_start(bands) == 10. Not particularly useful to a user.

band_end(bands::AbstractProportionalBands)

Return the standard band index number for the last band in bands.

For example, it happens that the approximate octave center bands includes 1000 Hz, and that particular band is numbered 10. So if the last band contained in bands happens to be 1000 Hz (and freq_scaler(bands) == 1.0), then band_end(bands) == 10. Not particularly useful to a user.

lower_bands(TBands::Type{<:AbstractProportionalBands{NO}}, fstart::TF, fend::TF, scaler=1) where {NO,TF}

Construct and return the lower edges of the proportional bands TBands, scaled by scaler, that would fully encompass a frequency range beginning with fstart and ending with fend.

lowerbands(bands::ExactProportionalBands{NO,LCU,TF}, scaler=freqscaler(bands)) where {NO,TF}

Construct and return the lower edges of the proportional bands bands scaled by scaler.

lowerbands(bands::ApproximateThirdOctaveBands{LCU,TF}, scaler=freqscaler(bands)) where {LCU,TF}

Construct and return the lower edges of the proportional bands bands scaled by scaler.

lower_bands(bands::ApproximateOctaveBands{LCU,TF}, scaler=freq_scaler(bands))

Construct and return the lower edges of the proportional bands bands scaled by scaler.

lower_bands(pbs::AbstractProportionalBandSpectrum)

Return the lower edges of the proportional bands associated with the proportional band spectrum pbs.

upper_bands(TBands::Type{<:AbstractProportionalBands{NO}}, fstart::TF, fend::TF, scaler=1) where {NO,TF}

Construct and return the upper edges of the proportional bands TBands, scaled by scaler, that would fully encompass a frequency range beginning with fstart and ending with fend.

upperbands(bands::ExactProportionalBands{NO,LCU,TF}, scaler=freqscaler(bands)) where {NO,TF}

Construct and return the upper edges of the proportional bands bands scaled by scaler.

upperbands(bands::ApproximateThirdOctaveBands{LCU,TF}, scaler=freqscaler(bands)) where {LCU,TF}

Construct and return the upper edges of the proportional bands bands scaled by scaler.

upper_bands(bands::ApproximateOctaveBands{LCU,TF}, scaler=freq_scaler(bands))

Construct and return the upper edges of the proportional bands bands scaled by scaler.

upper_bands(pbs::AbstractProportionalBandSpectrum)

Return the upper edges of the proportional bands associated with the proportional band spectrum pbs.

center_bands(TBands::Type{<:AbstractProportionalBands{NO}}, fstart::TF, fend::TF, scaler=1) where {NO,TF}

Construct and return the centers of the proportional bands TBands, scaled by scaler, that would fully encompass a frequency range beginning with fstart and ending with fend.

centerbands(bands::ExactProportionalBands{NO,LCU,TF}, scaler=freqscaler(bands)) where {NO,TF}

Construct and return the centers of the proportional bands bands scaled by scaler.

centerbands(bands::ApproximateThirdOctaveBands{LCU,TF}, scaler=freqscaler(bands)) where {LCU,TF}

Construct and return the centers of the proportional bands bands scaled by scaler.

center_bands(bands::ApproximateOctaveBands{LCU,TF}, scaler=freq_scaler(bands))

Construct and return the centers of the proportional bands bands scaled by scaler.

center_bands(pbs::AbstractProportionalBandSpectrum)

Return the centers of the proportional bands associated with the proportional band spectrum pbs.

cband_number(bands::AbstractProportionalBands, fc)

Return the standard band index number of the band with center frequency fc for proportional bands bands.

For example, if bands is a subtype of ApproximateOctaveBands and freq_scaler(bands) == 1.0, then cband_number(bands, 1000.0) == 10.

ExactProportionalBands{NO,LCU,TF} <: AbstractProportionalBands{NO,LCU,TF}

Representation of the exact proportional frequency bands with band fraction NO and eltype TF.

The LCU parameter can take one of three values:

• :lower: The struct returns the lower edges of each frequency band.
• :center: The struct returns the center of each frequency band.
• :upper: The struct returns the upper edges of each frequency band.

ExactOctaveCenterBands{TF}

Alias for ExactProportionalBands{1,:center,TF}

ExactOctaveLowerBands{TF}

Alias for ExactProportionalBands{1,:lower,TF}

ExactOctaveUpperBands{TF}

Alias for ExactProportionalBands{1,:upper,TF}

ExactThirdOctaveCenterBands{TF}

Alias for ExactProportionalBands{3,:center,TF}

ExactThirdOctaveLowerBands{TF}

Alias for ExactProportionalBands{3,:lower,TF}

ExactThirdOctaveUpperBands{TF}

Alias for ExactProportionalBands{3,:upper,TF}

ApproximateThirdOctaveBands{LCU,TF} <: AbstractProportionalBands{3,LCU,TF}

Representation of the approximate third-octave proportional frequency bands with eltype TF.

The LCU parameter can take one of three values:

• :lower: The struct returns the lower edges of each frequency band.
• :center: The struct returns the center of each frequency band.
• :upper: The struct returns the upper edges of each frequency band.

ApproximateThirdOctaveCenterBands{TF}

Alias for ApproximateThirdOctaveBands{:center,TF}

ApproximateThirdOctaveLowerBands{TF}

Alias for ApproximateThirdOctaveBands{:lower,TF}

ApproximateThirdOctaveUpperBands{TF}

Alias for ApproximateThirdOctaveBands{:upper,TF}

ApproximateOctaveBands{LCU,TF} <: AbstractProportionalBands{1,LCU,TF}

Representation of the approximate octave proportional frequency bands with eltype TF.

The LCU parameter can take one of three values:

• :lower: The struct returns the lower edges of each frequency band.
• :center: The struct returns the center of each frequency band.
• :upper: The struct returns the upper edges of each frequency band.

ApproximateOctaveCenterBands{TF}

Alias for ApproximateOctaveBands{:center,TF}

ApproximateOctaveLowerBands{TF}

Alias for ApproximateOctaveBands{:lower,TF}

ApproximateOctaveUpperBands{TF}

Alias for ApproximateOctaveBands{:upper,TF}

AbstractProportionalBandSpectrum{NO,TF} <: AbstractVector{TF}

Abstract type representing a proportional band spectrum with band fraction NO and eltype TF.

has_observer_time(pbs::AbstractProportionalBandSpectrum)

Return true if the proportional band spectrum is defined to exist over a limited time, false otherwise.

observer_time(pbs::AbstractProportionalBandSpectrum)

Return the observer time at which the proportional band spectrum is defined to exist.

timestep(pbs::AbstractProportionalBandSpectrum)

Return the time range over which the proportional band spectrum is defined to exist.

amplitude(pbs::AbstractProportionalBandSpectrum)

Return the underlying Vector containing the proportional band spectrum amplitudes contained in pbs.

time_period(pbs::AbstractArray{<:AbstractProportionalBandSpectrum})

Find the period of time over which the collection of proportional band spectrum pbs exists.

time_scaler(pbs::AbstractProportionalBandSpectrum{NO,TF}, period)

Find the scaling factor appropriate to multiply the proportional band spectrum pbs by that accounts for the duration of time the spectrum exists.

This is used when combining multiple proportional band spectra with the combine function.

LazyNBProportionalBandSpectrum{NO,IsTonal,TF,TAmp,TBandsC}

Lazy representation of a proportional band spectrum with octave fraction NO and eltype TF constructed from a narrowband (NB) spectrum.

IsTonal indicates how the acoustic energy is distributed through the narrow frequency bands:

• IsTonal == false means the acoustic energy is assumed to be evenly distributed thoughout each band
• IsTonal == true means the acoustic energy is assumed to be concentrated at each band center

frequency_nb(pbs::LazyNBProportionalBandSpectrum)

Return the narrowband frequencies associated with the underlying narrowband spectrum contained in pbs.

lazy_pbs(pbs, cbands::AbstractProportionalBands{NO,:center})

Construct a lazy proportional band spectrum on proportional center bands cbands using the proportional band spectrum pbs.

ProportionalBandSpectrum{NO,TF,TPBS,TBandsL,TBandsC,TBandsU}

Representation of a proportional band spectrum with octave fraction NO and eltype TF.

LazyPBSProportionalBandSpectrum{NO,TF} <: AbstractProportionalBandSpectrum{NO,TF}

Lazy representation of a proportional band spectrum with octave fraction NO and eltype TF constructed from a different proportional band spectrum.

ProportionalBandSpectrumWithTime{NO,TF,TPBS,TBandsC,TTime,TDTime}

Representation of a proportional band spectrum with octave fraction NO and eltype TF, but with an observer time.

combine(pbs::AbstractArray{<:AbstractProportionalBandSpectrum}, outcbands::AbstractProportionalBands{NO,:center}, time_axis=1) where {NO}

Combine each input proportional band spectrum of pbs into one output proportional band spectrum using the proportional center bands indicated by outcbands.

time_axis is an integer indicating the axis of the pbs array along which time varies. For example, if time_axis == 1 and pbs is a three-dimensional array, then apth[:, i, j] would be proportional band spectrum of source i, j for all time. But if time_axis == 3, then pbs[i, j, :] would be the proportional band spectrum of source i, j for all time.

W_A(f::AbstractFloat)

Calculate the A-weighting factor for a frequency f in Hertz.

Taken from the ANOPP2 Acoustics Analysis API Reference Manual.

OASPL(ap::AbstractPressureTimeHistory)

Return the overall sound pressure level of a pressure time history.

OASPL(ap::AbstractNarrowbandSpectrum)

Return the overall sound pressure level of a narrowband spectrum.