blinkdagger

Anyone who has ever used MATLAB has at one time or another used the all-powerful help command. The help command provides useful tidbits on the function’s inputs and outputs, and often supplies examples that helps the user immediately understand how to use the function. Unfortunately, I also think it’s safe to say that some of us have no idea how the help command works. In this post, we’re going to explore three things: the help command, the lookfor command, and the basic anatomy of an m-file.

Contents

• Why Do We Care?
• Looking for Something?
• Example: Anatomy of an m-file
• Conclusion

Why Do We Care?

First, we should ask ourselves “Why do we care how the help command works?” Simply put, we care about how the help function works because it is an amazingly useful function but requires the author of the function to provide detailed descriptions and examples to make it worthwhile. A large number of people who use MATLAB also write their own custom functions. Sometimes these functions are shared with other MATLAB users. Thus, its advantageous to write your m-files in such a way that it takes advantage of the the help command.

For instance, when you type the following at the MATLAB command prompt:

>>help mean

you see this:

 MEAN   Average or mean value.
    For vectors, MEAN(X) is the mean value of the elements in X. For
    matrices, MEAN(X) is a row vector containing the mean value of
    each column.  For N-D arrays, MEAN(X) is the mean value of the
    elements along the first non-singleton dimension of X.

    MEAN(X,DIM) takes the mean along the dimension DIM of X. 

    Example: If X = [0 1 2
                     3 4 5]

    then mean(X,1) is [1.5 2.5 3.5] and mean(X,2) is [1
                                                      4]

    Class support for input X:
       float: double, single

    See also median, std, min, max, var, cov, mode.

    Overloaded functions or methods (ones with the same name in other directories)
       help timeseries/mean.m
       help fints/mean.m

    Reference page in Help browser
       doc mean

Wouldn’t it be disastrous if nothing showed up on the MATLAB command prompt when we used the help command? I don’t know about you, but I’m very dependent on the help command. It’s one of my top ten functions used in MATLAB.

Looking for Something?

Another useful command that is a close cousin of help is the lookfor command, which allows you to search through all of MATLAB’s functions using specific keywords. For example, if I wanted to find a function to compare strings, I could do

>>lookfor 'compare string'

and get the following output:

STRCMP Compare strings.
STRCMPI Compare strings ignoring case.
STRCMP Compare strings for Java objects.
STRCMPI Compare strings ignoring case for Java objects.

The next logical thing would be to follow up with:

>>help strcmp

Example: Anatomy of an m-file

The anatomy of an m-file is important for not only the help command, but also the lookfor command. Let’s assume that Daniel has written a function called blinkdagger.m. It’s a great function that takes in as input a vector of the price history of a particular stock. It’s output is a prediction (with 99% certainty) of the behavior of that stock for the next year. Being a nice guy, Daniel sends me this lucrative MATLAB function via email but he suddenly develops an extreme case of amnesia. I receive the function in my inbox, but he (nor I) has no idea what the function does. So I try to do the following at the command prompt:

>>help blinkdagger

and I get nothing.

Now, if only Daniel had done the following to his m-file:

(Note: The above is an image. Click here to see the text.)
(Note2: I removed the actual code for the blinkdagger.m function as it could be destructive in the wrong hands.)

The first line (referred to as H1) after the function declaration is used for the lookfor command. The function name and keywords should be placed here (try to keep the description concise). The following lines after the H1 line are the lines extracted when the help command is used. Finally, similar functions or related functions should be mentioned in the “see also” portion.

Conclusion

Now, when i type the following at the command prompt:

>>help blinkdagger

I get the following output that is very informative:

 BLINKDAGGER Obtain future stock prices
    This part of the m-file shows up when you type the command
    "help blinkdagger" at the command prompt.  You can add useful
    information here regarding your function inputs and outputs.
    In addition, you can provide examples too!  If you have related
    functions then you can mention them in the "See also" portion.

    See also blinkdagger2, blinkdagger3

Check out this cool post over at Doug’s old blog for some more m-file pointers!