Repository: scikit-image/scikit-image

Issue:
Better documentation for `peak_local_max`s `exclude_border` boolean variant
## Description

The documentation of [`peak_local_max`](http://scikit-image.org/docs/dev/api/skimage.feature.html#skimage.feature.peak_local_max) says nothing about the boolean variant of the `exclude_border` parameter, although it defaults to `True`. So it's unclear from the documentation what that is supposed to mean.

By looking at the corresponding [code](https://github.com/scikit-image/scikit-image/blob/master/skimage/feature/peak.py#L115), one can see that `min_distance` is used for `exclude_border` when it is passed `True`.

**First improvement:** Update the corresponding documentation to make this invariant clear.

Additionally, I think the default value of `True` might lead to subtle problems, that people might not be aware of. For instance, I wasn't aware of this fact until now and just found it by visual inspection. My mental model of NMS doesn't seem to fit the default implementation of `peak_local_max`, which I find problematic.

**Second improvement:** Don't use `True` as default for `exclude_border`, instead use `0`.



Discussion:
Thanks for reporting this @b52 !
So, what's the state on this one? I would be willing to write a PR for this.
@b52 regarding your issue message: I also find the results very difficult to understand (although from the implementation point of view they are pretty clear). We already faced this in https://github.com/scikit-image/scikit-image/issues/1831, https://github.com/scikit-image/scikit-image/issues/1832.

Unless you are willing to go deep into the function and significantly rework it, I'd suggest only to document the default behaviour more clearly (your Improvement#1), i.e. write that "...by default, if exclude_border is True, uses min_distance... bla-bla-bla". In that case, IMO, `True` is a good choice for the default value (better than `0`, `-1` or `None`).
@soupault I disagree that `True` is a good default value for `exclude_border`. This is very counter intuitive and to my knowledge in no other NMS function used out there as a default.
@b52 Sorry, I wasn't clear. I meant that `True` is the best alternative among others with the same effect (border exclusion).
If you would like to change the default value, feel free to start the discussion. Or maybe we could converge on a PR with the brand new NMS algorithm with `exclude_border=False` :wink: ...

@jni @ahojnnes do you have any thoughts on this?
I see, nonetheless I think `exclude_border` should be an effect the user has to opt in explicitly. 
@soupault @b52 Oops, this response has been sitting in an open tab for the past couple of days:

I agree with @b52 that `True` is not a good default value — it's a little too active/prescriptive. In the past, when we have tried to do such "good defaults", we've often gotten into trouble (e.g. sigma=1 and convert2lab=True for SLIC) and had to backtrack on the API. I think the worst case behaviour is better for do-nothing defaults — people who want the advanced behaviour can find it, otherwise the function does what it says it does and nothing more.

Having said that, I suggest a default of `False` (assuming we want to keep the bool option), as it reads a little better than 0. And yes, the documentation should definitely mention what bool options do.
Alright, if it's fine with you guys I would write up an appropriate PR. Sounds good?
@b52 Yes, absolutely!
@soupault Mind merging #2435 before that?
In accordance with the policy, it is all up to the 2nd reviewer. :)

Resolving patch:
diff --git a/skimage/feature/peak.py b/skimage/feature/peak.py
--- a/skimage/feature/peak.py
+++ b/skimage/feature/peak.py
@@ -31,8 +31,9 @@ def peak_local_max(image, min_distance=1, threshold_abs=None,
     Peaks are the local maxima in a region of `2 * min_distance + 1`
     (i.e. peaks are separated by at least `min_distance`).
 
-    If peaks are flat (i.e. multiple adjacent pixels have identical
-    intensities), the coordinates of all such pixels are returned.
+    If there are multiple local maxima with identical pixel intensities
+    inside the region defined with `min_distance`,
+    the coordinates of all such pixels are returned.
 
     If both `threshold_abs` and `threshold_rel` are provided, the maximum
     of the two is chosen as the minimum intensity threshold of peaks.
@@ -51,9 +52,12 @@ def peak_local_max(image, min_distance=1, threshold_abs=None,
         the minimum intensity of the image.
     threshold_rel : float, optional
         Minimum intensity of peaks, calculated as `max(image) * threshold_rel`.
-    exclude_border : int, optional
-        If nonzero, `exclude_border` excludes peaks from
+    exclude_border : int or bool, optional
+        If nonzero int, `exclude_border` excludes peaks from
         within `exclude_border`-pixels of the border of the image.
+	If True, takes the `min_distance` parameter as value.
+	If zero or False, peaks are identified regardless of their
+	distance from the border.
     indices : bool, optional
         If True, the output will be an array representing peak
         coordinates.  If False, the output will be a boolean array shaped as


Test patch: