Table of contents
  Part:1 Getting Started with OxMetrics
1 Introduction and Overview
  1.1 Supported platforms
  1.1.1 Folder structure
  1.2 What is new?
  1.3 Availability
  1.4 Citation
  1.5 Help
  1.6 Modular application structure
  1.7 Ox language
  1.8 Registration
  1.9 Upgrades
  1.10 Algebra
  1.11 Batch
  1.12 Data storage
  1.13 Filenames and extensions
  1.14 Sample periods
  1.15 Status bar
  1.16 Tool bars
  1.17 Documentation conventions

OxMetrics book (pdf)

Installation (pdf)

Getting started

Reference
   Algebra Language
   Batch Language
   Data Management
   Graphics
   Statistics
   Text editing

Dialogs
   Aggregate dialog
   Algebra dialog
   Batch dialog
   Calculator dialog
   Delete dialog (database)
   Database description dialog
   Change sample dialog
   Variable description
   Rename variable
   New variable dialog
   Delete dialog (graphics)
   Edit Graph dialog
   Graphics dialog
   Graphics Text (Add Text) dialog
   Model dialog
   Find/Replace (text) dialog
   Text properties dialog
   Preferences dialog
   Options dialog
   Graphics setup dialog

Part:1 Getting Started with OxMetrics

Chapter 1 Introduction and Overview

The OxMetricstm system presents an interactive menu-driven graphics-oriented system for econometric, statistic, and financial analysis. Here we describe the core OxMetrics program, which acts as the `front-end' to a series of integrated software applications. These applications obtain their data from OxMetrics and return output and graphics to it. OxMetrics is the component that allows you to load, edit, and save data; transform that data using the calculator or algebra; create a wide variety of graphs, which can be edited, amended and saved in various formats; provide the data for other applications to analyze; receive their text output, results, and graphics; and lets you edit, amend, and save any or all of these as desired. As such, the OxMetrics front-end can be seen as the desktop for econometric and statistical modelling.

OxMetrics databases can have a fixed frequency, or are `dated', which allows for daily or timed observations. Aggregation facilities are provided, e.g. to convert daily data into monthly. OxMetrics is multilingual, in that names of database variables and text in reports and graphics can be from a wide range of languages, including Chinese and Japanese.

1.1 Supported platforms

The OxMetrics suite of programs runs on the following platforms:

A separate installation document describes the supported platforms in more detail, and shows how to install the software.

OxMetrics 9 operates independently from OxMetrics 8 and previous versions.

1.1.1 Folder structure

The OxMetrics folder structure is as follows: 

OxMetrics9/
    oxmetrics.exe        OxMetrics executable
    oxedit.exe           OxEdit executable
    algebra/             Algebra files
    apps/                OxMetrics application runtime files
    batch/               Batch files
    data/                Data files
    doc/                 Help system
    ox/                  Root of Ox installation: Ox executable files
        doc/             help files for Ox
        include/         Ox header files for Ox code
        lib/             Ox additional code library
        packages/        Ox packages
        samples/         Ox sample code
        ...              
    OxEdit_resources/    Additional resources for OxEdit
    OxMetrics_resources/ Additional resources for OxMetrics

1.2 What is new?

This documentation refers to OxMetrics 9. OxMetrics 8 users will find much that is familar. There are a number of small fixes in this version, which are documented in the online help.

The most important new features are:

1.3 Availability

For availability contact Timberlake Consultants: www.timberlake-consultancy.com or www.timberlake.co.uk.

Consult www.doornik.com or www.oxmetrics.info for pointers to additional information relevant to the current and future versions of OxMetrics. A demonstration version is also available from these web sites.

The Help/Support menu lists some contact addresses for OxMetrics, as well as web sources of information.

1.4 Citation

To facilitate replication and validation of empirical findings, the application used to generate the results should be cited in all reports and publications involving its application.

1.5 Help

In addition to this document, OxMetrics incorporates a cross-referenced help system based on HTML files, These will open in your default browser. OxMetrics help is available from the Help menu or the Help pane in the workspace. The Help pane lists the contents of all the applications that have been installed within OxMetrics. Double clicking on an entry will start your default browser with the Help contents.

Context-dependent help, where available, can be obtained either by pressing the F1 key, or from the Help menu. For example, when writing an Ox program, put the caret on `println', and press F1. OxMetrics will search the html index files for a reference to that word. If there is only one, it will jump there immediately. Otherwise it will offer a list of choices in a dialog.

1.6 Modular application structure

Several applications interact with OxMetrics. In that case, the OxMetrics front-end is the `server', while the applications (G@RCH, PcGive, STAMP, etc.) are the `clients'. The communication is implemented via a local socket.

While it is possible to write clients that interface directly with the server (such as OxPack, and OxRun), it is much easier to develop Ox packages which do this. This requires the use of the Modelbase class, which provides the necessary functionality. Examples of this are Arfima, PcGive, G@RCH, etc.

1.7 Ox language

Ox is a powerful object-oriented matrix programming language with an extensive statistical library. Ox allows you to write your own programs using high level matrix operations, and provides easy facilities to read the same data files as OxMetrics can load. When the preprogrammed options in other applications do not provide a required estimator or test, and you have some basic programming skills, Ox could be used instead. Ox also has preprogrammed classes (a class is a term in object-oriented programming) to facilitate writing Monte Carlo experiments. Ox tends to be faster than other popular matrix languages. Please consult the separate Ox documentation for further information. The OxRun dialog application allows running Ox programs with OxMetrics as the destination of text and graphical output. An interesting example which shows densities and QQ plots while a Monte Carlo experiment is in progress is provided in ox\samples\simulation\simnor.ox. The OxPack application provides an interactive front-end to several Ox packages.

1.8 Registration

A licensing code is required for the OxMetrics software to work properly. This code will have been supplied with your copy, and, under normal circumstances, the licence that is entered during installation is automatically used by the software.

Without code, OxMetrics will enter evaluation mode, allowing use for a short period.

Additional licences can be entered under the Help/Registration menu option (a dialog will automatically appear when OxMetrics is not registered). In the subsequent dialog you can enter your code as well as your name and affiliation. Help/Registration can be also used to check the available licences for using client applications.

1.9 Upgrades

Minor upgrades can be downloaded from www.doornik.com/products.html.

1.10 Algebra

The Algebra language enables you to transform database variables by writing mathematical formulae. Algebra code can be written interactively in the Calculator, or directly in the Algebra editor. Such algebra code can be saved, reloaded, and edited.

The Calculator writes its operations as algebra code to the Results window, from where it can be cut and pasted into the algebra editor. Algebra can also be run directly from the results window, by highlighting the block of algebra code, and then pressing Ctrl+A.

Algebra is a simple vector language, operating on the variables in the database. The operation is applied to each observation in turn, although it is possible to limit access to a subsample. The syntax is described in Chapter ??.

1.11 Batch

OxMetrics is a menu-driven program for ease of use, but some operations can be implemented by entering commands. These commands are parts of simple `computer language' which allow some control of OxMetrics through Batch operations. A Batch program may contain sections of Algebra code.

Batch files allow you to load data, append results, implement algebra and save current PcGive (or STAMP etc.) models. Later, these can be run from the Model/Batch menu or by clicking on the OxMetrics icon on the toolbar. Thus, when a complicated model has been created interactively, it can be saved as a batch file for further editing, or easy recall in a later session. This is also the most convenient way to create a batch file. Like Algebra, batch code can be run directly by highlighting the block of text, and then pressing Ctrl+B.

Once saved to disk, a batch file can also be run directly using File/Open, or even by double clicking on the batch file in the Windows Explorer. Batch files have the .fl extension, which originally stood for Fiml Language. The syntax is described in Chapter ??.

1.12 Data storage

The primary mode of data storage is a file with extension .oxdata. This is a zip file that contains two files. If you rename data.oxdata to data.oxdata.zip, you can see that it contains data.in7 and data.bn7. The latter is a binary file containing the actual data, whereas the former holds the information on the contents of the binary file.

The .bn7/.in7 pairing is still supported, but the oxdata format is more convenient, because it always keeps both together (while taking less space).

Please be careful not to overwrite precious data sets. It is always wise to make regular backups of important files: hard disks may break down, accidental deletion occur or viruses could strike.

OxMetrics can read and write human-readable files and Excel spreadsheet files. OxMetrics can also read comma-separated (.csv) and Stata files.

1.13 Filenames and extensions

All file names have automatic default extensions which need not be input. Say the basic data set is called m1ukq, then the data file might be m1ukq.oxdata, the OxMetrics Results window storage file could be m1ukq.out, the algebra storage file m1ukq.alg, and batch files m1ukq.fl. Graphs can be saved in many formats, including PDF (.pdf), Windows metafiles (.wmf), enhanced metafiles (.emf), Scalable Vector Graphics (.svg). The OxMetrics graphics file (.gwg, for GiveWin graphics) is always saved alongside the other format, and this is the file that is reloaded by OxMetrics for further editing.

Note that by default Windows does not show the file extension in the Explorer window --- only the icon shows what the file type is. If you wish, you can switch the display of file extensions on in the Folder Options entry in the Explorer.

1.14 Sample periods

For data samples, reference is by the absolute date in the form Year(Period) to Year(Period), for example: 1965(1) to 1985(3). Whenever a sample choice has to be made, OxMetrics will show the maximum available and will not allow choices outside that range.

When the data is dated, for example consisting of daily data, the choice is made by entering dates in ISO format of yyyy-mm-dd. The year is always four digits, the month one or two digits (1=January) and the date also one or two digits. For example: 1965-01-31 to 1985-9-5.

Time is written as hh:mm:ss.uuu where hour is two digits on the 24-hour clock (so 22:00 is 10 PM), mm is minutes, the seconds and hundreds are optional. When combined with a date, the ISO standard uses a T to glue the parts together: 1980-1-1T12:05:05.

There is no facility to handle time zones.

1.15 Status bar

The status bar is displayed at the bottom of the OxMetrics window and consists of four areas:

  1. The left area shows current status messages.

  2. If a tool is running, this is indicated on a yellow background in the second panel.

  3. The third panel shows the location of the current document. The content is different for text, data and graphics.

  4. The right area of the status bar also depends on the document type:

1.16 Tool bars

Three tool bars are displayed across the top of OxMetrics, below the menu bar. The tool bars can be customized from a right click on the bar. Customization allows adding or removing icons, and choosing small medium or large icon size (medium is the default).

The Find/Replace tool bar, by default on the second row, replicates most commands of the Find/Replace dialog. The two are actively linked, and the Find/Replace bar is often a convenient way to quickly search for text or execute search/replace actions. The default layout consists of:

Find text
Specify the text to search for. The drop down list box holds previously used search texts. You can use a context menu (right click) to insert text from the clipboard.
Find down
Finds the next occurrence of the search text downwards from the current location of the caret.
Find up
Finds the next occurrence of the search text upwards from the current location of the caret.
Case sensitive
Toggle case sensitive searching on or off (if the button is down, the search is case sensitive).
Whole word
Toggle word matching on or off (if the button is down, the search will only find whole words).
Goto next instance
Finds the next instance of the currently selected text downwards from the current location. The selected text will become the default for subsequent searches.
Goto previous instance
Finds the previous instance of the currently selected text upwards from the current location. The selected text will become the default for subsequent searches.
Show Find dialog
Open the Find dialog.
Show Replace dialog
Open the Find/Replace dialog.
Find in Files
Open a dialog that allows searching for text strings in disk files.

1.17 Documentation conventions

Code, instructions that need to be type, and file names are displayed in Typewriter font. Commands on menus, toolbar buttons, and dialog items (buttons, checkboxes etc.) are shown in the text in a Sans Serif font.

Equations are numbered as (chapter.number); for example, (8.1) refers to equation 8.1, which is the first equation in Chapter 8.

Multiple graphs are numbered from left to right and top to bottom, so b is the top-right graph of four, and c the bottom left.

Text topics

Column Editing

A column selection can be made with the mouse:

or with the keyboard:

A column selection can be dragged and dropped:

Use the Paste as Column command to insert text from the clipboard as a column.  Use the Sort command to sort using a column selection.  It is possible to restrict a find/replace operation to a column selection.

Text margin

The left margin indicates where the cursor is:

Double clicking on the margin toggles line numbering.  In binary and hexadecimal mode, the position of the first character is shown in hexadecimal.  Right clicking in the margin sets or clears a marker.

Text Markers

A marker allows for fast navigation through a document.  A marker is shown as a small blue rectangle in the margin of the line. 

To set a marker:

To clear a marker:

To go to a marker:

Markers are not remembered between sessions.

Text view modes

OxMetrics has three viewing modes:

Dialogs

Aggregate dialog

Creates a new database which holds the aggregated data of the current database.
New name
The name of the new database.
New frequency
The new (lower) frequency. The new database will have a fixed frequency if the frequency is monthly or lower.
Aggregation method

Algebra dialog

Algebra is case-sensitive: CONS and cons refer to different variables. Invalid names may be used in Algebra when enclosed in double quotes.

More information on Algebra syntax and other ways to execute Algebra code can be found here.

When you create a new variable through an assignment operation, it is immediately added to the database, and initialized to missing values. If necessary the database name will be truncated to 64 characters The database in focus can be switched from the drop-down box on the toolbar.

Edit field
The algebra dialog presents a standard edit window, where Algebra commands can be typed, or cut & pasted etc. from another edit window. This window behaves similarly to the Results window (e.g. double-clicking in the margin will toggle line numbering on and off).
Run
Executes the algebra code, and exits the dialog when the run is successful. If an error occurs during processing, the run will be aborted and an error message displayed at the top of the dialog.
Done
Closes the dialog.
Load
Loads a file with algebra code from disk.
Save As
Saves the contents of the algebra edit window to disk.
Recall
Recalls the algebra code from the previous run of the dialog.
Functions
Displays the functions available in Algebra. The selected function will be used in Write Algebra Code.
Database
Shows the database content. Selected variables will be used in Write Algebra Code.
Next to the list of contents are four buttons: to delete variables, to move variables up, to move down, and to rename a variable.
Sub-sample evaluation
If this box is checked when writing algebra code, an additional dialog pops up to select a sub-sample over which the algebra code is to be run.
Write Algebra Code
This can be used to paste the code for the selected function and variable(s) to the edit window. The code may still require some further adjustments.

Batch dialog

OxMetrics supports a batch language for easy repetition or communication of operations. Commands relating to data input output, batch, etc. are handled by OxMetrics. Some modules also support the batch language, extending the OxMetrics commands with their own. An example is PcGive. If a model has been estimated in PcGive, the code will automatically be recorded in the batch window. OxMetrics does not know the PcGive commands, so check the PcGive help system for the PcGive commands.

More information on Batch syntax and other ways to execute Batch code can be found here.

Edit field
The batch dialog presents a standard edit window, where batch commands can be typed, or cut & pasted etc. from another edit window. By default, this window will contain the batch code for the most recently estimated model.
Run
Executes the batch code, and exits the dialog when the run is successful. If an error occurs during processing, the run will be aborted and an error message displayed at the top of the dialog.
Done
Closes the dialog.
Load
Loads a file with batch code from disk.
Save As
Saves the contents of the batch edit window to disk.
Recall
Recalls the batch code from the previous run of the dialog.
Load history
Loads the entire history of batch code for estimated models into the edit window. This can then be edited down to just select a particular model, saved to disk, or copied to the clipboard.
Batch Commands
This is a list with all batch commands which are recognized by OxMetrics. Double clicking on a command will paste it to the editor.

Calculator dialog

The calculator enables easy manipulation of the variables in the database, and is a convenient way to write Algebra expressions.

The aim is to build a valid algebra expression in the expression window (without the assignment and the terminating semi-colon). All successful transformations are logged in the Results window. The box at the top of the dialog shows the current expression.

Data transformation using the calculator can be written directly in the expression field at the top. Then pressing the = button asks for a destination name and runs the algebra code. The code is written to the results window.

The fields below the expression window can help to save typing:

  1. select a variable (or several variables);
  2. press a function button (log, diff, etc.) to paste code;
  3. modify the code if necessary;
  4. press = to evaluate;
  5. provide a destination name.
Suppose that you have highlighted the variable CONS and pressed the log button. Then the expression will read log(CONS). On pressing =, the logarithm of CONS will be computed. The new variable must be named, with LCONS the suggestion in GiveWin. Accept this, and LCONS will be added to the database. If LCONS already exists, you have to confirm overwriting the existing variable. Multiple operations can be conducted, such as A*2*log(CONS)-3*log(INC).

More information on Algebra syntax and other ways to execute Algebra code can be found here.

Edit field
The caclculator presents a standard edit field, where Algebra commands can be typed, or created using the calculator facilities.
Database
Shows the database content. Selected variables will be used in the generated code.
Below the list of contents are four buttons: to delete variables, to move variables up, to move down, and to rename a variable.
Functions
Displays the functions available in Algebra. If a variable is highlighted (e.g. CONS), and you press a function button (e.g. log), the expression log(CONS) will be inserted in the edit field.
Keyboard

Delete dialog (database)

The top of the dialog shows the selected variable (or range of variables) and observations (or observation range). Note that any deletion can be undone again. Deleting observations (entire rows) works as follows. If the database has a fixed frequency, the remaining observations will be moved to fill the gap, and the sample reduced by the number of deleted observations. For a dated database, the remaining observations will not change their dates.

Database description dialog

This is a standard text editor window, where documentation can be typed, cut & pasted etc. to record details about the database in question. The description is only preserved in OxMetrics data files (.in7/.bn7).

Below that is the database summary (the same as can be printed to the Results window from the View menu). Remember that the dialog can be resized to view the full information.

This dialog can also be activated by double-clicking on the top left cell.

Change sample dialog

Frequency and start date
Either specify the fixed data frequency and the sample start (starting year, period) to define the sample characteristics. Or make the database dated by selecting dated and the numbers of days per week. This will create the apporpriate calendar dates (ignoring holidays).

Changing the frequency and start date does not change the number of observations in the database: the end year (period) is automatically adjusted.

Sample Size
The database sample period can be extended at the start and/or end by adding any desired number of observations in this dialog. It is also possible to delete observations to reduce the database.

The data for the extended period(s) are set to missing value.

Variable description/Rename variable/New variable dialog

Double clicking on the name of a variable in the database produces the dialog for editing the current description. The variable can be renamed in this field.
Variable Description
The description is only preserved in OxMetrics data files (.in7/.bn7). A description which applies to the database as a whole is available in the database description
Variable Type
The type of variable is relevant to create a dated database.

Delete dialog (graphics)

Select an area in the left column, and a graphics object on the right-hand side. Then press the Delete button to delete, and Done to close the dialog. Any deletion can be undone again.

Note that text, legends, axes and individual symbols (lines, rectangles, etc.) can be selected with the mouse, and then deleted by pressing the delete key.

Edit Graph dialog

Almost anything can be changed in a graph through the Edit Graph dialog or by the context menu from a right-click on the graph. Alternatively, double-click to select and edit the selected object.

More detailed information of the various aspects can be found here.

Graph layout
This section holds the settings that apply to the entire graph. This includes the area layout, whether to use boxes, which PostScript mode to use, etc.
Area 1
The remaining entries on the left-hand side are the areas in the graph. Select an area to edit properties specific to that area. This includes colours and line styles for each series that is plotted, the style of axes, legends, histograms, error bars, etc.

If there is more than one area, some properties can be copied from the current area to all the other areas.

Properties
On the left is the full list of properties that can be modified.

Graphics dialog

This dialog is used to specify the variables to be use in the selected type of graph. After creating a graph, a wide range of options are available to change most aspects.
Database
On the right is the list of all the variables in the database, any selection of which can be marked for graphing by moving them to the Selection list.

Note that the active database is listed in the title (as well as the active area if the plot is to be added to an area). The database can be changed from the drop-down box on the toolbar, or simply by activating another database.

<<
Moves selected database variables to the Selection list.
>>
Removes selected variables from the Selection listbox.
Selection
Lists the variables which have been selected for graphing.
Actual series
plots the actual values of the selection in one graph and closes the dialog.
Actual series (seperately)
plots the actual values of the selection in separate graphs and closes the dialog.
Scatter plot (YX)
creates a scatter plot of the selection and closes the dialog. The last variable in the selection is the X variable, and if n variables have been selected, n-1 cross-plots will be made.
All plot types
Moves to the Graphics Wizard to select a type from a wide range of graph types.
The Graphics dialog for all plot types has three fields:
Plot category
Sub category
provides a visual way to select a sub category.
All sub categories and properties
provides access to all properties for the selected category.

Graphics Text (Add Text) dialog

Text can be typed anywhere in a graphics window. Typing any keyboard character brings up this dialog where the desired text can be entered. Text can be also added from the Edit menu using Add Text.

Text entered immediately above the graph will have the title property, which means that it is moved with the area when the area is moved.

Mathematical and other formatting can be incorporated through LaTeX style commands.

Previously typed text can be revised by double clicking on it, an then selecting it in the properties editor; moved by grabbing with the mouse or deleted by clicking then pressing the Del key.

The following text properties can be changed after double clicking: actual text, type (floating, title, axis label), size, rotation, and location.

Model dialog

The modelling dialog gives access to all the modelling features of the OxMetrics applications. Which applications are available depends on your installation. For example, it may only include STAMP and PcGive, or also PcGets and G@rch.
Model app
Determines whether the category and model choices are listed for all applications together, or only for the selected module.
Category
Lists the available model categories, including models for time-series data, for cross-section data, for panel data, etc.
Model class
Lists the available models for the current category.
running icon
This icon moves when the module is running. To interrupt in that case, click on it (a dialog will ask for confirmation; the subsequent response may not be immediate).
Formulate
to start model formulation. This will normally follow through to estimation.
Estimate
To re-estimate the model.
Test
To access the test menu for the active module.
Progress
To access the progress dialog.
Options
To access the options dialog for the active module.

Find/Replace (text) dialog

Allows text to be found or replaced in the current document, current selection or all open documents.

C style means that escape characters in the find or replace text are recognized, e.g. \n for a new line and \t for a tab.

Text properties dialog

Allows the removal of tab characters, change of end-of-line mode, and the multilingual format.

Preferences dialog

For persistent options that affect the way OxMetrics operates.

Options dialog

For persistent options that affect the way OxMetrics operates.

Graphics setup dialog

This dialog determines the default settings for OxMetrics graphs. These settings are persistent, and will also affect the way graphs from Ox code disappear. Ox code can make modifications to the persistent settings using SetDraw (which is why DrawAdjust is preferred: that applies to the current graph only).

The settings can be reset to the initial default, or saved as a batch file that can be run later.

Index
Algebra
Availability
Batch
Data storage
Database
Date Representation
File names
Folder structure
Help
Ox
OxMetrics data file (.oxdata))
OxMetrics data file (.in7/.bn7)
Register OxMetrics
Sample period
Status bar
Time Representation
Tool bars
Upgrades