Acoustics module

[hivanov-nrel]

Acoustics Module Parity

This PR is meant to bring the acoustics module from MHKiT-Python to MHKiT-MATLAB as part of the parity goal.

IO

• read_hydrophone
• read_soundtrap
• read_iclisten
• export_audio --- Not implemented since matlab has a built-in audio player
• _read_wav_metadata --- this is not necessary since matlab have built in function to read audiofile
• _calculate_voltage_and_time --- this is not necessary since matlab have built in function to read audiofile

Analysis

• _fmax_warning
• minimum_frequency
• sound_pressure_spectral_density
• apply_calibration
• sound_pressure_spectral_density_level
• band_aggregate
• time_aggregate
• nmfs_auditory_weighting
• sound_exposure_level
• sound_pressure_level
• _band_sound_pressure_level
• third_octave_sound_pressure_level
• decidecade_sound_pressure_level

Graphics

• plot_spectrogram
• plot_spectra

Reviewer notes

• export_audio was not implemented since matlab has a built-in audio player
• Several of the helper functions for reading audio were not included since matlab has a built in function that has similar functionality
• Note that the execution of matlab's audioread is significantly slower than python implementation. It can take several minutes to read in some of the example audio files. Interestingly, this is only when running the notebook examples. Otherwise the function runs fast during tests.
• The 'method' functionality is not as extensive as the one in python. The list of available statistical functions is reduced due to implementation constraints.
• James - I used your original matlab code for building out the base function (sound pressure spectral density). Because of the differences in resolution, I had to change a lot of the "known" values in the tests. Part of my sanity checks was comparing the plots in the example, which yielded very similar results to the Python side, but it might be worth checking that function in particular to make sure the calculations are correct.
• I have not done anything with the matlab toolbox to add this module

Changelog info

Acoustics Module

• Introduced a new Acoustics module to MHKiT, providing comprehensive tools for processing and analyzing passive acoustic data from hydrophone recordings.
• Designed to facilitate compliance with the IEC-TS 62600-40 standard
• Supports hydrophone models such as SoundTrap and icListen, with functionality to read, calibrate, and process hydrophone data into acoustic metrics.
• Includes functionalities for:
  • Reading hydrophone data.
  • Performing spectral analyses.
    • spectral density (SPSD)
    • spectral density levels (SPSDL)
    • fractional octave bands (e.g., third-octave, decidecade)
    • Sound Pressure Level (SPL)
  • Applying calibrations.
  • Calculating sound pressure levels.
  • Visualizing results.

To support users, an example notebook demonstrates the application of this module with workflows

[jmcvey3]

Looks good from a coding standpoint.

[simmsa]

@hivanov-nrel, this looks good! My comments/fixes were added here:

hivanov-nrel#1

Thank you for this addition!

[simmsa]

@hivanov-nrel, this is good to go. I will merge once the tests finish...