rms

Calculates RMS for N-D matrices

Description

Efficient MATLAB function for finding RMS values. Accepts N-Dimensional matrices, and computes the column-wise RMS value for N>1, or across any dimension dim if specified by the user.

Usage:

output = rms(input,dim)

• MATLAB release: MATLAB 7.0.4 (R14SP2)
• Other requirements: Please report bugs to the author

[Duane Hanselman]

No useful help text. Why is a function needed to handle such a simple task? Just might be useful if it handled N-dim. data along a user-specified direction rather than just column-wise.

[Hazem (Author) Baqaen]

Duane, your criticism is misplaced. The function does not require much of a help text because its use is pretty much self-explanatory. Its strength is that it is optimized for speed in both the 1-D and N-D cases. And sure, it is very simple, but I found it useful in my work (that is why i created it as a separate function) and I thought it might be useful to others.

In my opinion, there is no need for a user-specified direction; it introduces unnecessary complications with the attendant loss in performance. I will give it some more thought, though.

Hazem

[Duane Hanselman]

Hazem: I note that you rated your own file with 5 stars to improve its rating. N/A would have been more appropriate. Also, help text that follows standard MATLAB practices is called for, e.g., >> help norm or >> help sqrt. These functions have good help text despite being "pretty much self-explanatory." Your arguments are not persuasive, so my rating remains.

[John D'Errico]

Any function still begs for help, despite its simplicity. Otherwise, how is the user to know if it acts row-wise or column-wise, or even if it works on the entire unrolled array? Forcing every user to edit the code to figure out the answer is silly. Remember, some of those who may use this tool may not have a need for it every day. Make it easy for them to use your code. Its one of the differences between professionally written code and the rest.

Duane also has a very valid point, that this could be a more useful tool if it worked in a way consistent with other similar functions, such as mean, std, etc. If it did, then your users might not even need to read the help (that should be there anyway.)

The loss of performance due to an if statement is trivial.
You can still retain that optimized speed with almost no loss.

Finally, you should not rate your own submission when you respond to comments! It is assumed that the author likes their own code when they posted it. That is why there is a N/A option in the ratings.

[Hazem Baqaen]

I apologize for rating my own code. I thought that a low early rating (which i thought unjustified) which Duane gave it might drive users away from it prematurely, although I am convinced it would do the job for them. In any case, it was wrong to do that.

You are both correct as regards the help text. It has been my practice to write code that I think is understandable without regard to MATLAB standard practices. This is mainly because of restrictions on my time.
In this case, the nature of the problem leaves no room for interpretation of the use of the code, and that is why I thought it was sufficiently self-explanatory. There is no need to edit the code to see how it works. A couple of trials with simple inputs should make everything plain.

Being such a simple fucntion, one of the things it offers over other similar functions is the relative speed opimization. This is not insignificant if it is imbedded in an iterative loop with long inputs.

Hazem

[urs (us) schwarz]

your apparent lack of sympathy towards a user friendly help section is bothersome and not appropriate if you want to publish your code(s) to this community
- you don't have time: well, what makes you think that the average user has time to spend for a couple of trials with simple input(!) to (finally) figure it out
- while one does not have to edit it, one will have to timeconsumingly type it every time anew -and- then think about it for another while
- just using a descriptive name does certainly not guarantee that every member of this community will automatically know what you put under the hood
- also, we are talking about the help section and not (yet) about commenting your engine, which (admittedly) is a different story
- in addition, i fully agree with the other reviewers that it should follow the syntax of similar (stats) functions
- i suggest you give it another try
us

[Hazem Baqaen]

Urs, while I don't disagree with you, I would like to point out that the user should never simply trust the help text in any code. Any serious user or programmer should have to check for him/herself whether the code actually works.

Hazem

[John D'Errico]

The idea of verifying personally every code you use is ridiculous. Will you personally verify the correctness and even what the outputs mean of codes such as svd, lu, chol, eig, etc? Suppose no help was provided there?
The quality of its documentation is a large factor in any professionally written piece of code. A second major factor is an interface consistent with those functions that naturally should behave the same way. Thus matlab has the functions mean, std, var, median, etc. Rms should be consistent with them if matlab is to remain a natural language to use. Code that is inconsistent with its natural cousins and lacks help to alert the user to that fact is not good by any definition of the word. The fastest code in the world is still useless if it generates an unexpected result.
Finally, you seem terribly worried about the speed of your code, and how it will be compromised by a simple branch. Consider the cost in debugging time when the unwary user uses your code. Consider that even the wary user is forced to test your code just to see what it does every time they use it.

[Hazem Baqaen]

Verifying every piece of code you use is not rediculous. I do it all the time. Even "official" MATLAB functions I test for key cases. I don't need to go into the code everytime to know that it will work for me. I just need a good understanding of the problem at hand to be able to test a function that attempts to solve it. But there is no foolproof way. I am talking about a reasonable degree of confidence here.

Testing or debugging time is not an issue for a single user, since s/he need to do it anyway only once. Once they are satisfied that rms works, that's it.

Hazem

[Jos x]

I still remember the distribution of points that made up a grade for a programming assignment at university: "2 points for algorithm design, 2 points for help and comments, and only 1 point for correct functioning".
So, my professor would rate this snippet as 1, and since he was a professor and I am not I can only agree with him ...

[Pascal Getreuer]

Well said, John: presentation is important. Even the simplest functions benefit from syntax description and some explanation.

[Duane Hanselman]

Be on the lookout for an alternative rms function to appear tomorrow (2005/01/12) on File Exchange.

[Hazem Baqaen (Author)]

I have now incorportated suggestions made by Duane and others while trying to keep the code as streamlined as possible.

Hazem

[Hazem Baqaen]

THIS FILE WAS NOT UPDATED
Because of some problem the list of changes was updated but not the file itself. Please wait for the update.

[Hazem Baqaen]

THE FILE HAS NOW BEN UPDATED

[Duane Hanselman]

No need to compute square of data just to find size of array, e.g., size(in.^2) is the same as size(in)

[Hazem Baqaen]

Right! thanks for pointing that out.

Hazem

[Bill Hallbert]

code has double &&

[John Bay]

thanks buddy!

[Jeff]

Your function does not work properly for inputs that are both complex and are greater than 1 dimension.

You could replace in .^ 2 with in .* conj(in)