---

Ox Function Reference

Chapter contents:

Tables:

Formatting types for scanning

Formatting flags for doubles and integers

Formatting types for printing

acf

acf(const ma, const ilag);

ma

in: arithmetic type, T x n matrix

ilag

in: int, the highest lag

Return value

Returns a (ilag+1) by n matrix with the autocorrelation function of the columns of ma up to lag ilag. Returns 0 if ilag <= 0. If any variance is <= 1e-20, then the corresponding autocorrelations are set to 0.

See also

DrawCorrelogram, pacf

Example

acos

acos(const ma);

ma

in: arithmetic type

Return value

Returns the arccosine of ma, of double or matrix type.

See also

asin, atan, cos, cosh, sin, sinh, tan, tanh

Example

aggregatec,aggregater

aggregatec(const ma, const istep);
aggregater(const ma, const istep);

ma

in: m x n matrix A

istep

in: int, size of groups, s

Return value

The aggregatec function returns a ceil(m/s) by n where each group of s observations in every column is replaced by the sum. The aggregater function returns a m by ceil(n/s) where each group of s observations in every row is replaced by the sum.

See also

thinc, thinr

Example

any

any(const ma);

ma

in: arithmetic type

Return value

Returns TRUE if any element of ma is TRUE, of integer type.

See also

equality expressions

Example

arglist

arglist();

Return value

Returns an array of strings holding the command line arguments passed to the Ox program. The first entry is the name of the program that was specified on the command line.

Example

See also

va_arglist (for variable number of function arguments)

array

array(const ma);

ma

in: any type

Return value

Casts the argument to an array, unless it already is an array.

Example

asin

asin(const ma);

ma

in: arithmetic type

Return value

Returns the arcsine of ma, of double or matrix type.

See also

acos, atan, cos, cosh, sin, sinh, tan, tanh

atan,atan2

atan(const ma);
atan2(const my, const mx);

ma

in: arithmetic type

Return value

atan returns the arctangent of ma, of double or matrix type, between -pi/2 and pi/2.

atan2 returns the arctangent of my ./ mx, between -pi and pi.

See also

acos, asin, cos, cosh, sin, sinh, tan, tanh

bessel

bessel(const mx, const type, const n01);
bessel(const mx, const type, const nu);

mx

in: x, arithmetic type

type

in: character, type of Bessel function: 'J', 'Y', 'I', 'K', or string: "IE", "KE", for scaled Bessel functions

n01

in: 0 or 1: order of Bessel function

nu

in: double, fractional order of Bessel function

Return value

Returns an m x n matrix, when mx is an m x n matrix, or a double when x is scalar. The following are available: J₀(x), Y₀(x), J₁(x), Y₁(x), and the modified Bessel functions I₀(x), K₀(x), I₁(x), K₁(x). If the specified order is not 0 or 1, the fractional Bessel functions are computed. The modified Bessel functions are also available in scaled form: e^-xI_n(x) and e^xK_n(x). The accuracy is to about 15 digits.

betafunc

betafunc(const mx, const ma, const mb);

mx

in: x, arithmetic type

ma

in: a, arithmetic type

mb

in: b, arithmetic type

Return value

Returns the incomplete beta integral B_x(a,b). Returns 0 if a <= 0, b <= 0 or x <= 0. The accuracy is to about 10 digits. The return type is derived as follows:

• m x n matrix, when mx is an m x n matrix, and ma,mb are scalar;
• m x n matrix, when mx is a scalar, and ma,mb are m x n matrices;
• m x n matrix, when mx is an m x n matrix, and ma,mb are m x n matrices;
• double, when mx and ma,mb are scalar.

See also

gammafunc, probf, probf, tailf

binand, bincomp, binor, binpop, binvec, binxor

binand(const ia, const ib, ...);
bincomp(const ia);
binor(const ia, const ib, ...);
binpop(const ia, ...);
binvec(const ia);
binxor(const ia, const ib, ...);

ia

in: int or matrix of integers

ib

in: int or matrix of integers

...

in: optional additional arguments, if present, all arguments must be integers

Return value

binand returns the result from and-ing all arguments (the & operator in C,C++ ).

bincomp returns the binary (bit-wise) complement of the argument (the ~ operator in C/C++).

binor returns the result from or-ing all arguments (the | operator in C,C++ ).

binpop returns the number of non-zero bits (popcount, Hamming weight) in the argument. If there is more than one argument, these are xored together first (the Hamming distance).

binvec returns the nx32 vector of zeros and ones, with each row the bitwise representation of the integer(s) in the argument. The least significant bit comes first, so 6 is returned as 0,1,1 followed by 29 zeros.

binxor returns the result from xor-ing all arguments (the ^ operator in C,C++ ).

Example

binomial

binomial(const n, const k);

n, k

in: arithmetic type

Return value

Returns the binomial function at the rounded value of each element, of double or matrix type. For negative integers, the function returns .NaN.

The binomial coefficient is: n!/((n-k)!k!). When max(n-k,k) >= 50 the computation uses the loggamma function: binomial(n,k)=exp(loggamma(n+1)-loggamma(n-k+1)-loggamma(k+1)).

See also

factorial, gammafact, loggamma

cabs, cdiv, cerf, cexp, clog, cmul, csqrt

cabs(const ma);
cdiv(const ma, const mb);
cerf(const ma);
cexp(const ma);
clog(const ma);
cmul(const ma, const mb);
csqrt(const ma);

ma, mb

in: 2 x n matrix (first row is real part, second row imaginary part), or 1 x n matrix (real part only)

Return value

cabs returns a 1 x n matrix with the absolute value of the vector of complex numbers.

cdiv returns a 2 x n matrix with the result of the division of the two vectors of complex numbers. If both ma and mb have no imaginary part, the return value will be 1 x n.

cmul returns a 2 x n matrix with the result of the multiplication of the two vectors of complex numbers. If both ma and mb have no imaginary part, the return value will be 1 x n.

csqrt returns a 2 x n matrix with the square root of the vector of complex numbers.

cerf returns a 2 x n matrix with the complex error function of the vector of complex numbers.

cexp returns a 2 x n matrix with the exponential of the vector of complex numbers.

clog returns a 2 x n matrix with the logarithm of the vector of complex numbers. This is the principal branch, i.e. the imaginary part is between -pi and pi.

Example

ceil

ceil(const ma);

ma

in: arithmetic type

Return value

Returns the ceiling of each element of ma, of double or matrix type. The ceiling is the smallest integer larger than or equal to the argument

See also

floor, round, trunc

Example

chdir

chdir(const s);

s

in: new directory

Return value

Returns 1 if the directory was changed successfully, 1 otherwise.

Windows specific: if the string starts with a drive letter followed by a semicolon, the current drive is also changed. For example, use chdir("c:") to change to the C drive.

See also

getcwd, getfiles, systemcall

Example

choleski

choleski(const ma);

ma

in: symmetric, positive definite m x m matrix A

Return value

Returns the Choleski decomposition P of a symmetric positive definite matrix A: A=PP'; P is lower triangular (has zero's above the diagonal). Returns 0 if the decomposition failed.

See also

decldl, invertsym, solvelu

Example

classname

classname(const obj);

obj

in: object of a class

Return value

Returns a string with the class name of the object (or 0 if the argument is not an object).

See also

isclass

clone

clone(const obj);
clone(const obj, const iDeep=1);

obj

in: object of a class

iDeep

in: int, 1 (deep copy, the default), 0: shallow copy

Return value

Returns a clone of the object.

The clone is an exact copy that must be removed with a call to delete. When writing a = new Database(); b = a; both a and b refer to the same object, and only one can be deleted. Writing a = new Database(); b = clone(a); both a and b refer different objects, which happen to hold the same values. Both a and b should be deleted when done. The default is to make a deep copy: all members that are objects are also cloned (and members of members, etc.). A shallow copy only clones the members that are objects, but not members of members.

columns

columns(const ma);

ma

in: any type

Return value

Returns an integer value with the number of columns in the argument ma:

• m x n matrix: n;
• string: number of characters in the string;
• array: number of elements in the array;
• file: number of columns in the file; (only if opened with f format, see fopen);
• other: 0.

See also

rows, sizeof

Example

constant

constant(const dval, const r, const c);
constant(const dval, const ma);

dval

in: double

r

in: int

c

in: int

ma

in: matrix

Return value

constant(dval,r,c) returns an r by c matrix filled with dval.

constant(dval,ma) returns a matrix of the same dimension as ma, filled with dval.

See also

ones, unit, zeros

Example

correlation

correlation(const ma);

ma

in: T x n matrix A

Return value

Returns a n x n matrix holding the correlation matrix of ma. If any variance is <= 1e-20, then the corresponding row and column of the correlation matrix are set to 0.

See also

acf, meanc, meanr, standardize, varc, varr, variance

Example

cos,cosh

cos(const ma);
cosh(const ma);

ma

in: arithmetic type

Return value

cos returns the cosine of ma, of double or matrix type. cosh returns the cosine hyperbolicus of ma, of double or matrix type.

See also

acos, asin, atan, cosh, sin, sinh, tan, tanh

countc

countc(const ma, const va);

ma

in: m x n matrix

va

in: 1 x q or q x 1 matrix

Return value

Returns a matrix r which counts of the number of elements in each column of ma which is between the corresponding values in va:

r[0][0] = # elements in column 0 of ma <= va[0]

r[1][0] = # elements in column 0 of ma > va[0] and <= va[1]

r[2][0] = # elements in column 0 of ma > va[1] and <= va[2]

r[q][0] = # elements in column 0 of ma > va[q-1]

...

r[0][1] = # elements in column 1 of ma <= va[0]

r[1][1] = # elements in column 1 of ma > va[0] and <= va[1]

r[2][1] = # elements in column 1 of ma > va[1] and <= va[2]

r[q][1] = # elements in column 1 of ma > va[q-1]

...

If ma is m x n, and va is 1 x q (or q x 1) the returned matrix is (q+1) x n (any remaining columns of va are ignored). If the values in va are not ordered, the return value is filled with missing values.

See also

countr

Example

countr

countr(const ma, const va);

ma

in: m x n matrix

va

in: 1 x q or q x 1 matrix

Return value

Returns a matrix r which counts of the number of elements in each row of ma which is between the corresponding values in va:

r[0][0] = # elements in row 0 of ma <= va[0]

r[0][1] = # elements in row 0 of ma > va[0] and <= va[1]

r[0][2] = # elements in row 0 of ma > va[1] and <= va[2]

r[0][q] = # elements in row 0 of ma > va[q-1]

...

r[1][0] = # elements in row 1 of ma <= va[0]

r[1][1] = # elements in row 1 of ma > va[0] and <= va[1]

r[1][2] = # elements in row 1 of ma > va[1] and <= va[2]

r[1][q] = # elements in row 1 of ma > va[q-1]

...

If ma is m x n, and va is 1 x q (or q x 1) the returned matrix is m x (q+1) (any remaining columns of va are ignored). If the values in va are not ordered, the return value is filled with missing values.

See also

countc

Example

cumprod

cumprod(const mfac);
cumprod(const mfac, const cp);
cumprod(const mfac, const cp, const mz);

mfac

in: T x n or 1 x n matrix of multiplication factors S

cp

in: int, autoregressive order p (optional argument; default is 1)

mz

in: T x n or 1 x n matrix of known components Z (optional argument; default is 0)

Return value

Returns a T x n matrix with the cumulated autoregressive product. The first p rows of the return value will be identical to the sum of those in mz and mfac; the recursion will be applied from the pth term onward. If either mz or mfac is 1> x n, the same values are used for every t.

cumprod computes:

a_t = z_t + s_t for t = 0,...,p-1,

a_t = z_t + s_t (a_t-1 x ... x a_t-p) for t = p,...,T-1.

Example

See also

armagen, cumsum cumulate

cumsum

cumsum(const mx, const vp);
cumsum(const mx, const vp, const mstart);

mx

in: T x n matrix of known components X

vp

in: 1 x p or n x p or T x p matrix with AR coefficients \phi₁, \phi₂, ..., \phi_p

mstart

in: s x n matrix of starting values S, s >= p; (optional argument; default is mx)

Return value

Returns a T x n matrix with the cumulated autoregressive sum. The first p rows of the return value will be identical to those of mstart; the recursion will be applied from the pth term onward.

If vp is 1 x p, the same coefficients are applied to each column.

If vp is n x p, each row will have coefficients specific to each column of the recursive series.

Finally, if vp is T x p, the same coefficients are applied to each column, but the coefficients are specific to each row (time-varying coefficients).

cumsum computes:

a_t = s_t for t = 0,...,p-1,

a_t = x_t + \phi₁ a_t-1 ... + \phi_p a_t-p for t = p,...,T-1.

When \phi is T by p (and p is not equal to the number of columns in X), the AR coefficients are time-varying:

a_t = s_t for t = 0,...,p-1,

a_t = x_t + \phi_t,1 a_t-1 ... + \phi_t,p a_t-p for t = p,...,T-1.

See also

armagen, cumprod cumulate

Example

cumulate

cumulate(const ma);
cumulate(const ma, const m1, ...);
cumulate(const ma, const am);

ma

in: T x n matrix A

m1

in: n x n matrix, coefficients of first lags (optional argument)

...

in: n x n matrix, coefficients of lags 2, ...

am

in: array of length k with n x n coefficient matrices

Return value

Returns a T x n matrix. The simplest version returns a matrix which holds the cumulated (integrated) columns of ma. The second form cumulates (integrates) the (vector) autoregressive process with current values ma using the specified coefficient matrices. The function has a variable number of arguments, and the number of arguments determines the autoregressive order (minimum 2 arguments, which is an AR(1) process). Note that cumulate(m) corresponds to cumulate(m, unit( columns(m) )).

See also

arma0, cumsum, lag0

Example

date

date();

Return value

A string holding the current date.

See also

time

Example

dawson

dawson(const ma);

ma

in: arithmetic type

Return value

Returns the Dawson integral of each element of ma, of double or matrix type.

See also

erf

dayofcalendar, dayofeaster, dayofmonth, dayofweek

dayofcalendar();
dayofcalendar(const index);
dayofcalendar(const year, const month, const day);
dayofeaster(const year);
dayofmonth(const year, const month, const dayofweek, const nth);
dayofweek(const index);
dayofweek(const year, const month, const day);

index

in: arithmetic type, calendar index of a certain date, as returned by dayofcalendar(year, month, day)

year

in: arithmetic type, year

month

in: arithmetic type, January=1, etc.

day

in: arithmetic type, day (1,...,31)

dayofweek

in: arithmetic type, day of week (Sunday = 1, Monday = 2, ...)

nth

in: arithmetic type, >0: n-th from start of month, <0: n-th from end of month

Return value

The dayofcalendar function without any arguments returns the calendar index (Julian day number) of today.

The dayofcalendar function with three arguments returns the calendar index of the specified date (this is the Julian day number, see below). If all arguments are an integer, the return value will be an integer.

The dayofcalendar function with one argument takes a calendar index (or vector of indices), as returned by dayofcalendar(year, month, day) as argument, returning a nx3 matrix with the triplet year, month, day in each row (n is the number of elements in the input).

The dayofeaster function returns the calendar index of Easter.

The dayofmonth function returns the calendar index of the n-th day of the week in the specified month (n-th from last for a negative value). For example dayofmonth(2005, 5, 2, -1) returns the index of the last Monday in May 2005.

The dayofweek function with three arguments returns the day of the week (Sunday = 1, Monday = 2, ...). If all arguments are an integer, the return value will be an integer.

The dayofweek function with one argument takes a calendar index (r vector of) as argument, returning the day of the week (Sunday = 1, Monday = 2, ...).

Description

The calendar index is the Julian day number, and the dayof... functions convert from or to the index. For example, Julian day 2453402 corresponds to 2005-01-31. An optional fractional part specifies the fraction of the day: 2453402.75 corresponds to 2005-01-01T18:00. If the day number is zero, it is interpreted as a time only, so 0.75 is just 18:00 (6 PM).

Use dayofcalendar(year, month, day) - dayofcalendar(year, 1, 1) + 1 to compute the day in the year. Similarly, the function can be used to compute the number of days between two dates.

The "%C" print format is available to print a calendar index.

See also

print, timeofday, timing

Example

decldl

decldl(const ma, const aml, const amd);

ma

in: symmetric, positive definite m x m matrix A

aml

in: address of variable

out: m x m lower diagonal matrix L, LDL'=A

amd

in: address of variable

out: 1 x m matrix with reciprocals of D

Return value

Returns the result of the Choleski decomposition:

• 1: no error;
• 0: the Choleski decomposition failed: the matrix is negative definite or the matrix is (numerically) singular.

See also

choleski, decldlband, solveldl

Example

decldlband

decldlband(const ma, const aml, const amd);

ma

in: p x m vector specifying the A^b matrix

aml

in: address of variable

out: holds p x m lower diagonal matrix L

amd

in: address of variable

out: 1 x m matrix with reciprocals of D

Return value

Returns the result of the Choleski decomposition:

• 1: no error;
• 0: the Choleski decomposition failed: the matrix is negative definite or the matrix is (numerically) singular.

For example, if the original matrix has bandwidth p=2, it is stored in ma as:

     0      0 [0][2] ... [m-3][m-1]
     0 [0][1] [1][2] ... [m-2][m-1]
[0][0] [1][1] [2][2] ... [m-1][m-1]

See also

diagonal solveldlband, solvetoeplitz

Example

declu

declu(const ma, const aml, const amu, const amp);

ma

in: square m x m matrix A

aml

in: address of variable

out: m x m lower diagonal matrix L, has ones on the diagonal

amu

in: address of variable

out: m x m upper diagonal matrix U, LU=PA

amp

in: address of variable

out: 2 x m matrix, the first row holds the permutation matrix P', A=(LU)[P'][], the second row holds the interchange permutations

Return value

Returns the result of the LU decomposition:

• 1: no error;
• 2: the decomposition could be unreliable;
• 0: the LU decomposition failed: the matrix is (numerically) singular.

See also

determinant, invert, solvelu

Example

decmgs

decmgs(const ma, const amq, const amr);

ma

in: m x n matrix A

amq

in: address of variable

out: n x m orthogonal matrix Q

amr

in: address of variable

out: n x n upper diagonal matrix R

Return value

Computes the thin QR decomposition, A=QR using the modified Gram-Schmidt (MGS) orthogonalization, returning:

• 0: out of memory,
• 1: success,
• 2: bad scaling, rescaling is advised,
• -1: (A'A) is (numerically) singular,
• -2: combines 2 and -1: bad scaling and singularity.

The inversion epsilon, eps_inv, is set by the inverteps function.

If a column of A causes singularity, the corresponding column of Q is set to zero.

See also

decqr, inverteps, olsc, solvelu

Example

decqr

decqr(const ma, const amht, const amr, const amp);

ma

in: m x n matrix A

amht

in: address of variable

out: n x m lower diagonal matrix H', which holds householder vectors

amr

in: address of variable

out: n x n upper diagonal matrix R₁

amp

in: address of variable (use 0 as argument to avoid pivoting; note that pivoting is recommended)

out: 2 x n matrix, the first row holds the permutation matrix P', the second row holds the interchange permutations

Return value

Computes the QR decomposition with pivoting, AP=QR, returning:

• 0: out of memory,
• 1: success,
• 2: ratio of diagonal elements of A'A is large, rescaling is advised (ratio of smallest to largest <= eps_inv),
• -1: (A'A) is (numerically) singular: |R_ii| <= eps_inv max_j sqrt[(A'A)_jj],
• -2: combines 2 and -1.

The inversion epsilon, eps_inv, is set by the inverteps function.

See also

decqrmul, decqrupdate, inverteps, olsc, solvelu

Example

decqrmul

decqrmul(const mht, const my);
decqrmul(const mht);

mht

in: n x m lower diagonal matrix H', which holds householder vectors from previous QR decomposition

my

in: m x p matrix Y

Return value

Returns Q'Y, where Q derives from a previous QR decomposition. To compute QY, use reversec to reverse the elements in each column of mht.
The version with one argument returns the m x m matrix Q'.

See also

decqr, olsc, solvelu

Example

decqrupdate

decqrupdate(const amq, const amr, const i1, const i2);
decqrupdate(const amq, const amr, const i1);

amq

in: address of m x n matrix Q

out: updated matrix Q

my

in: address of m x n matrix R

out: updated matrix R

No return value

Description

Updates the QR decomposition using Givens rotations.

The version with only the i1 argument zeroes the subdiagonal elements from subdiagonal i1 to the diagonal (i.e. subdiagonal 0). It is assumed that subdiagonals below i1 are already zero.

The version with both the i1 and i2 arguments zeroes the subdiagonal from column i1 to column i2. It is assumed that columns before i1 are already zero below the diagonal.

Both
decqrupdate(&q, &a, 0, columns(r)); and
decqrupdate(&q, &a, rows(r));
compute a complete QR decomposition (like decqr, although decqr does not compute Q explicitly). However, the decqrupdate function is primarily intended to update a QR factorization.

See also

decqr, decqrmul

Example

decschur,decschurgen

decschur(const ma, const amval, const ams, ...);
decschur(const ma, const amval, const ams, const amv,
    const dselmin, const dselmax);
decschurgen(const ma, const mb, const amalpha, const ambeta,
    const ams, const amt, ...);
decschurgen(const ma, const mb, const amalpha, const ambeta,
    const ams, const amt, const amvl, const amvr,
	const dselmin, const dselmax);

ma

in: m x m matrix A

amval

in: address of variable

out: complex eigenvalues: 2 x m matrix with eigenvalues of A, first row is real part, second row imaginary part. Only real eigenvalues: 1 x m matrix. The eigenvalues are not ordered, unless dselmin and dselmax are specified.

ams

in: address of variable

out: upper quasi-triangular Schur form S, such that A=VSV'

amv

in: (optional) address of variable

out: orthogonal matrix V with Schur vectors, such that A=VSV'

dselmin

in: (optional) double, minimum absolute eigenvalue to move forward

dselmax

in: (optional) double, maximum absolute eigenvalue to move forward

ma

in: m x m matrix A

mb

in: m x m matrix B for generalized Schur decomposition

amalpha

in: address of variable

out: complex eigenvalues: 2 x m matrix with alpha of A, first row is real part, second row imaginary part. Only real alphas: 1 x m matrix.
The generalized eigenvalues are (alphar[j]+i*alphai[j])/beta[j], j=0,...,m-1 The generalized eigenvalues are not ordered, unless dselmin and dselmax are specified.

ambeta

in: address of variable

out: 1 x m matrix with beta

ams

in: address of variable

out: upper quasi-triangular Schur form S, such that A=V_l*S*V_r'

amt

in: address of variable

out: upper triangular Schur form T, such that B=V_l*T*V_r'

amvl

in: (optional) address of variable

out: orthogonal matrix V_l with left Schur vectors

amvr

in: (optional) address of variable

out: orthogonal matrix V_r with right Schur vectors

dselmin

in: (optional) double, minimum absolute generalized eigenvalue to move forward

dselmax

in: (optional) double, maximum absolute generalized eigenvalue to move forward

Return value

Returns the result of the Schur decomposition:

• 0: no error;
• 1: maximum no of iterations reached;
• -1: ill conditioning prevented ordering;
• -2: rounding errors in ordering affected complex eigenvalues.

Description

The decschur function computes the Schur decomposition of a real matrix A=VSV', where V is orthogonal, and S upper quasi-triangular, with 2 x 2 blocks on the diagonal corresponding to complex eigenvalues. The decschurgen function computes the generalized Schur decomposition of two real matrices A,B: A=V_lSV_r', B=V_lTV_r', where V is orthogonal, and S upper quasi-triangular, with 2 x 2 blocks on the diagonal corresponding to complex eigenvalues. T is an upper-triangular matrix. The generalized eigenvalues are alpha[i]/beta[i], where alpha may be complex and beta is real. The Schur decomposition can be ordered if the dselmin and dselmax arguments are specified. Any (generalized) eigenvalues that are ≥ dselmin and ≤ dselmax in absolute value, are selected for reordering, and moved to the top left. Note the reordering may affect complex eigenvalue when the matrices are ill-conditioned. Sources: these routines are based on LAPACK 3.0.

Example

decsvd

decsvd(const ma);
decsvd(const ma, const amu, const amw);
decsvd(const ma, const amu, const amw, const amv);

ma

in: m x n matrix A

amu

in: address of variable

out: m x n matrix U, U'U = I_n

amw

in: address of variable

out: 1 x n matrix with diagonal of W

amv

in: (optional argument) address of variable

out: if not 0 on input: n x n matrix V, UWV'=A, V'V = I_n

Return value

The version with one argument: returns a 1 x min(m,n) matrix with the singular values, or 0 if the decomposition failed.

The version with two or more arguments returns an integer indicating the result of the singular value decomposition:

• 0: no error;
• k: if the k-th singular value (with index k-1) failed after 50 iterations.

Note that the singular values are in decreasing order, with the columns of U,V sorted accordingly.

See also multiplicative expressions

Example

deletec, deleter, deleteifc, deleteifr

deletec(const ma);
deletec(const ma, const mval);
deleter(const ma);
deleter(const ma, const mval);
deleteifc(const ma, const mifc);
deleteifr(const ma, const mifr);

ma

in: m x n matrix to delete from

mval

in: p x q matrix with values to use for deletion

mifc

in: p x n boolean matrix specifying columns to delete

mifr

in: m x q boolean matrix specifying rows to delete

Return value

The deletec function with one argument returns an m x s matrix, deleting columns from ma which have a missing value (NaN: not a number).

The deleter function with one argument returns an s x n matrix, deleting rows from ma which have a missing value (NaN).

The remaining forms do not have special treatment of missing values.

The deletec function with two arguments returns an m x s matrix, deleting the columns from ma which have at least one element equal to an element in the matrix mval.

The deleter function with two arguments returns an s x n matrix, deleting the rows from ma which have at least one element equal to an element in the matrix mval.

The deleteif functions can be used to delete rows or columns based on a logical expression: all rows (columns) wich have a zero in the corresponding row (column) are kept, the remainder is dropped.

The deleteifc function returns an m x s matrix, deleting only those columns from ma which have at least one non-zero element in the corresponding column of mifc.

The deleteifr function returns an s x n matrix, deleting only those rows from ma which have at least one non-zero element in the corresponding row of mifr.

All functions return an empty matrix if the result is empty.

See also

dropc, dropr, selectc, selectr, selectrc, selectifc, selectifr, isdotnan, vecindex

Example

denschi,densf,densn,denst

denschi(const ma, const df);
densf(const ma, const df1, const df2);
densn(const ma);
denst(const ma, const df);

ma

in: arithmetic type

df

in: arithmetic type, degrees of freedom

df1

in: arithmetic type, degrees of freedom in the numerator

df2

in: arithmetic type, degrees of freedom in the denominator

Return value

Returns the requested density at ma (the returned densities are between positive):

• denschi: chi²(df) density,
• densf: F(df1, df2) density,
• densn: standard normal density,
• denst: student-t(df) density.

The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and the rest is scalar;
• m x n matrix, when ma is a scalar, and the rest are m x n matrices;
• m x n matrix, when ma is an m x n matrix, and the rest are m x n matrices;
• double, when ma is scalar, and the rest is also scalar.

See also

prob..., quan..., tail..., Probability package

determinant

determinant(const ma);

ma

in: m x m matrix

Return value

Returns the determinant of ma. Return type is double.

See also

declu, invert, logdet

Example

dfft

dfft(const ma);
dfft(const ma, const inverse);

ma

in: 2 x n matrix (first row is real part, second row imaginary part), or 1 x n matrix (real part only, imaginary part is zero)

inverse

in: (optional argument), int: 1 (do an inverse discrete FT) or 2 (do an inverse real DFT)

Return value

If only one argument is used, the return value is a 2 x n matrix which holds the discrete Fourier transform.

If inverse equals 1, the return value is a 2 x n matrix which holds the inverse discrete Fourier transform.

If inverse equals 2, the return value is a 1 x n matrix which holds the real inverse discrete Fourier transform.

See also

fft1d

Example

diag

diag(const ma);

ma

in: double, or m x 1 or 1 x m matrix

Return value

Returns a m x m matrix with ma on the diagonal.

See also

diagonal, diagonalize, toeplitz

Example

diagcat

diagcat(const ma, const mb);

ma

in: m x n matrix

mb

in: p x q matrix

...

in: optional additional matrices

Return value

Returns a matrix with all arguments concatenated along the diagonal; the off-diagonal blocks are set to zero. With two arguments, the returned matrix is m+p x n+q.

Example

diagonal

diagonal(const ma);
diagonal(const ma, const upr);
diagonal(const ma, const upr, const lwr);

ma

in: arithmetic type

upr

in: (optional argument), int: upper bandwidth (>= 0, default 0)

lwr

in: (optional argument), int: lower bandwidth (<= 0, default 0)

Return value

The version with one argument returns a matrix with the diagonal from the specified matrix in the first row. Note that the diagonal is returned as a row vector, not a column. If ma is m x n, the returned matrix is 1 by min(m,n) (exception: 0 x 0 when m=0); if ma is scalar, the returned matrix is 1 x 1.

The general version returns the banded form, extracting upr upper diagonals and lwr lower diagonals. For example, if upr=2 and lwr=-1 and the returned matrix is:

     0      0 [0][2] ... 
     0 [0][1] [1][2] ... 
[0][0] [1][1] [2][2] ... 	(diagonal)
[1][0] [2][1] [3][2] ... 

See also

decldlband, diag, diagonalize, setdiagonal

Example

diagonalize

diagonalize(const ma);

ma

in: arithmetic type

Return value

Returns a matrix with the diagonal of ma on its diagonal, and zeros in off-diagonal elements. If ma is m x n, the returned matrix is m x n; if ma is scalar, the returned matrix is 1 x 1.

See also

diag, diagonal, setdiagonal

Example

diff,diff0

diff(const ma);
diff(const ma, const ilag);
diff(const ma, const ilag, const dmisval);
diff0(const ma);
diff0(const ma, const ilag);
diff0(const ma, const ilag, const dmisval);

ma

in: T x n matrix A

ilag

in: int, lag length of difference (1 for first difference; this is the default)

dmisval

in: (optional argument) double, value to set missing observations to (default is 0 for diff0, .NaN for diff)

Return value

The diff function returns a T x n matrix with the ilagth difference of the specified matrix, whereby missing values are replaced by .NaN. The diff0 function is the same, but using zero for the missing value. The result has the same dimensions as ma.

See also

lag, lag0 diffpow,

Example

discretize

discretize(const vx, const dmin, const dmax, const icount,
    const ioption);

vx

in: 1 x T data vector

dmin

in: double, first point a

dmax

in: double, last point b

icount

in: int, number of points M

ioption

in: int, 0: raw discretization; 1: weighted discretization

Return value

Returns a 1 x M matrix with the discretized data.

See also

countc

Example

double

double(const ma);

ma

in: arithmetic type

Return value

Casts the argument to a double:

• integer argument: converted to a double;
• double argument: unchanged;
• matrix argument: element 0,0;
• string argument: packs up to 8 characters into a double, see explicit type conversion;
• other argument types: error.

See also

int, matrix, string explicit type conversion

dropc,dropr

dropc(const ma, const midxc);
dropr(const ma, const midxr);
dropr(const aa, const midxr);

ma

in: m x n matrix to delete from

aa

in: m array to delete from

midxc

in: p x q matrix specifying the index of columns to delete

midxr

in: p x q matrix specifying the index of rows to delete

Return value

The dropc function with returns a copy of the input matrix with the specified columns deleted.

The dropr function with returns a copy of the input matrix with the specified rows deleted; dropr also works for arrays.

All functions return an empty matrix if all rows or columns are deleted (or empty array for arrays).

See also

deleteifc, deleteifr, insertc, insertr, vecindex

Example

eigen,eigensym

eigen(const ma, const amval);
eigen(const ma, const amval, const amvec);
eigensym(const ms, const amsval);
eigensym(const ms, const amsval, const amsvec);

ma

in: m x m matrix A

amval

in: address of variable

out: complex eigenvalues: 2 x m matrix with eigenvalues of A, first row is real part, second row imaginary part. Only real eigenvalues: 1 x m matrix. The eigenvalues are not sorted.

amvec

in: address of variable

out: complex eigenvectors: 2m x m matrix with eigenvectors of A in columns (real values are in first m rows). Only real eigenvalues: m x m matrix with eigenvectors in columns.

ms

in: symmetric m x m matrix A^s

amsval

in: address of variable

out: 1 x m matrix with eigenvalues of A^s, sorted in decreasing order

amsvec

in: address of variable

out: m x m matrix with eigenvectors of A^s in columns

Return value

Solves the eigenproblem Ax = \lambda x, returning the result of the eigenvalue decomposition:

• 0: no error;
• 1: maximum no of iterations (50) reached.

Example

eigensymgen

eigensymgen(const ma, const mb, const amval, const amvec);

ma

in: m x m symmetric matrix A

mb

in: m x m symmetric positive definite matrix B

amval

in: address of variable

out: 1 x m matrix with (generalized) eigenvalues of A, sorted in decreasing order

amvec

in: address of variable

out: n x m matrix with (generalized) eigenvectors of A in columns

Return value

Solves the general eigenproblem Ax = \lambda Bx. returning the result of the eigenvalue decomposition:

• 0: no error;
• 1: maximum no of iterations (50) reached.
• -1: Choleski decomposition failed.

See also

decldl, eigensym

Example

eprint

eprint(const a, ...);

a

in: any type

...

in: any type

Return value

Returns the number of arguments supplied to the function. Prints to stderr. See print for a further description.

See also

fprint, print, sprint

Example

erf

erf(const ma);

ma

in: arithmetic type

Return value

Returns the error function of each element of ma, of double or matrix type.

See also

cexp

exclusion

exclusion(const ma, const mb);
exclusion(const ma, const mb, const amidx);

ma, mb

in: matrix

amidx

in: address of variable

out: 2 x c matrix, first row is index of exclusion in ma, second row is index in mb.

Return value

Returns the sorted unique elements of ma which are not in mb as a row vector. Returns an empty matrix if the result is empty. Missing values are skipped.

See also

intersection, unique, union

Example

exit

exit(const iexit);

iexit

in: integer, exit code

No return value.

Exits the Ox run-time environment. The specified exit code is ignored.

exp

exp(const ma);

ma

in: arithmetic type

Return value

Returns the exponent of each element of ma, of double or matrix type.

See also

log

Example

expint

expint(const ma);

ma

in: arithmetic type

Return value

Returns the exponent integral Ei of each element of ma, of double or matrix type. Note that E₁(x)=-Ei(-x).

fabs

fabs(const ma);

ma

in: int, double, matrix

Return value

Returns the absolute value of each element of ma, of the same type as ma.

Example

factorial

factorial(const ma);

ma

in: arithmetic type

Return value

Returns the factorial function at the rounded value of each element of ma, of double or matrix type. Returns +.NaN for any argument which is negative. Note that n!=n*(n-1)...2*1, and n! equals gammafact(n+1).

Often a ratio of factorials functions is needed. Note that the factorial can overflow rapidly. However, often there is an offsetting factor in the denominator/numerator, and it is advised to use the loggamma or binomial function instead in that case.

See also

binomial, gammafact, loggamma

fclose

fclose(const file);

file

in: an open file which is to be closed
(use fclose("l") to close the log file).

Return value

Returns 0.

See also

fopen

Example

feof,fflush

feof(const file);
fflush(const file);

file

in: an open file

Return value

feof checks for end of file; returns 0 if not at end of file, a non-zero value otherwise. fflush flushes the file buffer.

fft,fft1d

fft(const ma);
fft(const ma, const inverse);
fft1d(const ma);
fft1d(const ma, const inverse);

ma

in: 2 x n matrix (first row is real part, second row imaginary part), or 1 x n matrix (real part only, imaginary part is zero)

inverse

in: (optional argument), int: 1 (do an inverse FFT) or 2 (do an inverse real FFT)

Return value

If only one argument is used, the return value is a 2 x s matrix which holds the Fourier transform.

If inverse equals 1, the return value is a 2 x s matrix which holds the inverse Fourier transform.

If inverse equals 2, the return value is a 1 x s matrix which holds the real inverse Fourier transform.

For fft1d, s=n, so it returns the same number of columns as the input. But fft pads with zeros until a power of two is reached: s is the smallest power of 2 which is >= n.

Description

Performs an (inverse) fast Fourier transform. The code is based on FFTE 2.0 by Daisuke Takahashi. FFTE provides Discrete Fourier Transforms of sequences of length (2^p)*(3^q)*(5^r), which has been extended to work for all sample size. If the input has no complex part, in the absence of the inverse argument, a real FFT is performed.

Example

find

find(const where, const what);
find(const where, const what, const mode);

where

in: object to search in

what

in: what to search for

mode

in: (optional argument), string controlling search method: "i", "ir", "r" or nothing

Return value

where	what	return type
m-vector	c-vector	c x 1 matrix with indices of occurrence (or -1 if not found)
array of strings	array of c string	c x 1 matrix with indices of occurrence (or -1 if not found)
array of strings	string	int: index of occurrence of string what, or -1 if not found
string	string	int: index of occurrence of substring what, or -1 if not found
string	r x c matrix with character values	rc x 1 matrix with indices of occurrence (-1 if not found)
string	character	int: index of occurrence of character what, or -1 if not found

Description

When strings are involved, this function is identical to the strfind family, except that the return value is a column vector. The default is case-sensitive forward search; use mode "i" to ignore case, "r" to search in reverse order, "ir" to do both.

When the two arguments are a vector (either column or row), find returns the location of the what elements in where (the numbers have to match exactly, or both be a missing value). The return value is a row vector with the same number of elements as what. Only the first instance will be located if there are multiple occurences in where; use vecindex to find all occurences of a certain value.

See also

strfind, replace, vecindex

Example

findsample

findsample(const mdata, const vvarsel, const vlagsel,
    const it1, const it2, const imode, const ait1, const ait2);

mdata

in: T x n data matrix

vvarsel

in: p-dimensional selection vector with indices in mdata or empty matrix to use whole mdata as selection

vlagsel

in: p-dimensional selection vector lag lengths for selection or empty matrix to use no lags

it1

in: int: first observation index to consider (>= 0)

it2

in: int: last observation index to consider (can use -1 for T-1)

mode

in: int: sample selection mode
SAM_ALLVALID : all observations must be valid
SAM_ENDSVALID : only the first and last observation must be wholly valid (there may be missing observations in between)
SAM_ANYVALID : the first and last observation must have some valid data

ait1

in: address of variable

out: the first observation index

ait2

in: address of variable

out: the last observation index

Return value The number of observation in the selected sample.

Example

floor

floor(const ma);

ma

in: arithmetic type

Return value

Returns the floor of each element of ma, of double or matrix type. The floor is the largest integer less than or equal to the argument.

See also

ceil, round, trunc

Example

fmod

fmod(const ma, const mb);

ma

in: arithmetic type

mb

in: arithmetic type

Return value

Returns the floating point remainder of ma / mb. The sign of the result is that of ma. The return type is double if both ma and mb are int or double. If ma is a matrix, the return type is a matrix of the same size, holding the floating point remainders ma[i][j] / mb[i][j], etc. The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and mb is scalar;
• m x n matrix, when ma is a scalar, and mb is an m x n matrix;
• m x n matrix, when ma is an m x n matrix, and mb is an m x n matrix;
• double, when ma and mb are scalar.

See also

imod

Example

fopen

fopen(const filename);
fopen(const filename, const smode);

filename

in: name of file to open

smode

in: text with open mode

Return value

Returns the opened file if successful, otherwise the value 0. Use isfile to test if fopen was successful.

Description

Opens a file. The first form, without the smode argument opens a file for reading (equivalent to using "r"). The smode argument can be:

• "w" open for writing (the default when omitting this argument);
• "a" open for appending;
• "r" open for reading;
• "r+" open for reading and writing (update);
• "l" open a log file for writing (use "la" to append).

In addition, the following letters can be used in the smode argument:

b

Opens the file in binary mode (Windows only). Binary leaves a \r\n as \r\n, whereas non-binary translates \n to \r\n on input (and vice versa on output). On Windows systems, it is customary to open text files without the b, and binary files (when using fread and fwrite) with the b.

F

Use for a v96 .fmt file, which stores a matrix. Reading and writing can then be done by blocks of rows. When writing, the file must be explicitly closed with fclose.

Also used for a v96 .dat file, which stores variable names and binary data. When writing, the first fwrite should be an array of strings, which also determines the number of variables. When reading, use fread(file, &as, 's') to read the variable names; this sets the file pointer to the first row.

f

Same as 'F', but only for extended v89 .fmt files.

e

Forces the file reading and writing (using fread and fwrite) to be in little-endian mode. This allows Ox on Unix (not Linux on Intel) to handle files which use the MS-DOS byte ordering (which is little-endian).

E

Forces the file reading and writing (using fread and fwrite) to be in big-endian mode. This allows Ox on Windows/MS-DOS to handle files which use the Unix (not Linux on Intel) byte ordering (which is big-endian).

v

Print a message if opening the file failed.

V

Print a message if opening the file failed, then generate a run-time error.

When using "r+", it is necessary to use fseek or fflush when switching from reading to writing.

To send the output from all print and println statements to a file (in addition to the screen), use fopen(filename, "l").

Finally, it is possible to read from a zip file, by specifying the archive name, followed by two slashes, followed by the name in the archive. For example

file = fopen("mydata/data.zip//data/data.in7"); Opens the file data/data.in7 in the zip archive mydata/data.zip. Ox will search for data.zip in the standard way. It is not possible to write to a zip file.

See also

fclose, fflush, fprint, fread, fscan, fseek, fwrite, isfile

Example

format

format(const sfmt);

sfmt

in: string: new default format for double or int

int: new line length for matrix printing

No return value.

Description

Use this function to specify the default format for double and int types. The function automatically recognizes whether the format string is for int or double (otherwise it is ignored). The specified double format will also be used for printing matrices. See under the print function for a complete description of the formatting strings. Use an integer argument to set the line length for matrix printing (default is 1024, the minimum is 72). The default format strings are:

• int: "%d"
• double: "%g"
• matrix: each element "%#13.5g", 6 elements on a line (depending on the line length). This format will always leave at least one space between numbers.

See also

fprint, print, sprint

fprint,fprintln

fprint(const file, const a, ...);
fprintln(const file, const a, ...);

file

in: file which is open for writing

a

in: any type

...

in: any type

Return value

Returns the number of arguments supplied to the function. Prints to the specified file, see print for a further description. fprintln is as fprint but ensures the next output will be on a new line.

Example

fread

fread(const file, const am);
fread(const file, const am, const type);
fread(const file, const am, const type, const r);
fread(const file, const am, const type, const r,const c);

file

in: file which is open for writing, or string with filename

am

in: address, address for storing read item

type

in: (optional argument), type of object to read, see below

r

in: (optional argument), number of rows to read; default is 1 if argument is omitted

c

in: (optional argument), number of columns to read; default is 1 if argument is omitted, unless file is opened with f, in which case the number of columns is read from the file

Return value

Returns an integer:

-1 nothing read, because end-of-file was reached;

0 nothing read, unknown error;

>0 object read, return value is size which was actually read:

• type: 'i', 'd', reads: integer, returns: 1;
• type: 'e', 'f', reads: double, returns: 1 (r and c omitted, or both equal to 1);
• type: 'e', 'f', reads: matrix, returns: r x c;
• type: 'e', 'f', reads: matrix, returns: r (number of complete rows read; file opened with f in format);
• type: 'c', reads: integer, returns: 1 (r=1: just one byte read);
• type: 'c', reads: string, returns: r (r>1: r bytes read).
• type: 's', reads: string, returns string length; unlike 'c' this ignores the r argument and reads up to (and including) the first null character or the end of file; \r\n is translated to \n
• type: '4', reads: float, returns: 1 (r and c omitted, or both equal to 1);
• type: '4', reads: matrix of floats, returns: r x c;

When reading a matrix, for example as fread(file,&x,'f',r,c), the size of x will always be r by c. If less than rc elements could be read, the matrix is padded with zeros. If no elements could be read at all, because the end of the file was reached, the return value is -1.

The '4' format reads 4-byte real values (`float'), these are not written by Ox, but may be needed to read externally created files.

The 's' type reads a string up to (and including) the first null character or the end of file.

Description

Reads binary data from the specified file. The byte ordering is the platform specific ordering, unless the f format was used (also see fopen and fwrite).

See also

fclose, fopen, fscan, fseek, fwrite

Example

fremove

fremove(const filename);

filename

in: name of file to remove

Return value

Returns 1 if the file was removed successfully, 0 otherwise.

fscan

fscan(const file, const a, ...);

file

in: file which is open for writing

a

in: any type

...

in: any type

Return value

Returns the number of arguments successfully scanned and assigned, or -1 when the end of the file was encountered and nothing was read.

Description

Reads text from a file. The arguments are a list of scanning strings and the addresses of variables. A scanning string consists of text, optionally with a format specifier which starts with a % symbol. The string is truncated after the format. Any text which precedes the format, is skipped in the file. A space character will skip any white space in the file. If the scanning string holds a format (and assignment is not suppressed in the format), the string must be followed by the address of a variable. The format specification is similar to that for the scanf function of the C language:

%[* or #][width]type

The width argument specifies the width of the input field. A * suppresses assignment. A # can only be used with m and M.

---

Table std.1: Formatting types for scanning

double type:
e,f,g       field is scanned as a double value,
le,lf,lg    field is scanned as a double value,
C           field is scanned as a calendar double value

integer type:
d           signed decimal notation,
i           signed decimal notation,
o           unsigned octal notation,
x           unsigned hexadecimal notation,
u           unsigned decimal notation,
c           (no width) scan a single character (i.e. one byte),

string type:
s           scan a string up to the next white space,
z           scan a whole line,
c           (width > 1) scan a number of characters,

matrix type:
m,M         scan a matrix row by row,

token type:
t           scan a token, returning the value,
T           scan a token, returning a triplet.

any type:
v		    scan an Ox constant.

---

Notes:

• The "%m" and "%M" formats can be used to read a matrix from a file. They first read the number of rows and columns, and then the matrix row by row; this corresponds to the format used by loadmat. No dimensions are read by "%#m" and "%#M", in that case the scanning string has to be followed by two integers indicating the number of rows and columns to be read. For fscan the two integers can be -1. In that case all numbers are read and returned as a column vector.
• When scanning a string with "%s", "%z" or "%t", the maximum string length which can be read is 16384. The sprintbuffer function can be used to enlarge the buffer size.
• The "%z" format reads a whole line up to \n, the \n (and \r) are removed from the return value. If the line in the file is too long, the remainder is skipped.
• The "%t" and "%T" formats can be used to read a token, using a simplified syntax that is similar to Ox code. Five types of tokens are distinguished:

  SCAN_EOF

  End of the file or text.

  SCAN_IDENTIFIER

  An identifier.

  SCAN_LITERAL

  A literal integer, double or string.

  SCAN_SYMBOL

  A symbol.

  SCAN_SPACE

  White space.

  The "%t" version returns the value that was read, while "%T" returns an array with three elements: the value, the actual text that was read and the token type (SCAN_...).

  Note that a negative number is read as two tokens: a minus symbol and the value. Space is returned as a token. To skip leading spaces use " %t" and " %T". Note that fscan may reach the end (i.e. return -1) before it gets to process the token, so the return value of fscan should be taken into account.

  The token format can be useful when a simple parser is required, or to read strings that are not delimited by white space. An example using sscan is given below.

• The "%C" format is used to scan a date/time field written in ISO format: yyyy-mm-dd, hh:mm::ss.hh, or yyyy-mm-ddThh:mm::ss.hh. Examples are 1999-03-31, 13:10 (a 24-hour clock is used, seconds and hundreds are optional) and 1999-3-31T13:10. Years with week number are also recognised, e.g. 1976-W3 returns the calendar index for the Monday of week 3 in 1976. (Week 1 is the first week that contains the first Thursday; or equivalently, the week that contains 4 January.)
• The "%v" format reads a variable that has been written in the format of an Ox constant. It is especially useful to read a variable that consist of a derived types, such as an array or a class object, but also for a matrix. When scanning a class object, the variable must already have the type of that class (using new), because the scan functions cannot create the object themselves. An example is given in ox/samples/inout/percent_v.ox and under the print function.

See also

fprint, fread, print, scan, sscan

Example

fseek

fseek(const file);
fseek(const file, const type);
fseek(const file, const type, const r);

file

in: file which is open for writing

type

in: (optional argument), type of object use in seeking, see below

r

in: (optional argument), number of rows to move; default is 1 if argument is omitted

Return value

The first form, with only the file argument, tells the current position in the file as an offset from that start of the file (as the standard C function ftell). The return vale is an integer, except in 64-bit Ox when the file is larger than 2GB: in that case it is a double.

The second and third form return 0 if the seek was successful, else a non-zero number,

Description

Repositions the file pointer to a new position specified from the start of a file. The type argument is interpreted as follows:

• type: 'i', 'd', seeks: integer, byte equivalent: 4r;
• type: 'e', 'f', seeks: double, byte equivalent: 8r;
• type: 'e', 'f', seeks: matrix rows, byte equivalent: 16+8rc (file opened with f in format);
• type: 'c', seeks: character, byte equivalent: r.

So when a file is opened as "rbf", fseek(file, 'f', r) moves the file pointer to row r in the .fmt file.

To position the file pointer at the end specify -1 for the third argument. This can be used to determine the length of a file.

See also

fclose, fopen

Example

fsize,ftime

fsize(const file);
ftime(const file);

file

in: an open file

Return value

fsize returns the size of the file in bytes (an integer, or a double if the file is larger than 2GB).

ftime returns the modification date and time of the file (a double).

fwrite

fwrite(const file, const a);

file

in: file which is open for writing, or string with filename

a

in: int, double, matrix or string

Return value

Returns 0 if failed to write, or the number of items written to the file:

• integer: 1;
• double: 1;
• m x n matrix: number of elements written (normally m x n);
• m x n matrix: opened with f format: no of rows written (normally m);
• string: number of characters written.

Description

Writes binary data to the specified file. The byte ordering is the platform specific ordering, unless the f format was used (also see fopen), in which case writing is to a .fmt file in little endian mode (also see savemat). When data is written to a .fmt file, the number of columns must match that already in the file (use columns(file) to ask for the number of columns in the file).

See also

fclose, fopen, fread, fseek

Example

fuzziness

fuzziness(const deps);

deps

in: double, 0 or new fuzziness value

Return value

Sets and returns the new fuzziness parameter if deps >0. If deps <= 0, no new fuzziness value is set, but the current one is returned. The default fuzziness is 1e-13.

See also

isfeq

gammafact

gammafact(const ma);

ma

in: arithmetic type

Return value

Returns the complete gamma function at the value of each element of ma, of double or matrix type. Returns +.Inf for any argument which is zero or a negative integer. Note that gammafact(n+1) equals n!.

See also

factorial, gammafunc, loggamma, polygamma

gammafunc

gammafunc(const dx, const dr);

mx

in: x, arithmetic type

mr

in: r, arithmetic type

Return value

Returns the incomplete gamma function G_x(r). Returns 0 if r <= 0 or x <= 0. The accuracy is to about 10 digits. The return type is derived as follows:

• m x n matrix, when mx is an m x n matrix, and mr is scalar;
• m x n matrix, when mx is a scalar, and mr is an m x n matrix;
• m x n matrix, when mx is an m x n matrix, and mr is an m x n matrix;
• double, when mx and mx are scalar.

Example

getcwd

getcwd();

Return value

Returns the current directory.

Windows specific: returns the current directory on the current drive. Use chdir to change the current drive.

See also

chdir, getfiles, systemcall

Example

getenv

getenv(const senv);

senv

in: string

Return value

Returns a string with the value of the environment variable, or an empty string if the environment variable is undefined.

See also

systemcall

getfiles,getfolders

getfiles(const sfilemask);
getfolders(const sfilemask);

sfilemask

in: string, mask for files, may have a path or wild cards

Return value

getfiles returns an array of strings with file names matching the specified mask.
getfolders returns an array of strings with folder names matching the specified mask.

See also

chdir, getcwd

Example

hyper_2F1

hyper_2F1(const a, const b, const c, const z);

a, b, c

in: arithmetic type, parameters of ₂F₁

z

in: arithmetic type, argument of ₂F₁

Return value

Returns the value of the Gauss Hypergeometric function ₂F₁ with real parameters a, b, c and real argument z.

idiv,imod

idiv(const ia, const ib);
imod(const ia, const ib);

ia

in: arithmetic type

ib

in: arithmetic type

Return value

The imod function returns the integer remainder of int(ia) / int(ib). The sign of the result is that of ia. The idiv function returns the result of the integer division int(ia) / int(ib). The return type is a matrix of integer values if either arguments is a matrix, else it is a scalar int.

See also

fmod

Example

insertc,insertr

insertc(const ma, const c, const cadd);
insertr(const ma, const r, const radd);
insertr(const aa, const r, const radd);

ma

in: m x n matrix to insert into

aa

in: m array to insert into

c

in: scalar, column index of insertion

cadd

in: scalar, number of columns of zeros to add

r

in: scalar, row index of insertion

radd

in: scalar, number of rows of zeros to add

Return value

The insertc function with returns a copy of the input matrix with the specified columns of zeros inserted.

The insertr function with returns a copy of the input matrix with the specified rows of zeros inserted; insertr also works for arrays.

See also

dropc, dropr

Example

int

int(const ma);

ma

in: arithmetic type

Return value

Casts the argument to an integer:

• integer: unchanged;
• double: rounded towards zero;
• matrix: element 0,0 rounded towards zero;
• string: element 0;
• other types: error.

See also

ceil, double , matrix , trunc, explicit type conversion

Example

intersection

intersection(const ma, const mb);
intersection(const ma, const mb, const amidx);

ma, mb

in: matrix

amidx

in: address of variable

out: 2 x c matrix, first row is the index of the common elements in vecr(ma), the second row is the index in vecr(mb). The order of the indices correspond to the order of the return value.

Return value

Returns the sorted unique elements of ma which are also in mb as a 1 x c vector, where c is the number of elements ma and mb have in common. Returns an empty matrix if the result is empty. Missing values are skipped.

See also

exclusion, union, unique

Example

invert

invert(const ma);
invert(const ma, const alogdet, const asign);

ma

in: m x m real matrix A

alogdet

in: (optional argument) address of variable

out: double, the logarithm of the absolute value of the determinant of A

asign

in: (optional argument) address of variable

>out: int , the sign of the determinant of A; 0: singular; -1,-2: negative determinant; +1,+2: positive determinant; -2,+2: result is unreliable

Return value

Returns the inverse of A, or the value 0 if the decomposition failed.

See also

decldl, invertgen, invertsym logdet

Example

inverteps

inverteps(const dEps);

dEps

in: sets the inversion epsilon eps_inv to dEps if dEps > 0, to the default if dEps < 0; leaves the value unchanged if dEps == 0

Return value

Returns the inversion epsilon (the new value if dEps != 0).

invertgen

invertgen(const ma);
invertgen(const ma, const mode);

ma

in: m x n real matrix A

mode

in: inversion mode (optional argument, default is 0)

Return value

Returns the (generalized) inverse of A, or the value 0 if the decomposition failed:

mode     description                                     A 
0        generalized inverse using SVD               
1        generalized symmetric p.s.d inverse using SVD   m=n
2,20     first try invert then mode 0                    m=n
3,30     first try invertsym then mode 1                 m=n
4,40     use olsc (QR dec.) for inverse of A'A           m>=n
>=10     print warning if matrix is singular

Description

• 0. When mode equals 0, or the mode argument is omitted, invertgen defaults to the generalized inverse when only one argument is used.
• 1. When mode equals 1, the matrix must be symmetric positive semi-definite. Do not use this mode for negative definite matrices.
• 2. Mode 2 first tries the normal inversion routine (invert), and then, if the matrix is singular, uses the generalized inverse. This mode is the same as using 1 / x.
• 3. Mode 3 first tries the normal inversion routine (invertsym), and then, if the matrix is singular, uses the generalized inverse (as mode 1). Do not use this mode for negative definite matrices.
• 4. Mode 4 uses the QR decomposition, and the inverse is the same as obtained from using olsc. This is a different type of generalized inverse, so that, when the matrix is singular a different value is obtained then from the other modes.

If the matrix is full rank, the generalized inverse equals the normal inverse (for modes 1,3 this also requires symmetry and positive definiteness). When the mode argument is multiplied by ten, a warning is printed if the matrix is singular (or negative definite for mode 30), but the return value is not affected.

See also

invert, invertsym

Example

invertsym

invertsym(const ma);
invertsym(const ma, const alogdet);

ma

in: symmetric, positive definite m x m matrix A

alogdet

in: (optional argument) address of variable

out: double, the logarithm of the determinant of A.

Return value

Returns the inverse of A, or the value 0 if the decomposition failed.

See also

declu, invert, invertgen

Example

isarray, isclass, isdouble, isfile, isfunction, isint, ismatrix, ismember, isstring

isarray(const a);
isclass(const a);
isclass(const a, const sclass);
isdouble(const a);
isfile(const a);
isfunction(const a);
isint(const a);
ismatrix(const a);
ismember(const a, const smember);
isstring(const a);

a

in: any type

sclass

in: string, class name

smember

in: string, member name

Return value

Returns TRUE (i.e. the value 1) if the argument is of the correct type, FALSE (0) otherwise.

isclass(a, "class") returns TRUE if a is an object of type "class", or derived from "class".

ismember returns 1 if a is an object of a class and has a function member "smember"; 2 if "smember" is a data member and 0 otherwise.

See also

classname

isdotfeq,iseq,isfeq

isdotfeq(const ma, const mb);
iseq(const ma, const mb);
isfeq(const ma, const mb);

ma

in: arithmetic type

mb

in: arithmetic type

Return value

isfeq always returns an integer: it returns 1 if the argument ma is fuzzy equal to mb, 0 otherwise. When strings are compared, the comparison is case insensitive.

iseq is as isfeq, but using fuzziness of zero. When strings are compared, the comparison is case sensitive.

isdotfeq returns a matrix if either argument is a matrix; the matrix consists of 0's and 1's: 1 if the comparison holds, 0 otherwise. If both arguments are scalar, isdotfeq is equal to isfeq. In both cases the current fuzziness value is used.

See also

fuzziness

Example

isdotinf

isdotinf(const ma);

ma

in: arithmetic type

Return value

isdotinf returns a matrix of the same dimensions if the input is a matrix; the returned matrix consists of 0's and 1's: 1 if the element is +/- infinity, 0 otherwise. If the arguments is a double, isdotnan returns 1 if the double is +/- infinity.

See also

isdotmissing, isdotnan

isdotmissing, isdotnan, ismissing, isnan

isdotmissing(const ma);
isdotnan(const ma);
ismissing(const ma);
isnan(const ma);

ma

in: arithmetic type

Return value

isnan always returns an integer: it returns 1 if any element in ma is a NaN (not a number), 0 otherwise. NaN can be used to indicate a missing value.

isdotnan returns a matrix of the same dimensions if the input is a matrix; the returned matrix consists of 0's and 1's: 1 if the element is NaN, 0 otherwise. If the arguments is a double, isdotnan returns 1 if the double is NaN.

ismissing and isdotmissing are similar to isnan and isdotnan respectively. However, in addition to NaN, they also treat +/- infinity and undefined (.Null) as a missing value.

See also

deletec, deleter, selectc, selectr

Example

lag,lag0

lag(const ma);
lag(const ma, const ilag);
lag(const ma, const ilag, double dmisval);
lag0(const ma);
lag0(const ma, const ilag);
lag0(const ma, const ilag, double dmisval);

ma

in: T x n matrix

ilag

in: int, lag length, or matrix with lag lengths (default is 1)

dmisval

in: (optional argument) double, value to set missing observations to (default is 0 for lag0, .NaN for lag)

Return value

The lag fuction returns the lags of the specified matrix, whereby missing values are replaced by .NaN. The result has the same dimensions as ma. The lag0 function is the same, but using zero for the missing value.
If ilag is a matrix the return value corresponds to: lag0(.,ilag[0])~lag0(.,ilag[1])~...

See also

diff0

Example

limits

limits(const ma);

ma

in: m x n matrix

Return value

Returns a 4 x n matrix:

• 1st row: minimum of each column of ma;
• 2nd row: maximum of each column of ma;
• 3rd row: row index of minimum (lowest index if more than one exists);
• 4th row: row index of maximum (lowest index if more than one exists).

See also

min, max

Example

loadmat

loadmat(const sname);
loadmat(const sname, const iFormat);
loadmat(const sname, const aasVarNames);
loadmat(const sname, const iFormat, const aasVarNames);

sname

in: string containing an existing file name

iFormat

in: (optional argument, .mat matrix file only)
1: file has no matrix dimensions; then the matrix is returned as a column vector, and reshape can be used to create a differently shaped matrix.

in: (optional argument, .xlsx,.xls Excel files only)
1: strings are loaded as values and dates translated to Ox dates, as in OxMetrics or the database class.
0 (the default): strings are treated as empty cells, unless a dot or starting with #N/A, and dates are read using the Excel numbering instead of Ox. For a date after 1-March-1900: oxdate = exceldate + 2415019.

aasVarNames

in: (optional argument, not for .mat matrix files) address of variable

out: array of strings, names of data columns

Return value

Returns the matrix which was read, or 0 if the operation failed.

Description

The type of file read depends on the extension of the file name:

• .mat: matrix file (text file), described below,
• .dat: data file (text file) with load information,
• .in7: PcGive 7 data file (with corresponding .bn7 file),
• .xlsx: Excel 2007 (or newer) workbook file (Office Open xml),
• .xls: Excel worksheet or workbook file (binary file),
• .csv: comma-separated spread sheet file (text file),
• .dta: Stata data file (version 4--6 or 11),
• .dht: Gauss data file (v89, with corresponding .dat file),
• .fmt: Gauss matrix file (v89 and v96);
• any other: as :.mat: file. A matrix file holds a matrix, preceded by two integers which specify the number of rows and columns of the matrix.

A matrix file holds a matrix, preceded by two integers which specify the number of rows and columns of the matrix. It will normally have the .mat extension. White space and a comma between numbers is skipped. If a symbol is found which is not a number, then the rest of the line will be skipped (so, e.g. everything following ; or // is treated as comments). The exception to this is an isolated dot, the letters m and M or the words .NaN and #N/A: these are interpreted as a missing element with value NaN (Not a Number); .Inf is interpreted as infinity.

See also

Database class, savemat, reshape

Example

loadsheet

loadsheet(const sname);
loadsheet(const sname);
loadsheet(const sname, const iSheet);
loadsheet(const sname, const iSheet, const bConvertDates);

sname

in: string containing an existing file name

iSheet

in:(optional argument), int: sheet number (default is zero)

bConvertDates

in:(optional argument), int: 1: convert dates to Ox; 0: keep dates (default is one)

Return value

Returns a two-dimensional array with the elements of the spreadsheet. The elements are .Null (blank in the sheet), double or string.
Returns an empty array if the file cannot be read.

Description

The type of file read depends on the extension of the file name:

• .xlsx: Excel 2007 (or newer) workbook file (Office Open xml),
• .csv: comma-separated spread sheet file (text file),
• any other: as .xlsx file.

See also

Database class, loadmat, savesheet

Example

log,log10

log(const ma);
log10(const ma);

ma

in: arithmetic type

Return value

The log function returns the natural logarithm of each element of ma, of double or matrix type.

The log10 function returns the logarithm (base 10) of each element of ma, of double or matrix type.

See also

exp

Example

logdet

logdet(const ma, const asign);

ma

in: m x m real matrix A

asign

in: address of variable

>out: int, the sign of the determinant of A; 0: singular; -1,-2: negative determinant; +1,+2: positive determinant; -2,+2: result is unreliable

Return value

Returns a double: the logarithm of the absolute value of the determinant of A (1.0 if the matrix is singular).

See also

determinant, invert

loggamma

loggamma(const ma);

ma

in: arithmetic type

Return value

Returns the logarithm of the complete gamma function at the value of each element of ma, of double or matrix type. Returns +.Inf for an argument equal to zero, and .NaN for arguments less than zero. Note that exp(loggamma(n+1)) equals n!.

See also

gammafact, gammafunc, polygamma

Example

lower

lower(const ma);

ma

in: m x n matrix

Return value

Returns the lower diagonal (including the diagonal), i.e. returns a copy of the input matrix with strict upper-diagonal elements set to zero.

See also

setdiagonal, setupper, setlower, upper

Example

matrix

matrix(const ma);

ma

in: arithmetic type

Return value

Casts the argument to a matrix:

• integer: a 1 x 1 matrix,
• double: a 1 x 1 matrix,
• matrix: unchanged,
• string: a 1 x 1 matrix,
• other types: error.

See also

int, double, explicit type conversion

max

max(const a, ...);

a

in: arithmetic type

...

in: arithmetic type

Return value

Returns the maximum value in all the arguments, ignoring missing values. The return type is int if all arguments are of type int; otherwise the return type is double.

See also

limits, maxc, min

Example

maxc,maxcindex,maxr

maxc(const ma);
maxcindex(const ma);
maxr(const ma);

ma

in: m x n matrix A

Return value

The maxc function returns a 1 x n matrix holding the maximum of each column of ma.

The maxcindex function returns a 1 x n matrix holding the row index of the maximum of each column ma.

The maxr function returns a m x 1 matrix holding the maximum of each row of ma.

Finds the maximum value in each column (row for maxr), ignoring missing values. If no maximum is found (a column has all missing values), then the maximum is .NaN, and the index -1.

See also

limits, max, minc, mincindex

Example

meanc, meanr

meanc(const ma);
meanr(const ma);

ma

in: T x n matrix A

Return value

The meanc function returns a 1 x n matrix holding the means of the columns of ma.

The meanr function returns a T x 1 matrix holding the means of the rows of ma.

See also

sumc, sumr, varc, variance, varr

Example

min

min(const a, ...);

a

in: arithmetic type

...

in: arithmetic type

Return value

Returns the minimum value in all the arguments, ignoring missing values. The return type is int if all arguments are of type int; otherwise the return type is double.

See also

limits, max, minc

Example

minc, mincindex, minr

minc(const ma);
mincindex(const ma);
minr(const ma);

ma

in: m x n matrix A

Return value

The minc function returns a 1 x n matrix holding the minimum of each column of ma.

The mincindex function returns a 1 x n matrix holding the row index of the minimum of each column ma.

The minr function returns a m x 1 matrix holding the minimum of each row of ma.

Finds the minimum value in each column (row for maxr), ignoring missing values. If no minimum is found (a column has all missing values), then the minimum is .NaN, and the index -1.

See also

limits, maxc, maxcindex, min

Example

moments

moments(const ma);
moments(const ma, const k);
moments(const ma, const k, const fratio);

ma

in: T x n matrix A

k

in: (optional argument) no of moments k (default is k=4)

fratio

in: (optional argument) 0: no ratios (default is moment ratios)

Return value

Returns an (k+1) x n matrix holding in each column for the corresponding column of ma:

row	holds	description
0	T*	effective sample size
1	m1	sample mean
2	m21/2	sample standard deviation
3	m3/m23/2	sample skewness
4	m4/m22	sample kurtosis
..	..	..
k	mk/m2k/2	sample kth central moment ratio (i.e. in deviation from mean)

If fratio equals 0, the moments are not divided:

row	holds	description
0	T*	effective sample size
1	m1	sample mean
2	m2	sample variance
..	..	..
k	mk	sample kth central moment (i.e. in deviation from mean)

Computes the central moment ratios or central moments. Skips missing values.

See also

meanc, meanr, standardize, varc, varr

Example

nans

nans(const r, const c);
nans(const ma);

r

in: int

c

in: int

ma

in: matrix

Return value

nans(r,c) returns an r by c matrix filled with .NaN.

nans(ma) returns a matrix of the same dimension as ma, filled with .NaN.

See also

constant, ones, unit, zeros

Example

norm

norm(const ma);
norm(const ma, const itype);

ma

in: arithmetic type

itype

in: int, type of norm (default is 0 for infinity norm)

Return value

Returns the norm of a matrix (a scalar double).

Description

The type of norm depends on the itype argument. When A is a matrix:

• 0: infinity norm, maximum of absolute column sums,
• 1: maximum absolute row sums,
• 2: largest singular value,
• 'F': Frobenius norm: square root of sum of squared elements.
• -1: minimum of absolute column sums,

When A is a vector:

• 0: infinity norm, maximum absolute value,
• 1: sum of absolute values,
• 2: square root of sum of squares,
• p: p-th root of sum of absolute elements raised to the power p.
• -1: minimum absolute value,

norm(x) corresponds to norm(x,0).

See also

decsvd, rank

Example

nullspace

nullspace(const ma);

ma

in: m x n matrix A

Return value

Returns the null space of ma, or a conformant empty matrix if ma is square and full rank, or 0 if the SVD fails.

See also

decsvd, inverteps

Example

ols2c, ols2r, olsc, olsr

ols2c(const my, const mx, const amb);
ols2c(const my, const mx, const amb, const amxtxinv);
ols2c(const my, const mx, const amb, const amxtxinv,
    const amxtx);

olsc(const my, const mx, const amb);
olsc(const my, const mx, const amb, const amxtxinv);
olsc(const my, const mx, const amb, const amxtxinv,
    const amxtx);

my

in: T x n matrix Y

mx

in: T x k matrix X

amb

in: address of variable

out: k x n matrix of OLS coefficients, B

amxtxinv

in: (optional argument) address of variable

out: k x k matrix (X'X)^-1,

amxtx

in: (optional argument) address of variable

out: k x k matrix (X'X),

ols2r(const my, const mx, const amb);
ols2r(const my, const mx, const amb, const amxtxinv);
ols2r(const my, const mx, const amb, const amxtxinv,
    const amxtx);

olsr(const my, const mx, const amb);
olsr(const my, const mx, const amb, const amxtxinv);
olsr(const my, const mx, const amb, const amxtxinv,
    const amxtx);

my

in: n x T matrix Y'

mx

in: k x T matrix X', T >= k

amb

in: address of variable

out: n x k OLS coefficient matrix, B'

amxtxinv

in: (optional argument) address of variable

out: k x k matrix (X'X)^-1,

amxtx

in: (optional argument) address of variable

out: k x k matrix (X'X),

Return value

• 0: out of memory,
• 1: success,
• 2: ratio of diagonal elements of X'X is large, rescaling is advised (ratio of smallest to largest <= eps_inv),
• -1: (X'X) is (numerically) singular (decision made in decqr and decldl respectively),
• -2: combines 2 and -1.

The inversion epsilon, eps_inv, is set by the inverteps function.

Description

The ols2c and ols2r versions use the Choleski decomposition on the second moment matrix, while the others use the QR decomposition. The latter is numerically more stable, and therefore preferred, but takes more memory and is marginally slower.

See also

decldl, decqr, inverteps

Example

ones

ones(const r, const c);
ones(const ma);

r

in: int

c

in: int

ma

in: matrix

Return value

ones(r,c) returns an r by c matrix filled with ones.

ones(ma) returns a matrix of the same dimension as ma, filled with ones.

See also

constant, nans, unit, zeros

Example

outer

outer(const mx, const ms);
outer(const mx, const ms, const mode);

mx

in: m x n matrix X

ms

in: n x n symmetric matrix S or empty matrix

mode

in: int, operation mode: 'd' or 'o' (optional argument)

Return value

outer(mx,ms) returns XSX', which is m x m.
outer(mx,<>) returns XX', which is m x m.
outer(mx,ms,'d') returns diagonal(XSX'), which is 1 x m.
outer(mx,<>,'o') returns Sum x_ix_i', which is n x n, where X'=(x₁,...,x_m).

See also

diagonal

Example

oxfilename

oxfilename(const itype);

itype

in: int, determines output format

Return value

Returns a string with the name of the Ox source file from which it is called:

itype  returns            example: oxl D:\waste\func  example: oxl func
0      full file name     D:\waste\func.ox            func.ox
1      path of file name  D:\waste\                    
2      base name          func                        func
3      file extension     .ox                         .ox

In the first two cases the return value depends on how the the program was started (the path may not have been specified).

oxprintlevel

oxprintlevel(const ilevel);

ilevel

in: int, print level, see below

No return value

Description

Controls printing:

• oxprintlevel(1);    default: prints as normal,
• oxprintlevel(0);    switches printing off (print and println have no output),
• oxprintlevel(2);    disallows further calls to oxprintlevel,
• oxprintlevel(-1);  switches printing off, including warnings.

This function can be useful in simulations (e.g.), where the code being simulated has no other mechanism for switching printing on and off (Modelbase derived code normally uses SetPrint).

See also

oxwarning

Example

oxrunerror

oxrunerror(const smsg);
oxrunerror(const smsg, const i01);

smsg

in: string, error message text

i01

in: int, 0 (the default) or 1

No return value

Prints the specified run-time error message and location, and exits the program.

Description

If i01=0, the standard Ox call trace is printed; if i01=1, the top level function call is skipped (in case the error is raised in an error handler function). Use 2 to omit the trace.

oxversion

oxversion();

Return value

Returns an integer with the version of Ox multiplied by 100. So for version 5.00 the return value is 500.

oxwarning

oxwarning(const smsg);
oxwarning(const flset);

smsg

in: string, user-determined warning message

flset

in: int, new warnings settings

Return value

Returns the previous warnings settings.

Description

When given a string as argument, the function will print a user-determined warning message.

Otherwise, oxwarning controls the reporting of run-time warning messages. The following types of messages are controlled by this function:

• WFL_DECFAILED   decomposition failed and invertgen messages,
• WFL_ITMAX   maximum no. of iterations reached,
• WFL_CONCAT   concatenation dimensions don't match,
• WFL_VECIDXMAT   indexed a matrix as a vector,
• WFL_DETERMINANT   determinant-related warning,
• WFL_USER   user-determined warning message.

The first occurs when an inversion or decomposition fails, the second could happen in an eigenvalue based function. The concatenation message is printed when the dimensions don't match, and the results has been padded with zeros. The message related to WFL_VECIDXMAT is given when a matrix which is not a row or column vector is indexed with just one index. However, the message is not given when using an empty single index [], which has the same effect as the vecr function.

You can add the flags together to specify warning settings. Use oxwarning(0) to switch both these messages off, and oxwarning(-1) to switch them all on.

See also

oxprintlevel

periodogram

periodogram(const ma);
periodogram(const ma, const itrunc, const cpoints,
    const imode);

ma

in: arithmetic type, T x n matrix

itrunc

in: int, truncation parameter m, if >= T then T-1 is used

cpoints

in: int, no of points N at which to evaluate periodogram

imode

in: 0: (truncated) periodogram (times T), 1: smoothed periodogram (times T) using Parzen window, 2: estimated spectral density using Parzen window (as option 1, but divided by c₀).

Return value

• periodogram(ma);
  Returns a N+1 by n matrix with T times the periodogram computed at the Fourier frequencies 0, 2\pi/T, ..., 2N\pi/T, where N=int(T/2).
• periodogram(ma, itrunc, N, 0);
  Returns a N by n matrix with the periodogram of the columns of ma using autocovariances up to lag itrunc, computed at frequencies: 0, \pi/(N-1), ..., \pi.
• periodogram(ma, itrunc, N, 1);
  Returns a N by n matrix with the smoothed periodogram of the columns of ma using autocovariances up to lag itrunc, computed at frequencies: 0, \pi/(N-1), ..., \pi.
• periodogram(ma, itrunc, N, 2);
  Returns a N by n matrix with the spectral density of the columns of ma using autocorrelations up to lag itrunc, computed at frequencies: 0, \pi/(N-1), ..., \pi.

See also

DrawSpectrum.

Example

polydiv

polydiv(const ma, const mb, const cp);

ma

in: 1 x m matrix A = (a₀ ... a_m-1) specifying the A polynomial (see below)

mb

in: 1 x n matrix B = (b₀ ... b_n-1) specifying the B polynomial (see below)

cp

in: int, required length, p, of polynomial resulting from division

Return value

Returns a 1 x p matrix with the coefficients of polynomial resulting from dividing the A polynomial by the B polynomial. The integer 0 is returned when b₀ is 0, or p=0.

See also

polyeval, polymake, polymul, polyroots

Example

polyeval

polyeval(const ma, const mx);

ma

in: 1 x m matrix A = (a₀ ... a_m-1) specifying the A polynomial

mx

in: arithmetics type

Return value

Returns the polynomial evaluated at mx.

See also

polydiv, polymake, polymul, polyroots

Example

polygamma

polygamma(const ma, const mn);

ma

in: arithmetic type, argument

mn

in: arithmetic type, order of derivative: 0 = first derivative, 1 = second derivative, etc.

Return value

Returns the derivative of the logarithm of the complete gamma function at the value of each element of ma, of double or matrix type. The second argument specifies the order of the derivative. Returns zero for derivative order less than 0 and -.Inf when the argument is zero or a negative integer. The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and the rest is scalar (int);
• m x n matrix, when ma is a scalar, and the rest are m x n matrices;
• m x n matrix, when ma is an m x n matrix, and the rest are m x n matrices;
• double, when ma is scalar, and the rest is also scalar (int).

See also

loggamma

Example

polymake

polymake(const roots);

roots

in: 2 x m matrix with (inverse) roots of the polynomial, first row is real part, second row imaginary part (or 1 x m matrix if all roots are real).

Return value

Returns the coefficients of the polynomial (a₀ = 1) as a 2 x (m+1) matrix if the roots had a complex part, else 1 x (m+1).

See also

polyroots

Example

polymul

polymul(const ma, const mb);

ma

in: 1 x m matrix A = (a₀ ... a_m-1) specifying the A polynomial (see below)

mb

in: 1 x n matrix B = (b₀ ... b_n-1) specifying the B polynomial (see below)

Return value

Returns a 1 x (m+n-1) matrix with the coefficients of the product of the polynomials.

See also

polydiv, polyeval, polymake, polyroots

Example

polyroots

polyroots(const ma, const amroots);

ma

in: 1 x (m+1) matrix A = (a₀ ... a_m) specifying the polynomial of order m (see below)

amroots

in: address of variable

out: 2 x m matrix with roots of the polynomial first row is real part, second row imaginary part (all zeros if the roots are real). The roots are not sorted.

Return value

Returns the result of the eigenvalue decomposition:

• 0: no error;
• 1: maximum no of iterations (50) reached.

See also

eigen, polydiv, polyeval, polymake, polymul

Example

pow

pow(const ma, const p);

ma

in: arithmetic type

Return value

Returns ma .^ p. This is identical to using the dot-power operator, with the exception that if both ma and p are an integer, the return type is a double.

See also

sqr, ^ .^

Example

print, println,

print(const a, ...);
println(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 using default formatting. A formatting string can be input in the input stream: a formatting string starts with a % symbol, and is followed by one or more characters. If a formatting string is encountered, it is not printed, but applied to the next argument.

There is an additional option to add column and row labels for a matrix, specify a different format for each matrix column, or only print the lower diagonal:

• %r the next argument contains row labels (array of strings),
• %c the next argument contains column labels (array of strings).
• %cf the next argument contains column formats (array of strings)
• %lwr only print the lower diagonal of the matrix

The default format strings are:

• no value: "null",
• int: "%d",
• double: "%g",
• matrix: "\n", then each element "%#13.5g", 6 elements on a line (5 if row is labelled), no labels,
• string: "%s",
• array: "&0x%p",
• function: "&%d",
• class: "&0x%p",
• library function: "&0x%p". The format function may be used to set a different default format; it also lists the format options.
• date/time: "%C", If there is no fraction the calendar date is printed as yyyy-mm-dd; if there is only a fraction the time is printed as hh:mm or hh:mm:ss or hh:mm:ss.hh. If both are present yyyy-mm-ddThh:mm[:ss[.hh]] is printed (so using the ISO standard for date/time formatting). Also see dayofcalendar.
• any type: "%v", prints a variable in the format of an Ox constant, and can be used for any variable. It can be especially useful to read and write variables that consist of derived types, such as an array or a class object, but also for a matrix. An example is given below and in ox/samples/inout/percent_v.ox.

The format specification is similar to that for the printf function of the C language:

%[flag][width][.precision]type

Table std.2: Formatting flags for doubles and integers

-        left adjust in output field,
+        always print a sign,
space    prefix space if first character is not a sign
0        pad with leading zeros,
#        alternate output form:
         type is o: first digit will be 0,
         type is xX: prefix with 0x or 0X (unless value is 0),
         type is eEfFgG: always print decimal point,
         type is gG: keep trailing zeros,
         type is mM: omit dimensions,
         type is v: omit outer { } when printing array,
         type is P: go upto three stars

---

The width argument specifies the width of the output field. The precision argument specifies the number of significant digits (type is gG) number of digits after the decimal point (type is eEf); the default is 6 if precision is absent.

---

Table std.3: Formatting types for printing

double type, also used for matrices:
g,G       %e or %E if the exponent is <-4 or >= precision; else use %f,%F
e,E       scientific notation: with exponent,
f,F       print in fixed-point notation, without exponent,
g,e,f	  prints .NaN as .NaN
G,E,F	  prints .NaN as .
C         print as a calendar date
P         print as a pvalue, e.g. [0.002]**
		  ** if pvalue < 0.01, * if < 0.05 (with # using *** for pvalue < 0.001)  

specials for matrices:
r         followed by row labels (array of strings),
c         followed by column labels (array of strings),
cf        followed by column formats (array of strings),
    e.g.: print("%c",{"a","b"},"%cf",{"%8.4g","%6.2g"},m);
rs        followed by row separator (string; also suppresses leading and trailing newline),
cs        followed by column separator (string),

integer type:
d,i       signed decimal notation,
o         unsigned octal notation,
x,X       unsigned hexadecimal notation,
u         unsigned decimal notation,
c         print as a single character (i.e. one byte),

string type:
s         string format.

matrix type:
m         print matrix row by row using %25.26e.
M         print matrix row by row with the default format.

any type:
v		  any variable in Ox constant format.

---

println is as print but ensures the next output will be on a new line.

To print text starting with a percentage symbol that is also a format specifier, use either %s as the format, or a double percentage, as in println("%s", "%GDP", " or: ", "%%GDP").

See also

eprint, format, fprint, fscan, fwrite, sprint

Example

probchi, probf, probn, probt

probchi(const ma, const df);
probchi(const ma, const df, const nc);
probf(const ma, const df1, const df2);
probf(const ma, const df1, const df2, const nc);
probn(const ma);
probt(const ma, const df);
probt(const ma, const df, const nc);

ma

in: arithmetic type

df

in: arithmetic type, degrees of freedom

df1

in: arithmetic type, degrees of freedom in the numerator

df2

in: arithmetic type, degrees of freedom in the denominator

nc

in: arithmetic type, non-centrality parameter

Return value

Returns the requested probabilities at ma (the returned probabilities are between zero and one):

• probchi: probabilities from chi²(df) distribution,
• probchi: probabilities from non-central chi²(df) distribution,
• probf: probabilities from F(df1, df2) distribution,
• probf: probabilities from non-central F(df1, df2) distribution,
• probn: one-sided probabilities from the standard normal N(0,1),
• probt: one-sided probabilities from student-t(df) distribution,
• probt: one-sided probabilities from non-central student-t(df) distribution.

The normal probabilities are accurate to 14-15 significant digits for probabilities >10^-20. The probabilities are accurate to about 10 digits. The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and the rest is scalar;
• m x n matrix, when ma is a scalar, and the rest are m x n matrices;
• m x n matrix, when ma is an m x n matrix, and the rest are m x n matrices;
• double, when ma is scalar, and the rest is also scalar.

See also

dens..., quan..., tail..., Probability package

Example

prodc, prodr

prodc(const ma);
prodr(const ma);

ma

in: T x n matrix A

Return value

The prodc function returns a 1 x n matrix r which holds the product of all column elements of ma.

The prodr function returns a T x 1 matrix which holds the product of all row elements of ma.

See also

sumc, sumr

Example

quanchi, quanf, quann, quant

quanchi(const ma, const df);
quanf(const ma, const df1, const df2);
quann(const ma);
quant(const ma, const df);

ma

in: arithmetic type, probabilities: all values must be between 0 and 1

df

in: arithmetic type, degrees of freedom

df1

in: arithmetic type, degrees of freedom in the numerator

df2

in: arithmetic type, degrees of freedom in the denominator

dr, da

in: arithmetic type

Return value

Returns the requested quantiles (inverse probability function; percentage points) at ma:

• quanchi: quantiles from chi²(df) distribution,
• quanf: quantiles from F(df1, df2) distribution,
• quann: standard normal quantiles,
• quant: quantiles from student-t(df) distribution.

The quantiles are accurate to about 10 digits. The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and the rest is scalar;
• m x n matrix, when ma is a scalar, and the rest are m x n matrices;
• m x n matrix, when ma is an m x n matrix, and the rest are m x n matrices;
• double, when ma is scalar, and the rest is also scalar.

See also

dens..., prob..., tail... Probability package

Example

quantilec, quantiler

quantilec(const ma);
quantiler(const ma);
quantilec(const ma, const mq);
quantiler(const ma, const mq);

ma

in: T x n matrix A

mq

in: (optional argument) 1 x q matrix of quantiles

Return value

The quantilec function returns a q x n matrix holding the requested quantiles of the columns of ma. If no second argument is used the return value is a 1 x n matrix holding the medians.

The quantiler function returns a T x q matrix holding the requested quantiles of the rows of ma. If no second argument is used the return value is a T x 1 matrix holding the medians.

See also

meanc, meanr, varc, varr

Example

range

range(const min, const max);
range(const min, const max, const step);

min

in: int or double, first value m

max

in: int or double, last value n

step

in: int or double, (optional argument) increment

Return value

Returns a 1 x (n-m+1) matrix with the values with values m, m+1, ..., n. If n<m, range returns a 1 x (m-n+1) matrix with the values with values m, m-1, ..., n. The version which uses the step argument uses that as the incrementor (rather than the default +1 or -1), the returned matrix is a row vector of the required length.

Description

When all arguments are integers, the incrementation arithmetic is done using integers, else using doubles. Integer arithmetic could be a bit more precise when using longer ranges. The following example illustrates the difference:

range(-1.1, 1.1, 0.11);
range(-110, 110, 11) / 100;

The first line has the loop using floating point arithmetic, and will not have exactly zero, but something like -1.9e-16 as its 11th element. In the second line, the loop is incremented in integer arithmetic before conversion to floating point numbers. Here the 11th number will be exactly zero. Because if these rounding errors, it is best to use the integer version, and scale afterwards.

See also

constant

Example

rank

rank(const ma);
rank(const ma, const eps);

ma

in: arithmetic type

eps

in: arithmetic type, optional tolerance

Return value

Returns the rank of a matrix, of type int. The rank of a scalar is 1, except for the rank of zero, which is zero. In the one argument version, the rank is also relative to the norm, so that rank(1e-20) equals one. The two argument version uses the specified tolerance: rank(1e-20, 1e-10) equals zero.

See also

decsvd, inverteps, norm

Example

ranloopseed

ranloopseed(const iloop, const istage);

iloop

in: int, loop counter (if istage = 0)

istage

in: int, -1: initialization, 0: iterating, 1: exiting

No return value

Description

Colours the current seed with the loop iterator, so that parallel loops have the same random number stream independently of how they are partitioned among threads or processes. This is automatically done inside Ox for parallel for and parallel foreach loops.

Note that nested calls to ranloopseed are ignored, as are calls inside a parallel loop.

rann

rann(const r, const c);

r

in: int, number of rows

c

in: int, number of columns

Return value

Returns a r by c matrix of random numbers from the standard normal distribution, using drawings from the current uniform random generator.

See also

ranseed, ranu, Probability package

Example

ranseed

ranseed(const iseed);

iseed

in: int (1 seed), or array of ints (multiple seeds), or
in: string, name of random number generator to use.

Return value

Returns the current seed(s) of the random number generator (RNG). If the generator only uses one seed, the return type is int. Otherwise it is an array holding all the seeds (all array elements are integers).

A call to ranseed(0) only returns the current seed, without changing it; ranseed(-1) resets to the initial seed and returns the initial seed.

A call with a string argument to set the RNG returns the name of the new RNG. Use ranseed("") to get the name of the current RNG without changing it.

Description

Sets and gets the seed(s); ranseed can also change the random number generator:

• "PM": LCG31, Modified Park and Miller (period approx. 2³¹)
• "GM": MWC60, George Marsaglia (period approx. 2⁶⁰)
• "LE": LFSR113, Pierre L'Ecuyer (period approx. 2¹¹³)
• "MWC_32": MWC8222, George Marsaglia multiply-with-carry (period approx. 2⁸²²²)
• "MWC_52", "default": MWC8222_52, George Marsaglia multiply-with-carry (period approx. 2⁸²²²)

The number of seeds is dependent on the RNG being used: To set the seed, for example:

• "PM" has 1 seed, example: ranseed(111);
• "GM" has 2 seeds, example: ranseed({111, 1111}); If only one seed is set then both seeds are set to this value.
• "LE" has 4 seeds, example: ranseed({1,11,111,1111}); In the this case the seeds have to be larger than 1, 7, 15, 127 respectively, otherwise the call is ignored. If only one seed is set then all seeds are set to this value (using 127 if the value is less than 127).
• "MWC_32" and "MWC_52" have 256 seeds and a state and carry, so ranseed(0) returns a vector with 258 elements. It is possible to set the seed with one element, for example ranseed(111). In that case 111 is used as a starting point for a procedure that generates 256 seeds, and the default state and carry are used.

"MWC_52" generates a random number that makes full use of the available floating point precision (this carries over to all other random number functions). The others only use 32 bits, instead of 52. This is now the default uniform RNG (in Ox 3.4 and earlier, "PM" was the default). Choosing "MWC_52" or "MWC_32" will generate standard normal samples (rann) using the ziggurat method, while the others use the polar method.

See also

rann, ranu

Example

ranu

ranu(const r, const c);

r

in: int

c

in: int

Return value

Returns a r by c matrix of uniform random numbers. The matrix is filled by row. When both r and c are 1, the return value is a scalar of type double. The ranseed function can be used to change the random number generator.

See also

rann, ranseed

Example

reflect

reflect(const ma);

ma

in: square m x m matrix

Return value

Returns the reflected version of ma (i.e. the matrix transposed around its secondary diagonal, which runs from element [m-1][0] to [0][m-1]).

See also

transpose operator '

Example

replace

replace(const where, const what, const with);
replace(const where, const what, const with, const smode);

where

in: object to search in

what

in: what to search for

with

in: the replacement

smode

in: (optional argument), string controlling search method: "i", "ir", "r" or nothing

Return value

Returns where, with the requested replacements made (if any).

Description

where	what	with	action
array	string	string	replace string elements equal where with with
array	string	string	apply the replace action on each string element
string	string	string	replace one or more occurrences of substring what
arithmetic	int,double	int,double	replace every element that occurs in what
arithmetic	matrix	int,double	replace every element that occurs in what
arithmetic	matrix	matrix	replace every element that occurs in what with the corresponding element in with
array	arithmetic	arithmetic	apply the replace action on each arithmetic element

Arithmetic denotes a matrix, int, or double. For string replacement, smode is an optional string consisting of the letters:

"i"	ignore case,
"*"	replace all,
"a"	replace all,
"."	dot-replacement: apply the string replacement to every string in the array (instead of replacing entire strings only),
"1" -- "9"	perform from one to nine replacements.

The default is "*".

The smode argument is ignored for arithmetic replacement.

See also

find, vecindex

Example

reshape

reshape(const ma, const r, const c);

ma

in: arithmetic type

r

in: int

c

in: int

Return value

Returns an r by c matrix, filled by row from vecr(ma). If there are less than rc elements in ma, the input matrix is repeated.

See also

shape, vecr

Example

reversec, reverser

reversec(const ma);
reverser(const ma);

ma

in: m x n matrix A

Return value

The reversec function returns an m x n matrix which is ma, except that the elements within each column are in reverse order.

The reverser function returns an m x n matrix which is ma, except that the elements within each row are in reverse order.

See also

sortc, sortr

Example

round

round(const ma);

ma

in: arithmetic type

Return value

Returns the rounded elements of ma, of double or matrix type. Rounds to the nearest integer.

See also

ceil, floor, trunc

Example

rows

rows(const ma);

ma

in: any type

Return value

Returns an integer value which is the number of rows in the argument:

• m x n matrix: m;
• string: number of characters in the string;
• array: number of elements in the array;
• file: number of columns in the file; (only if opened with f format, see fopen);
• other: 0.

See also

columns, sizeof

Example

savemat

savemat(const sname, const ma);
savemat(const sname, const ma, const iFormat);
savemat(const sname, const ma, const asVarNames);

sname

in: string containing a destination file name

ma

in: matrix

iFormat

in: (optional argument)
1: omit the matrix dimensions (.mat file only);
1: save in universal v96 format (.fmt file only)

asVarNames

in: (optional argument)
array of strings with names for data columns

Return value

Returns 0 if the operation failed, 1 otherwise.

Description

The type of file saved depends on the extension of the file name:

• .mat: matrix file (text file),
• .dat: data file (text file) with load information,
• .in7: PcGive 7 data file (with corresponding .bn7 file),
• .xlsx: Excel 2007 workbook file (Office Open xml),
• .xls: Excel version 2.1 spread sheet file,
• .csv: comma-separated spread sheet file (text file),

  Warning: Excel may write csv files with only single precision (9 significant digits, rather than the 17 that are needed for loss-less saving).

• .fmt: Gauss matrix file: extended v89 (default) or universal v96,
• .dta: Stata 11 data file (version 114),
• .dht: Gauss data file: extended v89, with corresponding .dat file,
• any other: as .mat file.

See also

Database class, loadmat

Example

savesheet

savesheet(const sname, const sheet);

sname

in: string containing a destination file name

sheet

in: two-dimensional array or matrix

Return value

Returns 0 if the operation failed, 1 otherwise.

Description

Saves as an .xlsx file.

See also

Database class, loadsheet (for an example)

scan

scan(const a, ...);

a

in: any type

...

in: any type

Return value

Returns the number of arguments successfully scanned and assigned.

Description

This function works as fscan, but reading from the console, not a file. Any text in the scanning string which is not an input is echoed to the console (this is different from the standard C scanf function).

See also

fscan, fwrite, sscan

Example

selectc, selectr, selectifc, selectifr, selectrc

selectc(const ma);
selectc(const ma, const mval);
selectr(const ma);
selectr(const ma, const mval);
selectifc(const ma, const mifc);
selectifr(const ma, const mifr);
selectrc(const ma, const mr, const mc);

ma

in: m x n matrix to select from

mval

in: p x q matrix with values to use for selection

mifc

in: p x n boolean matrix specifying columns to select

mifr

in: m x q boolean matrix specifying rows to select

mc

in: p x n matrix with indices of columns to select

mr

in: m x q matrix with indices of rows to select

Return value

The selectc function with one argument returns an m x s matrix, selecting columns from ma which have a missing value (NaN: not a number).

The selectr function with one argument returns an s x n matrix, selecting rows from ma which have a missing value (NaN).

The remaining forms expect matrices without missing values.

The selectc function with two arguments returns an m x s matrix, selecting the columns from ma which have at least one element equal to an element in the matrix mval.

The selectr function with two arguments returns an s x n matrix, selecting the rows from ma which have at least one element equal to an element in the matrix mval.

The selectif functions can be used to select rows or columns based on a logical expression: all rows (columns) wich have a zero in the corresponding row (column) are dropped.

The selectifc function returns an m x s matrix, selecting only those columns from ma which have at least one non-zero element in the corresponding column of mifc.

The selectifr function returns an s x n matrix, selecting only those rows from ma which have at least one non-zero element in the corresponding row of mifr.

The selectrc function returns a 1 x max(pn,mq) matrix, which holds the selected elements. If an index is outside the matrix bounds of ma the corresponding element in the return value is NaN.

All functions return an empty matrix if the selection is empty.

See also

deletec, deleter, deleteifc, deleteifr, isdotnan, vecindex

Example

setbounds

setbounds(const ma, const dlo, const dhi);

ma

in: m x n matrix

dlo

in: scalar, lower bound (may be -.Inf)

dhi

in: scalar, upper bound (may be +.Inf)

Return value

Returns the specified matrix, replacing values smaller than dlo by dlo and values greater that dhi by dhi. Missing values remain missing.

Example

setdiagonal, setlower, setupper

setdiagonal(const ma, const mdiag);
setlower(const ma, const ml);
setupper(const ma, const mu);
setlower(const ma, const ml, const mdiag);
setupper(const ma, const mu, const mdiag);

ma

in: m x n matrix

mdiag

in: 1 by min(m,n) or min(m,n) by 1 or matrix m x n matrix or scalar

ml

in: scalar, or m x n matrix, or vector, with new strict lower diagonal

mu

in: scalar or m x n matrix with new strict upper diagonal

Return value

setdiagonal returns a matrix with the diagonal replaced by mdiag, which is either a vector with the new diagonal elements, or a matrix from which the diagonal is copied. If mdiag is scalar, all diagonal elements of the returned matrix have that value.

setlower returns ma with the strict lower diagonal replaced by that of ml. If ml is a scalar, each element is set to that value. If ml is a row or column vector, the strict lower diagonal is set column-wise to elements of the vector (until the vector runs out).
setlower(ma, ml, mdiag) corresponds to setdiagonal( setlower(ma, ml), mdiag).

setupper returns ma with the strict upper diagonal replaced by that of ml. If ml is a scalar, each element is set to that value.
setupper(ma, ml, mdiag) corresponds to setdiagonal( setupper(ma, ml), mdiag).

See also

diag, diagonal, diagonalize, lower, upper

Example

shape

shape(const ma, const r, const c);

ma

in: arithmetic type

r

in: int

c

in: int

Return value

Returns an r by c matrix, filled by column from vec(ma). If there are fewer than rc elements in ma, the value 0 is used for padding.

See also

reshape, vec

Example

sin, sinh

sin(const ma);

ma

in: arithmetic type

Return value

sin returns the sine of ma, of double or matrix type.

sinh returns the sine hyperbolicus of ma, of double or matrix type.

See also

acos, asin, atan, cos, cosh, sinh, tan, tanh

sizec sizeof sizer sizerc

sizec(const ma);
sizeof(const ma);
sizer(const ma);
sizerc(const ma);

Return value

Returns an integer value which is the number elements in the argument:

                   rows/sizeof  columns   sizer  sizec  sizerc
int, double             0          0        1      1       1
m x n matrix            m          n        m      n      mn
string, length c        c          c        1      c       c
array, length c         c          c        1      c       c
file (f format)         r          c        r      c      rc

columns, rows

Example

solveldl

solveldl(const ml, const md, const mb);

ml

in: m x m lower diagonal matrix L, LDL'=A

md

in: 1 x m matrix with reciprocals of D

mb

in: m x n matrix B, the right-hand side

Return value

Returns the m x n matrix X from solving AX=B.

See also

decldl, invertsym

Example

solveldlband

solveldlband(const ml, const md, const mb);

ml

in: p x n vector specifying the L^b matrix

md

in: 1 x m matrix with reciprocals of D or empty matrix (see below).

mb

in: m x n matrix B, the right-hand side

Return value

Returns the m x n matrix X from solving AX=B.

If md is the empty matrix, the return value is the m x n matrix X=invert(L)B.

See also

decldlband, solvetoeplitz

Example

solvelu

solvelu(const ml, const mu, const mp, const mb);

ml

in: m x m lower diagonal matrix L

mu

in: m x m upper diagonal matrix U

mp

in: 2 x m matrix with interchange permutations in the second row

mb

in: m x n matrix B, the right-hand side

Return value

Returns the m x n matrix X from solving AX=B.

Description

Solves AX=B for X following a LU decomposition of A. This function may be used to only do the forward or backward substitution part:

solvelu(L, 0, 0, B) solves LX=B,

solvelu(0, U, 0, B) solves UX=B. So can be used to invert a triangular matrix.

See also

declu, invert

Example

solvetoeplitz

solvetoeplitz(const mr, const cm, const mb);
solvetoeplitz(const mr, const cm, const mb, alogdet);

mr

in: double, or r x 1 or 1 x r matrix, specifying the symmetric positive definite (band) Toeplitz matrix

cm

in: dimension of complete Toeplitz matrix: m x m, m >= r

mb

in: m x n matrix B, the right-hand side

alogdet

in: (optional argument) address of variable

out: double, the logarithm of (the absolute value of) the determinant of A

Return value

Returns the m x n matrix X from solving AX=B, or 0 if the Toeplitz matrix is singular.

See also

pacf, toeplitz

Example

sortbyc, sortbyr

sortbyc(const ma, const icol);
sortbyr(const ma, const irow);

ma

in: matrix

icol

in: scalar: index of column to sort, or matrix: specifying the columns to sort by.

irow

in: index of row to sort

Return value

The reordered (sorted in ascending order) matrix.

See also

reversec, reverser, sortc, sortr

Example

sortc, sortcindex, sortr

sortc(const ma);
sortr(const ma);
sortcindex(const mb);

ma

in: matrix, array or string

mb

in: row vector, column vector, array or string

Return value

If ma is a matrix, the return value is ma with each column (sortc) or row (sortr) sorted in ascending order. If ma is scalar the return type and value are that of ma.
If ma is an array of strings, the strings are sorted in increasing order (all non-string entries are pushed to the end, and will be in reverse order). If ma is a string, the string is returned unchanged.

sortcindex returns a column vector with the sorted index which results from applying sortc(mb) (so v[sortcindex(v)] equals sortc(v)). A matrix argument to sortcindex must be a column vector or a row vector (the transpose is used in the latter case, so sortcindex(v) and sortcindex(v') are the same).

Applying sortcindex twice, as in sortcindex(sortcindex(v)), returns the ranking.

See also

sortbyc, sortbyr

Example

spline

spline(const my, const mx, const alpha);
spline(const my, const mx, const alpha, agcv);

my

in: T x n matrix with variables (observations in columns) to smooth

mx

in: 0 for evenly spaced Y, else T x m matrix with X (where m=1: same X used for all Ys, or m=n: corresponding X is used with Y)

alpha

in: double, bandwidth, 0: automatic bandwidth selection using GCV, <0: absolute value is bandwidth, >0: specifies equivalent number of parameters.

agcv

in: (optional) address, returns GCV (generalized cross validation score) and equivalent number of parameters

Return value

Returns a T x n matrix with the smooth from applying the natural cubic spline. The optional agcv argument is a 2 x n matrix, with the generalized cross validation (GCV) score in the first row, and the equivalent number of parameters in the second.

Example

sprint

sprint(const a, ...);

a

in: any type

...

in: any type

Return value

Returns a string containing the written text, or 0 if the sprint buffer was too small (see sprintbuffer).

Description

Each argument is printed to a string. See print for a description of formatting. There is a maximum text length: this is documented under sprintbuffer.

See also

eprint, print, sprintbuffer

Example

sprintbuffer

sprintbuffer(const len);

len

in: int

Return value

Returns 0 of type int.

Description

Sets the size of the internal sprint buffer. The default is 16 * 1024 characters, and this function is only needed if a larger buffer is needed for sprint.

See also

sprint

sqr, sqrt

sqr(const ma);
sqrt(const ma);

ma

in: arithmetic type

Return value

sqrt returns the square root of the elements of ma, of double or matrix type.

sqr returns the square of the elements of ma. If the input to sqr is a double or matrix, the return type is a double or matrix. If the input is an integer, the return type is integer unless the result would overflow in integer computation. In that case the return type is double in order to represent the result.

See also

pow, ^ .^

Example

sscan

sscan(const string, const a, ...);
sscan(const astring, const a, ...);

string

in: string to scan from

astring

in: address of string to scan from, on return the scanned text has been removed from the string

a

in: any type

...

in: any type

Return value

Returns the number of arguments successfully scanned and assigned. If s is a string, then sscan(s, ...) will leave the string unchanged, whereas sscan(&s, ...) will remove the read characters from the string. Returns -1 when at the end of the string.

Description

This function works as fscan, but reading from a string, not a file. See fscan for a description of formatting; the "%#m" and "%#M" formats may not be used in sscan.

See also

fscan, fwrite, scan

Example

standardize

standardize(const ma);

ma

in: T x n matrix A

Return value

Returns a T x n matrix holding the standardized columns of ma. If any variance is <= 1e-20, then the corresponding column is set to 0.

See also

meanc, meanr, varc, varr, variance

Example

string

string(const ma);

ma

in: arithmetic type

Return value

Casts the argument to a string, see explicit type conversion.

See also

double

strfind, strfindr, strifind strifindr

strfind(const where, const what);
strfindr(const where, const what);
strifind(const where, const what);
strifindr(const where, const what);

where	what	return type
array of strings	array of c string	1 x c matrix with indices of occurrence (-1 if not found)
array of strings	string	int: index of occurrence of string what, or -1 if not found
string	string	int: index of occurrence of substring what, or -1 if not found
string	r x c matrix with character values	1 x rc matrix with indices of occurrence (-1 if not found)
string	character	int: index of occurrence of character what, or -1 if not found

strfind	case sensitive search
strifind	case insensitive search
strfindr	case sensitive reverse search
strifindr	case insensitive reverse search

Example

strlwr, strtrim, strupr

strlwr(const s);
strtrim(const s);
strupr(const s);

s

in: the strings to convert

Return value

Returns a copy of the string, which is converted to lower case (strlwr) or uppercase (strupr). strtrim returns the string with leading and trailing white space removed.

Example

submat

submat(const ma, const r1, const r2, const c1, const c2);

ma

in: matrix

r1,r2

in: int

c1,c2

in: int

Return value

Returns the submatrix of ma from row indices r1 to r2 and column indices c1 to c2. This is equivalent to ma[r1:r2][c1:c2], except that indices are truncated to the matrix dimensions and an empty matriux is returned if the submatrix is entirely outside the matrix.

See also

selectrc, []

sumc, sumr

sumc(const ma);
sumr(const ma);

ma

in: T x n matrix A

Return value

The sumc function returns a 1 x n matrix r which holds the sum of the column elements of ma.

The sumr function returns a T x 1 matrix which holds the sum of the row elements of ma.

See also

meanc, meanr, prodc, prodr, sumsqrc, sumsqrr, varc, varr

Example

sumsqrc, sumsqrr

sumsqrc(const ma);
sumsqrr(const ma);

ma

in: T x n matrix A

Return value

The sumsqrc function returns a 1 x n matrix r which holds the sum of the squares of the column elements of ma.

The sumsqrr function returns a T x 1 matrix which holds the sum of the squares of the row elements of ma.

See also

sumc, sumr, varc, varr

Example

systemcall

systemcall(const s);

s

in: string with system command

Return value

Performs a operating system call, and waits for the call to finish. Returns the exit code from the system call.

For example, systemcall("dir") lists the directory under Windows, while systemcall("ls") does this under Linux. The output of the command is echoed to the standard output console.

See also

chdir, getcwd, getenv

tailchi, tailf, tailn, tailt

tailchi(const ma, const df);
tailf(const ma, const df1, const df2);
tailn(const ma);
tailt(const ma, const idf);

ma

in: arithmetic type

df

in: arithmetic type, degrees of freedom

df1

in: arithmetic type, degrees of freedom in the numerator

df2

in: arithmetic type, degrees of freedom in the denominator

idf

in: int, degrees of freedom

Return value

Returns the requested tail probabilities at ma (the returned tail probabilities are between zero and one):

• tailchi: tail probabilities from chi²(df) distribution,
• tailf: tail probabilities from F(df1, df2) distribution,
• tailn: one-sided standard normal tail probability,
• tailt: one-sided tail probabilities from student-t(df) distribution.

The tail probabilities are accurate to about 10 digits. The return type is derived as follows:

• m x n matrix, when ma is an m x n matrix, and the rest is scalar (int for tailt);
• m x n matrix, when ma is a scalar, and the rest are m x n matrices;
• m x n matrix, when ma is an m x n matrix, and the rest are m x n matrices;
• double, when ma is scalar, and the rest is also scalar (int for tailt).

See also

dens..., prob..., quan...

Example

tan, tanh

tan(const ma);
tanh(const ma);

ma

in: arithmetic type

Return value

tan returns the tangent of ma, of double or matrix type.

tanh returns the tangent hyperbolicus of ma, of double or matrix type.

See also

acos, asin, atan, cos, cosh, sin, sinh, tanh

thinc, thinr

thinc(const ma, const c);
thinr(const ma, const r);

ma

in: m x n matrix A

c

in: int, desired number of columns to extract

r

in: int, desired number of rows to extract

Return value

The thinc function returns an m by c matrix consisting of a selection of columns of the original matrix. The thinr function returns an r by n matrix consisting of a selection of rows of the original matrix.

See also

aggregatec, aggregater

Example

time

time();

Return value

A string holding the current time.

See also

date

Example

timeofday

timeofday();
timeofday(const index);
timeofday(const hours, const minutes);
timeofday(const hours, const minutes, const seconds);
timeofday(const hours, const minutes, const seconds, const hundreds);

index

in: arithmetic type, calendar index of a certain date with fractional time

hours

in: arithmetic type, hours on 24-hour clock

minutes

in: arithmetic type, minutes

seconds

in: arithmetic type, seconds

hundreds

in: arithmetic type, hundreds

Return value

The timeofday function without any arguments returns the fraction of the calendar index representing the current time.

The timeofday function with two or more arguments returns the fraction of the calendar index of the specified time (see below). If all arguments are an integer, the return value will be an integer.

The timeofday function with one argument takes a calendar index (or vector of indices), as argument, returning a n x matrix with the quadruplet hours, minutes, seconds, hundreds in each row (n is the number of elements in the input).

Description

The calendar index is the Julian day number, with an optional fractional part to specifies the fraction of the day: 2453402.75 corresponds to 2005-01-01T18:00. If the day number is zero, it is interpreted as a time only, so 0.75 is just 18:00 (6 PM). The "%C" print format is available to print or scan a calendar index.

See also

dayofcalendar, print, timing

Example

timer, timespan

timer();
timespan(const time);
timespan(const time, const time0);

time

in: double, value from previous call to timer

time0

in: double, (optional argument) start time

Return value

The timer function returns a double representing the current time in one 100th of a second. (Under Windows this is the elapsed time since the process started; under Linux/Unix, it is the CPU time used so far, ignoring time taken by other processes.)

The timespan function returns a string holding the time lapsed since the time argument.

The timespan(time, time0) function returns a string holding the lapsed time between time and time0. Both arguments must be measured in one 100th of a second.

See also

today

Example

timestr, timing, today

timestr(const time);
timing(const mdates);
timing(const mtimes, const mode);
today();

time

in: double, date expressed as number of seconds since 1 January 1970 at 00:00:00 (e.g. a value from timing)

mdates

in: T x k matrix with date and time, in order: year, month, day, hour, minute, second (see below).

mtimes

in: m x n matrix with dates expressed in seconds

mode

in: int, 0 (or absent): convert date/time to seconds; 1: convert seconds to date/time; 2: convert seconds to calendar index as used in dayofcalendar and timeofday.

Return value

The timing function with mode 0 (or no mode specified) converts a T x k matrix of year, month, ..., seconds (see below) to a T x 1 vector with the date/time expressed as the number of seconds since 1 January 1970 at 00:00:00.

The timing function with mode 1 converts an m x n matrix of seconds, returning an mn x 6 matrix with respectively year, month, day, hour, min, sec in the columns.

The timing function with mode 2 converts an m x n matrix (or a single double) of seconds to calendar indices, returning an m x n matrix (or a double).

The timestr function returns the date/time expressed as a text string: "year-month-day hour:min:sec". The time is omitted if it is 00:00:00.

The today function returns a double with the current date/time expressed in seconds.

Description

These functions work with time in seconds: the number of seconds since 1 January 1970 at 00:00:00. This is more restrictive and less convenient than the calendar index (with fraction for time) that is used in dayofcalendar and timeofday. The input matrix for timing with mode 0 (or no mode specified) has a specified data and time in each row, with the columns organized as:

column   item    values
0        year    full year (e.g. 1970)
1        month   month in year, 1 ... 12 (e.g. 2 for February)
2        day     day in month, 1 ... 31
3        hour    hour in day, 0 ... 23
4        min     minutes, 0 ... 60
5        sec     seconds, 0 ... 60

The actual input matrix may have fewer columns, in which case the remainder is assumed to be zero.

See also

dayofcalendar, timeofday, timer

Example

toeplitz

toeplitz(const ma);
toeplitz(const ma, const cm);

ma

in: double, or r x 1 or 1 x r matrix

cm

in: (optional argument) m: dimension of matrix to be created, m >= r; if the argument is missing, m=r is used.

Return value

Returns a symmetric Toeplitz matrix.

See also

diag, solvetoeplitz

Example

trace

trace(const ma);

ma

in: arithmetic type

Return value

Returns the trace of ma (the sum of its diagonal elements). Return type is double.

See also

determinant

Example

trunc, truncf

trunc(const ma);
truncf(const ma);

ma

in: arithmetic type

Return value

trunc returns the truncated elements of ma, of double or matrix type.

truncf is fuzzy truncation.

See also

ceil, floor, fuzziness, round,

Example

union, unique

union(const ma);
unique(const ma);

ma

in: matrix

mb

in: matrix

Return value

unique returns the sorted unique elements of ma as a row vector.
union returns a row vector with the sorted unique elements of ma and mb combined.

Returns an empty matrix if the result is empty. Missing values are skipped.

See also

exclusion, intersection

Example

unit

unit(const rc);
unit(const r, const c);

rc

in: int

r

in: int

c

in: int

Return value

Returns an rc by rc identity matrix (one argument), or an r by c matrix with ones on the diagonal (rest zero).

See also

constant, unit, zeros

Example

unvech

unvech(const va);

va

in: arithmetic type, (column or row) vector to make into symmetric matrix

Return value

Returns a symmetric matrix, given the vectorized lower diagonal of a symmetric matrix.

See also

vech

Example

upper

upper(const ma);

ma

in: m x n matrix

Return value

Returns the upper diagonal (including the diagonal), i.e. returns a copy of the input matrix with strict lower-diagonal elements set to zero.

See also

lower, setdiagonal, setlower, setupper

Example

va_arglist

va_arglist();

Return value

Returns an array holding the arguments starting with the first variable in the variable argument list.

Description

See variable arguments.

Example

varc, varr

varc(const ma);
varr(const ma);

ma

in: T x n matrix A

Return value

The varc function returns a 1 x n matrix holding the variances of the columns of ma.

The varr function returns a T x 1 matrix holding the variances of the rows of ma.

See also

meanc, meanr, sumc, sumr, variance

Example

variance

variance(const ma);

ma

in: T x n matrix A

Return value

Returns an n x n matrix holding variance-covariance matrix of ma.

See also

acf, correlation, meanc, meanr, standardize, varc, varr

Example

vec

vec(const ma);

ma

in: arithmetic type

Return value

If ma is an m x n matrix, the return value is an mn x 1 matrix consisting of the stacked columns of ma. If ma is scalar, the return value is an 1 x 1 matrix consisting of the value ma.

See also

shape, vech, vecr

Example

vech

vech(const ma);

ma

in: arithmetic type

Return value

If ma is an m x n matrix, the return value is an (m(m+1)/2 - j(j+1)/2) by 1 matrix, where j = max(m-n,0), consisting of the stacked columns of the lower diagonal of ma. If ma is scalar, the return value is a 1 x 1 matrix consisting of the value ma.

See also

unvech, vec, vecr

Example

vecindex

vecindex(const ma);
vecindex(const ma, const mfind);

ma

in: matrix

mfind

in: matrix (optional argument)

Return value

vecindex with 1 argument returns a p x 1 matrix holding the row index of the non-zero elements of vec(ma), where p is the number of non-zero elements in ma. If there is no non-zero element, the function returns the empty matrix. A .NaN in ma is treated as a non-zero.

vecindex with 2 arguments returns a p x 1 matrix holding the row indices of the elements of vec(ma), which appear in vec(mfind). If none are found, the function returns the empty matrix.

Description

The one argument version is often used with a boolean expression: vecindex(x .< 0 .|| x .== 10) A scalar second argument locates all indices that have that value: vecindex(x, 5) If the second argument is a matrix, vecindex returns the sorted indices of elements of the first argument that occur in the second. Use find instead to determine the location of the elements of one vector in another.

See also

find, shape, vec, vecrindex

Example

vecr

vecr(const ma);

ma

in: arithmetic type

Return value

If ma is an m x n matrix, the return value is an mn x 1 matrix consisting of the stacked transposed rows of ma. If ma is scalar, the return value is a 1 x 1 matrix consisting of the value ma.

See also

reshape, vech, vec

Example

vecrindex

vecrindex(const ma);
vecrindex(const ma, const mfind);
vecrindex(const ma, const mfind, const bunique);

ma

in: matrix

mfind

in: matrix (optional argument)

bunique

in: int (optional argument when mfind is present)

Return value

vecrindex with 1 argument returns a p x 1 matrix holding the row index of the non-zero elements of vecr(ma), where p is the number of non-zero elements in ma. If there is no non-zero element, the function returns the empty matrix. A .NaN in ma is treated as a non-zero.

vecrindex with 2 arguments returns a p x 1 matrix holding the row indices of the elements of vecr(ma), which appear in mfind. If none are found, the function returns the empty matrix. If the optional third argument is TRUE, then the return value has at most the dimension of vecr(mfind); for each element in vecr(mfind) the first occurrence in ma is reported (if any). This can be faster when ma is large, and you know that each occurrence occurs only once.

See also

find, vecr, vecindex

Example

zeros

zeros(const r, const c);
zeros(const ma);

r

in: int

c

in: int

ma

in: matrix

Return value

zeros(r,c) returns an r by c matrix filled with zeros.

zeros(ma) returns a matrix of the same dimension as ma, filled with zeros.

See also

nans, ones, unit, zeros

Example

---

Ox version 4.08. © JA Doornik This file last changed .