Phone a Friend^♭Who Wants to be a Millionaire:  Understanding Ox Documentation

To learn how to use Ox you must learn how to get help with Ox. Complete Ox documentation is put on your computer when you install Ox. You can get to the documentation from OxEdit by following -> Help > Ox Help, which will open in your web browser. I recommend you bookmark that page so you can get to it directly.

The same exact documentation is available online at http://www.doornik.com/ox/. Here is that page:

There are 4 links that are most useful as you start to learn the Ox language. Some of the other items can become important later on.

A. Language Tutorial

If you click on this menu item you will see a brief summary of Ox programming. These notes cover the same material but assume less knowledge of programming and programming languages in general. If you already have programmed in some other language, the Ox language tutorial is a quick way to get going. If you have not programmed you will probably find it less useful at this point.

B. Syntax Reference

The syntax reference is a complete version of the language tutorial. It covers all elements of Ox syntax in a logical order. It is most useful as a reference guide once you can do some things in Ox but want to do more or if Ox is not behaving the way you expect. These notes attempt to cover the same ground but are not designed as a reference while debugging a program or trying to find a way to do something new in Ox.

C. Function Summary (and reference and examples)

One of the key aspects of Ox is the fact that it is designed for econometrics and economics in general. Much of this utility comes from its library of functions. For example, find the entry in the function summary for the Ox function sqr(). Here is an edited version of what you actually see:

sqr(const ma);
sqrt(const ma);
    ma
        in: arithmetic type

    Return value
    sqrt returns the square root of the elements of ma, of double or matrix type.

    sqr returns the square of the elements of ma. If the input to sqr is a double or matrix,
    the return type is a double or matrix. If the input is an integer, the return type is integer
    unless the result would overflow in integer computation. In that case the return type is
    double in order to represent the result.

Example

One job you have is to learn how to read this kind of description of a function so that you can use it in your own Ox program to do things you want. Some built-in Ox functions are pretty simple and self-explanatory like print() or sqr(). Others are complex and to use them correctly you have to read the description carefully and absorb what it is saying.

Most functions also have example code that you get by clicking on Example. Again, here is an edited version of what shows up if you do that for the sqr() descriptions:

#include "oxstd.oxh"
main() {
    print( sqr(<2,3>) );
}

produces
       4.0000       9.0000

The real example shows output of sqrt() and compares it to the power operator too. This part of the example shows that if you take the square of a vector it will return the vector of squares. The description above shows that you send any arithmetic type to sqr(), including integers, real numbers, vectors and matrices.

Notice that the description writes sqrt(const ma). The thing you send to sqr() is called an argument just like in math we would say $x$ is the argument of $f(x)$. The name ma is given so that the Ox description can talk about the argument sent to sqr(). It can be very confusing for a new programmer to realize that the name in the description does not affect how you use a built-in function like sqr(). The const tag before ma in the description is also confusing. What it means is that the function is not going to do anything to what you send to it. That is, it is treated as a constant. Why that matters and what it means is not something to explain now. (Arguments to Ox functions are almost always treated as constant). But hopefully it makes sense that writing sqr(x) should not change x itself but simply return (or equal) the square of x.

D. Index

The index of all the functions, symbols, topics, etc. This can be very helpful for finding out information about something about an operator or a keyword.

Exercises

• Look up the built in Ox function max(). Go to the Example of its use. Copy that program to a new .ox file in Oxedit. Run the program until you get the same output as the documentation claims. Then, change the arguments sent to max() and rerun it so that you understand what max() does. Once you feel comfortable, compare what max() does with maxc(), which is a different function. Compare the output of max() and maxc() when both are sent the matrix < 1, 2, 3; 4, 5, 6>.
• Use the Ox Help index to find out what symbol is used for the Kronecker product (a matrix operation not needed in this class, just used as an example for finding help.)