Auditory DMS simulation

The following tutorial will show you how to install LSNM and perform an auditory Delayed Match-to-Sample (DMS) simulation. As shown in the figure below, the DMS experiment to be simulated consists of an auditory stimulus (S1) being presented to a subject, followed by a delay period during which time no stimulus is presented. At the end of the delay period, a second auditory stimulus (S2) is presented to the subject, and the subject must respond whether S1 and S2 are the same or different (Response).

Images/DMS_task.png

Because the input module to our auditory neural network (MGN) is composed of 81 units in the form of a vector that changes through time, we need to organize our auditory inputs that way. We will initialize the units of our vector to zero and, in order to turn on selected units within the vector at specific times, we will assign values of 1.0 to those units. We will use tonal pattern shapes that look like the following (X axis represents time steps and Y axis represents neuronal unit):

Images/auditory_stimuli.png

For this tutorial, we will make use of the following five input files, all of them arranged in vectors of 81 elements describing auditory tonal contours lasting 70 time steps (roughly 350 milliseconds) and located in the directory $LSNM/inputs:

• bothtc1.inp and tc1_noise2.inp, both of them describing the tonal contour TC1 but with different input being concurrently perceived by a hypothetical "left brain hemisphere"

• bothtc2.inp and tc2_noise5.inp, both of them describing the tonal contour TC2 but with different input being concurrently perceived by a hypothetical "left brain hemisphere"

• bothtc3.inp, which describes the tonal contour TC3.

We will simulate three trials by making use of three script files: auseq1.s, auseq2.s, and auseq3.s. Those files are located within the directory $LSNM and they define the modules of the neural network as well as make reference to their respective connecting weight files and experimental script files. You can go ahead and visually inspect auseq1.s, auseq2.s, and auseq3.s: You will notice how each individual module of the neural network is defined as a vector of 81 elements. The experimental script files that auseq1.s, auseq2.s, and auseq3.s refer to are, respectively, auseq1.rsb, auseq2.rsb, and auseq3.rsb (located in $LSNM/inputs). Our first experimental trial, defined in auseq1.rsb, uses bothtc1.inp as first stimulus and tc1_noise2.inp as second stimulus (same stimulus but with different noise profile), so we are expecting to get a match as a response at the end of trial 1. Our second trial, defined in auseq2.rsb, uses bothtc3.inp as first stimulus and tc2_noise5.inp as second stimulus, so we are clearly expecting a mismatch as a response at the end of trial 2. Finally, our third trial, defined in auseq3.rsb, uses bothtc3.inp as both first and second stimulus, so we do expect a match at the end of trial 3. Now, please go ahead and visually inspect auseq1.rsb, auseq2.rsb, and auseq3.rsb: You will notice the command Run being used with a number following it. The command Run executes n number of time steps with the currently defined neural network and for the auditory model we are assuming that one second of real time corresponds roughly to 200 simulation time steps.

In this tutorial, we will simulate one single subject and three experimental trials. Please inspect the file mkbatchb_au.in, located in $LSNM/code, that defines the simulation parameters used in this tutorial.

NOTE: If you already have a working copy of LSNM, go directly to STEP 2

1. Download a copy of LSNM to your local workstation

• Launch Firefox or another web browser available on your local Unix workstation and copy/paste the following internet address (or just click on the highlighted link if you are in a browser already): https://github.com/NIDCD/lsnm.

• When the LSNM Github page displays, click on the button Download ZIP located on the right sidebar. Click on Save File to download the zip file containing the LSNM code to your Downloads folder.

• Inspect your Downloads folder to make sure you have downloaded the LSNM files. There should be a file called lsnm-master.zip in it.

• Unzip the file in your preferred location:

    $ unzip lsnm-master.zip
  

• Change the name of the lsnm directory (to keep the sim executable from having problems with the special character -:

    $ mv lsnm-master lsnm
  

• NOTE: If you do not have access to an internet browser you can grab a copy of the LSNM repository by typing the following command on your local Unix workstation. Please note that at a directory called sim will be created in the directory where you are currently located:

    $ git clone https://github.com/NIDCD/lsnm.git
  

2. Initialize the Unix environment variable $LSNM

As LSNM makes reference to a directory path relative an environmental variable called $LSNM, one needs to declare and initialize that variable.

• Launch a text editor (e.g., emacs) and open the file .bash_profile, located in your home directory:

    $ emacs ~/.bash_profile &
  

• Add the following variable declaration at the end of .bash_profile. Please note that the following assumes that the LSNM directory structure was stored within the directory called lsnm-master just under your home directory, but please adjust the name if that is not the case:

    LSNM=$HOME/lsnm/auditory/
    export LSNM
  

• Save the file and exit

• Upload the $LSNM variable to memory by typing the command below. Please note that you only need to do this once as it will be done automatically in the future every time you log in to your local workstation:

    $ source ~/.bash_profile
  

• Double-check that the variable $LSNM has been successfully uploaded to the environment by printing out the contents of it:

    $ echo $LSNM
  

3. Recompile executables

• Type the following commands in order to recompile the executables:

    $ cd $LSNM/code
    $ make altgenw_au
    $ make altgenw_L_au
    $ make crossws_au
    $ make crosswt_au_i
    $ make genw_au
    $ make mkattn_au
    $ cd $LSNM/code/netgen
    $ make netgenC_au
    $ make netgenC_L_au
    $ cd $LSNM/code/sim
    $ make au_sim1
  

4. Create a batch file and run the simulation

• Make the batch:

    $ cd $LSNM/code
    $ make mkbatchb_au
    $ cd $LSNM
    $ ./bin/mkbatchb_au
  

• Now execute it!

    $ ./batchb_au
  

5. Plot your output

• Verify that the output files have been created (you should be able to see a directory structure organizing output files by subject then by trial):

    $ cd $LSNM/batchb_output
    $ ls
  

• Now unzip simulated electrophysiological data from subject 1 / trial 1:

    $ cd $LSNM/batchb_output/subj1/b30/trial1
    $ gunzip *.gz
  

• And go to matlab and plot your data (You will need to add $LSNM/code/visualization to your path in matlab before plotting:

    $ matlab &
    fx> plotauditory