OxMetrics Help

1.2 Availability

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

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

For TSP go to www.tspintl.com.

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

1.3 Citation

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

1.4 Help

OxMetrics incorporates an extensive cross-referenced help system which offers advice about crucial decisions and can be accessed at any time. This is based on HTML files, and requires that a browser such as Firefox or Internet Explorer is installed. OxMetrics help is available from the Help menu or the Help pane in the workspace. The Help pane lists the contents of all the modules 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.5 Installation

An automatic installation procedure is supplied to install OxMetrics on your system. The default installation folder is C:\Program Files\OxMetrics5. OxMetrics version 5 can exist separately from OxMetrics 4 and GiveWin 2.

OxMetrics and its client modules store their setup and persistent data in the registry. The primary key is HKEY_CURRENT_USERS\Software\OxMetrics5. In addition, some file associations are created for the OxMetrics file types. To update the registry information type the following in a Command Prompt (Console) window, after moving to the OxMetrics5\bin folder:

    oxmetrics.exe -register
    oxmodel.exe -register

Then do the same for OxPack and OxRun if Ox Professional has been installed (in the ox\bin folder).

1.6 Modular structure

OxMetrics maintains the modular structure that was introduced in previous generations of the software. An increasing number of modules interacts with OxMetrics. In that case, the OxMetrics front-end is the `server', while the modules (TSP, STAMP, etc.) are the `clients'. The communication is implemented via DDE.

While it is possible to write clients that interface directly with the server (such as TSP, 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 PcGets, PcGive, G@rch, etc.

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 modules 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\simula\simnor.ox. The OxPack module provides an interactive front-end to several Ox packages.

1.7 Registration

A licensing code is required for the 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.

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

1.8 Upgrades

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

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

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

1.11 Data storage

The primary mode of data storage is a pair of files with extensions .in7 and .bn7. The latter is a binary file containing the actual data, whereas the former holds the information on the contents of the binary file such as variable names, sample periods, frequencies etc. The information file is a human-readable file, the .bn7 is binary and is not human-readable. One artificial data set is supplied in the OxMetrics5\data folder, in the files called data.in7 and data.bn7. The tutorials use this data set. If you want to load your own data, you must begin by inputting the observations; however, follow the relevant tutorial first.

OxMetrics checks for potential overwriting of files and if such is likely to occur, allows selecting another file name. The data options facilitate easy archiving of data. 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, GAUSS and Stata files.

1.12 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 information file might be m1ukq.in7, the associated binary file (of actual data) will be m1ukq.bn7, the OxMetrics Results window storage file could be m1ukq.out, the algebra storage file m1ukq.alg, and batch files m1ukq.fl. A human-readable base data file generally uses the .dat extension. Graph files allow saving in encapsulated PostScript (.eps), PostScript (.ps), Windows metafiles (.wmf), enhanced metafiles (.emf), and OxMetrics graphics (.gwg, for GiveWin graphics), of which the last can be re-read 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.13 Output storage

All text output are shown in the Results window as calculations proceed but are not stored on disk or diskette unless specifically requested. On long runs, a large amount of information can be generated. This can be edited to eliminate redundant records: the Edit menu allows copying, cutting and pasting, deleting, finding and replacing.

The storage facility allows rapid interactive modelling to proceed while any useful results can be printed as a batch job when the computer is otherwise idle.

Since much of the output is graphical, graphs can be easily edited. Graphs can be saved in a variety of formats as noted in the next section.

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

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 of the status bar describes actions of menu items as you use the arrow keys to navigate through menus. This area similarly shows messages that describe the actions of toolbar buttons as you depress them, before releasing them. If after viewing the description of the toolbar button command you wish not to execute the command, then release the mouse button while the pointer is off the toolbar button.

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.
   • For text it is the position in the document of the caret.

     For example: L 113 C 14 indicates that the caret is at Line 113, Column 14. In binary/hexadecimal viewing mode this shows the position of the caret in decimal (the first character of the document is at byte 0). This field will also indicate if the document is read-only, or when the editor is in overwrite mode.

   • For data it is the position in the database of the caret. If there is an active selection, it shows the selected variables.

   • For graphics it is the X coordinate of the mouse cursor.

4. The right area of the status bar also depends on the document type:
   • For text it indicates the document encoding properties:
     • End-of-line marker

       One of: Win, Lnx, Mac for Windows (\r\n), Linux (\n) or Mac (\r).

     • Multilingual file format

       If the file format is different from the default (ASCII) encoding, this is indicated by one of UTF8, UTF16, or UTF32. The can be followed by BE or LE to indicated big-endian or little-endian encoding.

     These properties can be changed using Edit/Text properties.

   • For data it is the value of the observation which has the caret. If there is an active selection, it shows the selected sample.

   • For graphics it is the Y coordinate of the mouse cursor.

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:

Text topics

Column Editing

A column selection can be made with the mouse:

• select with the right-mouse button,
• keep the ALT key down and select with the left-mouse button,

or with the keyboard:

• keep the ALT key down and select with the arrow keys.

A column selection can be dragged and dropped:

• within the same window it will be treated as a column selection
• other windows do not know it is a column selection, and it will be treated as a normal selection.

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:

• yellow: normal editable text
• red: read only
• green: is output or input window of running module.

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:

• mouse:  right click in the margin of the line
• menu:    use View/Set Marker
• find:       The Find dialog can set markers at all lines containing the search text.

To clear a marker:

• mouse:  right click in the margin of the line if that line has a marker
• menu:    use View/Clear Marker
• menu:    use View/Clear All Markers

To go to a marker:

• menu:    use Search/Goto Next Marker or Search/Goto Previous Marker

Markers are not remembered between sessions.

Text view modes

OxMetrics has three viewing modes:

• Text mode

  This is the default viewing mode for a text file.  This mode allows editing of the text.

• Binary Mode

  This is the viewing mode, most useful for binary file.  OxMetrics checks whether a file is binary when loading it.  If so, the viewing mode defaults to this binary mode.  The position indicator on the status bar will show the position of the caret in decimal (the first character of the document is at byte 0).

  In binary mode, there are no text lines.  The screen lines are determined by the window width.  Instead of lines in the margin, the position of the first character is shown in hexadecimal.

• Hexadecimal Mode

  This is the alternative binary viewing mode.  The display consists of two columns, with the text on the right, and the hexadecimal values on the left.  The position indicator on the status bar will show the position of the caret in decimal (the first character of the document is at byte 0).

Dialogs

Aggregate dialog

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

• End-period - the last observation in each period.
• Mid-period - the observation closest to the middle of each period. If there are equidistant before and after observations, the observation before the middle is used.

  weekly:	day that is closest to Wednesday
  monthly:	day between 12th and 18th that is closest to Wednesday
  quarterly:	day between 12th and 18th that is closest to Wednesday in middle month
  4-weekly:	day closest to centre of each 4-week period
  biannual:	day closest to Apr 1/Oct 1
  annual:	day closest to July 1

  
  
• Average - the average for the period; for weekly to monthly this is adjusted for the length-of-month.
• Sum - the sum for the period; for weekly to monthly this is adjusted for the length-of-month.
• Peak - the minimum value in each period.
• Through - the maximum value in each period.

Algebra dialog

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

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

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.

• log
  To take the (natural) logarithm of a variable. Can be applied to multiple variables at once.
• lag
  To take the nth lag of a variable, the default is first lag (negative number gives a lead). OxMetrics appends the lag length as extra characters in a name, preceded by an underscore. E.g. CONS_1 is CONS 1 period lagged. The first observation of CONS_1 will be the missing values.
  You are advised against creating lagged variables in this way, since lags can be created when a model is formulated in PcGive. This function can be applied to multiple variables at once.
• diff
  Takes the nth difference of a variable. The dlog function takes the first difference of the (natural) logarithm. This function can be applied to multiple variables at once.
• dlog
  The diff function takes the nth difference of a variable. The dlog function takes the first difference of the (natural) logarithm. This function can be applied to multiple variables at once.
• dummy
  To create a dummy. A dummy (or intervention) is a variable which consists of 0 and 1s.
• Other
  Displays the full list of algebra functions.

Keyboard

• =
  Prompts for a destination name and executes the algebra code.
• ^ * / + -
  For respectively: power, multiplication, division, addition, subtraction. These (and remaining buttons for 0,1,..) are pasted into the edit field.
• C
  This clears the edit window of the calculator.
• Sub-sample evaluation
  If this box is checked when pressing the evaluation button (or enter), an additional dialog pops up to select a sub-sample over which the algebra code is to be run.

Delete dialog (database)

• Delete entire variable(s)
  to delete the selected variable(s), i.e. entire columns.
• Delete selected observations for all variables (entire rows)
  to delete the selected rows entirely.
• Delete all observations for which this variable has missing values
  to delete entire rows for which the currently selected variable has a missing value.
• Delete all observations for which this variable is non-zero or missing
  to only keep entire rows for which the currently selected variable has a valid non-zero value.
• Remove selected observations, and shift remaining observations up
  to only remove observations from the selected variables (not entire rows, so the sample is unchanged). Vacated observations are set to missing values.
• Clear observations with specified value
  to set the values in the selected block to the new value as specified.

Database description dialog

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

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.

• Default for a normal numeric variable.
• Date for a variable that contains dates and/or times.
• Choice for a variable that has text labels associated to specific values. Excell files wich do not exactly fit the required data format may have such variables. This only properly preserved with correct numerical values in OxMetrics data files (.in7/.bn7).

Delete dialog (graphics)

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

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.

Prperties

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

Graphics dialog

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.

Plot category

• Actual series Transformed time series, for logscale, first differences, growth rates and different scales
• Multiple series
• Scatter plots
• Distribution for estimated densities and histograms, freqquency plots, boxplots, etc. QQ plots, etc.
• Time-series properties for (partial) autocorrelations, periodogram, spectrum, etc.
• Two series by a third for error bars/bands, high-low graphs, etc.
• 3-D (XYZ) plots for surface and contour plots

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

Module

Determines whether the category and model choices are listed for all modules 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

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

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

Preferences dialog

Options dialog

Graphics setup dialog

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