data.lily() is 4-channel 12-bit, 3 color channels + diascopic DIC channel, not as stated in docs

[kwikwag]

Description:

The lily image is different than all other images in data. Even in the example code from the docs trying to render it produces a warning - and rightfully so.

Documentation says it was produced by a Nikon C1 inverted microscope. From a quick search online (brochure, press release and software manual) it turns out images produced by the microscope are 12-bit and with a maximum of 3 fluorescence channels + 1 transmission diascopic DIC channel. The docs say it's 16-bit (which is indeed the 'container' dtype, but not the actual data type), 4 color channels (when in fact one of them is a DIC channel). I'm no microscope expert so I'm not sure how to render it, but I think something along the lines of x[:, :, :3] * x[:, :, 3] assuming x is a scaled floating-point type (0..1) should be close to correct.

It'd be nice if the example code is corrected. Also, consider modifying the image to reflect correct interpretation of the data (e.g. it should pass img_to_ubyte nicely - which is doesn't currently), or perhaps providing it as two separate images - a 3-color image + a grayscale DIC image. Perhaps reach out to whomever contributed the image in the first place.

Way to reproduce:

Run the example provided by scikit-image documentation.

Version information:

3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0]
Linux-5.15.120+-x86_64-with-glibc2.35
scikit-image version: 0.19.3
numpy version: 1.23.5

[jni]

Thanks for the report @kwikwag!

Yeah I don't think we have a good story now for 12-bit images, even though they are very common in microscopy. Perhaps we can have a keyword argument to the conversion functions, bit_depth=? The problem is that NumPy arrays themselves have no mechanism for storing that information, so in img_to_ubyte we can't infer the bit depth solely from the array.

Would you want to contribute an update to the dataset docstring and to the documentation example? (Though I'm not sure how to update that example specifically... Special-case Lily?)

[mkcor]

Hi @kwikwag,

Thanks for the detailed issue. Don't hesitate to submit an update to both the gallery example and the data documentation! Looping in @GenevieveBuckley who contributed the image in the first place. Thanks again.

[kwikwag]

Unfortunately I cannot push this forward...

[GenevieveBuckley]

Hi @kwikwag

It's not entirely clear what the request in your issue is. I think there are three things mentioned here:

1. To update the documentation for the lily of the valley sample
2. To change the rendering display in the example https://scikit-image.org/docs/stable/auto_examples/data/plot_scientific.html#sphx-glr-auto-examples-data-plot-scientific-py
3. 12 bit datatypes, and img_as_ubyte issues.

Thoughts:

1. is a great idea, and we would be happy to take a PR that improves the data description in the documentation.
2. I'm not sure what you'd consider a "correct" rendering/display here, but yes a PR to update this is welcome.
3. 12 bit datatypes are very common in microscopy, like Juan says. Yes, they do just get dumped into 16 bit arrays, which can be confusing. scikit-image doesn't have good infrastructure for this, but neither does numpy or the rest of the scientific software stack. It's not clear to me what you'd like here, besides "better tooling should be available" which is pretty open-ended and non-specific. And I agree, it would be great to have better tooling - but it take a lot of work and would need someone dedicated to offer to take it on.

There is some background information about the lily image and metadata here: https://gitlab.com/scikit-image/data/-/merge_requests/6

If one of the channels is DIC, that might make sense with why we saw two channels labelled with the same laser wavelength in the metadata. I assumed the settings were weird because this image was from my first training session on how to use the microscope, so we probably did a bunch of stuff that wouldn't make sense in an actual experiment.

References:

• https://gitlab.com/scikit-image/data/-/merge_requests/6
• Missing scientific (domain-specific) images and corresponding examples and tutorials #3384 (comment)
• Add fluorescence microscopy images to data registry. #4939

[github-actions]

Hello scikit-image core devs! There hasn't been any activity on this issue for more than 180 days. I have marked it as "dormant" to make it easy to find.
To our contributors, thank you for your contribution and apologies if this issue fell through the cracks! Hopefully this ping will help bring some fresh attention to the issue. If you need help, you can always reach out on our forum
If you think that this issue is no longer relevant, you may close it, or we may do it at some point (either way, it will be done manually).