Scripting Experiments in Matlab

Designing experimental protocols in Maestro's user interface can become quite tedious, particularly when it requires defining many complex trials involving many segments and more than a few participating targets. If the trials vary with the response characteristics of the neural unit acquired during an experiment, it may be impossible to edit the trial definitions before the unit is "lost". To address these concerns, the Matlab M-function maestrodoc() was introduced in May 2010 to support script-based generation of an entire Maestro experiment document. It allows you to specify all aspects of an experiment except for Continuous-mode stimulus runs, and saves the document in a plain-text file format that Maestro (as of v2.6.0) can import.

maestrodoc( op, arg ), where:

This M-function will typically be called many times from a user-developed script to rapidly generate Maestro experimental protocols. The native experiment document read and written by Maestro itself is in a condensed, binary format the details of which are handled by Microsoft support code. Maestrodoc() does not save the experiment document in this format, but instead writes a plain-text file encoded in JavaScript Object Notation (JSON) format. We refer to the JSON-formatted experiment document as the "JMX document" for short; the file ends with the extension .jmx. As of v2.6.0, Maestro can import the JMX text file (File|Import JMX doc... command); you can then make further changes and additions to your experiment within Maestro and save it as a standard binary experiment document (.cxe extension).

Notes and limitations

• 1. The function does not return a value. If an error occurs, the function aborts and prints an error message on the Matlab command console.

  2. The function relies on Java code to do its work. The Java archive (JAR) files hhmi-ms-common.jar and hhmi-ms-maestro.jar must be on Matlab's Java classpath. The most convenient way to do this is to include the line javaaddpath path_to_JAR in your Matlab startup.m file for each JAR file. Alternatively, at the Matlab command prompt, call javaclasspath(path_to_JAR). In each case, path_to_JAR is the full pathname for the JAR.

  3. The function checks all input arguments for any illegal or out-of-range parameter values. It will throw an exception if any such bad parameter value is found. Exceptions will also be thrown if an argument is incorrectly formatted. Matlab should catch the exception, abort the function (and the script that invoked it, usually), and display an error message on the console. Write your scripts carefully!

  4. IMPORTANT: A persistent variable is maintained in the function's private workspace -- the Java object encapsulating the JMX document currently being created/edited. Thus, you can perform many operations on this document without having to reopen it each time. You can only operate on one JMX document at a time.

  5. Some aspects of the native Maestro experiment document -- primarily, stimulus runs -- are not currently supported by maestrodoc() and the JMX document format. 

  6. Maestro can only import a JMX text file; it cannot export the currently open experiment document as a JMX file.

Usage details

In general, you will call maestrodoc() many times from an M-file script that you write. The first step is to open a new or existing JMX document. Then you can change the document settings (e.g., video display parameters) and add channel configurations, perturbations, targets and trials as dictated by your experimental design. Lastly, you must close the document, either discarding the changes or saving them to the JMX file you specify. The function has a steep learning curve because Maestro experiment objects -- particularly targets and trials -- are fairly complex and have a great many defining parameters. The sections to follow describe each of the supported operations in detail. This same information is available at the Matlab command prompt by typing help maestrodoc (assuming the M-file is in your command path, of course).

You'll find maestrodoc() and its supporting JAR files in a ZIP archive on the Downloads page. A sample script using the function -- examplemdoc.m -- is also included in the archive. We recommend reviewing this to learn how to use the function properly. You can use it as a template for writing your own scripts.

maestrodoc('open', filePath) : Creates a new JMX document or opens an existing one. The second argument is a character string specifying the file-system path. If it is an empty string, a brand-new, empty JMX document object is created. Otherwise, the specified file is opened and parsed as an existing JMX document; the filename extension must be .jmx. Operation fails if: (1) a JMX document is already open in the function's private workspace; (2) the specified file does not exist, does not end with the extension .jmx, or cannot be parsed as a JMX document.

maestrodoc('close', filePath) : Close the JMX document that is currently open, optionally saving it. The JMX document is saved only if filePath is a non-empty string specifying a file that can be created (existing file, if any, is overwritten); if it is an empty string, the in-memory JMX document is discarded. It is essential to close the document when you're done in order to save all the changes made since you opened it. Even if you do not save changes, you should still close the document, else you'll leave a persistent object (in the function's private workspace) lying around that potentially consumes a significant amount of heap space, hurting overall Matlab performance. Operation fails if the file cannot be created or if an error occurs while writing it. Regardless of success or failure, the current JMX document will be closed.

maestrodoc('settings', pref) : Change any general settings persisted in the Maestro experiment document. Here pref must be a Matlab structure with four fields (any other fields will be ignored):

• • pref.rmv : A numeric vector containing the RMVideo display properties [W H D BKG SZ DUR], where:

    • • W, H, D = width, height of visible display area in mm, and (perpendicular) distance from eye to screen center in mm. All are integers restricted to [50..5000].

      • BKG = display background color packed into a 32-bit integer 0x00RRGGBB (byte 2 = red, byte 1 = green, byte 0 = blue. Uppermost byte ignored. You can use the Matlab function hex2dec() to set this field.

      • SZ, DUR = spot size in mm [0..50, 0=disabled] and flash duration in # of video frames [1..9]. These parameters govern the RMVideo vertical sync flash feature introduced in Maestro 4.0.0.

  • pref.fix : A numeric vector setting horizontal and vertical fixation accuracy [H V] in Continuous mode, in degrees. H and V are floating-point values restricted to [0.1 .. 50].

  • pref.other : A numeric vector containing additional properties [D P1 P2 OVRIDE? VARATIO AUDIOREW BEEP? VSTABWIN], where:

    • • D = Fixation duration in milliseconds for Continuous mode. Integer restricted to [100..10000].

      • P1, P2 = Reward pulse lengths in milliseconds for Continuous mode. Integers restricted to [1..999].

      • OVRIDE? = Flag. If nonzero, reward pulse lengths P1,P2 override the same values specified in the individual trial definitions. Rarely used.

      • VARATIO = The variable ratio for random withholding of rewards. Integer restricted to [1..10], where 1 disables random withholding. Rarely used.

      • AUDIOREW = Duration of a tone played as an "audio reward", in ms. Integer restricted to [100..1000] or 0, which disables the feature. Rarely used.

      • BEEP? = Flag. If nonzero, a computer beep is sounded whenever a reward is delivered.

      • VSTABWIN = Length of sliding window for averaging eye position during velocity stabilization epochs. Integer restricted to [1..20] ms.

The operation fails if: (1) a JMX document is not currently open; (2) the argument pref is incorrectly formatted; (3) any of the property values in pref are invalid.

maestrodoc('chancfg', cfg) : Add a new channel configuration to the currently open JMX document, or replace an existing one. In Maestro, a trial's channel configuration tells the program which data signals should be recorded during that trial and which should be displayed in the Data Trace Display. It also includes display offset, gain, and trace color for each signal. The channel configuration itself is a distinct Maestro object containing 38 channel descriptions (16 analog, 16 digital, and six "computed" signals). It would be rather onerous to specify a description for every possible channel when you will typically only examine a small subset. You do NOT need to do so here -- just specify channel descriptions for the channels you care about! The argument cfg is a Matlab structure with two fields as described below:

• • cfg.name : The channel configuration's name. Like all Maestro object names, it can be up to 50 characters long and can include any ASCII alphanumeric character or any of these punctuation characters: .,_[]():;#@!$%*-+=<>?. No spaces are allowed. If the JMX document already contains a channel configuration with this name, it is replaced accordingly. Otherwise, a new configuration is created.

  • cfg.channels : A Nx6 cell array holding N individual channel descriptions. If it is empty, you'll create a default channel configuration. Each row {CH REC? DSP? OFFSET GAIN COLOR} in the cell array describes one channel, where:

    • • CH = Channel name, a string token. Recognized values (note alternate channel names in parentheses): analog input channels 'hgpos' ('ai0'), 'vepos' ('ai1'), 'hevel' ('ai2'), 'vevel'

      • ('ai3'), 'htpos' ('ai4'), 'vtpos' ('ai5'), 'hhvel' ('ai6'), 'hhpos' ('ai7'), 'hdvel' ('ai8'), 'htpos2' ('ai9'), 'vtpos2' ('ai10'), 'vepos2' ('ai11'), 'ai12', 'ai13', 'hgpos2' ('ai14'), 'spwav' ('ai15'); digital input channels 'di0' to 'di15'; and computed channels 'fix1_hvel', 'fix1_vvel', 'fix1_hpos', 'fix1_vpos', 'fix2_hvel', 'fix2_vvel'.  [NOTE: Analog input channel IDs like 'hgpos' refer to the channel's dedicated use in Maestro. As of Maestro 3.0, the use-specific IDs 'htpos', 'vtpos', 'htpos2' and 'vtpos2' no longer have meaning, since the FIBER1/2 optic-bench targets are no longer supported. You can still use these IDs or their generic counterparts ('ai4', etc.) to identify the corresponding AI channels. ]

      • REC? = Record flag, a scalar. Channel recorded if nonzero. Ignored for digital and computed channels.

      • DSP? = Display flag, a scalar. Channel is displayed in Data Trace Display if nonzero.

      • OFFSET = Display offset in millivolts, an integer restricted to [-90000..90000].

      • GAIN = Display gain, an integer restricted to [-5..5].

      • COLOR = Display trace color, a string: 'white', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', 'dk green', 'orange', 'purple', 'pink', and 'med gray'.

The operation fails if: (1) a JMX document is not currently open; (2) cfg is formatted incorrectly; (3) cfg.name is not a valid Maestro object name; or (4) any channel description parameter is invalid.

maestrodoc('pert', pertDef) : Add a new perturbation object to the currently open JMX document, or replace an existing one. In Maestro, a trial can include up to 4 different "trajectory perturbation waveforms". The perturbation waveform itself is a distinct object. Four types of perturbations are supported. The argument pertDef is a Matlab cell array {NAME, TYPE, DUR, P1, P2[, P3]} defining the perturbation, where:

• • NAME = The perturbation waveform object name. Again, it can be up to 50 characters long and can include any ASCII alphanumeric character or or any of the punctuation characters: .,_[]():;#@!$%*-+=<>?. No spaces are allowed. If the JMX document already contains a perturbation with this name, it is replaced accordingly. Otherwise, a new perturbation is created.

  • TYPE = 'sinusoid', 'pulse train', 'uniform noise', or 'gaussian noise'.

  • DUR = Perturbation duration in milliseconds. Integer >= 10.

  • P1..P3 = Two or three additional parameters, the number and meaning of which depend on the perturbation type:

    • • TYPE='sinusoid': P1 = period in ms, integer >= 10. P2 = phase in deg, integer in [-180..180].

      • TYPE='pulse train': P1 = ramp duration in ms, an integer >= 0. P2 = pulse duration in ms, an integer >= 10. P3 = pulse interval in ms, an integer >= P2 + 2*P1.

      • TYPE='uniform noise' or 'gaussian noise': P1 = noise update interval in ms, an integer >= 1. P2 = mean level, a floating-point value in [-1.0 .. 1.0]. P3 = seed for random number generation, an integer in [-9999999 .. 10000000].

The operation fails if: (1) a JMX document is not currently open; (2) pertDef is formatted incorrectly; (3) the perturbation name is not a valid Maestro object name; or (4) any other perturbation parameter value is invalid.

maestrodoc('tgset', name) : Add a new target set to the currently open JMX document. Argument name is a Matlab string containing the name for the new target set. It must satisfy the usual Maestro object naming rules. Operation fails if: (1) a JMX document is not currently open; (2) name is not a valid Maestro object name or duplicates that of an existing target set; or (3) name = 'Predefined', which is reserved by Maestro.  [NOTE: While the 'Predefined' target set no longer exists as of Maestro 3.0, it is still not allowed as a user-chosen target set name so that maestrodoc-generated JMX documents remain backwards-compatible with Maestro 2.x.]

maestrodoc('trset', name) : Add a new trial set to the currently open JMX document. Argument name is a Matlab string containing the name for the new trial set. It must satisfy the usual Maestro object naming rules. Operation fails if: (1) a JMX document is not currently open; (2) name is not a valid Maestro object name or duplicates that of an existing trial set.

maestrodoc('target', tgt) : Add a new target definition to the currently open JMX document, or replace an existing one. A Maestro target describes a visual stimulus, and a trial defines how one or more such targets are animated. You can only create RMVideo targets with this operation; support for defining XYScope targets was dropped in v1.2.2 of the utility. The tgt argument must be a Matlab structure with four fields:

• • tgt.set : The name of the target set in which this target should appear. The target set must already exist in the JMX document.

  • tgt.name : The target object name. Must follow the usual Maestro object naming rules. If the specified target set already contains a target with this name, it is replaced accordingly. Otherwise, a new target is created.

  • tgt.type : A string defining the RMVideo target type. The type names are abbreviations of what you see in the Maestro GUI: 'point', 'dotpatch', 'flowfield', 'bar', 'spot', 'grating', 'plaid', 'movie', 'image'

  • tgt.params : A cell array containing a sequence of one or more ('param-name', param-value) pairs. Specify only those parameters that are applicable to the target type. All unspecified parameters will be set to default values. Take advantage of the parameter defaults as much as you can to save time as you write scripts that call maestrodoc(). The table below lists all recognized target parameter names for each RMVideo target type, along with the purpose, expected format, value restrictions, and the implicit default value for each parameter.

The operation fails if: (1) a JMX document is not currently open; (3) tgt is incorrectly formatted; (2) tgt.set does not identify an existing target set in the document; (3) tgt.name is not a valid Maestro object name; (4) tgt.type is not a recognized target type; (5) tgt.params contains a bad parameter name or an invalid parameter value.

maestrodoc('trial', trial) : Add a new trial definition to the currently open JMX document, or replace an existing one. A Maestro trial describes the animation of one or more targets over time and is, by far, the most complex object in a JMX document. Its definition depends on other objects -- a channel configuration, one or more targets, and (possibly) perturbations. All such objects are identified by name, and this operation will fail if any of them do not exist in the JMX document. The trial argument must be a Matlab structure with nine fields (two of which are optional):

[IMPORTANT NOTE: Be sure to use Matlab's convention of 1-based indexing of arrays for specifying target and segment indices. Thus, for example, valid segment indices are [1..#segs], where #segs = length(trial.segs). The indices are decremented when the JMX document is imported by Maestro.]

• • trial.set : The name of the trial set in which this trial should appear. The trial set must already exist in the JMX document.

  • trial.name : The trial object name. Must follow the usual Maestro object naming rules. If the specified trial set already contains a trial with this name, it is replaced accordingly. Otherwise, a new trial is created.

  • trial.params : General trial parameters, which appear above the segment table in the Trial Editor in the Maestro GUI. It must be a cell array holding a sequence of zero or more ('param-name', param-value) pairs. The supported parameter names are listed below. There's no need to specify a value for every parameter listed here; most are rarely used. Only specify those for which the default value is not satisfactory. In fact, if all default values are acceptable, then just set trial.params = {}.

    • • 'chancfg': Name of the channel configuration applicable to this trial. If specified, it must exist in the JMX document. Default = 'default'. The 'default' configuration always exists because it is predefined when you open a brand-new experiment document in Maestro.

      • 'wt': Trial weight governing frequency of presentation in a Randomized sequence. An integer range-restricted to [0..255]. Default = 1.

      • 'keep': A scalar flag - save (nonzero) or discard (zero) data recorded during trial. Default = 1.

      • 'startseg': Turn on data recording at the beginning of this segment. Integer in [0..#segs]. If 0, the entire trial is recorded. Default = 0.

      • 'failsafeseg': If trial cut short because subject broke fixation, the data file is still saved if the trial reached the start of this segment. Integer in [0..#segs], where 0 means that the trial must finish. Default = 0.

      • 'specialop': Special feature. Recognized values: 'none', 'skip', 'selbyfix', 'selbyfix2', 'switchfix', 'rpdistro', 'choosefix1', 'choosefix2', 'search', and 'selectDur' (for 'selDurByFix', introduced in V5.0.1). Default = 'none'.

      • 'specialseg': Index of segment during which special feature operation occurs. Ignored if 'specialop'=='none'. Integer in [1..#segs]. Default = 1.

      • 'saccvt': Saccade threshold velocity in deg/sec for saccade-triggered special features. Integer value range-restricted to [0..999]. Default = 100.

      • 'marksegs': Display marker segments, [M1 M2]. If either element is a valid segment index in [1..#segs], a marker is drawn in the Data Trace Display at the starting time for that segment. Default = [0 0].

      • 'mtr': Mid-trial reward feature. Parameter value is a three-element array [M L D], where M is the mode (0 = periodic, delivered at regular intervals; nonzero = delivered at the end of each segment for which mid-trial rewards are enabled), L = reward pulse length in milliseconds (integer, range [1..999]), and D = reward pulse interval in milliseconds, for periodic mode only (integer, range [100..9999]). Default = [0 10 1000].

      • 'rewpulses': Lengths of end-of-trial reward pulses, [P1 P2], in milliseconds. The second reward pulse only applies to the special operations that involve the subject selecting one of two fixation targets. Each pulse length is an integer range-restricted to [1..999]. Default = [10 10].

      • 'rewWHVR': (As of Maestro v4.1.0) Random reward withholding variable ratio N/D for the two reward pulses, [N1 D1 N2 D2], where integers (Nm, Dm) must satisfy 0 <= Nm < Dm <= 100. Out of every Dm reps of the trial, the reward will be withheld in a randomly selected Nm reps. Default = [0 1 0 1], which disables withholding for both pulses.

      • 'stair': Staircase sequencing parameters [N S I]. N = the staircase number, an integer in [0..5], where 0 means that trial is NOT part of a staircase sequence. S = the staircase strength value assigned to the trial, a floating-point value restricted to [0..1000). I = the correct-response input channel (zero for AI12 and nonzero for AI13). Default = [0 1.0 0] (NOT a staircase trial).

  • trial.perts : List of perturbations participating in trial, with control parameters. This must be a cell vector of up to four cell vectors of the form {NAME, A, S, T, C}, where:

    • • NAME : The name of the perturbation waveform object. It must exist in the JMX document, or the operation fails.

      • A : Perturbation amplitude, range-restricted to +/-999.99.

      • S : Index of segment at which perturbation starts. Must be a valid segment index in [1..#segs].

      • T : Index of affected target. Must be a valid index into the trial's participating target list, [1..#tgts].

      • C : Affected trajectory component. Must be one of: 'winH', 'winV', 'patH', 'patV', 'winDir', 'patDir', 'winSpd', 'patSpd', 'speed', or 'direc'.

  • Perturbations are rarely used. If the trial includes no perturbations, simply set trial.perts = {}.

  • trial.tgts : The trial's participating target list, a non-empty cell array of strings, each identifying a target participating in the trial. The targets will appear in the trial segment table in the order listed. Each entry in the array must have the form 'setName/tgtName', where 'setName' is the name of an existing target set in the JMX document and 'tgtName' is the name of an existing target within that set. Note that the forward slash ('/') separating the name tokens is not a valid character in a Maestro object name. It is also possible to specify the predefined CHAIR target, which has no containing target set. Note that the old FIBER* and REDLED* predefined targets are not supported since Maestro 4 and are no longer supported by maestrodoc() (as of v1.2.2).

  • trial.tags : List of tagged sections in the trial's segment table. A "tagged section" attaches a label to a single segment in the trial, or to a contiguous span of segments. It is characterized by a label string and the indices of the first and last segments in the section. If you do not wish to define any tagged sections, simply set trial.tags = {}. Otherwise, it should be a cell array of cell arrays of the form {LABEL, START, END}, where:

    • • LABEL : The section tag. It must contain 1-17 characters. No restriction on character content.

      • START : Index of the first segment in the section. Must be a valid segment index in [1..#segs].

      • END : Index of last segment in the section. Must be a valid segment index ≥ START.

  • No two tagged sections can have the same label, and the defined sections cannot overlap. If either of these rules are violated, the operation fails.

  • trial.rvs: [Optional] The trial's random variables, if any. A cell array of 0 to 10 cell arrays, where the i-th cell array defines the i-th random variable, which are labelled x0 to x9 in Maestro. Each cell array must have one of the following forms:

    • • {'uniform', seed, A, B} : A uniform distribution over the interval [A, B], where A < B. The nonnegative integer seed parameter initializes the random number generator each time trial sequencing begins. If 0, then a different seed is chosen for each trial sequence.

      •  {'normal', seed, M, D, S} : A normal distribution with mean M, standard deviation D > 0, and a maximum spread S >= 3D. During trial sequencing, any time a generated value falls outside [M-S, M+S], that value is rejected and another generated in its place.

      • {'exponential', seed, L, S} : An exponential distribution with rate L > 0 and maximum spread S >= 3/L.

      • {'gamma', seed, K, T, S} : A gamma distribution with shape parameter K > 0, scale parameter T > 0, and a maximum spread S. The mean is KT and variance KT^2. The spread S must be at least 3 standard deviations beyond the mean, ie, S >= T(K + 3*sqrt(K)).

      • {'function', formula} : An RV expressed as a function of one or more other RVs. An RV is referenced in the formula string by its variable name, x0 to x9 (where x0 corresponds to the 1st cell array in trial.rvs, etc). In addition to these variables, the formula can contain integer or floating-point numeric constants; the named constant pi; the four standard arithmetic binary operators -, +, *, /; the unary - operator (as in -2*x1); left and right parentheses for grouping; and three named mathematical functions - sin(x), cos(x), and pow(x,y). Note that the pow() function includes a comma operator to separate its two arguments. Standard operator precedence rules are observed. It is an error for a function RV to depend on itself, on another function RV, or on an RV that was not defined in trial.rvs. Be careful to make sure the formula string is valid, as maestrodoc() does not validate function RVs. That will happen when the JMX document is imported by Maestro. 

  • trial.rvuse: [Optional] A cell array, possibly empty, indicating what trial segment parameters are governed by the random variables defined in trial.rvs. Each element of the array must have the form {rvIdx, 'paramName', segIdx, tgIdx}, where rvIdx is the 1-based index of a random variable defined in trial.rvs, segIdx is the 1-based index of the affected segment, tgIdx is the 1-based index of the affected target trajectory parameter, and 'paramName' identifies the affected parameter (a defined RV can control the value of more than one segment parameter; so there can be more entries in trial.rvuse than the number of RVs defined in trial.rvs):

    • • 'mindur', 'maxdur' : Minimum or maximum segment duration. (tgIdx ignored in this case)

      • 'hpos', 'vpos' : Horizontal or vertical target position.

      • 'hvel', 'vvel', 'hacc', 'vacc': Horizontal or vertical target velocity or acceleration. 

      • 'hpatvel', 'vpatvel': Horizontal or vertical target pattern velocity.

      • 'hpatacc', 'vpatacc': Horizontal or vertical target pattern acceleration.

  • trial.segs : The trial's segment table. This is a non-empty structure array with fields hdr and traj, as described below. The number of structures in the array is the number of segments in the trial.

    • • trial.segs(index).hdr : The segment's header, which is the list of parameters shown in the top six rows of the segment table in Maestro. The header is specified, once again, as a cell array of zero or more ('param-name', param-value) pairs. There is no need to specify a value for every parameter listed here; only specify those for which the default value is not correct.

        • 1. 'dur': The segment duration range in milliseconds, [D1 D2], where integers 0 ≤ D1 ≤ D2. When D1 < D2, the actual segment duration is randomized within the specified range. Default = [1000 1000].

          2. 'rmvsync': Enable RMVideo vertical sync flash for this segment? Nonzero = enable. Default = 0.

          3. 'fix1': Index of the first fixation target for this segment. Must be 0 ("NONE") or a valid index into the list of participating targets, [1..#tgts]. Default = 0.

          4. 'fix2': Similarly for the second fixation target. Default = 0.

          5. 'fixacc': Horizontal and vertical fixation accuracy [H V] in degrees. Each must be ≥ 0.1. Default = [5.0 5.0].

          6. 'grace': Grace period in ms for this segment. Integer ≥ 0. Default = 0.

          7. 'mtrena': Enable mid-trial reward feature for this segment? Nonzero = enable. Default = 0.

          8. 'chkrsp': Enable checking for correct/incorrect response from subject during this segment. Applicable to staircase trials only. Nonzero = enable. Default = 0.

          9. 'marker': Digital output channel number for a marker pulse delivered at the start of this segment. Integer value restricted to [0..10]; 0 = no marker, 1..10 selects DO<1..10>, respectively. Default = 0.

      • trial.segs(index).traj : A cell array of M cell arrays defining the trajectories of the M participating targets during this segment of the trial. Each of the M cell arrays contains zero or more ('param-name', param-value) pairs. Each trajectory parameter has a default value; only supply a trajectory parameter value if it is different from the default. If all parameters should be set to the defaults for target T in segment S, then trial.segs(S).traj{T} = {}. The trajectory parameters and their implicit defaults are listed here:

• • • • • 1. 'on': Target ON (nonzero) or OFF (zero). Default = 0.

          2. 'abs': Target position specified ABSolutely (nonzero) or RELative to last position (zero). Default = 0.

          3. 'vstab': Target velocity stabilization mode: 'none', 'h', 'v', 'hv'. Default = 'none'.

          4. 'snap': Enable (nonzero) or disable (zero) VStab "snap to current eye position" feature at start of segment. Default = 0.

          5. 'pos': Target horizontal and vertical position in deg, [H V]. Default = [0 0].

          6. 'vel': Target window vector velocity specified as [MAG DIR], where MAG is the vector magniture and DIR is the vector direction in deg counterclockwise from +X-axis. Note that this representation is different from what appears in Maestro -- the horizontal and vertical components of the vector velocity. Maestro handles the conversion when the JMX document is imported. Default = [0 0].

          7. 'acc': Target window vector acceleration specified as [MAG DIR]. Default = [0 0].

          8. 'patvel': Target pattern vector velocity specified as [MAG DIR]. Default = [0 0].

          9. 'patacc': Target pattern vector acceleration specified as [MAG DIR]. Default = [0 0].

• • • • There are a couple special cases in which the 'patvel' and 'patacc' variables must be treated differently.

• • • • • 1. If the target is an optic flow field, there is no pattern velocity velocity -- there is just a "flow velocity" (positive or negative). In this case, DIR is ignored and MAG is taken as the flow velocity (for 'patacc', DIR is ignored and MAG is taken as the flow acceleration).

          2. For an RMVideo 'grating' target with the 'oriadj' flag cleared, DIR is ignored and MAG is taken as the grating's drift velocity (for 'patvel') or drift acceleration (for 'patacc').

          3. For an RMVideo 'plaid' target with the 'indep' flag set, the component gratings move independently, not as a cohesive pattern. In this case, DIR is taken as the drift velocity (for 'patvel') or acceleration (for 'patacc') of the first component grating, while MAG is taken as the drift velocity or acceleration of the second component.

The operation fails if: (1) a JMX document is not currently open; (3) trial is incorrectly formatted; (2) trial.set does not identify an existing trial set in the document; (3) trial.name is not a valid Maestro object name; (4) trial.params contains a bad parameter name or an invalid parameter value; (5) trial.psgm contains a bad parameter name or an invalid parameter value; (6) trial.perts specifies a non-existent perturbation object or contains a bad parameter value; (7) trial.tgts names a target that does not exist; (8) trial.tags contains duplicate tags or overlapping/invalid sections; (9) trial.segs contains an invalid parameter name or value; or (10) the length of trial.segs(n).traj does not match the length of trial.tgts. BE CAREFUL!!!