OxUtils Function Reference

Chapter contents:

acfq acfisq fprintcsv fprinttex
info infoinit loadtab lockfile
unlockfile printcsv printtex PrintMatrix
ReadArg ReadArgUsed savetab setseed
size TrackInit TrackTime TrackRoutine
TrackReport wait

acfq

#include <packages/oxutils/oxutils.h> acfq(const ma, const vlag);
ma
in: arithmetic type, T x n matrix
vlag
in: 1 by q vector, with lags at which to compute the acf
Return value
Returns a q by n matrix with the autocorrelation function of the columns of ma at specified lags.
Description
This function is a generalised version of the standard ox-function acf, convenient especially if not all acf's up to a certain lag are needed, but only a choice.
See also
acfisq, exacfq.ox
[Top]

acfisq

#include <packages/oxutils/oxutils.h> acfisq(const ma, const vw, const vlag);
ma
in: arithmetic type, T x n matrix
vw
in: T x 1 vector, with weights
vlag
in: 1 x q vector, with lags at which to compute the acf
Return value
Returns a q by n matrix with the autocorrelation function of the weighted columns of ma at specified lags.
Description
This function is a generalised version of the standard ox-function acf, convenient especially if not all acf's up to a certain lag are needed, but only a choice.
See also
acfq, exacfq.ox

[Top]

info

#include <packages/oxutils/oxutils.h> info(const it, const nofexps);
it
in: int, number of present iteration (0 for initialization, or M_NAN to use an internal count of the number of times the routine was called)
nofexps
in: int, total number of iterations, or M_NAN if unknown
Return value
1 if screen output was given, 0 otherwise.
Description
This function prints information on the screen concerning elapsed/remaining number of iterations and time. If no separate initialization through infoinit is used, each call to info results in timing information printed on the screen. With infoinit, information is only given if a certain number of iterations or seconds has passed.
See also
infoinit, exinfo.ox
[Top]

infoinit

#include <packages/oxutils/oxutils.h> infoinit(const it, const dTime);
it
in: int, number of iterations between screen outputs, or M_NAN to check only for the time between outputs.
dTime
in: double, minimum time in seconds between screen outputs, or M_NAN to check only for the number of iterations between outputs.
No return value.
Description
This function initializes the info routine, in such a manner that not every call to info results in screen output. If it is called as infoinit(1000, 5); timing information is printed if it has at least been 5 seconds or 1000 iterations since the last time information was given.
See also
info, exinfo.ox
[Top]

infotimer, infotimespan, infobugcheck

(deprecated)

Since version 3.10 of Ox, the bug in the timer routines is resolved, and these routines are not needed anymore.
[Top]

loadtab

#include <packages/oxutils/oxutils.h> loadtab(const sFile, const aasrlab, const aasclab, const amX);
sFile
in: string, filename in which to save, with extension .tab
aasrlab
out: iR array of strings, row labels
aasclab
out: iC array of strings, column labels
amX
out: iRxiC matrix
Return value
Boolean, indicating if the file was succesfully loaded
Description
Loads a table, including the row and column labels, from files with extension .tab (labels) and .fmt (data).
See also
savetab, extable.ox
[Top]

lockfile

#include <packages/oxutils/oxutils.h> lockfile(const sBase); lockfile(const sBase, const iWait);
sBase
in: string, base for a filename
iWait
in: (optional) integer, number of seconds to wait between tries
Return value
Boolean, indicating if the file was succesfully locked
Description
This function can be used to lock a results file, during a simulation. The routine checks for existence of a directory <sBase>_lock. If this directory exists, the routine assumes that the present estimation is already being worked on by a different instance of Ox. If the directory does not exist, it is created, and it may be removed afterwards using unlockfile.

When iWait > 0, the routine successively tries to lock the file, waiting iWait seconds inbetween, until it succeeds.

See also
unlockfile, exlock.ox
[Top]

unlockfile

#include <packages/oxutils/oxutils.h> unlockfile(const sBase);
sBase
in: string, base for a filename
No return value
Description
This function deletes <sBase>_lock, if it exists. It is meant to be used after the computations have finished, to remove the lock on the file indicated by <sBase>.
See also
lockfile, exlock.ox
[Top]

PrintMatrix

(deprecated, use printtex instead)
#include <packages/oxutils/oxutils.h> PrintMatrix(const fh, const s0, const aPrFmt, const acLabs, const arLabs, const mX, const bHLine); PrintMatrix(const fh, const s0, const aPrFmt, const acLabs, const arLabs, const mX, const bHLine, const bHLine2, const bEnvironment);
fh
in: File handle, open for writing (if 0, no writing to file)
s0
in: String, for including in upper left corner of table
aPrFmt
in: Array with printing format, see print(). No '&' needed
acLabs
in: Array with column labels
arLabs
in: Array with row labels
mX
in: Data matrix
iHLine
in: Integer, indicating if table should start and end with one or more lines
iHLine2
in: (Optional) Integer, indicating whether columns labels should be separated with one or more lines from the matrix elements
bEnvironment
in: (Optional) Boolean indicating whether begin & end tabular environment should be printed
No return value.
Description
This function prints a LaTeX matrix to a file or to the screen. It basically works similar to the standard print function, but with LaTeX '&'s included. Also matrices with more than 6 columns can be printed, or with lines longer than 80 characters. Optionally, a LaTeX tabular environment can be printed along, with horizontal lines to distinguish between different parts of the table.

Several generalizations included in the present version of this routine are programmed by Patrick Houweling.

See also
printtex, fprinttex
[Top]

printtex, fprinttex

#include <packages/oxutils/oxutils.h> printtex(const a, ...); fprinttex(const fh, const a, ...);
a
in: any type
...
in: any type
Return value
Returns the number of arguments supplied to the function.
Description
Each argument is printed to stdout or the indicated file, thanks to Phillip Gould, using the formatting of the standard print() statement, adapted for LaTeX output. Note that the inputs can come in any order, of any type.

Missing values in a matrix are not printed, resulting in an empty cell in a table.

See also
exprinttex.ox
[Top]

printcsv, fprintcsv

#include <packages/oxutils/oxutils.h> printcsv(const a, ...); fprintcsv(const fh, const a, ...);
a
in: any type
...
in: any type
Return value
Returns the number of arguments supplied to the function.
Description
Each argument is printed to stdout or the indicated file, using the formatting of the standard print() statement, adapted for csv output. Note that the inputs can come in any order, of any type.

Missing values in a matrix are printed at .NaN.

See also
exprintcsv.ox
[Top]

ReadArg

#include <packages/oxutils/oxutils.h> ReadArg(const aiX, const sX, const iType); ReadArg(const aiX, const sX, const iType, const aSel);
aiX
Pointer to output variable, with value on command line if the string indicator is found, or unchanged otherwise. Boolean values default to FALSE, if the argument is not found.
sX
in: String, command line argument to look for.
iType
in: Integer, indicating type of element to look for;
aSel
in: (Optional) vector or array of allowed selection of input values.
Return value
Integer, indicating number of elements correctly read, or TRUE/FALSE for boolean.
Description
This function checks the command line arguments for the occurrence of the string sX, and if it is found the value of the next argument(s) is/are returned in aiX, or, if iType == 0, aiX is returned with the value of TRUE straight away.

The definition of the types changed in September 2005, switching the types for boolean and real to a more logical order. Now, incorrect use of the type should result in warning messages on screen, but still correct behaviour of the ReadArg function according to the old definition.

Optionally, allowed input can be indicated. If this is the case, then still only a maximum of |iType| arguments are read and tested.

See also
exreadarg.ox, ReadArgUsed
[Top]

ReadArgUsed

#include <packages/oxutils/oxutils.h> ReadArgUsed();
Return value
none
Description
This function gives an overview of the arguments passed to ReadArg, and the values returned.
See also
exreadarg.ox
[Top]

savetab

#include <packages/oxutils/oxutils.h> savetab(const sFile, const asrlab, const asclab, const mX); savetab(const sFile, const asrlab, const asclab, const mX, const sMode);
sFile
in: string, filename in which to save, with extension .tab
asrlab
in: iR array of strings, row labels
aasclab
in: iC array of strings, column labels
mX
in: iRxiC matrix
sMode
in: string (optional), format to use. The sMode argument can be
Return value
Boolean, indicating if the file was succesfully saved
Description
Saves a table, including the row and column labels, to files with extension .tab (labels) and .fmt (data). If the data is appended to an existing table, entries in existing table can be replaced, or columns and/or rows can be added.
See also
loadtab, extable.ox
[Top]

setseed

#include <packages/oxutils/oxutils.h> setseed(iseed);
iseed
int, seed for ranseed (if iseed > 0), else iseed is calculated based on current time
No return value.
Description
This function resets the seed based on the current time, if iseed <= 0. If not, iseed is passed to ranseed.
[Top]

size

#include <packages/oxutils/oxutils.h> size(const ma);
ma
matrix of size nxk
Return value:
2 x 1 matrix with value <n ; k>.
Description
This terribly simple function just reports the size of a matrix, saving the need to call rows(ma) and columns(ma) separately.
[Top]

TrackInit

#include <packages/oxutils/oxutils.h> TrackInit(const asNames);
asNames
in: Array with series of names of routines, or integer. Initializes.
No return value
Description
This routine initialises the tracking routines, by providing an array of names for the routines which are tracked. If instead of an array an integer is given, the timing of the routines is re-initialised, without changing the names. Note that routine is not needed when TrackTime() is called giving the name of the present routine instead of the index.
See also
TrackTime, TrackRoutine, TrackReport, extrack.ox
[Top]

TrackTime

#include <packages/oxutils/oxutils.h> TrackTime(const iInd); TrackTime(const sRoutine);
iInd
in: Integer, index of routine which is entered.
sRoutine
in: String, name of routine which is entered.
Return value
Integer, index of routine which is left.

With TrackTime() the routine which is entered is indicated; the routine returns the routine which was left. The present routine is either indicated using an index number, or more conveniently by its name.

By adding lines calling TrackTime in a program, it is possible to profile the computations.

See also
TrackInit, TrackRoutine, TrackReport, extrack.ox
[Top]

TrackRoutine

#include <packages/oxutils/oxutils.h> TrackRoutine(const bTrack);
bTrack
in: Boolean, indicating if a message is to be printed each time a routine is entered (default=FALSE)
No return value
See also
TrackInit, TrackTime, TrackReport, extrack.ox
[Top]

TrackReport

#include <packages/oxutils/oxutils.h> TrackReport();
No return value
Description
Print a report on the screen with the total and fraction of times spent in each of the routines
See also
TrackInit, TrackTime, TrackRoutine, extrack.ox
[Top]

wait

#include <packages/oxutils/oxutils.h> wait(const dTime);
dTime
in: Double, time in seconds to wait (if >= 0), else wait until return is pressed.
No return value
Description
Wait a prespecified number of seconds, or until return is pressed.
See also
exwait.ox
[Top]


Oxutils version 1.2. Changes made on 11-Febr-2015 by CS Bos