SMNG Code: Quick Start Guide
Data collection
Data collection for compensation-style experiment
Unless otherwise stated, any code referenced is in the carrien/free-speech repository on GitHub: https://github.com/carrien/free-speech
For data collection of a compensation experiment, run the function templates/modelExpt/run_modelComp_expt.m. That is our "wrapper" function that sets up a file expt.mat. At the end, it calls a function templates/modelExpt/run_modelComp_audapter.m. That is our "engine" function that actually runs Audapter and goes through all of the trials of the experiment. That's the basics, at least.
The results of these functions are two primary files: expt.mat, which stores metadata, and data.mat, which stores the audio recordings and other Audapter output.
Data collection for adaptation-style experiment
Essentially the same as for compensation-style experiment, but the functions are templates/modelExpt/run_modelExpt_expt.m and templates/modelExpt/run_modelExpt_audapter.m.
Data analysis
After data collection, there are two main methods of extracting the relevant formant data. Both result in a file called dataVals.mat, which is nicely formatted for further analysis.
Quick n' dirty data analysis method
In MATLAB, navigate to the folder containing the expt.mat and data.mat files, then run gen_dataVals_from_audapterdata (which comes from the free-speech repo). It will generate a file dataVals_audapter.mat using the pitch and formant data provided by Audapter. Since Audapter's pitch and formant data is calculated in real time as Audapter is running, it isn't super accurate and doesn't have the benefit of looking at the trial holistically, like Praat would. (NOTE: See item #1 in the "Before you go" section.) In our lab, we typically trust Audapter's formant data as a first pass after data collection or when working with pilot data. We don't use Audapter's formant data for publication-quality reports.
More reliable and time-intensive data analysis method
Our typical pipeline for data analysis includes several steps using various tools. It uses Praat to find formant values and allows you to configure parameters during formant analysis. That whole process is documented here. At the end of that process, you will have a file dataVals.mat.
Understanding dataVals
More info about dataVals is here: Basic dataVals structure. This is particularly useful info if you want to make your own plotting or analysis scripts.
Plotting
For plotting and further data analysis, a file fmtMatrix.mat is useful and can be derived from dataVals.mat. Use the wrapper templates/modelExpt/gen_fmtMatrix_modelComp.m to generate fmtMatrix.mat.
Then, see resources in the free-speech/plotting/ folder, but the most simple is plotting/plot_fmtMatrix.m. If you are in the data folder in Matlab, and your fmtMatrix file is called "fmtMatrix.mat", you can run it with plot_fmtMatrix([], 'fmtMatrix.mat').
Other resources
More basic info and terminology used in our code is in this README.md file: https://github.com/carrien/free-speech/tree/master/templates/modelExpt#reference-guide-to-modelexpt . Note that this document was written specifically for modelExpt (the adaptation experiment), not modelComp (the compensation experiment)
At the top of this page, you can click the "Resources for collaborator" hyperlink to find all pages with that tag. Some relevant ones are:
- How experiment settings are generally structured, including info about data.mat and expt.mat: https://kb.wisc.edu/smng/117641
- The aforementioned reliable data analysis pipeline in step 2b is here: https://kb.wisc.edu/smng/89601
- Plotting scripts additional info: https://kb.wisc.edu/smng/126737
- Functions for validating your expt.mat setup and making sure formants are actually being shifted in the way you expect: https://kb.wisc.edu/smng/109809
Before you go
- If this Github issue is still open, there is a limitation with the quick n' dirty method of generating dataVals.mat (in step 2a). If you use the quick n' dirty method and then get errors when running gen_fmtMatrix_modelComp in step 3:
- Open the dataVals.mat file in Matlab
- See if there are any rows (ie, trials) where the 'dur'ation column is less than 0.1 seconds.
- If there are, set the bExcl column to 1. Save dataVals_audapter.mat.
- Those short trials will be excluded when generating fmtMatrix.mat
- In our KB documents, some hyperlinks may direct you to a version of a page which has "internal" in the URL, and it will show up to you as "this page doesn't exist." Try removing "/internal" from the URL to see if a non-internal version of that page exists.