Frmsel June 3/98; D. McCrea originating document frmsel.wpd
Frmsel allows examination of frame files produced by cap or cavg. Frmsel can display any trace from any frame in a run file. It is invoked from the Maintenance Select-frame option of the Analysis program and then works on the current run file. It can also be run stand-alone from the shell with: “frmsel runfile“. If no run file name is specified, you will be prompted for one which may be specified with or without the “.frm” suffix.
All operations in frmsel require that a frame list be specified. This list is simply a line containing one or more frame numbers, each separated by one comma and/or one or more blanks. Ranges of frames can also be specified, by entering two frame numbers, separated by a colon or a dash.
For example, if you enter the frame list :3, 6 9-11 14,16 20
the operation will be performed on frames 1, 2, 3, 6, 9, 10, 11, 14, 16, and 20.
the word “all” will select all frames in the run file.
Frmsel has several uses that are outlined here and explained in detail below.
— assign labels to frames based on the presence of certain tag pulses. Frames can be tagged according to which stimulator was being used when the frame occurred.
— zero-adjusted traces to correct for any DC shift from frame to frame and adjust the DC baseline of all frames in the run file to that found in a chosen (reference) frame (Zero-0ffset).
–“mark” frames for deletion. Marking excludes those frames from subsequent averages or display during raw WF display with traces. Frames are flagged and not really deleted. Setting of the “delete flag” can be done automatically (by testing for criteria in a series of frames) or manually (frame by frame). Removal of the delete flag can be done automatically or manually. Deletions can be made
— by the user clicking on the trace manually.
— automatically for frames in which the data was “clipped off scale”. The user first sets a window of acceptable voltage ranges for a trace. This is useful for removing frames in which an action potential occurred.
— automatically for frames not containing a valid (user defined) “calibration pulse”
Each frame has three delete flags indicating whether a frame was deleted manually (M), deleted automatically because of a bad calibration pulse (P) or deleted automatically because of clipping (C). If set these flags are shown by their letters in both the frame Display mode and frame List mode. A dash indicates that that delete flag is not set.
The Alternator and stimulus marker pulses.
It is common practice to collect stimulus marker pulses indicating the time of occurrence of each stimulus pulse delivered and the stimulator used. There is a hardware interface (called the Alternator) between the delay-train units and the stimulators that permits gating of the stimulators. It is used for the alternation of condition and test stimuli. This interface also contains (separate) circuitry that produces a “marker” pulse of different amplitudes for each stimulator which are summed into a single analogue signal. This stimulus marker signal can be captured as an analogue trace by the cap program. Our convention is that stimlator #3 has the largest amplitude marker pulse. Other markers are progressively smaller, each by a factor of 2 (S3 > S2 > S1 > Sc > Sb > Sa).
When stimulus markers are captured as a trace, they can be used to tag frames for sorting into separate traces average for each stimulator used. Presently, only two stimulus marker values can be used by the analysis program for automatic frame sorting (tagging). These two markers must be discriminated from each other by a calibration procedure within frmsel (Set-tags).
Since Stimulus markers are an analogue signal, they can also be captured as a waveform. This allows them to be treated as “spikes” in the analysis program and used to create “spike-triggered” averages of the waveforms with respect to stimulation of a particular stimulator. An example of this is contained in the analysis documentation. When markers are captured only as a waveform, they cannot be accessed by frmsel which works on stimulus marker pulses in traces. Either as a trace or a waveform, markers indicate the time of occurrence of each stimulus and the stimulator used. They do not indicate stimulus intensity or duration.
Note that tagging of frames by capturing the stimulus marker signal as a trace (useing Set-tags in analysis of the frmsel program from the shell) is different than tagging frames during capture using the Bins option of cap or cavg. When capturing with Bins >0 the frames are automatically tagged according to the “state” of the alternator interface. There are 8 defined alternator states. A typical application of Bins > 0 is to use stimulator #1 for the test stimulus, and #2 for the conditioning stimulus. Three alternator states are then chosen with state 1 having only S#1 enabled, state 2 having S#2 enabled and state 3 having stimulator #1 and #2 enabled. If Bins>0 in cap then the frames can be automatically sorted according to their tags before averaging in the analysis program. This can greatly speed up analysis. For example in analysis
ATF Averaging Traces by Frame
ST0 Set Tag-list to 0
G Go, calculate an averages of only those frames in which the alternator was in state 0.
The limitation of the “Bin >0” method is that only the alternator states are encoded (they are put onto the trigger channel data). The investigator must ensure that the alternator states have the desired stimulators enabled when the data is collected. In this tagging method, the actual stimulus delivery is not recorded and any mistakes made in setting up the alternator states (e. g. failure to switch on a stimulator) and the condition-test delay cannot be determined in the analysis procedure. The advantage of the Bin >0 method of frame labeling is that no additional channels are used to collect tag data; the alternator states are encoded on the trigger channel.
Cavg uses the Bins parameter differently. In cavg the number of bins is critical; in cap Bins can be any value > 0. For example, a Bins = 3 setting in cavg causes an immediate tagging and sorting of frames into three groups according to the alternator state. The result is that three averages are produced and displayed automatically.
Frmsel Menu
Auto-del Display File Interpolate List Manual-del Number-tags Quit Rows-cols-scale Set-tags Trace Undelete View-stats Zero-adjust
Auto-del This selection can perform two validity tests on a selected trace in a series of frames in the file. Any frames that fail either test are flagged as deleted, which will cause them to be ignored in subsequent analyses. You will first be asked whether you want to delete clipped traces, i.e. traces containing spikes that exceed bounds that you will specify. You are then asked whether you want to delete traces with bad or missing calibration pulses. You are next asked to enter the frame number of the trace you want to use for setting the auto-deletion parameters.
Respond by entering a single frame number. In many cases you will not know which frame number to supply. Use the Display option to show screens of frames (Rows-cols-scale parameters are useful here) to find a trace that is suitable for setting the clipping, DC offset, or calibration pulse parameters. Make a note of its number and enter it manually when prompted. Once the reference frame has been selected, the current trace for this frame is displayed and various parameters set using the mouse.
If the test for clipping was chosen, parameters Tl and Tu are set. They define a rectangle delineating the left lower and right upper bounds of the range to test for valid data in other frames. Left clicking the mouse ( button A) sets Tl (i.e. the bottom-left corner of the box) ; middle clicking sets Tu (i.e. the top-right corner of the box). If within the time interval between Tl and Tu a trace contains any points below Tl or above Tu, then the frame containing that trace will be flagged as deleted. A subsequent display of the frames (with List or Display) will show a “C” in the middle flag position (-C-).
If the test for calibration pulses was chosen, there will be 8 parameters to set, in four steps. First by Left and Middle clicking choose the time interval in which the reference voltage level will be calculated. Points in this range will be averaged to compute the reference level for that trace. Next, the parameters indicating the heights of the calibration pulse are set. Left click to set T1 and middle click to set T2. In order to be valid, a calibration pulse must rise to a height greater than T1 , then fall to a height less than T2. Next, a time range for the calibration pulse duration is set; Left click for the minimum (Pw min) and middle click for the maximum (Pw max) calibration pulse duration. These parameters indicate the time range allowed from the crossing of T1 to the crossing of T2. Finally, a time range from the beginning of the trace until the onset of the calibration pulse is set. Dmin and Dmax are set by Left and Middle clicking respectively and indicate a valid delay range to the start of the calibration pulse, i.e. the time of the crossing of T1.
After all parameters have been set, the list of frames to be examined for possible deletion is entered. In most cases enter “all”. Each frame in the list will be tested for validity, and marked as deleted (P flag or C flag) if it fails. The number of frames deleted will be reported.
Display displays the current trace (Trace) in each frame in the supplied frame list, and allows individually (manually) deletion of any frame. You are asked whether previously deleted frames are to be displayed also (answer Y or N). The traces for the selected frames will be displayed to 20 per screen (by default). Use Rows-cols-scale to change display parameters. Remember that scale=0 indicates “autoscale” mode in which the gain of each traces is determined individually by the program (default setting). Any displayed traces can be deleted by Left clicking on the offending trace. An X will be drawn through that trace. A deleted trace can be undeleted by Left clicking on it again. When done with the current screen of traces, type D to continue. If there are more frames left, they will be displayed. Middle clicking breaks from (aborts) this procedure, and immediately returns to the main menu discarding any changes made to the current (but not previous) screens.
File Chooses the frame file (run file) to be examined. You will be prompted for a run file name. Respond by entering the file name of a captured run with or without the .B .frm suffix. If the file can be opened, the run header information will be displayed, as for View-stats below.
Interpolate This selection allows you to set the interpolation option. If this option is enabled, the data points of the displayed traces will be connected by line segments. By default this option is disabled and only the data points are displayed.
List Lists the frame numbers and their deletion status for a list of frames. By default, all frames will be listed. The listing will pause when the screen is full; type RETURN to continue.
Manual-del This selection allows you to quickly delete entire ranges of frames but does not display the data. You will be prompted for a list of frames, and each frame in the specified list will be marked as manually deleted. The number of frames deleted is reported. This option obviously requires a knowledge of the frame numbers to be deleted. Frame numbers can be seen with the Display command or from within the analysis program. One way of getting frame numbers is to select a range in analysis, set the SAP option, choose ATF and then a Bin-save. Each trace that within the range that would be included in the average is shown.
Future enhancements to the analysis program will make determining frame numbers much easier. The plan is to display frame numbers on the raw waveform display when the “Mark-frames” option is enabled.
Number-tags This selection allows you to manually mark frames with numeric tags. In most cases, you enter a short sequence of numeric tags that gets repeated throughout the frame list. For example, if there was a repeating sequence of test, condition, condition+test stimulus delivery; a tag sequence of 0, 1, 2 could be assigned to all frames. Note that Set-tags reads the actual stimulus markers collected as a trace and automatically assigns tags based on these markers (i. e. Set-tags does not assume that there is a repeating sequence). Once frames are tagged, subsequent analysis can be limited to certain labels and all other frames excluded.
You are first asked for a list of numbers for the tag sequence. This list specifies the repeating sequence of numeric tags to be assigned to the frames. The format of this list is the same as for a “frame list”. Tags can be specified in any order, and can appear more than once in a list. Next, you are prompted for a list of frames. The first frame in the frame list gets the first tag in the list, the second frame gets the second and so on. Once the end of the tag list is reached, the program goes back to the start of this list. The tag sequence is repeated as often as necessary, until the end of the frame list is reached. The number of frames modified will be reported.
Quit This selection causes the program to terminate. If frmsel was invoked from analysis, you will return to the maintenance sub-menu of analysis. When running frmsel from analysis in Xwindows under Linux, a Quit brings you back to the maintenance sub-menu but the window is inactive (window bar is blue). Click on the top window bar to get an active (pink) window.
Rows-cols-scale This selection changes the number of frames shown per screen by the Display operation, and controls the magnification (Y scale). You are asked first for the number of rows, then for the number of columns of frames to be displayed. The allowed range for each is shown in parentheses, and the current setting is shown as well. Next, you are asked for the display magnification factor. Enter the magnification factor you want, if fixed magnification is desired, or enter 0 for automatic magnification (autoscale). During automatic magnification, the program determines the best factor for each frame, and shows the factors used.
Set-tags calibrates the stimulus marker pulses captured as a trace so that two marker sizes can be distnguished from each other and used to tag frames. Subsequent analysis can be limited to frames containing certain tags and other frames excluded. You are first asked which trace contains the stimulus marker pulse data. You are next asked for a frame number containing the appropriate stimulus markers as a trace (i. e. the reference frame). You should choose a frame which contains both a short and a tall stimulus marker pulse to facilitate parameter setting. The trace for this frame is then displayed. You will then have to set various parameters using the mouse.
First, choose the time range in which a reference level (baseline) will be calculated using a Left and Middle click. Points in this range are averaged to compute the baseline for that trace. Next, frmsel attempts to find two stimulus marker pulses on the displayed trace, and displays the inter-pulse latency (the time from the start of the first pulse to the start of the second). Now the parameters TP1, TP2 and TP3 are set to indicate threshold heights above the baseline. If a marker pulse rises above TP1, but not above TP2, it is called stimulus marker pulse #1. If a pulse rises above TP2, but not above TP3, it is called marker pulse #2. If a pulse rises above TP3, it is assumed to be both the addition of stimulus marker pulses (#1 and #2) that overlap. First Left click to set TP1 and Middle click to set TP2. Finally, set TP3 using either a Left or Middle click. After all parameters have been set, the list of frames to be tagged is entered. Each frame will be tested, and tagged. The number of frames modified will be reported at the end. Tags are assigned to frames as follows:
Tags Frame contains
0 no stimulus markers
1 stimulus marker #1 only
2 stimulus marker #2 only
3 both markers #1 and #2 (either separate or overlapping)
Trace This selection allows you to choose the trace to be displayed by Display or tested by the Auto-del. Trace 0 is the default trace used is the first one (trace 0).
Undelete This selection allows you to clear any of the deletion flags on any list of frames. You are first asked which flags you wish to clear. You respond by typing any or all of the letters ” M ” (manual), ” C ” (clipped) and ” P (bad cal pulse). By default, only the autodeletion flags, C and P are cleared. Next, you are prompted for a frame list. The specified flags in the frame list are cleared and the number of frames modified reported.
.View-stats shows the run header information, which includes a list of all the traces in the run that contain data.
Zero-adjust removes DC shift on the current trace in a frame list. A single frame number containing the reference trace is entered. Choose a frame containing an interval in which a baseline (reference) level can be calculated. All points in the range set with by a Left and Middle mouse click are averaged to calculate the baseline level. Zero-adjusting will subtracts this baseline from each frame, so that the baseline of the selected trace is 0 Volts in all frames.
After setting the range, you are asked to enter a list of frames to be zero-adjusted and for confirmation before proceeding with zero adjustment. This procedure is irreversible and causes a modification of the calibration information for the current trace to indicate the new zero level. The number of frames modified are reported.
“!command” Instead of typing a letter to select a menu item, you can type an exclamation point, followed by any UNIX command, then hit RETURN. A UNIX shell is invoked to interpret and execute this command. You can recall and edit the last command entered, by hitting the “up arrow” key, or Control-K, after typing the exclamation point.
“$ or %” Whenever the menu line has just been printed, you can also type
a dollar sign ( $ ), to invoke an interactive Bourne shell,
or a percent sign ( % ), to invoke an interactive C shell. In either case, the shell will continue accepting commands until you type a Control-D, to exit from the shell, and return to frmsel.
“? or /” Whenever the menu line has just been printed, you can also type either a question mark, or slash to get a short description of all choices available in the current menu.