Contents Index Summary Citation Doornik

Ox - An Object-Oriented Matrix Language

Documentation contents

This documentation contains a considerable part of the official Ox reference book.

Chapters:

Ox overview
Ox language tutorial
Ox function summary
Ox function reference
Ox graphics function reference
Ox predefined constants
Ox class reference
Ox syntax
Ox index

Tables:

Escape sequences
Formatting types for scanning
Formatting flags for doubles and integers
Formatting types for printing
Hungarian notation prefixes
Hungarian notation, case sensitivity
Operator precedence
Result from dot operators
Result from relational operators

This documentation is a summary of the Ox book, which has many more examples and more detailed descriptions. The full printed documentation is available as: J.A Doornik (1996), Object-Oriented Matrix Programming using Ox, London: International Thomson Business Press (168-173 High Holborn, London WC1V 7AA, UK). Also see availability.

If you are reading the documentation from your disk, you can connect to the original documentation, which could be more up to date.

Note that links which take you outside the documentation are shown in italics.

Description

Ox is an object oriented matrix language, with a C and C++ like syntax. Ox currently has verions for Windows (PC and Alpha), MS-DOS, Linux, SunOS, SGI and HP-UX. Send me an email at

jurgen.doornik@nuffield.ox.ac.uk

if you need Ox on other platforms. The Windows versions allows extending Ox using DLLs; you can also make direct calls to the underlying C code.

I'm looking forward to receiving an email if you have suggestions for improvements, or or if something isn't working as expected. But please don't ask me to do your programming (the more time I spend on that, the less I have to improve Ox). I will set up a newsgroup in which we can exchange problems and solutions.

Ox version

This documentation refers to version 1.11. Please check my work page for the latest news, including known bugs in the latest and previous versions and planned extensions.

Which Ox version?

Windows

Under Windows there are three options for running your Ox source code:

oxlw.exe: 32-bit Windows command line,
oxl.exe: MS-DOS command line,
oxrun.exe: Windows dialog.

These programs run on the following platforms:

oxlw.exe: Win95/WinNT, in an MS-DOS window,
oxl.exe: Win 3.1/Win95/WinNT, in an MS-DOS window,
oxrun.exe: Win 3.1/Win95/WinNT.

Oxlw.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. oxlw test.ox > t). Oxlw can create and save graphs (but cannot display them). Oxlw can be extended using DLL libraries. To abort an oxlw run, press Ctrl+C.

Oxrun.exe is a Windows dialog for running Ox programs. It will make Ox code interact with GiveWin: text output and graphics appear in GiveWin 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 can be extended using DLL libraries. To abort a program run using oxrun, use end task on the task manager (closing GiveWin or a GiveWin window will stop the output, but not the program).

Oxl.exe is the MS-DOS console version (32-bit, using a DOS-extender). It can display graphs (but not very well, it might be required to switch back to text mode using the mode CO80 command). It does not support long file names nor DLLs. It is somewhat slower than oxlw. The Windows version are to be preferred version, but not available for free.

MS-DOS and MS-DOS consoles

Oxl.exe should work for all of these. Under Windows NT or 95 all the above programs will work.

Linux and other Unixes

Versions are available for most Unix platforms. E.g. under Linux the executable is called oxlinux. The .a files are also supplied to relink Ox with your own code (this is static linking, I haven't sorted out dynamic linking yet).

Availability of Ox

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

The Windows version is available, together with GiveWin, from International Thomson Business Press:

USA: tel. (617) 4234210, fax. (617)4234325;
Rest of the world: tel. +44 1264 342830, fax +44 1264 342761.

Users at companies and other commercial users 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 GiveWin 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 supported data formats

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

.mat (ASCII matrix file),
.dat (ASCII data file with load information),
.in7 (PcGive 7 data file, with data in .bn7 file),
.xls (Excel version 4 spread sheet file),
.wks/.wk1 (Lotus spread sheet file),
.dht (Gauss data file, with data in .dat file),
.fmt (Gauss matrix file).

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

Extending Ox

Under Windows, Ox can be extended. The written documentation provides examples of what you can do:

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

Using OxRun, Ox can use GiveWin as a front-end, which holds databases, and receives text and graphical output from Ox (and also other modules such as PcGive, and soon STAMP and PcFiml).

Ox packages

The following packages are currently available:

Arfima package: The Arfima package 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.
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 is in the basic release). The QuadPack source, together with files for creating the Ox DLL are in quadpkd.zip. This can be downloaded.
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.

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

Numerical optimization. MaxBFGS() can be used to maximize functions of many parameters such as likelihood functions. Examples for binary probit models are in ox/samples/maximize.
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.

Under development are modules for:

Dynamic panel data
Markov switching models

Ox command line options

General switches

Note that arguments before the Ox filename are passed to the compiler, those after to the running program. So in oxlw -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.

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

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

-ipath

Appends path in front of the current include path. Initially, the include path is that specified in the INCLUDE environment variable; use this switch to prepend directories for searching. Use a semicolon to separate directories. 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 INCLUDE environment variables.

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

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

Ox version 1.11. This file last changed 7-Aug-1996.