Ox - An Object-Oriented Matrix Language

Chapter contents

What is Ox?	Running and learning	Supported data file formats
Packages	Platforms and versions	Ox is fast
Graphics	Folder structure	Using file names in Ox
Extending Ox	Debug mode	OxEdit

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.

Platforms and versions

The full desktop version of Ox, called Ox Professional is part of the OxMetrics software that is available from Timberlake Consultants. Timberlake can be found on the internet at timberlake.co.

The Windows/macOS/Linux command-line versions of Ox can be downloaded from: oxlang.dev. This is called Ox Console, and contains OxEdit as the default editor to create and run Ox programs.

The Ox runtime is the same in the professional and console version. So both are 64-bit and support parallel loops.

The Ox folder structure is described below. Detailed information on the installation structure for Windows and macOS/linux is also available.

The browser version of Ox is at oxrun.dev.

Ox version

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

Running and learning Ox

Running Ox programs
Ox is most conveniently run via OxEdit or OxMetrics.
Ox can also be run from oxrun.dev or the command line using the oxl command.
Learning Ox
It is recommended to start with the by J.A. Doornik and M. Ooms. The accompanying tutorial programs are in the ox/samples folder and also in oxrun.dev.

Ox supported data file formats

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

.oxdata (OxMetrics 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),

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

Ox is fast

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

Graphics

Many types of graphs are readily produced in Ox, such as graphs over time of several variables, cross-plots, histograms, correlograms, etc. A graph can be saved in : PDF (.pdf or SVG (.svg). The OxMetrics graphics file (.gwg) is saved as a companion file to allow reloading into OxMetrics. Although view and saving graphs will work on any system supported by Ox, it is only possible to edit the results directly in OxMetrics. The terminal version cannot display graphs.

Folder structure

On Windows the Ox installation is by default in
```
    C:\Program Files\OxMetrics10\ox
```
If a local install is made, installation is to your user folder as recorded in \verb$%USERPROFILE%$:
```
    %USERPROFILE%\AppData\Local\Programs\OxMetrics10
```
On macOS the installation is in:
```
    /Applications/OxMetrics10/ox
```
and on Linux in:
```
  /usr/share/OxMetrics10/ox
```

Ox will by default also search a user folder for additional packages and code.

Under Windows this is
```
    %USERPROFILE%\OxMetrics10\ox
```
While on macOS and Linux:
```
    $HOME/OxMetrics10/ox
```

The layout within the installation folder is:

ox                   -  executables and DLLs
ox/data              -  default data directory 
ox/dev               -  examples on how to extend Ox 
doc/ox               -  documentation (start index.html)

ox/include           -  Ox header files 
ox/lib               -  useful additional source code files 
ox/packages          -  Ox extension packages 
ox/samples           -  Ox samples directory
ox/src               -  Ox code for .oxo files in ox/include 

ox/samples/bench     -  benchmark samples 
ox/samples/classes   -  Line and Angle classes, virtual
ox/samples/database  -  database class examples 
ox/samples/graphics  -  graphics examples 
ox/samples/inout     -  input/output examples
ox/samples/Introduction to Ox  -  Example code for \cite{OxIntro 
ox/samples/lib       -  examples for source code files in ox/lib
ox/samples/maximize  -  function maximization and differentiation 
ox/samples/oxapp     -  application illustrating Ox App dialogs
ox/samples/pcfiml    -  PcFiml examples 
ox/samples/simulation-  Simulator class examples

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 OX10PATH environment variable. Ox will read the OX10PATH 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.

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 .

Using Ox App, 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).