com.jstatcom.util
Class UData

java.lang.Object
  com.jstatcom.util.UData

public final class UData
extends java.lang.Object

This class contains a collection of methods to be used with JSCData objects. Some methods are directly related to time series analysis. The methods defined here should help to prepare parameters for procedure calls, as well as to make simple data transformations often needed to prepare input panels. They are not used as often as to make them part of particular JSCData implementations.

Author:

Markus Kraetzig

Method Summary

static JSCSArray	appendSuffix(JSCSArray arg, java.lang.String suffix, java.lang.String newName) Creates a new data object with suffix being appended to all string elements in arg.
static JSCNArray	createDeterministic(TSDateRange range, JSCNArray dummies, boolean isIntercept, boolean isSeasDum, boolean isSeasDumCentered, boolean isTrend, java.lang.String newName) Creates a data object with the deterministic variables to be used for estimation according to the parametrization.
static JSCNArray	createResMat(JSCNArray det, JSCNArray end, JSCNArray ex, java.lang.String name) Creates a restriction matrix to be used for model estimation.
static JSCNArray[]	createYZMat(JSCNArray detData, JSCNArray endData, JSCNArray exData, int endLags, int exLags, java.lang.String yName, java.lang.String zName) Creates the Y and Z matrices to be used for estimation.
static boolean	hasFullColumnRank(JSCNArray arg, int truncationLag) Checks the rank of arg after deleting the first truncationLag rows of it.
static JSCNArray[]	imp2ExpRes(JSCNArray res, JSCNArray r) Gets the explicit representation of restrictions on the cointegrating space, given the implicit representation.
static JSCNArray	indexData(JSCNArray arg, java.lang.String newName) Gets a new array with the elements of arg being transformed into an index with the mean of each column being normalized to +100 or -100, depending on the sign of the mean.
static JSCData[]	mergeTS(JSCSArray namesOfData, java.lang.String nameDat, java.lang.String nameRange) Merges time series with possibly different length and fills them with missing values at the beginning and/or the end.
static JSCNArray[]	splitDeterministics(JSCNArray dets, boolean zeroBased) Takes an array with deterministic terms and computes indices for the breaks of all dummy variables.
static JSCNArray	standardize(JSCNArray dat, java.lang.String name) Creates a new data object with the elements of dat divided by the standard devitation of the respective columns of dat.
static java.lang.String	stringForArray(JSCSArray data) String representation of the first row of a string data object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

appendSuffix

public static JSCSArray appendSuffix(JSCSArray arg,
                                     java.lang.String suffix,
                                     java.lang.String newName)

Creates a new data object with suffix being appended to all string elements in arg.

Parameters:

arg - the original data object

suffix - the string to be appended to all elements of arg

newName - the name of the new data object to be created

Returns:

a new data object with the changed string elements

Throws:

java.lang.IllegalArgumentException - if (arg == null || suffix == null || newName == null) or if arg is not of a string type

createDeterministic

public static JSCNArray createDeterministic(TSDateRange range,
                                            JSCNArray dummies,
                                            boolean isIntercept,
                                            boolean isSeasDum,
                                            boolean isSeasDumCentered,
                                            boolean isTrend,
                                            java.lang.String newName)

Creates a data object with the deterministic variables to be used for estimation according to the parametrization. The data object is constructed in the order dummies~intercept~seasonal dummies~trend, where each component may be there or not. If nothing is specified, an empty data object is returned.

Parameters:

range - the TSDateRange defining start and end

dummies - impulse and shift dummies, or other manually specified deterministics, can be either empty or null

isIntercept - true if a constant should be included

isSeasDum - true if seasonal dummies should be included, this automatically sets isIntercept=true as well, false otherwise

isSeasDumCentered - true if centered seasonal dummies should be used, only if (isSeasDum)

isTrend - true if a trend should be included

newName - the name of the new data object to create

Returns:

a new data object containing the deterministics for an estimation dummies~intercept~seasonal dummies~trend

Throws:

java.lang.IllegalArgumentException - if (newName == null || range == null) or if the number of observations in dummies does not fit with range

createResMat

public static JSCNArray createResMat(JSCNArray det,
                                     JSCNArray end,
                                     JSCNArray ex,
                                     java.lang.String name)

Creates a restriction matrix to be used for model estimation. The restriction matrix R is implicitely defined by vec(B)=R*gamma+r, where R is a (K(K*py + d + X(px+1)) x M) matrix with:

• K being dimension of the process
• py the endogenous lags
• d the number of deterministic variables
• X the number of exogenous variables
• px the exogenous lags
• M the number of free parameters to estimate
• gamma (M x 1) vector of free parameters
• r vector of known constants, here assumed to be 0
• B matrix of all estimators

See also H. Lütkepohl, Introduction to Multiple Time Series Analysis, 5.2.1. The suggested order of the restrictions can freely be set by rearranging the input data objects (exchanging det, end, ex). This method only supports exclusion restrictions for certain coefficients .

Parameters:

det - K x d matrix containing zeros and ones to exclude the respective coefficient for the deterministics

end - K x K*py matrix containing zeros and ones to exclude the respective coefficient for the endogenous part

ex - K x X(px+1) matrix containing zeros and ones to exclude the respective coefficient for the exogenous part

name - the name of the data object to create

Returns:

a new data object containing the restriction matrix, is empty if the input data objects are empty or if they do not contain any restrictions

Throws:

java.lang.IllegalArgumentException - if (name == null || det == null || end == null || ex == null )

createYZMat

public static JSCNArray[] createYZMat(JSCNArray detData,
                                      JSCNArray endData,
                                      JSCNArray exData,
                                      int endLags,
                                      int exLags,
                                      java.lang.String yName,
                                      java.lang.String zName)

Creates the Y and Z matrices to be used for estimation. For the definition of Z see Helmut Lütkepohl, Introduction to Multiple Time Series Analysis, 10.3. The input data objects must contain the same number of observations including the presample values which will be truncated according to the maximum number of endogenous/exogenous lags.

The order of the variables within Z must be det|end|ex. If subset restrictions are set, then this must correspond to the ordering of R.

The following symbols are defined:

• T sample size
• D number of deterministic variables
• K number of endogenous variables (dimension of process)
• X number of deterministic variables

Parameters:

detData - data object with dimension T + Math.max(endLags, exLags) x D

endData - data object with dimension T + Math.max(endLags, exLags) x K, must not be empty

exData - data object with dimension T + Math.max(endLags, exLags) x X

endLags - number of endogenous lags in levels

exLags - number of exogenous lags in levels

yName - name of data object for Y matrix

zName - name of data object for Z matrix

Returns:

2 x 1 array of data objects with the created matrices {Y, Z}

Throws:

java.lang.IllegalArgumentException - if one of the arguments was null or if (endLags < 0 || exLags < 0) or if (endData.isEmpty()) or if the dimensions of the nonempty data objects are not the same or if there are too many lags for the given sample dize

hasFullColumnRank

public static boolean hasFullColumnRank(JSCNArray arg,
                                        int truncationLag)

Checks the rank of arg after deleting the first truncationLag rows of it. Returns whether the rank is equal to arg.getCols().

Parameters:

arg - the data object to be checked for column rank

truncationLag - the number of rows to delete from arg before checking the rank

Returns:

true if rank(arg) == >arg.getCols(), false otherwise

Throws:

java.lang.IllegalArgumentException - if (arg == null) or if (truncationLag < 0) or if (arg.isEmpty())

imp2ExpRes

public static JSCNArray[] imp2ExpRes(JSCNArray res,
                                     JSCNArray r)

Gets the explicit representation of restrictions on the cointegrating space, given the implicit representation.
Implicit Representation: res*vec(beta') = r
Explicit Representation: vec(beta') =H*eta + h, with eta being the free parameters.

In the context of cointegration analysis, beta is the part of the Beta matrix in Beta = [I_r : beta], because the first r columns of Beta are normalized, with r being the cointegration rank. eta are the elements of beta that are freely estimated after imposing the restrictions.

Parameters:

res - the matrix with implicit restrictions (J x K-r)

r - a vector with numbers (J x 1)

Returns:

a 3 x 1 array of data objects with H, a vector of zeros and ones selecting the free elements of vec(beta') and h, respectively

Throws:

java.lang.IllegalArgumentException - if (res == null || r == null) or if (res.getRows() != r.getRows()) or if res contains restrictions that are linearly dependent

indexData

public static JSCNArray indexData(JSCNArray arg,
                                  java.lang.String newName)

Gets a new array with the elements of arg being transformed into an index with the mean of each column being normalized to +100 or -100, depending on the sign of the mean. This is usefull to compare series which differ greatly in levels. The index is computed as arg[i][j] * 100 / mean[j]

Parameters:

arg - the data object with the numbers to be transformed to an index

newName - the name of the new data object to be created

Returns:

a new data object with the indexed numbers

Throws:

java.lang.IllegalArgumentException - if (arg == null || newName == null)

mergeTS

public static JSCData[] mergeTS(JSCSArray namesOfData,
                                java.lang.String nameDat,
                                java.lang.String nameRange)

Merges time series with possibly different length and fills them with missing values at the beginning and/or the end.

Parameters:

namesOfData - data object with the names of the time series in the TSHolder

nameDat - name of the new data object which holds the observations

nameRange - name of the new data object which holds the date range

Returns:

a 2 x 1 array of data objects, the 1st element holds the observations, the 2nd element holds the earliest date of all time series defined by namesOfData

Throws:

java.lang.IllegalArgumentException - if (namesOfData == null || nameDat == null || nameRange == null)

splitDeterministics

public static JSCNArray[] splitDeterministics(JSCNArray dets,
                                              boolean zeroBased)

Takes an array with deterministic terms and computes indices for the breaks of all dummy variables. Recognized variables are impulse, extended impulse, shift dummies, and trend breaks. All other variables are ignored.

This method splits the data object with deterministic variables into the following data objects:

• data object with indices of impulses for each impulse dummy with name "impulseIndices"
• data object with start and end indices of shifts with name "extImpulseIndices"
• data object with shift start indices with name "shiftIndices"
• data object with trend break start indices with name "trendBreakIndices"

This method works only with impulse, extended impulse and shift dummies, not with seasonal summies, trend, or other deterministic variables. The following rules hold:

• impulse dummy: 0001000 (there is a sequence 010)
• extended impulse dummy: 00111000 OR 11110000 (ends with 0 and has at least one 11 sequence)
• shift dummy: 00011111 (starts with 0, ends with 11 sequence)
• trended variables like 002345678
• dummy variables that contain only 11111, 0000, or a pure trend are ignored
• dummy variables like 001000100 will be indexed like 00111100
• all other variables are ignored

Parameters:

dets - the data object containing the deterministic variables

zeroBased - whether zero based index should be used, if false then 1 based index is used (like in Gauss)

Returns:

4x1 array of data objects {impulse indices, extended impulse start/end indices, shift start indices, trend break indices}

Throws:

java.lang.IllegalArgumentException - if (dets == null)

standardize

public static JSCNArray standardize(JSCNArray dat,
                                    java.lang.String name)

Creates a new data object with the elements of dat divided by the standard devitation of the respective columns of dat.

Parameters:

dat - the original data object

name - the name of the new data object to create

Returns:

a new data object with all elements standardized

Throws:

java.lang.IllegalArgumentException - if (dat == null || name == null)

stringForArray

public static java.lang.String stringForArray(JSCSArray data)

String representation of the first row of a string data object. The elements are just printed space separated.

Parameters:

data - array containing names

Returns:

string with names, for example "y x invest cons"

Throws:

java.lang.IllegalArgumentException - if (array == null)