Clarify gSiz parameter role(s)

[EricThomson]

Looping around to something mentioned in #970 (and this is something that comes up a lot in workshops): the docs on gSiz are sort of all over the place, and it would be good to clarify.

Just putting some of my notes here so when I (or someone) return to it, we have some information here.

Just for reference, gSiz is an initialization parameter and is used to form a bounding box around seed pixels during initialization. This is different from the patches set up by the rf/stride parameters. Instead, this is a mechanism superimposed on such patches. Caiman cycles through each potential seed pixel creates a little bounding box around it (the size of the bounding box is determined by gSiz), and runs CNMF or CNMFE in the little bounding box. This is one way that Caiman keeps CNMF manageable given that it is an NP-hard problem.

But how it is described in the docs/demo notebooks, and how it is calculated and used is not the same for CNMF/CNMFE. For example:

• In params.py, it is defined as half-size of bounding box for each neuron, and the default is given as 2*gSig + 1. This is how gSiz is initialized if it is not defined by the user.

• In demo_pipeline_CNMFE.ipynb, gSiz is described as the average diameter of a neuron, in general 4*gSig + 1. The same claim is made in the docs in 1p processing tips.

If you do a deep dive in initialize.py you see that gSiz seems to be used differently for the CNMF and CNMFE. For CNMF (which uses greedyROI()) the bounding box for some operations is width 2gSiz+1 (for others it is gSiz+1). Compare this to CNMFE (which initializes using greedyROI_corr()), where the bounding box for the same operations is 2x the width used in greedyROI(). If someone really wanted to confused they would see that gSiz is also used to set the size of a Gaussian convolution filter in initialize.imblur() and sneaks in under the name siz.

I'm not sure why the different bounding boxes are set in CNMF versus CNMFE: maybe different levels of background noise demand larger diameter bounding boxes for CNMFE? I poked around in the Matlab versions of the two algorithms and found 2*gSig+1 in both instances, so I'm not sure how the 4*gSig+1 value became the convention in some of the CNMFE documentation.

In general it would be good to lock down how gSiz is used in the different init functions, and have this more clearly reflected in the documentation and demos. It will take a bit more sleuthing on my part to work it out to my satisfaction: if anyone else wants to help, or take this on, please let me know.

[zhouyi0812]

Hello!
Just a thought! If gSig and gSiz are highly dependent, will it be possible to automatically set the gSiz according to the gSig in the future? Therefore won't be confused by the formula behind it.
Thank you!

[EricThomson]

@zhouyi0812 we show how to do this in some notebooks, but there are cases when we wouldn't want to enforce this. E.g., if some neurons are very large or have with wild shapes (dendrites) it might make sense to make gSiz much larger than the standard multiples of gSig. I can also imagine some cases where you would want it smaller.

[pgunn]

I wonder if having that parameter accept either a number or a magic string value of "auto" would be a good way to handle this.

[EricThomson]

That might be a good option, people often won't need to worry about it.

[EricThomson]

I started on fixing this in the demo notebooks (PR #1075 and #1207 where I just explain what gsig and gsiz are in more direct and literal terms: they are the standard deviation and kernel size of the gaussian filter used by Caiman: we call a function in OpenCV that is used to convolve the images). there are a couple of other uses in Caiman because caiman has a tendency to overload variable names, but they are less important generally.

I won't consider this closed until we handle it in the docs though.