Class

Objects and methods for multi-companion matrices

Objects from the Class

For ordinary usage objects from this class should behave as matrices and there should be no need to access the slots directly.

Objects can be created with the function mCompanion. Other functions in the mcompanion package also produce MultiCompanion objects.

It is possible also to call new() directly:


    new("MultiCompanion", xtop, mo, n, mo.col, ido, x, dimnames,
        detect, misc)

Arguments:

xtop: is the top of the matrix.
mo: is the multi-companion order of the matrix.
n: is the dimension.
mo.col: is 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.
x: the whole 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.
misc: todo: describe this argument!

Normally one of xtop and x is supplied but if both are, they are checked for consistency, including the elements of the matrix (equality is tested with ==). To facilitate calls with one unnamed argument, when xtop is a square matrix it is taken to be the entire matrix (provided that x is missing).

Aside from xtop (or x), most of the remaining arguments can be deduced automatically. The number of rows and columns of xtop give the multi-companion order and the dimension of the matrix, respectively. A vector xtop is taken to stand for a matrix with one row. x needs to be square or a vector of length equal to exact square. mo and mo.col may be determined from the contents of x and xtop. There is no harm in ignoring mo.col but it is useful for our applications. Note that by default it is to set to the number of columns and not determined by scanning the matrix.

The contents of the misc argument are stored in the pad of the new object.

Slots

xtop:: The top of the matrix, an object of class "matrix"
mo:: Multi-companion order, an object of class "numeric"
ido:: dimension of the identity submatrix, object of class "numeric"
mo.col:: number of non-zero columns in top rows, object of class "numeric"
pad:: storage for additional info, object of class "objectPad"
x:: inherited, object of class "numeric"
Dim:: inherited, object of class "integer"
Dimnames:: inherited, object of class "list"
factors:: inherited, object of class "list"

Extends

Class "ddenseMatrix", directly. Class "generalMatrix", directly. Class "dMatrix", by class "ddenseMatrix". Class "denseMatrix", by class "ddenseMatrix". Class "Matrix", by class "ddenseMatrix". Class "Matrix", by class "ddenseMatrix". Class "compMatrix", by class "generalMatrix". Class "Matrix", by class "generalMatrix".

Methods

%*%: signature(x = "ANY", y = "MultiCompanion"): ...
%*%: signature(x = "MultiCompanion", y = "MultiCompanion"): ...
%*%: signature(x = "MultiCompanion", y = "ANY"): ...
[: signature(x = "MultiCompanion", i = "index", j = "index", drop = "logical"): ...
[: signature(x = "MultiCompanion", i = "index", j = "missing", drop = "logical"): ...
[: signature(x = "MultiCompanion", i = "missing", j = "index", drop = "logical"): ...
coerce: signature(from = "dgeMatrix", to = "MultiCompanion"): ...
coerce: signature(from = "matrix", to = "MultiCompanion"): ...
coerce: signature(from = "MultiCompanion", to = "matrix"): ...
coerce: signature(from = "MultiCompanion", to = "dgeMatrix"): ...
initialize: signature(.Object = "MultiCompanion"): This method is called implicitly when the user calls new("MultiCompanion",...).
mcStable: signature(x = "MultiCompanion"): ...
t: signature(x = "MultiCompanion"): ...
%*%: signature(x = "matrix", y = "MultiCompanion"): ...
%*%: signature(x = "MultiCompanion", y = "matrix"): ...
[: signature(x = "MultiCompanion", i = "index", j = "index", drop = "missing"): ...
[: signature(x = "MultiCompanion", i = "index", j = "missing", drop = "missing"): ...
[: signature(x = "MultiCompanion", i = "missing", j = "index", drop = "missing"): ...
%*%: signature(x = "MultiCompanion", y = "vector"): ...
%*%: signature(x = "vector", y = "MultiCompanion"): ...

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

Author

Georgi N. Boshnakov

Note

The implementation is rather redundant, this class probably should inherit in a different way from classes in Matrix package or may be not inherit at all.

Methods to get the multi-order, mo.col, and others, would be useful but first the terminology needs to be made consistent.

Other matrix arithmetic operations?

Argument n is called dim in other functions.

Examples

a1 <- matrix(1:12,nrow=2)
mc1 <- new("MultiCompanion",xtop=a1)
new("MultiCompanion",a1)   # same
#> 6 x 6 Matrix of class "MultiCompanion"
#>      [,1] [,2] [,3] [,4] [,5] [,6]
#> [1,]    1    3    5    7    9   11
#> [2,]    2    4    6    8   10   12
#> [3,]    1    0    0    0    0    0
#> [4,]    0    1    0    0    0    0
#> [5,]    0    0    1    0    0    0
#> [6,]    0    0    0    1    0    0

a2 <- matrix(c(1:6,rep(0,4)),nrow=2)   # 1st 3 columns of a2 are non-zero
mc2 <- new("MultiCompanion",a2)
mc2
#> 5 x 5 Matrix of class "MultiCompanion"
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    3    5    0    0
#> [2,]    2    4    6    0    0
#> [3,]    1    0    0    0    0
#> [4,]    0    1    0    0    0
#> [5,]    0    0    1    0    0
mc2@mo.col     # =5, because the default is to set mo.col to ncol
#> [1] 5

mc2a <- new("MultiCompanion",a2,detect="mo.col")
mc2a@mo.col   # =3, compare with above
#> [1] 3

b <- as(mc2,"matrix")  # b is ordinary R matrix
mcb <- new("MultiCompanion",x=b)
       new("MultiCompanion",b)   # same as mcb
#> 5 x 5 Matrix of class "MultiCompanion"
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    3    5    0    0
#> [2,]    2    4    6    0    0
#> [3,]    1    0    0    0    0
#> [4,]    0    1    0    0    0
#> [5,]    0    0    1    0    0

mcb@mo        # 2 (mo detected)
#> [1] 5
mcb@mo.col    # 5 (no attempt to detect mo.col)
#> [1] 5

mcba <- new("MultiCompanion",b,detect="all")
mcba@mo        # 2 (mo detected)
#> [1] 2
mcba@mo.col    # 3 (mo.col detected)
#> [1] 3

Class "MultiCompanion"