Ox - An Object-Oriented Matrix Language

Chapter contents

What is Ox?	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

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.

Ox version

This documentation refers to version 9. 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

Running Ox programs
Ox is most conveniently run via OxEdit or OxMetrics. OxEdit uses oxl, and OxMetrics OxRun.
- OxMetrics
  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.
More:
- Availability
- Conditions, citation and copyright
- OxEdit
- About non-Windows versions
- Running the first Ox program
- Also see the table of contents
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 PDF format, and also available as a printed book. The accompanying tutorial programs are in the ox\tutorial folder.
More:
- Data files
- Function summary
- Language tutorial
- OxEdit
- Ox-users discussion list
- www.doornik.com latest news, versions, bugs, etc.
- Also see the table of contents
Installation notes
- Windows
- Linux/macOS
- OX9PATH

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

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:

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.

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

Timberlake Consultants

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. Some 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 default paths.

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.

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

-cl

Create object (.oxo) file after linking in dependencies.

-d

Run program in debug mode (with -c: inserts some debug information in compiled 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

Shows the current include path.

-i-

Clears the current include path.

-ipath

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.

-ofile

Sends output from -c to file (default is the input file with .oxo extension).

-q

Run Ox in query (interactive) mode (at start up the file called ox_init.ox is run automatically).

-v#

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.

-W0

Switches off parse warnings.

-Wx

Treat linker warnings as errors.

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.
-O#: Sets optimization level to # (default is 0).

Run-time switches

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

    "./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 Linux 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:

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.

Debug mode

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

Interactive mode

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 as usual. (including, for example, when just a few spaces are entered).

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:

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 using oxl.exe. The output will appear in the window called Ox Output.
- OxRun - runs the currently active document window using OxRun. 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 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.