Construct Sparse Design / Model Matrices

Construct a sparse model or “design” matrix, from a formula and data frame (sparse.model.matrix) or a single factor (fac2sparse).

The fac2[Ss]parse() functions are utilities, also used internally in the principal user level function sparse.model.matrix().

Usage

sparse.model.matrix(object, data = environment(object),
        contrasts.arg = NULL, xlev = NULL, transpose = FALSE,
        drop.unused.levels = FALSE, row.names = TRUE,
        sep = "", verbose = FALSE, ...)

fac2sparse(from, to = c("d", "l", "n"),
     drop.unused.levels = TRUE, repr = c("C", "R", "T"), giveCsparse)
fac2Sparse(from, to = c("d", "l", "n"),
     drop.unused.levels = TRUE, repr = c("C", "R", "T"), giveCsparse,
     factorPatt12, contrasts.arg = NULL)

Arguments

object

an object of an appropriate class. For the default method, a model formula or terms object.

data

a data frame created with model.frame. If another sort of object, model.frame is called first.

contrasts.arg

for sparse.model.matrix():

A list, whose entries are contrasts suitable for input to the contrasts replacement function and whose names are the names of columns of data containing factors.

for fac2Sparse():

character string or NULL or (coercable to) "sparseMatrix", specifying the contrasts to be applied to the factor levels.

xlev

to be used as argument of model.frame if data has no "terms" attribute.

transpose

logical indicating if the transpose should be returned; if the transposed is used anyway, setting transpose = TRUE is more efficient.

drop.unused.levels

should factors have unused levels dropped? The default for sparse.model.matrix has been changed to FALSE, 2010-07, for compatibility with R's standard (dense) model.matrix().

row.names

logical indicating if row names should be used.

sep

character string passed to paste() when constructing column names from the variable name and its levels.

verbose

logical or integer indicating if (and how much) progress output should be printed.

...

further arguments passed to or from other methods.

from

(for fac2sparse():) a factor.

to

a character indicating the “kind” of sparse matrix to be returned. The default, "d" is for double.

giveCsparse

deprecated, replaced with repr; logical indicating if the result must be a CsparseMatrix.

repr

character string, one of "C", "T", or "R", specifying the sparse representation to be used for the result, i.e., one from the super classes CsparseMatrix, TsparseMatrix, or RsparseMatrix.

factorPatt12

logical vector, say fp, of length two; when fp[1] is true, return “contrasted” t(X); when fp[2] is true, the original (“dummy”) t(X), i.e, the result of fac2sparse().

Value

a sparse matrix, extending CsparseMatrix (for fac2sparse() if repr = "C" as per default; a TsparseMatrix or RsparseMatrix, otherwise).

For fac2Sparse(), a list of length two, both components with the corresponding transposed model matrix, where the corresponding factorPatt12 is true.

fac2sparse(), the basic workhorse of sparse.model.matrix(), returns the transpose (t) of the model matrix.

Note

model.Matrix(sparse = TRUE) from package MatrixModels may be nowadays be preferable to sparse.model.matrix, as model.Matrix returns an object of class modelMatrix with additional slots assign and contrasts relating to the model variables.

Author

Doug Bates and Martin Maechler, with initial suggestions from Tim Hesterberg.

See also

model.matrix in package stats, part of base R.

model.Matrix in package MatrixModels; see ‘Note’.

as(f, "sparseMatrix") (see coerce(from = "factor", ..) in the class doc sparseMatrix) produces the transposed sparse model matrix for a single factor f (and no contrasts).

Examples

dd <- data.frame(a = gl(3,4), b = gl(4,1,12))# balanced 2-way
options("contrasts") # the default:  "contr.treatment"
#> $contrasts
#>         unordered           ordered 
#> "contr.treatment"      "contr.poly" 
#> 
sparse.model.matrix(~ a + b, dd)
#> 12 x 6 sparse Matrix of class "dgCMatrix"
#>    (Intercept) a2 a3 b2 b3 b4
#> 1            1  .  .  .  .  .
#> 2            1  .  .  1  .  .
#> 3            1  .  .  .  1  .
#> 4            1  .  .  .  .  1
#> 5            1  1  .  .  .  .
#> 6            1  1  .  1  .  .
#> 7            1  1  .  .  1  .
#> 8            1  1  .  .  .  1
#> 9            1  .  1  .  .  .
#> 10           1  .  1  1  .  .
#> 11           1  .  1  .  1  .
#> 12           1  .  1  .  .  1
sparse.model.matrix(~ -1+ a + b, dd)# no intercept --> even sparser
#> 12 x 6 sparse Matrix of class "dgCMatrix"
#>    a1 a2 a3 b2 b3 b4
#> 1   1  .  .  .  .  .
#> 2   1  .  .  1  .  .
#> 3   1  .  .  .  1  .
#> 4   1  .  .  .  .  1
#> 5   .  1  .  .  .  .
#> 6   .  1  .  1  .  .
#> 7   .  1  .  .  1  .
#> 8   .  1  .  .  .  1
#> 9   .  .  1  .  .  .
#> 10  .  .  1  1  .  .
#> 11  .  .  1  .  1  .
#> 12  .  .  1  .  .  1
sparse.model.matrix(~ a + b, dd, contrasts = list(a="contr.sum"))
#> 12 x 6 sparse Matrix of class "dgCMatrix"
#>    (Intercept) a1 a2 b2 b3 b4
#> 1            1  1  .  .  .  .
#> 2            1  1  .  1  .  .
#> 3            1  1  .  .  1  .
#> 4            1  1  .  .  .  1
#> 5            1  .  1  .  .  .
#> 6            1  .  1  1  .  .
#> 7            1  .  1  .  1  .
#> 8            1  .  1  .  .  1
#> 9            1 -1 -1  .  .  .
#> 10           1 -1 -1  1  .  .
#> 11           1 -1 -1  .  1  .
#> 12           1 -1 -1  .  .  1
sparse.model.matrix(~ a + b, dd, contrasts = list(b="contr.SAS"))
#> 12 x 6 sparse Matrix of class "dgCMatrix"
#>    (Intercept) a2 a3 b1 b2 b3
#> 1            1  .  .  1  .  .
#> 2            1  .  .  .  1  .
#> 3            1  .  .  .  .  1
#> 4            1  .  .  .  .  .
#> 5            1  1  .  1  .  .
#> 6            1  1  .  .  1  .
#> 7            1  1  .  .  .  1
#> 8            1  1  .  .  .  .
#> 9            1  .  1  1  .  .
#> 10           1  .  1  .  1  .
#> 11           1  .  1  .  .  1
#> 12           1  .  1  .  .  .

## Sparse method is equivalent to the traditional one :
stopifnot(all(sparse.model.matrix(~    a + b, dd) ==
            Matrix(model.matrix(~    a + b, dd), sparse=TRUE)),
        all(sparse.model.matrix(~0 + a + b, dd) ==
            Matrix(model.matrix(~0 + a + b, dd), sparse=TRUE)))


(ff <- gl(3,4,, c("X","Y", "Z")))
#>  [1] X X X X Y Y Y Y Z Z Z Z
#> Levels: X Y Z
fac2sparse(ff) #  3 x 12 sparse Matrix of class "dgCMatrix"
#> 3 x 12 sparse Matrix of class "dgCMatrix"
#>                          
#> X 1 1 1 1 . . . . . . . .
#> Y . . . . 1 1 1 1 . . . .
#> Z . . . . . . . . 1 1 1 1
##
##  X  1 1 1 1 . . . . . . . .
##  Y  . . . . 1 1 1 1 . . . .
##  Z  . . . . . . . . 1 1 1 1

## can also be computed via sparse.model.matrix():
f30 <- gl(3,0    )
f12 <- gl(3,0, 12)
stopifnot(
  all.equal(t( fac2sparse(ff) ),
      sparse.model.matrix(~ 0+ff),
      tolerance = 0, check.attributes=FALSE),
  is(M <- fac2sparse(f30, drop= TRUE),"CsparseMatrix"), dim(M) == c(0, 0),
  is(M <- fac2sparse(f30, drop=FALSE),"CsparseMatrix"), dim(M) == c(3, 0),
  is(M <- fac2sparse(f12, drop= TRUE),"CsparseMatrix"), dim(M) == c(0,12),
  is(M <- fac2sparse(f12, drop=FALSE),"CsparseMatrix"), dim(M) == c(3,12)
 )