Ox - An Object-Oriented Matrix Language

Chapter contents

Brief description   Quick start Supported data file formats
Packages Which Ox program to use?   Availability
Ox is fast Command line options Using file names in Ox
Extending Ox Debug mode Interactive mode
OxEdit Ox-users discussion list

Brief description

Ox is an object-oriented matrix programming language with a comprehensive mathematical and statistical function library. Matrices can be used directly in expressions, for example to multiply two matrices, or to invert a matrix. The major features of Ox are its speed, extensive library, and well-designed syntax, which leads to programs which are easier to maintain. For a first impression of the matrix and statistical function library see the Function summary. Versions of Ox are available for many platforms.

Ox version

This documentation refers to version 6.00. Please check my work page for the latest news, including known bugs and planned extensions.
See what's new in this version.

Read this first

Conditions, citation and copyright.

Quick start

Ox supported data file formats

Ox can read (and write) the following data files directly into a matrix:

Data files are loaded into a matrix using the loadmat() function. Alternatively, the Database class can be used to load data files with sample period and variable names. The database function is Load.

In addition, there are text and binary functions for reading and writing.

Ox packages

Packages extend the functionality of Ox in various ways. Once installed, they become an integrated part of Ox. Some packages just add a few useful functions, whereas others offer their functionality in an extensive class. A package is also a convenient way for communicating research.

The following packages are currently available for downloading, with up-to-date links and additional packages provided here:

Arfima package
The Arfima package (by Jurgen Doornik and Marius Ooms) has a class for estimation and forecasting of ARFIMA(p,d,q) and ARMA(p,q) models. The available estimation methods are maximum likelihood and nonlinear least squares. The Arfima class derives from the database class to give easy loading of data sets and sample selection. An additional simulation class allows Monte Carlo experimentation of the facilities in the estimation class. The Arfima package can also be used as an OxPack package.
Bootstrap and Simulation Classes
These classes by James Davidson provides the basis for Ox programs for computing and simulating parametric bootstrap tests. The double and fast double bootstraps are implemented. The zip file contains source code, PDF documentation and example programs.
DPD package
DPD is a package for estimation of dynamic panel data models, developed by Manuel Arellano, Steve Bond and Jurgen Doornik. Some static panel estimators are also available. The DPD package can also be used as an OxPack package.
EmmPack
EmmPack (by Pieter-Jelle van der Sluis) extends Ox with C/C++ code (compiled into a DLL) for estimation of univariate stochastic volatility models with the efficient method of moments.
Financial Numerical Recipes
Financial Numerical Recipes is an Ox port of the code written by Bernt Arne Ødegaard for advanced financial calculations. It contains the basic and some advanced algorithms for option pricing, and some algorithms dealing with term structure modeling and pricing of fixed income securities.
G@RCH
G@RCH (by Sébastien Laurent and Jean-Philippe Peters) is an Ox package dedicated to the estimation of ARCH model and many of its extensions (GARCH, IGARCH, FIGARCH, EGARCH, FIEGARCH, APARCH, FIAPARCH and GJR). It can be used via OxPack (with a dialog-oriented interface) or via the traditional way (OxEdit). It allows the use of three distributions (Normal, Student-t and GED), an AR(FI)MA specification in the mean equation and the inclusion of explanatory variables in the mean and variance equations.
GnuDraw
GnuDraw is an Ox package meant for creating GnuPlot graphics from Ox, created by Charles Bos. The call syntax mimicks that of the Ox graphics functions. On Linux, Sun (Solaris) and Windows platforms, GnuPlot can be called automatically from within Ox. The resulting GnuPlot-files are in plain ASCII, and can be adapted to fit final needs. Output of the GnuPlot files can be of many different types. Included is support for EPS (bw and color), GIF and TeX.
Lapack
Lapack is a package for solving linear equations, linear least squares problems, eigenvalue problems, and singular value problems. This is a port to Ox of the main driver files for real and symmetric matrices from lapack, which is in netlib.
Loess Package
Loess is a package for smoothing of multivariate scattered data (LOESS); decompose time series into trend + seasonal + remainder (STL). This is a port to Ox of the port to Ox of the loess and stl code in netlib.
Long Memory Modelling
An Ox package by James Davidson for computing ARFIMA time series models with GARCH disturbances, including FIGARCH and HYGARCH (long memory) variants. The zip file includes source code and PDF documentation. Also an Excel spreadsheet for generating ARIMA/GARCH data series.
Markov switching models.
The MSVAR class (by Hans-Martin Krolzig) is designed for the econometric modelling of univariate and multiple time series subject to shifts in regime. It provides the statistical tools for the maximum likelihood estimation (EM algorithm) and model evaluation of Markov-Switching vector autoregressions as discussed in Krolzig (1997), Markov Switching Vector Autoregressions. Modelling, Statistical Inference and Application to Business Cycle Analysis. (Berlin: Springer Verlag). The MSVAR class derives from the Database class to allow the easy use and exchange with other classes such as PcFiml. A variety of model specifications regarding the number of regimes, regime-dependence versus invariance of parameters etc. provides the necessary flexibility for empirical research and will be of use to econometricians intending to construct and use models of dynamic, non-linear, non-stationary or cointegrated systems. The MSVAR package can also be used as an OxPack package.
PcNaive
PcNaive is an Ox Professional package for designing Monte Carlo experiments of dynamic econometric models by David Hendry and Jurgen Doornik. There is a set of interactive dialogs in which the data generation process (DGP) and model are formulated, and the statistics of interest are selected. PcNaive then generates and runs an Ox program. The output appears in OxMetrics and can include: PcNaive comes with a 200 page book, containing extensive tutorials introducing Monte Carlo analysis, and showing how the program can be used. A separate part discusses how PcNaive can be used in teaching econometrics, starting from the elementary through intermediate and finally advanced econometrics. PcNaive is available from Timberlake Consultants.
Quantile regression
The Ox code accompanying Stephen Portnoys and Roger Koenkers paper The Gaussian Hare and the Laplacian Tortoise: Computability of squared error vs absolute error estimators is available. This can be used to compute quantile regression estimates.
SSFPack
SSFPack is a package for analysing univariate Gaussian and non-Gaussian time series which can be placed in the state space form (SSF). SSFpack provides general filtering, smoothing and simulation smoothing routines. These can be tailored towards particular applications by the user.
See: S.J. Koopman, N. Shephard and J.A. Doornik (1999), `Statistical algorithms for models in state space form using SsfPack 2.2' (with discussion), Econometrics Journal, Vol 2, 107-160.
STR2
An OxPack package by Ivar Pettersen for solving smooth transition regressions. The STR2 class can also be used as an OxPack package.
SVPack
SVPack implements the computations required for the Sangjoon Kim, Neil Shephard, Siddhartha Chib SV paper entitled `Stochastic volatility: likelihood inference and comparison with ARCH models', Review of Economic Studies, 1998. SVPack contains the dynamic link libraries and documentation. Some of the functions use SsfPack 2.0 and ARMS (included in SVPack).

There are also several packages and utilities which are part of the basic release:

ARMA functions.
The Arma package contains a few functions which are useful in ARMA models.
Numerical optimization and differentiation.
The Maximization package can be used to maximize functions of many parameters such as likelihood functions. Examples for binary probit models are in ox/samples/maximize. A quadratic programming solver is available (SolveQP), as well as solver for systems of nonlinear equations (SolveNLE).
Probability functions.
The Probability package adds density, quantile, cumulative density and random number generation of various probability functions.
Econometrics. The PcFiml class
contains code for VARs, cointegration, simultaneous equations estimation, (multivariate) diagnostic tests. Some examples are in ox/samples/pcfiml.
Monte Carlo experiments.
The Simulation class allows for easy implementation of simulation experiments. Some examples are in ox/samples/simula.
QuadPack.
QuadPack is a Fortran library for univariate numerical integration (`quadrature') using adaptive rules. QuadPack is included with the standard Windows release of Ox (the Ox header file and DLL are in the basic release).

Which Ox program to use?

Versions of Ox are currently available the following platforms (check my home page for updated information, and downloading):

platform name dir Console DLL Debug graphics
Windows XP/2000 oxl   yes yes no yes,no
Windows XP/2000 oxli   yes yes yes yes,no
Windows XP/2000 OxRun   yes yes no yes,yes
Windows 9x/NT oxl   yes yes no yes,no
Linux (PC) oxl linux yes yes yes yes,no
Mac (OS-X) oxl osx yes yes yes yes,no
Sun (SunOs) oxl sun yes yes yes yes,no
Dec-Unix oxl dec yes yes yes yes,no
Irix (SGI) oxl sgi yes yes yes yes,no
HP-UX oxl hp yes yes yes yes,no
AIX (IBM) oxl aix yes yes yes yes,no

Console indicates whether the tool is launched from the command line, or using an interactive program. The first yes/no under graphics indicates whether graphs can be created and saved to disk, the second whether graphs can be displayed on screen by Ox.

Send an email to jurgen.doornik@nuffield.ox.ac.uk if you need Ox on other platforms. Most versions allow extending Ox using DLLs; you can also make direct calls to the underlying C code.

Windows

Oxl.exe is the fastest and can handle long file names. Output appears on the console. The simplest way to get the produced results into a file is to redirect the output (e.g. oxl test.ox > t). Oxl can create and save graphs, but cannot display them. Oxl supports extending Ox using DLL libraries. To abort an oxl run, press Ctrl+C.

OxRun.exe is a Windows dialog for running Ox programs. It will make Ox code interact with OxMetrics: text output and graphics appear in OxMetrics windows (where you can edit graphs, e.g. draw lines or add text, move legends, add regression lines, etc.; graphs can also be cut and pasted into other applications). OxRun supports extending Ox using DLL libraries. When you start OxRun from within OxMetrics, it also can be stopped from the OxMetrics modules menu. Otherwise use end task on the task manager.

Linux and other Unixes

Versions are available for most Unix platforms, as shown in here.

Availability of Ox

Please check availability on my work page to download the most recent version of Ox.

The Windows version, Ox Professional, is published by

Users at companies and other commercial users (including users at non-educational institutions, and academics using Ox for consulting) are welcome to download versions of Ox for evaluation purposes. However, when deciding to use Ox seriously, they are expected to purchase the Windows version of Ox and OxMetrics with documentation, regardless of which version they actually do use. More information may be found under citation.

Ox is fast

Ox is faster than most other matrix programming languages. Some benchmarks are available.

OX5PATH

Ox 4.x uses the OX5PATH environment variable if this has been set. Under Windows there is no need to set this variables anymore, because the system will use a default (determined from the location of oxwin.dll), e.g. 

    c:\ox\include;c:\ox

if you installed to c:\ox. Under Unix, this variable must always be set, see readunix.txt. Ox will still read the OX5PATH environment variable, so it can still be used. If you do set it, you must include the default. For example, when Ox is run from the network (X:\apps\ox for example), and you wish to also use packages installed on the local harddisk, you could set: 

    set OX5PATH=X:\apps\ox\include;X:\apps\ox;c:\ox

Ox 3.x used the OX3PATH environment variable, allowing Ox version 3 and 4 installations to exist side by side.

Ox command line options

To run an Ox program from the command-line using oxl: 

    oxl prog.ox

To run an OxGauss program from the command-line using oxl: 

    oxl -g prog.src

The general syntax is 

    oxl [options for oxl] program [options for program]

Arguments before the Ox filename are passed to the compiler, those after to the running program. So in 

    oxl -DMYTEXT1 prog.ox -DMYTEXT2

the string "-DMYTEXT2" is not handled by the compiler, but available to the prog.ox program when using the arglist() function.

General switches

-c
Create an object (.oxo) file, there is no linking or running of the file. An .oxo file is a binary file which holds compiled Ox code. It can be linked in using the -l switch, or using the link pragma.
-d
Run program in debug mode (with -c: inserts debug information in compiled file).
-g
The source code is an OxGauss file
-Dtoken
Define tokens, e.g. -DOPTION1+OPTION2 corresponds to the preprocessor statements
#define OPTION1
#define OPTION2
-lfilelist
Link object file, e.g. -lfile1+file2+file3, which links in the named files (the .oxo extension is assumed). If the file cannot be found as specified, the linker will search along the include path.
-i
Run Ox in interactive mode (at start up the file called ox_init.ox is run automatically).
-ipath
Appends path in front of the current include path. Initially, the include path is that specified in the OX5PATH environment variable (under Windows when {\tt OX5PATH} is not set, the default is obtained from the location of the binary file); use this switch to prepend directories for searching. Use a semicolon to separate directories, e.g. -id:\myox;c:\myox. The include path is used to search for files included in search code and link files.
-w0
Switches off parse warnings. Currently, the parser warns for
isolated ; is empty statement
This refers to expressions such as if (i == 10); where the semicolon terminates the expression. The warning is also issued for ; after for and while statements.
assignment in test expression
This refers to expressions such as if (i = 10) where an assignment is made inside a test expression. The warning is also issued for assignments in for, while, and do while statements.
-x
Clears the current include path. Use this prior to the -i switch if you do not wish to search in the directories specified by the OX5PATH environment variables.

Optimization switches

-od
Switch code optimizations off. By default this is on. Usually, there is no reason to switch it off, other than to to check for speed differences.
-on
Switch line numbering off. Use this switch to prevent the emission of line numbers into the compiled code. This makes error messages less helpful; moreover, the speed improvement is virtually negligable.

Run-time switches

-r-
Do not run code. The code will be compiled and linked. Could be useful to only do a syntax check.
-rc
Sets the matrix cache. By default, the cache stores up to 16 matrices, but only matrices which have fewer than 1000 elements (which corresponds to 8 KBytes). The first number is the number of matrices, the second the size, separated by a colon (no spaces are allowed!), so the default corresponds to -rc16,1000. It seems that the marginal benefit of a larger cache, or caching larger matrices is small. (Note that the default cache consumes 128 Kbytes in a (highly unlikely) worse case.) The cache can be switched off with -rc0,0. Use -rr for a cache report when the program is done.
-rf
Switch FastMath off (saves memory). FastMath significantly speeds up the following operations and functions: X'X, correlation, determinant, invertsym, ols2c, variance. In general, the overhead is a duplicate of the matrix.
-rp
Set number of parallel threads (if supported). The default is the number of cores or processors; use -rp1 to force one thread only (serial code).
-rr
Prints a cache report, e.g. after running bench1.ox: Cache status: size 16 limit 1000 hits 189998 misses 6 flushes 0 skipped 0.
-s
Sets the set symbol table and stack size. The default is -s3000,1000. Setting larger sizes is only required when large programs run out of symbol table or stack space.

Using file names in Ox

If you specify full path names of files in a string constant, you must either use one forward slash, or two backslashes: 

    "./data.mat"


    ".\\data.mat"

Ox will interpret one backslash in a string as an escape sequence (as in the newline character); a single backslash will only work if it does not happen to form an escape sequence. Also note that the Windows and Unix versions of Ox can handle long file names, and that Unix treats file names in a case sensitive manner.

Extending Ox

Ox implements a flexible run-time engine, and can be extended in various ways, for example:

The documentation is in the Ox Appendices.

Using OxRun, Ox can use OxMetrics as a front-end, which holds databases, and receives text and graphical output from Ox.

Debug mode

Most Ox versions have a debug mode, which is entered by using the -d switch (under Windows use oxli intead of oxl). The (debug) prompt indicates the debug mode. Just pressing enter will step through the code.

Local and global variables in .oxo files can only be seen in the debugger if these have been compiled with the -d switch. Note that expressions which are entered from the command line still need to be terminated with a semicolon as usual (including, for example, when just a few spaces are entered).

Type a question mark to see the available commands: 

#break file line - set breakpoint at line of file
#clear file line - clear breakpoint at line of file
#clear all       - clear all breakpoints
#go              - run to next breakpoint
#go file line    - run to line of file
#go line         - run to line of current file
?                - debug command summary (also: help)
??               - show all symbols and current break
?symbol          - show a symbols
#quit            - stop debugging
#step in         - step (in to function) (also: just press return)
#step over       - step (over function)
#step out        - step out of current function
#show            - shows current break
#show calls      - show call stack
#show variable   - as ?variable
#show breaks     - show all breakpoints
#show all        - show all variables
#show full       - show all variables with full value
#trace           - lists all lines executed
#trace off       - switches trace off
!command         - operating system command
expression       - enter an Ox expression, e.g. x[0][0]=1; or print(x);

Interactive mode

Most Ox versions have a interactive mode, which is entered by using the -i switch (under Windows use oxli intead of oxl). The (ox) prompt indicates the interactive mode. You can then enter Ox code from the command line. There are the differences from running a file with code:

Note that expressions still need to be terminated with a semicolon as usual. (including, for example, when just a few spaces are entered).

Type a question mark to see the available commands: 

?              - command summary (also: help)
??             - show all symbols and current break
?symbol        - show a symbols
#new           - clear all code and symbols
#quit          - quit Ox
#show variable - show a named variable with full value (also: ?variable)
#show all      - show all variables
#show full     - show all variables with full value
!command       - operating system command
expression     - enter an expression

OxEdit

OxEdit is a powerful text editor, and a very useful program in its own right. OxEdit has some features which are especially useful when writing Ox programs:

Ox-users discussion list

The ox-users discussion group is an email-based forum to discuss any problems related to Ox programming, and share code and programming solutions. To join the list, send a message to jiscmail@jiscmail.ac.uk. The body of your message should have the following text:

      join ox-users firstname lastname
      --

Instead of firstname and lastname type your own personal names (not your email address). The subject header is ignored. If you change email address, you will have to leave and rejoin the list. The -- stops processing at that point, so is useful if you have a signature. You will receive an email which confirm your registration.

To post a message to the list, send an email to ox-users@jiscmail.ac.uk. Please note that join and leave commands go to jiscmail@jiscmail.ac.uk, whereas messages sent to ox-users@jiscmail.ac.uk are forwarded to all list subscribers.

Past messages are archived, and may be consulted at www.jiscmail.ac.uk/lists/ox-users.html This link also provides general information about the mailbase service.

Ox version 6.00. © JA Doornik This file last changed .