{"id":3249,"date":"2019-04-30T14:24:08","date_gmt":"2019-04-30T18:24:08","guid":{"rendered":"https:\/\/blogs.mathworks.com\/steve\/?p=3249"},"modified":"2019-11-01T22:40:40","modified_gmt":"2019-11-02T02:40:40","slug":"changes-to-sum-and-dim","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/steve\/2019\/04\/30\/changes-to-sum-and-dim\/","title":{"rendered":"Changes to SUM and DIM"},"content":{"rendered":"

Does this line of code make you raise your eyebrows in puzzlement?<\/p>

c = sum(A,[1 2])\r\n<\/pre>
If so, you are likely an experienced MATLAB user who does not make a habit of carefully studying the release notes, line by line, every six months. So, let me tell you about this change to sum<\/tt> and other related functions.<\/p>
I think of sum<\/tt> as a vector-wise<\/i> function. Its basic definition is expressed in terms of its operation on a vector: sum(v)<\/tt>, where v<\/tt> is a vector, returns a scalar that is the sum of the elements of v<\/tt>.<\/p>
v = [1 2 3 4 5 6];\r\nsum(v)\r\n<\/pre>
\r\nans =\r\n\r\n    6 times 7 divided 2, silly.\r\n\r\n<\/pre>
For sum<\/tt> and many, many other functions, MATLAB has a forgiving definition of the term \"vector.\" It can refer to a single column (Px1) or a single row (1xP). The expression sum(v)<\/tt> doesn't care.<\/p>
w = v'\r\nsum(w)\r\n<\/pre>
\r\nw =\r\n\r\n     1\r\n     2\r\n     3\r\n     4\r\n     5\r\n     6\r\n\r\n\r\nans =\r\n\r\n    you can't fool me, the answer is still 21.\r\n\r\n<\/pre>
How about sum<\/tt> on a matrix? We just love magic squares around here, especially when we're talking about sums.<\/p>
A = magic(3)\r\n<\/pre>
\r\nA =\r\n\r\n     8     1     6\r\n     3     5     7\r\n     4     9     2\r\n\r\n<\/pre>
What does sum(A)<\/tt> do? Remember what I said earlier - I think of sum<\/tt> as a vector-wise function, meaning that fundamentally it operates on vectors. If you pass it a matrix, it will treat that matrix as a stack of vectors<\/b>. Specifically, it will treat the matrix as a stack of column vectors, computing the sum of each of them.<\/p>
sum(A)\r\n<\/pre>
\r\nans =\r\n\r\n    15    15    15\r\n\r\n<\/pre>
For the last two decades (and just a bit more), the sum<\/tt> function has accepted an optional argument that we call DIM<\/tt>. This argument lets you change the way sum<\/tt> treats a matrix (or a multidimensional array) as a stack of vectors. For example, the call sum(A,2)<\/tt> tells sum<\/tt> to treat A<\/tt> as a stack of row vectors and compute the sum of each one, result in a column vector containing row sums.<\/p>
sum(A,2)\r\n<\/pre>
\r\nans =\r\n\r\n    15\r\n    15\r\n    15\r\n\r\n<\/pre>
Of course, a magic square has the same row sums as column sums, which is why a magic square was probably a bad choice for this example. However, my employment contract requires that I use magic(3)<\/tt> at every opportunity.<\/p>
Now, suppose I have an RGB image, F<\/tt>, which is MxNx3, and I want to compute the sum of each of the three component images, F(:,:,1)<\/tt>, F(:,:,2)<\/tt>, and F(:,:,3)<\/tt>? For most of MATLAB history, this is what we would tell you to do: Compute the column sums and then compute the row sums of the result. (Or, you could do it the other way 'round and get the same answer.)<\/p>
F = imread('peppers.png'<\/span>);\r\nc = sum(sum(F,1),2)\r\n<\/pre>
\r\nc(:,:,1) =\r\n\r\n    23746472\r\n\r\n\r\nc(:,:,2) =\r\n\r\n    13054194\r\n\r\n\r\nc(:,:,3) =\r\n\r\n    11331211\r\n\r\n<\/pre>
OK, suppose I want to compute the sum of all<\/b> the elements of F<\/tt>? The historical answer: convert F<\/tt> to a single column vector using the expression F(:)<\/tt> and then call sum<\/tt>.<\/p>
sum(F(:))\r\n<\/pre>
\r\nans =\r\n\r\n    48131877\r\n\r\n<\/pre>
But those coding patterns are SO<\/b> R2018a. With the R2018b release, DIM<\/tt> can be a vector, and it call also be the string \"all\"<\/tt> (or 'all'<\/tt>). Computing the sum of the each of the three component images can now be:<\/p>
sum(F,[1 2])\r\n<\/pre>
\r\nans(:,:,1) =\r\n\r\n    23746472\r\n\r\n\r\nans(:,:,2) =\r\n\r\n    13054194\r\n\r\n\r\nans(:,:,3) =\r\n\r\n    11331211\r\n\r\n<\/pre>
And computing the sum of all of the elements of the three-dimensional array can be:<\/p>
sum(F,[1 2 3])\r\n<\/pre>
\r\nans =\r\n\r\n    48131877\r\n\r\n<\/pre>
or<\/p>
sum(F,\"all\"<\/span>)\r\n<\/pre>
\r\nans =\r\n\r\n    48131877\r\n\r\n<\/pre>
After you have summed everything in sight that seems to need summing, you can check out these other MATLAB vector-wise functions that also have this new DIM<\/tt> behavior: all<\/tt>, any<\/tt>, bounds<\/tt>, max<\/tt>, min<\/tt>, mean<\/tt>, median<\/tt>, mode<\/tt>, prod<\/tt>, std<\/tt>, and var<\/tt>.<\/p>
Let me leave you with a little bit of programming advice related to these functions. If you are certain that the input argument you are passing to one of these functions is a vector (because you constructed or computed it yourself), then you can safely use the single-input syntax, like sum(v)<\/tt>. Otherwise, I recommend that you always provide the optional DIM<\/tt> argument to avoid certain ambiguities associated with MATLAB's forgiving definition of \"vector.\"<\/p>