Other functions

Unlike readcxdata() and editcxdata(), the Maestro-related utilities described on this page are all M-file functions rather than compiled MEX functions. All are well-documented internally, so we do not include usage information for them in this guide. Assuming you have set up your Matlab search path to include the directory in which the M-files are located, simply type help functionName in the Matlab command window and start reading!

extractsectiondata() and buildsectionhist()

Maestro's intra-trial tagged sections feature was originally introduced to speed up the characterization of a recorded unit's receptive field. Since it is difficult to hold a neural unit for very long, researchers want to assess its response characteristics as quickly as possible. With tagged sections, one can present a number of different "mini-trials" dispersed over a set of actual trials. Each unique "mini-trial" presents a particular stimulus condition -- such as the direction or speed of motion of a patch of dots presented in the receptive field. A single trial would present several different stimulus conditions instead of just one. The challenge then is to extract, from the set of trial data files collected, the response data for each presentation of each tagged section, aligned with respect to the start time of the section rather than the start of the containing trial.

Two Matlab M-file functions are available to tackle this task: extractsectiondata() and buildsectionhist(). Of the two, extractsectiondata() is generally more useful because it merely culls the response data from the files -- grouped by tagged section rather than trial name -- without processing the data further. Analog response data, "spike events" on digital input channel 0 of Maestro's DIO event timer, and sorted spike train events added to the data file by JMWork or editcxdata() can all be extracted and collated by the function. Buildsectionhist() has a much more narrowly-defined purpose -- to prepare spike time histograms for each unique tagged section found among the set of trials examined. It does so only for spike events timestamped by Maestro itself.

plexmon() and plexsecthist()

The introduction of the Plexon™ Multichannel Acquisition Processor (MAP) into a number of lab rigs spurred the need for another set of Matlab utilities that integrate the data streams collected by the Plexon with the data files saved by Maestro. Plexmon() is an interactive Matlab application (with its own user interface) that runs on the same machine as the Plexon MAP server. It monitors the Plexon event timestamp stream, culls from it the timestamp data for each Maestro trial as it happens, and passes that data to a "trial handler" function that processes the data in some manner. It can also invoke readcxdata() to read in the corresponding Maestro data file and include that data in the structure passed to the trial handler. Plexmon() provides a general framework for online analysis and monitoring of an experiment using data collected by both Maestro and the Plexon. All of the "interesting" work is done in the trial handler, and users are encouraged to develop their own handlers in Matlab that suit their particular needs. One such handler, plexsecthist(), is available for general use; this M-file function builds tagged section histograms for all neural units being monitored on the Plexon. It was initially developed to make it possible to simultaneously assess the directional and speed sensitivity of multiple MT units recorded on the Plexon.

Since plexmon() interacts with the Plexon MAP server, it must be installed on the same Windows machine that runs the MAP server. The function can only run under Windows and Matlab 7.0+, and it relies on several Windows MEX functions to do its work: mexPlexOnline() handles communications with the Plexon, checkFile() checks that a file exists and is available for exclusive access, and readcxdata() reads in Maestro data files. If you use plexmon(), make sure all of these MEX files can be found on the Matlab search path. Be sure to use 32-bit MEX files (extension .mexw32) if running on 32-bit Windows, and 64-bit MEX files (.mexw64) on 64-bit Windows.

findtrialchains()

In Chained trial sequencer mode, chains of trials (1 or more consecutive presentations of the same trial) are delivered randomly to the subject. For example, given a trial set with just two trials named "A" an "B", a possible chained trial sequence might be: 3A, 1B, 2A, 5A, 8A, 10B, 5B, 6A, 4A, 1A, 7B. Since some of the adjacent chains involve the same trial, they can be collapsed into a longer chain: 3A, 1B, 15A, 15B, 11A, 7B. When analyzing the trial data files recorded during a chained trial sequence, researchers are interested in identifying every file sequence representing a contiguous, successfully completed chain of the same trial: a "success chain". Maestro sets a flag bit in the data file header field CXFILEHDR.dwTrialFlags that marks a trial as being the first completed trial in a new success chain, and analysis code can use this flag to find all such chains among the data files recorded during an experiment.

The findtrialchains(DIR, BASE) function does just that. It examines all Maestro data files named "BASE.nnnn" in the directory DIR that correspond to trials collected during a chained sequence, and finds all success chains for each type of trial that participated in the sequence. For each such chain, the function reports the numeric extension of the trial at the beginning of the chain, plus the chain's length. For example, if the base file name is "mytrial" and the function finds a success chain of length 5 starting with the file at extension 203, then the data files for that chain are: mytrial.0203, mytrial.0204, mytrial.0205, mytrial.0206, and mytrial.0207.

getrpdsummary()

The R/P Distro feature, introduced in Maestro version 1.4.0, includes the ability to write a plain text file summarizing the accumulated results for all trials employing the feature. The M-file function getrpdsummary() will read the contents of this file into Matlab. For each R/P Distro trial listed in the text file, getrpdsummary() returns the trial name, valid response range, the reward window (if defined), pass/fail statistics, and all samples accumulated in the "current" and "previous" response distributions associated with the trial. Note that the summary file format changed somewhat in Maestro v1.5.0, and getrpdsummary() was modified accordingly. Therefore, it can no longer process R/P Distro summary files generated by earlier Maestro versions!

rmvplaid()

This function -- available both as an M-file and a MEX function -- generates an image of a grayscale RMVideo single-grating or plaid target. Given the display geometry (resolution, width and height in mm, distance from the eye, background gray level), and target definition, rmvplaid() creates a NxM uint8 array holding the grayscale luminance [0..255] at each pixel in the target image. For details on its arguments and usage -- including how to display the generated image in a figure --, type help rmvplaid at the Matlab command prompt.