R: Symbolic Number Coding

symnum {stats} | R Documentation

## Symbolic Number Coding

### Description

Symbolically encode a given numeric or logical vector or array. Particularly useful for visualization of structured matrices, e.g., correlation, sparse, or logical ones.

### Usage

    symnum(x, cutpoints = c(0.3, 0.6, 0.8, 0.9, 0.95),
           symbols = if(numeric.x) c(" ", ".", ",", "+", "*", "B")
                     else c(".", "|"),
           legend = length(symbols) >= 3,
           na = "?", eps = 1e-5, numeric.x = is.numeric(x),
           corr = missing(cutpoints) && numeric.x,
           show.max = if(corr) "1", show.min = NULL,
           abbr.colnames = has.colnames,
           lower.triangular = corr && is.numeric(x) && is.matrix(x),
           diag.lower.tri   = corr && !is.null(show.max))

### Arguments

`x` | numeric or logical vector or array.
`cutpoints` | numeric vector whose values `cutpoints[j]` == c[j] (after augmentation, see `corr` below) are used for intervals.
`symbols` | character vector, one shorter than (the augmented, see `corr` below) `cutpoints`. `symbols[j]` == s[j] are used as ‘code’ for the (half open) interval (c[j], c[j+1]]. When `numeric.x` is `FALSE`, i.e., by default when argument `x` is `logical`, the default is `c(".","|")` (graphical 0 / 1 s).
`legend` | logical indicating if a `"legend"` attribute is desired.
`na` | character or logical. How `NAs` are coded. If `na == FALSE`, `NA`s are coded invisibly, including the `"legend"` attribute below, which otherwise mentions NA coding.
`eps` | absolute precision to be used at left and right boundary.
`numeric.x` | logical indicating if `x` should be treated as numbers, otherwise as logical.
`corr` | logical. If `TRUE`, `x` contains correlations. The cutpoints are augmented by `0` and `1` and `abs(x)` is coded.
`show.max` | if `TRUE`, or of mode `character`, the maximal cutpoint is coded especially.
`show.min` | if `TRUE`, or of mode `character`, the minimal cutpoint is coded especially.
`abbr.colnames` | logical, integer or `NULL` indicating how column names should be abbreviated (if they are); if `NULL` (or `FALSE` and `x` has no column names), the column names will all be empty, i.e., `""`; otherwise if `abbr.colnames` is false, they are left unchanged. If `TRUE` or integer, existing column names will be abbreviated to `abbreviate(*, minlength = abbr.colnames)`.
`lower.triangular` | logical. If `TRUE` and `x` is a matrix, only the lower triangular part of the matrix is coded as non-blank.
`diag.lower.tri` | logical. If `lower.triangular` and this are `TRUE`, the diagonal part of the matrix is shown.

### Value

An atomic character object of class `noquote` and the same dimensions as `x`.

If `legend` is `TRUE` (as by default when there are more than two classes), the result has an attribute `"legend"` containing a legend of the returned character codes, in the form

c[1] \sQuote{s[1]} c[2] \sQuote{s[2]} … \sQuote{s[n]} c_[n+1]

where c[j]`= cutpoints[j]` and s[j]`= symbols[j]`.

### Note

The optional (mostly logical) arguments all try to use smart defaults. Specifying them explicitly may lead to considerably improved output in many cases.

### Author(s)

Martin Maechler maechler@stat.math.ethz.ch

### See Also

`as.character`; `image`

### Examples

    ii <- setNames(0:8, 0:8)
    symnum(ii, cut =  2*(0:4), sym = c(".", "-", "+", "$"))
    symnum(ii, cut =  2*(0:4), sym = c(".", "-", "+", "$"), show.max = TRUE)

    symnum(1:12 %% 3 == 0)  # --> "|" = TRUE, "." = FALSE  for logical

    ## Pascal's Triangle modulo 2 -- odd and even numbers:
    N <- 38
    pascal <- t(sapply(0:N, function(n) round(choose(n, 0:N - (N-n)%/%2))))
    rownames(pascal) <- rep("", 1+N) # <-- to improve "graphic"
    symnum(pascal %% 2, symbols = c(" ", "A"), numeric = FALSE)

    ##-- Symbolic correlation matrices:
    symnum(cor(attitude), diag = FALSE)
    symnum(cor(attitude), abbr. = NULL)
    symnum(cor(attitude), abbr. = FALSE)
    symnum(cor(attitude), abbr. = 2)

    symnum(cor(rbind(1, rnorm(25), rnorm(25)^2)))
    symnum(cor(matrix(rexp(30, 1), 5, 18))) # <<-- PATTERN ! --
    symnum(cm1 <- cor(matrix(rnorm(90) ,  5, 18))) # < White Noise SMALL n
    symnum(cm1, diag = FALSE)
    symnum(cm2 <- cor(matrix(rnorm(900), 50, 18))) # < White Noise "BIG" n
    symnum(cm2, lower = FALSE)

    ## NA's:
    Cm <- cor(matrix(rnorm(60),  10, 6)); Cm[c(3,6), 2] <- NA
    symnum(Cm, show.max = NULL)

    ## Graphical P-values (aka "significance stars"):
    pval <- rev(sort(c(outer(1:6, 10^-(1:3)))))
    symp <- symnum(pval, corr = FALSE,
                   cutpoints = c(0,  .001,.01,.05, .1, 1),
                   symbols = c("***","**","*","."," "))
    noquote(cbind(P.val = format(pval), Signif = symp))

[Package stats version 4.0.5 Index]