Acquisition Protocol
From QuB
| Prev: Acquisition Notes | Outline | Next: Report |
The Acquisition Protocol window is used to design a stimulus waveform for simulation or instrumental output. A basic protocol consists of a sequence of Shapes such as Ramp, with the whole sequence repeated some number of times. Shapes are parametrized, and the parameters can change each repetition by a constant (increment) or rate (factor). A protocol can drive multiple stimuli (using multiple D/A Channels), and set digital on/off switches (#Bits). The most complicated protocols have multiple Stages: each Stage is a sequence of shapes with its own repetition count.
Several sample protocols are included with QuB, in the folder QuB\Sample Protocols\.
For an example using Acquisition Protocol, see Tutorial:Simulation#Pulses of Agonist.
Contents |
Layout
File Operations
The three top-left buttons are New, Open, and Save. Files are discussed further below.
D/A Channels
The number of stimulus signals in the protocol. The #Waveform area is divided into this many traces.
question: do you need an additional channel for Bits?
Prp
Originally intended to show a "Properties" dialog, this button is useless because all properties are onscreen.
Shape Palette
These shapes are the building blocks of your waveforms. Each shape is described in detail below. To use a shape, drag-and-drop it into the #Waveform area. If you click one of these Shape buttons, a shape will be added at the end of the shortest waveform.
Generate button
To use a protocol for Acquisition Output, you need to generate sampled data that can be sent to your hardware. When you press this button, QuB attempts to fill the "assigned" file in Acquisition Output with the sampled stimulus. If no file is assigned, QuB prompts you to create a new data file, which is "assigned" automatically. Make sure its A/D Channel count matches the protocol's D/A Channels.
You may get a warning: "AO Channel ______ went out of range. Try adjusting its Scaling." As discussed in Data Theory, the min/max values and resolution depend on the Scaling factor. If you are generating into the "assigned" file, for the purpose of driving your acquisition hardware, the Scaling values depend on the hardware: stimulus amplitudes are converted into voltages by the acquisition card, then voltages are interpreted as stimulus quantities (e.g. 1V :: 5uM). Overall Scaling is a function of resolution (bits) and range (max volts): 
. It should be set automatically when the file is "assigned". Channel scaling (the ratio between voltage and stimulus units) is set in the Hardware Configuration dialog. In this context, the warning means you should
- make sure your hardware settings accommodate the largest stimulus values
- make sure the Channel scaling matches your hardware settings
If you'd like to generate a sampled data file for purposes other than output acquisition, you have to trick QuB:
- make sure no file is "assigned" in Acquisition Output
- edit the Acquisition Output#Channels so there are no output channels in use (or at least a different number of channels than in your protocol)
Now the Generate button will always prompt you to create a new file. If it warns you about "... out of range", simply re-generate with a smaller Scaling.
Files
There is a list of open protocol files at the upper-right. Protocols are saved as QPF.
Right-click for a menu:
- Save as...
- prompts you to save the chosen protocol file
- Close
- closes the chosen protocol file
- Show tips
- no effect
- Properties
- no effect
Stages
A protocol file can have more than one Stage. Each stage is a sequence of Shapes, repeated some number of times. Click an item in the Stages panel (lower-right) to see and edit that Stage. Right-click for options:
- Insert stage
- adds a new, blank stage before the chosen stage
- Add stage
- adds a new, blank stage after all other stages
- Cut stage
- puts the chosen stage on the clipboard and removes it from the protocol
- Copy stage
- puts a copy of the chosen stage on the clipboard
- Paste stage before
- adds the stage from the clipboard before the chosen stage
- Paste stage after
- adds the stage from the clipboard after the chosen stage
- Delete stage
- removes the chosen stage from the protocol
Waveform
The center of the Protocol window contains the stimulus waveform. The waveform has as many traces as #D/A Channels. You can drag-and-drop Shapes into this area to build the waveform, and drag-and-drop a Shape from one spot to another within the waveform. Click a Shape to select it; the selected Shape is drawn with a red background (others are blue). The selected Shape's #Parameters are shown at left. Right-click a shape for this menu:
- Cut
- puts the selected shape on the clipboard and removes it from the protocol
- Copy
- puts a copy of the selected shape on the clipboard
- Paste
- adds the shape from the clipboard before the selected shape
- Paste after
- adds the shape from the clipboard after the selected shape
- Delete
- removes the selected shape from the protocol
Time scale: By default the waveform area shows 100% of (this stage of) the protocol. To zoom in, use the '+' and '-' buttons, or enter a percentage.
Vertical scale: the waveform's vertical axis is always scaled to show 100% of the visible stimulus.
Parameters
At the left edge is a table of parameters for the selected Shape. Each parameter has three entries:
- ___: the parameter's value (the first time through)
- ___ incr: how much to increment (add to) the value each repetition
- ___ factor: the value is multiplied by this factor each repetition
Either leave incr as 0 or factor as 1 -- if you change both, the behavior is undefined.
The parameters of each shape are described below.
Stage Options
At the bottom are options pertaining to the whole Stage (sequence of shapes). You can repeat a number of times; the final rep is displayed in the #Waveform area. You can also shuffle the reps (random order). Pausing is not implemented.
Shapes
Hold
Keeps a constant value for a period of time
- Duration
- time to Hold, in seconds
- Amp
- value to Hold
Ramp
Changes linearly from one value to another, over a period of time
- Duration
- length of the ramp, in seconds
- FromAmp
- value at the beginning of the ramp
- ToAmp
- value at the end of the ramp
Sine
A simple wave:
Offset + Amp * sin(t * Freq * 2π + Phase)
- Duration
- length of the wave, in seconds
- Amp
- max/-min value
- Freq
- frequency in Hz
- Phase
- in radians
- Offset
- constant vertical offset added to the wave
Step
One Step has the same effect as three Holds: it holds a "pre" Amp for a "pre" Duration, then holds an Amp for a Duration, then holds a "post" amp for a "post" duration.
- preAmp
- value to hold initially
- preDuration
- length (seconds) to hold the preAmp
- Amp
- value to hold in the middle of the Step
- Duration
- length (seconds) to hold the Amp
- (not the length of the whole shape including pre- and post- phases)
- postAmp
- value to hold at the end
- postDuration
- length (seconds) to hold the postAmp
Bits
please explain
Custom
A slice of any function of x and i. x varies linearly from "x from" to "x to" over "Duration" seconds. i is the "iteration" or repetition number, starting with 0. The function is written with Python syntax. It can use any of the common math functions (e.g. "sin"), and any functions and values defined in the Python Scripts window.
| Prev: Acquisition Notes | Outline | Next: Report |
