Analog output and input is implemented in two main sections: Stimulus and Acquisition. They both work together as one integrated environment within Igor Pro. Taken together we call this environment bAcq2.
Software and Hardware Requirements
bAcq2 is written in Igor Pro and will work with a range of National Instrument A/D boards. Because National Instruments and in turn Igor Pro provide a common driver interface across the National Instruments A/D board family, you should be able to configure bAcq2 to work with different National Instruments boards with no programming (in theory).
- Windows 7 and Windows XP
- WaveMetrics Igor Pro 6.2x
The Stimulus window provides an interface to: create, load, save, and edit a single stimulus. A single stimulus can then be repeatedly played as a Stimulus Set using the Acquisition window.
As parameters of a stimulus are modified, the resulting waveform is updated in real time to give feedback on what the stimulus looks like. Start by specifying the duration (Dur) and sampling interval (dt) of the stimulus in seconds. The remaining parameters will ‘fill’ the stimulus from left to right up to the specified duration. If parameters cause the stimulus to overrun the duration, there will be a red ‘Status’ message.
Train Group. A train is a sequence of stimulus. There is first an initial delay (at the start of the train) followed by a Number of stimuli at a given Interval.
Stim Group. Each stimulus has a Type (DC or Sin). Each stimulus (in a train) starts with a Delay followed by a pulse of Duration and Amplitude.
For Stimulus Type Sin, the frequency of the sin is set with ‘Sin Frequency (Hz)’. Please see ‘Important Concepts->Sin Stimuli’.
[(1) add a cartoon of the different params: initial delay, interval, number, … (2) chage name of window to ‘Stimulus’]
The Acquisition window is used to create and edit a sequence of Stimulus into a Stimulus Set. It is also used to control the actual stimulation and acquisition.
Go. Start acquiring a Stimulus Set.
Each time you press ‘Go’, both ‘Trial’ and ‘Master Epoch’ will be incremented.
Stop. Stop the acquisition of a Stimulus Set. When a Stimulus Set is being acquired, files are save at the end of each Repeat. If a stimulus set acquisition is stopped during its acquisition, the current repeat will not be saved.
Auto Save. If checked, will automatically save the Stimulus Set as it is played. Saving is done at the end each repeat. See ‘Saved Files’ below.
Interval (sec). The time interval that each Repeat of a Stim Set will be played. e.g. the time interval between each Stim in a Stim Set.
Initial Delay (sec). Specifies an initial delay before the first repeat of a Stimulus Set. Note, this is a delay before the first repeat, it is not inserted for subsequent repeats of a Stimulus Set. This is useful if you want to delay your stimulation/acquisition relative to some other hardware or software.
Wait For Trigger. If checked, pressing ‘Go‘ will arm your Stimulus Set and wait for an external trigger before starting. See ‘Options->Nidaq Boards->Analog in/out is triggered by’ to set the terminal that will externally trigger your Stimulus Set. This is useful if you want bAcq2 to act a a slave to other hardware/software. For example, if you want bAcq2 to be triggered by ScanImage.
Up Duration (seconds). If checked, the amount of time (in seconds) during the Interval that the counter will be in the up/1 state. The remaining portion of the interval will be in the down/0 state. If this is not checked, the counter will be up for 50% and then down for 50% of the Interval, e.g. the output pin of the counter will be up for the first half of Interval and then down for the second half. The up/down state of the counter can be used to trigger other equipment or software on and off. For example, ScanImage can be triggered on in response to the up and then off in response to the down.
Stimulus Set Group
The Stimulus Set group provides an interface to manage Stimulus Sets: select, save, load, new. It is also where the parameters of a Stimulus Set are specified.
Save. Save a Stimulus Set to disk. This will save the Stimulus Set (.bss) and any Stimuli (.stim) specified in the Stimulus Set with ‘Stim0’ and ‘Stim1’.
Load. Load a Stimulus Set from disk. Loading a Stimulus Set will also load the Stimulus files specified in ‘Stim0’ and ‘Stim1’.
New. Make a new Stimulus Set.
[(1) REWRITE THIS SECTION, (2) change name of window to ‘Acquisition’]
Displays runtime information while your Stim Set is running. [Add description of ‘Trial’ and ‘Master Epoch’]
Controls the display of in/out waves during acquisition.
Load User. Load a user .txt file to specify default behavior of bAcq2. See ‘User Files’ below.
Init Session. Creates hard-disk folders to save your files.
The options windows allows you to specify the behavior of bAcq2. Most of the settings can be controlled from a user.txt file.
Note: There are a lot of options and it can seem daunting. We have so many options because we want to provide maximal flexibility. By using a preconfigured ‘user file’ we can set all the desired defaults making bAcq2 an almost one-click acquisition system.
Acquired data can be browsed and analyzed with the Trial Set Panel. This can be used offline on an analysis computer that has Igor Pro but no hardware.
Load Single Trial. Loads a single trial from disk. A trial will have a number of repeats.
Load Session (Folder). Loads a number of trials that are all part of the same imaging session (e.g. A session ID created with ‘Init Session’).
Trial Plot. Displays all in/out waves associated with a single trial (just like ‘Trial Plot’ in the main Acq2 window).
Saved Acquisition Files
Files are saved at the end of each repeat in an End Of Scan (EOS) hook. At the end of each repeat, the following is saved:
- A single Igor binary wave (.ibw) with output and input waves.
- A text file that records Stim and Acq parameters (e.g. a Trial File). There is one Trial File per trial, it begins with a header containing information common to all repeats and then one column for each repeat. Each row begins with the variable name followed by its value. Header values are in column 1, repeat values are in column 1 through numRepeats column.
Thus, if a Stim Set has 10 repeats and is run to completion, 10 Igor binary waves (one per repeat) and a single Trial File with 10 columns will be saved.
Folder conventions. All data is saved within the ‘Root Path’ folder, specified in ‘Options->Save Path->Root Path’ and optionally configured from within a User File. Each time a session is initialized with the ‘Init Session‘ button, a new folder will be created within the ‘Root Path’ with the current date and the name of the specified session (e.g. 20131203_slice1). In this way, all stimulus/acquisition files from a single imaging or electrophysiology session are saved into one folder.
File Name Conventions. Each time you press the ‘Go‘ button you are acquiring a Stim Set with a trial number. The trial number is automatically incremented at the start of acquisition. Files are saved at the end of each repeat:
(1) All output and input waves for each repeat are saved in one Igor binary file with the name:
yyyymmdd : The current date, e.g. 20131203
session_id : The name of your session initialized with ‘Init Session’
trial : the current trial number
step : the step (row) of your stim set, starting with 0
epoch : the repeat within your stim set step, starting with 0 and ending with (Repeats-1)
(2) A tab-delimited text file for a single trial (e.g. a Trial File) with Stim and Acq parameters where each column is a repeat, rows are parameter name/value:
yyyymmdd : The current date, e.g. 20131203
session_id : The name of your session initialized with ‘Init Session’
trial : the current trial number
Reading a trial file. The text Trial File is split into different sections: [header], [repeats], and [stim].
|[header]||Information about this trial (a trial is a sequence of repeats/epochs)|
|Version||Software version number for saved trial set (as of 20140322 is ts1.1)|
|goTime||Time of day the ‘Go’ button was pressed|
|isi||inter-stimulus-interval between repeats (seconds)|
|totalRepeats||Total number of repeats (epochs)|
|actualTotalRepeats||The number of acquired repeats (different from totalRepeats if user hits stop during acquisition)|
|[repeats]||Information about each repeated stimulus that was acquired.|
|masterEpoch||Each repeat gets a unique index number. This is initialized when the software is started and is automatically incremented for each played repeat. Similar to ScanImage index values.|
|epoch||Zero based repeat/epoch number: 0..(actualTotalRepeats-1)|
|callbackTime||Time of day the end-of-scan was called for a given repeat (when the scanning of the repeat was done).|
|callbackDuration||Time the callback took to execute. If ((callbackDuration+gTotalDuration) > isi) there will be problems.|
|stim0||Name of bacq2 Stim that was played out channel 0.|
|[Stim0]||Parameters for stimulus played out analog 0|
|gdt0||Sampling interval (seconds per bin). This is the same for all Stim and all repeats within this Trial Set.|
|gDelay0||Time delay before the start of each pulse (seconds). The pulse is shifted within gInterval0.|
|gAmplitude0||Amplitude of each pulse (Volts)|
|gDuration0||Duration of each pulse (seconds)|
|gTotalDuration0||Total Duration of the stimulus (seconds)|
|gInterval0||Time interval between pulses (seconds)|
|gNumber0||Number of pulses|
|gInitialDelay0||Time delay before the start of the pulse train (seconds). The entire pulse train is shifted.|
|gStepTimeList0||Time (in seconds) of the start of each pulse (gNumber0 in total)|
The default behavior of bAcq2 can be controlled by loading a user file via the ‘Load User’ button in the Acq2 panel. User files are text files and can be created by users! This is a sample user.txt file with common parameters to include:
#assign the root hdd path #any sessions created with 'Init Session' will become folder within this root hdd path root:bAcq2:gRootPathHDD="vasculature:Users:cudmore:Desktop:bAcq2:" #turn channel display on (1) off (0) root:bAcq2:Plot:gDispIn0=1 root:bAcq2:Plot:gDispIn1=1 root:bAcq2:Plot:gDispIn2=0 root:bAcq2:Plot:gDispIn3=0 #load a stimset #This is assuming the stimset and its associated stim are in the same directory as *this file. #loading a stimset will automatically load any stim that are specified within the stimset stimset=model1.bss #load a stim #model0.stim #run in model mode (no hardware), default=0 #root:bAcq2:gIsFake=1 #watch folder, default=0 #root:bAcq2:gUseWatchedFolder=1 #experimental counter, default=0 root:bAcq2:runtime:counter:gUSeCounter=1
Defining National Instruments Hardware
[this text is a work in progress] bAcq2 can run with either one or two national instruments boards. With a one board configuration the input, output and counters will run on this board. In a two board configuration, input/output is on one board and the counters are on the other. For a single board configuration specify both ‘counter board’ and ‘analog in/out bard’ as ‘Dev1’.
[ToDo: Add ‘save config’ button to save user options for hardware. Currently hard-coded in code.]
Wiring The Linden Sutter
On the Linden Sutter scope we are using 2 national instruments boards
- Dev1, NI PCI-6602, BNC-2121, the counter board
- Dev2, NI PCI-MIO-16E 4, BNC-2090, the analog in/out board
(A) Igor as master and ScanImage as slave: Attach bAcq Dev1/User2 to ScanImage Dev2/User2
When ‘Go’ is clicked, a timer starts on Dev1/Ctr0 to count your ‘interval’. Each time this counter fires, it will set Dev1/PFI 36 (Out0) on the BNC-2121 to high for a duration. This duration is by default 1/2 your ‘interval’, unless you specify your own duration with xxx.
Dev1/PFI 36(Out0) is wired into Dev1/User2. Dev1/User2 MUST ALWAYS be connected to Dev2/User2 (which in turn is wired to Dev2/PFI8). This will start analog in/out on Dev2 in synch with the Dev1/Ctr0 counter.
ScanImage can be triggered by connecting bAcq2 Dev1/User2 to ScanImage Dev2/Users2. ScanImage can then be configured to start acquisition in response to the rising phase of bAcq Dev1/User2 and to stop acquiring in response to the falling phase.
(B) ScanImage as master and Igor as Slave: Attach ScanImage frameClock to bAcq Dev2/User1
Running bAcq2 in model mode
bAcq2 has a model model that can be run without National Instruments hardware. To run in model model, turn on ‘Simulated Scope’ in the Options panel. In model mode all output Stimuli become input current (units xxx) to a leaky integrate-and-fire model neuron (with noise) and the voltage output of this model is copied into the input/acquired waves. The threshold current for the model is ~1.4 to ~1.5 (units xxx).
[provide two simple recipies to get a user started with: 2 Stimuli, one Stimulus Set, and one User File]
Interval counter. During acquisition, each repeat of a Stim Set is presented at an interval (sec) and this interval is controlled by a counter on the National Instruments board specified as the ‘Counter Board’. This counter runs at a clock frequency which in turn will determine its maximal precision (a faster counter has more precision, a slower counter has less). The counter will count up to the next interval in steps of its clock frequency using a finite bit precision number (usually 24bit), thus the maximal interval is a function of the clock frequency. With a faster clock frequency, the counter will run out of space/bits to keep counting. The available counter clock frequencies will depend on the National Instruments board used, our National Intruments boards have two available counter clock frequencies:
Using the faster 80Mhz clock frequency, the maximum interval is limited to about 59 seconds. For this reason, we are using the slower 100 Khz clock frequency, with this clock the maximum interval is on the order of one week.
The interval is never perfect, it is limited by the precision of the clock frequency. In general, we do not see additive errors in repeat intervals. Using a Stim Set with 20 repeats at intervals of 40 seconds, each repeat will have some jitter (the repeats may occur at 40.0 +/- .010 sec) but the absolute time of each repeat should stay close to the specified interval. For a Stim Set with 20 repeats at an interval of 40 sec, the start of each interval will be close to a multiple of 40 sec. Put another way, the start time of repeat 20 will be approximately 20*40sec.
Sin Stimuli. When using a Sin Stim in bStim, please consider the following: (i) the ability to achieve a given sin frequency is a function of the sampling interval, dt, and (ii) the sin wave has a hard coded onset and offset envelope that needs to be improved to vary as a function of the sin wave frequency. [for now the onset/offset envelope is xxx]
-Check that repeated stim are not colliding. This happens when (stim duration + time eos() takes) > ISI. For example stim duration = 5 sec, callback takes 1 second and ISI=6 seconds, (5+1)=6 and we have a collision. Best we can do is warn user and have them adjust the stim dur, isi, or reduce the eos() time by not saving a0/a1/a2/a3.
-Do not change the names of saved files (e.g. files on the hard-drive). Do not change the names of saved Stimuli and Stimulus Set files. The tempation is that you want the name of a Stimulus or a Stimulus Set to appear different in bAcq2 so you change the filename on the hard-drive, do not do this. To change the name of a Stimulus or a Stimulus Set you need to make a new Stimulus or Stimulus Set using the bAcq2 interface
-Date rollover bug. If you initialize bAcq2 and then the date changes you will get errors. For now, bAcq2 DOES NOT work if the date changes while using.