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 needed for the next step.
The quick n' dirty method. Just run experiment_helpers/gen_dataVals_from_audapterdata.m. It uses Audapter's formant data, which, since it is calculated online, isn't super accurate and doesn't have the benefit of looking at the trial holistically. (NOTE: See item #1 in the "Before you go" section.)
The more time intensive and reliable 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.
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.