\HeaderA{bandSparse}{Construct Sparse Banded Matrix from (Sup-/Super-) Diagonals}{bandSparse}
\keyword{array}{bandSparse}
\keyword{algebra}{bandSparse}
\begin{Description}\relax
Construct a sparse banded matrix by specifying its non-zero sup- and
super-diagonals.
\end{Description}
\begin{Usage}
\begin{verbatim}
bandSparse(n, m = n, k, diagonals, symmetric = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{n,m}] the matrix dimension \eqn{(n,m) = (nrow, ncol)}{}.
\item[\code{k}] integer vector of \dQuote{diagonal numbers}, with identical
meaning as in \code{\LinkA{band}{band}(*, k)}.
\item[\code{diagonals}] optional list of sub-/super- diagonals; if missing,
the result will be a patter\bold{n} matrix, i.e., inheriting from
class \code{\LinkA{nMatrix}{nMatrix.Rdash.class}}.

\code{diagonals} can also be \eqn{n' \times d}{} matrix, where
\code{d <- length(k)} and \eqn{n' >= min(n,m)}{}.  In that case,
the sub-/super- diagonals are taken from the columns of
\code{diagonals}, where only the first several rows will be used
(typically) for off-diagonals.

\item[\code{symmetric}] logical; if true the result will be symmetric
(inheriting from class \code{\LinkA{symmetricMatrix}{symmetricMatrix.Rdash.class}}) and
only the upper or lower triangle must be specified (via \code{k} and
\code{diagonals}).
\end{ldescription}
\end{Arguments}
\begin{Value}
a sparse matrix (of \code{\LinkA{class}{class}}
\code{\LinkA{CsparseMatrix}{CsparseMatrix.Rdash.class}}) of dimension \eqn{n \times m}{}
with diagonal \dQuote{bands} as specified.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{band}{band}}, for \emph{extraction} of matrix bands;
\code{\LinkA{bdiag}{bdiag}}, \code{\LinkA{diag}{diag}},
\code{\LinkA{sparseMatrix}{sparseMatrix}},
\code{\LinkA{Matrix}{Matrix}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
diags <- list(1:30, 10*(1:20), 100*(1:20))
s1 <- bandSparse(13, k = -c(0:2, 6), diag = c(diags, diags[2]), symm=TRUE)
s1
s2 <- bandSparse(13, k =  c(0:2, 6), diag = c(diags, diags[2]), symm=TRUE)
stopifnot(identical(s1, t(s2)), is(s1,"dsCMatrix"))

## a pattern Matrix of *full* (sub-)diagonals:
bk <- c(0:4, 7,9)
(s3 <- bandSparse(30, k = bk, symm = TRUE))

## If you want a pattern matrix, but with "sparse"-diagonals,
## you currently need to go via logical sparse:
lLis <- lapply(list(rpois(20, 2), rpois(20,1), rpois(20,3))[c(1:3,2:3,3:2)],
               as.logical)
(s4 <- bandSparse(20, k = bk, symm = TRUE, diag = lLis))
(s4. <- as(drop0(s4), "nsparseMatrix"))

n <- 1e4
bk <- c(0:5, 7,11)
bMat <- matrix(1:8, n, 8, byrow=TRUE)
bLis <- as.data.frame(bMat)
B  <- bandSparse(n, k = bk, diag = bLis)
Bs <- bandSparse(n, k = bk, diag = bLis, symmetric=TRUE)
B [1:15, 1:30]
Bs[1:15, 1:30]
## can use a list *or* a matrix for specifying the diagonals:
stopifnot(identical(B,  bandSparse(n, k = bk, diag = bMat)),
          identical(Bs, bandSparse(n, k = bk, diag = bMat, symmetric=TRUE)))
\end{ExampleCode}
\end{Examples}

