mCompanion {mcompanion}

Create objects from class MultiCompanion

Description

Create, generate, or simulate objects from class "MultiCompanion" by specifying the matrix in several ways.

Usage

mCompanion(x, detect = "nothing", misc = list(), ...)

## S4 method for signature 'MultiCompanion'
initialize(.Object, xtop, mo, n, mo.col, ido, x, dimnames,
           detect = "nothing", misc = list())

Arguments

x

the matrix or, for mCompanion only, the top of the matrix or a character string, see section ‘Details’.

misc

information to be stored in the object's pad.

...

other arguments to be passed down to generator functions, see section ‘Details’.

xtop

the top of the matrix.

mo

the multi-companion order of the matrix.

n

the dimension.

mo.col

the top order, meaniing that columns mo.col+1,...,n of the top of the matrix are zeros. mo.col may also be set to "detect", in which case it is determined by scanning xtop or x.

ido

the dimension of the identity sub-matrix.

dimnames

is not used currently.

detect

controls whether automatic detection of mo and mo.col should be attempted. The values tested are "mo", "mo.col", "all", and "nothing" with obvious meanings.

.Object

this is set implicitly by package "methods".

Details

Objects from class "MultiCompanion" can be created by calling mCompanion() or new("MultiCompanion", ...). In the latter case the “...” arguments are as for the initialize method, except .Object. Do not call initialize directly.

mCompanion can generate multi-companion matrices from spectral information, full or partial, using the methodology developed by Boshnakov and Iqelan (2009). If the specification is not given in full, the missing information is filled with suitably simulated values. For example, unspecifies eigenvalues are generated inside the unit circle, sim_mc.

If argument x is the string "sim" or "gen", then mCompanion calls sim_mc or make_mcmatrix, respectively, with the arguments ... and converts the result to class MultiCompanion. See the documentation of those functions for further details and examples. The conversion may be the main reason to use mCompanion in this way rather than call sim_mc and make_mcmatrix directly.

Otherwise, if x is numeric it is taken to specify the top of the matrix unless detect="mo" in which case it is the whole matrix. In both cases all arguments are passed down to new, the only (more or less) change being that x is passed down as xtop=x and x=x, respectively, see MultiCompanion.

detect=="gen" signifies that x has the format of the output from sim_mc or make_mcmatrix, so that mCompanion may use the additional information in such objects.

The multi-companion order is determined automatically from the content of the matrix if detect=="mo".

Value

a multi-companion matrix, an object of class "MultiCompanion"

Author(s)

Georgi N. Boshnakov

References

Boshnakov GN (2002). “Multi-companion matrices.” Linear Algebra Appl., 354, 53–83. ISSN 0024-3795, doi:10.1016/S0024-3795(01)00475-X.

Boshnakov GN (2007). “Singular value decomposition of multi-companion matrices.” Linear Algebra Appl., 424(2-3), 393–404. ISSN 0024-3795, doi:10.1016/j.laa.2007.02.010.

Boshnakov GN, Iqelan BM (2009). “Generation of time series models with given spectral properties.” J. Time Series Anal., 30(3), 349–368. ISSN 0143-9782, doi:10.1111/j.1467-9892.2009.00617.x.

See Also

sim_mc, make_mcmatrix, MultiCompanion

Examples

# simulate a 6x6 mc matrix with 2 non-trivial rows
mCompanion("sim", dim = 4, mo = 2)
# simulate a 6x6 mc matrix with 4 non-trivial rows
mCompanion("sim", dim = 6, mo = 4)
# similar to above but top rows with 2 non-zero columns
mCompanion("sim", dim = 6, mo = 4, mo.col = 2)

## specify the non-trivial top rows (as a matrix):
m1 <- matrix(1:24, nrow = 4)
mCompanion(m1)            # mc matrix with m1 on top

m2 <- rbind(c(1, 2, 0, 0), c(3, 4, 0, 0))
x2a <- mCompanion(m2)     # mc matrix with m2 on top
[e-mail]                #  = 4

x2 <- mCompanion(m2, mo.col = "detect")
[e-mail]                #  = 2,  detects the 0 columns in m2
mCompanion(m2, mo.col = 2)  # same

# create manually an mc matrix
(m3 <- rbind(m1, c(1, rep(0, 5)), c(0, 1, rep(0, 4))))
# turn it into a MultiCompanion object
x3 <- mCompanion(x = m3, detect = "mo")
x3@mo
x3 <- mCompanion(m3)
x3@mo

m4 <- rbind(c(1, 2, rep(0, 4)), c(3, 4, rep(0, 4)))

x4 <- mCompanion(m4, mo = 2)
[e-mail]    #  = 6,
## special structure not incorporated in x4,
##   eigen and mc_eigen are equiv. in this case
eigen(x4)
mc_eigen(x4)

x4a <- mCompanion(m4, mo = 2, mo.col = 2)
[e-mail]    #  = 2,  has Jordan blocks of size > 1
## the eigenvectors do not span the space:
eigen(x4a)
## mc_eigen exploits the Jordan structure, e.g.2x2 Jordan blocks,
## and gives the generalised eigenvectors:
(ev <- mc_eigen(x4a))

x4a %*% ev$vectors

## construct the Jordan matrix of x4a from eigenvalues and eigenvectors
(x4a.j <- Jordan_matrix(ev$values,  ev$len.block))

## check that AX = XJ and A = XJX^-1, up to numerical precision:
x4a %*% ev$vectors  -  ev$vectors %*% x4a.j
x4a  -  ev$vectors %*% x4a.j %*% solve(ev$vectors)