DOC: transform.resize: document output dtype by mdhaber · Pull Request #7761 · scikit-image/scikit-image

mdhaber · 2025-03-18T19:20:48Z

Description

gh-7524 noted that the output dtype of transform.resize is not the same as the input dtype. This appears to be an intended feature, so perhaps the issue can be closed by documenting the output dtype. (Feel free to close if there is standard dtype behavior documented elsewhere.)

I traced the code a bit, but ultimately determined the relationship between input and output dtype using this script. I varied some of the other parameters manually rather than looping over all possibilities. If you know of another exception, I'd be happy to add it, but I think the consequences of missing an obscure one are rather low.

import numpy as np
from skimage.transform import resize

for order in [0, 3, 5]:
    for size in [(41, 41), (50, 50), (57, 57)]:
        for dtype in [np.uint8, np.uint16, np.uint32, np.uint64, 
                    np.int8, np.int16, np.int32, np.int64, 
                    np.float16, np.float32, np.float64]:
            image = np.ones((50, 50), dtype=dtype)
            out = resize(image, size, order=order)
            if out.dtype != np.float64:
                print(order, size, dtype, out.dtype)

matthew-brett

Looks good. Suggestion for phrasing.

matthew-brett · 2025-03-21T14:31:06Z

skimage/transform/_warps.py

        Resized version of the input.
+        The dtype is ``float64`` with the following exceptions:
+
+        - ``order==0``: resized dtype is ``image.dtype``.


Maybe something to explain why the type is np.float64? Such as "resize uses interpolation. Unless this interpolation (order) is nearest neighbor (order==0), then the algorithm will generate new values by a sum of variously weighted nearby values, so generating floating point values as output. Accordingly, the output is generally float64 with the following exceptions:

And maybe adding the alternative of scipy.ndimage.zoom as in Stefan's suggestion? https://docs.scipy.org/doc/scipy-1.15.2/reference/generated/scipy.ndimage.zoom.html

I concur but I would suggest including all this under a 'Notes' section (and refer to it in the 'Returns' section).

mkcor · 2025-03-25T14:32:17Z

skimage/transform/_warps.py

        Resized version of the input.
+        The dtype is ``float64`` with the following exceptions:
+
+        - ``order==0``: resized dtype is ``image.dtype``.


Suggested change

- ``order==0``: resized dtype is ``image.dtype``.

- When using `order=0`, output dtype is `image.dtype`.

I actually had something like that originally. I changed it for concision. Is there risk of confusion as written?

The backticks are correct as they are. See https://numpydoc.readthedocs.io/en/latest/format.html#common-rest-concepts.

The backticks are correct as they are. See https://numpydoc.readthedocs.io/en/latest/format.html#common-rest-concepts.

Thanks for sharing this page, @mdhaber. My suggestion is based on: "When referring to a parameter anywhere within the docstring, enclose its name in single backticks" (from https://numpydoc.readthedocs.io/en/latest/format.html#parameters). We've been following this style guide lately, when updating docstrings.

Here, order and image are parameters, unlike float64 which I agree could/should render in monospaced font and, hence, be enclosed within double backticks.

I actually had something like that originally. I changed it for concision. Is there risk of confusion as written?

@mdhaber I agree that concision is welcome under a 'Returns' section; my suggestion falls within a broader one about creating a 'Notes' section where, on the contrary, it's fine/good to be verbose.

My suggestion is based on: "When referring to a parameter anywhere within the docstring, enclose its name in single backticks"

I see how that can still be misunderstood, but it intends to refer to just the name of the parameter, when it appears alone.
I am sure because I wrote the style guide's new recommendations regarding backticks (numpy/numpydoc#525). Do you think it needs to be clarified?

Through that and pydata/pydata-sphinx-theme#1852, I've been trying to move the ecosystem's docs to consistently render code in monospaced font so it is easy to distinguish from English. I proposed to change the recommendation to use double-backticks across the board, even for individual parameter names, but the intent is that someday all these individual parameter names will render as monospaced-font links to the parameter section of the docstring. Feel free to add a thumbs up to numpy/numpydoc#484 if you'd like to see that happen!

As for the rest, I can move it if you and Matthew agree.

Moving is fine with me.

I am sure because I wrote the style guide's new recommendations regarding backticks (numpy/numpydoc#525).

Oh, wonderful!! I'm glad I can ask you questions directly then. 😁 (Nice to meet you, @mdhaber!)

I see how that can still be misunderstood, but it intends to refer to just the name of the parameter, when it appears alone.

Aaaah!

Do you think it needs to be clarified?

I would say yes, since I was never sure. I would suggest appending "When referring to a parameter anywhere within the docstring, enclose its name in single backticks if and only if it appears alone."

Through that and pydata/pydata-sphinx-theme#1852, I've been trying to move the ecosystem's docs to consistently render code in monospaced font so it is easy to distinguish from English.

I admit that I never 'adhered' to the italic-like rendering of parameter names, since I already use/need this rendering to express emphasis in plain English. I once left a comment about this, somewhere in a PR in this repo. But I wanted to be obedient and consistent...

I proposed to change the recommendation to use double-backticks across the board, even for individual parameter names,

I would support this. Ouch, we started replacing double backticks which enclosed parameter names with single backticks (not systematically, just when running into them). Now there is a mix of conventions in our docstrings... 😬

but the intent is that someday all these individual parameter names will render as monospaced-font links to the parameter section of the docstring. Feel free to add a thumbs up to numpy/numpydoc#484 if you'd like to see that happen!

Nice! Done; incremented the 🚀 emoji.

skimage/transform/_warps.py

mkcor · 2025-03-25T14:38:32Z

skimage/transform/_warps.py

        Resized version of the input.
+        The dtype is ``float64`` with the following exceptions:
+
+        - ``order==0``: resized dtype is ``image.dtype``.


I concur but I would suggest including all this under a 'Notes' section (and refer to it in the 'Returns' section).

mdhaber · 2025-03-27T02:19:13Z

Moved this to the Notes and referred to the Notes in the Returns section. Added explanation of why output dtype is floating point and changed exceptions to full sentences. Mentioned ndimage.zoom as an alternative that preserves dtype and added to a See Also section.

mkcor

Thanks for this nice improvement, @mdhaber!

Unrelated to this PR but, after reading the entire docstring, I wonder what "n-dimensional" really means in the context of channels, and whether that's the same as "N-dimensional" (mentioned earlier).

skimage/transform/_warps.py

Co-authored-by: Marianne Corvellec <[email protected]>

matthew-brett

Looks good to me.

mkcor · 2025-04-23T09:29:21Z

Wait, @mdhaber did you intend to close this PR? It got two approvals so it was meant to get merged into main...

lagru · 2025-04-23T12:39:32Z

Reopening – at least for now – so we don't eventually forget this due to its "closed" status.

mdhaber · 2025-04-23T15:01:48Z

Apologies; I'm not familiar with scikit-image review policies. I didn't want to have this open any more, but at the same time, I didn't want to ask for any more maintainer time. Please feel free to leave it open for another few weeks. After that, I'll close again, but you're welcome to use the commits in a separate PR. I'd just rather not have this in my PR list for too long. Thanks!

DOC: transform.resize: document output dtype

a3eff20

matthew-brett self-assigned this Mar 21, 2025

matthew-brett reviewed Mar 21, 2025

View reviewed changes

mkcor added the 📄 type: Documentation Updates, fixes and additions to documentation label Mar 25, 2025

mkcor reviewed Mar 25, 2025

View reviewed changes

DOC: transform.resize: adjust documentation per review

944ee80

mkcor approved these changes Mar 28, 2025

View reviewed changes

skimage/transform/_warps.py Outdated Show resolved Hide resolved

Update skimage/transform/_warps.py

60a33ab

Co-authored-by: Marianne Corvellec <[email protected]>

mkcor mentioned this pull request Mar 28, 2025

Improve docstring for transform.resize. #7765

Open

mkcor added the 🚀 Quick win Trivial, small, easy to address or review label Mar 29, 2025

mkcor mentioned this pull request Mar 31, 2025

Refactor transform initialization #7754

Merged

mdhaber requested a review from matthew-brett April 3, 2025 23:38

matthew-brett approved these changes Apr 4, 2025

View reviewed changes

mdhaber closed this Apr 20, 2025

lagru reopened this Apr 23, 2025

mdhaber closed this May 7, 2025

mkcor mentioned this pull request May 10, 2025

Document output dtype for transform.resize. #7792

Merged

	- ``order==0``: resized dtype is ``image.dtype``.
	- When using `order=0`, output dtype is `image.dtype`.

Uh oh!

Conversation

mdhaber commented Mar 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

matthew-brett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdhaber Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdhaber Mar 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdhaber commented Mar 27, 2025

Uh oh!

mkcor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

matthew-brett left a comment

Choose a reason for hiding this comment

Uh oh!

mkcor commented Apr 23, 2025

Uh oh!

lagru commented Apr 23, 2025

Uh oh!

mdhaber commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mdhaber commented Mar 18, 2025 •

edited

Loading

mdhaber Mar 26, 2025 •

edited

Loading

mdhaber Mar 26, 2025 •

edited

Loading

mdhaber commented Apr 23, 2025 •

edited

Loading