I have a vague feeling we agreed this should be a string like 'none', but I can't remember the reasoning.

Yes, I don't have a strong opinion here on whether prescale=False or prescale='none' is better. I'd say best not to mix argument types. But we do allow prescale=tuple(...), so that consistency is out of the window anyway? And prescale='none' does feel like a crutch for None or False.

Also see @stefanv's comment suggesting None.

@jni - I have some vague memory that you had a preference for the string 'none' here. Is that right?

Did we discuss an int-type scaling option independent of legacy? I mean scaling int images only from dtype min -> 0, dtype max -> 1?

Could you expand on that? Do you mean an option that only scales integer images to [0, 1] and ignores floats? Would that differentiate signed and unsigned ints? Do you think it would be more useful than confusing?

Isn't that what legacy does?

No, 'legacy' scales uints to 0, 1, and ints to -1, 1. Somewhat oddly.

Remind me, but can stacklevel not be auto-detected? It's a bit of a pity to have that complexity in this function, that will be commonly used.

Like I said in the meeting, there's the skip_file_prefixes argument. But that's only available since Python 3.12. According to SPEC0 we are close to dropping 3.11.

So it depends on whether you we want the very next release to support 3.11 or not. Otherwise we'd need to hack something together using either a decorator at the public API boundary or do some frame inspection ourselves (like in assert_stacklevel). Thoughts?

This is fine for now; we can revisit in the future.

Could consider calling this dtype instead of legacy. It doesn't matter much, but I think it's more description, and it actually makes sense not to touch float images when normalizing by dtype (since you only know ranges for integer dtypes).

Not opposed. That would also underline that we intend to keep this scaling option around. It's also less judgy. 😄 I'm on board. I assume it would also keep its specific behavior for unsigned and signed ints?

Hrm, no, I suppose that's the difference between this mode and legacy that @matthew-brett may have referred to: there's no scaling to [-1, 1], only [0, 1].

We can have multiple names for the same thing. I have a vague desire for 'legacy' because I suspect the most common use-case will be "give me what I got before", so, without 'legacy' they will have to do more reading.

How about integer_dt_range or something?

I'm not sure I agree. The two passed values don't need to correspond to a minimum and maximum. They are just a two values – the first lower than the other – that will correspond to 0 and 1 after scaling.

I remember us introducing that option precisely for batch cases, where that might not be the case? Thinking about it, it's an assumption I'd like to avoid using in our documentation.

Using lower and higher also avoids slight confusion with Python's min() and max() functions. But that's minor thing.

Ah, so you think we purposefully should allow scaling that takes the image outside of [0, 1]?

Is there a reason to enforce 0, 1 as output? I would have thought it cleaner to allow the user to do what they will with this; they can clip themselves if they want.

Should be (clip(img, min, max) - min) / (max - min)`.

Is that a typo? Do you actually mean to apply clip as the last operation? E.g.,

scaled = (img - lower) / (higher - lower)
scaled = clip(scaled, min, max)

I was operating under the impression that not clipping during scaling is a feature. That would allow something like Fahrenheit to Celsius conversion

fahrenheit = [-10, 1, 60, 100]
_prescale_value_range(fahrenheit, mode=(32, (9/5 + 32)))
# Out[6]: array([-23.33333333, -17.22222222,  15.55555556,  37.77777778])

I was concerned about the case where the user intends to do minmax scaling, but provides incorrect min and max values. However, I think since we already provide minmax, it's OK to let this remain as-is, and perhaps just note that in the docstring (that we do no clipping to ensure range is [0, 1] internally).

minmax vs min-max, preference anyone?

+0.5 for "minmax".

I vaguely prefer 'minmax' too.

Is this the most stable order? Small float - small float can be problematic.

Also, do we check that max value is >= max of image? Otherwise output will be >1. Same for lower bound.

Maybe recommend prescale='minmax'?

Maybe instead of copying this docstring everywhere, refer to a central docstring? I.e., we could expose the utility function in the public namespace? Or maybe this becomes templated, and is filled out on import?

My personal pet peeve are docstrings that are only useful at runtime. E.g., I find it really annoying when digging through SciPy's source code.

I'm also -1 on hiding the information from users behind a link for the same reason.

If you are worried about this getting out of sync. I'd rather have a decorator enforcing the consistency at runtime.

Yes, but this is going to appear all over the place, so if you replicate it, you are going to be doing a lot of search and replaces as we figure out the message. Thoughts @matthew-brett?

I agree that Scipy's automated docstrings are pretty annoying - and I think I wrote some of them. I quite like the idea of enforcing the match between docstrings with a decorator. We could add a source processor to do it, as well, to be run if the decorator check fails.