[SciPy-Dev] Proposal: Deprecate confusing flag params in ndimage.distance_transform_*

[Terry]

 Hi all,

I would like to remove the parameters `return_distances` and
`return_indicies`, because their names are misleading and behaviors are
different.

While working on this PR: https://github.com/scipy/scipy/pull/12144
I realized that the distance_transform_* functions had confusing and
complex interactions between the `return_distances`/`distances` and
`return_indicies`/`indicies` pairs (the feature transform is always
calculated because it's needed to calculate the distance transform).

Here's how the the behavior of each pair differs:
distances\return_distances |      False       |      True
----------------------------------------------+-----------------
          None             |     nothing      | return distances
        ndarray            |     nothing      | populate ndarray

indicies\return_indicies   |      False       |      True
----------------------------------------------+-----------------
          None             |     nothing      | return distances
        ndarray            | populate ndarray | populate ndarray

Here's the proposed API:
distances:
ndarray - put distance transform here, don't return it
Truthy - Return the distance transform
Falsey - Don't return the distance transform

indicies:
ndarray - put feature transform here, don't return it
Truthy - Return the feature transform
Falsey - Don't return the feature transform

This should simplify the documentation and code, and make it easier to
reason about these behaviors.
If this sounds reasonable, I'd also be happy to make similar changes to any
other parts of scipy that have multiple optional returns/outputs.

Regards,
Terry
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20200602/526f052b/attachment.html>