Repository: numpy/numpy
Pull request: DOC: Improve intersect1d docstring
The docstring now says what to expect if you call
intersect1d(assume_unique=True) but pass in non-unique data

This fixes https://github.com/numpy/numpy/issues/16406

Problem statement:
numpy.intersect1d() should be clear about the consequences of assume_unique=Tru
Hi. This is a minor documentation request. When you give numpy.intersect1d() non-unique data, but set assume_unique=True, then you get out-of-bounds indices. It would be nice if the docstring clearly indicated that this would happen. It woudl be very helpful if you THINK you're giving it unique data, but aren't. Reproducing snippet:

```python
import numpy

aa = numpy.array([ 1,2,3,4,5])
bb = numpy.array([ 3,4,4,5,6])

common, ia, ib = numpy.intersect1d(aa,bb, assume_unique=True, return_indices=True)

print(ia)
```

I get

```
[2 3 6 4]
```

in the output, which is clearly wrong since you can't index a length-5 array with 6.

The documentation should say something like

```
If True, the input arrays are both assumed to be unique, which can speed up the calculation. If True and non-unique arrays are given, incorrect results and out-of-bounds indices could result. Default is False.
```

Thanks!

Hints from issue discussion:
Thanks for reporting @dkogan ! On the one hand, it could be argued that the documentation is already pretty clear here: the name `assume_unique` itself is already pretty descriptive, and the parameter description makes it clear it is an optimization feature. IMO the current documentation is sufficient to dissuade users from explicitly setting `assume_unique=True` with non-unique inputs. On the other hand, adding a mention of OOB indices as you propose is a relatively unobtrusive change that does forewarn users of the *kind* of problem they can expect if the assumption is violated.

I'd lean towards leaving it as-is (on the premise that shorter text is more likely to be read), but I don't feel strongly about it. Feel free to submit a PR with the proposed change which is more likely to elicit opinions during review.
That extra bit of text would have saved me at least one hour of debugging time yesterday. I'll submit a pr in a bit.

Commit message: intersect1d(): a bit more info in the docstring

The docstring now says what to expect if you call
intersect1d(assume_unique=True) but pass in non-unique data

Patch to review:
diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index 22687b9415f6..7cc868c54e06 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -356,8 +356,10 @@ def intersect1d(ar1, ar2, assume_unique=False, return_indices=False):
     ar1, ar2 : array_like
         Input arrays. Will be flattened if not already 1D.
     assume_unique : bool
-        If True, the input arrays are both assumed to be unique, which
-        can speed up the calculation.  Default is False.
+        If True, the input arrays are both assumed to be unique, which can speed
+        up the calculation.  If True but non-unique arrays are given, incorrect
+        results and out-of-bounds indices could result.  Default is False.
+
     return_indices : bool
         If True, the indices which correspond to the intersection of the two
         arrays are returned. The first instance of a value is used if there are


Code review comments:
diff_hunk: @@ -356,8 +356,10 @@ def intersect1d(ar1, ar2, assume_unique=False, return_indices=False):
     ar1, ar2 : array_like
         Input arrays. Will be flattened if not already 1D.
     assume_unique : bool
-        If True, the input arrays are both assumed to be unique, which
-        can speed up the calculation.  Default is False.
+        If True, the input arrays are both assumed to be unique, which can speed
+        up the calculation.  If True but non-unique arrays are given, incorrect
+        results and out-of-bounds indices could result.  Default is False.
+
path: numpy/lib/arraysetops.py
text: @user1:
```suggestion
```