I've been bothered recently by a MATLAB terminology question: How should we describe the dim argument in functions such as sum? The documentation for sum says:
B = sum(A,dim) sums along the dimension of A specified by scalar dim. The dim input is an integer value from 1 to N, where N is the number of dimensions in A. Set dim to 1 to compute the sum of each column, 2 to sum rows, etc.
For example:
a = [1 2 3; 4 5 6; 7 8 9]
a =
1 2 3
4 5 6
7 8 9
sum(a, 1)
ans =
12 15 18
sum(a, 2)
ans =
6
15
24
For some people this terminology seems to be quite confusing. I started thinking about this when I saw a user question about it recently. In that question, the mental model leading to confusion seems to be this: dimension 1 is the row dimension, so sum(a,1) should sum each row, but MATLAB sums each column.
This a hard mental model to shake, apparently, and it makes me wonder if the phrase "along the dimension" isn't clear enough.
When you look at equations instead of ambiguous prose, it's easier to see the logic of the dim argument. Consider, for example, an M-by-N matrix A. sum(A,1) is doing this:
The variable of summation, i, is the first subscript of A.
sum(A,2) is doing this:
The variable of summation, j, is the second subscript of A.
This pattern extends nicely to higher dimensions.
So, dear readers, can you suggest a better way to document the meaning of the dim argument? Or should we just leave it be?
Get
the MATLAB code
Published with MATLAB® 7.10
Hi Steve,
I think the documentation is clear enough. What’s confusing is that the first dimension goes down. ;)
I remember that when I started using MATLAB I made the same mistake and then I simply figured out that the “dim” was consistent with the summation symbol terminology.
I think it may be useful (especially in the getting started guide or in the FAQ) to reference explicitly this logic, maybe with the same examples posted by Steve.
Oleg
The “column first” comes natural if you are thinking of matrices as mathematical objects. But if you think about them as data display objects then the “row first” view is easier to understand. So, here is an example of when the COME FROM construct make sense to think about (more so than the corresponding GOTO, which in both cases landed at the Matlab label .-)
Lars
I think it is counterintuitive. Maybe you can try something like:
= sum(A,dim) sums the elements of A, varying the dimension
specified by scalar dim, and leaving the others fixed.
The dim input is an integer value from 1 to N,
where N is the number of dimensions in A. Set dim to 1 to
compute the sum of each column, 2 to sum rows, etc.
Or something like that. Sorry for my poor English.
I think that it could be useful to turn “along dimension dim” into a link that refers to an article in Getting Started, or FAQ, across the documentation, where there could be an explanation similar to the one I gave in my answer to the SO question: “along dimension dim” means “along the direction in which dim is counted”, and “performing an operation like sum, or mean, along a dimension will collapse this dimension to size 1″.
I’m Agree with Cris, the documentation is clear enough, but you must learn first that Matlab “works better” allong rows.
example:
If you’ve learned this, you will never forget that the rows are the lovely direction of Matlab, so sum(a,1) will do the sumation on “MAtlab’s first lovely dimension” that means “Down”. ;-)
It’s a kind of trick to learn it as the Right-hand-rule
http://en.wikipedia.org/wiki/Right-hand_rule
Best regards
I have always found the terminology a bit tricky too. Along the rows doesn’t tell me if I hold rows constant or march down them for the direction. I do use the same idea mentioned above about MATLAB being column major to help me out.
–Loren
I think the documentation is clear but adding the formula may help for those that may get confused.
What I do find irritating is that the dimension parameter is not always accepted as the second input parameter, mean() and sum() work in the same manner however e.g. std() needs a flag as second parameter.
I agree with Jonas,
whenever the DIM argument exists there should be a link to a DIM help section (or a see also DIM) where Steve’s explanation with both summation formulas is integrated with graphic examples (showing a matrix with a row indicating the direction of along which the operation is computed) and descriptions.
Oleg
Instead “(…showing a matrix with a row…)”
I meant “(…showing a matrix with an arrow…)”
I feel like I’m in good company when Loran shares my views. It is tricky & likely, we all stumble thru it.
It sounds like you have concluded that some important fraction of users are confused by this. Isn’t that clear evidence that better quality of writing is required here?
You guys are sharp, world class experts & you can look at the code. So, get your technical writers working on this & make it crystal clear. The function has 6 syntax options & you did a really good job writing the FRP for 5 of them. Just improve the discussion on dim & you’re done.
Like I’ve said before, good documentation is a productivity issue. Users shouldn’t have to hack away to figure out something as simple as what you mean by the dim variable in the sum function.
OE—You seem annoyed with me that I solicited feedback about this issue in this forum. I have used this blog in the past to pose terminology questions, and I have always gained useful insight as a result. This time is no different in that respect. I plan to continue doing it.
I had not reached any conclusion about the fraction of users confused by this, other than it is nonzero.
The discussion on dim is indeed tricky, and it also affects many other functions with similar syntaxes, spread across a number of products. The broad impact certainly makes it important to get this right, but I do not underestimate the challenge in doing so. English prose is frequently ambiguous to some degree. Clarity, precision, and comprehensiveness in prose sometimes even trade off against each other.
As for being a sharp, world class expert, well, the more experience I get in software development, the less I feel like an expert in anything. Learning from readers is part of the value I get personally from time spent writing this blog.
I support the idea that Jonas presented: Make a link to a more lengthy description. (I bet you wont be able to make a better one line description than what you already have.)
I found this blog entry is the perfect explanation. If the last several lines (s(j) = \sum …, s(i) = \sum …) are in the matlab documentation, I will be relieved.
Thanks for the nice explanation.
I think the documentation is quite clear and that as soon as you start thinking about arrays with more than 2 dimensions there is no other way to interpret “along the dimension DIM.” Not to pick on Loren, but statements like:
just don’t make sense in higher dimensions. That said, my opinion is likely due to the fact that I’ve used Matlab for quite some time and am used to it. Additional help documentation, like a page on DIM or perhaps a more in-depth example using the summation convention on the doc pages would be useful for new users. Alternative phrasing along the lines of:
might also be useful – but maybe that’s just the way I think about things.
Hi Steve,
The terminology is very slippery terrain, but I try to give several general and not very contradictory rules which are helping me from time to time. They are not specially edited.
* do not over generalize
* do not oversimplify
* make it explicitly
* make it descriptively
* make is clear
* make correspondence between the name, abbreviation, terms and the function
* no duplicates, no borrowings, be original
* make in easy to decode (expand)
* write the definition (description) and compress it to a short phrase and easy to pronounce and decode abbreviation
* test it at least three examples
* test it with different subjects
* do not combine different subjects in one field
* follow the human language from the “standard” grammar books
Examples:
Write disruptively:
sbr = sum by row not just a “s” or “sum”
seabr = sum of elements in array by row not just a “s” or “sum”
Raison: “Do not over generalize!”
Some people are reading and thinking “vertically” and some people are reading and thinking “horizontally”.
Some people are reading from top to bottom, others from bottom to top.
Some people are reading from left to right, others from right to left, etc.
Note:
Assembler commands of some machines are good examples (But not all Assemblers and definitely not C-like languages. They horrifyingly oversimplified.).
Some of the issues with B = sum (A, dim) are:
* you have put two very different things in one field ( A is name, dim is dimension or unclear parameter)
* “sum” is not descriptive. It is over generalized term.
“Sum” is summing along the dimensions” is unclear because is does not describe two summing algorithm.
Method” Divide by function” or “divide by definition” could help, e.g.
csbr = compute sum by rows
csbr (A, 3×3) instead of sum (a,1)
csbr (A, r=3, c =3) instead of sum (a,1)
csbr (A)(r=3, c =3) instead of sum (a,1)
csec = compute the sum of each column
csec (A, 3×3) instead of sum (a,2)
csec (A, r=3, c =3) instead of sum (a,2)
csec (A) (r=3, c =3) instead of sum (a,2)
Sorry, but the prose is not ambiguous by itself.
If just take too much time to select the right word and to put in the right place.
The prose is as much accurate as formulas and computer programs.
But unfortunately the prose is largely neglected.
I will not comment on formulas, due to some limitations of my txt and formula processing programs. In fact I not am using this type of notation. Instead I am using abbreviations, not mathematical symbols.
I hope that will help a bit.
Best regards
Petre Petrov
I’d just like to show my support for Jonas and Paul’s view, that this phrase is very evocative of the way I visualize things:
“DIM is the dimension that is reduced by the summation”
An alternative phrasing of this concept is “the dimension collapses to size 1″. Something along those lines in addition to what’s already in the doc would probably help (or in the external explanation page that has been suggested).
When looking at a function like this, most users probably start by thinking how it would work with a for (since that’s how they coded it before). So introducing the word iteration could also be useful: the sum iterates along the dimension DIM.
The docs already include examples of the use with 2D arrays along dimensions 1 and 2 (which has helped me immensely in the past!), but saying that dim=1 computes the sums of all columns and dim=2 of all rows would be just as good.
“DIM is the dimension that is reduced by the summation”
Does it mean that dimension 1 is reduced to dimension 0?
Summing is making a sum and dimension of the original is not changed. Or not?
“the dimension collapses to size 1″.
“collapse” usually mean break down, fold or close up, crumble: fall apart, crash, etc.
I am not sure that the word “collapse” has place in the description of that function.
When looking at a function like this, the users with the appropriate level should immediately and clearly understand the subject and not looking elsewhere and making wrong conclusions.
“…the sum iterates along the dimension DIM.”
” Iteration or just “summation” or “making the sum” in such and such way”?
The old “DIM” should just be renamed with more appropriate term according to its functionality.
“…The docs already include examples of the use with 2D arrays along dimensions 1 and 2 (which has helped me immensely in the past!), but saying that dim=1 computes the sums of all columns and dim=2 of all rows would be just as good…..”
The examples should be easy to deduce (conclude by reasoning; in logic) and remember. Not just learned by heard and applied without thinking.