SCRC Capture User’s Guide – Spinal Cord Research Centre

NAME

cap – interactive data capture program

SYNOPSIS

cap [ -n ] [ -f runfile ] [ -p parmfile ]

DESCRIPTION

Cap captures a run of data from the A/D converter. A run consists of a set of triggered channels, and a set of untriggered channels. The triggered channels are stored in a frame file, and the untriggered channels are stored in individual waveform files. Each channel can be sampled at any rate that is an integer fraction of the specified sampling rate.

You have the option to perform a disk capture or a queued capture. A disk capture allows a higher transfer rate, but requires more processing time. 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.

Cap allows you to set all required parameters, and then invokes qcap or dcap to perform the data capture. (See dsepr(1) for more details about the data capture, and about the files produced.)

Cap maintains, in your current directory, the file default.cap, which keeps track of all the parameters used for the previous data capture. These parameters are used as the defaults for the current capture. If this file does not exist in your current directory, it will be created. Also, if there is no default.cap in your current directory, cap will attempt to load the cap parameter file /usr/neuro/lib/parmgrps/default.cap.

If cap is invoked with either the -n option, the -f option, or the -p option, it will not go into its parameter setting mode, but will invoke qcap or dcap right away. The -n option will cause all current parameter values to be used for the capture. The -f option allows you to specify an alternate output file name, runfile; all other current parameter values are taken as-is. The -p option allows you to specify a parameter set, parmfile, to be loaded; all parameter values other than the output file name are taken from this file. The parmfile name can be a simple parameter set name, to be taken from your current parameter group, or a name of the form groupname/setname to load a set from any parameter group.

When cap is invoked without any of the above options, it displays all current parameter values. A line at the top of the display shows the free disk space remaining on the current volume. The right side-bar shows a list of alternate parameter sets which can be loaded, or a list of parameter groups; see PARAMETER SETS below for details about how to use these. A parameter is set by pressing the key corresponding to it, then entering the new parameter value. See PARAMETERS below.

Once you have finished setting the parameters, and wish to proceed to the data capture, press either C or Q. The entered parameters are then saved in the file default.cap, for the next time you run cap. Cap then invokes qcap or dcap to perform the capture. (See dsepr(1).) In either case, you will be prompted to hit RETURN once you are ready to start capturing data. The capture program will copy the calibration information into the run header of the frame file it will create.

If the capture is successful, you will be asked for a run description. You can enter one line of text to describe the run of data which was just captured. Hit RETURN when done. Cap will then attempt to “increment” the file name stored in default.cap. The last part of the file name will then be the run number.

If you leave from the parameter setting mode by pressing either ESCAPE or end-of-file, the parameters will not be saved in default.cap, and the capture will not be performed. Similarly, if you leave from the parameter setting mode by interrupting it, usually by typing Control-C, the parameters will not be saved, and the capture will not be performed.

PARAMETERS

When cap is in the parameter setting mode, you can set any capture parameter by pressing the key corresponding to it, then entering the new parameter value. Any leading or trailing spaces will be stripped away from the line you enter. You can also use the arrow keys to move the highlight from one parameter to another, and use the RETURN key to select the highlighted parameter. On an X Window terminal, you can also select a parameter by using the mouse to point and click on any parameter you want, and then type in the new value. A further mouse click, when cap is waiting for you to enter a value for a parameter, will be taken as a RETURN key press.

Note that not all parameters on the screen have a particular key associated with them. The central part of the screen is the channel table, which features rows for channels 0 through 15, and for each of these rows there are colums for the channel name, WF (i.e. waveform) number, divisor, effective rate in Hz, Tr (trace) number, divisor and rate, and a “checkbox” column, marked with an X for the channel that’s selected as trigger. It’s best to point and click these entries, on an X Window terminal, but they can be accessed by the arrow keys as well. Here is a description of each column of the channel table.

Ch Name

This column shows the number and name of each channel. You can highlight the number you want, and press RETURN, or click on the name or number, and you will be prompted for the name of the channel. This name will be updated right away in your default.cal file. If you have an A/D converter with more than 16 channels, the channel table can be scrolled: A + or – sign will appear to the left of this column, at the top and/or bottom row, showing that the table can be scrolled by clicking on that sign. You can also use the up and down arrow keys from within the top or bottom row of this table to scroll it.

WF or Tr

These columns show the waveform number and/or trace number associated with a particular channel. When blank, that particular channel will not be captured as a waveform or trace. You can set either one, or both if you want the same signal captured twice as a continuous waveform and as triggered sweeps. When selecting an empty slot for WF or Tr, you are prompted with the next available waveform or trace number, but if the slot wasn’t empty, the current number is shown. Either way, you can hit SPACE to clear the number, if you decide you don’t want this waveform or trace, or you can change the number if you want to assign the channel to a different wf/trace number in the captured run. Changing the number will cause any other affected waveform or trace numbers to be automatically reassigned so there are no gaps or duplicates. When using the mouse, because a click is taken as a press of the RETURN key when cap is waiting for a value to be entered, you can quickly add channels to be captured by double-clicking empty slots in these columns. Similarly, you can remove any channel by pointing to the WF or Tr number and using click-SPACE-click, as the SPACE bar clears the value.

Div

These columns show the sampling rate divisor for the corresponding waveform or trace. Changing these causes the corresponding effective capture rate in the next column to be automatically updated. A divisor of 0 is accepted, but is not recommended, as it will cause the channel to be captured, increasing overhead, even though none of the data will be kept. The preferred method of removing a waveform or trace is to blank out the WF or Tr number as explained above.

Hz

These columns show the effective sampling rate for the corresponding waveform or trace. Changing these causes the corresponding rate divisor in the previous column to be automatically updated. Note that the effective sampling rate for any channel must divide into the current Sampling Rate (R), described below, as the sampling rate divisor must be a whole number. If you pick a value that is inappropriate, cap will automatically adjust it to the closest valid value.

Trig

Clicking or selecting any row in this column will assign this channel as the trigger channel. This will only take effect if you’ve actually selected some channels as traces by setting the Tr number column. An X will mark the current selection.

The rest of the parameters are those that can be accessed by a single keystroke, as well as a mouse click. Below is a description of all of these parameters, and the keys used to select them.

F File

This selection allows you to select the output file name. This name refers to a group of related files. Each file name generated by the program consists of the specified file name, followed by a dot and a three character suffix which indicates the type of the file. It is recommended that you stick to alphanumeric characters and hyphens in the file name, as spaces and other punctuation have been known to cause problems later on.

L Run Length

This selection allows you to select the run length, which may be specified as either a number of samples at the sampling frequency, or as a time value, as for the pre/post trigger delay and the window duration below.

R Sampling Rate (Hz)

This selection allows you to select the sampling frequency (in Hz). The frequency used may not be exactly what you specify, since frequencies are generated by dividing a fundamental clock frequency.

K (Q)ueued/(D)isk

This selection allows you to select the type of data capture: either a queued capture or a disk capture. Enter a Q for a queued capture, or a D for a disk capture.

X Queue Buffer Length

This selection allows you to change the capture buffer length used by qcap. It may be specified as either a number of samples at the sampling frequency, or as a time value, as for the delay and the window duration below. Usually, the default value (2 seconds) is acceptable, but it may be necessary to reduce this if qcap fails to lock its pages in physical memory. This parameter can also be specified as a specific size in bytes, by entering a real number followed by a b (for bytes), kb (for kilobytes), or mb (for megabytes).

W Window Dur.

This selection allows you to select the window duration. It may be specified as either a number of samples at the sampling frequency, or as a time value, as for the pre/post trigger delay below. The window duration, which must be positive, indicates how long to sample the triggered channels for each trigger pulse.

P Pre/Post Trigger

This selection allows you to select the pre- or post-trigger delay to start of window. It may be specified either as a number of samples at the sampling frequency, by entering an integer; or as a time value, by entering a real number followed by an s (for seconds), an m (for milliseconds), or a u (for microseconds). The delay indicates how long to wait, after the detection of a trigger pulse, before sampling the triggered channels. If a negative delay is specified, it indicates the amount of pre-trigger sampling desired; the window will start before the trigger by that amount.

N Sweeps

This selection allows you to select the maximum number of sweeps (or frames) which will be captured from the triggered channels. Capture will end after this number of sweeps has been triggered, even if the run length has not yet expired. Note that if you select the disk capture, the capture is performed 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.

H Trig. Thresh.

This selection allows you to select the trigger pulse threshold. This value, specified in A/D units, determines the change in amplitude required on the trigger pulse channel, in two sampling periods, to trigger a frame; i.e. to start sampling the triggered channels. The value must be large enough to avoid triggering on noise, and small enough so no trigger pulses are missed. (An A/D unit is roughly equal to 2.5 mV, for a 10 volt input range.)

B # of Bins

This selection allows you to select the number of bins to be used for real-time averaging. This parameter is used by cavg(1) for this purpose. It also applies to cap, for the purpose of enabling or disabling automatic frame tagging. When this parameter is 0, automatic tagging is disabled, whether or not the hardware generates the proper trigger signal for tagging. When this parameter is non-zero (e.g. 1), automatic tagging is enabled. Use this feature only if your hardware is set up for this. (See TAGGING in dsepr(1) for details.)

A Sweeps to Pause

This selection allows you to select the number of sweeps (or frames) which will be captured before automatically pausing the capture of data from the triggered channels. This works for the queued capture only. Triggered capture will pause after this number of sweeps have been triggered. You can then enter a description, and resume triggered capture, just like when the pause facility is invoked directly, by pressing the space bar during a queued capture (see dsepr(1)). If you set this parameter to 0, then the automatic pausing will not take place.

M Trigger Mode

This selection allows you to select 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. In check mode, the program checks whether the trigger rate is too fast, and warns you if it is. In retrigger mode, an early trigger will end the current sweep, and begin a new frame. The ignore mode will not check the trigger signal while a sweep is in progress; it is a bit faster, and uses a bit less memory than the check mode.

Z Scan Freq.

This selection allows you to change the conversion frequency or channel scanning frequency – the rate (in Hz) at which channels are scanned in one sampling cycle. This should be set high enough to support the Sampling Rate you choose multiplied by the total number of channels you are capturing (including the trigger signal and any repeated channels). However, you should beware of setting it too high, especially if you have equipment connected to your A/D converter that does not have a very low input impedance. Setting it too high can result in sequential-channel crosstalk, because a higher impedance signal source needs more time to pull the A/D input to it’s level after the multiplexer switches to that source. A lower scanning frequency, or a low impedance buffer amplifier between the A/D card and your equipment, can minimize this problem.

O Channel Sampling Order/Origin

This selection allows you to select the channel sampling order on systems that support random channel addressing, or the first channel to be sampled on systems that don’t. Normally, you do not set this parameter directly, as it is automatically altered by changes you make to the channel table. For A/D hardware that allows random channel addressing, this parameter is a random channel list, which specifies the order in which the channels will be sampled. Enter a list of sixteen channel numbers, in the order you want, separated by spaces. For A/D hardware that cannot handle random channel access, such as the EF12M on old Masscomp systems, enter a single channel number; the channels will be sampled sequentially, beginning with this channel. For example, if you enter 13, and are capturing a total of five channels, the channels sampled will be 13, 14, 15, 0 and 1, in that order. Currently supported QNX or Linux-based data capture systems all have A/D hardware that support random channel lists.

T # of Triggered Channels

This selection allows you to select the number of triggered channels to be extracted. If you aren’t using triggered channels, enter a 0. If you are using triggered channels, 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). Normally, you do not set this parameter directly, as it is automatically altered by changes you make to the channel table.

D Divisors

This selection allows you to select the list of triggered channel divisors. Enter a divisor (a positive integer or a 0) for each triggered channel, separated by spaces. These numbers are used to divide the sampling frequency, allowing each channel to be sampled at a different frequency. A divisor of 0 means “don’t save points from this channel”. If you enter more divisors than there are triggered channels, the extra divisors are ignored. If there are too few divisors, 0 is assumed for the missing ones. Normally, you do not set this parameter directly, as it is automatically altered by changes you make to the channel table.

U # of Untriggered Channels

This selection allows you to select the number of untriggered channels to be extracted. If you aren’t using untriggered channels, enter a 0. Normally, you do not set this parameter directly, as it is automatically altered by changes you make to the channel table.

I Divisors

This selection allows you to select the list of untriggered channel divisors. Enter a divisor (a positive integer or a 0) for each untriggered channel, separated by spaces. These numbers are used to divide the sampling frequency, allowing each channel to be sampled at a different frequency. A divisor of 0 means “don’t save points from this channel”. If you enter more divisors than there are untriggered channels, the extra divisors are ignored. If there are too few divisors, 0 is assumed for the missing ones. Normally, you do not set this parameter directly, as it is automatically altered by changes you make to the channel table.

J CALIBRATE

This selection doesn’t change any capture parameters, but it launches the calibrate(1) program, to make changes to the calibration file beyond simple name changes in the channel table.

PARAMETER SETS

When cap is in the parameter setting mode, you can change all of the parameters (except the output file name), by loading in a parameter set. Cap can have up to twelve groups of up to twelve parameter sets each. The same keys are used to select a group of parameter sets and to select a parameter set within a group.

On an X Window terminal, the right side-bar shows either a list of parameter sets which can be loaded from a group, or a list of groups. Use the keys F1 through F12 to select a set or group, or use the mouse to point and click.

If cap is run from a plain ASCII terminal, the keys 1 through 9, 0, – and = are used instead of F1 through F12. Also, on a terminal with less than 34 lines, not all parameters will fit on the screen at once, but cap will display them page by page, and automatically switch pages on the display when you move to an off-screen parameter. The parameters are laid out such that the page division is at a good place on a standard 24 line display.

When no group has been selected, cap lists the groups available, and the “Group Name” field is blank. Select a group by hitting the key corresponding to it, or by using the pointing device. You will be prompted for the group name. Group names should be limited to 14 characters, and you should avoid characters that have special meanings to the system, such as spaces and slashes. If no group name exists for the selected slot, enter one and the group will be created. If a group name has already been assigned to the slot you selected, you can just hit RETURN to select that group. If you enter a different name, for a named slot, the group name is changed without affecting the contents of the group. Finally, you can enter a space to clear the group name: the group will be erased, provided it is an empty group. The selection “V VIEW GROUPS” will de-select the current group, and return you to the list of the available groups, allowing you to choose another group.

When a group has been selected, cap lists the contents of that group (the parameter sets in the group), and the “Group Name” field indicates the name of the selected group. Select a parameter set by hitting the key corresponding to it, or by using the pointing device. You can only select a slot that has a name assigned to it. The parameter set of that name will be loaded.

The selection “S SAVE PARAMETER SET” allows you to save your current parameter values as a set in the current group. (You must be in a group to save a parameter set.) After selecting the “SAVE” operation, you are asked to select the parameter set (i.e. the slot into which the parameters are to be saved). Select a slot by hitting the key corresponding to it, or by using the pointing device. You will be prompted for the parameter set name. If no set name exists for the selected slot, enter one and the set will be created. If a set name has already been assigned to the slot you selected, you can just hit RETURN to update that set with the current parameter values. If you enter a different name, for a named slot, the existing set is removed, and the new set is created with the name you chose. Finally, you can enter a space to clear the parameter set name: the parameter set will be removed, and the slot freed up. Parameter set names should be limited to 10 characters, and you should avoid characters that have special meanings to the system, such as spaces and slashes.

The selection “E LOAD EXTERNAL SET” allows you to load a parameter file located elsewhere on the system, rather than in one of the available groups. After selecting the “LOAD” operation, you are asked for the parameter file name. Enter the name of the file you want to load, complete with the .cap suffix if it has one. This can be a default.cap file that you copied or renamed previously, or one of the parameter sets from the old version of cap.

The selection “G Group Dir.” allows you to use a completely different collection of groups of parameter sets. The directory you specify must exist, but any group indexes or group directories can be created under it as required by cap. This allows you to work with your own private collection of parameter groups, instead of the system-wide collection that is used by default.

NOTES

Before cap calls qcap or dcap, if a run already exists with the same name as the selected output file name, it will be removed, along with any analysis(1) parameter files of the same name.

On an X Window terminal, cap temporarily clears the KEYMAP environment variable, to disable any keyboard mapping you may have enabled, such as the ISO Latin 1 character set. It does this so that the function keys, which are mapped internally to upper-half 8-bit characters, have their usual assignments. The side effect is that if you selected an alternate keyboard mapping, it will not work while in cap, or in any program called from cap.

If the CALFIXUP environment variable is set to the file name of an executable program, this program will be called right after a successful capture, with the name of the captured file as its command line argument. This is to facilitate the automatic calibration correction system used at the Panum Institute, where the program indicated by this variable reads the settings of knobs on the amplifiers and adjusts the calibration accordingly.

X WINDOW SUPPORT

When cap is run from an xterm (or kterm) window on an X Window terminal, a new window will be shown for the parameter setting. Like the other X Window programs in this package, cap will recognise the usual X command line options, such as -display, -geometry, -font, etc. The environment variables for setting these options will also work. (This is provided that the DISPLAY environment variable is set, and TERM is set to xterm or kterm.) See analysis(1) for details on X options and environment variables.

However, cap shouldn’t be run in the background, since the program returns to the xterm window once parameter setting is complete.

FILES

default.cap default capture parameters

/usr/neuro/lib/parmgrps/*.ini configuration files

/usr/neuro/lib/parmgrps/editprms.grp group list

/usr/neuro/lib/parmgrps/*/editprms.grp parameter set lists

/usr/neuro/lib/parmgrps/*/*.cap parameter sets

default.cal calibration information

/usr/neuro/lib/default.cal system calibration file

*.raw produced by disk capture

*.frm the frame file

*.w[0-9][0-9] untriggered waveforms

*.txt run description text line

*.frd frame description file

*.p?? parameter files

Index

Ch Name
WF or Tr
Div
Hz
Trig
F File
L Run Length
R Sampling Rate (Hz)
K (Q)ueued/(D)isk
X Queue Buffer Length
W Window Dur.
P Pre/Post Trigger
N Sweeps
H Trig. Thresh.
B # of Bins
A Sweeps to Pause
M Trigger Mode
Z Scan Freq.
O Channel Sampling Order/Origin
T # of Triggered Channels
D Divisors
U # of Untriggered Channels
I Divisors
J CALIBRATE