EVOLUTION-MANAGER

Edit File: sparseVector-class.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Sparse Vector Classes</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for sparseVector-class {Matrix}"><tr><td>sparseVector-class {Matrix}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Sparse Vector Classes</h2>

<h3>Description</h3>

Sparse Vector Classes: The virtual mother class
<code>"sparseVector"</code> has the five actual daughter classes
<code>"dsparseVector"</code>, <code>"isparseVector"</code>,
<code>"lsparseVector"</code>, <code>"nsparseVector"</code>, and
<code>"zsparseVector"</code>, where we've mainly implemented methods for
the <code>d*</code>, <code>l*</code> and <code>n*</code> ones.

<h3>Slots</h3>

<dl>
<dt><code>length</code>:</dt><dd>class <code>"numeric"</code> - the <code><a href="../../base/html/length.html">length</a></code>
of the sparse vector. Note that <code>"numeric"</code> can be
considerably larger than the maximal <code>"integer"</code>,
<code><a href="../../base/html/zMachine.html">.Machine</a>$integer.max</code>, on purpose.
</dd>
<dt><code>i</code>:</dt><dd>class <code>"numeric"</code> - the (1-based) indices of
the non-zero entries. Must not be <code>NA</code> and strictly
sorted increasingly.

Note that <code>"integer"</code> is &ldquo;part of&rdquo; <code>"numeric"</code>,
and can (and often will) be used for non-huge sparseVectors.
</dd>
<dt><code>x</code>:</dt><dd>(for all but <code>"nsparseVector"</code>):
the non-zero entries. This is of class <code>"numeric"</code> for class
<code>"dsparseVector"</code>, <code>"logical"</code> for class
<code>"lsparseVector"</code>, etc.

Note that <code>"nsparseVector"</code>s have no <code>x</code> slot.
Further, mainly for ease of method definitions, we've defined the
class union (see <code><a href="../../methods/html/setClassUnion.html">setClassUnion</a></code>) of all sparse vector
classes which have an <code>x</code> slot, as class <code>"xsparseVector"</code>.

</dd>
</dl>

<h3>Methods</h3>

<dl>
<dt>length</dt><dd><code>signature(x = "sparseVector")</code>: simply extracts
the <code>length</code> slot.
</dd>
<dt>show</dt><dd><code>signature(object = "sparseVector")</code>: The
<code><a href="../../methods/html/show.html">show</a></code> method for sparse vectors prints
&ldquo;structural&rdquo; zeroes as <code>"."</code> using the
non-exported <code>prSpVector</code> function which allows further
customization such as replacing <code>"."</code> by <code>" "</code> (blank).

Note that <code><a href="../../base/html/options.html">options</a>(max.print)</code> will influence how many
entries of large sparse vectors are printed at all.
</dd>
<dt>as.vector</dt><dd><code>signature(x = "sparseVector", mode = "character")</code>
coerces sparse vectors to &ldquo;regular&rdquo;, i.e., atomic vectors.
This is the same as <code>as(x, "vector")</code>.
</dd>
<dt>as</dt><dd>..: see <code>coerce</code> below
</dd>
<dt>coerce</dt><dd><code>signature(from = "sparseVector", to = "sparseMatrix")</code>, and
</dd>
<dt>coerce</dt><dd><code>signature(from = "sparseMatrix", to = "sparseVector")</code>,
etc: coercions to and from sparse matrices (<code><a href="sparseMatrix-class.html">sparseMatrix</a></code>) are
provided and work analogously as in standard R, i.e., a vector is
coerced to a 1-column matrix.
</dd>
<dt>dim&lt;-</dt><dd><code>signature(x = "sparseVector", value = "integer")</code>
coerces a sparse vector to a sparse Matrix, i.e., an object
inheriting from <code><a href="sparseMatrix-class.html">sparseMatrix</a></code>, of the
appropriate dimension.
</dd>
<dt>head</dt><dd><code>signature(x = "sparseVector")</code>: as with R's
(package util) <code><a href="../../utils/html/head.html">head</a></code>, <code>head(x,n)</code> (for
n &gt;= 1) is equivalent to <code>x[1:n]</code>, but here can be much
more efficient, see the example.
</dd>
<dt>tail</dt><dd><code>signature(x = "sparseVector")</code>: analogous to
<code><a href="../../utils/html/head.html">head</a></code>, see above.
</dd>
<dt>toeplitz</dt><dd><code>signature(x = "sparseVector")</code>: as
<code><a href="../../stats/html/toeplitz.html">toeplitz</a>(x)</code>, produce the n \times n
Toeplitz matrix from <code>x</code>, where <code>n = length(x)</code>.
</dd>
<dt>rep</dt><dd><code>signature(x = "sparseVector")</code> repeat <code>x</code>,
with the same argument list <code>(x, times, length.out, each,
	...)</code> as the default method for rep().
</dd>
<dt>which</dt><dd><code>signature(x = "nsparseVector")</code> and
</dd>
<dt>which</dt><dd><code>signature(x = "lsparseVector")</code> return the
indices of the non-zero entries (which is trivial for sparse vectors).
</dd>
<dt>Ops</dt><dd><code>signature(e1 = "sparseVector", e2 = "*")</code>: define
arithmetic, compare and logic operations, (see
<code><a href="../../methods/html/S4groupGeneric.html">Ops</a></code>).
</dd>
<dt>Summary</dt><dd><code>signature(x = "sparseVector")</code>: define
all the <code><a href="../../methods/html/S4groupGeneric.html">Summary</a></code> methods.
</dd>
<dt>[</dt><dd><code>signature(x = "atomicVector", i = ...)</code>: not only can you
subset (aka &ldquo;index into&rdquo;) sparseVectors <code>x[i]</code>
using sparseVectors <code>i</code>, but we also support efficient
subsetting of traditional vectors <code>x</code> by logical sparse
vectors (i.e., <code>i</code> of class <code>"nsparseVector"</code> or
<code>"lsparseVector"</code>).
</dd>
<dt>is.na, is.finite, is.infinite</dt><dd><code>(x = "sparseVector")</code>, and
</dd>
<dt>is.na, is.finite, is.infinite</dt><dd><code>(x = "nsparseVector")</code>:
return <code><a href="../../base/html/logical.html">logical</a></code> or <code>"nsparseVector"</code> of the same
length as <code>x</code>, indicating if/where <code>x</code> is
<code><a href="../../base/html/NA.html">NA</a></code> (or <code>NaN</code>), finite or infinite, entirely
analogously to the corresponding base R functions.
</dd>
</dl>

<code>c.sparseVector()</code> is an S3 method for all
<code>"sparseVector"</code>s, but automatic dispatch only happens for the
first argument, so it is useful also as regular R function, see the
examples.

<code><a href="sparseVector.html">sparseVector</a>()</code> for friendly construction of sparse
vectors (apart from <code>as(*, "sparseVector")</code>).

<h3>Examples</h3>

<pre>
getClass("sparseVector")
getClass("dsparseVector")
getClass("xsparseVector")# those with an 'x' slot

sx &lt;- c(0,0,3, 3.2, 0,0,0,-3:1,0,0,2,0,0,5,0,0)
(ss &lt;- as(sx, "sparseVector"))

ix &lt;- as.integer(round(sx))
(is &lt;- as(ix, "sparseVector")) ## an "isparseVector" (!)
(ns &lt;- sparseVector(i= c(7, 3, 2), length = 10)) # "nsparseVector"
## rep() works too:
(ri &lt;- rep(is, length.out= 25))

## Using `dim&lt;-`  as in base R :
r &lt;- ss
dim(r) &lt;- c(4,5) # becomes a sparse Matrix:
r
## or coercion (as as.matrix() in base R):
as(ss, "Matrix")
stopifnot(all(ss == print(as(ss, "CsparseMatrix"))))

## currently has "non-structural" FALSE -- printing as ":"
(lis &lt;- is &amp; FALSE)
(nn &lt;- is[is == 0]) # all "structural" FALSE

## NA-case
sN &lt;- sx; sN[4] &lt;- NA
(svN &lt;- as(sN, "sparseVector"))

v &lt;- as(c(0,0,3, 3.2, rep(0,9),-3,0,-1, rep(0,20),5,0),
         "sparseVector")
v &lt;- rep(rep(v, 50), 5000)
set.seed(1); v[sample(v@i, 1e6)] &lt;- 0
str(v)

system.time(for(i in 1:4) hv &lt;- head(v, 1e6))
##   user  system elapsed
##  0.033   0.000   0.032
system.time(for(i in 1:4) h2 &lt;- v[1:1e6])
##   user  system elapsed
##  1.317   0.000   1.319

stopifnot(identical(hv, h2),
          identical(is | FALSE, is != 0),
	  validObject(svN), validObject(lis), as.logical(is.na(svN[4])),
	  identical(is^2 &gt; 0,	is &amp; TRUE),
	  all(!lis), !any(lis), length(nn@i) == 0, !any(nn), all(!nn),
	  sum(lis) == 0, !prod(lis), range(lis) == c(0,0))

## create and use the t(.) method:
t(x20 &lt;- sparseVector(c(9,3:1), i=c(1:2,4,7), length=20))
(T20 &lt;- toeplitz(x20))
stopifnot(is(T20, "symmetricMatrix"), is(T20, "sparseMatrix"),
	  identical(unname(as.matrix(T20)),
                    toeplitz(as.vector(x20))))

## c() method for "sparseVector" - also available as regular function
(c1 &lt;- c(x20, 0,0,0, -10*x20))
(c2 &lt;- c(ns, is, FALSE))
(c3 &lt;- c(ns, !ns, TRUE, NA, FALSE))
(c4 &lt;- c(ns, rev(ns)))
## here, c() would produce a list {not dispatching to c.sparseVector()}
(c5 &lt;- c.sparseVector(0,0, x20))

## checking (consistency)
.v &lt;- as.vector
.s &lt;- function(v) as(v, "sparseVector")
stopifnot(
 all.equal(c1, .s(c(.v(x20), 0,0,0, -10*.v(x20))), tol=0),
 all.equal(c2, .s(c(.v(ns), .v(is), FALSE)), tol=0),
 all.equal(c3, .s(c(.v(ns), !.v(ns), TRUE, NA, FALSE)), tol=0),
 all.equal(c4, .s(c(.v(ns), rev(.v(ns)))), tol=0),
 all.equal(c5, .s(c(0,0, .v(x20))), tol=0)
)
</pre>

<hr /><div style="text-align: center;">[Package Matrix version 1.2-17 <a href="00Index.html">Index</a>]</div>
</body></html>