Behavioral Control in MATLAB



Peer-Reviewed Studies that used MonkeyLogic

Recent updates to MonkeyLogic

Download MonkeyLogic (Most recent updates on GitHub)

NEW! MonkeyLogic User's Forum 


MonkeyLogic is a MATLAB toolbox for the design and execution of psychophysical tasks with high temporal precision. It is structured to allow for the flexible construction of sensory, motor, or cognitive tasks that are based upon the interaction of a subject with visual stimuli through the use of eye-position, joystick, button, lever, and / or keyboard input.

control screen subject screen



  • Real-time experimental control with high-precision temporal replication across trials (millisecond time-scale).
  • Straightforward, MATLAB-based interface for flexible task design.
  • Able to present static images, movie stimuli, and translating images and movies, while simultaneously tracking behavior.
  • Works with widely-available data acquisition hardware for I/O functions, including eye-signal and joystick acquisition, reward delivery, digital eventmarker output, TTL and analog output.
  • Easy calibration of eye- and joystick-inputs and automatic, configurable, on-line eye-signal drift correction.
  • Graphical user interface for setting and saving a variety of task-related configuration parameters, such as video settings, I/O mappings & calibrations, and methods for condition & block selection.
  • Information-rich display of behavioral performance and within-trial events during task execution.
  • A comprehensive behavioral data file is generated by each task run that includes complete descriptions of behavioral performance, event markers and their text labels, task structure, and the actual stimulus images used. Any trial can be re-played to inspect a subject's behavior and AVI movie files can be generated from any trial to demonstrate how a task was performed.
  • Behavior can be followed over the web, and commands can be submitted remotely to alter the execution of the task (e.g., pause, quit, resume, change blocks, etc).



An experiment is constructed using two main programming elements: A conditions file and a timing script. The conditions file is a tab-delimited text file which enumerates each possible set of stimuli that can occur within any given trial of the experiment. The timing script is a a MATLAB program that determines when and under what conditions each of those stimuli are presented. The timing script can take full advantage of the resources of the MATLAB programming language to create straightforward tasks or to study complex, highly-contingent behaviors. Each stimulus is referred to as a “TaskObject” and can take the form of a visual object, a sound, or an analog or digital output (e.g., to drive a stimulator or injector).

This structure is derived from the CORTEX (“Computerized Real-Time EXperiments”) software developed originally by Thomas White in the lab of Robert Desimone (formerly at the NIH, now at MIT) and in wide use by many other labs as well. This organization has two main benefits: 1) The timing file(s) can be written efficiently, so as to operate independently of the actual stimuli being presented on any particular trial, and 2) The explicit enumeration of all conditions and block structures greatly facilitates data analysis.

main menu

The independence of timing files from particular stimuli allows a timing file to present, for example, a sequence of pictures whose identity and position may vary from trial to trial. Timing files call up TaskObjects without regard to these specifics. For example, suppose one is constructing a delayed-match-to-sample task. TaskObjects 1-3 each might then refer to a picture object. The timing file can first present TaskObject1, then later present TaskObject2 and TaskObject3, and wait for target acquisition of TaskObject2 (for example, by saccade or joystick maneuver), regardless of which pictures the TaskObjects actually contain and where they are placed on the screen. The specific pictures and locations are specified by the conditions file. The conditions text file would specify which picture appears first by listing that picture under the TaskObject1 column. In the delayed-match-to-sample rule, for instance, the matching target picture can be re-specified as TaskObject2, and the timing script would simply assume that TaskObject2 is always the target of the correct response. A separate line determines the TaskObjects for each individual condition (i.e., each possible permutation of TaskObjects).

Because conditions are explicitly defined and each is associated with a unique condition number, an analysis can simply pull out those conditions which conform to any specific combination of stimuli or stimulus features (e.g., picture identity, picture location, distractor position, etc).

Despite running in a non-real-time operating environment (Windows), high performance can nevertheless be achieved in an appropriately configured system, and is possible on modern, multi-core machines and by the use of DirectX extensions (SVI Toolbox) to control a video display with sub-millisecond resolution.

MonkeyLogic will store a comprehensive record of behavioral data; However, it is assumed that a separate acquisition system (e.g., Plexon) is available to acquire neural data (LFPs, EEG, spike waveforms, etc). The two data files can then by synchronized for analysis by aligning event markers stored locally with those sent digitally by MonkeyLogic to the acquisition system.

Getting Started

Example DMS Task
(Conditions File & Timing Code)


Peer-Reviewed Studies that used MonkeyLogic

If you use MonkeyLogic in your published work, citing it with one or more of these references is greatly appreciated, as this will enable us to more easily continue funding to support and enhance it. The studies below cite at least one MonkeyLogic paper. Thank you.

Cortical Information Flow during Flexible Sensorimotor Decisions
Markus Siegel, Timothy J. Buschman & Earl K. Miller
Science, 2015, Vol. 348 (6241), pp. 1352-1355

Microcircuitry of agranular frontal cortex: contrasting laminar connectivity between occipital and frontal areas
Taihei Ninomiya, Kacie Dougherty, David C. Godlove, Jeffrey D. Schall, & Alexander Maier
Journal of Neurophysiology, 2015, Vol. 113 (9), pp. 3242-3255

Neuronal Prediction of Opponent’s Behavior during Cooperative Social Interchange in Primates
Keren Haroush & Ziv M. Williams
Cell, 2015, Vol. 160 (6), pp. 1233-1245

Mapping of Functionally Characterized Cell Classes onto Canonical Circuit Operations in Primate Prefrontal Cortex
Salva Ardid, Martin Vinck, Daniel Kaping, Susanna Marquez, Stefan Everling, & Thilo Womelsdorf
Journal of Neuroscience, 2015, Vol. 35 (7), pp. 2975-2991

Anterior Cingulate Cortex Cells Identify Process-Specific Errors of Attentional Control Prior to Transient Prefrontal-Cingulate Inhibition
Chen Shen, Salva Ardid, Daniel Kapling, Stephanie Westendorff, Stefan Everling & Thilo Womelsdorf
Cerebral Cortex, 2015, Vol. 25 (8), pp. 2213-2228

Reversal Learning and Dopamine: A Bayesian Perspective
Vincent D. Costa, Valery L. Tran, Janita Turchi, & Bruno B. Averbeck
Journal of Neuroscience, 2015, Vol. 35 (6), pp. 2407-2416

Functional Mapping of Face-Selective Regions in the Extrastriate Visual Cortex of the Marmoset
Chia-Chun Hung, Cecil C. Yen, Jennifer L. Ciuchta1, Daniel Papoti1, Nicholas A. Bock, David A. Leopold, & Afonso C. Silva
Journal of Neuroscience, 2015, Vol. 35 (3), pp. 1160-1172

A MATLAB-based eye tracking control system using non-invasive helmet head restraint in the macaque
Paolo De Luna1, Mohamed Faiz Bin Mohamed Mustafar1 & Gregor Rainer
Journal of Neuroscience Methods, 2015, Vol. 235 (3), pp. 41-50

Functional MRI of visual responses in the awake, behaving marmoset
Chia-Chun Hung, Cecil C. Yen, Jennifer L. Ciuchta1, Daniel Papoti1, Nicholas A. Bock, David A. Leopold, & Afonso C. Silva
Neuroimage, 2014, Vol. 120, pp. 1-11

Functional Organization of the Orbitofrontal Cortex
Erin L. Rich & Jonathan D. Wallis
Journal of Cognitive Neuroscience, 2014, Vol. 26 (7), pp. 1347-1362

A cortical–spinal prosthesis for targeted limb movement in paralysed primate avatars
Maryam M. Shanechi, Rollin C. Hu & Ziv M. Williams
Nature Communications, 2014, Vol. 5, Article #3237

Frontoparietal Correlation Dynamics Reveal Interplay between Integration and Segregation during Visual Working Memory
Nicholas M. Dotson, Rodrigo F. Salazar, & Charles M. Gray
Journal of Neuroscience, 2014, Vol. 34 (41), pp. 13600-13613

An electrocorticographic electrode array for simultaneous recording from medial, lateral, and intrasulcal surface of the cortex in macaque monkeys
Makoto Fukushima, Richard C. Saunders, Matthew Mullarkey, Alexandra M. Doyle, Mortimer Mishkin & Naotaka Fujii
Journal of Neuroscience Methods, 2014, Vol. 233, pp. 155-165

Dynamic Integration of Task-Relevant Visual Features in Posterior Parietal Cortex
Guilhem Ibos & David J. Freedman
Neuron, 2014, Vol. 83 (6), pp. 1468-1480

Encoding of Rules by Neurons of the Human Dorsolateral Prefrontal Cortex
Matthew K. Mian, Sameer A. Sheth, Shaun R. Patel, Konstantinos Spiliopoulos, Emad N. Eskandar & Ziv M. Williams
Cerebral Cortex, 2013, Vol. 24, No. 3, pp. 807-816

Single-Neuron Mechanisms Underlying Cost-Benefit Analysis in the Frontal Cortex
Takayuki Hosokawa, Steven W. Kennerly, Jennifer Sloan & Jonathan D. Wallis
Journal of Neuroscience, 2013, Vol. 33, No. 44, pp. 17385-17397

A Comparison of Lateral and Medial Intraparietal Areas during a Visual Categorization Task
Sruthi K. Swaminathan, Nicolas Y. Masse & David J. Freedman
Journal of Neuroscience, 2013, Vol. 33, No. 32, pp. 13157-13170

Studying task-related activity of individual neurons in the human brain
Shaun R. Patel, Sameer A. Sheth, Clarissa Martinez-Rubio, Matthew K. Mian, Wael F. Asaad, Jason L. Gerrard, Churl-Su Kwon, Darin D. Dougherty, Alice W. Flaherty, Benjamin D. Greenberg, John T. Gale, Ziv M. Williams & Emad N. Eskandar
Nature Protocols, 2013, Vol. 8, No. 5, pp. 949-957

Independent Category and Spatial Encoding in Parietal Cortex
Christopher A. Rishel, Gang Huang & David J. Freedman
Neuron, 2013, Vol. 77, No. 5, pp. 969-979

Human Dorsal Anterior Cingulate Cortex Neurons Mediate Ongoing Behavioural Adaptation
Sameer A. Sheth, Matthew K. Mian, Shaun R. Patel, Wael F. Asaad, Ziv M. Williams, Darin D. Dougherty, George Bush & Emad N. Eskandar
Nature, 2012, Vol. 488, No. 7410, pp. 218-221

Single-Neuron Responses in the Human Nucleus Accumbens during a Financial Decision-Making Task
Shaun R. Patel, Sameer A. Sheth, Matt K. Mian, John T. Gale, Benjamin D. Greenberg, Darin D. Dougherty & Emad N. Eskandar
Journal of Neuroscience, 2012, Vol. 32, No. 21, pp. 7311-7315

Preferential Encoding of Visual Categories in Parietal Cortex Compared to Prefrontal Cortex
Sruthi Swaminathan & David J. Freedman
Nature Neuroscience, 2012, Vol. 15, No. 2, pp. 315-320

Specific Contributions of Ventromedial, Anterior Cingulate, and Lateral Prefrontal Cortex for Attentional Selection and Stimulus Valuation
Daniel Kaping, Martin Vinck, R. Matthew Hutchison, Stefan Everling & Thilo Womelsdorf
PLoS Biology, 2011, Vol. 9, No. 12, e1001224

Encoding of both Positive and Negative Reward Prediction Errors by Neurons of the Primate Lateral Prefrontal Cortex and Caudate Nucleus
Wael F. Asaad & Emad N. Eskandar
Journal of Neuroscience, 2011, Vol. 31, No. 49, pp. 17772-17787

Neural Substrates of Cognitive Capacity Limitations
Timothy J. Buschman, Markus Siegel, Jefferson E. Roy & Earl K. Miller
Proc. Natl. Acad. Sci., U.S.A., 2011, Vol. 108, No. 27, pp. 11252-11255

Range-Adapting Representation of Economic Value in the Orbitofrontal Cortex
Camillo Padoa-Schioppa
Journal of Neuroscience, 2009, Vol. 29, No. 44, pp. 14004-14014

This site last updated: May, 2014
© 2008-2014