Fix intensity normalizations

[qin-yu]

Hi @carsen-stringer!

During the process of packaging the custom Cellpose model for bioimage.io, I identified two potential issues with the intensity normalization implementation in Cellpose. This PR proposes fixes for:

1. The current normalization with the lowhigh argument is not channel-wise. In this PR, lowhigh now either takes a 2-tuple (low, high) for all channels, or a nchan-tuple of that for each channel.
2. The current invert mechanism does not necessarily invert the channel to be segmented (--chan); instead, it inverts the last channel. Depending on the --chan2 value, this might not be the intended channel. In this PR, all channels are inverted if invert.

Original PR message on 25 Jul 2024

Original PR

Hi @carsen-stringer!

During the process of packaging the custom Cellpose model for bioimage.io, I identified two potential issues with the intensity normalization implementation in Cellpose. This PR proposes fixes for:

1. The current min-max normalization with the lowhigh argument is not channel-wise, and the argument itself might be misused.
2. The current invert mechanism does not necessarily invert the channel to be segmented (--chan); instead, it inverts the last channel. Depending on the --chan2 value, this might not be the intended channel.

Please review these changes as I might have misunderstood some parts.

---

Fix for Min-Max Normalization by 31bc5be

For cellpose.transforms.normalize_img() (channel-wise normalization), the lowhigh option is provided. I assume this corresponds to min-max normalization where lowhigh is a tuple representing (new minimum, new maximum).

cellpose/cellpose/transforms.py

Lines 600 to 601 in 84344b0

	lowhigh (tuple, optional): The lower and upper bounds for normalization. If provided, it should be a tuple
	of two values. Defaults to None.

If lowhigh represents (old minimum, old maximum), then normalization is not channel-wise if lowhigh has a length of 2:

cellpose/cellpose/transforms.py

Lines 624 to 626 in 84344b0

	if lowhigh is not None:
	assert len(lowhigh) == 2
	assert lowhigh[1] > lowhigh[0]

In either case, the implementation needs fixing:

cellpose/cellpose/transforms.py

Lines 640 to 643 in 84344b0

	if lowhigh is not None:
	for c in range(nchan):
	img_norm[...,
	c] = (img_norm[..., c] - lowhigh[0]) / (lowhigh[1] - lowhigh[0])

The current implementation is essentially: img_norm = (img_norm - lowhigh[0]) / (lowhigh[1] - lowhigh[0])

This has been fixed by commit 31bc5be.

---

Fix for Invert by 91469d1

For cellpose.transforms.normalize_img() (channel-wise normalization), there is an invert option for cases where "cells are dark instead of bright":

cellpose/cellpose/transforms.py

Lines 598 to 599 in 84344b0

	invert (bool, optional): Whether to invert the image. Useful if cells are dark instead of bright.
	Defaults to False.

In Cellpose, the invert function is performed after reshape(), which moves the main channel to channel 0 and the auxiliary channel to channel 1. Therefore, the primary use case is to invert the first channel (channel 0) instead of the last one (current implementation):

cellpose/cellpose/transforms.py

Lines 666 to 667 in 84344b0

	if (tile_norm_blocksize > 0 or normalize) and invert:
	img_norm[..., c] = -1 * img_norm[..., c] + 1

The variable c retains the value from a previous loop, being 1 if nchan is 2 or 2 if nchan is 3.

This has been fixed by commit 91469d1, but further improvements can be made to allow for a user-specified list of channels to be inverted.

[carsen-stringer]

thanks @qin-yu ! the lowhigh is meant to represent the values to set to 0 and 1 (e.g. pixel value 100->0 and 1100->1 corresponds to lowhigh = [100,1100]. I think the fix here would be to check if lowhigh is a list of lists (per channel) or a single list (for all channels). It's a good point that this use-case isn't covered currently.

for the inversion, thanks for catching that, I think it would make sense to apply for all channels?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 53.70%. Comparing base (19b65ce) to head (4df2731).
Report is 14 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #981      +/-   ##
==========================================
+ Coverage   52.76%   53.70%   +0.93%     
==========================================
  Files          18       18              
  Lines        4126     4132       +6     
==========================================
+ Hits         2177     2219      +42     
+ Misses       1949     1913      -36     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[qin-yu]

thanks @qin-yu ! the lowhigh is meant to represent the values to set to 0 and 1 (e.g. pixel value 100->0 and 1100->1 corresponds to lowhigh = [100,1100]. I think the fix here would be to check if lowhigh is a list of lists (per channel) or a single list (for all channels). It's a good point that this use-case isn't covered currently.

Thanks for explaining! That makes sense, working on it.

for the inversion, thanks for catching that, I think it would make sense to apply for all channels?

Yes you are right, inverting all channels by default if invert == True seems natural to me. But maybe this could also be either a bool or tuple(bool, ...)?

[carsen-stringer]

Thanks so much, regarding the invert function I think it's fine with all channels, I'm not sure how much it's being used with multichannel images

[qin-yu]

Thanks so much, regarding the invert function I think it's fine with all channels, I'm not sure how much it's being used with multichannel images

You are right. Let's keep it simple

I have finalized the PR, including two fixes along with the corresponding tests. Please take a look when you have a moment! @carsen-stringer

[qin-yu]

The failed check seems to be incidental and maybe unrelated to the PR.

[qin-yu]

All checks passed 🥳