Perform 3D CNMF using the implementation provided by the CaImAn library. This modules basically provides a GUI for parameter entry.

I highly recommend going through the following before using this module



Please see the CaImAn demo notebook mentioned above to understand the parameters. The Caiman docs also provide descriptions of the parameters:

You can also enter parameters for CNMF and component evaluation as keyword arguments (kwargs) in the the respective text boxes if you select “Use CNMF kwrags” or “Use evaluation params”. This is useful if you want to enter parameters that cannot be entered in the GUI for example. Use single quotes if you want to enter string kwargs, do not use double quotes.


The parameters used for 3D CNMF are stored in the work environment of the viewer and this log is carried over and saved in Project Samples as well. To see the parameters that were used for 3D CNMF in the viewer, execute get_workEnv().history_trace in the viewer console and look for the ‘cnmf_3d’ entry.


Importing several thousands of ROIs into the Viewer can take 15-30 minutes. You will be able to track the progress of the import in the Viewer Window’s status bar.


This module adds a “CNMF_3D” item to the batch. Set the desired parameters (see Caiman docs & demos) and then enter a name to add it as an item to the batch. After the batch item is processed, double-click the batch item to import the CNMF output into a Viewer. You can then annotate and curate ROIs, and add the data as a Sample to your project.

See also

This modules uses the Batch Manager.


It’s recommended to open a new Viewer when you want to import 3D CNMF data. Full garbage collection of 3D data in the Viewer Work environment is a WIP for when you want to clear & import 3D data into the same viewer. However when you close the Viewer entirely it is garbage collected entirely.

Script Usage

A script can be used to add CNMF batch items. This is much faster than using the GUI. This example sets the work environment from the output of a batch item.

See also

Script Editor

This example loads 3D sequences from disk & adds them to a batch with 3 parameter variants.

 1# just so we can reset the params for each new image file
 2def reset_params():
 3    # CNMF Params that we will use for each item
 4    cnmf_kwargs = \
 5    {
 6        'p': 2,
 7        'merge_thresh': 0.8,
 8        'k': 50,
 9        'gSig': (10, 10, 1),
10        'gSiz': (41, 41, 4)
11    }
13    # component evaluation params
14    eval_kwargs = \
15    {
16        'min_SNR': 3.0,
17        'rval_thr': 0.75,
18        'decay_time': 1.0,
19    }
21    # the dict that will be passed to the mesmerize caiman module
22    params = \
23    {
24        "cnmf_kwargs":  cnmf_kwargs,
25        "eval_kwargs":  eval_kwargs,
26        "refit":        True,  # if you want to perform a refit
27        "item_name":    "will set later per file",
28        "use_patches":  False,
29        "use_memmap":   False,  # re-use the memmap from a previous batch item, reduces computation time
30        "memmap_uuid:   None,   # UUID (as a str) of the batch item to use the memmap from
31        "keep_memmmap": False   # keep the memmap of this batch item
33    }
35    return params
37# get the 3d cnmf module
38cnmf_mod = get_module('cnmf_3d', hide=True)
40# Path to the dir containing images
41files = glob("/full_path_to_raw_images/*.tiff")
42# Sort in alphabetical order (should also work for numbers)
45# Open each file, crop, and add to batch with 3 diff mot cor params
46for i, path in enumerate(files):
47    print("Working on file " + str(i + 1) + " / " + str(len(files)))
49    # get json file path for the meta data
50    meta_path = path[:-5] + ".json"
52    # Create a new work environment with this image sequence
53    vi.viewer.workEnv = ViewerWorkEnv.from_tiff(path=path,           # tiff file path
54                                                method='imread',     # use imread
55                                                meta_path=meta_path, # json metadata file path
56                                                axes_order=None)     # default axes order
57                                                                     # see Mesmerize Tiff file module docs for more info on axes order
59    # update the work environment
60    vi.update_workEnv()
62    # get the first variant of params
63    params = reset_parmas()
65    # Set name for this video file
66    name = os.path.basename(path)[:-5]
67    params["item_name"] = name
69    # add batch item with one variant of params
70    u = cnmf_mod.add_to_batch(params)
72    # add the same image but change some params
73    params["cnmf_kwargs"]["gSig"] = (12, 12, 1)
74    params["eval_kwargs"]["min_SNR"] = 2.5
76    # use the same memmap as the previous batch item
77    # since it's the same image
78    params["use_memmap"] = True
79    params["memmap_uuid"] = str(u)
81    # add this param variant to the batch
82    cnmf_mod.add_to_batch(params)
84    # one more variant of params
85    params["eval_kwargs"]["min_SNR"] = 2.0
87    # add this param variant to the batch
88    cnmf_mod.add_to_batch(params)