8000 ENH: add initial and out parameters to bincount · numpy/numpy@9f6e608 · GitHub
[go: up one dir, main page]

Skip to content

Commit 9f6e608

Browse files
committed
ENH: add initial and out parameters to bincount
The optional parameters initial and out allow bincount to efficiently reuse and accumulate results across multiple invocations.
1 parent fe2c2a4 commit 9f6e608

File tree

4 files changed

+361
-88
lines changed

4 files changed

+361
-88
lines changed

numpy/core/multiarray.py

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -889,16 +889,17 @@ def vdot(a, b):
889889

890890

891891
@array_function_from_c_func_and_dispatcher(_multiarray_umath.bincount)
892-
def bincount(x, weights=None, minlength=None):
892+
def bincount(x, weights=None, minlength=None, initial=None, out=None):
893893
"""
894-
bincount(x, /, weights=None, minlength=0)
894+
bincount(x, /, weights=None, minlength=0, initial=None, out=None)
895895
896896
Count number of occurrences of each value in array of non-negative ints.
897897
898898
The number of bins (of size 1) is one larger than the largest value in
899899
`x`. If `minlength` is specified, there will be at least this number
900900
of bins in the output array (though it will be longer if necessary,
901-
depending on the contents of `x`).
901+
depending on the contents of `x`). If `out` is specified, its size must
902+
be large enough to contain all of the bins.
902903
Each bin gives the number of occurrences of its index value in `x`.
903904
If `weights` is specified the input array is weighted by it, i.e. if a
904905
value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead
@@ -912,22 +913,32 @@ def bincount(x, weights=None, minlength=None):
912913
Weights, array of the same shape as `x`.
913914
minlength : int, optional
914915
A minimum number of bins for the output array.
916+
initial: ndarray, 1 dimension, optional
917+
Array of initial values for each bin. It must have the same shape and
918+
buffer length as the expected output
919+
out: ndarray, 1 dimenion, optional
920+
Alternative output array in which to place the result. It must have the
921+
same shape and buffer length as the expected output but the type will
922+
be cast when safe.
915923
916924
.. versionadded:: 1.6.0
917925
918926
Returns
919927
-------
920928
out : ndarray of ints
921929
The result of binning the input array.
922-
The length of `out` is equal to ``np.amax(x)+1``.
930+
The length of `out` is equal to ``max(minlength, np.amax(x)+1)``.
923931
924932
Raises
925933
------
926934
ValueError
927935
If the input is not 1-dimensional, or contains elements with negative
928-
values, or if `minlength` is negative.
936+
values, or if `minlength` is negative, or initial or out do not have
937+
sufficient sizes, or initial and out have different sizes.
929938
TypeError
930-
If the type of the input is float or complex.
939+
If the type of the input is float or complex, or `minlength` cannot be
940+
converted to int, or `initial` or `out` cannot be safely converted to
941+
the expected type.
931942
932943
See Also
933944
--------

numpy/core/multiarray.pyi

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -417,6 +417,8 @@ def bincount(
417417
/,
418418
weights: None | ArrayLike = ...,
419419
minlength: SupportsIndex = ...,
420+
initial: None | NDArray[Any] = ...,
421+
out: None | NDArray[Any] = ...,
420422
) -> NDArray[intp]: ...
421423

422424
def copyto(

0 commit comments

Comments
 (0)
0