R: Format and Print Sparse Matrices Flexibly

printSpMatrix {Matrix} | R Documentation

## Format and Print Sparse Matrices Flexibly

### Description

Format and print sparse matrices flexibly. These are the “workhorses” used by the `format`, `show` and `print` methods for sparse matrices. If `x` is large, `printSpMatrix2(x)` calls `printSpMatrix()` twice, namely, for the first and the last few rows, suppressing those in between, and also suppresses columns when `x` is too wide.

`printSpMatrix()` basically prints the result of `formatSpMatrix()`.

### Usage

    formatSpMatrix(x, digits = NULL, maxp = 1e9,
                   cld = getClassDef(class(x)), zero.print = ".",
                   col.names, note.dropping.colnames = TRUE, uniDiag = TRUE,
                   align = c("fancy", "right"))

    printSpMatrix(x, digits = NULL, maxp = getOption("max.print"),
                  cld = getClassDef(class(x)),
                  zero.print = ".", col.names, note.dropping.colnames = TRUE,
                  uniDiag = TRUE, col.trailer = "",
                  align = c("fancy", "right"))

    printSpMatrix2(x, digits = NULL, maxp = getOption("max.print"),
                  zero.print = ".", col.names, note.dropping.colnames = TRUE,
                  uniDiag = TRUE, suppRows = NULL, suppCols = NULL,
                  col.trailer = if(suppCols) "......" else "",
                  align = c("fancy", "right"),
                  width = getOption("width"), fitWidth = TRUE)

### Arguments

`x` | an R object inheriting from class `sparseMatrix`.
`digits` | significant digits to use for printing, see `print.default`, the default, `NULL`, corresponds to using `getOption("digits")`.
`maxp` | integer, default from `options(max.print)`, influences how many entries of large matrices are printed at all.
`cld` | the class definition of `x`; must be equivalent to `getClassDef(class(x))` and exists mainly for possible speedup.
`zero.print` | character which should be printed for structural zeroes. The default `"."` may occasionally be replaced by `" "` (blank); using `"0"` would look almost like `print()`ing of non-sparse matrices.
`col.names` | logical or string specifying if and how column names of `x` should be printed, possibly abbreviated. The default is taken from `options("sparse.colnames")` if that is set, otherwise `FALSE` unless there are less than ten columns. When `TRUE` the full column names are printed. When `col.names` is a string beginning with `"abb"` or `"sub"` and ending with an integer `n` (i.e., of the form `"abb... <n>"`), the column names are `abbreviate()`d or `substring()`ed to (target) length `n`, see the examples.
`note.dropping.colnames` | logical specifying, when `col.names` is `FALSE` if the dropping of the column names should be noted, `TRUE` by default.
`uniDiag` | logical indicating if the diagonal entries of a sparse unit triangular or unit-diagonal matrix should be formatted as `"I"` instead of `"1"` (to emphasize that the 1's are “structural”).
`col.trailer` | a string to be appended to the right of each column; this is typically made use of by `show(<sparseMatrix>)` only, when suppressing columns.
`suppRows, suppCols` | logicals or `NULL`, for `printSpMatrix2()` specifying if rows or columns should be suppressed in printing. If `NULL`, sensible defaults are determined from `dim(x)` and `options(c("width", "max.print"))`. Setting both to `FALSE` may be a very bad idea.
`align` | a string specifying how the `zero.print` codes should be aligned, i.e., padded as strings. The default, `"fancy"`, takes some effort to align the typical `zero.print = "."` with the position of `0`, i.e., the first decimal (one left of decimal point) of the numbers printed, whereas `align = "right"` just makes use of `print(*, right = TRUE)`.
`width` | number, a positive integer, indicating the approximately desired (line) width of the output, see also `fitWidth`.
`fitWidth` | logical indicating if some effort should be made to match the desired `width` or temporarily enlarge that if deemed necessary.

### Details

formatSpMatrix:

  If `x` is large, only the first rows making up the approximately first `maxp` entries is used, otherwise all of `x`. `.formatSparseSimple()` is applied to (a dense version of) the matrix. Then, `formatSparseM` is used, unless in trivial cases or for sparse matrices without `x` slot.

### Value

`formatSpMatrix()` | returns a character matrix with possibly empty column names, depending on `col.names` etc, see above.
`printSpMatrix*()` | return `x` invisibly, see `invisible`.

### Author(s)

Martin Maechler

### See Also

the virtual class `sparseMatrix` and the classes extending it; maybe `sparseMatrix` or `spMatrix` as simple constructors of such matrices.

The underlying utilities `formatSparseM` and `.formatSparseSimple()` (on the same page).

### Examples

    f1 <- gl(5, 3, labels = LETTERS[1:5])
    X <- as(f1, "sparseMatrix")
    X ## <==>  show(X)  <==>  print(X)
    t(X) ## shows column names, since only 5 columns

    X2 <- as(gl(12, 3, labels = paste(LETTERS[1:12],"c",sep=".")),
             "sparseMatrix")
    X2
    ## less nice, but possible:
    print(X2, col.names = TRUE) # use [,1] [,2] .. => does not fit

    ## Possibilities with column names printing:
          t(X2) # suppressing column names
    print(t(X2), col.names=TRUE)
    print(t(X2), zero.print = "", col.names="abbr. 1")
    print(t(X2), zero.print = "-", col.names="substring 2")

[Package Matrix version 1.2-12 Index]