Using the MATLAB VocalizationFunctions Package

Michael Rieger

12.30.2015

Contents

I Installation & upgrades 2

1 Installing for the �rst time 21.1 Downloading the Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Installing the Rlike library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Installing the VocalizationFunctions library package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Upgrading to the newest version 4

II Running the GUI 4

3 Preparing your data 43.1 Preparing a CSV for upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 Checking �les for consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Starting the GUI 7

5 Setting options for processing 85.1 Project details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85.2 Audio File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.3 White Noise Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.4 FFT Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.5 Automated Call Scoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.6 Spectrogram Spot-Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6 Inspecting output reports 11

7 Adding new data to an existing project 12

III Running the console-only version 13

8 Preparing your data 13

9 Creating a pipeline template 149.1 Loading the VocalizationFunctions library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159.2 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

10 Running processing 1510.1 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1

11 Cleaning outliers and preparing output table 1511.1 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

IV Variable Exploration and Analysis 1511.2 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

12 Worked example: Making scatter/boxplots 1512.1 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

13 Worked example: Running statistical modeling in R 1513.1 To Be Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Part I

Installation & upgrades

Important note: It is very important that your default path in MATLAB does not contain any references to previous instancesof the VocalizationFunctions package. Your package should be installed to your default MATLAB directory locally (usually�Documents/MATLAB�). We will not add these to the path (this will be done using the library() function). If there areany old entries from previous iterations make sure to remove these entries and save your path. To inspect your path (inR2013,R2014), click �Set Path�:

If MATLAB complains (usually this happens on Windows) that you cannot save your path after making changes, restartMATLAB using Administrative privileges.

1 Installing for the �rst time

1.1 Downloading the Archives

The archives containing the package functions are stored on the genstorage server at the following address:

2

�//genstorage.wustl.edu/jdlab/Behavior/Behavior Assay Procedures and Protocols/Maternal Isolation Pup USVRecording�

There are two �les you will need to copy:

� Rlike

� VocalizationFunctions-mm-dd-yyyy

Both are provided as either .zip or .tar.gz archives depending on your environment. Do not extract these on the server!Download them to your

Documents/MATLAB/

directory and then extract them there. Do this on your computer, not on an external disk, not anywhere else. To yourDocuments/MATLAB directory and nowhere else.

1.2 Installing the Rlike library

Unzip Rlike.tar.gz or Rlike.zip in the Documents/MATLAB directory. A number of �les will appear:

� asvector.mThis function vectorizes a matrix. Useful for nested function calls.

� between.mThis function performs a logical test for values between a and b. Useful for readability.

� betwout.mThis function performs a logical test for values outside of a and b. Useful for readability.

� head.mThis function displays the �rst 10 rows of a dataset or other matrix-like object. head(X, n) displays the �rst n rows.

� tail.mThis function displays the last 10 rows of a dataset or other matrix-like object. tail(X,n) displays the last n rows.

� nrow.mThis function returns the number of rows. It is a call to size(X,1).

� ncol.mThis function returns the number of columns. It is a call to size(X,2).

� library.mThis function is executed as library('LibraryName'). LibraryName is the name of a folder under Documents/MATLAB.library() temporarily adds this folder and its subfolders to the MATLAB path during a session. This method avoidsclashes between functions of the same name, and simpli�es the path update procedure.

Because these are unzipped in the Documents/MATLAB directory they will always be available in your MATLAB path foruse in any MATLAB session. If you unzip them elsewhere, this will not occur.

1.3 Installing the VocalizationFunctions library package

Unzip the VocalizationFunctions-mm-dd-yyy.zip or VocalizationFunctions-mm-dd-yyyy.tar.gz in the Documents/MATLABdirectory. If you are using a graphical archive utility (e.g., WinZip, WinRAR, Mac Archive Manager), right-click and use anoption for �Extract Here�. This will produce a top level VocalizationFunctions folder (which is also its library name), andthree subfolders:

� VocalizationFunctions

3

. CleanThis folder contains the functions for running a console-only version of the pipeline. The console-only version isrecommended as it robustly checks �les and data for inconsistencies and prevents crashes.

. GUIThis folder contains functions for running the GUI frontend. The GUI version will no longer be updated after thisversion.

. MiscThis folder contains many other functions that need to be catalogued, including Tim Holy's legacy functions fromHoly & Guo 2005.

This is it for installation. Before running any function it will be necessary to execute:

>�> library('VocalizationFunctions')

from the MATLAB command prompt.

2 Upgrading to the newest version

Recent versions can contain �xes to bugs or cosmetic changes or both, and it is always a good idea to upgrade. To do so,download the most recent version of VocalizationFunctions-mm-dd-yyyy.tar.gz or .zip and unzip as in the previous section.It should overwrite existing functions in previous folders.

Part II

Running the GUI

The GUI version was a fun experiment, but the console version is more robust in several respects. Rather than build theseinto the GUI version, I've left it up to you to make sure your data do not have inconsistencies. The example data used inthis are located under ~/Documents/MATLAB/VocalizationFunctions/Sample.

3 Preparing your data

Create a destination folder for your project. In this example, I have created MyProject. Inside the MyProject folder I havecreated a folder calls WAVs.

4

Copy over the WAV �les from their source to the WAVs folder:

3.1 Preparing a CSV for upload

If you would like the output dataset to contain metadata (weight, sex, other variables), prepare a CSV �le. The top line ofyour CSV should contain header names for each of the metadata variables you'd like to add. These names should not containspecial characters: ~!@#$%^&*()-+= and no spaces.

Under the header row you should make sure that the number of rows equals the number of �les you want to process. It isvery important that the data in each row corresponds to the �les in the order in which they appear in yourWAVs folder. Usually this is how the �les are acquired in the �rst place. If you don't make sure this is the case, potentiallythe wrong �les will be paired with the wrong data. (This error is avoided in the console-only version.) Make sure the CSVdoesn't have empy cells. For Matlab use �NaN� as the �Not-A-Number� code for missing data where data are numeric. NaN,Inf, -Inf are the only non-numeric characters MATLAB will allow in a column otherwise �lled with numbers.

Below shows an example CSV:

5

Save this CSV to your project folder:

NOTE: If you make a CSV in Windows, but do processing in Mac/Linux, or vice versa, errors can occur.This is because �under the hood� Windows and Unix use di�erent �end-of-line� characters in text �les. Makesure to save your CSV in the operating system environment you plan to do your processing in. This is as easy as opening upthe Excel spreadsheet and saving to CSV.

6

3.2 Checking �les for consistency

It is important that your �les are of similar length. During processing a small chunk will be used for background calculations.If some of your �les are abnormally short (such as an aborted recording) they will not have a chunk of adequate length andthe processing pipeline will crash. You will note that VGAT_p7_007.WAV is 6.2 MB while most of the �les are around ≈90MB. This indicates you should remove this �le (and its correspondingly line in the metadata CSV) before beginning:

4 Starting the GUI

From the MATLAB command line, execute the following:

>�> library('VocalizationFunctions')

>�> vocalizationRun

After typing each line, hit Enter. The �rst line loads the VocalizationFunctions package into the path.

7

5 Setting options for processing

From the GUI, under Project Folder, Browse to choose the project folder location.

5.1 Project details

Under Project details, type a name for your project. If this is a new project, leave Process All Files checked. If you have aCSV, click �Upload metadata from CSV...� and navigate and choose its location. The last three checkboxes are:

� Skip spectrogram spot check : If checked, you will not check the automatic scores of call start/end points in thespectrogram. If this is a new project, leave this unchecked. I like to verify about 10 % of �les. Later it will ask howmany �les you want to check.

8

� Generate Quality Control Plots: Leave checked to generate QC variable histograms.

� Generate output report: Leave checked to generate output CSV with processed data.

5.2 Audio File Parameters

� Sampling Rate: Enter the sampling rate in kHz (default is 250000).

� Bits: Enter the bit depth. (default is 16 bits).

� Gain: Set the gain level. Default is 0. The default gain will return amplitude values in dB re 1.0. dB are a relative

unit, where 1dB = 10 · log10(

amplitude2

referencevalue2

). Each dB is 10 log10 units relative to some reference power unit. �dB re

1.0� means the reference is the detector maximum. Since 1.0 is the detector max (read: �100%�), values are fraction,and dB are negative. �-20 dB re 1.0� , or -20 dB in common parlance means 20 dB units below the maximum, wherethe maximum is 0 dB.If you choose the gain setting, voltage data will be reported in actual Volt units based upon estimated conversionfactors from the manufacturer and dB data will be reported as dB SPL re 2 µPa, or dB SPL for short. Amplitudein Volts is converted to Pressure data in Pascals based upon manufacturer estimated microphone sensitivity for theAvisoft Bioacoustics CM16 microphone. These data are not true measurements of sound pressure because over time themicrophone's plate is di�erently sensitivity than initially. To know the true sound pressure, the microphone must becalibrated (using, surprise, surprise, a calibrated microphone! which in turn must be calibrated with another calibratedmicrophone...).Unless you have strong feelings about what units to report, report the default (leave Gain set to 0) and no conversionwill be performed.

5.3 White Noise Filtering

� Leave �Use manual thresholding?� unchecked. If checked, white noise levels must be approximated by eye. The pipelinewill present a graph for each �le of a (default) 15 second chunk of audio (frequencies on the x axis and log10 unscaledFFT magnitude on the y-axis. A magic red line will be drawn based upon an automated algorithm and the user canenter and select to change the position of this line. such that it approximates the noise �oor level.

� sigma: The sensitivity of the automated noise threshold (default = 2.5). You can turn this nob up and down. The minvalue is 1. Larger numbers are more sensitive. If you feel that spectrograms are not being correctly scored, increase ordecrease as desired.

� length: Default is 15 seconds. Processing the entire �le for noise will be very laborious, so only a small chunk is chosen.

5.4 FFT Settings

� Window length: The fast Fourier transform is computed in 50% overlapping windows. The % overlap is not tweakableat this time. Changing the window length changes the temporal and spectral resolution which is shown in real time inthe box at right. Big windows make for better spectral resolution, but poorer temporal resolution, and vice versa. 512is the default. Each time point in the spectrogram will be 1.024 msec with a bin size of 512 samples.

� Band-pass �lter: From (25000 Hz default) To (120000 Hz default). The high frequency spectrum is saved for mice,with non-white noise, but low frequency audio �ltered out.

5.5 Automated Call Scoring

These are the parameters used to improve the automated scoring of USV call start and stop times.

� Power calc: Linear vs. Log. If your signal is very weak, log-scale scoring might improve signal detection accuracy.Linear is default.

� Smooth size: 0.01 seconds default. Frequency data is smoothed over 10 milliseconds. Helps smooth out �empty� spotswhere signal may drop below detection.

9

� Min. duration: 0.005 seconds default. The minimum duration for a USV call (for the so-called �whistle� calls).

� Min. purity: 0.25 default (in practice I think 0.15 works better). This says at any moment in time, within acall, some % (the �spectral purity�) must be concentrated in the frequency where the maximum occurs. This meansyou have a nice tall peak somewhere in the spectrum, and the rest of the audio can be alternatively distributed. Smallnumbers are �dirtier� more peaky spectra, and bigger number are �clean� spectra. A purity of 1.0 would be the Diracdelta function in the spectrum (100% of the power at the max, 0 elsewhere). I �nd pup calls are sometimes a lil dirty,so I use 0.15.

� Min mean pitch: Wherever the frequency of maximum power (�pitch�) is , it should be at least 35 kHz or greater(default).

� Max spec. discontinuity: Consecutive time bins within a call should have their peaks in mostly the same place. Valuesrange from 0 (identical spectra from t to t+1) to 2 (spectra with peaks in opposite place from t to t+1). A valueof 1 indicates consecutive spectra have a shape that is 50% the same. Gradual evolution over time suggest spectraldiscontinuity is on the range of 0:1. Discontinuities between 1:2 are very abrupt changes in the spectra. By the way,these occur whenever a pitch jump occurs, but this is taken care of by the next paramter.

� Min gap: 0.03 seconds default. Any areas between two calls where the signal is : (a) too dirty, (b) too discontinuous,(c) below detection, or would otherwise be scored as �not a call�, if these areas are 30 milliseconds are less, the twodisjointed calls are merged and scored as a single call. This also allows the discontinuities evident in calls with pitchjumps to be scored as a single call despite violating the spectral discontinuity threshold.

If you don't know what you're doing, I would change the spectral purity to 0.15 and leave the rest alone.This is my �lled out GUI:

10

5.6 Spectrogram Spot-Check

In the spectrogram view, the upper plot is the gray-scale spectrogram, and the lower plot shows the locations of calls asscored automatically from start time to stop time. The spectrogram can be navigated by selecting and using the arrow keysor arrow buttons in the lower �slider window�. Your goal is to make sure the automated scores overlap with calls you wouldscore manually. If they don't you may have restart and tweak some settings.

On subsequent runs if you think that the utilized settings do a good job, then you can check the box in the main GUI toskip this step.

When everything is complete, you should return the following at the MATLAB console:

6 Inspecting output reports

The �rst report that you will want to inspect is the _qcgraphs.pdf �le. These are histograms which giveyou a sense of how di�erent USV features are distributed.

� Noise Mean & Threshold: These are actually a bit redundant, but they both are the estimates of the background whitenoise level in the spectrum, in the original FFT units and then rescaled to the units which the spectrograms are storedin (Voltage in the case that Gain>0 is used, or full scale where Gain=0). The threshold represents the magnitude levelin the spectrum. FFT magnitudes below this value are set to 0 in the spectrum. The noise level is set on a per-�lebasis. You should be concerned however if the distribution appears bimodal - i.e., that some �les appear to have adi�erent noise level than other �les. This is likely due to changes in the recording environment (such as switching boxesor rooms), or changes to the gain level on the the microphone's pre-ampli�er. This may make results non-comparableas a change in the noise level or the sensitivity of the recording equipment will likely alter the number of calls detected.

� Fraction of calls peaking: The x-axis is �le number, and the y-axis is the number of calls exceeding the maximum ofthe detector limit somewhere within the call. Peaking may not e�ect call counts, but will likely skew the computation

11

of other features of USV such as features based on the pitch or amplitude envelope of the call.

� Other features of USV: Unlike the preceding two distributions, the other distributions are mostly informational. Theyinform you what each of these USV features looks like:

. Call number: # of calls in each recording.

. Call duration: Pooled duration times (milliseconds) over all calls.

. Call duration averages: Average duration for each recording.

. Pauses ( 0.5 seconds are considered �silence� in the recording and nota pause before the next call.

. Average Pause times per �le.

. Bout #: Number of bouts per recording, where a bout is a sequences of calls separated by pauses < 0.5 sec.

. Fraction of bouts with only one call: # of bouts of length = 1.

. Correlation between duration & subsequent pause length. This is usually around 0 but may be slightly negative.

. Correlation between adjacent duration times: This is usually positive.

. Correlation between adjacent pause times: This is also usually positive.

. Mean Pitch: The average pitch of each call, pooling all calls.

. Mean Pitch average: The average Mean Pitch for each �le.

. Pitch Range: Pitch range observed pooled over all calls.

. Pitch Range �le averages.

. Pitch slope: Hz/millisecond slopes in calls, usually center on 0 (�at calls).

. Pitch slope �le averages.

. Spectral purity: �Noisiness� of the calls, with a minimum as de�ned by the processing parameters (e.g., 0.15).

. Spectral purity �le averages.

. dB: Peak amplitude level pooled across all calls.

. dB �le averages.

. Fraction with jumps (>10 kHz).

7 Adding new data to an existing project

This capability exists but is currently untested so use at your own risk. It should work. As of this issue, the GUI is deprecated,so I will not be supporting future updates to this feature.

From the GUI main page:

12

� Uncheck the box that says New Project. The GUI will check for the presence of a Vars subfolder containing initializationparameters and a �data.mat� �le. If these don't exist, it will tell you that it does not think there is actually an existingproject.

� Uncheck Process All Files and change the Start at File to be the number of the next �le to run, in numerical orderfrom their listing in the WAVs folder, or in row order from your metadata CSV.

Part III

Running the console-only version

As of 2016, the GUI is deprecated. It was a nice experiment, however it leaves a lot to the user to ensure that processingproceeds in a bug-free manner. The console tools require more of the user to deal directly with MATLAB scripting, howeverincludes functions which better ensure that processing proceeds with informative crashes and no silent errors.

8 Preparing your data

The �rst change which has been made between the console version & the GUI version is that the console version explicitlyrequires a metadata CSV �le. This �le contains the �lenames which are to be processed. Thus, they can be presented inany row order: only the �le names as written will be processed. If a �le is considered an outlier for some reason, its row ofdata can be eliminated, and thus not processed.

To prepare your spreadsheet, make sure that the �rst column contains the �le names. This should be the �le name pre�xonly, not containing the .WAV su�x. We will annotate this later. (You can also make the �le name a full path, but you mayhave to edit the script lines a little. This is up to you.)

13

In this case, my CSV �le has �lename column, and other metadata such as treatment, sex, day, genotype, and weight.These are typical for a pup USV experiment.

Once again, under your project folder (here, �MyProject�), create a WAVs subfolder and copy your �les to this folder.You can copy any �les you want really; only the �lenames explicitly delineated in the CSV will be processed.

After you do this, I create the following folders, though in principle your other project �les can exist anywhere:

� SNGs (if you don't create this folder, it will automatically be generated)

� code

� graphs

� data

Under the �code� folder, you will need a pipeline script that we will tailor to your project. For simplicity, you can copythe skeleton �pipe.m� from VocalizationFunctions/Clean/pipe.m to your code folder. Otherwise, you can create any kind ofscript �le that you like. I like to store these �les in the code folder for organizational purposes. Do not run the codein the template /VocalizationFunctions/Clean/pipe.m �le without copying it to your project folder and editing it tosuit your project's needs, as this may lead to unexpected results or crashes.

Once your folder structure and template pipeline have been generated, start Matlab and navigate to your project/codefolder:

9 Creating a pipeline template

In your project folder, open your pipeline using the edit command. In my case, this is called �pipe.m�.

The editor window should appear. You can in principle use any editor you like.

14

This is the processing pipe.When you're run is ready you can execute your pipe by typing:

>�> run('./pipe.m')

from the command line. But for now, we're going to go line by line.

9.1 Loading the VocalizationFunctions library

The library() function loads the VocalizationFunctions folder & subfolders into the MATLAB path. You need to have thisline present every time you run, and it is more bug-free than permanently editing your path. Please use the library() function.

9.2 To Be Edited

10 Running processing

10.1 To Be Edited

11 Cleaning outliers and preparing output table

11.1 To Be Edited

Part IV

Variable Exploration and Analysis

11.2 To Be Edited

12 Worked example: Making scatter/boxplots

12.1 To Be Edited

13 Worked example: Running statistical modeling in R

13.1 To Be Edited

15