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. SeeHistory 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 aprotocolfile and the default file extension is .pro. A protocol file is executed using theLoadcommand or from within a batch file using thePcoffcommand. 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

The startup.pro protocol file

The special protocol filestartup.prois executed wheneverMatOFFis started. It is a handy way to customizeMatOFF. Startup.pro must be in the default MATLAB directory when theMatOFFcommand is given. See theGetting startedsection.

Automatic creation of a protocol file (the Save command)

TheSavecommand 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 theSavecommand can be used to recreate the state of MatOFF. Only theenvironmental variablesare outside the scope of the parameters that are saved.

Nested protocol files (Metafiles)

AnyMatOFFcommand that is not recognized will be treated as a request to execute ametafile. 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 calledmysort_save.metcontaining 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 theSetenvcommand for details. To use mysort_save, issue this command at theMatOFFcommand 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 parameterunit256.sortreplaces 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, theBreakcommand 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 intoMatOFF. 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

MatOFFsimulates a DOS environment for executing batch files with the Batchcommand. For example, you can create a DOS-like batch file calledmcopy.batfor copying files:

REM mcopy.bat use with MatOFF to copy files
COPY $1 $2

This file can be called with theMatOFFBatchcommand:

>batch mcopy results.mwu oldresults.mwu

Within a batch file the DOSsetcommand operates exactly like aMatOFFsetenvcommand. Also, theBatchcommand recognizes the special Pcoffcommand within these batch files. ThePcoffcommand is a combination of: theLoadandUnitcommands, 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

ThePcoffcommand calls a protocol file, opens a data file, selects a unit, and provides for replacement parameters in a protocol file. ThePcoff 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 theluke.proprotocol file.

pcoff luke march28 unit28r1

This last command will load luke.pro, open the data filemarch28, and select unitunit28r1.

pcoff luke march28 unit28r1 45 epoch 23

This command will open the same files as above, and will also make the parameters45,epoch, and23available 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 aplace holderto 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,MatOFFmay 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 nextPcoffcommand. TheFileerrorcommand controlsMatOFF'sbehavior 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.

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\bothcopy 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. ThePcoffcommand is used to process each unit.

Each of thesePcoffcommands 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  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 theShowcommand is executed in "dostats.pro".

Here is a table to help keep track of the replaceable parameters:

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 forMatOFFto extract data for further analysis with other programs,MatOFFhas some commands to flexibly generate output text files. The followingMatOFFcommands can be used to create any ASCII file from aMatOFFprotocol 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:

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 theSet <process> keepfamily of commands, with careful use offormat files. The SAS command files are generated with theOpen,WriteandClose ascii commands listed above. TheMatOFFprogram is distributed with two example files:anv2.proandanv2.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 withMatOFFand 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>