numpy broadcasting rules could do with simplification
corinnebosley opened this issue · comments
The numpy course Broadcasting section can be difficult to understand due to confusing technical language. The concept itself is quite straightforward, but there are several layers of complexity in the sentences which describe the rules, and they do not correlate to the graphics although they seem like they should, so the images actually just become confusing.
I think that this section would be easier to understand if the images matched the rules and allowed the user to understand all the loaded phrases (like 'the shape of the array with fewer dimensions ... padded ... leading (left) side'; this would be easier to unpack if you maybe showed the shape of the dimensions in a code cell, and then what it means to 'pad' it to match the shape of the other array).
I agree that the having broadcasting rules in the course confuses things, and I would go as far as to say we simply remove them altogether. They are technical detail gleaned from the numpy documentation and are unncessesary to understanding the concept. The diagrams along with a good explanation of the problem broadcasting addresses is good enough IMO.
remove them altogether ... are unnecessary to understanding the concept
Interesting. Some thoughts ...
The rules are quirky + complicated, but understanding them can be important.
My initial reaction was that it is important to get across the whole gory truth + not pretend that it's all quite obvious + straightforward, when in practice it absolutely is not !!!
However, after some soul-searching, I can support the idea that we can summarise without trying to explain it all :
- the basic idea is simple + useful (examples)
- it doesn't do everything you'd like, so in many cases you need to take control (more examples : use 'reshape' or 'newaxis' to get it to do the right thing)
- there is a long + complicated set of exact rules (see external reference)
- that short + precise 'rules' based description is here : https://docs.scipy.org/doc/numpy/reference/ufuncs.html#broadcasting
Interestingly, I note that numpy docs already has such a "longer + less formal" account in the User Guide : https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html
I'm not sure I like it that much, but I have to admit that it's examples do introduce almost exactly the same ideas, in the same order, as the list I wrote out for myself !