Skip to content

Commit 0991272

Browse files
committed
ENH: add an axis argument to np.bincount
This adds an axis argument to np.bincount, which can now take multidimensional arrays and do the counting over an arbitrary number of axes. `axis` defaults to `None`, which does the counting over all the axes, i.e. over the flattened array. The shape of the output is computed by removing from `list` (the input array) all dimensions in `axis`, and appending a dimension of length `max(max(list) + 1, minlength)` to the end. `out[..., n]` will hold the number of occurrences of `n` at the given position over the selected axes. If a `weights` argument is provided, its shape is broadcasted with `list` before removing the axes. In this case, `axis` refers to the axes of `list` *before* broadcasting, and `out[..., n]` will hold the sum of `weights` over the selected axes, at all positions where `list` takes the value `n`. The general case is handled with nested iterators, but shortcuts without having to set up an iterator are provided for 1D cases, with no performance loss against the previous version. As a plus, this PR also solves numpy#823, by providing specialized functions for all integer types to find the max. There are also specialized functions for all integer types for counting and doing weighted counting.
1 parent db198d5 commit 0991272

5 files changed

Lines changed: 868 additions & 125 deletions

File tree

‎numpy/add_newdocs.py‎

Lines changed: 58 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4987,48 +4987,58 @@ def luf(lamdaexpr, *args, **kwargs):
49874987

49884988
add_newdoc('numpy.lib._compiled_base', 'bincount',
49894989
"""
4990-
bincount(x, weights=None, minlength=None)
4990+
bincount(list, weights=None, minlength=None, axis=None)
49914991
4992-
Count number of occurrences of each value in array of non-negative ints.
4992+
Count number of occurrences of each value in an array of non-negative ints
4993+
along the selected axes.
49934994
4994-
The number of bins (of size 1) is one larger than the largest value in
4995-
`x`. If `minlength` is specified, there will be at least this number
4996-
of bins in the output array (though it will be longer if necessary,
4997-
depending on the contents of `x`).
4998-
Each bin gives the number of occurrences of its index value in `x`.
4999-
If `weights` is specified the input array is weighted by it, i.e. if a
5000-
value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead
5001-
of ``out[n] += 1``.
4995+
Each bin gives the number of occurrences of its index value in `list`
4996+
along the axes in `axis`. If `weights` is specified, 'list' is weighted
4997+
by it, i.e. if ``list[i] == n``, then ``out[n] += weight[i]`` instead of
4998+
``out[n] += 1``.
50024999
50035000
Parameters
50045001
----------
5005-
x : array_like, 1 dimension, nonnegative ints
5002+
list : array_like, nonnegative ints
50065003
Input array.
50075004
weights : array_like, optional
5008-
Weights, array of the same shape as `x`.
5005+
Weights, array broadcastable with `list`.
50095006
minlength : int, optional
50105007
.. versionadded:: 1.6.0
5011-
50125008
A minimum number of bins for the output array.
5009+
axis : int or tuple of ints, optional
5010+
.. versionadded:: 1.9.0
5011+
The axes of `x` over which to count, defaults to counting over
5012+
the flattened array.
50135013
50145014
Returns
50155015
-------
5016-
out : ndarray of ints
5016+
out : ndarray of ints (or doubles if weights is specified)
50175017
The result of binning the input array.
5018-
The length of `out` is equal to ``np.amax(x)+1``.
50195018
50205019
Raises
50215020
------
50225021
ValueError
5023-
If the input is not 1-dimensional, or contains elements with negative
5024-
values, or if `minlength` is non-positive.
5022+
If the input contains elements with negative values, if there are
5023+
entries in axis repeated or out of bounds, or if the input array
5024+
and `weights` cannot be broadcasted together.
50255025
TypeError
5026-
If the type of the input is float or complex.
5026+
If the type of the input, `minlength` or `axis` is not an integer, or
5027+
if `weights` cannot be safely cast to a double.
50275028
50285029
See Also
50295030
--------
50305031
histogram, digitize, unique
50315032
5033+
Notes
5034+
-----
5035+
To determine the output shape, `list` and `weights` are broadcasted
5036+
together, the axes in `axis` are removed from the broadcasted shape, and
5037+
a dimension of size `max(max(list) + 1, minlength)` is appended to the
5038+
end. Note that the values in `axis` refer to the shape of `list` prior to
5039+
broadcasting, not after. Then entry at position `out[..., n]` will be the
5040+
(weighted) count of all instances of `n` in `list` along the selected axes.
5041+
50325042
Examples
50335043
--------
50345044
>>> np.bincount(np.arange(5))
@@ -5037,7 +5047,7 @@ def luf(lamdaexpr, *args, **kwargs):
50375047
array([1, 3, 1, 1, 0, 0, 0, 1])
50385048
50395049
>>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23])
5040-
>>> np.bincount(x).size == np.amax(x)+1
5050+
>>> np.bincount(x).size == np.max(x)+1
50415051
True
50425052
50435053
The input array needs to be of integer dtype, otherwise a
@@ -5046,16 +5056,42 @@ def luf(lamdaexpr, *args, **kwargs):
50465056
>>> np.bincount(np.arange(5, dtype=np.float))
50475057
Traceback (most recent call last):
50485058
File "<stdin>", line 1, in <module>
5049-
TypeError: array cannot be safely cast to required type
5059+
TypeError: input must be an array of integers
50505060
5051-
A possible use of ``bincount`` is to perform sums over
5052-
variable-size chunks of an array, using the ``weights`` keyword.
5061+
A possible use of `bincount` is to perform sums over
5062+
variable-size chunks of an array, using the `weights` keyword.
50535063
50545064
>>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights
50555065
>>> x = np.array([0, 1, 1, 2, 2, 2])
50565066
>>> np.bincount(x, weights=w)
50575067
array([ 0.3, 0.7, 1.1])
50585068
5069+
Using the `axis` argument allows (weighted) counting over multiple axes:
5070+
5071+
>>> x = np.arange(2*3).reshape(3, 2, 1)
5072+
>>> np.bincount(x, axis=(1, 2))
5073+
array([[1, 1, 0, 0, 0, 0],
5074+
[0, 0, 1, 1, 0, 0],
5075+
[0, 0, 0, 0, 1, 1]])
5076+
>>> w = x * x
5077+
>>> np.bincount(x, w, axis=(1, 2))
5078+
array([[ 0., 1., 0., 0., 0., 0.],
5079+
[ 0., 0., 4., 9., 0., 0.],
5080+
[ 0., 0., 0., 0., 16., 25.]])
5081+
5082+
With broadcasting, multidimensional `weights` can be summed:
5083+
5084+
>>> x = [0, 1, 1, 2]
5085+
>>> w = np.arange(8).reshape(4, 2)
5086+
>>> np.bincount(x, w.T).T
5087+
array([[ 0., 1.],
5088+
[ 6., 8.],
5089+
[ 6., 7.]])
5090+
5091+
Note that in this last example, the broadcasted shape of `x` is
5092+
`(1, 1, 4)`, but counting is only done over the last axis, not all three,
5093+
because the `axis` value (which defaults to all axes) refers to the shape
5094+
prior to broadcasting.
50595095
""")
50605096

50615097
add_newdoc('numpy.lib._compiled_base', 'ravel_multi_index',

‎numpy/lib/bento.info‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ HookFile: bscript
33
Library:
44
Extension: _compiled_base
55
Sources:
6-
src/_compiled_base.c
6+
src/_compiled_base.c.src

‎numpy/lib/setup.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ def configuration(parent_package='',top_path=None):
1111

1212

1313
config.add_extension('_compiled_base',
14-
sources=[join('src', '_compiled_base.c')]
14+
sources=[join('src', '_compiled_base.c.src')]
1515
)
1616

1717
config.add_data_dir('benchmarks')

0 commit comments

Comments
 (0)