Caiman Motion Correction

Perform motion correction using the NoRMCorre implementation in the CaImAn library.

I highly recommend going through the following before using this module

../../../_images/caiman_motion_correction.png

Parameters

Output bit depth: The motion corrected image sequences are of float32 type. You can optionally convert the output to 8 or 16 bit uint types to save disk space. This doesn’t always work from my experience, values might get clipped.

For all other parameters please see the demo notebook mentioned above.

You can also enter parameters as keyword arguments (kwargs) in the text box if you select “Use motion correction kwargs”. 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.

Usage

This module adds a “caiman motion correction” item to the batch. Set the desired parameters (see demo notebook) 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 open the motion corrected image sequence in the viewer. You can then use this motion corrected image sequence for further analysis.

See also

This modules uses the Batch Manager.

Note

The parameters used for motion correction are stored in the work environment of the viewer and this log is carried over and saved in the Project Sample as well. To see the parameters that were used for motion correction in the viewer, execute get_workEnv().history_trace in the viewer console and look for the caiman_motion_correction entry.

Script Usage

A script can be used to add caiman motion correction batch items. This is much faster than using the GUI.

See also

Script Editor

Add items

This example shows how to add all tiff files (of image sequences) from a directory as batch items with 3 different variants of parameters.

 1# Import glob so we can get all tiff files in a dir
 2from glob import glob
 3# Import os to get filenames from paths
 4import os
 5
 6# Motion correction params.
 7
 8mc_kwargs = \
 9{
10    "max_shifts":           (6, 6),
11    "niter_rig":            2,
12    "max_deviation_rigid":  3,
13    "strides":              (196, 196),
14    "overlaps":             (98, 98),
15    "upsample_factor_grid": 4,
16    "gSig_filt":            (10, 10)  # Set to `None` for 2p data
17}
18
19params = \
20{
21    'mc_kwargs':        mc_kwargs,  # the kwargs we set above
22    'item_name':        "will set later per file",
23    'output_bit_depth': "Do not convert"  # can also set to `8` or `16` if you want the output in `8` or `16` bit
24}
25
26# Path to the dir containing images
27files = glob("/full_path_to_raw_images/*.tiff")
28# Sort in alphabetical order (should also work for numbers)
29files.sort()
30
31# Open each file, crop, and add to batch with 3 diff mot cor params
32for i, path in enumerate(files):
33    print("Working on file " + str(i + 1) + " / " + str(len(files)))
34
35    # get json file path for the meta data
36    meta_path = path[:-5] + ".json"
37
38    # Create a new work environment with this image sequence
39    work_env = ViewerWorkEnv.from_tiff(path, "asarray-multi", meta_path)
40
41    # set it as the current work environment
42    vi.viewer.workEnv = work_env
43    vi.update_workEnv()
44
45    # Get caiman motion correction module, hide=False to not show GUI
46    mc_module = get_module("caiman_motion_correction", hide=True)
47
48    # Set name for this video file
49    name = os.path.basename(path)[:-5]
50    params["item_name"] = name
51
52    # First variant of params
53    params["mc_kwargs"]["strides"] = (196, 196)
54    params["mc_kwargs"]["overlaps"] = (98, 98)
55
56    # Add one variant of params for this video to the batch
57    mc_module.add_to_batch(params)
58
59    # Try another variant of params
60    params["mc_kwargs"]["strides"] = (256, 256)
61    params["mc_kwargs"]["overlaps"] = (128, 128)
62
63    # Set these params and add to batch
64    mc_module.add_to_batch(params)
65
66    # Try one more variant of params
67    params["mc_kwargs"]["strides"] = (296, 296)
68    params["mc_kwargs"]["overlaps"] = (148, 148)
69
70    # Set these params and add to batch
71    mc_module.add_to_batch(params)
72
73# If you want to process the batch after adding the items uncomment the following lines
74#bm = get_batch_manager()
75#bm.process_batch(clear_viewers=True)

Crop and add items

This example shows how to crop videos prior to adding them as batch items. This is useful if you want to crop-out large unchanging regions of your movides. It uses either simple thresholding or spectral salieny on a standard deviation projection to determine the bounding box for cropping.

  1# Import glob so we can get all tiff files in a dir
  2from glob import glob
  3# Import os to get filenames from paths
  4import os
  5
  6# Just get a shortcut reference to the auto_crop function
  7auto_crop = image_utils.auto_crop
  8
  9# Parameters for cropping, these should work for everything
 10# These worked well for various different constructs
 11# If you get non-specific cropping (too much black) try "method" as "spectral_saliency" (See below)
 12crop_params = \
 13{
 14    "projection":       "max+std",
 15    "method":           "threshold",
 16    "denoise_params":   (32, 32),
 17}
 18
 19# Spectral saliency is another method
 20# You can try and play around with the parameters
 21# If the cropping is insufficient, you can set "projection" to just "max" or "std"
 22# If you get too much junk blackness around the animal try increasing denoise_params
 23# or reduce padding. Default padding is 30 (when nothing is specified like above)
 24crop_params_salient = \
 25{
 26    "projection":       "max+std",
 27    "method":           "spectral_saliency",
 28    "denoise_params":   (16, 16),
 29    "padding":          40
 30}
 31
 32# Motion correction params.
 33mc_kwargs = \
 34{
 35    "max_shifts":           (6, 6),
 36    "niter_rig":            2,
 37    "max_deviation_rigid":  3,
 38    "strides":              (196, 196),
 39    "overlaps":             (98, 98),
 40    "upsample_factor_grid": 4,
 41    "gSig_filt":            (10, 10)  # Set to `None` for 2p data
 42}
 43
 44params = \
 45{
 46    'mc_kwargs':        mc_kwargs,  # the kwargs we set above
 47    'item_name':        "will set later per file",
 48    'output_bit_depth': "Do not convert"  # can also set to `8` or `16` if you want the output in `8` or `16` bit
 49}
 50
 51# Path to the dir containing images
 52files = glob("/full_path_to_raw_images/*.tiff")
 53# Sort in alphabetical order (should also work for numbers)
 54files.sort()
 55
 56# Open each file, crop, and add to batch with 3 diff mot cor params
 57for i, path in enumerate(files):
 58    print("Working on file " + str(i + 1) + " / " + str(len(files)))
 59
 60    # get json file path for the meta data
 61    meta_path = path[:-5] + ".json"
 62
 63    # Create a new work environment with this image sequence
 64    work_env = ViewerWorkEnv.from_tiff(path, "asarray-multi", meta_path)
 65
 66    # autocrope the image sequence in the work environment
 67    raw_seq = work_env.imgdata.seq
 68    # Auto crop the image sequence
 69    print("Cropping file: " + str(i + 1))
 70
 71    cropped = auto_crop.crop(raw_seq, crop_params)
 72    # Set work env img seq to the cropped one and update
 73    work_env.imgdata.seq = cropped
 74
 75    # update thew work environment
 76    vi.viewer.workEnv = work_env
 77    vi.update_workEnv()
 78
 79    # Get caiman motion correction module, hide=False to not show GUI
 80    mc_module = get_module("caiman_motion_correction", hide=True)
 81
 82    # Set name for this video file
 83    name = os.path.basename(path)[:-5]
 84    params["item_name"] = name
 85
 86    # First variant of params
 87    params["mc_kwargs"]["strides"] = (196, 196)
 88    params["mc_kwargs"]["overlaps"] = (98, 98)
 89
 90    # Add one variant of params for this video to the batch
 91    mc_module.add_to_batch(params)
 92
 93    # Try another variant of params
 94    params["mc_kwargs"]["strides"] = (256, 256)
 95    params["mc_kwargs"]["overlaps"] = (128, 128)
 96
 97    # Set these params and add to batch
 98    mc_module.add_to_batch(params)
 99
100    # Try one more variant of params
101    params["mc_kwargs"]["strides"] = (296, 296)
102    params["mc_kwargs"]["overlaps"] = (148, 148)
103
104    # Set these params and add to batch
105    mc_module.add_to_batch(params)
106
107# If you want to process the batch after adding the items uncomment the following lines
108#bm = get_batch_manager()
109#bm.process_batch(clear_viewers=True)