Ox - An Object-Oriented Matrix Language
What is Ox?
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 several platforms.
This documentation refers to version 9.
Please check my
work page for the latest news, including
and planned extensions.
See what's new in this version.
Read this first
Conditions, citation and copyright.
- Running Ox programs
Ox is most conveniently run via OxEdit or OxMetrics. OxEdit uses oxl, and OxMetrics OxRun.
oxl.exe for use in a command prompt (console) window or with OxEdit,
oxrun.exe for full graphical functionality
in conjunction with OxMetrics.
The oxrun and oxl programs have an interactive and debug mode.
Executables are in OxMetrics9\ox.
- Ox Console
oxl.exe for use in a command prompt window or with OxEdit.
- Writing Ox programs
It is strongly recommended to start with
the Introduction to Ox by J.A. Doornik and M. Ooms.
This is supplied as part of the on-line help in
and also available as a printed book.
The accompanying tutorial programs are in the
- Installation notes
Ox supported data file formats
Ox can read (and write) the following data files directly into a matrix:
- .oxdata (OxMetrics 9 data file),
- .in7 (PcGive 7 data file, with data in .bn7 file),
- .xlsx (Excel workbook files),
- .csv (comma separated data file),
- .csv.zip (zipped comma separated data file),
- .mat (ASCII matrix file),
- .dat (ASCII data file with load information),
- .dta (Stata data file).
Data files are loaded into a matrix using the
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
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.
www.doornik.com/download.html for additional code and packages.
The Arfima and DPD packages are installed with Ox and OxMetrics:
- 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.
- 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.
PcNaive is an OxMetrics 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.
- theoretical analysis of the DGP,
- live graphical output as the experiment progresses,
- numerical output of final results.
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),
Vol 2, 107-160.
The Professional version of SsfPack is available from Timberlake Consultants.
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
Windows, macOS (Apple and Intel silicon), and Linux.
All are 64-bit, support parallel computation, debugging and interactive mode.
Ox can be run in four ways:
- from the console (command line) using oxl.
Graphs cannot be displayed.
- from OxEdit (the `running person' icon) using oxl
Graphs cannot be displayed.
- from OxMetrics (either using OxRun or the `running person' icon)
Graphs are shown in OxMetrics.
All 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 OxMetrics, 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 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.
benchmarks are available.
Search path in Ox
Ox is installed with a default search path for code and data files. To see what it is, open a terminal (console)
window, go to the ox folder, and enter oxl -i.
The search path can be amended on the command line, or through the OX9PATH environment variable.
Ox will read the OX9PATH environment variable on all platforms.
If you do set it, you must include the
Ox command line options
The command-line 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.
- 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 imported later.
- Create object (.oxo) file after linking in dependencies.
- Run program in debug mode (with -c: inserts some debug
information in compiled file).
- Define tokens, e.g. -DOPTION1+OPTION2 corresponds
to the preprocessor statements
- #define OPTION1
- #define OPTION2
- 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.
- Shows the current include path.
- Clears the current include path.
- Appends path in front of the current include path.
Use a semicolon to separate directories. The include path
is used to search for files included or imported in code.
- Sends output from -c to file (default is the input file
with .oxo extension).
- Run Ox in query (interactive) mode (at start up the file called
ox_init.ox is run automatically).
- Set verbosity level (-v1 or -v2, default is -v0).
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.
- Treat linker warnings as errors.
- 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.
- Sets optimization level to # (default is 0).
- 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.
The default is the number of processor cores;
use -rp1 to force one thread only (serial code).
- Display generated code.
- Print runtime trace.
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 Linux treats file names
in a case sensitive manner.
Ox implements a flexible run-time engine, and can be extended in various ways,
- Develop an OxPack compatible interactive package when
deriving from the Modelbase class (Windows only).
- Make extensions to Ox in e.g. C/C++ or Fortran, and put that in a DLL;
such functions are then callable from Ox code.
- Use Ox as a mathematics library (e.g. if you are programming in C/C++
but do not want to program in Ox; or to call functions such as Choleski
decomposition or a random number generator in your Ox extension DLL).
- Write an interface wrapper around Ox code (Windows only). The Ox book provides
examples of interface wrappers using Visual C++ and Visual Basic.
- It is possible to make callbacks to Ox from a C/C++ extension to Ox
(e.g. to numerically integrate a function defined in Ox, where the integrator
is in C).
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.
Most Ox versions have a debug mode, which is entered by
using the -d switch.
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
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).
Ox hs an interactive mode, which is entered by
using the -q switch.
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:
- At startup the file ox_init.ox is run.
- Variables assigned to in code entered from the command line need not
be declared explicitly.
Note that expressions still need to be terminated with a semicolon
(including, for example, when just a few spaces are entered).
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:
- Syntax colouring
Three colours are used to distinguish keywords, constants and comment.
This makes the code more readable, and mistakes easier to spot.
- Facility to easily comment in or comment out blocks of text
- Run Ox programs from inside OxEdit
The first time you use OxEdit, execute the Add Ox modules
command on the Modules menu. From then on you can run
your Ox programs without leaving OxEdit:
- Ox - runs the currently active document window
The output will appear in the window called Ox Output.
- OxRun - runs the currently active document window
The output will appear in OxMetrics.
- Ox - interactive - starts an interactive session.
The input/output window is called Session.ox.
- Ox - debug - starts a debug session
for the currently active document window.
The input/output window is called Debug.ox.
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
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
Please note that join and
leave commands go to email@example.com,
whereas messages sent to firstname.lastname@example.org are forwarded
to all list subscribers.
Past messages are archived, and may be consulted at
This link also provides general information about the mailbase service.
Ox version 9.00.
This file last changed .