symnum                 package:stats                 R Documentation

_S_y_m_b_o_l_i_c _N_u_m_b_e_r _C_o_d_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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))

_A_r_g_u_m_e_n_t_s:

       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.

_V_a_l_u_e:

     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] 's[1]' c[2] 's[2]' ... 's[n]' c_[n+1]

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

_N_o_t_e:

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

_A_u_t_h_o_r(_s):

     Martin Maechler maechler@stat.math.ethz.ch

_S_e_e _A_l_s_o:

     'as.character'; 'image'

_E_x_a_m_p_l_e_s:

     ii <- 0:8; names(ii) <- ii
     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))

