Extract.html | searchcode

/RdotNET/bin/lib/R/library/base/html/Extract.html

http://rdotnet.googlecode.com/
HTML | 321 lines | 272 code | 49 blank | 0 comment | 0 complexity | 03105f314f96165300520490d1c0e81c MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1, LGPL-2.0, BSD-3-Clause, AGPL-3.0

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html><head><title>R: Extract or Replace Parts of an Object</title>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<link rel="stylesheet" type="text/css" href="../../R.css">

</head><body>



<table width="100%" summary="page for Extract {base}"><tr><td>Extract {base}</td><td align="right">R Documentation</td></tr></table>

<h2>Extract or Replace Parts of an Object</h2>





<h3>Description</h3>



<p>

Operators acting on vectors, matrices, arrays and lists to extract or

replace parts.

</p>





<h3>Usage</h3>



<pre>

x[i]

x[i, j, ... , drop = TRUE]

x[[i]]

x[[i, j, ...]]

x$name

</pre>





<h3>Arguments</h3>



<table summary="R argblock">

<tr valign="top"><td><code>x</code></td>

<td>

object from which to extract element(s) or in which to replace element(s).

</td></tr>

<tr valign="top"><td><code>i, j, ..., name</code></td>

<td>

indices specifying elements to extract or replace.  <code>i, j</code> are

<code>numeric</code> or <code>character</code> vectors or empty (missing) or

<code>NULL</code> whereas <code>name</code> must be a character string or an

(unquoted or backtick quoted) name.  Numeric values are coerced to

integer as by <code><a href="integer.html">as.integer</a></code>.  For extraction with

<code>[[</code> and <code>$</code> character strings are normally (see under

Environments) partially matched to the <code><a href="names.html">names</a></code> of the

object if exact matching does not succeed.

<br>

For <code>[</code>-indexing only: <code>i, j, ...</code> can be logical

vectors, indicating elements/slices to select.  Such vectors are

recycled if necessary to match the corresponding extent. <code>i, j,

      ...</code> can also be negative integers, indicating elements/slices

to leave out of the selection.

<br>

When indexing arrays by <code>[</code> a single argument <code>i</code> can be a

matrix with as many columns as there are dimensions of <code>x</code>; the

result is then a vector with elements corresponding to the sets of

indices in each row of <code>i</code>.

<br>

An index value of <code>NULL</code> is treated as if it were <code>integer(0)</code>.

</td></tr>

<tr valign="top"><td><code>drop</code></td>

<td>

For matrices and arrays.  If <code>TRUE</code> the result is

coerced to the lowest possible dimension (see the examples).  This

only works for extracting elements, not for the replacement.</td></tr>

</table>



<h3>Details</h3>



<p>

These operators are generic.  You can write methods to handle indexing

of specific classes of objects, see <a href="zMethods.html">InternalMethods</a> as well as

<code><a href="Extract.data.frame.html">[.data.frame</a></code> and <code><a href="Extract.factor.html">[.factor</a></code>.  The

descriptions here apply only to the default methods.  Note that

separate methods are required for the replacement functions

<code>[&lt;-</code>, <code>[[&lt;-</code> and <code>$&lt;-</code> for use when indexing occurs on

the assignment side of an expression.

</p>

<p>

The most important distinction between <code>[</code>, <code>[[</code> and

<code>$</code> is that the <code>[</code> can select more than one element whereas

the other two select a single element.

</p>

<p>

The default methods work somewhat differently for atomic vectors,

matrices/arrays and for recursive (list-like, see

<code><a href="is.recursive.html">is.recursive</a></code>) objects.  <code>$</code> returns <code>NULL</code>

except for recursive objects, and is only discussed in the section

below on recursive objects.

</p>

<p>

Subsetting (except by an empty index) will drop all attributes except

<code>names</code>, <code>dim</code> and <code>dimnames</code>.

</p>

<p>

Indexing can occur on the right-hand-side of an expression for

extraction, or on the left-hand-side for replacement. When an index

expression appears on the left side of an assignment (known as

<EM>subassignment</EM>) then that part of <code>x</code> is set to the value

of the right hand side of the assignment.  In this case no partial

matching of indices is done, and the left-hand-side is coerced as

needed to accept the values.  Attributes are preserved (although

<code>names</code>, <code>dim</code> and <code>dinmanes</code> will be adjusted

suitably).

</p>





<h3>Atomic vectors</h3>



<p>

The usual form of indexing is <code>"["</code>.  <code>"[["</code> can be used to

select a single element, but <code>"["</code> can also do so (but will not

partially match a character index).

</p>

<p>

The index object <code>i</code> can be numeric, logical, character or empty.

Indexing by factors is allowed and is equivalent to indexing by the

numeric codes (see <code><a href="factor.html">factor</a></code>) and not by the character

values which are printed (for which use <code>[as.character(i)]</code>).

</p>

<p>

An empty index selects all values: this is most often used to replace

all the entries but keep the <code><a href="attributes.html">attributes</a></code>.

</p>





<h3>Matrices and arrays</h3>



<p>

Matrices and arrays are vectors with a dimension attribute and so all

the vector forms of indexing can be used with a single index.  The

result will be an unnamed vector unless <code>x</code> is one-dimensional

when it will be a one-dimensional array.

</p>

<p>

The most common form of indexing a <i>k</i>-dimensional array is to

specify <i>k</i> indices to <code>[</code>.  As for vector indexing, the

indices can be numeric, logical, character, empty or even factor.

An empty index (a comma separated blank) indicates that all entries in

that dimension are selected.

The argument <code>drop</code> applies to this form of indexing.

</p>

<p>

A third form of indexing is via a numeric matrix with the one column

for each dimension: each row of the index matrix then selects a single

element of the array, and the result is a vector.  Negative indices are

not allowed in the index matrix.  <code>NA</code> and zero values are allowed:

rows of an index matrix containing a zero are ignored, whereas rows

containing an <code>NA</code> produce an <code>NA</code> in the result.

</p>

<p>

A vector obtained by matrix indexing will be unnamed unless <code>x</code>

is one-dimensional when the row names (if any) will be indexed to

provide names for the result.

</p>





<h3>Recursive (list-like) objects</h3>



<p>

Indexing by <code>[</code> is similar to atomic vectors and selects a list

of the specified element(s).

</p>

<p>

Both <code>[[</code> and <code>$</code> select a single element of the list.  The

main difference is that <code>$</code> does not allow computed indices,

whereas <code>[[</code> does.  <code>x$name</code> is equivalent to

<code>x[["name"]]</code>.

</p>

<p>

<code>[</code> and <code>[[</code> are sometimes applied to other recursive

objects such as <a href="call.html">call</a>s and <a href="expression.html">expression</a>s.  Pairlists are

coerced to lists for extraction by <code>[</code>, but all three operators

can be used for replacement.

</p>

<p>

<code>[[</code> can be applied recursively to lists, so that if the single

index <code>i</code> is a vector of length <code>p</code>, <code>alist[[i]]</code> is

equivalent to <code>alist[[i1]]...[[ip]]</code> providing all but the

final indexing results in a list.

</p>

<p>

When <code>$&lt;-</code> is applied to a <code>NULL</code> <code>x</code>, it first coerces

<code>x</code> to <code>list()</code>.  This is what also happens with <code>[[&lt;-</code>

if the replacement value <code>value</code> is of length greater than one:

if <code>value</code> has length 1 or 0, <code>x</code> is first coerced to a

zero-length vector of the type of <code>value</code>.

</p>





<h3>Environments</h3>



<p>

Both <code>$</code> and <code>[[</code> can be applied to environments.  Only

character arguments are allowed and no partial matching is done. The

semantics of these operations are those of <code>get(i, env=x,

    inherits=FALSE)</code>.  If no match is found then <code>NULL</code> is

returned.  The assignment versions, <code>$&lt;-</code> and <code>[[&lt;-</code>, can

also be used.  Again, only character arguments are allowed.  The

semantics in this case are those of <code>assign(i, value, env=x,

    inherits=FALSE)</code>.  Such an assignment will either create a new

binding or change the existing binding in <code>x</code>.

</p>





<h3>NAs in indexing</h3>



<p>

When extracting, a numerical, logical or character <code>NA</code> index picks

an unknown element and so returns <code>NA</code> in the corresponding

element of a logical, integer, numeric, complex or character result,

and <code>NULL</code> for a list.  (It returns <code>00</code> for a raw result.]

</p>

<p>

When replacing (that is using indexing on the lhs of an

assignment) <code>NA</code> does not select any element to be replaced.  As

there is ambiguity as to whether an element of the rhs should

be used or not, this is only allowed if the rhs value is of length one

(so the two interpretations would have the same outcome).

</p>





<h3>Argument matching</h3>



<p>

Note that these operations do not match their index arguments in the

standard way: argument names are ignored and positional matching only is

used.  So <code>m[j=2,i=1]</code> is equivalent to <code>m[2,1]</code> and

<STRONG>not</STRONG> to <code>m[1,2]</code>.

</p>

<p>

This may not be true for methods defined for them; for example it is

not true for the <code>data.frame</code> methods described in

<code><a href="Extract.data.frame.html">[.data.frame</a></code>.

</p>

<p>

To avoid confusion, do not name index arguments (but <code>drop</code> must

be named).

</p>





<h3>Note</h3>



<p>

S uses partial matching when extracting by <code>[</code>

(Becker <EM>et al</EM> p. 358) whereas <font face="Courier New,Courier" color="#666666"><b>R</b></font> does not.

</p>

<p>

The documented behaviour of S is that an <code>NA</code> replacement index

&lsquo;goes nowhere&rsquo; but uses up an element of <code>value</code>

(Becker <EM>et al</EM> p. 359).  However, that is not the current

behaviour of S-PLUS.

</p>





<h3>References</h3>



<p>

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)

<EM>The New S Language</EM>.

Wadsworth &amp; Brooks/Cole.

</p>





<h3>See Also</h3>



<p>

<code><a href="list.html">list</a></code>, <code><a href="array.html">array</a></code>, <code><a href="matrix.html">matrix</a></code>.

</p>

<p>

<code><a href="Extract.data.frame.html">[.data.frame</a></code> and <code><a href="Extract.factor.html">[.factor</a></code> for the

behaviour when applied to data.frame and factors.

</p>

<p>

<code><a href="Syntax.html">Syntax</a></code> for operator precedence, and the

<EM>R Language</EM> reference manual about indexing details.

</p>





<h3>Examples</h3>



<pre>

x &lt;- 1:12; m &lt;- matrix(1:6,nr=2); li &lt;- list(pi=pi, e = exp(1))

x[10]                 # the tenth element of x

x &lt;- x[-1]            # delete the 1st element of x

m[1,]                 # the first row of matrix m

m[1, , drop = FALSE]  # is a 1-row matrix

m[,c(TRUE,FALSE,TRUE)]# logical indexing

m[cbind(c(1,2,1),3:1)]# matrix index

m &lt;- m[,-1]           # delete the first column of m

li[[1]]               # the first element of list li

y &lt;- list(1,2,a=4,5)

y[c(3,4)]             # a list containing elements 3 and 4 of y

y$a                   # the element of y named a



## non-integer indices are truncated:

(i &lt;- 3.999999999) # "4" is printed

(1:5)[i]  # 3



## recursive indexing into lists

z &lt;- list( a=list( b=9, c='hello'), d=1:5)

unlist(z)

z[[c(1, 2)]]

z[[c(1, 2, 1)]]  # both "hello"

z[[c("a", "b")]] &lt;- "new"

unlist(z)



## check $ and [[ for environments

e1 &lt;- new.env()

e1$a &lt;- 10

e1[["a"]]

e1[["b"]] &lt;- 20

e1$b

ls(e1)

</pre>







<hr><div align="center">[Package <em>base</em> version 2.4.0 <a href="00Index.html">Index]</a></div>



</body></html>