Skip to content

MUPET wiki

Jump to bottom Edit New page
Maarten Van Segbroeck edited this page Oct 4, 2018 · 95 revisions

Welcome to the MUPET wiki!

Here you can find an easy to follow manual that will guide you step-by-step through the MUPET tool.

Installation procedure

  1. To run MUPET on your computer you need to have Matlab installed first.
  2. Download MUPET from:
  3. Download ZIP link on the MUPET github page, or
  4. git clone https://github.com/mvansegbroeck/mupet.git
  5. Open Matlab, go to the installed directory and type > mupet
  6. Try out MUPET with sample USV data files
  7. 20 sample C57BL/6 wave files (2.6 GB)
  8. 20 sample DBA/2 wave files (2.7 GB)

Choosing Your Workspace:

With the community accepting MUPET actively for their analysis, the developers decided to add a feature/notion of the workspace that let's more than one researcher use MUPET on the same machine. As a pre-step, the MUPET user needs to select a folder (anywhere on the machine) that shall hold all the files of his/her analysis. We can also state that this allows the user to continue his "session" off from where he/she left off previously. If another user wants to use MUPET on the same machine, they just switch their workspace folder using the "Select Workspace Folder" button and the previous user's work remains intact, unlike previous versions of MUPET.

NOTE: Please select the workspace before beginning your analysis, this is a mandatory step to use MUPET and subsequent features will not work in the absence of this folder.

Audio files

step 0: preparing the audio

  • Audio files should be formatted in Waveform Audio File Format (WAV) and ideally have a sampling frequency around 250 kHz to cover the ultrasonic frequency range. Audio files will be resampled to this frequency. Sampling frequencies below 90 kHz are not accepted.
  • The directory structure of the audio data should be organized by the user such that it reflects the data sets for analysis by MUPET.
    For example, if you have 3 audio recordings (recordingA1.wav, recordingA2.wav, recordingA3.wav) belonging to dataset experimentA, and 2 recordings (recordingB1.wav, recordingB2.wav) belonging to experimentB, the directory structure should be organized as follows:
    experimentA/
    |--recordingA1.wav
    |--recordingA2.wav
    \--recordingA3.wav
    experimentB/
    |--recordingB1.wav
    \--recordingB2.wav
    Alternatively, MUPET also allows you to ignore files in a directory (see step2). This way you can create datasets and build repertoires from subsets of files belonging to the same directory.
  • MUPET automatically create folders to stores processed files, datasets and repertoires. Make sure to have sufficient disk space on the disk where MUPET is installed.
  • It is advisable to run MUPET on a computer with sufficient memory space (RAM > 4 Gb), although this does not critically affects the performance.

step 1: selecting the audio files

  • Select the directory where the audio files are stored. The corresponding path and audio files will be shown in the text field and list box.

step 2: processing the files

  • Process a single file by selecting a file and clicking on process file. Alternatively, all files can be processed at once by clicking on process all.
    The processing step involves segmentation of the audio file in syllable segments, extracting spectral features and compute acoustical and statistical information from the syllables.
  • Each time a file is processed, MUPET stores the syllable content in .mat file, e.g. audio/experimentA/recordingA1.mat. All temporary files can be cleaned up by clicking on process restart.
  • By selecting a file and by clicking on ignore file, files can be disregarded from the processing and subsequent dataset creation.
  • The user can change the default settings for processing the files by clicking on edit settings and modify the CSV file config.csv. Make sure to save the file and to click on load settings in order for the changes to have effect in subsequent processing. Each file that was previously processed with a different configuration setting will be recomputed. See step11: Modifying the configuration parameters, for more details on the configuration parameters.

step 3: inspecting the syllables of a file

  • Select and process an audio file from the Audio files section.
  • Inspect the syllable content of the selected audio file.
  • Loop through the syllable content of the file.
  • The figure displays the sonogram and Gammatone filtered representation of the selected syllable.
  • The text area shows syllable index and statistics in terms of frequency, time and intensity.

step 4: exporting the syllable statistics to a CSV file

  • By clicking on export stats from the Audio files section, a CSV file will be generated, e.g. audio/experimentA/CSV/recordingA1.csv.
  • The CSV file lists a complete overview of all syllables extracted, including time stamps and acoustically related statistics of each individual syllable.

Data sets

step 5: creating a data set

  • Create a data set from the audio files. A name for the data set should be specified first.
    Once created, the data set will appear in the list box.
  • You can refresh the list, delete a selected data set or print the file content of a dataset.

step 6: exporting the data set content

  • By clicking on export content, a CSV file datasets/CSV/datasets_file_content.csv will be generated. This CSV file lists the audio files contained by each data set.

step 7: inspecting the acoustic and syllable statistics of the data set

  • Select a data set in the Data sets section.
  • Inspect and compare the data sets in terms of:
  • power spectral content
  • frequency bandwidth
  • vocalization time
  • syllable rate
  • syllable duration
  • inter-syllable distance
  • By clicking on export content, the CSV file datasets/CSV/datasets_USV_profile_stats.csv is generated that lists all the above datasets statistics.

Syllable repertoires

step8: building a repertoire

  • Build a repertoire. Select the desired number of syllable units first (default: 80).
    Once created, the repertoire will appear in the list box.
  • Repertoires can be exported into a CSV file in the repertoire/CSV folder showing for each repertoire unit the number of calls in the data set.

step9: inspecting the repertoire

  • Select a repertoire in the section step13: Data set and repertoire refinement.
  • Show the selected repertoire.
  • Compute the syllable category counts.
    Select the number of units of the meta-repertoire.
    The meta-repertoire will be generated from all listed repertoires.

step10: comparing syllable repertoires

  • Select a base repertoire (A) and compare it against all listed repertoires based on best match. The similarity matrix will be shown, together with the base repertoire where the repertoire elements are sorted according to best match (y-axis of the similarity matrix)
  • Select a base repertoire (A) and compare it against all listed repertoires based on activity. The similarity scores will be shown in box plot representations.

Refinement steps

step11: Modifying the configuration parameters

  • MUPET allows the user to change parameters with respect to the syllable extraction and selection.
    Those parameters are:

    • noise-reduction: parameter value between 0 and 10, lower (higher) parameter value for less (more) noise reduction.

    • minimum-syllable-duration: value in milliseconds, syllables with shorter duration will be ignored.

    • maximum-syllable-duration: value in milliseconds, syllables with longer duration (up to 200ms) will be ignored.

    • minimum-syllable-total-energy: value in dB, syllables with less total energy will be ignored.

    • minimum-syllable-peak-amplitude: value in dB, syllables with smaller peak amplitude energy will be ignored.

    • minimum-syllable-distance: value in milliseconds, syllable (fragments) that succeed in time smaller than this value will be merged into a single syllable.

    • sample-frequency: value in Hertz, this is the desired sampling frequency in which MUPET will process the audio files. If different than the sampling frequency of the files, MUPET will up/down sample to this frequency.

    • minimum-usv-frequency: value in Hertz, lower bound of the frequency spectrum for syllable extraction.

    • maximum-usv-frequency: value in Hertz, upper bound of the frequency spectrum for syllable extraction. This value should be smaller than sample-frequency/2

    • number-filterbank-filters: integer value, number of filters to be used in the filterbank.

    • filterbank-type: value is either 0 (non-linear filterbank) or 1 (linear filterbank), frequency warping between the Fourier frequency spectrum and center frequencies of the filterbank filters.

step12: Data set and repertoire refinement

  • After a repertoire is build for a given data set, the user has the option to refine it. A text box window will display in which the user can provide the unwanted repertoire units to be removed from the repertoire. The repertoire will be updated (denoted with a '+' sign in the name).
  • After the repertoire refinement step, the data set is also updated (denoted with a '+' sign in the name). Data set refinement involves the removal of all syllables that were clustered into the unwanted repertoire unit.
  • The user is advised to inspect and export the data set statistics from the updated data set.
  • After clicking on process file, the syllable inspector will only show the syllables that were retained after the refinement step.

Add a custom footer
Add a custom sidebar
Clone this wiki locally