Designing Experiments
Maestro executes two distinct kinds of experimental protocols, segmented trials in Trial mode and stimulus runs in Continuous mode. A typical experiment involves the presentation of a related set of trials or stimulus runs. A stimulus run defines one or more stimulus channels, each of which describe a periodic, noisy, or pulsatile trajectory for a particular target. Any combination of such channels can be enabled during the run, and in some cases the trajectory of a single target is the sum of more than one stimulus channel. A trial is considerably more complex and versatile. It defines the trajectories of up to 25 participating targets. Some of those trajectories may be modulated by perturbation waveforms attached to the trial. The set of data channels that are recorded and/or displayed during trial runtime are specified in the trial's channel configuration. Finally, as of v3.3.0, segment duration and target trajectory parameters may be selectively governed by "random variables", or functions of those random variables.
Targets, perturbations, channel configurations, trials, and stimulus runs can be thought of as the "building blocks" for a Maestro experiment. Generically, we refer to any such building block as an "object". Trials and stimulus runs are "dependent" objects in the sense that their definition relies upon one or more instances of the other three (independent) object classes. The main advantage of this building-block approach is reuse: We can often use the same target, channel configuration, and perturbation objects in many different trial and stimulus run definitions.
Maestro document structure - the document object tree
All component objects created by the user are organized in a hierarchical tree structure -- the document object tree -- and stored in a binary file known as the experiment document. This document also holds a number of global application settings, including video display parameters and options governing fixation behavior. Given the file extension .cxe, the experiment document is the only document type handled by Maestro, which follows the "single document interface" (SDI) model for Windows applications. Since it is designed to hold over 60000 different objects in a single file, users can often save all of their experiments in a single document -- which is one of Maestro's chief advantages over its predecessor, Cntrlx. The user views and edits the experiment document in the client area of Maestro's main frame window. The client area is split into a left pane and a right pane. The right pane is a tabbed window holding the editors for targets, channel configurations, trials, and so on. See the other chapters in this section of the guide for a detailed discussion of each of these editors. The left pane, as shown in the screenshot on the right (click on it to display a larger image), is a Windows Explorer-style tree view of the current open document. Unlike a general file system, the document's object tree is restricted both in content and structure. The screenshot shows all the kinds of objects that exist in a typical document. At the top level are five folders -- one for each of the different object classes. These exist in every document and cannot be removed or renamed by the user. Trials are always grouped into trial sets, which are the immediate children of the Trials folder. Likewise, stimulus runs are grouped into run sets, which are stored in the Stimulus Runs folder. Individual target objects can appear directly under the Targets folder, or indirectly as a member of a target set. All perturbation objects are stored under the Perturbations folder, and all data channel configurations go in the Channels folder -- there are no such entities as "perturbation sets" or "channel sets". When you create a brand-new document with the File|New command, it will contain the five top-level folders and several predefined objects. In the Channels folder is a single predefined channel configuration named "default". It is present for historical reasons and cannot be removed or renamed; however, the user can modify its definition in the Channels Editor. In addition, the Targets folder includes a single predefined target object, Chair, representing the rotational turntable upon which the animal subject sits (note that not all experiment rigs may be outfitted with a turntable). Unlike targets for the XYScope and RMVideo displays, the Chair target has no modifiable properties; it can neither be removed nor renamed.
** NEW in Maestro v3.1.2 - Trial subsets ** Prior to version 3.1.2, a trial set consisted only of zero or more trial objects. Now, a set can contain any number of trials and/or trial subsets. A trial subset is simply a collection of zero or more related trials; it may NOT contain other subsets. (The screenshot above shows an example of a trial set containing 4 subsets and 2 trials.) Subsets were not introduced to give you more flexibility in organizing your experiment trials; rather, they offer a second level of sequencing in Trial mode. If the trials in your set are divided into subsets, you can specify a sequencing mode for both the subsets and for the trials within the current subset. For more information on this new trial sequencing feature, review the chapter on the Trial mode control panel.
Editing the document tree
The user creates, copies, deletes, and renames objects in the document tree by selecting commands from the Object menu. While this menu appears as one of the top-level menus in the frame window's menu bar, it may be more conveniently accessed as the context (popup) menu for the document tree view. Simply right-click anywhere on the tree view and the menu pops up near the mouse cursor's current location. Note that certain commands may or may not be enabled depending upon the current context, and some commands pertain specifically to the current selection in the tree view.
New -- Create a new object. A cascaded popup menu appears listing all of the available object types, including entries for a target set, trial set, trial subset, or stimulus run set. The command is always enabled. After the object is created, it is inserted into the document tree at the location of the tree item that has the current focus (the one outlined by a thin dotted rectangle), if it is a valid location for the new object. If not, Maestro automatically inserts it in a valid location within the tree. For example, when you create a new trial and the current focus item is outside a trial set, the program automatically creates a new trial set under the Trials folder and places the new trial within that set. After insertion, Maestro puts the focus on the new object and brings up an "in-place" edit box to prompt the user to rename it. If you do not wish to assign a different name to the object, simply hit the Esc key or click elsewhere on the user interface.
Copy -- Copy the object currently selected in the document tree. Since the tree view supports multiple selections, it is possible to copy many objects in one go. The command is enabled if at least one object is selected; it will be disabled if the only object selected is one of the predefined objects in the tree. When an object is copied, the duplicate is not stored in some invisible "clipboard" to be pasted in later. Instead, the duplicate is created under the same parent node as the original object. Since all "sibling" nodes in the document tree must have unique names, the duplicate object's name is set to the source object's name with a digit appended (for example, "myTrial2" for the copy of "myTrial").
Rename -- Rename an item in the document tree. When this command is selected, the label of the currently focussed tree item turns into an in-place edit box. Note that there is a convenient shortcut for invoking this command: With the cursor on top of an item label, hold down the left mouse button for about 2 seconds; when you release it, the edit box appears. Type in the new name for the item, then press the Enter key or click outside the box. If the new name string is not valid, the original name is restored. The command is enabled so long as the current focus item is not one of the predefined document objects.
Delete -- Delete one or more objects in the document tree. This command is more easily invoked by hitting the Delete key, so long as the tree view has the keyboard focus (if you last clicked or typed somewhere else on the GUI, then the tree view may not have the keyboard focus!). Every selected object in the tree is deleted -- unless it is one of the predefined components, or there is a trial or stimulus run in the document that depends on that object for its definition. Whenever this is the case, the independent object is "locked", and Maestro cannot let the user remove it until all locks have been released; otherwise, the deletion would invalidate the definition of the dependent trial or stimulus run. The command is enabled so long as a user-defined object is selected in the tree.
Remove All -- Remove all user-defined objects from the current document tree. This command is rarely used; it essentially returns the document to its initial state, containing only the five top-level folders and the aforementioned "predefined" objects. Use it only when you want to start over from scratch. The command is always enabled.
Show Properties -- Show the definition of the currently focussed object in the document tree. The object's definition is loaded into the appropriate editor in the tabbed window to the right of the tree view, and that editor is brought to the front. This command is rarely accessed via the context menu; the fastest way to see an object's definition is to double-click on the object's label in the document tree!
Selecting multiple objects in the tree
On occasion you may want to select a number of different objects to move, copy, or delete from the document tree. The tree view supports some of the typical gestures for selecting multiple items. To select a contiguous range of items, click on the first item in the desired range, then hold down the Shift key while clicking on the last item. To select a non-contiguous range, hold down the Ctrl key while clicking on the items you want to select. You can also depress the mouse outside any item label, then drag the mouse around to select a range of items; a banding rectangle follows the mouse, and the current selection is highlighted as you move the banding rectangle around.
Rearranging the tree via "drag-and-drop"
Sometimes the user may need to move objects around in the document tree. For example, it may be desirable to move a subset of trials from a large trial set into a different set. If a document contains a large number of trial sets, the user might want the most frequently used trial sets to appear first in the Trials folder. Most importantly, when a trial set is executed in the Ordered trial sequencer mode, the individual trials are presented in the same order that they appear in the set -- so the user must be able to control that order! The tree view's drag-and-drop capabilities facilitate such rearrangements. Simply select the item or items you wish to move, then hold the left mouse down over the selection and drag it to a valid destination. If a given destination node cannot parent items in the selection, then the drag cursor will indicate that fact -- and if you release the mouse at that point, nothing will happen. If you drag a selected item to a valid destination, it is moved there (and removed from the old parent). If you want to copy the selection to the destination, then initiate the drag operation with the right mouse button. Then, when you release the mouse, a popup menu lets you Move, Copy, or Cancel the operation. Finally, to change the position of, say, a particular trial object within its current trial set, simply drag it on top of the trial that you want it to precede.
Object naming rules
Each object in a Maestro document has a name up to 50 characters long. We recommend restricting object names to 40 characters or less, because the Maestro data file format cannot handle longer names (that format was inherited from Maestro's predecessor, Cntrlx). The name must be unique in the sense that it cannot be shared by any sibling of the object. Valid characters include any letter or digit (A-Z, a-z, and 0-9), plus any of the following punctuation characters: .,_[]():;#@!$%*-+=<>? . Note that the space character is NOT permitted. Maestro enforces these naming rules whenever an object is copied, moved, or renamed.