|
""" |
|
======================== |
|
Broadcasting over arrays |
|
======================== |
|
|
|
The term broadcasting describes how numpy treats arrays with different |
|
shapes during arithmetic operations. Subject to certain constraints, |
|
the smaller array is "broadcast" across the larger array so that they |
|
have compatible shapes. Broadcasting provides a means of vectorizing |
|
array operations so that looping occurs in C instead of Python. It does |
|
this without making needless copies of data and usually leads to |
|
efficient algorithm implementations. There are, however, cases where |
|
broadcasting is a bad idea because it leads to inefficient use of memory |
|
that slows computation. |
|
|
|
NumPy operations are usually done on pairs of arrays on an |
|
element-by-element basis. In the simplest case, the two arrays must |
|
have exactly the same shape, as in the following example: |
|
|
|
>>> a = np.array([1.0, 2.0, 3.0]) |
|
>>> b = np.array([2.0, 2.0, 2.0]) |
|
>>> a * b |
|
array([ 2., 4., 6.]) |
|
|
|
NumPy's broadcasting rule relaxes this constraint when the arrays' |
|
shapes meet certain constraints. The simplest broadcasting example occurs |
|
when an array and a scalar value are combined in an operation: |
|
|
|
>>> a = np.array([1.0, 2.0, 3.0]) |
|
>>> b = 2.0 |
|
>>> a * b |
|
array([ 2., 4., 6.]) |
|
|
|
The result is equivalent to the previous example where ``b`` was an array. |
|
We can think of the scalar ``b`` being *stretched* during the arithmetic |
|
operation into an array with the same shape as ``a``. The new elements in |
|
``b`` are simply copies of the original scalar. The stretching analogy is |
|
only conceptual. NumPy is smart enough to use the original scalar value |
|
without actually making copies, so that broadcasting operations are as |
|
memory and computationally efficient as possible. |
|
|
|
The code in the second example is more efficient than that in the first |
|
because broadcasting moves less memory around during the multiplication |
|
(``b`` is a scalar rather than an array). |
|
|
|
General Broadcasting Rules |
|
========================== |
|
When operating on two arrays, NumPy compares their shapes element-wise. |
|
It starts with the trailing dimensions, and works its way forward. Two |
|
dimensions are compatible when |
|
|
|
1) they are equal, or |
|
2) one of them is 1 |
|
|
|
If these conditions are not met, a |
|
``ValueError: frames are not aligned`` exception is thrown, indicating that |
|
the arrays have incompatible shapes. The size of the resulting array |
|
is the maximum size along each dimension of the input arrays. |
|
|
|
Arrays do not need to have the same *number* of dimensions. For example, |
|
if you have a ``256x256x3`` array of RGB values, and you want to scale |
|
each color in the image by a different value, you can multiply the image |
|
by a one-dimensional array with 3 values. Lining up the sizes of the |
|
trailing axes of these arrays according to the broadcast rules, shows that |
|
they are compatible:: |
|
|
|
Image (3d array): 256 x 256 x 3 |
|
Scale (1d array): 3 |
|
Result (3d array): 256 x 256 x 3 |
|
|
|
When either of the dimensions compared is one, the other is |
|
used. In other words, dimensions with size 1 are stretched or "copied" |
|
to match the other. |
|
|
|
In the following example, both the ``A`` and ``B`` arrays have axes with |
|
length one that are expanded to a larger size during the broadcast |
|
operation:: |
|
|
|
A (4d array): 8 x 1 x 6 x 1 |
|
B (3d array): 7 x 1 x 5 |
|
Result (4d array): 8 x 7 x 6 x 5 |
|
|
|
Here are some more examples:: |
|
|
|
A (2d array): 5 x 4 |
|
B (1d array): 1 |
|
Result (2d array): 5 x 4 |
|
|
|
A (2d array): 5 x 4 |
|
B (1d array): 4 |
|
Result (2d array): 5 x 4 |
|
|
|
A (3d array): 15 x 3 x 5 |
|
B (3d array): 15 x 1 x 5 |
|
Result (3d array): 15 x 3 x 5 |
|
|
|
A (3d array): 15 x 3 x 5 |
|
B (2d array): 3 x 5 |
|
Result (3d array): 15 x 3 x 5 |
|
|
|
A (3d array): 15 x 3 x 5 |
|
B (2d array): 3 x 1 |
|
Result (3d array): 15 x 3 x 5 |
|
|
|
Here are examples of shapes that do not broadcast:: |
|
|
|
A (1d array): 3 |
|
B (1d array): 4 # trailing dimensions do not match |
|
|
|
A (2d array): 2 x 1 |
|
B (3d array): 8 x 4 x 3 # second from last dimensions mismatched |
|
|
|
An example of broadcasting in practice:: |
|
|
|
>>> x = np.arange(4) |
|
>>> xx = x.reshape(4,1) |
|
>>> y = np.ones(5) |
|
>>> z = np.ones((3,4)) |
|
|
|
>>> x.shape |
|
(4,) |
|
|
|
>>> y.shape |
|
(5,) |
|
|
|
>>> x + y |
|
<type 'exceptions.ValueError'>: shape mismatch: objects cannot be broadcast to a single shape |
|
|
|
>>> xx.shape |
|
(4, 1) |
|
|
|
>>> y.shape |
|
(5,) |
|
|
|
>>> (xx + y).shape |
|
(4, 5) |
|
|
|
>>> xx + y |
|
array([[ 1., 1., 1., 1., 1.], |
|
[ 2., 2., 2., 2., 2.], |
|
[ 3., 3., 3., 3., 3.], |
|
[ 4., 4., 4., 4., 4.]]) |
|
|
|
>>> x.shape |
|
(4,) |
|
|
|
>>> z.shape |
|
(3, 4) |
|
|
|
>>> (x + z).shape |
|
(3, 4) |
|
|
|
>>> x + z |
|
array([[ 1., 2., 3., 4.], |
|
[ 1., 2., 3., 4.], |
|
[ 1., 2., 3., 4.]]) |
|
|
|
Broadcasting provides a convenient way of taking the outer product (or |
|
any other outer operation) of two arrays. The following example shows an |
|
outer addition operation of two 1-d arrays:: |
|
|
|
>>> a = np.array([0.0, 10.0, 20.0, 30.0]) |
|
>>> b = np.array([1.0, 2.0, 3.0]) |
|
>>> a[:, np.newaxis] + b |
|
array([[ 1., 2., 3.], |
|
[ 11., 12., 13.], |
|
[ 21., 22., 23.], |
|
[ 31., 32., 33.]]) |
|
|
|
Here the ``newaxis`` index operator inserts a new axis into ``a``, |
|
making it a two-dimensional ``4x1`` array. Combining the ``4x1`` array |
|
with ``b``, which has shape ``(3,)``, yields a ``4x3`` array. |
|
|
|
See `this article <http://wiki.scipy.org/EricsBroadcastingDoc>`_ |
|
for illustrations of broadcasting concepts. |
|
|
|
""" |
|
from __future__ import division, absolute_import, print_function |
|
|
