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.