\Header{symnum}{Symbolic Number Coding}
\keyword{utilities}{symnum}
\keyword{character}{symnum}
\begin{Usage}
\begin{verbatim}
symnum(x, cutpoints=c(0.3, 0.6, 0.8, 0.9, 0.95),
	  symbols=c(" ", ".", ",", "+", "*", "B"),
       legend = length(symbols) >= 3,
       na="?", eps=1e-5,
       corr = missing(cutpoints), show.max = if(corr) "1", show.min = NULL,
       lower.triangular = corr & is.matrix(x),
       diag.lower.tri = corr & !is.null(show.max))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] numeric or logical vector or array.
\item[\texttt{cutpoints}] numeric vector whose values \texttt{cutpoints[j]}
\eqn{= c_j}{== c[j]}  (\emph{after} augmentation, see \texttt{corr}
below) are used for intervals.
\item[\texttt{symbols}] character vector, one shorter than (the
\emph{augmented}, see \texttt{corr} below) \texttt{cutpoints}.
\texttt{symbols[j]}\eqn{= s_j}{== s[j]} are used as ``code'' for
the (half open) interval \eqn{(c_j,c_{j+1}]}{(c[j], c[j+1]]}.

For \texttt{logical} argument \texttt{x}, the default is
\texttt{c(".","|")} (graphical 0 / 1 s).
\item[\texttt{legend}] logical indicating if a \texttt{"legend"} attribute is desired.
\item[\texttt{na}] character or logical. How \texttt{\Link{NA}s} are coded.  If
\texttt{na == FALSE}, \texttt{NA}s are coded invisibly, \emph{including}
the \texttt{"legend"} attribute below, which otherwise mentions NA coding.
\item[\texttt{eps}] absolute precision to be used at left and right boundary.
\item[\texttt{corr}] logical.  If \texttt{TRUE}, \texttt{x} contains correlations.
The cutpoints are augmented by \texttt{0} and \texttt{1} and \texttt{abs(x)}
is coded.
\item[\texttt{show.max}] If \texttt{TRUE}, or of mode \texttt{character}, the
maximal cutpoint is coded especially.
\item[\texttt{show.min}] If \texttt{TRUE}, or of mode \texttt{character}, the
minmal cutpoint is coded especially.
\item[\texttt{lower.triangular}] logical. If \texttt{TRUE} and \texttt{x} is a
matrix, only the \emph{lower triangular} part of the matrix is coded
as non-blank.
\item[\texttt{diag.lower.tri}] logical. If \texttt{lower.triangular} \emph{and}
this are \texttt{TRUE}, the \emph{diagonal} part of the matrix is shown.
\end{ldescription}
\end{Arguments}
\begin{Value}
An atomic character object of class \texttt{\Link{noquote}} and the same
dimensions as \texttt{x}.
If \texttt{legend} (\texttt{TRUE} by default when there more than 2 classes),
it has an attribute \texttt{"legend"} containing a legend
of the returned character codes, in the form
\deqn{c_1 s_1 c_2 s_2 \dots s_n c_{n+1}}{c[1] `s[1]' c[2] `s[2]' \dots `s[n]' c_[n+1]}
where \eqn{c_j}{c[j]}\texttt{ = cutpoints[j]} and
\eqn{s_j}{s[j]}\texttt{ = symbols[j]}.\end{Value}
\begin{Author}
Martin Maechler \email{maechler@stat.math.ethz.ch}\end{Author}
\begin{SeeAlso}
\texttt{\Link{as.character}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
ii _ 0:8; names(ii) _ ii
symnum(ii, cut= 2*(0:4), sym = c(".", "-", "+", "$"))
symnum(ii, cut= 2*(0:4), sym = c(".", "-", "+", "$"), show.max=T)

symnum(1:12 %% 3 == 0)# use for logical

##-- Symbolic correlation matrices:
data(attitude)
symnum(cor(attitude), diag = F)

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=F)
symnum(cm2 <- cor(matrix(rnorm(900), 50, 18))) # < White Noise "BIG" n
symnum(cm2, lower=F)

## 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=F,
		cutpoints = c(0,  .001,.01,.05, .1, 1),
		symbols	  =  c("***","**","*","."," "))
noquote(cbind(P.val = format(pval), Signif= symp))
\end{ExampleCode}
\end{Examples}

