Original Document “scrc guide.wpd”
from B. Fedirchuk; June 9, 1998
THE UNIVERSITY OF MANITOBA SPINAL CORD RESEARCH CENTRE
Department of Physiology Neuroscience Research Program
USER’S GUIDE TO SCRC DATA CAPTURE
AND ANALYSIS SOFTWARE
Introduction to the SCRC data capture & analysis system:
Terminology Definitions:
waveform, trace, frame, sweep, run, descriptor
also; File types created by SCRC software:
User guides to various parts of SCRC Software:
CAPTURE
CALIBRATE
ANALYSIS
QM
FRMSEL
WTSUM
RASTER
LAYOUT
Other helpful bits:
SCRC Analysis Help Page
SCRC Software Manual Pages
File Management:
Guide to SCRC FILE UTILITIES
Guide to basic, commonly used UNIX commands
How Do I?
Print a text file in Linux?
Cancel a print job?
Run SCRC software remotely using XWindows?
Mount a jaz drive or cdrom as a Linux drive?
Back up data onto a CDROM?
INTRODUCTION TO SCRC DATA CAPTURE AND ANALYSIS SOFTWARE:
Historical:
The SCRC software is a collection of programs that have been designed for the acquisition and analysis of electrophysiological data. Originally, analogue to digital (A/D) conversion rates were rather limited on most hardware platforms, so SCRC software was developed for a Masscomp computer using a UNIX operating environment. The A/D conversion rate of that system has recently been equaled (and surpassed) by inexpensive PC based systems, so the SCRC software has been ported to the Linux and QNX operating environments running on the IBM based PC. This means that a PC with an appropriate A/D card, operating under QNX, can be used to digitize data at very high sampling rates and the data can be subsequently analysed either on that same PC or another PC configured to run Linux.
“CAPTURING” DATA:
Analogue voltage signals representing electrophysiological signals (e.g.’s electroneurograms, blood pressure, extracellular recordings, intracellular recordings, etc…) and experimental indicators (e.g.’s stimulus markers, monitor of intracellular current injection, etc…) can be digitized by a computer’s A/D converter. The CAPTURE program allows the experimentor control the A/D converter so they can easily select the number of channels to be sampled, choose sampling rates that are sufficient to accurately represent the original signal and choose whether the digitization should be continuous or discontinuous (i.e. ‘free-running’ versus triggered by a trigger pulse which the experimentor will provide). CAPTURE also functions to write the data that has been digitized onto the computer’s hard disk and allow the experimentor to add a text description that will accompany that data set. During data acquisition, CAPTURE utilizes a companion program called CALIBRATE so that the signals being digizited are named and calibrated (if desired) so the digital signals can be presented more meaningfully during subsequent analysis. The experimentor can define the names and calibration parameters before digitization from within the CAPTURE program, or after digitization using the CALIBRATE program (and then re-calibrate the already digitized data).
Terminology applied to Digitized Data:
Data that has been digitized can be from different signals attached to different channels of the computer’s A/D converter, and as mentioned above, data can be digitized either continuously or discontinously. While CALIBRATE does allow us to add meaningful names to the signals as they are digitized, those names are often only meaningful for that particular experiment. In a different experiment a different signal may be digitized and analysed in very similar ways, so the analysis software must use terminology that is independent of the specific signal attached to the A/D converter. It is crucial that one understands the terminology which is used throughout the SCRC software to accurately discuss different portions of the digitized data and to understand the analysis procedures.
Continuous Digitization:
Within CAPTURE, one can choose to digitize signals on selected A/D channels continuously (at a sampling rate of their choice), which will continue either for the length of time that the experimentor has entered as the “run length” or until they manually stop the capture by pressing “q”. The data digitized in this way is called a “waveform“. A separate waveform is made for each A/D channel that has been digitized. If you had entered a name for the signal attached to the A/D board, that name will be added to each waveform. All the waveforms that are digitized at one time are saved together as a “run“. The name of the run file is set by the experimentor in CAPTURE, and unless changed, the next captured run will be automatically incremented by 1. A number is added to the end of the filename if it wasn’t there already.
This run of data is subsequently loaded into other programs specialized for analysing the data by calling it by it’s “filename” (you don’t need to type the “.frm”). Within the .frm file, all the information about how many waveform files there should be, the length of the run etc, is stored. The .frm therefore has vital information pertaining to the waveform files (.w00, .w01, .w02), so all these files should be treated as a package. DON’T DELETE A WAVEFORM FILE IN AN ATTEMPT TO DELETE WAVEFORMS THAT ARE UN-NECESSARY. That should be done using the ANALYSIS program (it will update the .frm file). Also, DON’T DELETE THE .FRM FILE AND EXPECT TO BE ABLE TO SEE THE WAVEFORMS. THE .FRM FILE CONTAINS INFORMATION THAT IS ESSENTIAL FOR DECODING THE WAVEFORM FILES.
At the end of the digitization for that run, you will be prompted to enter a “run descriptor“. This gives you the opportunity to add a one line description of that digitized data which will automatically be saved as a file named “filename.txt”. You can edit the filename.txt file using any text editor (e.g.’s: PICO, EMACS or VI) anytime later. Or, if a descriptor was not entered after the digitization (then CAPTURE would not have created the “filename”.txt file), you may create a text file using an editor and save it as “filename”.txt. Anytime the run file is loaded by a SCRC software, it searches the current directory for an appropriate .txt file which will also be loaded.
Discontinuous Digitization:
Analogue signals can be digitized either as a waveform (i.e. continuously, see above), or as a “trace“, where the signal is digitized in bursts that are discontinuous, triggered by some signal that you supply to the A/D board, and are of a user defined duration. (Sometimes data digitized as a trace is also called a “sweep” in slang since it is analogous to one sweep of an oscilloscope.) The main advantage of capturing data as a trace is that if the phenomenon of interest is associated with a specific time period (e.g. following a stimulus pulse), then you can successively digitize those areas of interest at a high sampling frequency without digitizing the signal in time periods in between (when nothing interesting is happening). This saves a considerable amount of hard disk space and makes all the data files smaller and more managable. Also, trace aquisition can be paused during capture while digitization of waveforms continues.
The CAPTURE program allows the experimentor to select some A/D channels as waveforms and others as traces, giving you the flexibility to create capture paradigms that have high sampling rates of discontinous sampling for some channels, yet permitting continuous digitization of other channels (or even the same channel) often to look at slower events with a lower sampling frequency.
Since more than one signal can be digitized discontinuously, each trigger pulse may initiate the digitization of several traces. As depicted, all the traces that are triggered from an individual trigger pulse are collectively called a “frame“. Therefore, a run can consist both of several waveforms and traces (separated into frames).
SUMMARY OF FILE TYPES PRODUCED BY SCRC SOFTWARE:
Files created by CAPTURE:
“filename”.frm -frm files are also called “runfiles”, and contain any data digitized as traces as well as information used to decode the digitized data (both for traces and waveforms) therefore, deleting of waveforms should be done from within the ANALYSIS program.
“filename”.w?? -files with extensions starting with a “w” contain the raw data digitized for an individual waveform. It is the file that the corresponding .frm file points to when ANALYSIS looks for the waveform data points.
“filename”.txt -contains a one line text descriptor of that runfile. If one wasn’t typed in after that particular capture, the .txt file will not exist but can be created later either within ANALYSIS or using a text editor.
“filename”.frd -If you are capturing frames and have “sweeps to pause” set or you press “space” during a capture to pause the acquisition of frames, you are prompted for a run descriptor for the last group of frames that were captured. These descriptions will be saved in the “filename.frd” file (for frame descriptor)
Files created by ANALYSIS:
In addition to the files created when the data was digitized, the ANALYSIS program also creates files to save parameters that are set during various analysis procedures.
“filename”.prm -contains analysis parameters saved either from within or upon exiting ANALYSIS.
“filename”.p?? -contains waveform parameter information. For example, if you set a voltage level for spike detection or define step cycles, those parameters are not added into the .w?? file (that file is only for original data), so ANALYSIS creates a new parameter file associated with the appropriate waveform.
You may also create plot files, bin-save files or copy segments of a run to a new file etc., from within ANALYSIS, but in all of these cases you will be prompted for a new file name.
AN INCOMPLETE GUIDE TO SOME COMMONLY USED UNIX COMMANDS:
SCRC software runs under UNIX or more commonly now, under “UNIX-like” environments (i.e. Linux & QNX). Currently CAPTURE is run on a PC the QNX environment, and most ANALYSIS is done in the Linux environment (this saves buying a QNX license for each analysis workstation). Therefore, in order to manage data files, the user needs to know at least some UNIX-type commands. To find out about other commands or more detail about these, either consult a Linux or UNIX manual or try the online manual by typing: “man command” at the prompt.
In general, UNIX commands are highly abbreviated (i.e. not very descriptive), and have several options available. Usually the format is “command –option” (the minus sign is important). Also, there is usually little feedback as to whether the command has been successful. (For instance when copying a file with “cp” the operating system does not say “1 file copied” or any such thing. It just performs the command.) When doing a copy “cp” or move “mv” if the destination file already exists, it is overwritten by the command without confirming that that’s what you intended to do!
Warning for the uninitiated:
A UNIX-LIKE OPERATING SYSTEM ASSUMES THAT YOU KNOW WHAT YOU ARE DOING, SO IT DOES NOT ASK YOU IF YOU REALLY INTEND TO OVERWRITE OR DELETE FILES… IT JUST DOES IT!!
THERE IS NO UN-DELETE FUNCTION IN A UNIX-LIKE OPERATING SYSTEM!! IF YOU DELETE OR OVERWRITE SOMETHING BY MISTAKE… IT’S GONE.
You can’t say that you haven’t been warned!!
Here is a VERY incomplete guide to UNIX, but these are basic commands that you’ll need or want to use at some time or other:
cd .. or valid subdirectory or path
change directory. You have to name either a valid subdirectory, or a complete path (e.g. /home/exp) or “..” to move one directory up the tree from your current location.
ls –option filename (or portion of filename with wildcard(s))
lists directory contents. Common options are “-l” (long format) and -R (recursive, lists all sub directories)
e.g. “ls -l *txt” lists all files in current directory ending with “txt” in long format (includes details)
-if you don’t understand about the asterisk, see “wildcards” below
pwd tells you the present working directory
cp filename newfilename
copies a file Note: do not use this to copy a runfile of data. See SCRC file utilities and use “copyrun” instead.
DANGER: if the newfilename already exists, it will be overwritten!
> the “redirect” symbol causes an output to be redirected to somewhere other than the screen.
e.g. “ls -l *txt > txtlist” means that the output of the “ls” command is redirected to a file called “txtlist” which will be created by the redirect command. DANGER: If the destination filename already exists, it will be overwritten!
more is a UNIX utility for displaying things like large text files or lists in pages instead of it scrolling quickly on the screen.
e.g. “more txtlist” shows the text tile “txtlist” (as created above) and is displayed page by page
| the “pipe” symbol redirects the output of a command to another program, not to a file. It is used to link
multiple commands on one command line. On the keyboard it is the key with that has 2 vertical lines (usually,
sometimes just one).
e.g. “ls -l *txt | more” and the output of the “ls command” is sent to “more” instead of to the screen directly. More then displays the output page by page.
mkdir new_directory_name
Creates a new directory in the current directory with the name that you specify.
rmdir existing_directory_name
Deletes an empty directory that you name. If the directory contains any files it tells you “not empty” and does not delete it. (therefore this is a safer way to delete directories than with an unrestricted “rm” command)
rm -options filename(s)
Is the “remove” command and the Unix equivalent of “delete”. It can be used with wildcards, but BE CAREFUL!! If you are going to use a wildcard with rm command, it is a good idea to first use that filename/wildcard combination with the “ls” command to see exactly which files will be deleted by the subsequent “rm” command. You might be surprised that an “*” matched a larger file list than you expect (or want!).
The “-i” option specifies “interactive” and will ask you if you really intend to delete that file etc. It isn’t a bad idea to use rm with the -i option until you are somewhat comfortable with unix.
BIG WARNING:
rm with a “-r” option: an “rm -r filename_or_directory_name” is the most powerful & dangerous command known to man!! “-r” means “recursive” but it might be better to think of it as meaning “remove safety features!” because in addition to the files that you specify, matching directories, and the contents of those directories and all sub-directories and their contents will be deleted. It is never a good idea to use “rm -r” with a wildcard, and it is always wise to double check that directories that you intend to delete do not also contain subdirectories with contents that do not intend to delete. Again, there is no such thing as
“undelete” or “unrm” so be careful, and don’t “rm -r” any directory unless you are sure that you want it and everything it contains obliterated!!
Now, after all that warning, “rm -r directory_name” is often used to delete a directory and it’s contents when it is not wanted anymore. A slower, but less dangerous alternative is to “cd” into that directory, delete the contents a bit at a time using an “rm filename” command, and then move to the parent directory (“cd ..”) and remove the now empty directory using “rmdir directory_name”
mv -options source_file destination_file
Is the Unix “move” command. It moves the file(s) (or directory) to either a new place if you specify a directory as the destination or to a new file if you specify a new filename. Therefore in Unix “mv” also functions as the “rename” command.
Warning: If the destination_file already exists, it will be silently overwritten!!
Warning: If you intend to mv a single file to a different directory, but the directory that you name does not exist, mv will create a new FILE (ie. function like a “rename command”). Subsequent attempts to mv other files to the non-existent directory will silently overwrite the newly renamed file. (This is the same problem as with the “cp” command, but when done you don’t still have the original copy.)
If you intend the destination to be a directory, the safe thing to do is to append a trailing “/” to its name. Doing that will cause an error message to be given if the directory doesn’t exist rather than creating a new filename. e.g. “mv filename sub_directory_name/”
wildcards
“Wildcards” are special characters that are used either alone or in conjuction with partial filenames and allow you to specify multiple filenames which will be targeted for the command. They are extremely helpful, but you should be extremely careful when combining them with “rm” commands. You may be matching more filenames than you expect, and therefore deleting more files than you intend to. If you do want to delete files using a “rm” command naming files using a wildcard(s), it’s always a good idea to first use the same filename/wildcard combination with an “ls” command to see the list of files that will be deleted with a subsequent “rm” command with the same filename/wildcard combination. Sometimes you are surprised!
* -the asterisk is a wildcard that substitutes for any character and any number of characters. In Unix, the dot before the filename suffix does not terminate the matching of an asterisk (unlike DOS), so “*” matches all files, while “*.*” matches only those filenames containing a “.” (i.e. in Unix a dot more or less just a regular character)
For example:
ls Cell1* would list: Cell1-01.frm, Cell1-01.txt, Cell10-01.frm, Cell10-01.txt etc… if they exist in the current directory
? -a question mark will specify any character, but only a single character.
For example:
ls Cell1-0?.txt would list: Cell1-01.txt, Cell1-02.txt, Cell1-03.txt etc..
Brackets [ ], are used to give a range of acceptable matches for a single character. It is sort of a “?” with restrictions.
For example:
ls Cell1-0[1-3].txt would list: Cell1-01.txt, Cell1-02.txt, Cell1-03.txt
Braces (curly brackets) { }, can be used to form a list of acceptable matches separated by a comma, that will be considered in turn.
For example:
ls Cell1-0{2,4}.txt would list: Cell1-02.txt and Cell1-04.txt
These wildcards can of course be combined.
For example: ls Cell?-*{txt,frd} would list Cell1-01.txt, Cell1-01.frd, Cell1-02.txt, Cell1-02.frd …. Cell9-15.txt, Cell9-15.frd etc.
Other helpful things to know in Unix:
history: Unix keeps a record of what commands you have typed in the current session. This list is called the “history”, and this list can be viewed (by typing “history”). These commands can then be called up using either an exclamation point or the arrow keys as described below.
! -an exclamation point is a special character that denotes that you want to re-run a previously used command. Unix knows what commands have been given in the current session from the “history” list.
How to use an !:
-2 exclamation points (!!) will repeat the previous command given in the history list. So, if the last command you typed at the prompt was “ls *txt | more”, typing !! will repeat that command.
-an exclamation point followed by a letter (or letters) will repeat the most recent command in the history list that starts with that character(s): eg. “!l” will repeat “ls *txt | more” if that was the last command in the list starting with an “l”.
-an exclamation point followed by a number will repeat that command (the number denotes the number of the history list)
Note: the exclamation point is somewhat shell dependent so it may be a bit different on some systems (esp. some QNX shells)
up arrow, down arrow: are used to scroll through the commands currently in the history list. It’s especially nice because you can edit the command before pressing “return”
files starting with a “-“: since the dash is normally used to denote an option following a command, if you inadvertently create a file started with a hyphen, you will have to use;
command ./-filename (where the command could be rm, mv, cp etc.)
OTHER HELPFUL HINTS:
How do I print text files in Linux?
Usually the command for printing a text file within Linux is “lpr filename“. If some line lengths are long, you may find that the line runs off the page, in which case you should first wrap the long lines onto the next line using the “fold” utility. So, if you were to want to make a file containing all the text descriptors from the data files and print them, you could do it as follows:
more *txt > descriptors #more reads all of the .txt files and the output is redirected to a new file named “descriptors”
fold descriptors | lpr #folds the long lines so they don’t run off the page and then pipes the output to lpr which prints it.
you may want to direct the output to the default network printer, so the lpr command should be used with the options -Phpt which defines the destination. i.e. fold descriptors | lpr -Phpt
How do I cancel a print job?
The contents of the printer spooler can be viewed using the “lpq” command (lp query), to cancel a print job that’s on the spooler, use the command:
lprm print_job_number
In QNX, to see the print spooler contents you use “lprq” and to cancel a print job use:
lprrm print_job_number
How do I run SCRC software remotely via XWindows?
If you have a system that runs XWindows, then you can log onto a networked Linux (or QNX) system and run SCRC software remotely. On your own system (the remote system) you have to start a remote xterminal and then add the host system to your XWindows host list with the command “xhost +host_name“. On the host system you then need to tell it to display the application on your remote Xterminal. So, depending on the whether the remote system is QNX or Linux, and also depending on what shell that system is configured to use for Xapplications, one of the following commands will have to run on the host system (you’ll have to figure out which one works):
“setenv DISPLAY remote_name:0″
or “export DISPLAY remote_name:0″
or “DISPLAY=remote_name:0″ followed by “export DISPLAY”
After this, if you start an application in your remote Xterminal, it will displayed on your terminal.
How do I mount a jaz drive or cdrom in Linux and/or QNX?
In Linux you mount a drive by typing “mount /cdrom” or “mount /jaz” and unmount the disk with “umount /cdrom” or “umount /jaz”. Of course you will not be able to un-mount the drive if your present working directory is on that drive, because it will say “device busy”.
By default, Linux mounts the DOS partition at startup as /dos/c (or /dos/d). Note: on old Linux systems it may be /dosd or /dosc (Currently we don’t normally mount jaz cartridges on Linux machines, but that will likely change before long.)
In QNX the commands are different…. they are “mntcd” or “mntjaz” to mount and “umntcd” and “umntjaz” to un-mount. Same as above about the “device busy” error.
QNX does not mount the DOS partition by default. (so it isn’t seen by a “df” command).
How do I back up data onto a cdrom?
Briefly, you collect all the data files that you want to write onto a cdrom into one directory, either on the hard drive of that Linux or QNX system or more commonly on a jaz cartridge. You then run “isomaster” on that system (in QNX), and after going through all the prompts for volume names, address and preparer ID’s etc, you name the directory to backed up as the source. Isomaster will then read all that data and write it into one very large file on that system’s DOS partition (usually the /dos/d drive). Here it will tell you the size (in MB) of all the files that you are going to backup and warn you if they will not fit onto one cdrom. Isomaster by default the suffix “.iso” to its default volume name and creates a “filename”.iso file. If want a different filename, add a “.iso” suffix to it since Easy-CD Pro will be looking for an “.iso” file type. Once the filename.iso file is made, you reboot the computer into Windows95 and start Easy-CD Pro. There you do not use the “wizard”, but rather chose to create a cdrom from an “image file”. You then browse to the appropriate drive (usually d:) and choose the filename.iso file that you made using “isomaster”. Next you decide whether you want Easy-CD Pro to “test” the file before writing it (perhaps a good idea, but usually not done because it doubles the time required to make the cd). If you decide to skip the test procedure, you un-check the test box (which is checked by default). The rest of the defaults are fine (e.g. writing at 2x etc.) and then you click on “write” on the Easy-CD Pro toolbar (the button with the red dot). If you are writing a full cdrom (~630 MB) it will take about 45 minutes for the cdrom to be “burned”. It’s a good idea to check that the cdrom is readable, and before leaving MAKE SURE YOU DELETE YOUR filename.iso IMAGE FILE FROM THE DOS DRIVE. Someone else may want to make a cdrom but not have enough hard disk space if you leave your file there. Lastly, reboot the computer back into QNX, since someone may want to telnet to it or analyse data remotely using XWindows. By the way, it is always a good idea to have more than one backup copy of files around in case the cdrom is ever damaged or lost. Writeable cdrom disks are very inexpensive (< $4 each), so don’t worry about not having them full, or about the cost of multiple backup copies.