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 8.01. 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.

Check www.doornik.com/download.html for additional code and packages. A few are listed 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 (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 (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 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 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.
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:
  • theoretical analysis of the DGP,
  • live graphical output as the experiment progresses,
  • numerical output of final results.
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 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.
The Professional version of SsfPack is available from Timberlake Consultants.
An OxPack package by Ivar Pettersen for solving smooth transition regressions. The STR2 class can also be used as an OxPack package.
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 Simulator class allows for easy implementation of simulation experiments. Some examples are in ox/samples/simulation.
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 on the following platforms (check www.doornik.com for updated information, and downloading):

platform executable DLLs supported Debug save graphs show graphs
Windows 7/Vista/XP oxl yes no yesno
Windows 7/Vista/XP oxli yes yes yesno
Windows 7/Vista/XP OxRun yes no yesyes
Linux (PC) oxl or oxl64yes yes yesno
Linux (PC) OxRun yes no yesyes
Mac (OS-X) oxl yes yes yesno
Mac (OS-X) OxRun yes no yesyes

Ox can be run in four ways:

  1. from the console (command line) using oxl (bin64/oxl in 64-bit Windows; oxl64 in 64-bit Linux).

    Graphs cannot be displayed.

  2. from OxEdit (the `running person' icon) using oxl

    Graphs cannot be displayed.

  3. from OxMetrics (either using OxRun or the `running person' icon)

    Graphs are shown in OxMetrics. This requires Ox Professional.

  4. from the console (command line) using oxli

    This supports command line debugging and interactive use. Graphs cannot be displayed. This requires Ox Professional.

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.

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.


Ox 7.x uses the OX7PATH 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.


if you installed to c:\ox. Under Unix, this variable must always be set, see readunix.txt. Ox will read the OX7PATH environment variable on all platforms. If you do set it, you must include the default paths. 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 OX7PATH=X:\apps\ox\include;X:\apps\ox;c:\ox

Ox 6.x used the OX6PATH environment variable, allowing Ox version 7 and 6 installations to exist side by side.

Ox command line options

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

    oxl prog.ox

In 64-bit linux the default script is oxl64:

    oxl64 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

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.
Create object (.oxo) file after linking in dependencies (Ox Professional only).
Run program in debug mode (with -c: inserts debug information in compiled file).
Define tokens, e.g. -DOPTION1+OPTION2 corresponds to the preprocessor statements
#define OPTION1
#define OPTION2
The source code is an OxGauss file
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.
Run Ox in interactive mode (at start up the file called ox_init.ox is run automatically).
Appends path in front of the current include path. Initially, the include path is that specified in the OX7PATH environment variable (under Windows when OX7PATH 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.
Set verbosity level (-v1 or -v2). Use -v1 to print information on loaded files and required imports as well as canonical and parallel loops. Use -v2 to also print which include files are opened.
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.
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 OX7PATH environment variables.

Optimization switches

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.
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

Do not run code. The code will be compiled and linked. Could be useful to only do a syntax check.
Set number of parallel threads (Ox Professional only). The default is the number of processor cores; use -rp1 to force one thread only (serial code).
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:



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 Developer's manual.

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 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.20. © JA Doornik This file last changed .