Scripted Output Guide

Overview

This guide will demonstrate how to use the open-loop output capabilities of NeuroRighter. NeuroRighter is capable of generating streams of arbitrary outputs in order to interact with both biological tissue and experimental hardware. There are three basic types of output that you, as a pioneering electrohpysiologist, probably care about. Here they are:

• 1. Digital signals that consist of binary states on a set of channels. In the case of NeuroRighter, you have access to 32 bits of digital output, each of which can take a state of LOW or HIGH. In the physical world of your NI card, this translates to 0 or 5 volts at a given channel. These are very useful for turning things on and off, marking exactly when certain events occur and even writing down parameters of events as the occur in way that is very efficient in terms of disk usage. For instance, analog waveforms can be represented by an integer code that describes the waveform parameters, rather than writing however many 64 bit double precision floating point numbers it takes to record the waveform itself.

  2. Auxiliary analog signals that consist of continuous voltage signals between -10 and 10 volts at 16 bit resolution, which corresponds to roughly 0.3 mV per quantization level. Auxiliary analog streams can serve as control signals for external hardware.

  3. Electrical stimuli intended for neural excitation that are translated by the NeuroRighter stim board. These signals are actually a mixture of analog and digital signals (the analog portion encodes the stimulus waveform, either voltage or current, and the digital portion tells the hardware to what electrode it should be sent).

NeuroRighter's Output Capabilities

• • 10 μsec output timing precision (100 KHz digital to analog conversion rate)

  • Double-buffering system allows non-periodic streams of output

  • MATLAB (or Octave) functions to generate files that NeuroRighter can read to produce different outputs

  • Simultaneous, clock-synchronized application of digital, analog, and electrical stimulation streams

  • Temporally synchronized generation of output streams with other data streams (e.g. spikes, LFP's, EEG, etc). This means that if an electrical stimulus is scheduled for 12,345 samples after data acquisition has commenced, and the user is recording electrical stimuli, the recorded electrical stimulus will have occurred at sample 12,345.

Using NeuroRighter's Open-loop Output

First, lets take a look at the information we need to provide to NeuroRighter in order to run an open-loop experiment. Fire up NeuroRighter and take a look in the Stim/Output tab:

You will see a group-box with a whole bunch of text fields in it called 'Scripted Output':

In order to run an open-loop experiment, you will populate one or more of these text fields with paths to files that define the output streams you wish to to apply during a concurrent neural recording. Each of these output files is a text file defining things like when, relative to the start of a neural recording, a change to a particular output channel should occur. Theoretically, you could open up your favorite text editor and manually write out the strings required to make this happen, but for experiments in which hundreds of channels need to be precisely coordinated, and for which arbitrary signals can flow through any of these channels, this might be a bit tedious. Therefore, we can leverage the power of a high-level programming language, like  MATLAB or Octave, to automate this process and define very complex experiments. At this point, lets take a look at the scripts that we will use to create our open-loop experiment in MATLAB . 

• • As a side note, it would be very easy to port these to Perl or Python, so if there is popular demand, we will do that.

Creating Open-Loop Protocols for Use with NeuroRighter Using the Matlab (or Octave) scripts

Go ahead and download the script generation functions attached to this page:

• • makestimfile.m

  • makeauxfile.m

  • makedigfile.m

Each of these MATLAB functions will take vectors of numbers and turn them into the text files that NeuroRighter can interpret during an open-loop experiment. Each of these files contains documentation that can be accessed by typing 

    >> help makestimfile     >> help makeauxfile     >> help makedigfile

into the MATLAB terminal when these files are either in your working directory or you have added them to your MATLAB path. These functions are very similar to one another. The first argument is always the output filename. If this filename is not a fully qualified path to some location on your computer, the resultant protocols files will be saved in your working directory. The second argument will be a vector of times, measured in seconds from the start of a protocol for which certain things should happen. The next arguments are dependent on the type of file you are creating, but will generally specify the channel to send the signal to, and finally you will define the signal itself (a voltage, a waveform, or a port state for digital output). Below we go through some examples to solidify the usage of these functions. 

Example 1: A Simple Digital Output

For our first example, we will make a protocol in which the first bit of our 32-bit digital output port to goes high for 1 millisecond at a frequency of 1 Hz over a 100 second time period. First, we note that the state of the port will change two times every second. Once when the first bit goes high and then a millisecond later when it goes back to low. We can create two time vectors to define this: 

    >> t_high = 0:1:100; % times that the zeroth bit should go high    >> t_low  = t_high + 0.001; % times that the zeroth bit should go low

Next, we need to tell the port what to do with each of its 32 bits at these times. In the case of a digital output, we have two options for telling the port which bits to set to high or low at a given point in time. 

• • We can tell the file explicitly on which bit (31 to 0) an event is occurring, and tell it when that bit goes high and when it goes back to low.

  • We can provide the port with a single vector of 32 bit unsigned integers that correspond to the 32 bit state that the port should take.

Here is how we use the first method:

    >> b = zeros(size(t_high)); % since we want all these changes to happen at the zeroth bit    >> makedigfile('mydigitaltest', b', t_high' ,t_low'); % arguments must be column vectors

Here is how we use the second method

    >> i1 =  ones(size(t_high)); % since when the zeroth bit is high, the 32-bit integer taken by the port is (0*2^31 + 0*2^30 + ... + 0*2^1 + 1*2^0) = 1    >> i0 =  zeros(size(t_low));    >> i = zeros(size(t_high) + size(t_low));    >> i(1:2:end) = i1     >> i(2:2:end) = i0     >> t = sort([t_high t_low]);    >> makedigfile('mytestfile', t', i');

Both of these methods will result in the same digital output protocol.

Example 2: Combining Different Output Streams

Open up the ol_example.m file attached to this page in MATLAB. This script will create two files defining a Poissonian stimulation protocol at the first auxiliary output channel, each pulse at a random amplitude between 0 and 1 volts. In the meantime, a digital output file defines a digital output stream that represents the random amplitude that was sent out of the analog channel. This can be recorded back into NeuroRighter through its digital input port. This way, the timing of each auxiliary pulse is marked through the digital port which is locked to the clock being used for all other recordings in NeuroRighter. By saving digital data instead of recording the raw stream from the analog output channel, you will save a ton of disk space and post-processing will be a breeze (i.e. no estimating analog amplitudes based off of a potentially noisy time-series trace - you wrote that information down already!).