diff options
| author | Eric Wieser <wieser.eric@gmail.com> | 2017-12-29 22:19:05 +0000 |
|---|---|---|
| committer | Eric Wieser <wieser.eric@gmail.com> | 2017-12-31 10:57:17 +0000 |
| commit | 268fedb88a1ef4a8bcc843cf7eda50833e9b4ba7 (patch) | |
| tree | e410390f155ec76de63e05d224a03d0bf82bd84a /numpy/add_newdocs.py | |
| parent | 7bb2d5a8f0219aa5acb5fda05929f1a0745a1883 (diff) | |
| download | numpy-268fedb88a1ef4a8bcc843cf7eda50833e9b4ba7.tar.gz | |
DOC: Explain np.digitize more clearly
Show the four modes in a table for clarity
Compare to searchsorted
[ci-skip]
Diffstat (limited to 'numpy/add_newdocs.py')
| -rw-r--r-- | numpy/add_newdocs.py | 29 |
1 files changed, 21 insertions, 8 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index e0eeccb08..16ceee48b 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -5136,13 +5136,17 @@ add_newdoc('numpy.core.multiarray', 'digitize', Return the indices of the bins to which each value in input array belongs. - Each index ``i`` returned is such that ``bins[i-1] <= x < bins[i]`` if - `bins` is monotonically increasing, or ``bins[i-1] > x >= bins[i]`` if - `bins` is monotonically decreasing. If values in `x` are beyond the - bounds of `bins`, 0 or ``len(bins)`` is returned as appropriate. If right - is True, then the right bin is closed so that the index ``i`` is such - that ``bins[i-1] < x <= bins[i]`` or ``bins[i-1] >= x > bins[i]`` if `bins` - is monotonically increasing or decreasing, respectively. + ========= ============= ============================ + `right` order of bins returned index `i` satisfies + ========= ============= ============================ + ``False`` increasing ``bins[i-1] <= x < bins[i]`` + ``True`` increasing ``bins[i-1] < x <= bins[i]`` + ``False`` decreasing ``bins[i-1] > x >= bins[i]`` + ``True`` decreasing ``bins[i-1] >= x > bins[i]`` + ========= ============= ============================ + + If values in `x` are beyond the bounds of `bins`, 0 or ``len(bins)`` is + returned as appropriate. Parameters ---------- @@ -5160,7 +5164,7 @@ add_newdoc('numpy.core.multiarray', 'digitize', Returns ------- - out : ndarray of ints + indices : ndarray of ints Output array of indices, of same shape as `x`. Raises @@ -5187,6 +5191,15 @@ add_newdoc('numpy.core.multiarray', 'digitize', for larger number of bins than the previous linear search. It also removes the requirement for the input array to be 1-dimensional. + For monotonically _increasing_ `bins`, the following are equivalent:: + + np.digitize(x, bins, right=True) + np.searchsorted(bins, x, side='left') + + Note that as the order of the arguments are reversed, the side must be too. + The `searchsorted` call is marginally faster, as it does not do any + monotonicity checks. Perhaps more importantly, it supports all dtypes. + Examples -------- >>> x = np.array([0.2, 6.4, 3.0, 1.6]) |