MatOFF Scripting Language
Introduction
MatOFF has powerful scripting capabilities. The scripting mechanism is nested and permits multiple levels of replaceable parameters. Further, nearly every MatOFF action that can be executed from a menu option can also be executed from the command line or from a script file. Scripting can be used to run very large batch files of neuronal data. Scripting can also be used to simplify interactive processing by reducing the number of keystrokes. One command can automatically generate a detailed script that can reproduce every aspect of the current state of MatOFF.
In addition to the MatOFF scripting language, there is an interface that integrates MATLAB scripts into MatOFF. This MATLAB programming interface was developed for handling experimental paradigms where the behavior is dynamic (e.g. learning). However, the full power of MATLAB is available using this interface and can provide solutions to problems not solved using protocol files. See History scripting for details. Data can be sent to history scripts from protocol files using the History data command.
Simple scripts (protocol files)
The simplest script is simply a file of MatOFF commands. This type of file is called a protocol file and the default file extension is .pro. A protocol file is executed using the Load command or from within a batch file using the Pcoff command. A protocol file can include any MatOFF command, with a few exceptions. There are certain MatOFF commands designed especially for use in protocol files. MatOFF uses the environmental variable PROTOCOLPATH to determine the default directory for saving and loading protocol files. If PROTOCOLPATH is not defined, the MatOFF
DEFAULTPATH value is used. Lines beginning with a semicolon (";") are treated as a comment line in a protocol file.
Commands not available in a protocol file
Commands of special utility in protocol files
End | Stop the execution of a protocol file, clear all associated files |
Break | Interrupt protocol file (resume with Continue command) |
Exit | Quit both MatOFF and MATLAB |
Fileerror | Determine how to react to a failed File command |
The startup.pro protocol file
The special protocol file startup.pro is executed whenever MatOFF is started. It is a handy way to customize MatOFF. Startup.pro must be in the default MATLAB directory when the MatOFF command is given. See the Getting started section.
Automatic creation of a protocol file (the Save command)
The Save command will create a protocol file that is a snapshot of all the current MatOFF settings. It is a valuable tool for saving either the current search strategy or the graphical layout parameters. The file created with the Save command can be used to recreate the state of MatOFF. Only the environmental variables are outside the scope of the parameters that are saved.
Nested protocol files (Metafiles)
Any MatOFF command that is not recognized will be treated as a request to execute a metafile. Metafiles have the same structure and rules as protocol files but must use the extension . met. Metafiles can be called with parameters. For example, consider the file called mysort_save.met containing the following text:
; mysort_save.met save the results of a sort to a file ; use: mysort_save <filename> set sort keep set sort filename $1 show set sort nokeep
Mysort_save.met must reside in the directory identified by the METAPATH environmental variable. See the Setenv command for details. To use mysort_save, issue this command at the MatOFF command prompt. Mysort_save can also be called by a protocol file. Note that no suffix is needed to call a metafile:
>mysort_save unit256.sort
MatOFF notices that mysort_save is not a standard command, so it looks for a file called mysort_save.met. The parameter unit256.sort replaces the $1 in the mysort_save.met file. Up to nine command line arguments can be used in the metafile by following the metafile name with the arguments separated by spaces, tabs or commas. Use $0, $1, $2,...$9, $A, $B,...$K in the metafile to refer to the arguments. $0 will be substituted with the name of the command. $1 through $9 will refer to the next 9 arguments. $A through $K will refer to the next 11 arguments. (The letters A to K must be in UPPER case.) If the corresponding argument does not exist on the command line, a null string will be inserted. If the "$" character causes problem, it can be changed using the METACHAR1 environmental variable.
Metafiles have some special rules. Metafiles cannot call other metafiles. Also, the Break command cannot be issued from a metafile. One way to select a metafile name is to try out the name before creating a metafile by typing the name into MatOFF. It should return: "no such command or metafile." Otherwise, it is already a valid command name and a metafile with the same name will be ignored.
Batch files and the Pcoff command
Introduction
MatOFF simulates a DOS environment for executing batch files with theBatch command. For example, you can create a DOS-like batch file called mcopy.bat for copying files:
REM mcopy.bat use with MatOFF to copy files COPY $1 $2
This file can be called with the MatOFF Batch command:
>batch mcopy results.mwu oldresults.mwu
Within a batch file the DOS set command operates exactly like a MatOFF setenv command. Also, the Batch command recognizes the special Pcoff command within these batch files. The
Pcoff command is a combination of: the Load and Unit commands, and allows a full set of command line replacement variables. Batch processing is a powerful way to analyze large numbers of data files and units.
Using the Pcoff command in a batch file
The Pcoff command calls a protocol file, opens a data file, selects a unit, and provides for replacement parameters in a protocol file. The Pcoff command can only be called from within a batch file. The format is:
pcoff <protocol file> <file> <unit> <pcoff param1>
<pcoff
param2>...
(up to param9)
Examples:
pcoff luke.pro
pcoff luke
Either of these two commands in a batch file will load the luke.pro protocol file.
pcoff luke march28 unit28r1
This last command will load luke.pro, open the data file march28, and select unit unit28r1.
pcoff luke march28 unit28r1 45 epoch 23
This command will open the same files as above, and will also make the parameters 45, epoch, and 23 available to any protocol file commands in luke.pro. These parameters can be accessed using these equivalences:
%0 =
PCOFF always the
same %1 =
luke protocol
file name %2 =
march28 data file
name %3 =
unit28r1 unit
name %4 =
45
first parameter %5 =
epoch second
parameter %6 =
23
third parameter
%0 will always exist as the string "PCOFF". The % parameters are used
in protocol files just as the $ parameters are used in metafiles (see
above). A metafile will recognize the % parameters as well, so metafiles
can be take advantage of both sets of replacement parameters (see below).
Here is an example of how luke.pro might use the % parameters:
... sequence
[13][18][41-%1][118][119] this sequence
command becomes: sequence
[13][18][41-45][118][119] mark
%3
this mark command becomes: mark
4 sort
%2
this sort command becomes: sort
epoch
A dashed line can be used as a place holder to skip any parameter:
pcoff luke - - 45 epoch
23 do not open a file and do not select a
unit
It common to build a long batch file for processing many units:
pcoff luke march28 unit18r1 45 epoch 23 pcoff luke
march28 unit19d1 46 epoch 23 pcoff luke march28 unit20u1 47 pulse
23 pcoff luke march29 unit21r1 46 epoch 23 pcoff luke march29
unit22d1 47 epoch 23 pcoff luke march29 unit23u1 45 pulse 23
When running these long batch files, MatOFF may encounter a file that
will not open properly. Sometimes it is best to stop the batch process
when this happens. Other times it is best to skip that file and move to
the next Pcoff command. The Fileerror command controls MatOFF's behavior when a file cannot be opened.
Complex batch and script files
Here is a complex example of scripting and batch processing.
Here is a general purpose batch file to create a directory that combines data
from two experiments. It also sets the DATAPATH environmental variable to
this new directory.
combine.bat
REM combine.bat - combine data from two experiments
into one directory mkdir %1%4 copy %1%2 %1%4 copy %1%3 %1%4 cd
%1%4 set DATAPATH %1%4 |
It is a cryptic program for those who have not done any DOS batch
programming, but most of the mess is to combine file and directory names.
For instance, calling the script with this command:
call combine c:\analysis\ exp1 exp2 both
will have this effect:
mkdir c:\analysis\both
create a new ("both") directory under the analysis directory copy
c:\analysis\exp1 >c:\analysis\both copy data from the
experiment 1 directory to the new directory copy c:\analysis\exp2
c:\analysis\both copy data from experiment
2 cd
c:\analysis\both
switch to the new directory set DATAPATH
c:\analysis\both
tell MatOFF that this will be the default data path
We will combine this handy function with a list of units that are from both
experiments. For each unit we need to include the channel number from the
file and the conditions that were tested with that unit. The Pcoff
command is used to process each unit.
allstats.bat
REM allstats.bat - process all the units from both
experiments REM ---- Combine data from both experiments ---- call
combine c:\analysis\ exp1 exp2 both REM ---- Set up paths for
data and statistics ---- set DEFAULTPATH c:\analysis set FORMATPATH
c:\analysis\formats set STATPATH
c:\analysis\stats REM REM ---- Each cell has a stimulus
number and condition tested --- REM ---- (some cells were tested under
multiple conditions) --- REM REM
<protocol> <file> <unit> <stim>
<condition> <event code> pcoff dostats
oct24 th1002 123
compat 34 pcoff
dostats oct24 th1002 123
notcompat 35 pcoff dostats
oct24 th1002 123
delay 36 pcoff
dostats oct24 th1003 125
compat 34 pcoff
dostats oct25 th1012 126
compat 34 pcoff
dostats oct25 th1013 127
compat 34 pcoff
dostats oct25 th1014 128
compat 34 pcoff
dostats oct25 th1014 128
notcompat 35 pcoff dostats
oct25 th1016 129
compat 34 pcoff
dostats oct26 th1017 130
notcompat 35 pcoff dostats
oct26 th1018 131
notcompat
35 etc...
|
Each of these Pcoff commands in the batch file invokes the protocol
file "dostats.pro" The first time dostats.pro is called, the file "oct24"
is opened and the unit "th1002" is selected. The parameter %1 is assigned
the value "123" (the stimulus number), %2 is assigned "compat" (compatible
condition), and %3 is assigned to the event code "34". These are all used
to generate a statistics file.
dostats.pro ; dostats.pro append segment statistics for this unit
globalignore [19,21-23,38-39,41,100,101]
spot [37]
sort off
seg a 260-300
seg b 595-598
close append
set segment keep
set segment append
set segment name combined.seg
; note the %3 gets changed to 34, 35, or 36
sequence [32] [20] [131] [33] [%3] [40] [37] [30]
center 4
mark 2
fmt_seg c:\analysis\formats
show |
The protocol calls "fmt_seg.met" (a metafile) to control each line of the
statistics output file. The "FORMAT" line of the segstats.fmt file
determines how each output line looks. fmt_seq.met adds the type of
condition and stimulus number to each line of statistics. The call must
indicate where to put the format file. The segstats.fmt file is used when
the Show command is executed in "dostats.pro".
fmt_seq.met
; fmt_seq.met modify the format of the stats
file being written ;
; open the segment stats format file on the chosen
directory open $1\segstats.fmt
write DELIMITER ',' write
TRIAL:0 write SEGA:0:2 ; write a format that includes the stimulus
number (%1) and conditions (%2) write FORMAT
%1,%2,TRIAL,SEGA,SEGB close ascii
|
Here is a table to help keep track of the replaceable parameters:
If you are in |
These parameters can be used |
Main batch file |
no replaceable parameters allowed here |
Second batch file |
%0, %1, %2...%9 from the main batch file |
protocol file |
%0, %1, %2...%9 from the Pcoff
command, %10 and %11 (date and time) |
metafile |
%0, %1, %2...%9 from Pcoff command,
%10 and %11 (date and time) and $0, $1..$9,
$A...$K from calling line of protocol file |
Special replaceable parameters
The parameter $0 is the name of the metafile that was called. The parameters
%10 and %11 are also special. They can be used in any protocol or batch
file to get a date string (%10) or a time string (%11).
Generation of text files
Since it is often useful for MatOFF to extract data for further
analysis with other programs, MatOFF has some commands to flexibly
generate output text files. The following MatOFF commands can be
used to create any ASCII file from a MatOFF protocol file. Note that it
is most common to use these commands in a metafile or with a batch file (see
below), since metafiles and batch files can handle replaceable command line
parameters. This feature can also be used to create HTML files (web
pages).
Basic commands:
Open
<filename> |
create and open a file for writing to with the
Write command. Any previous open file is first closed. |
Append <filename> |
same as Open except the file must already exist and data written is appended to the end of the file. |
Close ascii |
closes any file open by the Open or Append commands. |
Write <text> |
writes one line of text to the open output file. |
Example generation of a SAS command file
SAS is a popular statistics software package that supports ANOVA.
MatOFF can make and save measurements from input data files, and simultaneously generate a command file for SAS. The measurements and the
commands can be given to SAS for further processing. This approach will
work with any software package that supports an ASCII scripting language.
The measurements are saved using the Set <process> keep family of commands, with careful use of format files.
The SAS command files are generated with the Open, Write and Close ascii commands listed above. The MatOFF program is distributed with two example files: anv2.pro and anv2.met. They show how we processed two data files for unit activity under several different conditions, and created a data file and a command file compatible with SAS.
Example generation of a web page
An HTML file for a web page is simply an ASCII file. It is easy to create a figure with MatOFF and then place it into a HTML file that can be viewed with a web browser. Here is an example that saves the current figure as a JPEG type file, then embeds that file into a simple web page. The example uses a protocol file (example_html.pro) that calls a metafile (gen_html.met).
example_html.pro
; example_html.pro ; name the plot set plot name
unit3a ; select jpeg graphics type setenv graphicsformat jpeg setenv
plotpath . ; send current figure to the disk plot ; create a html
file open unit3a.html gen_html UNIT_3A unit3a.jpg
Responses_from_Unit_3A:_AP10_ML3 ; close file close ascii
gen_html.met
; Call: make_html <title> <figure name>
<legend> write <html> write <head> write <meta
http-equiv="Content-Language" content="en-us"> write <meta
http-equiv="Content-Type" content="text/html; charset=windows-1252"> write
<meta name="GENERATOR" content="MatOFF"> write
<title>$1</title> write </head> write
<body> write <h1>$1</h1> write <p
align="center"><img border="0" src="$2" width="750"
height="450"></p> write <p
align="center">$3</p> write </body> write </html>
|