DSEPR

Home › Software › Manual Pages › DSEPR

NAME

SYNOPSIS

qcap [-nsi] [-npi] [-nbi] [-nti i ...] [-nui i ...] [-ti] [-m mode] [-df[smu]] [-wf[smu]] [-lf[smu]] [-bf[smu]] [-ff] [-sf] [[-o] outfile] [-r list] [-c file]

dsepr [-nsi] [-nbi] [-nti i ...] [-nui i ...] [-ti] [-m mode] [-df[smu]] [-wf[smu]] [-lf[smu]] [-ff] [infile] [-o outfile] [-c file]

dcavg [-nsi] [-nbi] [-nti i ...] [-nui i ...] [-ti] [-m mode] [-df[smu]] [-wf[smu]] [-lf[smu]] [-ff] [-sf] [[-o] outfile] [-r list] [-c file]

qcavg [-nsi] [-npi] [-nbi] [-nti i ...] [-nui i ...] [-ti] [-m mode] [-df[smu]] [-wf[smu]] [-lf[smu]] [-bf[smu]] [-ff] [-sf] [[-o] outfile] [-r list] [-c file]

dsepavg [-nsi] [-nbi] [-nti i ...] [-nui i ...] [-ti] [-m mode] [-df[smu]] [-wf[smu]] [-lf[smu]] [-ff] [infile] [-o outfile] [-c file]  

DESCRIPTION

Dcavg and qcavg capture a run of data from the A/D converter, much like dcap and qcap. The difference is that only one frame is generated in the frame file, consisting of the average of all sweeps triggered from each of the triggered channels. (If you select a multi-bin average, there will be one frame generated in the frame file for each bin.) The untriggered channels are stored in individual waveform files, in the usual way.

You will be prompted to hit RETURN or SPACE to start the capture.

Dcap and dcavg perform a disk capture; qcap and qcavg perform a queued capture. A disk capture allows a higher transfer rate, but requires more processing time. (Dcavg will defer the calculation of the average until after the data have been captured, limiting its usefulness.) The queued capture allows you to stop the data capture before the run length has expired, by typing a Q, or by limiting the number of sweeps. The queued capture also allows you to pause the capture of triggered channels, by hitting SPACE, or by setting the number of sweeps to capture before an automatic pause. (See PAUSING CAPTURE below.)

Dsepr reads an existing file of captured data, in raw direct-to-disk capture form, and separates the triggered and untriggered channels. Dsepavg does so as well, averaging the sweeps taken from the triggered channels.

These programs will always create a frame file, with the file name suffix .frm, which will contain, at the very least, a run header to be used by the analysis software. For unaveraged captures, the run header will be followed by one frame for each trigger pulse detected. This frame will contain raw data points from each triggered channel, captured for the duration of the frame sampling window. For averaged captures, the run header will be followed by a single frame for a normal average, or several frames representing the bins in a multi-bin average, provided at least one trigger pulse was detected. Frames in an averaged run contain an averaged trace for each of the triggered channels.

For each untriggered channel, a separate file is created, with the file name suffix .wnn, where nn is a 2 digit (decimal) waveform number. The first untriggered channel will be waveform 00; the next, waveform 01; and so on.

Dcap and dcavg also produce the raw direct-to-disk capture data file, with the file name suffix .raw, which contains data points from all specified channels, sampled at the given sampling rate. (This is not to be confused with a raw run file, which has been processed to separate the channels, but in which the traces have not been averaged.)  

Running display of average

Options

-nsi

Specifies the maximum number of sweeps allowed. Processing will cease after this number of sweeps has been triggered, even if the run length has not yet expired. Note that dcap and dcavg will perform the direct-to-disk capture for the entire run length, before even looking for sweeps. Limiting the number of sweeps for a disk capture will affect the way the run file is processed, but will not limit the size of the raw direct-to-disk capture file, nor limit the time taken to capture it.

-npi

Specifies the number of sweeps (or frames) which will be captured, before automatically pausing the capture of data from the triggered channels. This works for queued captures (qcap and qcavg) only. Triggered capture will pause after this number of sweeps have been triggered. In qcap, you are asked to enter a description of the frames just captured. You can then wait, and resume triggered capture, just like when the pause facility is invoked directly, by pressing the space bar during a queued capture. (See PAUSING CAPTURE below.) If you set this parameter to 0 (the default), then automatic pausing will not take place.

-nbi

Specifies the number of bins used in a multi-bin, real-time average. The unaveraged captures performed by dsepr, dcap, and qcap will not actually use bins, but if you set this option to 1, it will enable automatic tagging of frames; otherwise, the tagging information is ignored. For averaged captures, when this number is 0 (the default), the average is a single bin (single frame) containing all sweeps captured, and the tagging information is ignored. When another number is given, the averages are calculated in the specified number of bins, where each bin receives sweeps with a specific tag value. (I.e. sweeps with tag 0 go in the 1st bin, tag 1 in the 2nd, and so on.) The bins are written out to the frame data file as one frame for each bin. The difference between specifying 0 and 1 for this option is that when 0 is specified, the tag values are ignored, and when 1 is specified, only sweeps with tag value 0 are included in the one-bin average. See TAGGING below for more details.

-nti i ...

Specifies the number of triggered channels to extract, followed by up to that number of sample rate divisors for each channel. If this option is selected, the first channel in the input sequence is used as the trigger, followed by the specified number of triggered channels, followed by the untriggered channels (if any). The divisors are used to divide the sampling frequency, allowing each channel to be stored at a different frequency. Missing divisors default to zero (i.e. don't save points from this channel), and any extra divisors are ignored.

-nui i ...

Specifies the number of untriggered channels to extract, followed by up to that number of sample rate divisors for each channel. The divisors are used to divide the sampling frequency, allowing each channel to be stored at a different frequency. Missing divisors default to zero (i.e. don't save points from this channel), and any extra divisors are ignored.

-ti

Set the trigger pulse threshold to i (A/D units); default is 150. This value determines the change in amplitude required on the trigger pulse channel, in two sampling periods, to trigger a frame. The value must be large enough to avoid triggering on noise, and small enough so no trigger pulses are missed.

-m mode

Specifies the trigger mode to be used for scanning the trigger signal for trigger pulses, and deciding what action to take if the trigger rate is too fast for the current window. The mode can be one of C, R or I, (upper- or lower-case), corresponding to "check" mode, "retrigger" mode, and "ignore" mode. The default is "ignore" mode, where the trigger signal is only scanned between triggered sweeps, not during active windows. Any triggers occurring before the end of the window are ignored. In "check" mode, the trigger signal is scanned continuously; if any triggers occur before the end of the window, a warning is given. In "retrigger" mode, the trigger signal is also scanned continuously; if a trigger occurs before the end of the window, the current sweep is stopped, and a new sweep is triggered. (For reverse compatibility, the mode can also be F - "fast" mode - which is equivalent to "ignore" mode.)

-df[smu]

Set the post trigger delay to f, where f is given as a number of samples (at specified sampling rate) or as seconds, milliseconds or microseconds if followed by one of the letters s, m, or u. If a negative delay is specified, it indicates the amount of pre-trigger sampling desired, i.e. the window will start before the trigger by that amount. (Default is 0.)

-wf[smu]

Set the frame sampling window to f, where f is specified as above. (Default is 50m.)

-lf[smu]

set the overall run length to f, where f is specified as above. (Default is 10s for dcap, qcap, dcavg and qcavg; entire input file for dsepr and dsepavg.)

-bf[smu]

Set the total buffer length (i.e. for entire queue) to f, where f is specified as above. (Default is 2s; used by qcap and qcavg only.)

-ff

Specifies the sampling frequency (in Hz) used during the capture. (Default is 10000.)

-sf

Specifies the channel scanning frequency (conversion rate, in Hz) for the capture. (Used by dcap, qcap, dcavg and qcavg only.)

-stf

Specifies the channel number and signal threshold for the channel to be monitored for stimulator triggering. (Used by qcap and qcavg only.) On systems configured for queued, networked capture and stimulator control, this parameter specifies at least these two numbers, separated by punctuation. When the signal on the specified channel crosses the given threshold, qcap will turn on the digital output that controls the stimulator, and turn it off again when the signal drops below that level. Specify the channel number first, followed by the threshold, separated by punctuation (e.g., a comma, slash or "at" sign). The threshold is specified in A/D levels, or can be followed by "uV", "mV" or "V" if specified in microvolts, millivolts or volts. You can optionally include a hysteresis level after the threshold, again separated by a punctuation character, and again optionally followed by a voltage specifier. The hysteresis is specified relative to the threshold level: if you specify a negative hysteresis, the signal must drop by that amount below the threshold before the digital output is turned off; if positive, the triggering is based on a negative crossing of the threshold, and the digital output is turned off again after the signal rises above the threshold plus the hysteresis. Finally, you can optionally include one or two delays after the hysteresis, again separated by a punctuation character, and optionally followed by a time specifier of "us", "ms" or "s". Without the time specifier, the delays are in sampling periods at the sampling rate selected by the -f option. The first delay is the time from the detection of the threshold crossing (plus a few milliseconds of jitter elimination) to the beginning of the output trigger pulse. If a second delay is given, it will be a post-trigger delay before scanning resumes for the next threshold crossing.

infile

Specifies the file containing the raw direct-to-disk captured data. (Default is the standard input; used by dsepr and dsepavg only.)

-o outfile

Specifies the base name to be used for all output files. (Each will have its own suffix added.) Default is infile (with .raw suffix removed, if present), or data if infile is not specified. (For dcap, qcap, dcavg and qcavg, the -o flag is not required, and the default outfile is data.)

-r list

Specifies the random channel list to be used to determine the channel sequence. The list is either a string, or a file: if the argument is not the name of an existing file, the program tries to scan the string. The string is a list of channel numbers, in the desired order, separated by commas or spaces (the string should be quoted). The file is a free-format list of pairs of integers, where the first integer is the channel number, and the second is a code indicating the gain. This gain code is ignored, since the gain values are taken from the calibration information file. They are included in the file for purposes of historical compatibility with Masscomp's random channel list format. Duplicate channels may appear in the channel list, as the list will be optimized such that repeated channels are only sampled once per sampling period, even if they are to be used more than once, e.g. to capture a channel as both triggered and untriggered signals. The size allowed for the channel list depends on what the A/D hardware will allow, but most modern devices support 256 entries, which is more than enough to support all the traces and waveforms that can be captured. (Default sequence is channels 0 to 15 in that order; used by dcap, qcap, dcavg and qcavg only.) For A/D hardware that cannot handle random channel addressing, such as the EF12M, you need only specify a single channel number; the channels will be sampled sequentially, beginning with this channel.

-c file

Specifies the calibration file to be used for setting the calibration information in the run header. If this option is omitted, calibration information is taken from default.cal, if it exists in your current directory, or else from /usr/neuro/lib/default.cal. See the calibration overview in calibrate(1) to find out more about managing calibration information.

Environment Variables

The variable DACPAD indicates the device name for the A/D converter. (The default for this is "/dev/dacp0/adf0".) The variables DACPCLK0 and DACPCLK1 indicate the device names for the first and second clocks, such as "/dev/dacp0/efclk0" and "/dev/dacp0/efclk1" for the EF12M (Extended Function Module). (The defaults for these are "/dev/dacp0/clk2" and "/dev/dacp0/clk3".) On Linux-based PowerDAQ systems, the A/D doesn't have separate device nodes for the clocks, so these variables are simply set to the same device name as the DACPAD variable.

For systems configured to use a networked capture server, such as any NI USB or PCI based systems, as well as any 64-bit Linux system, the DACPAD variable will instead indicate the URL used to contact the server. If the data capture server is configured to support stimulator control via a digital output, a parameter in the URL specifies the output that will be used when triggering based on the parameters specified with the -st option.

The variable MAXADRATE should be set to the maximum allowable channel scanning rate, such as "333333" for the EF12M. (The default is "1000000".)

ADRANDOM must be set to "no" if your hardware cannot support random channel addressing. In this case, a fixed scanning sequence (incremental channel addressing) is used, starting with the first channel in the specified channel list. Also, the list should be in sequential order, otherwise a warning is issued; in any case, the first channel in the list is used to start the sequence. The gain used for all channels is the gain set for this first channel, in the calibration information file; if the gains in the calibration file are not all equal, a warning is issued. MAXADCHANS should be set to the number of channels supported by your A/D hardware, if it is anything other than the default of "16".  

TAGGING

In order to perform multi-bin averaging, it is necessary for dcavg, qcavg or dsepavg to automatically tag individual sweeps, based on conditions at the time the sweep was captured. Again, this can only be done if you have the required hardware support. You must set the number of bins option to a non-zero value to enable this feature of the software.

The tag values are obtained by sampling an encoded level on the trigger channel. This encoded level can represent up to eight different states of your signal-generating or signal-processing hardware, at the time a trigger pulse is generated. The trigger signal is sampled 0.5 ms, 2 ms, and 4 ms after the onset of a trigger pulse. The first sample measures the height of the pulse, which should be 1 ms wide. After the pulse, and before the trigger signal returns to the baseline level, this signal is expected to drop to a level between 0 and 7 sevenths of the trigger pulse height, for a length of 2 ms. The second sample measures this level, and interprets it as a tag value of 0 to 7. The third sample gives the baseline reference level. A good trigger pulse height is 1.75 Volts - that is the level we use on our systems. In other words, our trigger signals vary between 0 and 7 eights of 2 Volts. The trigger rate should never exceed about 200 Hz when using this automatic tagging scheme, to prevent false tagging. The capture rate should also be fairly high also (not less than about 5000 Hz) to guarantee adequate resolution in the levels sampled.

If your hardware cannot generate the encoded hardware state level, it should still generate a 1 ms trigger pulse; the second sample, which will be at baseline level, will always be interpreted as a tag value of 0. If your trigger pulses are not 1 ms wide, or if the trigger signal is not a clean, square signal, be sure to leave the number of bins option at 0, or the capture may behave unpredictably - frames with a bad tag level are marked as deleted in the run. The program will give you a warning, at the end of the capture, if any frames were deleted because of this.  

PAUSING CAPTURE

If you press the SPACE bar during a queued capture, then the capture of triggered channels is temporarily suspended. If you are also capturing untriggered channels, they will continue to be captured; it is merely the trigger signal which is ignored when you pause the capture.

In qcap, you will be asked to enter a description of the frames captured up to the point where SPACE was hit. You can enter a brief, one line description, then hit RETURN. This description is stored, along with the range of frame numbers, as a line of text in the frame description file. This file, which has the file name suffix .frd, is created the first time the capture is paused. If you just hit RETURN, without entering a description, then only the range of frame numbers is stored. The file can be edited later, to add or correct descriptions.

You are then asked to hit RETURN or SPACE to continue the capture of triggered channels, or type Q to stop the capture. If you continue, the trigger signal will again be scanned, causing the capture of triggered channels to resume. You can then hit SPACE again, later, to pause again.  

START TIME

FILES

SEE ALSO

BUGS

Index

NAME

SYNOPSIS

DESCRIPTION

Running display of average

Options

Environment Variables

TAGGING

PAUSING CAPTURE

START TIME

FILES

SEE ALSO

BUGS