Add decoding functionality to Polaris

[xuefei-wang]

Add decoding part to the repo. Spot decoding has its own application, and is also wrapped into Polaris.
Tests are also provided.

[elaubsch]

Can you write some tests for the SpotDecoding application and the decoding_functions.py script?

[rossbar]

Just a couple quick notes on the infrastructure/versioning stuff. As we discussed yesterday, the failures on CI are not related to the changes in this PR itself. The easiest way to fix that would be to merge #40, then merge those changes into this PR. There may be some minor merge conflicts in doing so - I'd be happy to help resolve them if you'd like to team up!

I haven't looked at the code itself yet here - LMK when you think it's at a stage where you'd like a more detailed review!

[rossbar]

Apologies for leaving so many comments - almost all of them can be safely ignored!

I don't see any critical blockers here, aside from doublechecking the dependency specifications (see the comments in requirements.txt and setup.py).

Generally speaking there's a lot of conversion e.g. between dataframes/dicts/arrays etc. that could probably be simplified, but we shouldn't let perfection be the enemy of good. At the very least it was useful for me to walk through the diffs to get a better sense of the operations that go into this workflow.

Two major caveats: I didn't review the notebooks, nor do I have any experience to say anything meaningful about the model construction in decoding_functions.py.

One last thing: running the test suite gives a decent number of RuntimeWarnings, likely due to division by 0 and related floating point arithmetic problems. It's probably worth doublechecking that these are things you expect! You can do so by running the test-suite locally, something like:

# Create a test environment
$ python -m venv dc-spots-testenv
# Make sure working directory is clean
# NOTE: Only run `git clean` if you *don't* have any uncommitted 
# changes that you want to save!
$ git clean -xdf
# Enter clean virtual environment
$ source dc-spots-testenv/bin/activate
# Install dependencies and library locally
$ python -m pip install -r requirements.txt -r test_requirements.txt
$ python -m pip install .
# Run test suite on installed version
$ pytest --pyargs deepcell_spots

[rossbar]

tl;dr - this probably doesn't matter, but may break existing code. It's safe to ignore if you don't care about backward compatibility yet!

---

Technically, adding a kwarg to the front of a signature like this will break any existing code that uses position-based arguments. For example, if there is existing code where a Polaris object was instantiated like:

>>> Polaris(my_seg_model, "cytoplasm")

this change in the signature will break that code, because now the first unnamed argument maps to image_type instead of segmentation_model.

If you don't have a ton of existing code that you're worried about breaking, you can go ahead and ignore this for now! Another solution would be to use keyword-only arguments (i.e. start this signature list with *,) which prevents users from creating Polaris objects with unnamed args. This may still break existing code, but it will fail loudly with a very specific message and a straightforward, future-proof fix.

[rossbar]

There's almost certainly an opportunity to vectorize here, but I'm only breezing over it for now. Another thing to keep in mind for a followup!

[xuefei-wang]

I loosely remember that we did something dirty inside Polaris when adding multiplex functionality - for example, this line and related lines should probably be better moved into the detection class. Should we refactor things as well if we want to do things rigorously?

deepcell-spots/deepcell_spots/applications/polaris.py

Line 259 in 2269b68

spots_locations = max_cp_array_to_point_list_max(max_proj_images,

[rossbar]

Should we refactor things as well if we want to do things rigorously?

It might be worth it, but if so I'd advise to leave it for a separate PR. That will make it easier to focus on the specific changes and will prevent blocking this one!