This documentation is for the older Mesmerize legacy desktop application. Please see the home page or GitHub repo for information on the latest packages.

Project Browser

Browse, edit and sort the project DataFrame

You can open the Project Browser from the Welcome Window after you have opened a project.


The columns that are visible in the Project Browser Window correspond to the Project Configuration. For each column you will see a list which is a set of unique elements from that column in the project DataFrame.


Open Sample

Double-click on a Sample in the SampleID column to open it in the Viewer.

In the viewer you can make changes and then save it by going to File -> Add to Project. You will see a “Save changes (overwrite)” option which will overwrite the data for this project Sample with the current data in the viewer work environment. If you have not changed the image sequence data you can uncheck the “Overwrite image data” checkbox, useful if your image sequences are large.



You can make any changes that you want to the Sample. This may include things such as changing or adding new tags to ROIs, changing stimulus maps, tagging a new custom column etc.


You can never change the AnimalID or TrialID (i.e. SampleID) since these are partially used as unique identifiers. A workaround is described in the FAQ for Project Organization.


You can sort your Project DataFrame into different groups (such as experimental groups) using text and numerical filters. Type a filter into the text entries that are below the list of elements for a column. You can also click on one or many elements in a column to set those elements as the filters.

If you filter out of the root tab, it will always create a new tab with a name of your choice. If you filter out of any other tab it will apply the filter in-place unless you right click on the “Apply” button and choose “Apply in new tab”

Text filters

Partial match

To filter out a group based on partial text matches just enter the text into the filter text entry below the column(s) of interest and click “Apply”


Since this is filtering out of the root tab, you will be prompted to give a name for a new tab that will be created based on the filter you have entered.


The result is a DataFrame containing all rows where the cell_name contains ‘aten’


If you go to View -> Current dataframe you can see the whole dataframe.


To see how the filter translates to pandas commands go to View -> Current tab filter history


Multiple filters

You can combine filters together by using the | seperator. The | acts as an “or” operator.


The result is all rows where mn, palp, or pr are in the cell_name column.



This can be combined with Modifiers

Filter multiple columns

You can filter multiple columns simultaneously if you are not in the root tab. You can create a new tab that is essentially the same as the root by just keeping the filter entries blank and clicking “Apply”.

Filter out all rows where the cell_name column contains ‘pr’ and promoter column contains ‘pc2’ or ‘cng_ch4’.


Right click on the “Apply” button and choose “Apply all” or “Apply all in new tab”


If you view the pandas filter history (View -> Current tab filter history) you can see that the filters for each column are simply applied sequentially.


The dataframe



You can perform other types of matches, such as exact matches, negations, and exact negations. Enter the filter and then right click on the text entry to see available modifiers and choose the desired modifier.





Results in the negation of partial matches


Treats the filter as a str, same as Partial Match (see above sub-section)


Exact text match


Negation of exact text match

Numerical filters

By default the filters in all entires are treated as text. If your column contains numerical data you have additional options for modifiers. The first four modifiers are the same as explained above. The rest are self explanatory.



You can view and edit the Project DataFrame directly in a GUI using the DataFrame editor.



Make sure you know what you are doing when you directly modify the Project DataFrame. Changes cannot be undone but you can restore a backup from the project’s dataframe directory. For example, do not modify data under the following columns: CurvePath, ImgInfoPath, ImgPath, ROI_State, any uuid column.

See also

Uses the Spyder object editor


If you are familiar with pandas you can interact with the project DataFrame directly. If you are unfamiliar with pandas it’s very easy to learn.

Useful Callables




returns dataframe of the current project browser tab


always returns dataframe of the root tab (entire project DataFrame)


pass a pandas.DataFrame instance to set it as the project DataFrame


General usage to modify the project DataFrame would be something like this:

# Get a copy the project DataFrame to modify
df = get_root_dataframe().copy()

# Do stuff to df

# Set the project DataFrame with the modified one


Let’s say you have been inconsistent in naming “ATENA” ROI Tags in the “cell_name” column. You can rename all occurances of ‘atena’ to ‘ATENA’

# Get a copy of the project DataFrame
>>> df = get_root_dataframe().copy()

# View all occurances of 'atena'
>>> df.cell_name[df.cell_name == 'atena']
2      atena
3      atena
4      atena
5      atena
6      atena
205    atena
Name: cell_name, dtype: object

# Rename all occurances of 'atena' to 'ATENA'
>>> df.cell_name[df.cell_name == 'atena'] = 'ATENA'

# Check that there are more occurances of 'atena'
>>> df.cell_name[df.cell_name == 'atena']
Series([], Name: cell_name, dtype: object)

# Check that we have renamed the 'atena' occurances to 'ATENA'
# Indices 2-6 and 205 were named 'atena'
>>> df.cell_name
0      untagged
1      untagged
2         ATENA
3         ATENA
4         ATENA
5         ATENA
6         ATENA
7         atenp
Name: cell_name, Length: 311, dtype: object

# Check index 205
>>> df.cell_name.iloc[205]

# Finally set the changed DataFrame as the root (project) DataFrame
>>> set_root_dataframe(df)