Stimulus Mapping

API Reference

Video Tutorial

This tutorial shows how to create a New Project, open images in the Viewer, use the Stimulus Mapping module and perform Caiman motion correction

Map temporal information such as stimulus or behavioral periods.

Stimulus Mapping Module


Stimulus periods illustrated on the viewer timeline


The tabs that are available in the stimulus mapping module corresponds to the stimulus types in your Project Configuration.

You can add stimulus periods either manually or through a script.

Manual Annotation

  1. To add a stimulus manually click the “Add Row” button. This will add an empty row to the current tab page.

  2. Enter a name for the stimulus, start time, end time, and pick a color for illustrating the stimulus periods on the Viewer timeline.

  3. To remove a stimulus click the “Remove stim” button. Stimulus periods do not have to be added in chronological order.

  4. Click “Set all maps” to set the mappings for all stimulus types. You can then choose to illustrate a stimulus on the viewer timeline by selecting it from “Show on timeline”

Import and Export are not implemented yet.


At the moment, only “frames” are properly supported for the time units.


It is generally advisable to keep your stimulus names short with lowercase letters. When sharing your project you can provide a mapping for all your keys. This helps maintain consistency throughout your project and makes the data more readable.


See also

API Reference

You can also use the Stimulus Mapping module’s API to set the stimulus mappings from a pandas DataFrame.

This example creates a pandas DataFrame from a csv file to set the stimulus mappings. It uses the csv file from the pvc-7 dataset availble on CRCNS:

You can also download the csv here: stimulus_pvc7.csv

This example is meant to be run through the Viewer Script Editor

 1import pandas as pd
 2from mesmerize.plotting.utils import get_colormap
 4# Load dataframe from CSV
 5df = pd.read_csv('path_to_csv_file')
 7# Sort according to time
 8df.sort_values(by='start').reset_index(drop=True, inplace=True)
10# Trim off the stimulus periods that are not in the current image sequence
11trim = get_image().shape[2]
12df = df[df['start'] <= trim]
14# get one dataframe for each of the stimulus types
15ori_df = df.drop(columns=['sf', 'tf', 'contrast'])  # contains ori stims
16sf_df = df.drop(columns=['ori', 'tf', 'contrast'])  # contains sf stims
17tf_df = df.drop(columns=['sf', 'ori', 'contrast'])  # contains tf stims
19# Rename the stimulus column of interest to "name"
20ori_df.rename(columns={'ori': 'name'}, inplace=True)
21sf_df.rename(columns={'sf': 'name'}, inplace=True)
22tf_df.rename(columns={'tf': 'name'}, inplace=True)
25# Get the stimulus mapping module
26smm = get_module('stimulus_mapping')
28# set the stimulus map in Mesmerize for each of the 3 stimulus types
29for stim_type, _df in zip(['ori', 'sf', 'tf'], [ori_df, sf_df, tf_df]):
30    # data in the name column must be `str` type for stimulus mapping module
31    _df['name'] = _df['name'].apply(str)
33    # Get the names of the stimulus periods
34    stimuli = _df['name'].unique()
35    stimuli.sort()
37    # Create colormap with the stimulus names
38    stimuli_cmap = get_colormap(stimuli, 'tab10', output='pyqt', alpha=0.6)
40    # Create a column with colors that correspond to the stimulus names
41    # This is for illustrating the stimulus periods in the viewer plot
42    _df['color'] = _df['name'].map(stimuli_cmap)
44    # Set the data in the Stimulus Mapping module
45    smm.maps[stim_type].set_data(_df)