[Introduction] [Getting Started] [Importing Data] [Commands: Alphabetic] [Commands: Category]
[Global Settings] [Creating Plots] [Exporting Results] [Scripting] [History Scripting] [History] [Support]

MatOFF Scripting Language

[introduction] [simple scripts] [metafiles] [batch files] [complex scripts] [generating text files]

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

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 the Batch 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.

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.

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  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".

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).

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:

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>

[Introduction] [Getting Started] [Importing Data] [Commands: Alphabetic] [Commands: Category]
[Global Settings] [Creating Plots] [Exporting Results] [Scripting] [History Scripting] [History] [Support]

[MatOFF home] [LSN home] [LSN computing page]

Copyright 2000-2007, NIMH Laboratory of Systems Neuroscience
Last updated 1 March 2007

webmaster