\name{bandSparse}
\alias{bandSparse}
\title{Construct Sparse Banded Matrix from (Sup-/Super-) Diagonals}
\description{
Construct a sparse banded matrix by specifying its non-zero sup- and
super-diagonals.
}
\usage{
bandSparse(n, m = n, k, diagonals, symmetric = FALSE, giveCsparse = TRUE)
}
\arguments{
\item{n,m}{the matrix dimension \eqn{(n,m) = (nrow, ncol)}.}
\item{k}{integer vector of \dQuote{diagonal numbers}, with identical
meaning as in \code{\link{band}(*, k)}.}
\item{diagonals}{optional list of sub-/super- diagonals; if missing,
the result will be a patter\bold{n} matrix, i.e., inheriting from
class \code{\linkS4class{nMatrix}}.
\code{diagonals} can also be \eqn{n' \times d}{n' x 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{symmetric}{logical; if true the result will be symmetric
(inheriting from class \code{\linkS4class{symmetricMatrix}}) and
only the upper or lower triangle must be specified (via \code{k} and
\code{diagonals}).}
\item{giveCsparse}{logical indicating if the result should be a
\code{\linkS4class{CsparseMatrix}} or a
\code{\linkS4class{TsparseMatrix}}. The default, \code{TRUE} is
very often more efficient subsequently, but not always.}
}
% \details{ __needed ?__
%
% }
\value{
a sparse matrix (of \code{\link{class}}
\code{\linkS4class{CsparseMatrix}}) of dimension \eqn{n \times m}{n x m}
with diagonal \dQuote{bands} as specified.
}
%\author{Martin Maechler}
\seealso{
\code{\link{band}}, for \emph{extraction} of matrix bands;
\code{\link{bdiag}}, \code{\link{diag}},
\code{\link{sparseMatrix}},
\code{\link{Matrix}}.
}
\examples{
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)))
}
\keyword{array}
\keyword{algebra}