R: A Language and Environment for Statistical Computing


R: A Language and Environment for Statistical Computing Reference Index The R Development Core Team Version 2.14.1 (2011-12-22) Copyright (©) 1999–2010 R Foundation for Statistical Computing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the R Development Core Team. R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License. For more information about these matters, see http://www.gnu.org/copyleft/gpl.html. ISBN 3-900051-07-0 Contents I 1 1 The base package3 base-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 .Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 .Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 .Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 abbreviate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 agrep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 all............................................. 11 all.equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 all.names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 any............................................. 15 aperm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 args ............................................ 20 Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 as.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 as.Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 as.environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 as.function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 as.POSIX* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 AsIs............................................ 34 assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 assignOps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 attr............................................. 39 attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 backsolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 basename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Bessel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 bindenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 body............................................ 49 i ii CONTENTS bquote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 browserText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 builtins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 by............................................. 55 c.............................................. 56 call............................................. 57 callCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 cat............................................. 61 cbind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 char.expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 charmatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 chartr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 chol ............................................ 70 chol2inv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 col............................................. 75 Colon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 colSums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 commandArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 crossprod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Cstack_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 cumsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 cut............................................. 106 cut.POSIXt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 data.class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 data.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 date ............................................ 114 Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 DateTimeClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 dcf............................................. 119 debug ........................................... 121 Defunct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 delayedAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 CONTENTS iii deparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 deparseOpts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 det............................................. 128 detach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 diag ............................................ 130 diff............................................. 132 difftime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 dim ............................................ 135 dimnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 do.call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 dput............................................ 141 drop............................................ 143 droplevels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 dump ........................................... 145 duplicated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 dyn.load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 eapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 eigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 encodeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 EnvVar .......................................... 160 eval ............................................ 162 exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 expand.grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Extract.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Extract.factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Extremes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 file.access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 file.choose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 file.info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 file.path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 file.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 files ............................................ 188 files2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 find.package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 findInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Foreign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 formals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 format.info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 format.pval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 iv CONTENTS formatC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 formatDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 funprog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 gc ............................................. 213 gc.time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 gctorture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 get............................................. 217 getDLLRegisteredRoutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 getLoadedDLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 getNativeSymbolInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 getwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 gl ............................................. 226 grep............................................ 227 grepRaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 groupGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 gzcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 hexmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Hyperbolic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 iconv............................................ 240 icuSetCollate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 identical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 ifelse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Internal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 InternalMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 invisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 is.finite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 is.function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 is.language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 is.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 is.R ............................................ 257 is.recursive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 is.single . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 is.unsorted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 ISOdatetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 isS4 ............................................ 261 isSymmetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 jitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 kappa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 kronecker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 l10n_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 lapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 CONTENTS v Last.value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 levels ........................................... 273 libPaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 library.dynam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 list............................................. 282 list.files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 list2env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 load ............................................ 287 locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 log............................................. 290 Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 lower.tri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 ls.............................................. 296 make.names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 make.unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 mapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 margin.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 mat.or.vec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 match.arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 match.call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 match.fun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 MathFun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 matmult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 maxCol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 mean............................................ 313 memCompress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Memory-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 memory.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 merge ........................................... 319 message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 missing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 mode ........................................... 323 NA............................................. 325 name............................................ 326 names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 nargs............................................ 329 nchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 nlevels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 noquote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 norm............................................ 334 normalizePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 vi CONTENTS NotYet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 nrow............................................ 337 ns-dblcolon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 ns-hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 ns-load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 ns-topenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 NULL........................................... 343 numeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 NumericConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 numeric_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 octmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 on.exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Ops.Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 outer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Paren ........................................... 362 parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 path.expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 pmatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 polyroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 pos.to.env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 pretty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 print.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 print.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 prmatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 proc.time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 prod............................................ 379 prop.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 pushBack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 qr ............................................. 382 QR.Auxiliaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 quit ............................................ 386 Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 R.Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Random . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 Random.user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 rank............................................ 398 rapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 raw ............................................ 401 rawConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 rawConversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 RdUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 readBin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 CONTENTS vii readChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 readLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 readRDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 readRenviron . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 real ............................................ 416 Recall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 reg.finalizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 regex............................................ 418 regmatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 remove .......................................... 424 rep............................................. 425 replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 Reserved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 rev............................................. 428 Rhome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 rle............................................. 430 Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 round.POSIXt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 row ............................................ 433 row+colnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 row.names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 rowsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 save ............................................ 440 scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 scan............................................ 444 search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 seek............................................ 449 seq............................................. 450 seq.Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 seq.POSIXt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 sets ............................................ 458 setTimeLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 showConnections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 shQuote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 sign ............................................ 463 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 sink ............................................ 464 slice.index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 slotOp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 socketSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 solve............................................ 468 sort ............................................ 470 source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 Special . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 viii CONTENTS split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 sQuote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 srcfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 stop ............................................ 491 stopifnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 strptime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 strsplit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 strtoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 strtrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502 strwrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 subset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 substitute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506 substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 sum ............................................ 509 summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 svd............................................. 512 sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 Sys.getenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 Sys.getpid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Sys.glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 Sys.info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Sys.localeconv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 sys.parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Sys.readlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Sys.setenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 Sys.setFileTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Sys.sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 sys.source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Sys.time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Sys.which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 system.file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 system.time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 system2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 t.............................................. 538 table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 tabulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 tapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 taskCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 taskCallbackManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 taskCallbackNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 tempfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 textConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 CONTENTS ix tilde . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 timezones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 traceback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 tracemem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Trig ............................................ 565 try............................................. 566 typeof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 unlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 unname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 UseMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 userhooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 utf8Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Vectorize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 weekdays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 which.min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 with............................................ 589 withVisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 writeLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 xtfrm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 zapsmall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 zpackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 zutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 2 The datasets package 597 datasets-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 ability.cov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 airmiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 AirPassengers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 airquality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 anscombe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 attenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 attitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 austres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 beavers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 BJsales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 BOD............................................ 607 cars ............................................ 608 ChickWeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 chickwts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610 x CONTENTS CO2............................................ 611 co2............................................. 612 crimtab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 discoveries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 DNase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 esoph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 euro............................................ 618 eurodist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 EuStockMarkets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 faithful . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Formaldehyde . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 freeny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 HairEyeColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 Harman23.cor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 Harman74.cor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Indometh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 infert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 InsectSprays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 iris............................................. 628 islands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 JohnsonJohnson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 LakeHuron . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 lh ............................................. 632 LifeCycleSavings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 Loblolly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 longley . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 lynx............................................ 635 morley . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 mtcars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 nhtemp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 Nile ............................................ 638 nottem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 occupationalStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 Orange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 OrchardSprays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 PlantGrowth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 precip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 presidents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 pressure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 Puromycin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 quakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 randu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 rivers ........................................... 649 rock............................................ 650 sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 stackloss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 sunspot.month . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 CONTENTS xi sunspot.year . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 sunspots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 swiss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 Theoph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 Titanic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659 ToothGrowth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 treering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 UCBAdmissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 UKDriverDeaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 UKgas........................................... 665 UKLungDeaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 USAccDeaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 USArrests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 USJudgeRatings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 USPersonalExpenditure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 uspop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 VADeaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 volcano . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 warpbreaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 women........................................... 672 WorldPhones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 WWWusage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 3 The grDevices package 675 grDevices-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 adjustcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 as.graphicsAnnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 as.raster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 axisTicks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 boxplot.stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 cairo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682 check.options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684 chull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 cm............................................. 686 col2rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 colorRamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688 colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690 contourLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 convertColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 densCols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 dev............................................. 695 dev.capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 dev.capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 dev.flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 dev.interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 dev.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 dev2............................................ 701 dev2bitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 xii CONTENTS devAskNewPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 embedFonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 extendrange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 getGraphicsEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 gray............................................ 712 gray.colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 hcl............................................. 714 Hershey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 hsv............................................. 719 Japanese . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 make.rgb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 n2mfrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 nclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725 Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 pdf............................................. 728 pdf.options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732 pictex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 plotmath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 png ............................................ 740 postscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 postscriptFonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 pretty.Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753 ps.options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 quartz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755 quartzFonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 recordGraphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 recordPlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 rgb............................................. 761 rgb2hsv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762 savePlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764 trans3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765 Type1Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 x11 ............................................ 767 X11Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 xfig ............................................ 773 xy.coords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 xyTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 xyz.coords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778 4 The graphics package 781 graphics-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 abline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783 assocplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785 Axis............................................ 786 axis ............................................ 787 axis.POSIXct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790 CONTENTS xiii axTicks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791 barplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 box ............................................ 797 boxplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798 boxplot.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 bxp ............................................ 802 cdplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805 clip ............................................ 807 contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 convertXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811 coplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812 curve ........................................... 815 dotchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817 filled.contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819 fourfoldplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821 frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823 grid ............................................ 824 hist............................................. 825 hist.POSIXt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 identify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832 layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 matplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844 mosaicplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847 mtext ........................................... 850 pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852 panel.smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 par............................................. 855 persp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 pie............................................. 868 plot ............................................ 870 plot.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871 plot.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 plot.design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875 plot.factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 plot.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878 plot.histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879 plot.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881 plot.window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882 plot.xy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883 points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884 polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888 polypath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 rasterImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892 rect ............................................ 894 xiv CONTENTS rug............................................. 895 screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896 segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899 smoothScatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 spineplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904 stem............................................ 908 stripchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 strwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911 sunflowerplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 text ............................................ 917 title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920 units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921 xspline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 5 The grid package 925 grid-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925 absolute.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926 arrow ........................................... 927 convertNative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 dataViewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929 drawDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930 editDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931 gEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 getNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933 gpar............................................ 933 gPath ........................................... 935 Grid............................................ 936 Grid Viewports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 grid.add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 grid.arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942 grid.cap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944 grid.circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 grid.clip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 grid.collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948 grid.convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949 grid.copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951 grid.curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952 grid.display.list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954 grid.draw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955 grid.edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956 grid.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 grid.function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958 grid.get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960 grid.grab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 grid.grill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963 grid.grob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964 grid.layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965 CONTENTS xv grid.lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967 grid.locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 grid.ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970 grid.move.to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972 grid.newpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 grid.null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975 grid.pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976 grid.path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 grid.place . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980 grid.plot.and.legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981 grid.points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981 grid.polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982 grid.pretty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984 grid.prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985 grid.raster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986 grid.record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 grid.rect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989 grid.refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990 grid.remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991 grid.segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 grid.set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 grid.show.layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 grid.show.viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 grid.text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 grid.xaxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 grid.xspline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000 grid.yaxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003 grobName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 grobWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005 grobX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005 plotViewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006 pop.viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007 push.viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 Querying the Viewport Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 roundrect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010 showGrob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011 showViewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012 stringWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014 unit ............................................ 1014 unit.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016 unit.length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017 unit.pmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018 unit.rep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018 valid.just . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019 validDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020 vpPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021 widthDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022 Working with Viewports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022 xvi CONTENTS xDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025 xsplinePoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026 6 The methods package 1027 methods-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027 .BasicFunsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028 as ............................................. 1028 BasicClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032 callGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034 callNextMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036 canCoerce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038 cbind2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040 classesToAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044 className . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045 classRepresentation-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048 dotsMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050 environment-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053 envRefClass-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054 evalSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055 findClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 findMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060 fixPre1.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063 genericFunction-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064 GenericFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065 getClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069 getMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070 getPackageName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073 hasArg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074 implicitGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075 inheritedSlotNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077 initialize-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078 is.............................................. 1080 isSealedMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085 language-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086 LinearMethodsList-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087 makeClassRepresentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088 method.skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089 MethodDefinition-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 MethodsList-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100 MethodWithNext-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101 new ............................................ 1102 nonStructure-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104 ObjectsWithPackage-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105 promptClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105 promptMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107 ReferenceClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108 CONTENTS xvii representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117 S3Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119 S4groupGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123 SClassExtension-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125 selectSuperClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126 setClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127 setClassUnion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131 setGeneric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133 setMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139 setOldClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142 show............................................ 1147 showMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148 signature-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151 slot............................................. 1152 StructureClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153 testInheritedMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156 TraceClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157 validObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158 7 The splines package 1161 splines-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161 asVector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161 backSpline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162 bs ............................................. 1163 interpSpline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164 ns ............................................. 1166 periodicSpline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167 polySpline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1168 predict.bs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169 predict.bSpline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170 splineDesign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171 splineKnots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172 splineOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173 xyVector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174 8 The stats package 1175 stats-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175 .checkMFClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175 acf............................................. 1176 acf2AR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178 add1............................................ 1179 addmargins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182 aggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183 AIC ............................................ 1186 alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1188 anova ........................................... 1190 anova.glm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191 anova.lm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192 anova.mlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194 xviii CONTENTS ansari.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196 aov............................................. 1198 approxfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200 ar ............................................. 1202 ar.ols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1206 arima . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208 arima.sim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211 arima0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213 ARMAacf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216 ARMAtoMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217 as.hclust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218 asOneSidedFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219 ave............................................. 1220 bandwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221 bartlett.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223 Beta............................................ 1224 binom.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227 Binomial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228 biplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230 biplot.princomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232 birthday . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233 Box.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 C.............................................. 1236 cancor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1237 case+variable.names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1238 Cauchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239 chisq.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240 Chisquare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243 cmdscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246 coef ............................................ 1248 complete.cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249 confint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249 constrOptim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250 contrast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253 contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254 convolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256 cophenetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257 cor............................................. 1259 cor.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261 cov.wt........................................... 1264 cpgram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265 cutree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266 decompose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267 delete.response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269 dendrapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270 dendrogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1272 density . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276 deriv............................................ 1280 CONTENTS xix deviance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282 df.residual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283 diffinv........................................... 1284 dist............................................. 1285 Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288 dummy.coef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289 ecdf ............................................ 1290 eff.aovlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293 effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294 embed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296 expand.model.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296 Exponential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297 extractAIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299 factanal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301 factor.scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304 family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305 FDist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309 fft ............................................. 1311 filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312 fisher.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313 fitted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316 fivenum .......................................... 1317 fligner.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318 formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1319 formula.nls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321 friedman.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322 ftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324 ftable.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326 GammaDist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328 Geometric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330 getInitial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331 glm ............................................ 1332 glm.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337 glm.summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339 hclust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340 heatmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 HoltWinters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346 Hypergeometric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349 identify.hclust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351 influence.measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352 integrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355 interaction.plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357 IQR ............................................ 1360 is.empty.model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 isoreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 KalmanLike . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363 kernapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365 kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366 xx CONTENTS kmeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368 kruskal.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369 ks.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371 ksmooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374 lag............................................. 1375 lag.plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376 line ............................................ 1377 lm............................................. 1378 lm.fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382 lm.influence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383 lm.summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385 loadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386 loess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387 loess.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390 Logistic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391 logLik . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392 loglin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394 Lognormal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396 lowess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 ls.diag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399 ls.print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400 lsfit ............................................ 1401 mad ............................................ 1402 mahalanobis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1403 make.link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404 makepredictcall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405 manova .......................................... 1406 mantelhaen.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407 mauchly.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410 mcnemar.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411 median . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413 medpolish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414 model.extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415 model.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416 model.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419 model.tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1420 monthplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422 mood.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424 Multinom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425 na.action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1427 na.contiguous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428 na.fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428 naprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429 naresid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430 NegBinomial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431 nextn ........................................... 1433 nlm ............................................ 1434 nlminb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436 CONTENTS xxi nls............................................. 1439 nls.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444 NLSstAsymptotic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446 NLSstClosestX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447 NLSstLfAsymptote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447 NLSstRtAsymptote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448 nobs............................................ 1449 Normal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1450 numericDeriv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452 offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453 oneway.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453 optim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455 optimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460 order.dendrogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462 p.adjust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463 pairwise.prop.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1466 pairwise.t.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1466 pairwise.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1468 pairwise.wilcox.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1468 plot.acf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469 plot.density . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471 plot.HoltWinters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471 plot.isoreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1472 plot.lm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1474 plot.ppr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1477 plot.profile.nls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478 plot.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 plot.stepfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1480 plot.ts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1482 Poisson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484 poisson.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486 poly............................................ 1487 power ........................................... 1489 power.anova.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490 power.prop.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491 power.t.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492 PP.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493 ppoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495 ppr............................................. 1496 prcomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499 predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501 predict.Arima . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1503 predict.glm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504 predict.HoltWinters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506 predict.lm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507 predict.loess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509 predict.nls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1511 predict.smooth.spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512 xxii CONTENTS preplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514 princomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514 print.power.htest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517 print.ts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518 printCoefmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518 profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1520 profile.nls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521 proj ............................................ 1522 prop.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524 prop.trend.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526 qqnorm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1527 quade.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1528 quantile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1530 r2dtable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533 read.ftable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1534 rect.hclust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536 relevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537 reorder.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1538 reorder.dendrogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1539 replications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1540 reshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1541 residuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544 runmed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545 scatter.smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1547 screeplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1548 sd ............................................. 1549 se.contrast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550 selfStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552 setNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1554 shapiro.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555 SignRank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556 simulate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557 smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559 smooth.spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1561 smoothEnds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565 sortedXyData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566 spec.ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1567 spec.pgram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1568 spec.taper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570 spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1571 splinefun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1573 SSasymp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576 SSasympOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577 SSasympOrig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1578 SSbiexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579 SSD............................................ 1580 SSfol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1581 SSfpl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582 CONTENTS xxiii SSgompertz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1583 SSlogis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1584 SSmicmen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585 SSweibull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1586 start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587 stat.anova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588 stats-deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1589 step ............................................ 1589 stepfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592 stl ............................................. 1594 stlmethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596 StructTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597 summary.aov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599 summary.glm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1601 summary.lm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603 summary.manova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605 summary.nls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1606 summary.princomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608 supsmu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1609 symnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1610 t.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1612 TDist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614 termplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617 terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619 terms.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620 terms.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621 time............................................ 1622 toeplitz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623 ts.............................................. 1624 ts-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626 ts.plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1627 ts.union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628 tsdiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629 tsp............................................. 1630 tsSmooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630 Tukey ........................................... 1631 TukeyHSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632 Uniform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634 uniroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635 update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1637 update.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638 var.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639 varimax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641 vcov............................................ 1642 Weibull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643 weighted.mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1644 weighted.residuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645 weights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646 xxiv CONTENTS wilcox.test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647 Wilcoxon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650 window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1652 xtabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654 9 The stats4 package 1657 stats4-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657 coef-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657 confint-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658 logLik-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658 mle ............................................ 1659 mle-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1660 plot-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661 profile-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1662 profile.mle-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663 show-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664 summary-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664 summary.mle-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664 update-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665 vcov-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666 10 The tcltk package 1667 tcltk-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1667 TclInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668 tclServiceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672 TkCommands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673 tkpager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676 tkProgressBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1677 tkStartGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678 TkWidgetcmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679 TkWidgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682 tk_choose.dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684 tk_choose.files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684 tk_messageBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 tk_select.list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686 11 The tools package 1689 tools-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 add_datalist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689 bibstyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1690 buildVignettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692 charsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1693 checkFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694 checkMD5sums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695 checkRd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696 checkRdaFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698 checkTnF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699 checkVignettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1700 codoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701 CONTENTS xxv compactPDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703 delimMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1704 dependsOnPkgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705 encoded_text_to_latex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706 fileutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707 getDepList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709 HTMLheader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710 HTMLlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1711 installFoundDepends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712 md5sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713 package.dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714 parseLatex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714 parse_Rd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715 pskill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717 psnice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718 QC............................................. 1719 Rd2HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720 Rd2txt_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1723 Rdiff............................................ 1724 Rdindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 RdTextFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726 Rdutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727 read.00Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728 readNEWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1729 showNonASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 startDynamicHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731 SweaveTeXFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732 testInstalledPackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733 texi2dvi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1734 toHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1735 tools-deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736 toRd............................................ 1736 undoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737 vignetteDepends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 write_PACKAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739 xgettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741 12 The utils package 1743 utils-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743 adist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743 alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745 apropos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746 aregexec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747 aspell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749 aspell-utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750 available.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752 BATCH .......................................... 1753 bibentry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754 browseEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758 xxvi CONTENTS browseURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759 browseVignettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761 bug.report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762 capture.output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1764 chooseBioCmirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765 chooseCRANmirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766 citation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 citEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768 close.socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769 combn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770 compareVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771 COMPILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772 contrib.url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773 count.fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773 create.post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774 data ............................................ 1776 dataentry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778 debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780 demo ........................................... 1782 download.file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783 download.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785 edit ............................................ 1787 edit.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1790 file.edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792 file_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793 findLineNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794 fix............................................. 1796 flush.console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797 format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797 getAnywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798 getFromNamespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799 getS3method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1801 glob2rx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802 head............................................ 1803 help ............................................ 1805 help.request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1807 help.search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809 help.start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811 INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813 install.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815 installed.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818 LINK ........................................... 1820 localeToCharset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820 ls.str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821 maintainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1823 make.packages.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824 make.socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825 CONTENTS xxvii memory.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1826 menu ........................................... 1827 methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828 mirrorAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829 modifyList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1830 news............................................ 1831 nsl............................................. 1832 object.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1833 package.skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834 packageDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1836 packageStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837 page............................................ 1839 person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840 PkgUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842 prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843 promptData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845 promptPackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846 Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848 rcompgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850 read.DIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1855 read.fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857 read.fwf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1858 read.socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860 read.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861 recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866 relist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868 REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870 remove.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 removeSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871 RHOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872 roman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872 Rprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1873 Rprofmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1874 Rscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876 RShowDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877 RSiteSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878 rtags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1879 Rtangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881 RweaveLatex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1883 savehistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887 select.list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888 sessionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889 setRepositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1890 SHLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892 sourceutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893 stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894 str............................................. 1896 summaryRprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898 xxviii CONTENTS Sweave .......................................... 1900 SweaveSyntConv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902 tar............................................. 1903 toLatex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905 txtProgressBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1906 type.convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1908 untar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909 unzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910 update.packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912 url.show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1914 URLencode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915 utils-deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916 View............................................ 1916 vignette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917 write.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1919 zip............................................. 1922 II 1925 13 The KernSmooth package 1927 bkde............................................ 1927 bkde2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1928 bkfe............................................ 1930 dpih............................................ 1931 dpik............................................ 1932 dpill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1934 locpoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935 14 The MASS package 1939 abbey ........................................... 1939 accdeaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939 addterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1940 Aids2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942 Animals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1943 anorexia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1943 anova.negbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1944 area ............................................ 1945 bacteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946 bandwidth.nrd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947 bcv............................................. 1948 beav1 ........................................... 1949 beav2 ........................................... 1950 Belgian-phones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1951 biopsy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1952 birthwt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953 Boston . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1954 boxcox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1955 cabbages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956 CONTENTS xxix caith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1957 Cars93 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958 cats ............................................ 1959 cement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1960 chem............................................ 1961 con2tr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1961 confint-MASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1962 contr.sdif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963 coop............................................ 1964 corresp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1965 cov.rob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1966 cov.trob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1968 cpus............................................ 1970 crabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971 Cushings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1972 DDT............................................ 1972 deaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973 denumerate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973 dose.p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974 drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975 dropterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976 eagles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977 epil ............................................ 1978 eqscplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1980 farms ........................................... 1981 fgl............................................. 1982 fitdistr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983 forbes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985 fractions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985 GAGurine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986 galaxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1987 gamma.dispersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1988 gamma.shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1989 gehan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1990 genotype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991 geyser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1992 gilgais . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1992 ginv ............................................ 1993 glm.convert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1994 glm.nb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995 glmmPQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996 hills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998 hist.scott . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998 housing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999 huber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001 hubers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002 immer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003 Insurance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004 xxx CONTENTS isoMDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2005 kde2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006 lda............................................. 2007 ldahist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010 leuk ............................................ 2011 lm.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012 lm.ridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013 loglm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015 logtrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017 lqs............................................. 2019 mammals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022 mca ............................................ 2022 mcycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023 Melanoma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024 menarche . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024 michelson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2025 minn38 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026 motors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027 muscle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028 mvrnorm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2029 negative.binomial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030 newcomb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031 nlschools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2031 npk ............................................ 2032 npr1............................................ 2033 Null............................................ 2034 oats ............................................ 2035 OME ........................................... 2036 painters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039 pairs.lda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040 parcoord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2041 petrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2042 Pima.tr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043 plot.lda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2044 plot.mca . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2045 plot.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2045 polr ............................................ 2046 predict.glmmPQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049 predict.lda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2050 predict.lqs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2052 predict.mca . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2053 predict.qda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054 profile.glm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055 qda............................................. 2056 quine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2058 Rabbit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059 rational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2060 renumerate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061 CONTENTS xxxi rlm............................................. 2062 rms.curv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2064 rnegbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2065 road............................................ 2066 rotifer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067 Rubber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067 sammon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068 ships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2069 shoes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070 shrimp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070 shuttle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2071 Sitka . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2071 Sitka89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2072 Skye............................................ 2073 snails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074 SP500 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2075 stdres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2075 steam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2076 stepAIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077 stormer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079 studres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2080 summary.loglm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2080 summary.negbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081 summary.rlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2082 survey........................................... 2084 synth.tr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2085 theta.md . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2085 topo............................................ 2087 Traffic........................................... 2087 truehist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2088 ucv............................................. 2089 UScereal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2090 UScrime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091 VA............................................. 2092 waders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093 whiteside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2094 width.SJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095 write.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2096 wtloss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097 15 The Matrix package 2099 abIndex-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2099 abIseq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100 all-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2101 all.equal-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102 atomicVector-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2103 band............................................ 2103 bandSparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105 bdiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2106 xxxii CONTENTS BunchKaufman-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107 CAex ........................................... 2108 cBind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2109 CHMfactor-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110 chol ............................................ 2113 chol2inv-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114 Cholesky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115 Cholesky-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2117 colSums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2118 compMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2120 condest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2120 CsparseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2122 ddenseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2124 ddiMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2125 denseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126 dgCMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126 dgeMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2127 dgRMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129 dgTMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130 Diagonal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2131 diagonalMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2133 diagU2N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134 dMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135 dpoMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137 drop0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138 dsCMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139 dsparseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2141 dsRMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2142 dsyMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143 dtCMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2145 dtpMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146 dtRMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2148 dtrMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149 expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150 expm ........................................... 2151 externalFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2152 facmul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154 forceSymmetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155 formatSparseM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156 generalMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158 Hilbert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158 image-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159 index-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2161 is.na-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2161 isSymmetric-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162 KNex ........................................... 2162 kronecker-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163 ldenseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2164 CONTENTS xxxiii ldiMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165 lgeMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2166 lsparseMatrix-classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167 lsyMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168 ltrMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169 lu ............................................. 2170 LU-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2172 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2173 Matrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2175 MatrixFactorization-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2177 ndenseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178 nearPD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2179 ngeMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182 nMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183 nnzero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2184 norm............................................ 2185 nsparseMatrix-classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186 nsyMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2188 ntrMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2189 number-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2190 pMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191 printSpMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192 qr-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2195 rankMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2195 rcond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196 rep2abI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2199 replValue-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2199 rleDiff-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200 RsparseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2201 Schur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2202 Schur-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203 sparse.model.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2204 sparseLU-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205 SparseM-conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207 sparseMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2208 sparseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2210 sparseQR-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212 sparseVector-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2214 spMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216 symmetricMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217 symmpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218 tcrossprod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219 triangularMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220 TsparseMatrix-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221 unpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222 Unused-classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223 USCounties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223 xtabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224 xxxiv CONTENTS [-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226 [<–methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227 16 The boot package 2229 abc.ci . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229 acme............................................ 2231 aids ............................................ 2231 aircondit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2232 amis............................................ 2233 aml ............................................ 2234 beaver........................................... 2235 bigcity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236 boot............................................ 2237 boot.array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2243 boot.ci . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2244 brambles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248 breslow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248 calcium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249 cane............................................ 2250 capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251 catsM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252 cav............................................. 2253 cd4............................................. 2253 cd4.nested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254 censboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255 channing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259 claridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260 cloth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261 co.transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262 coal ............................................ 2263 control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263 corr ............................................ 2265 cum3 ........................................... 2266 cv.glm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267 darwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2269 dogs............................................ 2270 downs.bc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270 ducks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271 EEF.profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2272 empinf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273 envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276 exp.tilt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278 fir ............................................. 2280 freq.array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280 frets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281 glm.diag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282 glm.diag.plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283 gravity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284 hirose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285 CONTENTS xxxv Imp.Estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286 imp.weights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288 inv.logit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290 islay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290 jack.after.boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291 k3.linear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293 linear.approx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2294 lines.saddle.distn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2296 logit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298 manaus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298 melanoma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299 motor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2300 neuro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301 nitrofen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302 nodal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2303 norm.ci . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304 nuclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306 paulsen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2307 plot.boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308 poisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2310 polar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311 print.boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312 print.bootci . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313 print.saddle.distn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314 print.simplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314 remission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315 saddle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316 saddle.distn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318 saddle.distn.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2321 salinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2322 simplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2323 simplex.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2325 smooth.f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2326 sunspot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2328 survival . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2328 tau............................................. 2329 tilt.boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2330 tsboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2333 tuna ............................................ 2337 urine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2338 var.linear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2339 wool............................................ 2340 17 The class package 2341 batchSOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2341 condense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2342 knn ............................................ 2343 knn.cv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2344 knn1............................................ 2346 xxxvi CONTENTS lvq1............................................ 2347 lvq2............................................ 2348 lvq3............................................ 2349 lvqinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2350 lvqtest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2351 multiedit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2352 olvq1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2353 reduce.nn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2354 SOM............................................ 2355 somgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2357 18 The cluster package 2359 agnes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359 agnes.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2362 agriculture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2363 animals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2364 bannerplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2365 chorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2366 clara . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2367 clara.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2370 clusplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2371 clusplot.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2372 coef.hclust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377 daisy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2378 diana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2381 dissimilarity.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2383 ellipsoidhull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2384 fanny ........................................... 2386 fanny.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2389 flower........................................... 2390 lower.to.upper.tri.inds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2391 mona ........................................... 2392 mona.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2393 pam ............................................ 2394 pam.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2396 partition.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2398 plantTraits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2399 plot.agnes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2401 plot.diana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2403 plot.mona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2405 plot.partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2406 pltree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2408 pltree.twins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2408 pluton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2410 predict.ellipsoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411 print.agnes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2412 print.clara . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2412 print.diana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2413 print.dissimilarity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2414 CONTENTS xxxvii print.fanny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2415 print.mona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2415 print.pam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2416 ruspini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2416 silhouette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417 sizeDiss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2420 summary.agnes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2421 summary.clara . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2422 summary.diana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2423 summary.mona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2423 summary.pam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2424 twins.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2424 volume.ellipsoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2425 votes.repub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2426 xclara . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2426 19 The codetools package 2427 checkUsage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2427 codetools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2428 findGlobals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2430 showTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2431 20 The foreign package 2433 lookup.xport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2433 read.arff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2434 read.dbf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2435 read.dta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2436 read.epiinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2437 read.mtp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2439 read.octave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2440 read.spss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441 read.ssd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2443 read.systat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2444 read.xport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2446 S3 read functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2447 write.arff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2448 write.dbf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2449 write.dta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2450 write.foreign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2452 21 The lattice package 2455 A_01_Lattice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2455 B_00_xyplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2458 B_01_xyplot.ts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2477 B_02_barchart.table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2480 B_03_histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481 B_04_qqmath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2486 B_05_qq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2489 B_06_levelplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2491 xxxviii CONTENTS B_07_cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2496 B_08_splom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2502 B_09_tmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2506 B_10_rfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2508 B_11_oneway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2509 C_01_trellis.device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2510 C_02_trellis.par.get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2512 C_03_simpleTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2514 C_04_lattice.options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2516 C_05_print.trellis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2517 C_06_update.trellis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521 C_07_shingles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2523 D_draw.colorkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2525 D_draw.key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2526 D_level.colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2527 D_make.groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2528 D_simpleKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2529 D_strip.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2530 D_trellis.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2533 E_interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2534 F_1_panel.barchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2540 F_1_panel.bwplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2542 F_1_panel.cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2544 F_1_panel.densityplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549 F_1_panel.dotplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2550 F_1_panel.histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2551 F_1_panel.levelplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2552 F_1_panel.pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2554 F_1_panel.parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2557 F_1_panel.qqmath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2559 F_1_panel.stripplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2560 F_1_panel.xyplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2561 F_2_llines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2564 F_2_panel.functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2566 F_2_panel.loess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2570 F_2_panel.qqmathline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571 F_2_panel.smoothScatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2572 F_2_panel.spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2574 F_2_panel.superpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2575 F_2_panel.violin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2577 F_3_prepanel.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2579 F_3_prepanel.functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2580 G_axis.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2582 G_banking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2585 G_latticeParseFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2587 G_packet.panel.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2588 G_panel.axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2589 G_panel.number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2591 CONTENTS xxxix G_Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2592 G_utilities.3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2593 H_barley . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2594 H_environmental . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2595 H_ethanol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2596 H_melanoma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2598 H_singer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2599 I_lset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2600 22 The mgcv package 2601 mgcv-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601 anova.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2603 bam ............................................ 2604 bam.update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2608 choose.k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2610 columb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613 concurvity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2614 cSplineDes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2616 exclude.too.far . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2617 extract.lme.cov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2618 fix.family.link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2620 fixDependence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2621 formula.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2622 formXtViX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2624 full.score . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2625 gam ............................................ 2626 gam.check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2635 gam.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2637 gam.convergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2639 gam.fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2640 gam.fit3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2641 gam.models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2644 gam.outer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2650 gam.selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2651 gam.side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2654 gam.vcomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2655 gam2objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2657 gamm ........................................... 2658 gamObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2664 gamSim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2667 get.var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2668 in.out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2669 influence.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2670 initial.sp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2671 interpret.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2672 ldTweedie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2673 linear.functional.terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2674 logLik.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2677 ls.size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2679 xl CONTENTS magic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2680 magic.post.proc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2684 mgcv ........................................... 2685 mgcv-FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2688 mgcv.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2690 model.matrix.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2691 mono.con . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2692 mroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2693 negbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2694 new.name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2697 notExp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2698 notExp2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2699 null.space.dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2701 pcls ............................................ 2702 pdIdnot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2705 pdTens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2707 pen.edf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2708 place.knots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2709 plot.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2710 polys.plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2715 predict.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2716 Predict.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2721 Predict.matrix.cr.smooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2722 print.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2723 qq.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2724 random.effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2726 residuals.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2728 rig............................................. 2729 rTweedie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2730 s.............................................. 2731 slanczos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2734 smooth.construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2735 smooth.construct.ad.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2740 smooth.construct.cr.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2743 smooth.construct.ds.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2745 smooth.construct.fs.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2747 smooth.construct.mrf.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2749 smooth.construct.ps.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2752 smooth.construct.re.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2754 smooth.construct.sos.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2755 smooth.construct.tensor.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . 2758 smooth.construct.tp.smooth.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2759 smooth.terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2761 smoothCon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2764 sp.vcov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2766 spasm.construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2767 step.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2768 summary.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2769 CONTENTS xli t2 ............................................. 2773 te ............................................. 2777 tensor.prod.model.matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2781 Tweedie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2782 uniquecombs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2784 vcov.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2785 vis.gam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2786 23 The nlme package 2791 ACF............................................ 2791 ACF.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2792 ACF.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2793 Alfalfa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2795 allCoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2795 anova.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2796 anova.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2799 as.matrix.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2801 as.matrix.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2803 as.matrix.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2804 asOneFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2805 Assay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2805 asTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2806 augPred . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2807 balancedGrouped . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2809 bdf............................................. 2810 BodyWeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2811 Cefamandole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2812 Coef............................................ 2813 coef.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2814 coef.gnls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2815 coef.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2816 coef.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2817 coef.modelStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2819 coef.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2820 coef.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2821 coef.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2822 collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2823 collapse.groupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2824 compareFits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2826 comparePred . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2827 corAR1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2828 corARMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2830 corCAR1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2831 corClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2833 corCompSymm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2834 corExp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2835 corFactor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2837 corFactor.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2838 corGaus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2839 xlii CONTENTS corLin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2841 corMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2842 corMatrix.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2843 corMatrix.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2845 corMatrix.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2846 corNatural . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2847 corRatio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2848 corSpatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2850 corSpher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2851 corSymm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2853 Covariate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2855 Covariate.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2856 Dialyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2857 Dim............................................ 2858 Dim.corSpatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2859 Dim.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2860 Dim.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2861 Earthquake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2862 ergoStool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2863 Fatigue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2863 fdHess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2864 fitted.glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2865 fitted.gnlsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2866 fitted.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2867 fitted.lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2868 fitted.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2869 fitted.nlmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2870 fixed.effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2871 fixef.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2872 formula.pdBlocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2873 formula.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2874 formula.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2875 gapply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2876 Gasoline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2877 getCovariate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2878 getCovariate.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2879 getCovariate.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2880 getCovariate.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2881 getCovariateFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2882 getData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2882 getData.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2883 getData.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2884 getData.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2885 getGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2886 getGroups.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2887 getGroups.data.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2888 getGroups.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2889 getGroups.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2890 CONTENTS xliii getGroups.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2891 getGroups.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2892 getGroupsFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2893 getResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2894 getResponseFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2894 getVarCov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2895 gls............................................. 2896 glsControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2898 glsObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2900 glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2901 Glucose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2902 Glucose2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2902 gnls ............................................ 2903 gnlsControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2905 gnlsObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2907 gnlsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2908 groupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2909 gsummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2911 Gun ............................................ 2913 IGF ............................................ 2914 Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2914 Initialize.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2915 Initialize.glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2916 Initialize.lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2917 Initialize.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2918 Initialize.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2919 intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2920 intervals.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2921 intervals.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2922 intervals.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2923 isBalanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2924 isInitialized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2925 LDEsysMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2926 lme ............................................ 2927 lme.groupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2930 lme.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2932 lmeControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2934 lmeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2936 lmeScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2938 lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2938 lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2939 lmList.groupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2941 logDet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2942 logDet.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2943 logDet.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2944 logDet.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2945 logLik.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2946 logLik.glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2947 xliv CONTENTS logLik.gnls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2948 logLik.gnlsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2949 logLik.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2950 logLik.lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2951 logLik.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2952 logLik.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2953 logLik.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2954 Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2955 MathAchieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2955 MathAchSchool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2956 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2956 Matrix.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2957 Matrix.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2958 Meat............................................ 2959 Milk............................................ 2959 model.matrix.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2960 Muscle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2961 Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2962 Names.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2963 Names.pdBlocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2964 Names.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2965 Names.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2966 needUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2967 needUpdate.modelStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2967 Nitrendipene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2968 nlme............................................ 2969 nlme.nlsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2972 nlmeControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2974 nlmeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2976 nlmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2978 nlsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2979 nlsList.selfStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2980 Oats............................................ 2981 Orthodont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2982 Ovary ........................................... 2983 Oxboys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2983 Oxide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2984 pairs.compareFits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2985 pairs.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2986 pairs.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2987 PBG............................................ 2989 pdBlocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2990 pdClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2991 pdCompSymm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2992 pdConstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2993 pdConstruct.pdBlocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2994 pdDiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2996 pdFactor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2998 CONTENTS xlv pdFactor.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2999 pdIdent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3000 pdLogChol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3001 pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3002 pdMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3004 pdMatrix.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3005 pdNatural . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3006 pdSymm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3007 Phenobarb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3009 phenoModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3010 Pixel............................................ 3011 plot.ACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3011 plot.augPred . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3012 plot.compareFits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3013 plot.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3014 plot.intervals.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3016 plot.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3017 plot.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3019 plot.nffGroupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3020 plot.nfnGroupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3022 plot.nmGroupedData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3024 plot.ranef.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3026 plot.ranef.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3027 plot.Variogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3029 pooledSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3030 predict.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3031 predict.gnls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3032 predict.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3033 predict.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3034 predict.nlme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3035 print.summary.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3037 print.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3038 qqnorm.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3038 qqnorm.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3040 Quinidine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3041 quinModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3042 Rail ............................................ 3044 random.effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3044 ranef.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3045 ranef.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3047 RatPupWeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3048 recalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3049 recalc.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3050 recalc.modelStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3051 recalc.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3052 recalc.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3053 Relaxin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3054 Remifentanil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3054 xlvi CONTENTS residuals.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3055 residuals.glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3056 residuals.gnlsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3057 residuals.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3058 residuals.lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3059 residuals.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3060 residuals.nlmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3061 reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3062 simulate.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3064 solve.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3065 solve.reStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3066 Soybean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3067 splitFormula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3068 Spruce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3068 summary.corStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3069 summary.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3070 summary.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3071 summary.lmList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3072 summary.modelStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3074 summary.nlsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3075 summary.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3076 summary.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3077 Tetracycline1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3078 Tetracycline2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3079 update.modelStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3079 update.varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3080 varClasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3081 varComb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3082 varConstPower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3083 VarCorr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3084 varExp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3085 varFixed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3086 varFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3087 varIdent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3088 Variogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3089 Variogram.corExp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3090 Variogram.corGaus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3091 Variogram.corLin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3092 Variogram.corRatio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3093 Variogram.corSpatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3094 Variogram.corSpher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3095 Variogram.default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3096 Variogram.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3098 Variogram.lme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3100 varPower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3102 varWeights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3103 varWeights.glsStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3104 varWeights.lmeStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3105 CONTENTS xlvii Wafer ........................................... 3106 Wheat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3106 Wheat2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3107 [.pdMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3107 24 The nnet package 3109 class.ind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3109 multinom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3110 nnet ............................................ 3111 nnetHess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3114 predict.nnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3115 which.is.max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3116 25 The rpart package 3119 car.test.frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3119 cu.summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3120 kyphosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3121 labels.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3122 meanvar.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3123 na.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3124 path.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3124 plot.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3125 plotcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3127 post.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3128 predict.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3129 print.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3131 printcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3132 prune.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3133 residuals.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3134 rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3135 rpart.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3137 rpart.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3138 rpconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3139 rsq.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3140 snip.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3141 solder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3142 summary.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3143 text.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3144 xpred.rpart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3145 26 The spatial package 3147 anova.trls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3147 correlogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3148 expcov........................................... 3149 Kaver ........................................... 3150 Kenvl ........................................... 3151 Kfn ............................................ 3152 ppgetregion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3153 ppinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3153 xlviii CONTENTS pplik . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3154 ppregion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3155 predict.trls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3156 prmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3157 Psim............................................ 3158 semat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3159 SSI............................................. 3160 Strauss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3161 surf.gls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3162 surf.ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3163 trls.influence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3164 trmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3165 variogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3166 27 The survival package 3169 aareg............................................ 3169 aml ............................................ 3172 anova.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3172 attrassign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3174 basehaz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3175 bladder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3176 cch............................................. 3177 cgd............................................. 3180 clogit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3181 cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3182 colon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3182 cox.zph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3183 coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3184 coxph.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3188 coxph.detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3189 coxph.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3190 dsurvreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3191 frailty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3192 heart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3194 is.ratetable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3195 kidney . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3196 lines.survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3197 lung............................................ 3199 mgus............................................ 3200 model.frame.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3201 model.matrix.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3202 nwtco . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3203 ovarian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3204 pbc............................................. 3205 pbcseq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3206 plot.aareg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3207 plot.cox.zph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3208 plot.survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3209 predict.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3211 CONTENTS xlix predict.survreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3212 print.aareg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3214 print.summary.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3215 print.summary.survexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3215 print.summary.survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3216 print.survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3217 pspline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3218 pyears . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3220 ratetable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3222 ratetableDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3223 ratetables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3224 rats............................................. 3225 residuals.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3226 residuals.survreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3227 ridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3228 stanford2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3229 strata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3230 summary.aareg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3231 summary.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233 summary.survexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3234 summary.survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3235 Surv............................................ 3236 survConcordance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3238 survdiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3240 survexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3241 survexp.fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3244 survfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3245 survfit.coxph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3246 survfit.formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3249 survfit.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3253 survfitcoxph.fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3254 survobrien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3256 survreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3257 survreg.control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3259 survreg.distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3259 survreg.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3261 survregDtest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3262 survSplit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263 tcut ............................................ 3264 tobin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3265 tt.............................................. 3266 untangle.specials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267 veteran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3268 Index 3269 l CONTENTS Part I 1 Chapter 1 The base package base-package The R Base Package Description Base R functions Details This package contains the basic functions which let R function as a language: arithmetic, in- put/output, basic programming support, etc. Its contents are available through inheritance from any environment. For a complete list of functions, use library(help="base"). .Device Lists of Open/Active Graphics Devices Description A pairlist of the names of open graphics devices is stored in .Devices. The name of the active device (see dev.cur) is stored in .Device. Both are symbols and so appear in the base namespace. Value .Device is a length-one character vector. .Devices is a pairlist of length-one character vectors. The first entry is always "null device", and there are as many entries as the maximal number of graphics devices which have been simul- taneously active. If a device has been removed, its entry will be "" until the device number is reused. 3 4 .Machine .Machine Numerical Characteristics of the Machine Description .Machine is a variable holding information on the numerical characteristics of the machine R is running on, such as the largest double or integer and the machine’s precision. Usage .Machine Details The algorithm is based on Cody’s (1988) subroutine MACHAR. As all current implementations of R use 32-bit integers and almost all use IEC 60559 floating-point (double precision) arithmetic, all but the last two values are the same for almost all R builds. Note that on most platforms smaller positive values than .Machine$double.xmin can occur. On a typical R platform the smallest positive double is about 5e-324. Value A list with components double.eps the smallest positive floating-point number x such that 1 + x != 1. It equals double.base ^ ulp.digits if either double.base is 2 or double.rounding is 0; otherwise, it is (double.base ^ double.ulp.digits) / 2. Normally 2.220446e-16. double.neg.eps a small positive floating-point number x such that 1 - x != 1. It equals double.base ^ double.neg.ulp.digits if double.base is 2 or double.rounding is 0; otherwise, it is (double.base ^ double.neg.ulp.digits) / 2. Normally 1.110223e-16. As double.neg.ulp.digits is bounded below by -(double.digits + 3), double.neg.eps may not be the smallest number that can alter 1 by subtrac- tion. double.xmin the smallest non-zero normalized floating-point number, a power of the radix, i.e., double.base ^ double.min.exp. Normally 2.225074e-308. double.xmax the largest normalized floating-point number. Typically, it is equal to (1 - double.neg.eps) * double.base ^ double.max.exp, but on some machines it is only the second or third largest such number, being too small by 1 or 2 units in the last digit of the significand. Normally 1.797693e+308. Note that larger unnormalized numbers can occur. double.base the radix for the floating-point representation: normally 2. double.digits the number of base digits in the floating-point significand: normally 53. .Machine 5 double.rounding the rounding action, one of 0 if floating-point addition chops; 1 if floating-point addition rounds, but not in the IEEE style; 2 if floating-point addition rounds in the IEEE style; 3 if floating-point addition chops, and there is partial underflow; 4 if floating-point addition rounds, but not in the IEEE style, and there is partial underflow; 5 if floating-point addition rounds in the IEEE style, and there is partial under- flow. Normally 5. double.guard the number of guard digits for multiplication with truncating arithmetic. It is 1 if floating-point arithmetic truncates and more than double digits base- double.base digits participate in the post-normalization shift of the floating- point significand in multiplication, and 0 otherwise. double.ulp.digits the largest negative integer i such that 1 + double.base ^ i != 1, except that it is bounded below by -(double.digits + 3). Normally -52. double.neg.ulp.digits the largest negative integer i such that 1 - double.base ^ i != 1, except that it is bounded below by -(double.digits + 3). Normally -53. double.exponent the number of bits (decimal places if double.base is 10) reserved for the repre- sentation of the exponent (including the bias or sign) of a floating-point number. Normally 11. double.min.exp the largest in magnitude negative integer i such that double.base ^ i is posi- tive and normalized. Normally -1022. double.max.exp the smallest positive power of double.base that overflows. Normally 1024. integer.max the largest integer which can be represented. Always 2147483647. sizeof.long the number of bytes in a C long type: 4 or 8 (most 64-bit systems, but not Windows). sizeof.longlong the number of bytes in a C long long type. Will be zero if there is no such type, otherwise usually 8. sizeof.longdouble the number of bytes in a C long double type. Will be zero if there is no such type, otherwise possibly 12 (most 32-bit builds) or 16 (most 64-bit builds). sizeof.pointer the number of bytes in a C SEXP type. Will be 4 on 32-bit builds and 8 on 64-bit builds of R. Note sizeof.longdouble only tells you the amount of storage allocated for a long double (which are used internally by R for accumulators in e.g. sum, and can be read by readBin). Often what is stored is the 80-bit extended double type of IEC 60559, padded to the double alignment used on the platform — this seems to be the case for the common R platforms using ix86 and x86_64 chips. 6 .Platform References Cody, W. J. (1988) MACHAR: A subroutine to dynamically determine machine parameters. Trans- actions on Mathematical Software, 14, 4, 303–311. See Also .Platform for details of the platform. Examples .Machine ## or for a neat printout noquote(unlist(format(.Machine))) .Platform Platform Specific Variables Description .Platform is a list with some details of the platform under which R was built. This provides means to write OS-portable R code. Usage .Platform Value A list with at least the following components: OS.type character string, giving the Operating System (family) of the computer. One of "unix" or "windows". file.sep character string, giving the file separator used on your platform: "/" on both Unix-alikes and on Windows (but not on the once port to Classic Mac OS). dynlib.ext character string, giving the file name extension of dynamically loadable libraries, e.g., ".dll" on Windows and ".so" or ".sl" on Unix-alikes. (Note for Mac OS X users: these are shared objects as loaded by dyn.load and not dylibs: see dyn.load.) GUI character string, giving the type of GUI in use, or "unknown" if no GUI can be assumed. Possible values are for Unix-alikes the values given via the ‘-g’ command-line flag ("X11","Tk"), "AQUA" (running under R.app on Mac OS X), "Rgui" and "RTerm" (Windows) and perhaps others under alternative front- ends or embedded R. endian character string, "big" or "little", giving the endianness of the processor in use. This is relevant when it is necessary to know the order to read/write bytes of e.g. an integer or double from/to a connection: see readBin. .Platform 7 pkgType character string, the preferred setting for options("pkgType"). Values "source","mac.binary.leopard" and "win.binary" are currently in use. path.sep character string, giving the path separator, used on your platform, e.g., ":" on Unix-alikes and ";" on Windows. Used to separate paths in environment variables such as PATH and TEXINPUTS. r_arch character string, possibly "". The name of an architecture-specific directory used in this build of R. AQUA .Platform$GUI is set to "AQUA" under the Mac OS X GUI, R.app. This has a number of conse- quences: • the DISPLAY environment variable is set to ":0" if unset. • appends ‘/usr/local/bin’ to the PATH environment variable. • the default graphics device is set to quartz. • selects native (rather than Tk) widgets for the graphics = TRUE options of menu and select.list. • HTML help is displayed in the internal browser. • The spreadsheet-like data editor/viewer uses a Quartz version rather than the X11 one. See Also R.version and Sys.info give more details about the OS. In particular, R.version$platform is the canonical name of the platform under which R was compiled. .Machine for details of the arithmetic used, and system for invoking platform-specific system commands. Examples ## Note: this can be done in a system-independent way ## by file.info()$isdir if(.Platform$OS.type == "unix") { system.test <- function(...) { system(paste("test", ...)) == 0 } dir.exists <- function(dir) sapply(dir, function(d) system.test("-d", d)) dir.exists(c(R.home(), "/tmp", "~", "/NO"))# > T T T F } 8 abbreviate abbreviate Abbreviate Strings Description Abbreviate strings to at least minlength characters, such that they remain unique (if they were), unless strict=TRUE. Usage abbreviate(names.arg, minlength = 4, use.classes = TRUE, dot = FALSE, strict = FALSE, method = c("left.kept", "both.sides")) Arguments names.arg a character vector of names to be abbreviated, or an object to be coerced to a character vector by as.character. minlength the minimum length of the abbreviations. use.classes logical (currently ignored by R). dot logical: should a dot (".") be appended? strict logical: should minlength be observed strictly? Note that setting strict=TRUE may return non-unique strings. method a string specifying the method used with default "left.kept", see ‘Details’ below. Details The algorithm (method = "left.kept") used is similar to that of S. For a single string it works as follows. First all spaces at the beginning of the string are stripped. Then (if necessary) any other spaces are stripped. Next, lower case vowels are removed (starting at the right) followed by lower case consonants. Finally if the abbreviation is still longer than minlength upper case letters are stripped. Characters are always stripped from the end of the word first. If an element of names.arg contains more than one word (words are separated by space) then at least one letter from each word will be retained. Missing (NA) values are unaltered. If use.classes is FALSE then the only distinction is to be between letters and space. This has NOT been implemented. agrep 9 Value A character vector containing abbreviations for the strings in its first argument. Duplicates in the original names.arg will be given identical abbreviations. If any non-duplicated elements have the same minlength abbreviations then, if method = "both.sides" the basic internal abbreviate() algorithm is applied to the characterwise reversed strings; if there are still duplicated abbreviations and if strict=FALSE as by default, minlength is incremented by one and new abbreviations are found for those elements only. This process is repeated until all unique elements of names.arg have unique abbreviations. The character version of names.arg is attached to the returned value as a names argument: no other attributes are retained. Warning This is really only suitable for English, and does not work correctly with non-ASCII characters in multibyte locales. It will warn if used with non-ASCII characters. See Also substr. Examples x <- c("abcd", "efgh", "abce") abbreviate(x, 2) abbreviate(x, 2, strict=TRUE)# >> 1st and 3rd are == "ab" (st.abb <- abbreviate(state.name, 2)) table(nchar(st.abb))# out of 50, 3 need 4 letters : as <- abbreviate(state.name, 3, strict=TRUE) as[which(as == "Mss")] ## method="both.sides" helps: no 4-letters, and only 4 3-letters: st.ab2 <- abbreviate(state.name, 2, method="both") table(nchar(st.ab2)) ## Compare the two methods: cbind(st.abb, st.ab2) agrep Approximate String Matching (Fuzzy Matching) Description Searches for approximate matches to pattern (the first argument) within each element of the string x (the second argument) using the generalized Levenshtein edit distance (the minimal possibly weighted number of insertions, deletions and substitutions needed to transform one string into an- other). 10 agrep Usage agrep(pattern, x, max.distance = 0.1, costs = NULL, ignore.case = FALSE, value = FALSE, fixed = TRUE, useBytes = FALSE) Arguments pattern a non-empty character string or a character string containing a regular expression (for fixed = FALSE) to be matched. Coerced by as.character to a string if possible. x character vector where matches are sought. Coerced by as.character to a character vector if possible. max.distance Maximum distance allowed for a match. Expressed either as integer, or as a fraction of the pattern length times the maximal transformation cost (will be replaced by the smallest integer not less than the corresponding fraction), or a list with possible components cost: maximum number/fraction of match cost (generalized Levenshtein dis- tance) all: maximal number/fraction of all transformations (insertions, deletions and substitutions) insertions: maximum number/fraction of insertions deletions: maximum number/fraction of deletions substitutions: maximum number/fraction of substitutions If cost is not given, all defaults to 10%, and the other transformation number bounds default to all. The component names can be abbreviated. costs a numeric vector or list with names partially matching ‘insertions’, ‘deletions’ and ‘substitutions’ giving the respective costs for computing the generalized Levenshtein distance, or NULL (default) indicating using unit cost for all three possible transformations. Coerced to integer via as.integer if possible. ignore.case if FALSE, the pattern matching is case sensitive and if TRUE, case is ignored during matching. value if FALSE, a vector containing the (integer) indices of the matches determined is returned and if TRUE, a vector containing the matching elements themselves is returned. fixed logical. If TRUE (default), the pattern is matched literally (as is). Otherwise, it is matched as a regular expression. useBytes logical. in a multibyte locale, should the comparison be character-by-character (the default) or byte-by-byte. Details The Levenshtein edit distance is used as measure of approximateness: it is the (possibly cost- weighted) total number of insertions, deletions and substitutions required to transform one string into another. all 11 As from R 2.10.0 this uses tre by Ville Laurikari (http://http://laurikari.net/tre/), which supports MBCS character matching much better than the previous version. The main effect of useBytes is to avoid errors/warnings about invalid inputs and spurious matches in multibyte locales. It inhibits the conversion of inputs with marked encodings, and is forced if any input is found which is marked as "bytes". Value Either a vector giving the indices of the elements that yielded a match, or, if value is TRUE, the matched elements (after coercion, preserving names but no other attributes). Note Since someone who read the description carelessly even filed a bug report on it, do note that this matches substrings of each element of x (just as grep does) and not whole elements. See adist in package utils, which optionally returns the offsets of the matched substrings. Author(s) Original version by David Meyer. Current version by Brian Ripley and Kurt Hornik. See Also grep Examples agrep("lasy", "1 lazy 2") agrep("lasy", c(" 1 lazy 2", "1 lasy 2"), max = list(sub = 0)) agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2) agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2, value = TRUE) agrep("laysy", c("1 lazy", "1", "1 LAZY"), max = 2, ignore.case = TRUE) all Are All Values True? Description Given a set of logical vectors, are all of the values true? Usage all(..., na.rm = FALSE) Arguments ... zero or more logical vectors. Other objects of zero length are ignored, and the rest are coerced to logical ignoring any class. na.rm logical. If true NA values are removed before the result is computed. 12 all Details This is a generic function: methods can be defined for it directly or via the Summary group generic. For this to work properly, the arguments ... should be unnamed, and dispatch is on the first argument. Coercion of types other than integer (raw, double, complex, character, list) gives a warning as this is often unintentional. This is a primitive function. Value The value is a logical vector of length one. Let x denote the concatenation of all the logical vectors in ... (after coercion), after removing NAs if requested by na.rm = TRUE. The value returned is TRUE if all of the values in x are TRUE (including if there are no values), and FALSE if at least one of the values in x is FALSE. Otherwise the value is NA (which can only occur if na.rm = FALSE and ... contains no FALSE values and at least one NA value). S4 methods This is part of the S4 Summary group generic. Methods for it must use the signature x, ..., na.rm. Note That all(logical(0)) is true is a useful convention: it ensures that all(all(x), all(y)) == all(x,y) even if x has length zero. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also any, the ‘complement’ of all, and stopifnot(*) which is an all(*) ‘insurance’. Examples range(x <- sort(round(stats::rnorm(10) - 1.2, 1))) if(all(x < 0)) cat("all x values are negative\n") all(logical(0)) # true, as all zero of the elements are true. all.equal 13 all.equal Test if Two Objects are (Nearly) Equal Description all.equal(x,y) is a utility to compare R objects x and y testing ‘near equality’. If they are different, comparison is still made to some extent, and a report of the differences is returned. Don’t use all.equal directly in if expressions—either use isTRUE(all.equal(....)) or identical if appropriate. Usage all.equal(target, current, ...) ## S3 method for class ’numeric’ all.equal(target, current, tolerance = .Machine$double.eps ^ 0.5, scale = NULL, check.attributes = TRUE, ...) attr.all.equal(target, current, check.attributes = TRUE, check.names = TRUE, ...) Arguments target R object. current other R object, to be compared with target. ... Further arguments for different methods, notably the following two, for numer- ical comparison: tolerance numeric ≥ 0. Differences smaller than tolerance are not considered. scale numeric scalar > 0 (or NULL). See ‘Details’. check.attributes logical indicating if the attributes(.) of target and current should be compared as well. check.names logical indicating if the names(.) of target and current should be compared as well (and separately from the attributes). Details all.equal is a generic function, dispatching methods on the target argument. To see the available methods, use methods("all.equal"), but note that the default method also does some dispatching, e.g. using the raw method for logical targets. Numerical comparisons for scale = NULL (the default) are done by first computing the mean absolute difference of the two numerical vectors. If this is smaller than tolerance or not finite, absolute differences are used, otherwise relative differences scaled by the mean absolute difference. If scale is positive, absolute comparisons are made after scaling (dividing) by scale. 14 all.names For complex target, the modulus (Mod) of the difference is used: all.equal.numeric is called so arguments tolerance and scale are available. attr.all.equal is used for comparing attributes, returning NULL or a character vector. Value Either TRUE (NULL for attr.all.equal) or a vector of mode "character" describing the differ- ences between target and current. References Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer (for =). See Also identical, isTRUE, ==, and all for exact equality testing. Examples all.equal(pi, 355/113) # not precise enough (default tol) > relative error d45 <- pi*(1/4 + 1:10) stopifnot( all.equal(tan(d45), rep(1,10))) # TRUE, but all (tan(d45) == rep(1,10)) # FALSE, since not exactly all.equal(tan(d45), rep(1,10), tol=0) # to see difference all.names Find All Names in an Expression Description Return a character vector containing all the names which occur in an expression or call. Usage all.names(expr, functions = TRUE, max.names = -1L, unique = FALSE) all.vars(expr, functions = FALSE, max.names = -1L, unique = TRUE) Arguments expr an expression or call from which the names are to be extracted. functions a logical value indicating whether function names should be included in the result. max.names the maximum number of names to be returned. -1 indicates no limit (other than vector size limits). unique a logical value which indicates whether duplicate names should be removed from the value. any 15 Details These functions differ only in the default values for their arguments. Value A character vector with the extracted names. See Also substitute to replace symbols with values in an expression. Examples all.names(expression(sin(x+y))) all.names(quote(sin(x+y))) # or a call all.vars(expression(sin(x+y))) any Are Some Values True? Description Given a set of logical vectors, is at least one of the values true? Usage any(..., na.rm = FALSE) Arguments ... zero or more logical vectors. Other objects of zero length are ignored, and the rest are coerced to logical ignoring any class. na.rm logical. If true NA values are removed before the result is computed. Details This is a generic function: methods can be defined for it directly or via the Summary group generic. For this to work properly, the arguments ... should be unnamed, and dispatch is on the first argument. Coercion of types other than integer (raw, double, complex, character, list) gives a warning as this is often unintentional. This is a primitive function. 16 aperm Value The value is a logical vector of length one. Let x denote the concatenation of all the logical vectors in ... (after coercion), after removing NAs if requested by na.rm = TRUE. The value returned is TRUE if at least one of the values in x is TRUE, and FALSE if all of the values in x are FALSE (including if there are no values). Otherwise the value is NA (which can only occur if na.rm = FALSE and ... contains no TRUE values and at least one NA value). S4 methods This is part of the S4 Summary group generic. Methods for it must use the signature x, ..., na.rm. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also all, the ‘complement’ of any. Examples range(x <- sort(round(stats::rnorm(10) - 1.2,1))) if(any(x < 0)) cat("x contains negative values\n") aperm Array Transposition Description Transpose an array by permuting its dimensions and optionally resizing it. Usage aperm(a, perm, ...) ## Default S3 method: aperm(a, perm = NULL, resize = TRUE, ...) ## S3 method for class ’table’ aperm(a, perm = NULL, resize = TRUE, keep.class = TRUE, ...) aperm 17 Arguments a the array to be transposed. perm the subscript permutation vector, usually a permutation of the integers 1:n, where n is the number of dimensions of a. When a has named dimnames, it can be a character vector of length n giving a permutation of those names. The default (used whenever perm has zero length) is to reverse the order of the di- mensions. resize a flag indicating whether the vector should be resized as well as having its ele- ments reordered (default TRUE). keep.class logical indicating if the result should be of the same class as a. ... potential further arguments of methods. Value A transposed version of array a, with subscripts permuted as indicated by the array perm. If resize is TRUE, the array is reshaped as well as having its elements permuted, the dimnames are also permuted; if resize = FALSE then the returned object has the same dimensions as a, and the dimnames are dropped. In each case other attributes are copied from a. The function t provides a faster and more convenient way of transposing matrices. Author(s) Jonathan Rougier, did the faster C implementation. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also t, to transpose matrices. Examples # interchange the first two subscripts on a 3-way array x x <- array(1:24, 2:4) xt <- aperm(x, c(2,1,3)) stopifnot(t(xt[,,2]) == x[,,2], t(xt[,,3]) == x[,,3], t(xt[,,4]) == x[,,4]) UCB <- aperm(UCBAdmissions, c(2,1,3)) UCB[1,,] summary(UCB)# UCB is still a continency table 18 apply append Vector Merging Description Add elements to a vector. Usage append(x, values, after = length(x)) Arguments x the vector to be modified. values to be included in the modified vector. after a subscript, after which the values are to be appended. Value A vector containing the values in x with the elements of values appended after the specified element of x. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Examples append(1:5, 0:1, after=3) apply Apply Functions Over Array Margins Description Returns a vector or array or list of values obtained by applying a function to margins of an array or matrix. Usage apply(X, MARGIN, FUN, ...) apply 19 Arguments X an array, including a matrix. MARGIN a vector giving the subscripts which the function will be applied over. E.g., for a matrix 1 indicates rows, 2 indicates columns, c(1, 2) indicates rows and columns. Where X has named dimnames, it can be a character vector selecting dimension names. FUN the function to be applied: see ‘Details’. In the case of functions like +,%*%, etc., the function name must be backquoted or quoted. ... optional arguments to FUN. Details If X is not an array but an object of a class with a non-null dim value (such as a data frame), apply attempts to coerce it to an array via as.matrix if it is two-dimensional (e.g., a data frame) or via as.array. FUN is found by a call to match.fun and typically is either a function or a symbol (e.g. a backquoted name) or a character string specifying a function to be searched for from the environment of the call to apply. Value If each call to FUN returns a vector of length n, then apply returns an array of dimension c(n, dim(X)[MARGIN]) if n > 1. If n equals 1, apply returns a vector if MARGIN has length 1 and an array of dimension dim(X)[MARGIN] otherwise. If n is 0, the result has length 0 but not necessarily the ‘correct’ dimension. If the calls to FUN return vectors of different lengths, apply returns a list of length prod(dim(X)[MARGIN]) with dim set to MARGIN if this has length greater than one. In all cases the result is coerced by as.vector to one of the basic vector types before the dimensions are set, so that (for example) factor results will be coerced to a character array. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also lapply and there, simplify2array; tapply, and convenience functions sweep and aggregate. Examples ## Compute row and column sums for a matrix: x <- cbind(x1 = 3, x2 = c(4:1, 2:5)) dimnames(x)[[1]] <- letters[1:8] apply(x, 2, mean, trim = .2) col.sums <- apply(x, 2, sum) row.sums <- apply(x, 1, sum) rbind(cbind(x, Rtot = row.sums), Ctot = c(col.sums, sum(col.sums))) 20 args stopifnot( apply(x, 2, is.vector)) ## Sort the columns of a matrix apply(x, 2, sort) ##- function with extra args: cave <- function(x, c1, c2) c(mean(x[c1]), mean(x[c2])) apply(x,1, cave, c1="x1", c2=c("x1","x2")) ma <- matrix(c(1:4, 1, 6:8), nrow = 2) ma apply(ma, 1, table) #--> a list of length 2 apply(ma, 1, stats::quantile)# 5 x n matrix with rownames stopifnot(dim(ma) == dim(apply(ma, 1:2, sum))) ## Example with different lengths for each call z <- array(1:24, dim=2:4) zseq <- apply(z, 1:2, function(x) seq_len(max(x))) zseq ## a 2 x 3 matrix typeof(zseq) ## list dim(zseq) ## 2 3 zseq[1,] apply(z, 3, function(x) seq_len(max(x))) # a list without a dim attribute args Argument List of a Function Description Displays the argument names and corresponding default values of a function or primitive. Usage args(name) Arguments name a function (a closure or a primitive). If name is a character string then the func- tion with that name is found and used. Details This function is mainly used interactively to print the argument list of a function. For programming, consider using formals instead. Arithmetic 21 Value For a closure, a closure with identical formal argument list but an empty (NULL) body. For a primitive, a closure with the documented usage and NULL body. Note that some primitives do not make use of named arguments and match by position rather than name. NULL in case of a non-function. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also formals, help. Examples args(c) args(graphics::plot.default) Arithmetic Arithmetic Operators Description These binary operators perform arithmetic on numeric or complex vectors (or objects which can be coerced to them). Usage x + y x - y x * y x / y x ^ y x %% y x %/% y Arguments x, y numeric or complex vectors or objects which can be coerced to such, or other objects for which methods have been written. 22 Arithmetic Details The binary arithmetic operators are generic functions: methods can be written for them individually or via the Ops group generic function. (See Ops for how dispatch is computed.) If applied to arrays the result will be an array if this is sensible (for example it will not if the recycling rule has been invoked). Logical vectors will be coerced to integer or numeric vectors, FALSE having value zero and TRUE having value one. 1 ^ y and y ^ 0 are 1, always. x ^ y should also give the proper limit result when either argument is infinite (i.e., +- Inf). Objects such as arrays or time-series can be operated on this way provided they are conformable. For real arguments, %% can be subject to catastrophic loss of accuracy if x is much larger than y, and a warning is given if this is detected. %% and x %/% y can be used for non-integer y, e.g. 1 %/% 0.2, but the results are subject to representation error and so may be platform-dependent. Because the IEC 60059 representation of 0.2 is a binary fraction slightly larger than 0.2, the answer to 1 %/% 0.2 should be 4 but most platforms give 5. Users are sometimes surprised by the value returned, for example why (-8)^(1/3) is NaN. For double inputs, R makes use of IEC 60559 arithmetic on all platforms, together with the C system function ‘pow’ for the ^ operator. The relevant standards define the result in many corner cases. In particular, the result in the example above is mandated by the C99 standard. On many Unix-alike systems the command man pow gives details of the values in a large number of corner cases. Arithmetic on type double in R is supposed to be done in ‘round to nearest, ties to even’ mode, but this does depend on the compiler and FPU being set up correctly. Value These operators return vectors containing the result of the element by element operations. The elements of shorter vectors are recycled as necessary (with a warning when they are recycled only fractionally). The operators are + for addition, - for subtraction, * for multiplication, / for division and ^ for exponentiation. %% indicates x mod y and %/% indicates integer division. It is guaranteed that x == (x %% y) + y * ( x %/% y ) (up to rounding error) unless y == 0 where the result for %% is NA_integer_ or NaN (depending on the typeof of the arguments). If either argument is complex the result will be complex, otherwise if one or both arguments are numeric, the result will be numeric. If both arguments are of type integer, the type of the result of / and ^ is numeric and for the other operators it is integer (with overflow, which occurs at ±(231 −1), returned as NA_integer_ with a warning). The rules for determining the attributes of the result are rather complicated. Most attributes are taken from the longer argument, the first if they are of the same length. Names will be copied from the first if it is the same length as the answer, otherwise from the second if that is. For time series, these operations are allowed only if the series are compatible, when the class and tsp attribute of whichever is a time series (the same, if both are) are used. For arrays (and an array result) the dimensions and dimnames are taken from first argument if it is an array, otherwise the second. array 23 S4 methods These operators are members of the S4 Arith group generic, and so methods can be written for them individually as well as for the group generic (or the Ops group generic), with arguments c(e1, e2). Note ** is translated in the parser to ^, but this was undocumented for many years. It appears as an index entry in Becker et al (1988), pointing to the help for Deprecated but is not actually mentioned on that page. Even though it had been deprecated in S for 20 years, it was still accepted in R in 2008. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. D. Goldberg (1991) What Every Computer Scientist Should Know about Floating-Point Arithmetic ACM Computing Surveys, 23(1). Postscript version available at http://www.validlab.com/goldberg/paper.ps Extended PDF version at http://www.validlab.com/goldberg/paper.pdf See Also sqrt for miscellaneous and Special for special mathematical functions. Syntax for operator precedence. %*% for matrix multiplication. Examples x <- -1:12 x + 1 2 * x + 3 x %% 2 #-- is periodic x %/% 5 array Multi-way Arrays Description Creates or tests for arrays. Usage array(data = NA, dim = length(data), dimnames = NULL) as.array(x, ...) is.array(x) 24 array Arguments data a vector (including a list or expression vector) giving data to fill the array. Other objects are coerced by as.vector. dim the dim attribute for the array to be created, that is a vector of length one or more giving the maximal indices in each dimension. dimnames either NULL or the names for the dimensions. This is a list with one component for each dimension, either NULL or a character vector of the length given by dim for that dimension. The list can be named, and the list names will be used as names for the dimensions. If the list is shorter than the number of dimensions, it is extended by NULLs to the length required x an R object. ... additional arguments to be passed to or from methods. Details An array in R can have one, two or more dimensions. It is simply a vector which is stored with addi- tional attributes giving the dimensions (attribute "dim") and optionally names for those dimensions (attribute "dimnames"). A two-dimensional array is the same thing as a matrix. One-dimensional arrays often look like vectors, but may be handled differently by some functions: str does distinguish them in recent versions of R. The "dim" attribute is an integer vector of length one or more containing non-negative values: the product of the values must match the length of the array. The "dimnames" attribute is optional: if present it is a list with one component for each dimension, either NULL or a character vector of the length given by the element of the "dim" attribute for that dimension. is.array is a primitive function. Value array returns an array with the extents specified in dim and naming information in dimnames. The values in data are taken to be those in the array with the leftmost subscript moving fastest. If there are too few elements in data to fill the array, then the elements in data are recycled. If data has length zero, NA of an appropriate type is used for atomic vectors (0 for raw vectors) and NULL for lists. as.array is a generic function for coercing to arrays. The default method does so by attaching a dim attribute to it. It also attaches dimnames if x has names. The sole purpose of this is to make it possible to access the dim[names] attribute at a later time. is.array returns TRUE or FALSE depending on whether its argument is an array (i.e., has a dim attribute of positive length) or not. It is generic: you can write methods to handle specific classes of objects, see InternalMethods. Note is.array is a primitive function. as.data.frame 25 References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also aperm, matrix, dim, dimnames. Examples dim(as.array(letters)) array(1:3, c(2,4)) # recycle 1:3 "2 2/3 times" # [,1] [,2] [,3] [,4] #[1,] 1 3 2 1 #[2,] 2 1 3 2 as.data.frame Coerce to a Data Frame Description Functions to check if an object is a data frame, or coerce it if possible. Usage as.data.frame(x, row.names = NULL, optional = FALSE, ...) ## S3 method for class ’character’ as.data.frame(x, ..., stringsAsFactors = default.stringsAsFactors()) ## S3 method for class ’matrix’ as.data.frame(x, row.names = NULL, optional = FALSE, ..., stringsAsFactors = default.stringsAsFactors()) is.data.frame(x) Arguments x any R object. row.names NULL or a character vector giving the row names for the data frame. Missing values are not allowed. optional logical. If TRUE, setting row names and converting column names (to syntactic names: see make.names) is optional. ... additional arguments to be passed to or from methods. stringsAsFactors logical: should the character vector be converted to a factor? 26 as.Date Details as.data.frame is a generic function with many methods, and users and packages can supply fur- ther methods. If a list is supplied, each element is converted to a column in the data frame. Similarly, each column of a matrix is converted separately. This can be overridden if the object has a class which has a method for as.data.frame: two examples are matrices of class "model.matrix"(which are included as a single column) and list objects of class "POSIXlt" which are coerced to class "POSIXct". Arrays can be converted to data frames. One-dimensional arrays are treated like vectors and two- dimensional arrays like matrices. Arrays with more than two dimensions are converted to matrices by ‘flattening’ all dimensions after the first and creating suitable column labels. Character variables are converted to factor columns unless protected by I. If a data frame is supplied, all classes preceding "data.frame" are stripped, and the row names are changed if that argument is supplied. If row.names = NULL, row names are constructed from the names or dimnames of x, otherwise are the integer sequence starting at one. Few of the methods check for duplicated row names. Names are removed from vector columns unless I. Value as.data.frame returns a data frame, normally with all row names "" if optional = TRUE. is.data.frame returns TRUE if its argument is a data frame (that is, has "data.frame" amongst its classes) and FALSE otherwise. References Chambers, J. M. (1992) Data for models. Chapter 3 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. See Also data.frame, as.data.frame.table for the table method (which has additional arguments if called directly). as.Date Date Conversion Functions to and from Character Description Functions to convert between character representations and objects of class "Date" representing calendar dates. as.Date 27 Usage as.Date(x, ...) ## S3 method for class ’character’ as.Date(x, format = "", ...) ## S3 method for class ’numeric’ as.Date(x, origin, ...) ## S3 method for class ’POSIXct’ as.Date(x, tz = "UTC", ...) ## S3 method for class ’Date’ format(x, ...) ## S3 method for class ’Date’ as.character(x, ...) Arguments x An object to be converted. format A character string. If not specified, it will try "%Y-%m-%d" then "%Y/%m/%d" on the first non-NA element, and give an error if neither works. origin a Date object, or something which can be coerced by as.Date(origin, ...) to such an object. tz a timezone name. ... Further arguments to be passed from or to other methods, including format for as.character and as.Date methods. Details The usual vector re-cycling rules are applied to x and format so the answer will be of length that of the longer of the vectors. Locale-specific conversions to and from character strings are used where appropriate and available. This affects the names of the days and months. The as.Date methods accept character strings, factors, logical NA and objects of classes "POSIXlt" and "POSIXct". (The last is converted to days by ignoring the time after midnight in the represen- tation of the time in specified timezone, default UTC.) Also objects of class "date" (from package date) and "dates" (from package chron). Character strings are processed as far as necessary for the format specified: any trailing characters are ignored. as.Date will accept numeric data (the number of days since an epoch), but only if origin is sup- plied. The format and as.character methods ignore any fractional part of the date. Value The format and as.character methods return a character vector representing the date. NA dates are returned as NA_character_. The as.Date methods return an object of class "Date". 28 as.Date Conversion from other Systems Most systems record dates internally as the number of days since some origin, but this is fraught with problems, including • Is the origin day 0 or day 1? As the ‘Examples’ show, Excel manages to use both choices for its two date systems. • If the origin is far enough back, the designers may show their ignorance of calendar systems. For example, Excel’s designer thought 1900 was a leap year (claiming to copy the error from earlier DOS spreadsheets), and Matlab’s designer chose the non-existent date of ‘January 0, 0000’ (there is no such day), not specifying the calendar. (There is such a year in the ‘Gregorian’ calendar as used in ISO 8601:2004, but that does say that it is only to be used for years before 1582 with the agreement of the parties in information exchange.) The only safe procedure is to check the other systems values for known dates: reports on the Internet (including R-help) are more often wrong than right. Note The default formats follow the rules of the ISO 8601 international standard which expresses a day as "2001-02-03". If the date string does not specify the date completely, the returned answer may be system-specific. The most common behaviour is to assume that a missing year, month or day is the current one. If it specifies a date incorrectly, reliable implementations will give an error and the date is reported as NA. Unfortunately some common implementations (such as ‘glibc’) are unreliable and guess at the intended meaning. Years before 1CE (aka 1AD) will probably not be handled correctly. References International Organization for Standardization (2004, 1988, 1997, . . . ) ISO 8601. Data ele- ments and interchange formats – Information interchange – Representation of dates and times. For links to versions available on-line see (at the time of writing) http://www.qsl.net/g1smd/ isopdf.htm; for information on the current official version, see http://www.iso.org/iso/en/ prods-services/popstds/datesandtime.html. See Also Date for details of the date class; locales to query or set a locale. Your system’s help pages on strftime and strptime to see how to specify their formats. Windows users will find no help page for strptime: code based on ‘glibc’ is used (with corrections), so all the format specifiers described here are supported, but with no alternative number representation nor era available in any locale. Examples ## locale-specific version of the date format(Sys.Date(), "%a %b %d") ## read in date info in format ’ddmmmyyyy’ as.environment 29 ## This will give NA(s) in some locales; setting the C locale ## as in the commented lines will overcome this on most systems. ## lct <- Sys.getlocale("LC_TIME"); Sys.setlocale("LC_TIME", "C") x <- c("1jan1960", "2jan1960", "31mar1960", "30jul1960") z <- as.Date(x, "%d%b%Y") ## Sys.setlocale("LC_TIME", lct) z ## read in date/time info in format ’m/d/y’ dates <- c("02/27/92", "02/27/92", "01/14/92", "02/28/92", "02/01/92") as.Date(dates, "%m/%d/%y") ## date given as number of days since 1900-01-01 (a date in 1989) as.Date(32768, origin="1900-01-01") ## Excel is said to use 1900-01-01 as day 1 (Windows default) or ## 1904-01-01 as day 0 (Mac default), but this is complicated by Excel ## treating 1900 as a leap year. ## So for dates (post-1901) from Windows Excel as.Date(35981, origin="1899-12-30") # 1998-07-05 ## and Mac Excel as.Date(34519, origin="1904-01-01") # 1998-07-05 ## (these values come from http://support.microsoft.com/kb/214330) ## Experiment shows that Matlab’s origin is 719529 days before ours, ## so Matlab day 734373 can be imported as as.Date(734373, origin = "1970-01-01") - 719529 ## (value from http://www.mathworks.com/help/techdoc/matlab_prog/bspgcx2-1.html) ## Timezone effect z <- ISOdate(2010, 04, 13, c(0,12)) # midnight and midday UTC as.Date(z) # in UTC ## these timezone names are common as.Date(z, tz ="NZ") as.Date(z, tz ="HST") # Hawaii as.environment Coerce to an Environment Object Description A generic function coercing an R object to an environment. A number or a character string is converted to the corresponding environment on the search path. Usage as.environment(x) 30 as.function Arguments x an R object to convert. If it is already an environment, just return it. If it is a number, return the environment corresponding to that position on the search list. If it is a character string, match the string to the names on the search list. If it is a list, the equivalent of list2env(x, parent=emptyenv()) is returned. If is.object(x) is true and it has a class for which an as.environment method is found, that is used. Value The corresponding environment object. Note This is a primitive function. Author(s) John Chambers See Also environment for creation and manipulation, search; list2env. Examples as.environment(1) ## the global environment identical(globalenv(), as.environment(1)) ## is TRUE try( ## <<- stats need not be attached as.environment("package:stats")) ee <- as.environment(list(a = "A", b = pi, ch = letters[1:8])) ls(ee) # names of objects in ee utils::ls.str(ee) as.function Convert Object to Function Description as.function is a generic function which is used to convert objects to functions. as.function.default works on a list x, which should contain the concatenation of a formal argu- ment list and an expression or an object of mode "call" which will become the function body. The function will be defined in a specified environment, by default that of the caller. as.POSIX* 31 Usage as.function(x, ...) ## Default S3 method: as.function(x, envir = parent.frame(), ...) Arguments x object to convert, a list for the default method. ... additional arguments, depending on object envir environment in which the function should be defined Value The desired function. Note For ancient historical reasons, envir = NULL uses the global environment rather than the base environment. Please use envir = globalenv() instead if this is what you want, as the special handling of NULL may change in a future release. Author(s) Peter Dalgaard See Also function; alist which is handy for the construction of argument lists, etc. Examples as.function(alist(a=,b=2,a+b)) as.function(alist(a=,b=2,a+b))(3) as.POSIX* Date-time Conversion Functions Description Functions to manipulate objects of classes "POSIXlt" and "POSIXct" representing calendar dates and times. 32 as.POSIX* Usage as.POSIXct(x, tz = "", ...) as.POSIXlt(x, tz = "", ...) ## S3 method for class ’character’ as.POSIXlt(x, tz = "", format, ...) ## S3 method for class ’numeric’ as.POSIXlt(x, tz = "", origin, ...) ## S3 method for class ’POSIXlt’ as.double(x, ...) Arguments x An object to be converted. tz A timezone specification to be used for the conversion, if one is required. System-specific (see time zones), but "" is the current timezone, and "GMT" is UTC (Universal Time, Coordinated). ... further arguments to be passed to or from other methods. format character string giving a date-time format as used by strptime. origin a date-time object, or something which can be coerced by as.POSIXct(tz="GMT") to such an object. Details The as.POSIX* functions convert an object to one of the two classes used to represent date/times (calendar dates plus time to the nearest second). They can convert a wide variety of objects, in- cluding objects of the other class and of classes "Date","date" (from package date), "chron" and "dates" (from package chron) to these classes. Dates without times are treated as being at midnight UTC. They can also convert character strings of the formats "2001-02-03" and "2001/02/03" option- ally followed by white space and a time in the format "14:52" or "14:52:03". (Formats such as "01/02/03" are ambiguous but can be converted via a format specification by strptime.) Frac- tional seconds are allowed. Alternatively, format can be specified for character vectors or factors: if it is not specified and no standard format works for all non-NA inputs an error is thrown. If format is specified, remember that some of the format specifications are locale-specific, and you may need to set the LC_TIME category appropriately via Sys.setlocale. This most often affects the use of %b,%B (month names) and %p (AM/PM). Logical NAs can be converted to either of the classes, but no other logical vectors can be. The as.double method converts "POSIXlt" objects to "POSIXct". If you are given a numeric time as the number of seconds since an epoch, see the examples. Character input is first converted to class "POSIXlt" by strptime: numeric input is first converted to "POSIXct". Any conversion that needs to go between the two date-time classes requires a time- zone: conversion from "POSIXlt" to "POSIXct" will validate times in the selected timezone. One issue is what happens at transitions to and from DST, for example in the UK as.POSIX* 33 as.POSIXct(strptime(’2011-03-27 01:30:00’, ’%Y-%m-%d %H:%M:%S’)) as.POSIXct(strptime(’2010-10-31 01:30:00’, ’%Y-%m-%d %H:%M:%S’)) are respectively invalid (the clocks went forward at 1:00 GMT to 2:00 BST) and ambiguous (the clocks went back at 2:00 BST to 1:00 GMT). What happens in such cases is OS-specific: one should expect the first to be NA, but the second could be interpreted as either BST or GMT (and common OSes give both possible values). Note too (see strftime), OS facilities may not format invalid times correctly. Value as.POSIXct and as.POSIXlt return an object of the appropriate class. If tz was specified, as.POSIXlt will give an appropriate "tzone" attribute. Date-times known to be invalid will be returned as NA. Note Some of the concepts used have to be extended backwards in time (the usage is proleptic). For example, the origin of time for the "POSIXct" class, ‘1970-01-01 00:00.00 UTC’, is before UTC was defined. More importantly, conversion is done assuming the Gregorian calendar which was introduced in 1582 and not used universally until the 20th century. One of the re-interpretations assumed by ISO 8601:2004 is that there was a year zero, even though current year numbering (and zero) is a much later concept (525 AD for year numbers from 1 AD). If you want to extract specific aspects of a time (such as the day of the week) just convert it to class "POSIXlt" and extract the relevant component(s) of the list, or if you want a character representa- tion (such as a named day of the week) use format.POSIXlt or format.POSIXct. If a timezone is needed and that specified is invalid on your system, what happens is system-specific but attempts to set it will probably be ignored. See Also DateTimeClasses for details of the classes; strptime for conversion to and from character repre- sentations. Sys.timezone for details of the (system-specific) naming of time zones. locales for locale-specific aspects. Examples (z <- Sys.time()) # the current datetime, as class "POSIXct" unclass(z) # a large integer floor(unclass(z)/86400) # the number of days since 1970-01-01 (UTC) (z <- as.POSIXlt(Sys.time())) # the current datetime, as class "POSIXlt" unlist(unclass(z)) # a list shown as a named vector ## suppose we have a time in seconds since 1960-01-01 00:00:00 GMT ## (the origin used by SAS) z <- 1472562988 # ways to convert this as.POSIXct(z, origin="1960-01-01") # local 34 AsIs as.POSIXct(z, origin="1960-01-01", tz="GMT") # in UTC as.POSIXct(z, origin=ISOdatetime(1960,1,1,0,0,0)) # local ISOdatetime(1960,1,1,0,0,0) + z # local ## SPSS dates (R-help 2006-02-16) z <- c(10485849600, 10477641600, 10561104000, 10562745600) as.Date(as.POSIXct(z, origin="1582-10-14", tz="GMT")) as.POSIXlt(Sys.time(), "GMT") # the current time in UTC ## Not run: ## These may not be correct names on your system as.POSIXlt(Sys.time(), "America/New_York") # in New York as.POSIXlt(Sys.time(), "EST5EDT") # alternative. as.POSIXlt(Sys.time(), "EST" ) # somewhere in Eastern Canada as.POSIXlt(Sys.time(), "HST") # in Hawaii as.POSIXlt(Sys.time(), "Australia/Darwin") ## End(Not run) AsIs Inhibit Interpretation/Conversion of Objects Description Change the class of an object to indicate that it should be treated ‘as is’. Usage I(x) Arguments x an object Details Function I has two main uses. • In function data.frame. Protecting an object by enclosing it in I() in a call to data.frame inhibits the conversion of character vectors to factors and the dropping of names, and ensures that matrices are inserted as single columns. I can also be used to protect objects which are to be added to a data frame, or converted to a data frame via as.data.frame. It achieves this by prepending the class "AsIs" to the object’s classes. Class "AsIs" has a few of its own methods, including for [, as.data.frame, print and format. • In function formula. There it is used to inhibit the interpretation of operators such as "+", "-","*" and "^" as formula operators, so they are used as arithmetical operators. This is interpreted as a symbol by terms.formula. assign 35 Value A copy of the object with class "AsIs" prepended to the class(es). References Chambers, J. M. (1992) Linear models. Chapter 4 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. See Also data.frame, formula assign Assign a Value to a Name Description Assign a value to a name in an environment. Usage assign(x, value, pos = -1, envir = as.environment(pos), inherits = FALSE, immediate = TRUE) Arguments x a variable name, given as a character string. No coercion is done, and the first element of a character vector of length greater than one will be used, with a warning. value a value to be assigned to x. pos where to do the assignment. By default, assigns into the current environment. See ‘Details’ for other possibilities. envir the environment to use. See ‘Details’. inherits should the enclosing frames of the environment be inspected? immediate an ignored compatibility feature. Details There are no restrictions on name: it can be a non-syntactic name (see make.names). The pos argument can specify the environment in which to assign the object in any of several ways: as an integer (the position in the search list); as the character string name of an element in the search list; or as an environment (including using sys.frame to access the currently active function calls). The envir argument is an alternative way to specify an environment, but is primarily there for back compatibility. 36 assign assign does not dispatch assignment methods, so it cannot be used to set elements of vectors, names, attributes, etc. Note that assignment to an attached list or data frame changes the attached copy and not the original object: see attach and with. Value This function is invoked for its side effect, which is assigning value to the variable x. If no envir is specified, then the assignment takes place in the currently active environment. If inherits is TRUE, enclosing environments of the supplied environment are searched until the variable x is encountered. The value is then assigned in the environment in which the variable is encountered (provided that the binding is not locked: see lockBinding: if it is, an error is signaled). If the symbol is not encountered then assignment takes place in the user’s workspace (the global environment). If inherits is FALSE, assignment takes place in the initial frame of envir, unless an existing binding is locked or there is no existing binding and the environment is locked. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also <-, get, exists, environment. Examples for(i in 1:6) { #-- Create objects ’r.1’, ’r.2’, ... ’r.6’ -- nam <- paste("r",i, sep=".") assign(nam, 1:i) } ls(pattern = "^r..$") ##-- Global assignment within a function: myf <- function(x) { innerf <- function(x) assign("Global.res", x^2, envir = .GlobalEnv) innerf(x+1) } myf(3) Global.res # 16 a <- 1:4 assign("a[1]", 2) a[1] == 2 #FALSE get("a[1]") == 2 #TRUE assignOps 37 assignOps Assignment Operators Description Assign a value to a name. Usage x <- value x <<- value value -> x value ->> x x = value Arguments x a variable name (possibly quoted). value a value to be assigned to x. Details There are three different assignment operators: two of them have leftwards and rightwards forms. The operators <- and = assign into the environment in which they are evaluated. The operator <- can be used anywhere, whereas the operator = is only allowed at the top level (e.g., in the complete expression typed at the command prompt) or as one of the subexpressions in a braced list of expressions. The operators <<- and ->> cause a search to made through the environment for an existing definition of the variable being assigned. If such a variable is found (and its binding is not locked) then its value is redefined, otherwise assignment takes place in the global environment. Note that their semantics differ from that in the S language, but are useful in conjunction with the scoping rules of R. See ‘The R Language Definition’ manual for further details and examples. In all the assignment operator expressions, x can be a name or an expression defining a part of an object to be replaced (e.g., z[[1]]). A syntactic name does not need to be quoted, though it can be (preferably by backticks). The leftwards forms of assignment <- = <<- group right to left, the other from left to right. Value value. Thus one can use a <- b <- c <- 6. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chamber, J. M. (1998) Programming with Data. A Guide to the S Language. Springer (for =). 38 attach See Also assign, for “subassignment” such as x[i] <- v,[<-; environment. attach Attach Set of R Objects to Search Path Description The database is attached to the R search path. This means that the database is searched by R when evaluating a variable, so objects in the database can be accessed by simply giving their names. Usage attach(what, pos = 2, name = deparse(substitute(what)), warn.conflicts = TRUE) Arguments what ‘database’. This can be a data.frame or a list or a R data file created with save or NULL or an environment. See also ‘Details’. pos integer specifying position in search() where to attach. name name to use for the attached database. warn.conflicts logical. If TRUE, warnings are printed about conflicts from attaching the database, unless that database contains an object .conflicts.OK. A conflict is a function masking a function, or a non-function masking a non-function. Details When evaluating a variable or function name R searches for that name in the databases listed by search. The first name of the appropriate type is used. By attaching a data frame (or list) to the search path it is possible to refer to the variables in the data frame by their names alone, rather than as components of the data frame (e.g. in the example below, height rather than women$height). By default the database is attached in position 2 in the search path, immediately after the user’s workspace and before all previously attached packages and previously attached databases. This can be altered to attach later in the search path with the pos option, but you cannot attach at pos = 1. The database is not actually attached. Rather, a new environment is created on the search path and the elements of a list (including columns of a data frame) or objects in a save file or an environment are copied into the new environment. If you use <<- or assign to assign to an attached database, you only alter the attached copy, not the original object. (Normal assignment will place a modified version in the user’s workspace: see the examples.) For this reason attach can lead to confusion. One useful ‘trick’ is to use what = NULL (or equivalently a length-zero list) to create a new envi- ronment on the search path into which objects can be assigned by assign or load or sys.source. Names starting "package:" are reserved for library and should not be used by end users. The name for an attached file is always of the form file:what, even if name is supplied. Otherwise the attr 39 name argument given for the attached environment will be used by search and can be used as the argument to as.environment. There are hooks to attach user-defined table objects of class "UserDefinedDatabase", supported by the Omegahat package RObjectTables. See http://www.omegahat.org/RObjectTables/. Value The environment is returned invisibly with a "name" attribute. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also library, detach, search, objects, environment, with. Examples require(utils) summary(women$height) # refers to variable ’height’ in the data frame attach(women) summary(height) # The same variable now available by name height <- height*2.54 # Don’t do this. It creates a new variable # in the user’s workspace find("height") summary(height) # The new variable in the workspace rm(height) summary(height) # The original variable. height <<- height*25.4 # Change the copy in the attached environment find("height") summary(height) # The changed copy detach("women") summary(women$height) # unchanged ## Not run: ## create an environment on the search path and populate it sys.source("myfuns.R", envir=attach(NULL, name="myfuns")) ## End(Not run) attr Object Attributes Description Get or set specific attributes of an object. 40 attr Usage attr(x, which, exact = FALSE) attr(x, which) <- value Arguments x an object whose attributes are to be accessed. which a non-empty character string specifying which attribute is to be accessed. exact logical: should which be matched exactly? value an object, the new value of the attribute, or NULL to remove the attribute. Details These functions provide access to a single attribute of an object. The replacement form causes the named attribute to take the value specified (or create a new attribute with the value given). The extraction function first looks for an exact match to which amongst the attributes of x, then (unless exact = TRUE) a unique partial match. (Setting options(warnPartialMatchAttr=TRUE) causes partial matches to give warnings.) The replacement function only uses exact matches. Note that some attributes (namely class, comment, dim, dimnames, names, row.names and tsp) are treated specially and have restrictions on the values which can be set. (Note that this is not true of levels which should be set for factors via the levels replacement function.) The extractor function allows (and does not match) empty and missing values of which: the re- placement function does not. Both are primitive functions. Value For the extractor, the value of the attribute matched, or NULL if no exact match is found and no or more than one partial match is found. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also attributes Examples # create a 2 by 5 matrix x <- 1:10 attr(x,"dim") <- c(2, 5) attributes 41 attributes Object Attribute Lists Description These functions access an object’s attributes. The first form below returns the object’s attribute list. The replacement forms uses the list on the right-hand side of the assignment as the object’s attributes (if appropriate). Usage attributes(obj) attributes(obj) <- value mostattributes(obj) <- value Arguments obj an object value an appropriate named list of attributes, or NULL. Details Unlike attr it is possible to set attributes on a NULL object: it will first be coerced to an empty list. Note that some attributes (namely class, comment, dim, dimnames, names, row.names and tsp) are treated specially and have restrictions on the values which can be set. (Note that this is not true of levels which should be set for factors via the levels replacement function.) Attributes are not stored internally as a list and should be thought of as a set and not a vector. They must have unique names (and NA is taken as "NA", not a missing value). Assigning attributes first removes all attributes, then sets any dim attribute and then the remaining attributes in the order given: this ensures that setting a dim attribute always precedes the dimnames attribute. The mostattributes assignment takes special care for the dim, names and dimnames attributes, and assigns them only when known to be valid whereas an attributes assignment would give an error if any are not. It is principally intended for arrays, and should be used with care on classed objects. For example, it does not check that row.names are assigned correctly for data frames. The names of a pairlist are not stored as attributes, but are reported as if they were (and can be set by the replacement form of attributes). Both assignment and replacement forms of attributes are primitive functions. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. 42 autoload See Also attr. Examples x <- cbind(a=1:3, pi=pi) # simple matrix w/ dimnames attributes(x) ## strip an object’s attributes: attributes(x) <- NULL x # now just a vector of length 6 mostattributes(x) <- list(mycomment = "really special", dim = 3:2, dimnames = list(LETTERS[1:3], letters[1:5]), names = paste(1:6)) x # dim(), but not {dim}names autoload On-demand Loading of Packages Description autoload creates a promise-to-evaluate autoloader and stores it with name name in .AutoloadEnv environment. When R attempts to evaluate name, autoloader is run, the package is loaded and name is re-evaluated in the new package’s environment. The result is that R behaves as if file was loaded but it does not occupy memory. .Autoloaded contains the names of the packages for which autoloading has been promised. Usage autoload(name, package, reset = FALSE, ...) autoloader(name, package, ...) .AutoloadEnv .Autoloaded Arguments name string giving the name of an object. package string giving the name of a package containing the object. reset logical: for internal use by autoloader. ... other arguments to library. Value This function is invoked for its side-effect. It has no return value. backsolve 43 See Also delayedAssign, library Examples require(stats) autoload("interpSpline", "splines") search() ls("Autoloads") .Autoloaded x <- sort(stats::rnorm(12)) y <- x^2 is <- interpSpline(x,y) search() ## now has splines detach("package:splines") search() is2 <- interpSpline(x,y+x) search() ## and again detach("package:splines") backsolve Solve an Upper or Lower Triangular System Description Solves a system of linear equations where the coefficient matrix is upper (or ‘right’, ‘R’) or lower (‘left’, ‘L’) triangular. x <- backsolve (R, b) solves Rx = b, and x <- forwardsolve(L, b) solves Lx = b, respectively. Usage backsolve(r, x, k=ncol(r), upper.tri=TRUE, transpose=FALSE) forwardsolve(l, x, k=ncol(l), upper.tri=FALSE, transpose=FALSE) Arguments r,l an upper (or lower) triangular matrix giving the coefficients for the system to be solved. Values below (above) the diagonal are ignored. x a matrix whose columns give the right-hand sides for the equations. k The number of columns of r and rows of x to use. upper.tri logical; if TRUE (default), the upper triangular part of r is used. Otherwise, the lower one. transpose logical; if TRUE, solve r0 ∗ y = x for y, i.e., t(r) %*% y == x. 44 basename Value The solution of the triangular system. The result will be a vector if x is a vector and a matrix if x is a matrix. Note that forwardsolve(L, b) is just a wrapper for backsolve(L, b, upper.tri=FALSE). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Dongarra, J. J., Bunch,J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications. See Also chol, qr, solve. Examples ## upper triangular matrix ’r’: r <- rbind(c(1,2,3), c(0,1,1), c(0,0,2)) ( y <- backsolve(r, x <- c(8,4,2)) ) # -1 3 1 r %*% y # == x = (8,4,2) backsolve(r, x, transpose = TRUE) # 8 -12 -5 basename Manipulate File Paths Description basename removes all of the path up to and including the last path separator (if any). dirname returns the part of the path up to but excluding the last path separator, or "." if there is no path separator. Usage basename(path) dirname(path) Arguments path character vector, containing path names. Bessel 45 Details For dirname tilde expansion of the path is done. Trailing path separators are removed before dissecting the path, and for dirname any trailing file separators are removed from the result. Value A character vector of the same length as path. A zero-length input will give a zero-length output with no error. If an element of path is NA, so is the result. Behaviour on Windows On Windows this will accept either \ or / as the path separator, but dirname will return a path using /(except if on a network share, when the leading \\ will be preserved). Expect these only to be able to handle complete paths, and not for example just a share or a drive. UTF-8-encoded dirnames not valid in the current locale can be used. Note These are not wrappers for the POSIX system functions of the same names: in particular they do not have the special handling of the path "/" and of returning "." for empty strings in basename. See Also file.path, path.expand. Examples basename(file.path("","p1","p2","p3", c("file1", "file2"))) dirname(file.path("","p1","p2","p3","filename")) Bessel Bessel Functions Description Bessel Functions of integer and fractional order, of first and second kind, Jν and Yν, and Modified Bessel functions (of first and third kind), Iν and Kν. Usage besselI(x, nu, expon.scaled = FALSE) besselK(x, nu, expon.scaled = FALSE) besselJ(x, nu) besselY(x, nu) 46 Bessel Arguments x numeric, ≥ 0. nu numeric; The order (maybe fractional!) of the corresponding Bessel function. expon.scaled logical; if TRUE, the results are exponentially scaled in order to avoid overflow (Iν) or underflow (Kν), respectively. Details If expon.scaled = TRUE, e−xIν(x), or exKν(x) are returned. For ν < 0, formulae 9.1.2 and 9.6.2 from Abramowitz & Stegun are applied (which is probably suboptimal), except for besselK which is symmetric in nu. Value Numeric vector of the same length of x with the (scaled, if expon.scaled=TRUE) values of the corresponding Bessel function. Author(s) Original Fortran code: W. J. Cody, Argonne National Laboratory Translation to C and adaption to R: Martin Maechler . Source The C code is a translation of Fortran routines from http://www.netlib.org/specfun/ribesl, ‘../rjbesl’, etc. References Abramowitz, M. and Stegun, I. A. (1972) Handbook of Mathematical Functions. Dover, New York; Chapter 9: Bessel Functions of Integer Order. See Also Other special mathematical functions, such as gamma, Γ(x), and beta,B(x). Examples require(graphics) nus <- c(0:5, 10, 20) x <- seq(0, 4, length.out = 501) plot(x, x, ylim = c(0, 6), ylab = "", type = "n", main = "Bessel Functions I_nu(x)") for(nu in nus) lines(x, besselI(x, nu=nu), col = nu+2) legend(0, 6, legend = paste("nu=", nus), col = nus+2, lwd = 1) x <- seq(0, 40, length.out = 801); yl <- c(-.8, .8) Bessel 47 plot(x, x, ylim = yl, ylab = "", type = "n", main = "Bessel Functions J_nu(x)") for(nu in nus) lines(x, besselJ(x, nu=nu), col = nu+2) legend(32,-.18, legend = paste("nu=", nus), col = nus+2, lwd = 1) ## Negative nu’s : xx <- 2:7 nu <- seq(-10, 9, length.out = 2001) op <- par(lab = c(16, 5, 7)) matplot(nu, t(outer(xx, nu, besselI)), type = "l", ylim = c(-50, 200), main = expression(paste("Bessel ", I[nu](x), " for fixed ", x, ", as ", f(nu))), xlab = expression(nu)) abline(v=0, col = "light gray", lty = 3) legend(5, 200, legend = paste("x=", xx), col=seq(xx), lty=seq(xx)) par(op) x0 <- 2^(-20:10) plot(x0, x0^-8, log="xy", ylab="",type="n", main = "Bessel Functions J_nu(x) near 0\n log - log scale") for(nu in sort(c(nus, nus+.5))) lines(x0, besselJ(x0, nu=nu), col = nu+2) legend(3, 1e50, legend = paste("nu=", paste(nus, nus+.5, sep=",")), col = nus + 2, lwd = 1) plot(x0, x0^-8, log="xy", ylab="", type="n", main = "Bessel Functions K_nu(x) near 0\n log - log scale") for(nu in sort(c(nus, nus+.5))) lines(x0, besselK(x0, nu=nu), col = nu+2) legend(3, 1e50, legend = paste("nu=", paste(nus, nus+.5, sep=",")), col = nus + 2, lwd = 1) x <- x[x > 0] plot(x, x, ylim=c(1e-18, 1e11), log = "y", ylab = "", type = "n", main = "Bessel Functions K_nu(x)") for(nu in nus) lines(x, besselK(x, nu=nu), col = nu+2) legend(0, 1e-5, legend=paste("nu=", nus), col = nus+2, lwd = 1) yl <- c(-1.6, .6) plot(x, x, ylim = yl, ylab = "", type = "n", main = "Bessel Functions Y_nu(x)") for(nu in nus){ xx <- x[x > .6*nu] lines(xx, besselY(xx, nu=nu), col = nu+2) } legend(25, -.5, legend = paste("nu=", nus), col = nus+2, lwd = 1) ## negative nu in bessel_Y -- was bogus for a long time curve(besselY(x, -0.1), 0, 10, ylim = c(-3,1), ylab = ’’) for(nu in c(seq(-0.2, -2, by = -0.1))) curve(besselY(x, nu), add = TRUE) title(expression(besselY(x, nu) * " " * {nu == list(-0.1, -0.2, ..., -2)})) 48 bindenv bindenv Binding and Environment Adjustments Description These functions represent an experimental interface for adjustments to environments and bindings within environments. They allow for locking environments as well as individual bindings, and for linking a variable to a function. Usage lockEnvironment(env, bindings = FALSE) environmentIsLocked(env) lockBinding(sym, env) unlockBinding(sym, env) bindingIsLocked(sym, env) makeActiveBinding(sym, fun, env) bindingIsActive(sym, env) Arguments env an environment. bindings logical specifying whether bindings should be locked. sym a name object or character string fun a function taking zero or one arguments Details The function lockEnvironment locks its environment argument, which must be a normal environ- ment (not base). (Locking the base environment and namespace may be supported later.) Locking the environment prevents adding or removing variable bindings from the environment. Changing the value of a variable is still possible unless the binding has been locked. The namespace environ- ments of packages with namespaces are locked when loaded. lockBinding locks individual bindings in the specified environment. The value of a locked binding cannot be changed. Locked bindings may be removed from an environment unless the environment is locked. makeActiveBinding installs fun so that getting the value of sym calls fun with no arguments, and assigning to sym calls fun with one argument, the value to be assigned. This allows the implemen- tation of things like C variables linked to R variables and variables linked to databases. It may also be useful for making thread-safe versions of some system globals. Value The *isLocked functions return a length-one logical vector. The remaining functions return NULL, invisibly. body 49 Author(s) Luke Tierney Examples # locking environments e <- new.env() assign("x", 1, envir = e) get("x", envir = e) lockEnvironment(e) get("x", envir = e) assign("x", 2, envir = e) try(assign("y", 2, envir = e)) # error # locking bindings e <- new.env() assign("x", 1, envir = e) get("x", envir = e) lockBinding("x", e) try(assign("x", 2, envir = e)) # error unlockBinding("x", e) assign("x", 2, envir = e) get("x", envir = e) # active bindings f <- local( { x <- 1 function(v) { if (missing(v)) cat("get\n") else { cat("set\n") x <<- v } x } }) makeActiveBinding("fred", f, .GlobalEnv) bindingIsActive("fred", .GlobalEnv) fred fred <- 2 fred body Access to and Manipulation of the Body of a Function Description Get or set the body of a function. 50 body Usage body(fun = sys.function(sys.parent())) body(fun, envir = environment(fun)) <- value Arguments fun a function object, or see ‘Details’. envir environment in which the function should be defined. value an object, usually a language object: see section ‘Value’. Details For the first form, fun can be a character string naming the function to be manipulated, which is searched for from the parent frame. If it is not specified, the function calling body is used. The bodies of all but the simplest are braced expressions, that is calls to {: see the ‘Examples’ section for how to create such a call. Value body returns the body of the function specified. This is normally a language object, most often a call to {, but it can also be an object (e.g. pi) to be the return value of the function. The replacement form sets the body of a function to the object on the right hand side, and (poten- tially) resets the environment of the function. If value is of class "expression" the first element is used as the body: any additional elements are ignored, with a warning. See Also alist, args, function. Examples body(body) f <- function(x) x^5 body(f) <- quote(5^x) ## or equivalently body(f) <- expression(5^x) f(3) # = 125 body(f) ## creating a multi-expression body e <- expression(y <- x^2, return(y)) # or a list body(f) <- as.call(c(as.name("{"), e)) f f(8) bquote 51 bquote Partial substitution in expressions Description An analogue of the LISP backquote macro. bquote quotes its argument except that terms wrapped in .() are evaluated in the specified where environment. Usage bquote(expr, where = parent.frame()) Arguments expr A language object. where An environment. Value A language object. See Also quote, substitute Examples require(graphics) a <- 2 bquote(a == a) quote(a == a) bquote(a == .(a)) substitute(a == A, list(A = a)) plot(1:10, a*(1:10), main = bquote(a == .(a))) ## to set a function default arg default <- 1 bquote( function(x, y = .(default)) x+y ) 52 browser browser Environment Browser Description Interrupt the execution of an expression and allow the inspection of the environment where browser was called from. Usage browser(text="", condition=NULL, expr=TRUE, skipCalls=0L) Arguments text a text string that can be retrieved once the browser is invoked. condition a condition that can be retrieved once the browser is invoked. expr An expression, which if it evaluates to TRUE the debugger will invoked, other- wise control is returned directly. skipCalls how many previous calls to skip when reporting the calling context. Details A call to browser can be included in the body of a function. When reached, this causes a pause in the execution of the current expression and allows access to the R interpreter. The purpose of the text and condition arguments are to allow helper programs (e.g. external debuggers) to insert specific values here, so that the specific call to browser (perhaps its location in a source file) can be identified and special processing can be achieved. The values can be retrieved by calling browserText and browserCondition. The purpose of the expr argument is to allow for the illusion of conditional debugging. It is an illusion, because execution is always paused at the call to browser, but control is only passed to the evaluator described below if expr evaluates to TRUE. In most cases it is going to be more efficient to use an if statement in the calling program, but in some cases using this argument will be simpler. The skipCalls argument should be used when the browser() call is nested within another debug- ging function: it will look further up the call stack to report its location. At the browser prompt the user can enter commands or R expressions, followed by a newline. The commands are c (or just an empty line, by default) exit the browser and continue execution at the next statement. cont synonym for c. n enter the step-through debugger. This changes the meaning of c: see the documentation for debug. where print a stack trace of all active function calls. Q exit the browser and the current evaluation and return to the top-level prompt. browserText 53 (Leading and trailing whitespace is ignored, except for an empty line). Anything else entered at the browser prompt is interpreted as an R expression to be evaluated in the calling environment: in particular typing an object name will cause the object to be printed, and ls() lists the objects in the calling frame. (If you want to look at an object with a name such as n, print it explicitly.) The number of lines printed for the deparsed call can be limited by setting options(deparse.max.lines). Setting option "browserNLdisabled" to TRUE disables the use of an empty line as a synonym for c. If this is done, the user will be re-prompted for input until a valid command or an expression is entered. This is a primitive function but does argument matching in the standard way. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also debug, and traceback for the stack on error. browserText for how to retrieve the text and condi- tion. browserText Functions to Retrieve Values Supplied by Calls to the Browser Description A call to browser can provide context by supplying either a text argument or a condition argument. These functions can be used to retrieve either of these arguments. Usage browserText(n=1) browserCondition(n=1) browserSetDebug(n=1) Arguments n The number of contexts to skip over, it must be non-negative. 54 builtins Details Each call to browser can supply either a text string or a condition. The functions browserText and browserCondition provide ways to retrieve those values. Since there can be multiple browser con- texts active at any time we also support retrieving values from the different contexts. The innermost (most recently initiated) browser context is numbered 1: other contexts are numbered sequentially. browserSetDebug provides a mechanism for initiating the browser in one of the calling functions. See sys.frame for a more complete discussion of the calling stack. To use browserSetDebug you select some calling function, determine how far back it is in the call stack and call browserSetDebug with n set to that value. Then, by typing c at the browser prompt you will cause evaluation to continue, and provided there are no intervening calls to browser or other inter- rupts, control will halt again once evaluation has returned to the closure specified. This is similar to the up functionality in gdb or the "step out" functionality in other debuggers. Value browserText returns the text, while browserCondition returns the condition from the specified browser context. browserSetDebug returns NULL, invisibly. Note It may be of interest to allow for querying further up the set of browser contexts and this function- ality may be added at a later date. Author(s) R. Gentleman See Also browser builtins Returns the Names of All Built-in Objects Description Return the names of all the built-in objects. These are fetched directly from the symbol table of the R interpreter. Usage builtins(internal = FALSE) Arguments internal a logical indicating whether only ‘internal’ functions (which can be called via .Internal) should be returned. by 55 Details builtins() returns an unsorted list of the objects in the symbol table, that is all the objects in the base environment. These are the built-in objects plus any that have been added subsequently when the base package was loaded. It is less confusing to use ls(baseenv(), all=TRUE). builtins(TRUE) returns an unsorted list of the names of internal functions, that is those which can be accessed as .Internal(foo(args ...)) for foo in the list. Value A character vector. by Apply a Function to a Data Frame Split by Factors Description Function by is an object-oriented wrapper for tapply applied to data frames. Usage by(data, INDICES, FUN, ..., simplify = TRUE) Arguments data an R object, normally a data frame, possibly a matrix. INDICES a factor or a list of factors, each of length nrow(data). FUN a function to be applied to data frame subsets of data. ... further arguments to FUN. simplify logical: see tapply. Details A data frame is split by row into data frames subsetted by the values of one or more factors, and function FUN is applied to each subset in turn. Object data will be coerced to a data frame by the default method, but if this results in a 1-column data frame, the objects passed to FUN are dropped to a subsets of that column. Value An object of class "by", giving the results for each subset. This is always a list if simplify is false, otherwise a list or array (see tapply). See Also tapply, simplify2array. ave also applies a function block-wise. 56 c Examples require(stats) by(warpbreaks[, 1:2], warpbreaks[,"tension"], summary) by(warpbreaks[, 1], warpbreaks[, -1], summary) by(warpbreaks, warpbreaks[,"tension"], function(x) lm(breaks ~ wool, data = x)) ## now suppose we want to extract the coefficients by group tmp <- with(warpbreaks, by(warpbreaks, tension, function(x) lm(breaks ~ wool, data = x))) sapply(tmp, coef) c Combine Values into a Vector or List Description This is a generic function which combines its arguments. The default method combines its arguments to form a vector. All arguments are coerced to a com- mon type which is the type of the returned value, and all attributes except names are removed. Usage c(..., recursive=FALSE) Arguments ... objects to be concatenated. recursive logical. If recursive = TRUE, the function recursively descends through lists (and pairlists) combining all their elements into a vector. Details The output type is determined from the highest type of the components in the hierarchy NULL < raw < logical < integer < real < complex < character < list < expression. Pairlists are treated as lists, but non-vector components (such names and calls) are treated as one-element lists which cannot be unlisted even if recursive = TRUE. c is sometimes used for its side effect of removing attributes except names, for example to turn an array into a vector. as.vector is a more intuitive way to do this, but also drops names. Note too that methods other than the default are not required to do this (and they will almost certainly preserve a class attribute). This is a primitive function. Value NULL or an expression or a vector of an appropriate mode. (With no arguments the value is NULL.) call 57 S4 methods This function is S4 generic, but with argument list (x, ..., recursive = FALSE). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also unlist and as.vector to produce attribute-free vectors. Examples c(1,7:9) c(1:5, 10.5, "next") ## uses with a single argument to drop attributes x <- 1:4 names(x) <- letters[1:4] x c(x) # has names as.vector(x) # no names dim(x) <- c(2,2) x c(x) as.vector(x) ## append to a list: ll <- list(A = 1, c="C") ## do *not* use c(ll, d = 1:3) # which is == c(ll, as.list(c(d=1:3)) ## but rather c(ll, d = list(1:3))# c() combining two lists c(list(A=c(B=1)), recursive=TRUE) c(options(), recursive=TRUE) c(list(A=c(B=1,C=2), B=c(E=7)), recursive=TRUE) call Function Calls Description Create or test for objects of mode "call". 58 call Usage call(name, ...) is.call(x) as.call(x) Arguments name a non-empty character string naming the function to be called. ... arguments to be part of the call. x an arbitrary R object. Details call returns an unevaluated function call, that is, an unevaluated expression which consists of the named function applied to the given arguments (name must be a quoted string which gives the name of a function to be called). Note that although the call is unevaluated, the arguments ... are evaluated. call is a primitive, so the first argument is taken as name and the remaining arguments as arguments for the constructed call: if the first argument is named the name must partially match name. is.call is used to determine whether x is a call (i.e., of mode "call"). Objects of mode "list" can be coerced to mode "call". The first element of the list becomes the function part of the call, so should be a function or the name of one (as a symbol; a quoted string will not do). All three are primitive functions. call is ‘special’: it only evaluates its first argument. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also do.call for calling a function by name and argument list; Recall for recursive calling of functions; further is.language, expression, function. Examples is.call(call) #-> FALSE: Functions are NOT calls ## set up a function call to round with argument 10.5 cl <- call("round", 10.5) is.call(cl)# TRUE cl ## such a call can also be evaluated. eval(cl)# [1] 10 A <- 10.5 call("round", A) # round(10.5) callCC 59 call("round", quote(A)) # round(A) f <- "round" call(f, quote(A)) # round(A) ## if we want to supply a function we need to use as.call or similar f <- round ## Not run: call(f, quote(A)) # error: first arg must be character (g <- as.call(list(f, quote(A)))) eval(g) ## alternatively but less transparently g <- list(f, quote(A)) mode(g) <- "call" g eval(g) ## see also the examples in the help for do.call callCC Call With Current Continuation Description A downward-only version of Scheme’s call with current continuation. Usage callCC(fun) Arguments fun function of one argument, the exit procedure. Details callCC provides a non-local exit mechanism that can be useful for early termination of a com- putation. callCC calls fun with one argument, an exit function. The exit function takes a single argument, the intended return value. If the body of fun calls the exit function then the call to callCC immediately returns, with the value supplied to the exit function as the value returned by callCC. Author(s) Luke Tierney Examples # The following all return the value 1 callCC(function(k) 1) callCC(function(k) k(1)) callCC(function(k) {k(1); 2}) callCC(function(k) repeat k(1)) 60 capabilities capabilities Report Capabilities of this Build of R Description Report on the optional features which have been compiled into this build of R. Usage capabilities(what = NULL) Arguments what character vector or NULL, specifying required components. NULL implies that all are required. Value A named logical vector. Current components are jpeg is the jpeg function operational? png is the png function operational? tiff is the tiff function operational? tcltk is the tcltk package operational? Note that to make use of Tk you will almost always need to check that "X11" is also available. X11 Are the X11 graphics device and the X11-based data editor available? This loads the X11 module if not already loaded, and checks that the default display can be contacted unless a X11 device has already been used. aqua Are the R.app GUI components and the quartz function operational? Only on some Mac OS X builds. Note that this is distinct from .Platform$GUI == "AQUA", which is true when using the Mac R.app GUI console. http/ftp Are url and the internal method for download.file available? sockets Are make.socket and related functions available? libxml is there support for integrating libxml with the R event loop? fifo are FIFO connections supported? cledit is command-line editing available in the current R session? This is false in non- interactive sessions. It will be true for the command-line interface if readline support has been compiled in and ‘--no-readline’ was not used when R was invoked. iconv is internationalization conversion via iconv supported? Always true as from R 2.10.0. NLS is there Natural Language Support (for message translations)? profmem is there support for memory profiling? cairo is there support the svg, cairo_pdf and cairo_ps devices, and for type = "cairo" in the X11, bmp, jpeg, png, and tiff devices? cat 61 Note to Mac OS X users Capabilities "jpeg","png" and "tiff" refer to the X11-based versions of these devices. If capabilities("aqua") is true, then these devices with type="quartz" will be available, and out-of-the-box will be the default type. Thus for example the tiff device will be available if capabilities("aqua") || capabilities("tiff") if the defaults are unchanged. See Also .Platform Examples capabilities() if(!capabilities("http/ftp")) warning("internal download.file() is not available") ## See also the examples for ’connections’. cat Concatenate and Print Description Outputs the objects, concatenating the representations. cat performs much less conversion than print. Usage cat(... , file = "", sep = " ", fill = FALSE, labels = NULL, append = FALSE) Arguments ... R objects (see ‘Details’ for the types of objects allowed). file A connection, or a character string naming the file to print to. If "" (the default), cat prints to the standard output connection, the console unless redirected by sink. If it is "|cmd", the output is piped to the command given by ‘cmd’, by opening a pipe connection. sep a character vector of strings to append after each element. fill a logical or (positive) numeric controlling how the output is broken into suc- cessive lines. If FALSE (default), only newlines created explicitly by ‘"\n"’ are printed. Otherwise, the output is broken into lines with print width equal to the option width if fill is TRUE, or the value of fill if this is numeric. Non- positive fill values are ignored, with a warning. labels character vector of labels for the lines printed. Ignored if fill is FALSE. 62 cat append logical. Only used if the argument file is the name of file (and not a connection or "|cmd"). If TRUE output will be appended to file; otherwise, it will overwrite the contents of file. Details cat is useful for producing output in user-defined functions. It converts its arguments to character vectors, concatenates them to a single character vector, appends the given sep= string(s) to each element and then outputs them. No linefeeds are output unless explicitly requested by ‘"\n"’ or if generated by filling (if argument fill is TRUE or numeric.) If file is a connection and open for writing it is written from its current position. If it is not open, it is opened for the duration of the call in "wt" mode and then closed again. Currently only atomic vectors and names are handled, together with NULL and other zero-length objects (which produce no output). Character strings are output ‘as is’ (unlike print.default which escapes non-printable characters and backslash — use encodeString if you want to output encoded strings using cat). Other types of R object should be converted (e.g. by as.character or format) before being passed to cat. cat converts numeric/complex elements in the same way as print (and not in the same way as as.character which is used by the S equivalent), so options "digits" and "scipen" are rele- vant. However, it uses the minimum field width necessary for each element, rather than the same field width for all elements. Value None (invisible NULL). Note If any element of sep contains a newline character, it is treated as a vector of terminators rather than separators, an element being output after every vector element and a newline after the last. Entries are recycled as needed. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also print, format, and paste which concatenates into a string. Examples iter <- stats::rpois(1, lambda=10) ## print an informative message cat("iteration = ", iter <- iter + 1, "\n") ## ’fill’ and label lines: cbind 63 cat(paste(letters, 100* 1:26), fill = TRUE, labels = paste("{",1:10,"}:",sep="")) cbind Combine R Objects by Rows or Columns Description Take a sequence of vector, matrix or data frames arguments and combine by columns or rows, respectively. These are generic functions with methods for other R classes. Usage cbind(..., deparse.level = 1) rbind(..., deparse.level = 1) Arguments ... vectors or matrices. These can be given as named arguments. Other R objects will be coerced as appropriate: see sections ‘Details’ and ‘Value’. (For the "data.frame" method of cbind these can be further arguments to data.frame such as stringsAsFactors.) deparse.level integer controlling the construction of labels in the case of non-matrix-like ar- guments (for the default method): deparse.level = 0 constructs no labels; the default, deparse.level = 1 or 2 constructs labels from the argument names, see the ‘Value’ section below. Details The functions cbind and rbind are S3 generic, with methods for data frames. The data frame method will be used if at least one argument is a data frame and the rest are vectors or matrices. There can be other methods; in particular, there is one for time series objects. See the section on ‘Dispatch’ for how the method to be used is selected. In the default method, all the vectors/matrices must be atomic (see vector) or lists. Expressions are not allowed. Language objects (such as formulae and calls) and pairlists will be coerced to lists: other objects (such as names and external pointers) will be included as elements in a list result. Any classes the inputs might have are discarded (in particular, factors are replaced by their internal codes). If there are several matrix arguments, they must all have the same number of columns (or rows) and this will be the number of columns (or rows) of the result. If all the arguments are vectors, the number of columns (rows) in the result is equal to the length of the longest vector. Values in shorter arguments are recycled to achieve this length (with a warning if they are recycled only fractionally). When the arguments consist of a mix of matrices and vectors the number of columns (rows) of the result is determined by the number of columns (rows) of the matrix arguments. Any vectors have their values recycled or subsetted to achieve this length. For cbind (rbind), vectors of zero length (including NULL) are ignored unless the result would have zero rows (columns), for S compatibility. (Zero-extent matrices do not occur in S3 and are not ignored in R.) 64 cbind Value For the default method, a matrix combining the ... arguments column-wise or row-wise. (Excep- tion: if there are no inputs or all the inputs are NULL, the value is NULL.) The type of a matrix result determined from the highest type of any of the inputs in the hierarchy raw < logical < integer < real < complex < character < list . For cbind (rbind) the column (row) names are taken from the colnames (rownames) of the argu- ments if these are matrix-like. Otherwise from the names of the arguments or where those are not supplied and deparse.level > 0, by deparsing the expressions given, for deparse.level = 1 only if that gives a sensible name (a ‘symbol’, see is.symbol). For cbind row names are taken from the first argument with appropriate names: rownames for a matrix, or names for a vector of length the number of rows of the result. For rbind column names are taken from the first argument with appropriate names: colnames for a matrix, or names for a vector of length the number of columns of the result. Data frame methods The cbind data frame method is just a wrapper for data.frame(..., check.names = FALSE). This means that it will split matrix columns in data frame arguments, and convert character columns to factors unless stringsAsFactors = FALSE is specified. The rbind data frame method first drops all zero-column and zero-row arguments. (If that leaves none, it returns the first argument with columns otherwise a zero-column zero-row data frame.) It then takes the classes of the columns from the first data frame, and matches columns by name (rather than by position). Factors have their levels expanded as necessary (in the order of the levels of the levelsets of the factors encountered) and the result is an ordered factor if and only if all the components were ordered factors. (The last point differs from S-PLUS.) Old-style categories (integer vectors with levels) are promoted to factors. Dispatch The method dispatching is not done via UseMethod(), but by C-internal dispatching. Therefore there is no need for, e.g., rbind.default. The dispatch algorithm is described in the source file (‘.../src/main/bind.c’) as 1. For each argument we get the list of possible class memberships from the class attribute. 2. We inspect each class in turn to see if there is an applicable method. 3. If we find an applicable method we make sure that it is identical to any method determined for prior arguments. If it is identical, we proceed, otherwise we immediately drop through to the default code. If you want to combine other objects with data frames, it may be necessary to coerce them to data frames first. (Note that this algorithm can result in calling the data frame method if all the arguments are either data frames or vectors, and this will result in the coercion of character vectors to factors.) References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. char.expand 65 See Also c to combine vectors (and lists) as vectors, data.frame to combine vectors and matrices as a data frame. Examples m <- cbind(1, 1:7) # the ’1’ (= shorter vector) is recycled m m <- cbind(m, 8:14)[, c(1, 3, 2)] # insert a column m cbind(1:7, diag(3))# vector is subset -> warning cbind(0, rbind(1, 1:3)) cbind(I=0, X=rbind(a=1, b=1:3)) # use some names xx <- data.frame(I=rep(0,2)) cbind(xx, X=rbind(a=1, b=1:3)) # named differently cbind(0, matrix(1, nrow=0, ncol=4))#> Warning (making sense) dim(cbind(0, matrix(1, nrow=2, ncol=0)))#-> 2 x 1 ## deparse.level dd <- 10 rbind(1:4, c=2, "a++" = 10, dd, deparse.level=0)# middle 2 rownames rbind(1:4, c=2, "a++" = 10, dd, deparse.level=1)# 3 rownames (default) rbind(1:4, c=2, "a++" = 10, dd, deparse.level=2)# 4 rownames char.expand Expand a String with Respect to a Target Table Description Seeks a unique match of its first argument among the elements of its second. If successful, it returns this element; otherwise, it performs an action specified by the third argument. Usage char.expand(input, target, nomatch = stop("no match")) Arguments input a character string to be expanded. target a character vector with the values to be matched against. nomatch an R expression to be evaluated in case expansion was not possible. Details This function is particularly useful when abbreviations are allowed in function arguments, and need to be uniquely expanded with respect to a target table of possible values. 66 character Value A length-one character vector, one of the elements of target (unless nomatch is changed to be a non-error, when it can be a zero-length character string). See Also charmatch and pmatch for performing partial string matching. Examples locPars <- c("mean", "median", "mode") char.expand("me", locPars, warning("Could not expand!")) char.expand("mo", locPars) character Character Vectors Description Create or test for objects of type "character". Usage character(length = 0) as.character(x, ...) is.character(x) Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. Details as.character and is.character are generic: you can write methods to handle specific classes of objects, see InternalMethods. Further, for as.character the default method calls as.vector, so dispatch is first on methods for as.character and then for methods for as.vector. as.character represents real and complex numbers to 15 significant digits (technically the com- piler’s setting of the ISO C constant DBL_DIG, which will be 15 on machines supporting IEC60559 arithmetic according to the C99 standard). This ensures that all the digits in the result will be reli- able (and not the result of representation error), but does mean that conversion to character and back to numeric may change the number. If you want to convert numbers to character with the maximum possible precision, use format. charmatch 67 Value character creates a character vector of the specified length. The elements of the vector are all equal to "". as.character attempts to coerce its argument to character type; like as.vector it strips attributes including names. For lists it deparses the elements individually, except that it extracts the first element of length-one character vectors. is.character returns TRUE or FALSE depending on whether its argument is of character type or not. Note as.character truncates components of language objects to 500 characters (was about 70 before 1.3.1). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also paste, substr and strsplit for character concatenation and splitting, chartr for character trans- lation and casefolding (e.g., upper to lower case) and sub, grep etc for string matching and substi- tutions. Note that help.search(keyword = "character") gives even more links. deparse, which is normally preferable to as.character for language objects. Examples form <- y ~ a + b + c as.character(form) ## length 3 deparse(form) ## like the input a0 <- 11/999 # has a repeating decimal representation (a1 <- as.character(a0)) format(a0, digits=16) # shows one more digit a2 <- as.numeric(a1) a2 - a0 # normally around -1e-17 as.character(a2) # normally different from a1 print(c(a0, a2), digits = 16) charmatch Partial String Matching Description charmatch seeks matches for the elements of its first argument among those of its second. 68 charmatch Usage charmatch(x, table, nomatch = NA_integer_) Arguments x the values to be matched: converted to a character vector by as.character. table the values to be matched against: converted to a character vector. nomatch the (integer) value to be returned at non-matching positions. Details Exact matches are preferred to partial matches (those where the value to be matched has an exact match to the initial part of the target, but the target is longer). If there is a single exact match or no exact match and a unique partial match then the index of the matching value is returned; if multiple exact or multiple partial matches are found then 0 is returned and if no match is found then nomatch is returned. NA values are treated as the string constant "NA". Value An integer vector of the same length as x, giving the indices of the elements in table which matched, or nomatch. Author(s) This function is based on a C function written by Terry Therneau. See Also pmatch, match. grep or regexpr for more general (regexp) matching of strings. Examples charmatch("", "") # returns 1 charmatch("m", c("mean", "median", "mode")) # returns 0 charmatch("med", c("mean", "median", "mode")) # returns 2 chartr 69 chartr Character Translation and Casefolding Description Translate characters in character vectors, in particular from upper to lower case or vice versa. Usage chartr(old, new, x) tolower(x) toupper(x) casefold(x, upper = FALSE) Arguments x a character vector, or an object that can be coerced to character by as.character. old a character string specifying the characters to be translated. If a character vector of length 2 or more is supplied, the first element is used with a warning. new a character string specifying the translations. If a character vector of length 2 or more is supplied, the first element is used with a warning. upper logical: translate to upper or lower case?. Details chartr translates each character in x that is specified in old to the corresponding character specified in new. Ranges are supported in the specifications, but character classes and repeated characters are not. If old contains more characters than new, an error is signaled; if it contains fewer characters, the extra characters at the end of new are ignored. tolower and toupper convert upper-case characters in a character vector to lower-case, or vice versa. Non-alphabetic characters are left unchanged. casefold is a wrapper for tolower and toupper provided for compatibility with S-PLUS. Value A character vector of the same length and with the same attributes as x (after possible coercion). Elements of the result will be have the encoding declared as that of the current locale (see Encoding if the corresponding input had a declared encoding and the current locale is either Latin-1 or UTF- 8. The result will be in the current locale’s encoding unless the corresponding input was in UTF-8, when it will be in UTF-8 when the system has Unicode wide characters. See Also sub and gsub for other substitutions in strings. 70 chol Examples x <- "MiXeD cAsE 123" chartr("iXs", "why", x) chartr("a-cX", "D-Fw", x) tolower(x) toupper(x) ## "Mixed Case" Capitalizing - toupper( every first letter of a word ) : .simpleCap <- function(x) { s <- strsplit(x, " ")[[1]] paste(toupper(substring(s, 1,1)), substring(s, 2), sep="", collapse=" ") } .simpleCap("the quick red fox jumps over the lazy brown dog") ## -> [1] "The Quick Red Fox Jumps Over The Lazy Brown Dog" ## and the better, more sophisticated version: capwords <- function(s, strict = FALSE) { cap <- function(s) paste(toupper(substring(s,1,1)), {s <- substring(s,2); if(strict) tolower(s) else s}, sep = "", collapse = " " ) sapply(strsplit(s, split = " "), cap, USE.NAMES = !is.null(names(s))) } capwords(c("using AIC for model selection")) ## -> [1] "Using AIC For Model Selection" capwords(c("using AIC", "for MODEL selection"), strict=TRUE) ## -> [1] "Using Aic" "For Model Selection" ## ^^^ ^^^^^ ## ’bad’ ’good’ ## -- Very simple insecure crypto -- rot <- function(ch, k = 13) { p0 <- function(...) paste(c(...), collapse="") A <- c(letters, LETTERS, " ’") I <- seq_len(k); chartr(p0(A), p0(c(A[-I], A[I])), ch) } pw <- "my secret pass phrase" (crypw <- rot(pw, 13)) #-> you can send this off ## now ‘‘decrypt’’ : rot(crypw, 54 - 13)# -> the original: stopifnot(identical(pw, rot(crypw, 54 - 13))) chol The Choleski Decomposition Description Compute the Choleski factorization of a real symmetric positive-definite square matrix. chol 71 Usage chol(x, ...) ## Default S3 method: chol(x, pivot = FALSE, LINPACK = pivot, ...) Arguments x an object for which a method exists. The default method applies to real sym- metric, positive-definite matrices. ... arguments to be based to or from methods. pivot Should pivoting be used? LINPACK logical. Should LINPACK be used in the non-pivoting case (for compatibility with R < 1.7.0)? Details chol is generic: the description here applies to the default method. This is an interface to the LAPACK routine DPOTRF and the LINPACK routines DPOFA and DCHDC. Note that only the upper triangular part of x is used, so that R0R = x when x is symmetric. If pivot = FALSE and x is not non-negative definite an error occurs. If x is positive semi-definite (i.e., some zero eigenvalues) an error will also occur, as a numerical tolerance is used. If pivot = TRUE, then the Choleski decomposition of a positive semi-definite x can be computed. The rank of x is returned as attr(Q, "rank"), subject to numerical errors. The pivot is returned as attr(Q, "pivot"). It is no longer the case that t(Q) %*% Q equals x. However, setting pivot <- attr(Q, "pivot") and oo <- order(pivot), it is true that t(Q[, oo]) %*% Q[, oo] equals x, or, alternatively, t(Q) %*% Q equals x[pivot, pivot]. See the examples. Value The upper triangular factor of the Choleski decomposition, i.e., the matrix R such that R0R = x (see example). If pivoting is used, then two additional attributes "pivot" and "rank" are also returned. Warning The code does not check for symmetry. If pivot = TRUE and x is not non-negative definite then there will be a warning message but a meaningless result will occur. So only use pivot = TRUE when x is non-negative definite by construction. 72 chol2inv References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications. Anderson. E. and ten others (1999) LAPACK Users’ Guide. Third Edition. SIAM. Available on-line at http://www.netlib.org/lapack/lug/lapack_lug.html. See Also chol2inv for its inverse (without pivoting), backsolve for solving linear systems with upper trian- gular left sides. qr, svd for related matrix factorizations. Examples ( m <- matrix(c(5,1,1,3),2,2) ) ( cm <- chol(m) ) t(cm) %*% cm #-- = ’m’ crossprod(cm) #-- = ’m’ # now for something positive semi-definite x <- matrix(c(1:5, (1:5)^2), 5, 2) x <- cbind(x, x[, 1] + 3*x[, 2]) m <- crossprod(x) qr(m)$rank # is 2, as it should be # chol() may fail, depending on numerical rounding: # chol() unlike qr() does not use a tolerance. try(chol(m)) (Q <- chol(m, pivot = TRUE)) # NB wrong rank here - see Warning section. ## we can use this by pivot <- attr(Q, "pivot") crossprod(Q[, order(pivot)]) # recover m ## now for a non-positive-definite matrix ( m <- matrix(c(5,-5,-5,3),2,2) ) try(chol(m)) # fails try(chol(m, LINPACK=TRUE)) # fails (Q <- chol(m, pivot = TRUE)) # warning crossprod(Q) # not equal to m chol2inv Inverse from Choleski (or QR) Decomposition chol2inv 73 Description Invert a symmetric, positive definite square matrix from its Choleski decomposition. Equivalently, compute (X0X)−1 from the (R part) of the QR decomposition of X. Usage chol2inv(x, size = NCOL(x), LINPACK = FALSE) Arguments x a matrix. The first size columns of the upper triangle contain the Choleski decomposition of the matrix to be inverted. size the number of columns of x containing the Choleski decomposition. LINPACK logical. Should LINPACK be used (for compatibility with R < 1.7.0)? Details This is an interface to the LAPACK routine DPOTRI and the LINPACK routine DPODI. Value The inverse of the matrix whose Choleski decomposition was given. References Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications. Anderson. E. and ten others (1999) LAPACK Users’ Guide. Third Edition. SIAM. Available on-line at http://www.netlib.org/lapack/lug/lapack_lug.html. See Also chol, solve. Examples cma <- chol(ma <- cbind(1, 1:3, c(1,3,7))) ma %*% chol2inv(cma) 74 class class Object Classes Description R possesses a simple generic function mechanism which can be used for an object-oriented style of programming. Method dispatch takes place based on the class of the first argument to the generic function. Usage class(x) class(x) <- value unclass(x) inherits(x, what, which = FALSE) oldClass(x) oldClass(x) <- value Arguments x a R object what, value a character vector naming classes. value can also be NULL. which logical affecting return value: see ‘Details’. Details Many R objects have a class attribute, a character vector giving the names of the classes from which the object inherits. If the object does not have a class attribute, it has an implicit class, "matrix","array" or the result of mode(x) (except that integer vectors have implicit class "integer"). (Functions oldClass and oldClass<- get and set the attribute, which can also be done directly.) When a generic function fun is applied to an object with class attribute c("first", "second"), the system searches for a function called fun.first and, if it finds it, applies it to the object. If no such function is found, a function called fun.second is tried. If no class name produces a suitable function, the function fun.default is used (if it exists). If there is no class attribute, the implicit class is tried, then the default method. The function class prints the vector of names of classes an object inherits from. Correspondingly, class<- sets the classes an object inherits from. Assigning a zero-length vector or NULL removes the class attribute. unclass returns (a copy of) its argument with its class attribute removed. (It is not allowed for objects which cannot be copied, namely environments and external pointers.) inherits indicates whether its first argument inherits from any of the classes specified in the what argument. If which is TRUE then an integer vector of the same length as what is returned. Each element indicates the position in the class(x) matched by the element of what; zero indicates no col 75 match. If which is FALSE then TRUE is returned by inherits if any of the names in what match with any class. All but inherits are primitive functions. Formal classes An additional mechanism of formal classes is available in packages methods which is attached by default. For objects which have a formal class, its name is returned by class as a character vector of length one. However, S3 method selection attempts to treat objects from an S4 class as if they had the appropriate S3 class attribute, as does inherits. Therefore, S3 methods can be defined for S4 classes. See Methods for details. The replacement version of the function sets the class to the value provided. For classes that have a formal definition, directly replacing the class this way is strongly deprecated. The expression as(object, value) is the way to coerce an object to a particular class. The analogue of inherits for formal classes is is. The two functions behave consistently objects with one exception: S4 classes can have conditional inheritance, with an explicit test. In this case, is will test the condition, but inherits ignores all conditional superclasses. Note Functions oldClass and oldClass<- behave in the same way as functions of those names in S- PLUS 5/6, but in R UseMethod dispatches on the class as returned by class (with some interpolated classes: see the link) rather than oldClass. However, group generics dispatch on the oldClass for efficiency, and internal generics only dispatch on objects for which is.object is true. See Also UseMethod, NextMethod,‘group generic’, ‘internal generic’ Examples x <- 10 class(x) # "numeric" oldClass(x) # NULL inherits(x, "a") #FALSE class(x) <- c("a", "b") inherits(x,"a") #TRUE inherits(x, "a", TRUE) # 1 inherits(x, c("a", "b", "c"), TRUE) # 1 2 0 col Column Indexes Description Returns a matrix of integers indicating their column number in a matrix-like object, or a factor of column labels. 76 Colon Usage col(x, as.factor = FALSE) Arguments x a matrix-like object, that is one with a two-dimensional dim. as.factor a logical value indicating whether the value should be returned as a factor of column labels (created if necessary) rather than as numbers. Value An integer (or factor) matrix with the same dimensions as x and whose ij-th element is equal to j (or the j-th column label). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also row to get rows. Examples # extract an off-diagonal of a matrix ma <- matrix(1:12, 3, 4) ma[row(ma) == col(ma) + 1] # create an identity 5-by-5 matrix x <- matrix(0, nrow = 5, ncol = 5) x[row(x) == col(x)] <- 1 Colon Colon Operator Description Generate regular sequences. Usage from:to a:b Colon 77 Arguments from starting value of sequence. to (maximal) end value of the sequence. a, b factors of the same length. Details The binary operator : has two meanings: for factors a:b is equivalent to interaction(a, b) (but the levels are ordered and labelled differently). For other arguments from:to is equivalent to seq(from, to), and generates a sequence from from to to in steps of 1 or -1. Value to will be included if it differs from from by an integer up to a numeric fuzz of about 1e-7. Non-numeric arguments are coerced internally (hence without dispatching methods) to numeric—complex values will have their imaginary parts discarded with a warning. Value For numeric arguments, a numeric vector. This will be of type integer if from is integer-valued and the result is representable in the R integer type, otherwise of type "double" (aka mode"numeric"). For factors, an unordered factor with levels labelled as la:lb and ordered lexicographically (that is, lb varies fastest). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (for numeric arguments: S does not have : for factors.) See Also seq (a generalization of from:to). As an alternative to using : for factors, interaction. For : used in the formal representation of an interaction, see formula. Examples 1:4 pi:6 # real 6:pi # integer f1 <- gl(2,3); f1 f2 <- gl(3,2); f2 f1:f2 # a factor, the "cross" f1 x f2 78 colSums colSums Form Row and Column Sums and Means Description Form row and column sums and means for numeric arrays. Usage colSums (x, na.rm = FALSE, dims = 1) rowSums (x, na.rm = FALSE, dims = 1) colMeans(x, na.rm = FALSE, dims = 1) rowMeans(x, na.rm = FALSE, dims = 1) Arguments x an array of two or more dimensions, containing numeric, complex, integer or logical values, or a numeric data frame. na.rm logical. Should missing values (including NaN) be omitted from the calculations? dims integer: Which dimensions are regarded as ‘rows’ or ‘columns’ to sum over. For row*, the sum or mean is over dimensions dims+1, ...; for col* it is over dimensions 1:dims. Details These functions are equivalent to use of apply with FUN = mean or FUN = sum with appropriate margins, but are a lot faster. As they are written for speed, they blur over some of the subtleties of NaN and NA. If na.rm = FALSE and either NaN or NA appears in a sum, the result will be one of NaN or NA, but which might be platform-dependent. Notice that omission of missing values is done on a per-column or per-row basis, so column means may not be over the same set of rows, and vice versa. To use only complete rows or columns, first select them with na.omit or complete.cases (possibly on the transpose of x). Value A numeric or complex array of suitable size, or a vector if the result is one-dimensional. The dimnames (or names for a vector result) are taken from the original array. If there are no values in a range to be summed over (after removing missing values with na.rm = TRUE), that component of the output is set to 0 (*Sums) or NaN (*Means), consistent with sum and mean. See Also apply, rowsum commandArgs 79 Examples ## Compute row and column sums for a matrix: x <- cbind(x1 = 3, x2 = c(4:1, 2:5)) rowSums(x); colSums(x) dimnames(x)[[1]] <- letters[1:8] rowSums(x); colSums(x); rowMeans(x); colMeans(x) x[] <- as.integer(x) rowSums(x); colSums(x) x[] <- x < 3 rowSums(x); colSums(x) x <- cbind(x1 = 3, x2 = c(4:1, 2:5)) x[3, ] <- NA; x[4, 2] <- NA rowSums(x); colSums(x); rowMeans(x); colMeans(x) rowSums(x, na.rm = TRUE); colSums(x, na.rm = TRUE) rowMeans(x, na.rm = TRUE); colMeans(x, na.rm = TRUE) ## an array dim(UCBAdmissions) rowSums(UCBAdmissions); rowSums(UCBAdmissions, dims = 2) colSums(UCBAdmissions); colSums(UCBAdmissions, dims = 2) ## complex case x <- cbind(x1 = 3 + 2i, x2 = c(4:1, 2:5) - 5i) x[3, ] <- NA; x[4, 2] <- NA rowSums(x); colSums(x); rowMeans(x); colMeans(x) rowSums(x, na.rm = TRUE); colSums(x, na.rm = TRUE) rowMeans(x, na.rm = TRUE); colMeans(x, na.rm = TRUE) commandArgs Extract Command Line Arguments Description Provides access to a copy of the command line arguments supplied when this R session was invoked. Usage commandArgs(trailingOnly = FALSE) Arguments trailingOnly logical. Should only arguments after ‘--args’ be returned? Details These arguments are captured before the standard R command line processing takes place. This means that they are the unmodified values. This is especially useful with the ‘--args’ command- line flag to R, as all of the command line after that flag is skipped. 80 comment Value A character vector containing the name of the executable and the user-supplied command line argu- ments. The first element is the name of the executable by which R was invoked. The exact form of this element is platform dependent: it may be the fully qualified name, or simply the last component (or basename) of the application, or for an embedded R it can be anything the programmer supplied. If trailingOnly = TRUE, a character vector of those arguments (if any) supplied after ‘--args’. See Also Startup BATCH Examples commandArgs() ## Spawn a copy of this application as it was invoked, ## subject to shell quoting issues ## system(paste(commandArgs(), collapse=" ")) comment Query or Set a "comment" Attribute Description These functions set and query a comment attribute for any R objects. This is typically useful for data.frames or model fits. Contrary to other attributes, the comment is not printed (by print or print.default). Assigning NULL or a zero-length character vector removes the comment. Usage comment(x) comment(x) <- value Arguments x any R object value a character vector, or NULL. See Also attributes and attr for other attributes. Comparison 81 Examples x <- matrix(1:12, 3,4) comment(x) <- c("This is my very important data from experiment #0234", "Jun 5, 1998") x comment(x) Comparison Relational Operators Description Binary operators which allow the comparison of values in atomic vectors. Usage x < y x > y x <= y x >= y x == y x != y Arguments x, y atomic vectors, symbols, calls, or other objects for which methods have been written. Details The binary comparison operators are generic functions: methods can be written for them individu- ally or via the Ops) group generic function. (See Ops for how dispatch is computed.) Comparison of strings in character vectors is lexicographic within the strings using the collating sequence of the locale in use: see locales. The collating sequence of locales such as ‘en_US’ is normally different from ‘C’ (which should use ASCII) and can be surprising. Beware of making any assumptions about the collation order: e.g. in Estonian Z comes between S and T, and collation is not necessarily character-by-character – in Danish aa sorts as a single letter, after z. In Welsh ng may or may not be a single sorting unit: if it is it follows g. Some platforms may not respect the locale and always sort in numerical order of the bytes in an 8-bit locale, or in Unicode point order for a UTF-8 locale (and may not sort in the same order for the same language in different character sets). Collation of non-letters (spaces, punctuation signs, hyphens, fractions and so on) is even more problematic. Character strings can be compared with different marked encodings (see Encoding): they are trans- lated to UTF-8 before comparison. At least one of x and y must be an atomic vector, but if the other is a list R attempts to coerce it to the type of the atomic vector: this will succeed if the list is made up of elements of length one that can be coerced to the correct type. 82 Comparison If the two arguments are atomic vectors of different types, one is coerced to the type of the other, the (decreasing) order of precedence being character, complex, numeric, integer, logical and raw. Missing values (NA) and NaN values are regarded as non-comparable even to themselves, so compar- isons involving them will always result in NA. Missing values can also result when character strings are compared and one is not valid in the current collation locale. Language objects such as symbols and calls are deparsed to character strings before comparison. Value A logical vector indicating the result of the element by element comparison. The elements of shorter vectors are recycled as necessary. Objects such as arrays or time-series can be compared this way provided they are conformable. S4 methods These operators are members of the S4 Compare group generic, and so methods can be written for them individually as well as for the group generic (or the Ops group generic), with arguments c(e1, e2). Note Do not use == and != for tests, such as in if expressions, where you must get a single TRUE or FALSE. Unless you are absolutely sure that nothing unusual can happen, you should use the identical function instead. For numerical and complex values, remember == and != do not allow for the finite representation of fractions, nor for rounding error. Using all.equal with identical is almost always preferable. See the examples. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Collation of character strings is a complex topic. For an introduction see http://en.wikipedia. org/wiki/Collating_sequence. The Unicode Collation Algorithm (http://unicode.org/ reports/tr10/) is likely to be increasingly influential. Where available R makes use of ICU (http://site.icu-project.org/ for collation. See Also factor for the behaviour with factor arguments. Syntax for operator precedence. icuSetCollate to tune the string collation algorithm when ICU is in use. complex 83 Examples x <- stats::rnorm(20) x < 1 x[x > 0] x1 <- 0.5 - 0.3 x2 <- 0.3 - 0.1 x1 == x2 # FALSE on most machines identical(all.equal(x1, x2), TRUE) # TRUE everywhere # range of most 8-bit charsets, as well as of Latin-1 in Unicode z <- c(32:126, 160:255) x <- if(l10n_info()$MBCS) { intToUtf8(z, multiple = TRUE) } else rawToChar(as.raw(z), multiple= TRUE) ## by number writeLines(strwrap(paste(x, collapse=" "), width = 60)) ## by locale collation writeLines(strwrap(paste(sort(x), collapse=" "), width = 60)) complex Complex Vectors Description Basic functions which support complex arithmetic in R. Usage complex(length.out = 0, real = numeric(), imaginary = numeric(), modulus = 1, argument = 0) as.complex(x, ...) is.complex(x) Re(z) Im(z) Mod(z) Arg(z) Conj(z) Arguments length.out numeric. Desired length of the output vector, inputs being recycled as needed. real numeric vector. imaginary numeric vector. modulus numeric vector. 84 complex argument numeric vector. x an object, probably of mode complex. z an object of mode complex, or one of a class for which a methods has been defined. ... further arguments passed to or from other methods. Details Complex vectors can be created with complex. The vector can be specified either by giving its length, its real and imaginary parts, or modulus and argument. (Giving just the length generates a vector of complex zeroes.) as.complex attempts to coerce its argument to be of complex type: like as.vector it strips at- tributes including names. All forms of NA and NaN are coerced to a complex NA, for which both the real and imaginary parts are NA. Note that is.complex and is.numeric are never both TRUE. The functions Re, Im, Mod, Arg and Conj have their usual interpretation as returning the real part, imaginary part, modulus, argument and complex conjugate for complex values. The modulus and argument are also called the polar coordinates. If z = x + iy with real x and y, for r = Mod(z) = px2 + y2, and φ = Arg(z), x = r ∗ cos(φ) and y = r ∗ sin(φ). They are all internal generic primitive functions: methods can be defined for them individually or via the Complex group generic. In addition, the elementary trigonometric, logarithmic, exponential, square root and hyperbolic functions are implemented for complex values. Internally, complex numbers are stored as a pair of double precision numbers, either or both of which can be NaN or plus or minus infinity. S4 methods as.complex is primitive and can have S4 methods set. Re, Im, Mod, Arg and Conj constitute the S4 group generic Complex and so S4 methods can be set for them individually or via the group generic. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Examples require(graphics) 0i ^ (-3:3) matrix(1i^ (-6:5), nrow=4) #- all columns are the same 0 ^ 1i # a complex NaN ## create a complex normal vector z <- complex(real = stats::rnorm(100), imaginary = stats::rnorm(100)) conditions 85 ## or also (less efficiently): z2 <- 1:2 + 1i*(8:9) ## The Arg(.) is an angle: zz <- (rep(1:4,len=9) + 1i*(9:1))/10 zz.shift <- complex(modulus = Mod(zz), argument= Arg(zz) + pi) plot(zz, xlim=c(-1,1), ylim=c(-1,1), col="red", asp = 1, main = expression(paste("Rotation by "," ", pi == 180^o))) abline(h=0,v=0, col="blue", lty=3) points(zz.shift, col="orange") conditions Condition Handling and Recovery Description These functions provide a mechanism for handling unusual conditions, including errors and warn- ings. Usage tryCatch(expr, ..., finally) withCallingHandlers(expr, ...) signalCondition(cond) simpleCondition(message, call = NULL) simpleError (message, call = NULL) simpleWarning (message, call = NULL) simpleMessage (message, call = NULL) ## S3 method for class ’condition’ as.character(x, ...) ## S3 method for class ’error’ as.character(x, ...) ## S3 method for class ’condition’ print(x, ...) ## S3 method for class ’restart’ print(x, ...) conditionCall(c) ## S3 method for class ’condition’ conditionCall(c) conditionMessage(c) ## S3 method for class ’condition’ conditionMessage(c) withRestarts(expr, ...) 86 conditions computeRestarts(cond = NULL) findRestart(name, cond = NULL) invokeRestart(r, ...) invokeRestartInteractively(r) isRestart(x) restartDescription(r) restartFormals(r) .signalSimpleWarning(msg, call) .handleSimpleError(h, msg, call) Arguments c a condition object. call call expression. cond a condition object. expr expression to be evaluated. finally expression to be evaluated before returning or exiting. h function. message character string. msg character string. name character string naming a restart. r restart object. x object. ... additional arguments; see details below. Details The condition system provides a mechanism for signaling and handling unusual conditions, includ- ing errors and warnings. Conditions are represented as objects that contain information about the condition that occurred, such as a message and the call in which the condition occurred. Currently conditions are S3-style objects, though this may eventually change. Conditions are objects inheriting from the abstract class condition. Errors and warnings are ob- jects inheriting from the abstract subclasses error and warning. The class simpleError is the class used by stop and all internal error signals. Similarly, simpleWarning is used by warning, and simpleMessage is used by message. The constructors by the same names take a string de- scribing the condition as argument and an optional call. The functions conditionMessage and conditionCall are generic functions that return the message and call of a condition. Conditions are signaled by signalCondition. In addition, the stop and warning functions have been modified to also accept condition arguments. The function tryCatch evaluates its expression argument in a context where the handlers provided in the ... argument are available. The finally expression is then evaluated in the context in which conditions 87 tryCatch was called; that is, the handlers supplied to the current tryCatch call are not active when the finally expression is evaluated. Handlers provided in the ... argument to tryCatch are established for the duration of the evalua- tion of expr. If no condition is signaled when evaluating expr then tryCatch returns the value of the expression. If a condition is signaled while evaluating expr then established handlers are checked, starting with the most recently established ones, for one matching the class of the condition. When several handlers are supplied in a single tryCatch then the first one is considered more recent than the second. If a handler is found then control is transferred to the tryCatch call that established the handler, the handler found and all more recent handlers are disestablished, the handler is called with the condition as its argument, and the result returned by the handler is returned as the value of the tryCatch call. Calling handlers are established by withCallingHandlers. If a condition is signaled and the ap- plicable handler is a calling handler, then the handler is called by signalCondition in the context where the condition was signaled but with the available handlers restricted to those below the han- dler called in the handler stack. If the handler returns, then the next handler is tried; once the last handler has been tried, signalCondition returns NULL. User interrupts signal a condition of class interrupt that inherits directly from class condition before executing the default interrupt action. Restarts are used for establishing recovery protocols. They can be established using withRestarts. One pre-established restart is an abort restart that represents a jump to top level. findRestart and computeRestarts find the available restarts. findRestart returns the most re- cently established restart of the specified name. computeRestarts returns a list of all restarts. Both can be given a condition argument and will then ignore restarts that do not apply to the condition. invokeRestart transfers control to the point where the specified restart was established and calls the restart’s handler with the arguments, if any, given as additional arguments to invokeRestart. The restart argument to invokeRestart can be a character string, in which case findRestart is used to find the restart. New restarts for withRestarts can be specified in several ways. The simplest is in name=function form where the function is the handler to call when the restart is invoked. Another simple variant is as name=string where the string is stored in the description field of the restart object returned by findRestart; in this case the handler ignores its arguments and returns NULL. The most flex- ible form of a restart specification is as a list that can include several fields, including handler, description, and test. The test field should contain a function of one argument, a condition, that returns TRUE if the restart applies to the condition and FALSE if it does not; the default function returns TRUE for all conditions. One additional field that can be specified for a restart is interactive. This should be a function of no arguments that returns a list of arguments to pass to the restart handler. The list could be obtained by interacting with the user if necessary. The function invokeRestartInteractively calls this function to obtain the arguments to use when invoking the restart. The default interactive method queries the user for values for the formal arguments of the handler function. .signalSimpleWarning and .handleSimpleError are used internally and should not be called directly. 88 conflicts References The tryCatch mechanism is similar to Java error handling. Calling handlers are based on Common Lisp and Dylan. Restarts are based on the Common Lisp restart mechanism. See Also stop and warning signal conditions, and try is essentially a simplified version of tryCatch. Examples tryCatch(1, finally=print("Hello")) e <- simpleError("test error") ## Not run: stop(e) tryCatch(stop(e), finally=print("Hello")) tryCatch(stop("fred"), finally=print("Hello")) ## End(Not run) tryCatch(stop(e), error = function(e) e, finally=print("Hello")) tryCatch(stop("fred"), error = function(e) e, finally=print("Hello")) withCallingHandlers({ warning("A"); 1+2 }, warning = function(w) {}) ## Not run: { withRestarts(stop("A"), abort = function() {}); 1 } ## End(Not run) withRestarts(invokeRestart("foo", 1, 2), foo = function(x, y) {x + y}) ##--> More examples are part of ##--> demo(error.catching) conflicts Search for Masked Objects on the Search Path Description conflicts reports on objects that exist with the same name in two or more places on the search path, usually because an object in the user’s workspace or a package is masking a system object of the same name. This helps discover unintentional masking. Usage conflicts(where = search(), detail = FALSE) Arguments where A subset of the search path, by default the whole search path. detail If TRUE, give the masked or masking functions for all members of the search path. connections 89 Value If detail=FALSE, a character vector of masked objects. If detail=TRUE, a list of character vectors giving the masked or masking objects in that member of the search path. Empty vectors are omitted. Examples lm <- 1:3 conflicts(, TRUE) ## gives something like # $.GlobalEnv # [1] "lm" # # $package:base # [1] "lm" ## Remove things from your "workspace" that mask others: remove(list = conflicts(detail=TRUE)$.GlobalEnv) connections Functions to Manipulate Connections Description Functions to create, open and close connections. Usage file(description = "", open = "", blocking = TRUE, encoding = getOption("encoding"), raw = FALSE) url(description, open = "", blocking = TRUE, encoding = getOption("encoding")) gzfile(description, open = "", encoding = getOption("encoding"), compression = 6) bzfile(description, open = "", encoding = getOption("encoding"), compression = 9) xzfile(description, open = "", encoding = getOption("encoding"), compression = 6) unz(description, filename, open = "", encoding = getOption("encoding")) pipe(description, open = "", encoding = getOption("encoding")) fifo(description, open = "", blocking = FALSE, 90 connections encoding = getOption("encoding")) socketConnection(host = "localhost", port, server = FALSE, blocking = FALSE, open = "a+", encoding = getOption("encoding"), timeout = getOption("timeout")) open(con, ...) ## S3 method for class ’connection’ open(con, open = "r", blocking = TRUE, ...) close(con, ...) ## S3 method for class ’connection’ close(con, type = "rw", ...) flush(con) isOpen(con, rw = "") isIncomplete(con) Arguments description character string. A description of the connection: see ‘Details’. open character. A description of how to open the connection (if it should be opened initially). See section ‘Modes’ for possible values. blocking logical. See the ‘Blocking’ section. encoding The name of the encoding to be used. See the ‘Encoding’ section. raw logical. If true, a ‘raw’ interface is used which will be more suitable for argu- ments which are not regular files, e.g. character devices. This suppresses the check for a compressed file when opening for text-mode reading, and asserts that the ‘file’ may not be seekable. compression integer in 0–9. The amount of compression to be applied when writing, from none to maximal available. For xzfile can also be negative: see the ‘Compres- sion’ section. timeout numeric: the timeout (in seconds) to be used for this connection. Beware that some OSes may treat very large values as zero: however the POSIX standard requires values up to 31 days to be supported. filename a filename within a zip file. host character. Host name for port. port integer. The TCP port number. server logical. Should the socket be a client or a server? con a connection. type character. Currently ignored. rw character. Empty or "read" or "write", partial matches allowed. ... arguments passed to or from other methods. connections 91 Details The first nine functions create connections. By default the connection is not opened (except for socketConnection), but may be opened by setting a non-empty value of argument open. For file the description is a path to the file to be opened or a complete URL (when it is the same as calling url), or "" (the default) or "clipboard" (see the ‘Clipboard’ section). Use "stdin" to refer to the C-level ‘standard input’ of the process (which need not be connected to anything in a console or embedded version of R). See also stdin() for the subtly different R-level concept of stdin. For url the description is a complete URL, including scheme (such as ‘http://’, ‘ftp://’ or ‘file://’). Proxies can be specified for HTTP and FTP url connections: see download.file. For gzfile the description is the path to a file compressed by gzip: it can also open for reading uncompressed files and (as from R 2.10.0) those compressed by bzip2, xz or lzma. For bzfile the description is the path to a file compressed by bzip2. For xzfile the description is the path to a file compressed by xz (http://en.wikipedia.org/ wiki/Xz) or (for reading only) lzma (http://en.wikipedia.org/wiki/LZMA). unz reads (only) single files within zip files, in binary mode. The description is the full path to the zip file, with ‘.zip’ extension if required. For pipe the description is the command line to be piped to or from. This is run in a shell, on Windows that specified by the COMSPEC environment variable. For fifo the description is the path of the fifo. (Windows does not have fifos, so attempts to use this function there are an error. It was possible to use file with fifos prior to R 2.10.0, but raw=TRUE is now required for reading, and fifo was always the documented interface.) All platforms support file, pipe, gzfile, bzfile, xzfile, unz and url("file://") connections. The other connections may be partially implemented or not implemented at all. (They do work on most Unix platforms, and all but fifo on Windows.) The intention is that file and gzfile can be used generally for text input (from files and URLs) and binary input respectively. open, close and seek are generic functions: the following applies to the methods relevant to con- nections. open opens a connection. In general functions using connections will open them if they are not open, but then close them again, so to leave a connection open call open explicitly. close closes and destroys a connection. This will happen automatically in due course (with a warning) if there is no longer an R object referring to the connection. A maximum of 128 connections can be allocated (not necessarily open) at any one time. Three of these are pre-allocated (see stdout). The OS will impose limits on the numbers of connections of various types, but these are usually larger than 125. flush flushes the output stream of a connection open for write/append (where implemented, cur- rently for file and clipboard connections, stdout and stderr). If for a file or fifo connection the description is "", the file/fifo is immediately opened (in "w+" mode unless open = "w+b" is specified) and unlinked from the file system. This provides a tempo- rary file/fifo to write to and then read from. 92 connections Value file, pipe, fifo, url, gzfile, bzfile, xzfile, unz and socketConnection return a connection object which inherits from class "connection" and has a first more specific class. isOpen returns a logical value, whether the connection is currently open. isIncomplete returns a logical value, whether the last read attempt was blocked, or for an output text connection whether there is unflushed output. URLs url and file support URL schemes ‘http://’, ‘ftp://’ and ‘file://’. A note on ‘file://’ URLs. The most general form (from RFC1738) is ‘file://host/path/to/file’, but R only accepts the form with an empty host field refer- ring to the local machine. This is then ‘file:///path/to/file’, where ‘path/to/file’ is relative to ‘/’. So although the third slash is strictly part of the specification not part of the path, this can be regarded as a way to specify the file ‘/path/to/file’. It is not possible to specify a relative path using a file URL. No attempt is made to decode an encoded URL: call URLdecode if necessary. Note that ‘https://’ connections are not supported (with some exceptions on Windows). Contributed package RCurl provides more comprehensive facilities to download from URLs. Modes Possible values for the argument open are "r" or "rt" Open for reading in text mode. "w" or "wt" Open for writing in text mode. "a" or "at" Open for appending in text mode. "rb" Open for reading in binary mode. "wb" Open for writing in binary mode. "ab" Open for appending in binary mode. "r+","r+b" Open for reading and writing. "w+","w+b" Open for reading and writing, truncating file initially. "a+","a+b" Open for reading and appending. Not all modes are applicable to all connections: for example URLs can only be opened for reading. Only file and socket connections can be opened for both reading and writing. An unsupported mode is usually silently substituted. If a file or fifo is created on a Unix-alike, its permissions will be the maximal allowed by the current setting of umask (see Sys.umask). For many connections there is little or no difference between text and binary modes. For file-like connections on Windows, translation of line endings (between LF and CRLF) is done in text mode only (but text read operations on connections such as readLines, scan and source work for any form of line ending). Various R operations are possible in only one of the modes: for example pushBack is text-oriented and is only allowed on connections open for reading in text mode, and connections 93 binary operations such as readBin, load and save operations can only be done on binary-mode connections. The mode of a connection is determined when actually opened, which is deferred if open = "" is given (the default for all but socket connections). An explicit call to open can specify the mode, but otherwise the mode will be "r".(gzfile, bzfile and xzfile connections are exceptions, as the compressed file always has to be opened in binary mode and no conversion of line-endings is done even on Windows, so the default mode is interpreted as "rb".) Most operations that need write access or text-only or binary-only mode will override the default mode of a non-yet-open connection. Append modes need to be considered carefully for compressed-file connections. They do not pro- duce a single compressed stream on the file, but rather append a new compressed stream to the file. Readers (including R) may or may not read beyond end of the first stream: currently R does so for gzfile, bzfile and xzfile connections, but earlier versions did not. Compression R has for a long time supported gzip and bzip2 compression, and support for xz compression (and read-only support for its precursor lzma compression) was added in R 2.10.0. For reading, the type of compression (if any) can be determined from the first few bytes of the file, and this is exploited as from R 2.10.0. Thus for file(raw = FALSE) connections, if open is "", "r" or "rt" the connection can read any of the compressed file types as well as uncompressed files. (Using "rb" will allow compressed files to be read byte-by-byte.) Similarly, gzfile connections can read any of the forms of compression and uncompressed files in any read mode. (The type of compression is determined when the connection is created if open is unspecified and a file of that name exists. If the intention is to open the connection to write a file with a different form of compression under that name, specify open = "w" when the connection is created or unlink the file before creating the connection.) For write-mode connections, compress specifies now hard the compressor works to minimize the file size, and higher values need more CPU time and more working memory (up to ca 800Mb for xzfile(compress = 9)). For xzfile negative values of compress correspond to adding the xz argument ‘-e’: this takes more time (double?) to compress but may achieve (slightly) better compression. The default (6) has good compression and modest (100Mb memory usage): but if you are using xz compression you are probably looking for high compression. Choosing the type of compression involves tradeoffs: gzip, bzip2 and xz are successively less widely supported, need more resources for both compression and decompression, and achieve more compression (although individual files may buck the general trend). Typical experience is that bzip2 compression is 15% better on text files than gzip compression, and xz with maximal com- pression 30% better. The experience with R save files is similar, but on some large ‘.rda’ files xz compression is much better than the other two. With current computers decompression times even with compress = 9 are typically modest and reading compressed files is usually faster than uncompressed ones because of the reduction in disc activity. Encoding The encoding of the input/output stream of a connection can be specified by name in the same way as it would be given to iconv: see that help page for how to find out what encoding names are 94 connections recognized on your platform. Additionally, "" and "native.enc" both mean the ‘native’ encoding, that is the internal encoding of the current locale and hence no translation is done. Re-encoding only works for connections in text mode: reading from a connection with re-encoding specified in binary mode will read the stream of bytes, but mixing text and binary mode reads (e.g. mixing calls to readLines and readChar) is likely to lead to incorrect results. The encodings "UCS-2LE" and "UTF-16LE" are treated specially, as they are appropriate values for Windows ‘Unicode’ text files. If the first two bytes are the Byte Order Mark 0xFFFE then these are removed as some implementations of iconv do not accept BOMs. Note that whereas most implementations will handle BOMs using encoding "UCS-2" and choose the appropriate byte order, some (including earlier versions of glibc) will not. There is a subtle distinction between "UTF-16" and "UCS-2" (see http://en.wikipedia.org/wiki/UTF-16/UCS-2: the use of surrogate pairs is very rare so "UCS-2LE" is an appropriate first choice. Requesting a conversion that is not supported is an error, reported when the connection is opened. Exactly what happens when the requested translation cannot be done for invalid input is in general undocumented. On output the result is likely to be that up to the error, with a warning. On input, it will most likely be all or some of the input up to the error. Blocking Whether or not the connection blocks can be specified for file, url (default yes) fifo and socket connections (default not). In blocking mode, functions using the connection do not return to the R evaluator until the read/write is complete. In non-blocking mode, operations return as soon as possible, so on in- put they will return with whatever input is available (possibly none) and for output they will return whether or not the write succeeded. The function readLines behaves differently in respect of incomplete last lines in the two modes: see its help page. Even when a connection is in blocking mode, attempts are made to ensure that it does not block the event loop and hence the operation of GUI parts of R. These do not always succeed, and the whole R process will be blocked during a DNS lookup on Unix, for example. Most blocking operations on HTTP/FTP URLs and on sockets are subject to the timeout set by options("timeout"). Note that this is a timeout for no response, not for the whole operation. The timeout is set at the time the connection is opened (more precisely, when the last connection of that type – ‘http:’, ‘ftp:’ or socket – was opened). Fifos Fifos default to non-blocking. That follows S version 4 and is probably most natural, but it does have some implications. In particular, opening a non-blocking fifo connection for writing (only) will fail unless some other process is reading on the fifo. Opening a fifo for both reading and writing (in any mode: one can only append to fifos) connects both sides of the fifo to the R process, and provides an similar facility to file(). Clipboard file can be used with description = "clipboard" in mode "r" only. This reads the X11 primary selection (see http://standards.freedesktop.org/clipboards-spec/clipboards-latest. connections 95 txt), which can also be specified as "X11_primary" and the secondary selection as "X11_secondary". On most systems the clipboard selection (that used by ‘Copy’ from an ‘Edit’ menu) can be specified as "X11_clipboard". When a clipboard is opened for reading, the contents are immediately copied to internal storage in the connection. Unix users wishing to write to one of the selections may be able to do so via xclip (http:// sourceforge.net/projects/xclip/), for example by pipe("xclip -i", "w") for the primary selection. Mac OS X users can use pipe("pbpaste") and pipe("pbcopy", "w") to read from and write to that system’s clipboard. Note R’s connections are modelled on those in S version 4 (see Chambers, 1998). However R goes well beyond the S model, for example in output text connections and URL, compressed and socket connections. The default open mode in R is "r" except for socket connections. This differs from S, where it is the equivalent of "r+", known as "*". On (rare) platforms where vsnprintf does not return the needed length of output there is a 100,000 byte output limit on the length of line for text output on fifo, gzfile, bzfile and xzfile connec- tions: longer lines will be truncated with a warning. References Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. Ripley, B. D. (2001) Connections. R News, 1/1, 16–7. http://www.r-project.org/doc/Rnews/ Rnews_2001-1.pdf See Also textConnection, seek, showConnections, pushBack. Functions making direct use of connections are (text-mode) readLines, writeLines, cat, sink, scan, parse, read.dcf, dput, dump and (binary-mode) readBin, readChar, writeBin, writeChar, load and save. capabilities to see if HTTP/FTP url, fifo and socketConnection are supported by this build of R. gzcon to wrap gzip (de)compression around a connection. memCompress for more ways to (de)compress and references on data compression. Examples zz <- file("ex.data", "w") # open an output file connection cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n") cat("One more line\n", file = zz) close(zz) readLines("ex.data") unlink("ex.data") 96 connections zz <- gzfile("ex.gz", "w") # compressed file cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n") close(zz) readLines(zz <- gzfile("ex.gz")) close(zz) unlink("ex.gz") zz <- bzfile("ex.bz2", "w") # bzip2-ed file cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n") close(zz) print(readLines(zz <- bzfile("ex.bz2"))) close(zz) unlink("ex.bz2") ## An example of a file open for reading and writing Tfile <- file("test1", "w+") c(isOpen(Tfile, "r"), isOpen(Tfile, "w")) # both TRUE cat("abc\ndef\n", file=Tfile) readLines(Tfile) seek(Tfile, 0, rw="r") # reset to beginning readLines(Tfile) cat("ghi\n", file=Tfile) readLines(Tfile) close(Tfile) unlink("test1") ## We can do the same thing with an anonymous file. Tfile <- file() cat("abc\ndef\n", file=Tfile) readLines(Tfile) close(Tfile) ## fifo example -- may fail even with OS support for fifos if(capabilities("fifo")) { zz <- fifo("foo-fifo", "w+") writeLines("abc", zz) print(readLines(zz)) close(zz) unlink("foo-fifo") } ## Unix examples of use of pipes # read listing of current directory readLines(pipe("ls -1")) # remove trailing commas. Suppose ## Not run: % cat data2 450, 390, 467, 654, 30, 542, 334, 432, 421, 357, 497, 493, 550, 549, 467, 575, 578, 342, 446, 547, 534, 495, 979, 479 Constants 97 ## End(Not run) # Then read this by scan(pipe("sed -e s/,$// data2_"), sep=",") # convert decimal point to comma in output: see also write.table # both R strings and (probably) the shell need \ doubled zz <- pipe(paste("sed s/\\\\./,/ >", "outfile"), "w") cat(format(round(stats::rnorm(48), 4)), fill=70, file = zz) close(zz) file.show("outfile", delete.file=TRUE) ## example for a machine running a finger daemon con <- socketConnection(port = 79, blocking = TRUE) writeLines(paste(system("whoami", intern=TRUE), "\r", sep=""), con) gsub(" *$", "", readLines(con)) close(con) ## Not run: ## Two R processes communicating via non-blocking sockets # R process 1 con1 <- socketConnection(port = 6011, server=TRUE) writeLines(LETTERS, con1) close(con1) # R process 2 con2 <- socketConnection(Sys.info()["nodename"], port = 6011) # as non-blocking, may need to loop for input readLines(con2) while(isIncomplete(con2)) {Sys.sleep(1); readLines(con2)} close(con2) ## examples of use of encodings # write a file in UTF-8 cat(x, file = (con <- file("foo", "w", encoding="UTF-8"))); close(con) # read a ’Windows Unicode’ file A <- read.table(con <- file("students", encoding="UCS-2LE")); close(con) ## End(Not run) Constants Built-in Constants Description Constants built into R. 98 Constants Usage LETTERS letters month.abb month.name pi Details R has a small number of built-in constants. The following constants are available: • LETTERS: the 26 upper-case letters of the Roman alphabet; • letters: the 26 lower-case letters of the Roman alphabet; • month.abb: the three-letter abbreviations for the English month names; • month.name: the English names for the months of the year; • pi: the ratio of the circumference of a circle to its diameter. These are implemented as variables in the base namespace taking appropriate values. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also data, DateTimeClasses. Quotes for the parsing of character constants, NumericConstants for numeric constants. Examples ## John Machin (ca 1706) computed pi to over 100 decimal places ## using the Taylor series expansion of the second term of pi - 4*(4*atan(1/5) - atan(1/239)) ## months in English month.name ## months in your current locale format(ISOdate(2000, 1:12, 1), "%B") format(ISOdate(2000, 1:12, 1), "%b") contributors 99 contributors R Project Contributors Description The R Who-is-who, describing who made significant contributions to the development of R. Usage contributors() Control Control Flow Description These are the basic control-flow constructs of the R language. They function in much the same way as control statements in any Algol-like language. They are all reserved words. Usage if(cond) expr if(cond) cons.expr else alt.expr for(var in seq) expr while(cond) expr repeat expr break next Arguments cond A length-one logical vector that is not NA. Conditions of length greater than one are accepted with a warning, but only the first element is used. Other types are coerced to logical if possible, ignoring any class. var A syntactical name for a variable. seq An expression evaluating to a vector (including a list and an expression) or to a pairlist or NULL. A factor value will be coerced to a character vector. expr, cons.expr, alt.expr An expression in a formal sense. This is either a simple expression or a so called compound expression, usually of the form { expr1 ; expr2 }. 100 Control Details break breaks out of a for, while or repeat loop; control is transferred to the first statement outside the inner-most loop. next halts the processing of the current iteration and advances the looping index. Both break and next apply only to the innermost of nested loops. Note that it is a common mistake to forget to put braces ({ .. }) around your statements, e.g., after if(..) or for(....). In particular, you should not have a newline between } and else to avoid a syntax error in entering a if ... else construct at the keyboard or via source. For that reason, one (somewhat extreme) attitude of defensive programming is to always use braces, e.g., for if clauses. The seq in a for loop is evaluated at the start of the loop; changing it subsequently does not affect the loop. If seq has length zero the body of the loop is skipped. Otherwise the variable var is assigned in turn the value of each element of seq. You can assign to var within the body of the loop, but this will not affect the next iteration. When the loop terminates, var remains as a variable containing its latest value. Value if returns the value of the expression evaluated, or NULL invisibly if none was (which may happen if there is no else). for, while and repeat return NULL invisibly. for sets var to the last used element of seq, or to NULL if it was of length zero. break and next do not return a value as they transfer control within the loop. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also Syntax for the basic R syntax and operators, Paren for parentheses and braces. ifelse, switch for other ways to control flow. Examples for(i in 1:5) print(1:i) for(n in c(2,5,10,20,50)) { x <- stats::rnorm(n) cat(n,":", sum(x^2),"\n") } f = factor(sample(letters[1:5], 10, replace=TRUE)) for( i in unique(f) ) print(i) converters 101 converters Management of .C argument conversion list Description These functions provide facilities to manage the extensible list of converters used to translate R objects to C pointers for use in .C calls. The number and a description of each element in the list can be retrieved. One can also query and set the activity status of individual elements, temporarily ignoring them. And one can remove individual elements. Usage getNumCConverters() getCConverterDescriptions() getCConverterStatus() setCConverterStatus(id, status) removeCConverter(id) Arguments id either a number or a string identifying the element of interest in the converter list. A string is matched against the description strings for each element to identify the element. Integers are specified starting at 1 (rather than 0). status a logical value specifying whether the element is to be considered active (TRUE) or not (FALSE). Details The internal list of converters is potentially used when converting individual arguments in a .C call. If an argument has a non-trivial class attribute, we iterate over the list of converters looking for the first that matches. If we find a matching converter, we have it create the C-level pointer corresponding to the R object. When the call to the C routine is complete, we use the same converter for that argument to reverse the conversion and create an R object from the current value in the C pointer. This is done separately for all the arguments. The functions documented here provide R user-level capabilities for investigating and managing the list of converters. There is currently no mechanism for adding an element to the converter list within the R language. This must be done in C code using the routine R_addToCConverter(). Value getNumCConverters returns an integer giving the number of elements in the list, both active and inactive. getCConverterDescriptions returns a character vector containing the description string of each element of the converter list. getCConverterStatus returns a logical vector with a value for each element in the converter list. Each value indicates whether that converter is active (TRUE) or inactive (FALSE). The names of the elements are the description strings returned by getCConverterDescriptions. 102 copyright setCConverterStatus returns the logical value indicating the activity status of the specified ele- ment before the call to change it took effect. This is TRUE for active and FALSE for inactive. removeCConverter returns TRUE if an element in the converter list was identified and removed. In the case that no such element was found, an error occurs. Author(s) Duncan Temple Lang References http://developer.R-project.org/CObjectConversion.pdf See Also .C Examples getNumCConverters() getCConverterDescriptions() getCConverterStatus() ## Not run: old <- setCConverterStatus(1, FALSE) setCConverterStatus(1, old) ## End(Not run) ## Not run: removeCConverter(1) removeCConverter(getCConverterDescriptions()[1]) ## End(Not run) copyright Copyrights of Files Used to Build R Description R is released under the ‘GNU Public License’: see license for details. The license describes your right to use R. Copyright is concerned with ownership of intellectual rights, and some of the software used has conditions that the copyright must be explicitly stated: see the ‘Details’ section. We are grateful to these people and other contributors (see contributors) for the ability to use their work. Details The file ‘R_HOME/COPYRIGHTS’ lists the copyrights in full detail. crossprod 103 crossprod Matrix Crossproduct Description Given matrices x and y as arguments, return a matrix cross-product. This is formally equivalent to (but usually slightly faster than) the call t(x) %*% y (crossprod) or x %*% t(y) (tcrossprod). Usage crossprod(x, y = NULL) tcrossprod(x, y = NULL) Arguments x, y numeric or complex matrices: y = NULL is taken to be the same matrix as x. Vectors are promoted to single-column or single-row matrices, depending on the context. Value A double or complex matrix, with appropriate dimnames taken from x and y. Note When x or y are not matrices, they are treated as column or row matrices, but their names are usually not promoted to dimnames. Hence, currently, the last example has empty dimnames. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also %*% and outer product %o%. Examples (z <- crossprod(1:4)) # = sum(1 + 2^2 + 3^2 + 4^2) drop(z) # scalar x <- 1:4; names(x) <- letters[1:4]; x tcrossprod(as.matrix(x)) # is identical(tcrossprod(as.matrix(x)), crossprod(t(x))) tcrossprod(x) # no dimnames m <- matrix(1:6, 2,3) ; v <- 1:3; v2 <- 2:1 104 Cstack_info stopifnot(identical(tcrossprod(v, m), v %*% t(m)), identical(tcrossprod(v, m), crossprod(v, t(m))), identical(crossprod(m, v2), t(m) %*% v2)) Cstack_info Report Information on C Stack Size and Usage Description Report information on the C stack size and usage (if available). Usage Cstack_info() Details On most platforms, C stack information is recorded when R is initialized and used for stack- checking. If this information is unavailable, the size will be returned as NA, and stack-checking is not performed. The information on the stack base address is thought to be accurate on Windows, Linux and FreeBSD (including Mac OS X), but a heuristic is used on other platforms. Because this might be slightly inaccurate, the current usage could be estimated as negative. (The heuristic is not used on embedded uses of R on platforms where the stack base is not thought to be accurate.) Value An integer vector. This has named elements size The size of the stack (in bytes), or NA if unknown. current The estimated current usage (in bytes), possibly NA. direction1 (stack grows down, the usual case) or -1 (stack grows up). eval_depth The current evaluation depth (including two calls for the call to Cstack_info). Examples Cstack_info() cumsum 105 cumsum Cumulative Sums, Products, and Extremes Description Returns a vector whose elements are the cumulative sums, products, minima or maxima of the elements of the argument. Usage cumsum(x) cumprod(x) cummax(x) cummin(x) Arguments x a numeric or complex (not cummin or cummax) object, or an object that can be coerced to one of these. Details These are generic functions: methods can be defined for them individually or via the Math group generic. Value A vector of the same length and type as x (after coercion), except that cumprod returns a numeric vector for integer input (for consistency with *). Names are preserved. An NA value in x causes the corresponding and following elements of the return value to be NA, as does integer overflow in cumsum (with a warning). S4 methods cumsum and cumprod are S4 generic functions: methods can be defined for them individually or via the Math group generic. cummax and cummin are individually S4 generic functions. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (cumsum only.) Examples cumsum(1:10) cumprod(1:10) cummin(c(3:1, 2:0, 4:2)) cummax(c(3:1, 2:0, 4:2)) 106 cut cut Convert Numeric to Factor Description cut divides the range of x into intervals and codes the values in x according to which interval they fall. The leftmost interval corresponds to level one, the next leftmost to level two and so on. Usage cut(x, ...) ## Default S3 method: cut(x, breaks, labels = NULL, include.lowest = FALSE, right = TRUE, dig.lab = 3, ordered_result = FALSE, ...) Arguments x a numeric vector which is to be converted to a factor by cutting. breaks either a numeric vector of two or more cut points or a single number (greater than or equal to 2) giving the number of intervals into which x is to be cut. labels labels for the levels of the resulting category. By default, labels are constructed using "(a,b]" interval notation. If labels = FALSE, simple integer codes are returned instead of a factor. include.lowest logical, indicating if an ‘x[i]’ equal to the lowest (or highest, for right = FALSE) ‘breaks’ value should be included. right logical, indicating if the intervals should be closed on the right (and open on the left) or vice versa. dig.lab integer which is used when labels are not given. It determines the number of digits used in formatting the break numbers. ordered_result logical: should the result be an ordered factor? ... further arguments passed to or from other methods. Details When breaks is specified as a single number, the range of the data is divided into breaks pieces of equal length, and then the outer limits are moved away by 0.1% of the range to ensure that the extreme values both fall within the break intervals. (If x is a constant vector, equal-length intervals are created that cover the single value.) If a labels parameter is specified, its values are used to name the factor levels. If none is specified, the factor level labels are constructed as "(b1, b2]","(b2, b3]" etc. for right = TRUE and as "[b1, b2)", . . . if right = FALSE. In this case, dig.lab indicates the minimum number of digits should be used in formatting the numbers b1, b2, . . . . A larger value (up to 12) will be used if needed to distinguish between any pair of endpoints: if this fails labels such as "Range3" will be used. cut 107 Value A factor is returned, unless labels = FALSE which results in the mere integer level codes. Note Instead of table(cut(x, br)), hist(x, br, plot = FALSE) is more efficient and less memory hungry. Instead of cut(*, labels = FALSE), findInterval() is more efficient. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also split for splitting a variable according to a group factor; factor, tabulate, table, findInterval(). quantile for ways of choosing breaks of roughly equal content (rather than length). Examples Z <- stats::rnorm(10000) table(cut(Z, breaks = -6:6)) sum(table(cut(Z, breaks = -6:6, labels=FALSE))) sum(graphics::hist(Z, breaks = -6:6, plot=FALSE)$counts) cut(rep(1,5),4)#-- dummy tx0 <- c(9, 4, 6, 5, 3, 10, 5, 3, 5) x <- rep(0:8, tx0) stopifnot(table(x) == tx0) table( cut(x, b = 8)) table( cut(x, breaks = 3*(-2:5))) table( cut(x, breaks = 3*(-2:5), right = FALSE)) ##--- some values OUTSIDE the breaks : table(cx <- cut(x, breaks = 2*(0:4))) table(cxl <- cut(x, breaks = 2*(0:4), right = FALSE)) which(is.na(cx)); x[is.na(cx)] #-- the first 9 values 0 which(is.na(cxl)); x[is.na(cxl)] #-- the last 5 values 8 ## Label construction: y <- stats::rnorm(100) table(cut(y, breaks = pi/3*(-3:3))) table(cut(y, breaks = pi/3*(-3:3), dig.lab=4)) table(cut(y, breaks = 1*(-3:3), dig.lab=4)) # extra digits don’t "harm" here table(cut(y, breaks = 1*(-3:3), right = FALSE)) #- the same, since no exact INT! 108 cut.POSIXt ## sometimes the default dig.lab is not enough to be avoid confusion: aaa <- c(1,2,3,4,5,2,3,4,5,6,7) cut(aaa, 3) cut(aaa, 3, dig.lab=4, ordered = TRUE) ## one way to extract the breakpoints labs <- levels(cut(aaa, 3)) cbind(lower = as.numeric( sub("\\((.+),.*", "\\1", labs) ), upper = as.numeric( sub("[^,]*,([^]]*)\\]", "\\1", labs) )) cut.POSIXt Convert a Date or Date-Time Object to a Factor Description Method for cut applied to date-time objects. Usage ## S3 method for class ’POSIXt’ cut(x, breaks, labels = NULL, start.on.monday = TRUE, right = FALSE, ...) ## S3 method for class ’Date’ cut(x, breaks, labels = NULL, start.on.monday = TRUE, right = FALSE, ...) Arguments x an object inheriting from class "POSIXt" or "Date". breaks a vector of cut points or number giving the number of intervals which x is to be cut into or an interval specification, one of "sec","min","hour","day", "DSTday","week","month","quarter" or "year", optionally preceded by an integer and a space, or followed by "s". For "Date" objects only "day", "week","month","quarter" and "year" are allowed. labels labels for the levels of the resulting category. By default, labels are constructed from the left-hand end of the intervals (which are include for the default value of right). If labels = FALSE, simple integer codes are returned instead of a factor. start.on.monday logical. If breaks = "weeks", should the week start on Mondays or Sundays? right, ... arguments to be passed to or from other methods. data.class 109 Details Using both right = TRUE and include.lowest = TRUE will include both ends of the range of dates. Using breaks = "quarter" will create intervals of 3 calendar months, with the intervals beginning on January 1, April 1, July 1 or October 1, based upon min(x) as appropriate. Value A factor is returned, unless labels = FALSE which returns the integer level codes. See Also seq.POSIXt, seq.Date, cut Examples ## random dates in a 10-week period cut(ISOdate(2001, 1, 1) + 70*86400*stats::runif(100), "weeks") cut(as.Date("2001/1/1") + 70*stats::runif(100), "weeks") data.class Object Classes Description Determine the class of an arbitrary R object. Usage data.class(x) Arguments x an R object. Value character string giving the class of x. The class is the (first element) of the class attribute if this is non-NULL, or inferred from the object’s dim attribute if this is non-NULL, or mode(x). Simply speaking, data.class(x) returns what is typically useful for method dispatching. (Or, what the basic creator functions already and maybe eventually all will attach as a class attribute.) Note For compatibility reasons, there is one exception to the rule above: When x is integer, the result of data.class(x) is "numeric" even when x is classed. 110 data.frame See Also class Examples x <- LETTERS data.class(factor(x)) # has a class attribute data.class(matrix(x, ncol = 13)) # has a dim attribute data.class(list(x)) # the same as mode(x) data.class(x) # the same as mode(x) stopifnot(data.class(1:2) == "numeric")# compatibility "rule" data.frame Data Frames Description This function creates data frames, tightly coupled collections of variables which share many of the properties of matrices and of lists, used as the fundamental data structure by most of R’s modeling software. Usage data.frame(..., row.names = NULL, check.rows = FALSE, check.names = TRUE, stringsAsFactors = default.stringsAsFactors()) default.stringsAsFactors() Arguments ... these arguments are of either the form value or tag = value. Component names are created based on the tag (if present) or the deparsed argument itself. row.names NULL or a single integer or character string specifying a column to be used as row names, or a character or integer vector giving the row names for the data frame. check.rows if TRUE then the rows are checked for consistency of length and names. check.names logical. If TRUE then the names of the variables in the data frame are checked to ensure that they are syntactically valid variable names and are not duplicated. If necessary they are adjusted (by make.names) so that they are. stringsAsFactors logical: should character vectors be converted to factors? The ‘factory-fresh’ default is TRUE, but this can be changed by setting options(stringsAsFactors = FALSE). data.frame 111 Details A data frame is a list of variables of the same number of rows with unique row names, given class "data.frame". If no variables are included, the row names determine the number of rows. The column names should be non-empty, and attempts to use empty names will have unsupported results. Duplicate column names are allowed, but you need to use check.names = FALSE for data.frame to generate such a data frame. However, not all operations on data frames will preserve duplicated column names: for example matrix-like subsetting will force column names in the result to be unique. data.frame converts each of its arguments to a data frame by calling as.data.frame(optional=TRUE). As that is a generic function, methods can be written to change the behaviour of arguments according to their classes: R comes with many such methods. Character variables passed to data.frame are converted to factor columns unless protected by I or argument stringsAsFactors is false. If a list or data frame or matrix is passed to data.frame it is as if each component or column had been passed as a separate argument (except for matrices of class "model.matrix" and those protected by I). Objects passed to data.frame should have the same number of rows, but atomic vectors, factors and character vectors protected by I will be recycled a whole number of times if necessary (including as elements of list arguments). If row names are not supplied in the call to data.frame, the row names are taken from the first component that has suitable names, for example a named vector or a matrix with rownames or a data frame. (If that component is subsequently recycled, the names are discarded with a warning.) If row.names was supplied as NULL or no suitable component was found the row names are the integer sequence starting at one (and such row names are considered to be ‘automatic’, and not preserved by as.matrix). If row names are supplied of length one and the data frame has a single row, the row.names is taken to specify the row names and not a column (by name or number). Names are removed from vector inputs not protected by I. default.stringsAsFactors is a utility that takes getOption("stringsAsFactors") and ensures the result is TRUE or FALSE (or throws an error if the value is not NULL). Value A data frame, a matrix-like structure whose columns may be of differing types (numeric, logical, factor and character and so on). How the names of the data frame are created is complex, and the rest of this paragraph is only the basic story. If the arguments are all named and simple objects (not lists, matrices of data frames) then the argument names give the column names. For an unnamed simple argument, a deparsed version of the argument is used as the name (with an enclosing I(...) removed). For a named ma- trix/list/data frame argument with more than one named column, the names of the columns are the name of the argument followed by a dot and the column name inside the argument: if the argument is unnamed, the argument’s column names are used. For a named or unnamed matrix/list/data frame argument that contains a single column, the column name in the result is the column name in the argument. Finally, the names are adjusted to be unique and syntactically valid unless check.names = FALSE. 112 data.matrix Note In versions of R prior to 2.4.0 row.names had to be character: to ensure compatibility with such versions of R, supply a character vector as the row.names argument. References Chambers, J. M. (1992) Data for models. Chapter 3 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. See Also I, plot.data.frame, print.data.frame, row.names, names (for the column names), [.data.frame for subsetting methods, Math.data.frame etc, about Group methods for data.frames; read.table, make.names. Examples L3 <- LETTERS[1:3] (d <- data.frame(cbind(x=1, y=1:10), fac=sample(L3, 10, replace=TRUE))) ## The same with automatic column names: data.frame(cbind( 1, 1:10), sample(L3, 10, replace=TRUE)) is.data.frame(d) ## do not convert to factor, using I() : (dd <- cbind(d, char = I(letters[1:10]))) rbind(class=sapply(dd, class), mode=sapply(dd, mode)) stopifnot(1:10 == row.names(d))# {coercion} (d0 <- d[, FALSE]) # NULL data frame with 10 rows (d.0 <- d[FALSE, ]) # <0 rows> data frame (3 cols) (d00 <- d0[FALSE,]) # NULL data frame with 0 rows data.matrix Convert a Data Frame to a Numeric Matrix Description Return the matrix obtained by converting all the variables in a data frame to numeric mode and then binding them together as the columns of a matrix. Factors and ordered factors are replaced by their internal codes. Usage data.matrix(frame, rownames.force = NA) data.matrix 113 Arguments frame a data frame whose components are logical vectors, factors or numeric vectors. rownames.force logical indicating if the resulting matrix should have character (rather than NULL) rownames. The default, NA, uses NULL rownames if the data frame has ‘auto- matic’ row.names or for a zero-row data frame. Details Logical and factor columns are converted to integers. Any other column which is not numeric (according to is.numeric) is converted by as.numeric or, for S4 objects, as(, "numeric"). If all columns are integer (after conversion) the result is an integer matrix, otherwise a numeric (double) matrix. Value If frame inherits from class "data.frame", an integer or numeric matrix of the same dimensions as frame, with dimnames taken from the row.names (or NULL, depending on rownames.force) and names. Otherwise, the result of as.matrix. Note The default behaviour for data frames differs from R < 2.5.0 which always gave the result character rownames. References Chambers, J. M. (1992) Data for models. Chapter 3 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. See Also as.matrix, data.frame, matrix. Examples DF <- data.frame(a=1:3, b=letters[10:12], c=seq(as.Date("2004-01-01"), by = "week", len = 3), stringsAsFactors = TRUE) data.matrix(DF[1:2]) data.matrix(DF) 114 Dates date System Date and Time Description Returns a character string of the current system date and time. Usage date() Value The string has the form "Fri Aug 20 11:11:00 1999", i.e., length 24, since it relies on POSIX’s ctime ensuring the above fixed format. Timezone and Daylight Saving Time are taken account of, but not indicated in the result. The day and month abbreviations are always in English, irrespective of locale. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also Sys.Date and Sys.time; Date and DateTimeClasses for objects representing date and time. Examples (d <- date()) nchar(d) == 24 ## something similar in the current locale format(Sys.time(), "%a %b %d %H:%M:%S %Y") Dates Date Class Description Description of the class "Date" representing calendar dates. Usage ## S3 method for class ’Date’ summary(object, digits = 12, ...) Dates 115 Arguments object An object summarized. digits Number of significant digits for the computations. ... Further arguments to be passed from or to other methods. Details Dates are represented as the number of days since 1970-01-01, with negative values for earlier dates. They are always printed following the rules of the current Gregorian calendar, even though that calendar was not in use long ago (it was adopted in 1752 in Great Britain and its colonies). It is intended that the date should be an integer, but this is not enforced in the internal representation. Fractional days will be ignored when printing. It is possible to produce fractional days via the mean method or by adding or subtracting (see Ops.Date). The print methods respect options("max.print"). See Also Sys.Date for the current date. Ops.Date for operators on "Date" objects. format.Date for conversion to and from character strings. axis.Date and hist.Date for plotting. weekdays for convenience extraction functions. seq.Date, cut.Date, round.Date for utility operations. DateTimeClasses for date-time classes. Examples ## Not run: (today <- Sys.Date()) format(today, "%d %b %Y") # with month as a word (tenweeks <- seq(today, length.out=10, by="1 week")) # next ten weeks weekdays(today) months(tenweeks) as.Date(.leap.seconds) ## End(Not run) 116 DateTimeClasses DateTimeClasses Date-Time Classes Description Description of the classes "POSIXlt" and "POSIXct" representing calendar dates and times (to the nearest second). Usage ## S3 method for class ’POSIXct’ print(x, ...) ## S3 method for class ’POSIXct’ summary(object, digits = 15, ...) time + z z + time time - z time1 lop time2 Arguments x, object An object to be printed or summarized from one of the date-time classes. digits Number of significant digits for the computations: should be high enough to represent the least important time unit exactly. ... Further arguments to be passed from or to other methods. time date-time objects time1, time2 date-time objects or character vectors. (Character vectors are converted by as.POSIXct.) z a numeric vector (in seconds) lop One of ==,!=, <, <=, > or >=. Details There are two basic classes of date/times. Class "POSIXct" represents the (signed) number of seconds since the beginning of 1970 (in the UTC timezone) as a numeric vector. Class "POSIXlt" is a named list of vectors representing sec 0–61: seconds min 0–59: minutes hour 0–23: hours mday 1–31: day of the month mon 0–11: months after the first of the year. DateTimeClasses 117 year years since 1900. wday 0–6 day of the week, starting on Sunday. yday 0–365: day of the year. isdst Daylight Savings Time flag. Positive if in force, zero if not, negative if unknown. Note that the internal list structure is somewhat hidden, as many methods, including print() or str, apply to the abstract date-time vector, as for "POSIXct". The classes correspond to the POSIX/C99 constructs of ‘calendar time’ (the time_t data type) and ‘local time’ (or broken-down time, the struct tm data type), from which they also inherit their names. The components of "POSIXlt" are integer vectors, except sec. "POSIXct" is more convenient for including in data frames, and "POSIXlt" is closer to human- readable forms. A virtual class "POSIXt" exists from which both of the classes inherit: it is used to allow operations such as subtraction to mix the two classes. Note that length(x) is the length of the corresponding (abstract) date/time vector, also in the "POSIXlt" case. Components wday and yday of "POSIXlt" are for information, and are not used in the conversion to calendar time. However, isdst is needed to distinguish times at the end of DST: typically 1am to 2am occurs twice, first in DST and then in standard time. At all other times isdst can be deduced from the first six values, but the behaviour if it is set incorrectly is platform-dependent. Logical comparisons and limited arithmetic are available for both classes. One can add or sub- tract a number of seconds from a date-time object, but not add two date-time objects. Subtraction of two date-time objects is equivalent to using difftime. Be aware that "POSIXlt" objects will be interpreted as being in the current timezone for these operations, unless a timezone has been specified. "POSIXlt" objects will often have an attribute "tzone", a character vector of length 3 giving the timezone name from the TZ environment variable and the names of the base timezone and the alternate (daylight-saving) timezone. Sometimes this may just be of length one, giving the timezone name. "POSIXct" objects may also have an attribute "tzone", a character vector of length one. If set to a non-empty value, it will determine how the object is converted to class "POSIXlt" and in particular how it is printed. This is usually desirable, but if you want to specify an object in a particular timezone but to be printed in the current timezone you may want to remove the "tzone" attribute (e.g. by c(x)). Unfortunately, the conversion is complicated by the operation of time zones and leap seconds (24 days have been 86401 seconds long so far: the times of the extra seconds are in the object .leap.seconds). The details of this are entrusted to the OS services where possible. This always covers the period 1970–2037, and on most machines back to 1902 (when time zones were in their infancy). Outside the platform limits we use our own C code. This uses the offset from GMT in use either for 1902 (when there was no DST) or that predicted for one of 2030 to 2037 (chosen so that the likely DST transition days are Sundays), and uses the alternate (daylight-saving) timezone only if isdst is positive or (if -1) if DST was predicted to be in operation in the 2030s on that day. (There is no reason to suppose that the DST rules will remain the same in the future, and indeed the US legislated in 2005 to change its rules as from 2007, with a possible future reversion.) It seems that some rare systems use leap seconds, but most ignore them (as required by POSIX). This is detected and corrected for at build time, so all "POSIXct" times used by R do not include leap seconds. (Conceivably this could be wrong if the system has changed since build time, just possibly by changing locales or the ‘zoneinfo’ database.) 118 DateTimeClasses Using c on "POSIXlt" objects converts them to the current time zone, and on "POSIXct" objects drops any "tzone" attributes (even if they are all marked with the same time zone). A few times have specific issues. First, the leap seconds are ignored, and real times such as "2005- 12-31 23:59:60" are (probably) treated as the next second. However, they will never be generated by R, and are unlikely to arise as input. Second, on some OSes there is a problem in the POSIX/C99 standard with "1969-12-31 23:59:59 UTC", which is -1 in calendar time and that value is on those OSes also used as an error code. Thus as.POSIXct("1969-12-31 23:59:59", format = "%Y- %m-%d %H:%M:%S", tz = "UTC") may give NA, and hence as.POSIXct("1969-12-31 23:59:59", tz = "UTC") will give "1969-12-31 23:59:00". Other OSes (including the code used by R on Windows) report errors separately and so are able to handle that time as valid. The print methods respect options("max.print"). Sub-second Accuracy Classes "POSIXct" and "POSIXlt" are able to express fractions of a second. (Conversion of frac- tions between the two forms may not be exact, but will have better than microsecond accuracy.) Fractional seconds are printed only if options("digits.secs") is set: see strftime. Warning Some Unix-like systems (especially Linux ones) do not have environment variable TZ set, yet have internal code that expects it (as does POSIX). We have tried to work around this, but if you get unexpected results try setting TZ. See Sys.timezone for valid settings. References Ripley, B. D. and Hornik, K. (2001) Date-time classes. R News, 1/2, 8–11. http://www. r-project.org/doc/Rnews/Rnews_2001-2.pdf See Also Dates for dates without times. as.POSIXct and as.POSIXlt for conversion between the classes. strptime for conversion to and from character representations. Sys.time for clock time as a "POSIXct" object. difftime for time intervals. cut.POSIXt, seq.POSIXt, round.POSIXt and trunc.POSIXt for methods for these classes. weekdays for convenience extraction functions. Examples (z <- Sys.time()) # the current date, as class "POSIXct" Sys.time() - 3600 # an hour ago as.POSIXlt(Sys.time(), "GMT") # the current time in GMT format(.leap.seconds) # all 24 leap seconds in your timezone dcf 119 print(.leap.seconds, tz="PST8PDT") # and in Seattle’s ## look at *internal* representation of "POSIXlt" : leapS <- as.POSIXlt(.leap.seconds) names(leapS) ; is.list(leapS) utils::str(unclass(leapS), vec.len = 7) dcf Read and Write Data in DCF Format Description Reads or writes an R object from/to a file in Debian Control File format. Usage read.dcf(file, fields = NULL, all = FALSE, keep.white = NULL) write.dcf(x, file = "", append = FALSE, indent = 0.1 * getOption("width"), width = 0.9 * getOption("width"), keep.white = NULL) Arguments file either a character string naming a file or a connection."" indicates output to the console. For read.dcf this can name a compressed file (see gzfile). fields Fields to read from the DCF file. Default is to read all fields. all a logical indicating whether in case of multiple occurrences of a field in a record, all these should be gathered. If all is false (default), only the last such occur- rence is used. keep.white a character string with the names of the fields for which whitespace should be kept as is, or NULL (default) indicating that there are no such fields. Coerced to character if possible. For fields where whitespace is not to be kept as is, read.dcf removes leading and trailing whitespace, and write.dcf folds using strwrap. x the object to be written, typically a data frame. If not, it is attempted to coerce x to a data frame. append logical. If TRUE, the output is appended to the file. If FALSE, any existing file of the name is destroyed. indent a positive integer specifying the indentation for continuation lines in output en- tries. width a positive integer giving the target column for wrapping lines in the output. 120 dcf Details DCF is a simple format for storing databases in plain text files that can easily be directly read and written by humans. DCF is used in various places to store R system information, like descriptions and contents of packages. The DCF rules as implemented in R are: 1. A database consists of one or more records, each with one or more named fields. Not every record must contain each field. Fields may appear more than once in a record. 2. Regular lines start with a non-whitespace character. 3. Regular lines are of form tag:value, i.e., have a name tag and a value for the field, separated by :(only the first : counts). The value can be empty (i.e., whitespace only). 4. Lines starting with whitespace are continuation lines (to the preceding field) if at least one character in the line is non-whitespace. Continuation lines where the only non-whitespace character is a ‘.’ are taken as blank lines (allowing for multi-paragraph field values). 5. Records are separated by one or more empty (i.e., whitespace only) lines. Note that read.dcf(all = FALSE) reads the file byte-by-byte. This allows a ‘DESCRIPTION’ file to be read and only its ASCII fields used, or its ‘Encoding’ field used to re-encode the remaining fields. write.dcf does not write NA fields. Value The default read.dcf(all = FALSE) returns a character matrix with one row per record and one column per field. Leading and trailing whitespace of field values is ignored unless a field is listed in keep.white. If a tag name is specified in the file, but the corresponding value is empty, then an empty string is returned. If the tag name of a field is specified in fields but never used in a record, then the corresponding value is NA. If fields are repeated within a record, the last one encountered is returned. Malformed lines lead to an error. For read.dcf(all = TRUE) a data frame is returned, again with one row per record and one column per field. The columns are lists of character vectors for fields with multiple occurrences, and character vectors otherwise. Note that an empty file is a valid DCF file, and read.dcf will return a zero-row matrix or data frame. For write.dcf, invisible NULL. References http://www.debian.org/doc/debian-policy/ch-controlfields.html. Note that R does not require encoding in UTF-8, which is a recent Debian requirement. See Also write.table. debug 121 Examples ## Not run: ## Create a reduced version of the ’CONTENTS’ file in package ’splines’ x <- read.dcf(file = system.file("CONTENTS", package = "splines"), fields = c("Entry", "Description")) write.dcf(x) ## End(Not run) debug Debug a Function Description Set, unset or query the debugging flag on a function. The text and condition arguments are the same as those that can be supplied via a call to browser. They can be retrieved by the user once the browser has been entered, and provide a mechanism to allow users to identify which breakpoint has been activated. Usage debug(fun, text="", condition=NULL) debugonce(fun, text="", condition=NULL) undebug(fun) isdebugged(fun) Arguments fun any interpreted R function. text a text string that can be retrieved when the browser is entered. condition a condition that can be retrieved when the browser is entered. Details When a function flagged for debugging is entered, normal execution is suspended and the body of function is executed one statement at a time. A new browser context is initiated for each step (and the previous one destroyed). At the debug prompt the user can enter commands or R expressions, followed by a newline. The commands are n (or just an empty line, by default). Advance to the next step. c continue to the end of the current context: e.g. to the end of the loop if within a loop or to the end of the function. cont synonym for c. where print a stack trace of all active function calls. 122 Defunct Q exit the browser and the current evaluation and return to the top-level prompt. (Leading and trailing whitespace is ignored, except for an empty line). Anything else entered at the debug prompt is interpreted as an R expression to be evaluated in the calling environment: in particular typing an object name will cause the object to be printed, and ls() lists the objects in the calling frame. (If you want to look at an object with a name such as n, print it explicitly.) Setting option "browserNLdisabled" to TRUE disables the use of an empty line as a synonym for n. If this is done, the user will be re-prompted for input until a valid command or an expression is entered. To debug a function is defined inside a function, single-step though to the end of its definition, and then call debug on its name. If you want to debug a function not starting at the very beginning, use trace(..., at = *) or setBreakpoint. Using debug is persistent, and unless debugging is turned off the debugger will be entered on every invocation (note that if the function is removed and replaced the debug state is not preserved). Use debugonce to enter the debugger only the next time the function is invoked. In order to debug S4 methods (see Methods), you need to use trace, typically calling browser, e.g., as trace("plot", browser, exit=browser, signature = c("track", "missing")) The number of lines printed for the deparsed call when a function is entered for debugging can be limited by setting options(deparse.max.lines). See Also browser, trace; traceback to see the stack after an Error: ... message; recover for another debugging approach. Defunct Marking Objects as Defunct Description When a function is removed from R it should be replaced by a function which calls .Defunct. Usage .Defunct(new, package = NULL, msg) Arguments new character string: A suggestion for a replacement function. package character string: The package to be used when suggesting where the defunct function might be listed. msg character string: A message to be printed, if missing a default message is used. delayedAssign 123 Details .Defunct is called from defunct functions. Functions should be listed in help("pkg-defunct") for an appropriate pkg, including base. See Also Deprecated. base-defunct and so on which list the defunct functions in the packages. delayedAssign Delay Evaluation Description delayedAssign creates a promise to evaluate the given expression if its value is requested. This provides direct access to the lazy evaluation mechanism used by R for the evaluation of (interpreted) functions. Usage delayedAssign(x, value, eval.env = parent.frame(1), assign.env = parent.frame(1)) Arguments x a variable name (given as a quoted string in the function call) value an expression to be assigned to x eval.env an environment in which to evaluate value assign.env an environment in which to assign x Details Both eval.env and assign.env default to the currently active environment. The expression assigned to a promise by delayedAssign will not be evaluated until it is eventually ‘forced’. This happens when the variable is first accessed. When the promise is eventually forced, it is evaluated within the environment specified by eval.env (whose contents may have changed in the meantime). After that, the value is fixed and the expres- sion will not be evaluated again. Value This function is invoked for its side effect, which is assigning a promise to evaluate value to the variable x. 124 deparse See Also substitute, to see the expression associated with a promise. Examples msg <- "old" delayedAssign("x", msg) msg <- "new!" x #- new! substitute(x) #- x (was ’msg’ ?) delayedAssign("x", { for(i in 1:3) cat("yippee!\n") 10 }) x^2 #- yippee x^2 #- simple number e <- (function(x, y = 1, z) environment())(1+2, "y", {cat(" HO! "); pi+2}) (le <- as.list(e)) # evaluates the promises deparse Expression Deparsing Description Turn unevaluated expressions into character strings. Usage deparse(expr, width.cutoff = 60L, backtick = mode(expr) %in% c("call", "expression", "(", "function"), control = c("keepInteger", "showAttributes", "keepNA"), nlines = -1L) Arguments expr any R expression. width.cutoff integer in [20, 500] determining the cutoff (in bytes) at which line-breaking is tried. backtick logical indicating whether symbolic names should be enclosed in backticks if they do not follow the standard syntax. control character vector of deparsing options. See .deparseOpts. nlines integer: the maximum number of lines to produce. Negative values indicate no limit. deparse 125 Details This function turns unevaluated expressions (where ‘expression’ is taken in a wider sense than the strict concept of a vector of mode "expression" used in expression) into character strings (a kind of inverse to parse). A typical use of this is to create informative labels for data sets and plots. The example shows a simple use of this facility. It uses the functions deparse and substitute to create labels for a plot which are character string versions of the actual arguments to the function myplot. The default for the backtick option is not to quote single symbols but only composite expressions. This is a compromise to avoid breaking existing code. Using control = "all" comes closest to making deparse() an inverse of parse(). However, not all objects are deparse-able even with this option and a warning will be issued if the function recognizes that it is being asked to do the impossible. Numeric and complex vectors are converted using 15 significant digits: see as.character for more details. width.cutoff is a lower bound for the line lengths: deparsing a line proceeds until at least width.cutoff bytes have been output and e.g. arg = value expressions will not be split across lines. Note To avoid the risk of a source attribute out of sync with the actual function definition, the source attribute of a function will never be deparsed as an attribute. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also substitute, parse, expression. Quotes for quoting conventions, including backticks. Examples require(stats); require(graphics) deparse(args(lm)) deparse(args(lm), width = 500) myplot <- function(x, y) { plot(x, y, xlab=deparse(substitute(x)), ylab=deparse(substitute(y))) } e <- quote(‘foo bar‘) deparse(e) deparse(e, backtick=TRUE) e <- quote(‘foo bar‘+1) 126 deparseOpts deparse(e) deparse(e, control = "all") deparseOpts Options for Expression Deparsing Description Process the deparsing options for deparse, dput and dump. Usage .deparseOpts(control) Arguments control character vector of deparsing options. Details This is called by deparse, dput and dump to process their control argument. The control argument is a vector containing zero or more of the following strings. Partial string matching is used. keepInteger Either surround integer vectors by as.integer() or use suffix L, so they are not converted to type double when parsed. This includes making sure that integer NAs are pre- served (via NA_integer_ if there are no non-NA values in the vector, unless "S_compatible" is set). quoteExpressions Surround expressions with quote(), so they are not evaluated when re-parsed. showAttributes If the object has attributes (other than a source attribute), use structure() to display them as well as the object value. This is the default for deparse and dput. useSource If the object has a source attribute, display that instead of deparsing the object. Cur- rently only applies to function definitions. warnIncomplete Some exotic objects such as environments, external pointers, etc. can not be deparsed properly. This option causes a warning to be issued if the deparser recognizes one of these situations. Also, the parser in R < 2.7.0 would only accept strings of up to 8192 bytes, and this option gives a warning for longer strings. keepNA Integer, real and character NAs are surrounded by coercion where necessary to ensure that they are parsed to the same type. all An abbreviated way to specify all of the options listed above. This is the default for dump, and the options used by edit (which are fixed). delayPromises Deparse promises in the form rather than evaluating them. The value and the environment of the promise will not be shown and the deparsed code cannot be sourced. Deprecated 127 S_compatible Make deparsing as far as possible compatible with S and R < 2.5.0. For compat- ibility with S, integer values of double vectors are deparsed with a trailing decimal point. Backticks are not used. For the most readable (but perhaps incomplete) display, use control = NULL. This displays the object’s value, but not its attributes. The default in deparse is to display the attributes as well, but not to use any of the other options to make the result parseable. (dput and dump do use more default options, and printing of functions without sources uses c("keepInteger", "keepNA").) Using control = "all" comes closest to making deparse() an inverse of parse(). However, not all objects are deparse-able even with this option. A warning will be issued if the function recognizes that it is being asked to do the impossible. Value A numerical value corresponding to the options selected. Deprecated Marking Objects as Deprecated Description When an object is about removed from R it is first deprecated and should include a call to .Deprecated. Usage .Deprecated(new, package=NULL, msg) Arguments new character string: A suggestion for a replacement function. package character string: The package to be used when suggesting where the deprecated function might be listed. msg character string: A message to be printed, if missing a default message is used. Details .Deprecated("") is called from deprecated functions. The original help page for these functions is often available at help("oldName-deprecated") (note the quotes). Functions should be listed in help("pkg-deprecated") for an appropriate pkg, including base. See Also Defunct base-deprecated and so on which list the deprecated functions in the packages. 128 det det Calculate the Determinant of a Matrix Description det calculates the determinant of a matrix. determinant is a generic function that returns sepa- rately the modulus of the determinant, optionally on the logarithm scale, and the sign of the deter- minant. Usage det(x, ...) determinant(x, logarithm = TRUE, ...) Arguments x numeric matrix. logarithm logical; if TRUE (default) return the logarithm of the modulus of the determinant. ... Optional arguments. At present none are used. Previous versions of det al- lowed an optional method argument. This argument will be ignored but will not produce an error. Details The determinant function uses an LU decomposition and the det function is simply a wrapper around a call to determinant. Often, computing the determinant is not what you should be doing to solve a given problem. Value For det, the determinant of x. For determinant, a list with components modulus a numeric value. The modulus (absolute value) of the determinant if logarithm is FALSE; otherwise the logarithm of the modulus. sign integer; either +1 or −1 according to whether the determinant is positive or negative. Examples (x <- matrix(1:4, ncol=2)) unlist(determinant(x)) det(x) det(print(cbind(1,1:3,c(2,0,1)))) detach 129 detach Detach Objects from the Search Path Description Detach a database, i.e., remove it from the search() path of available R objects. Usually this is either a data.frame which has been attached or a package which was attached by library. Usage detach(name, pos = 2, unload = FALSE, character.only = FALSE, force = FALSE) Arguments name The object to detach. Defaults to search()[pos]. This can be an unquoted name or a character string but not a character vector. If a number is supplied this is taken as pos. pos Index position in search() of the database to detach. When name is a number, pos = name is used. unload A logical value indicating whether or not to attempt to unload the namespace when a package is being detached. If the package has a namespace and unload is TRUE, then detach will attempt to unload the namespace via unloadNamespace: if the namespace is imported by another namespace or unload is FALSE, no unloading will occur. character.only a logical indicating whether name can be assumed to be character strings. force logical: should a package be detached even though other attached packages de- pend on it? Details This is most commonly used with a single number argument referring to a position on the search list, and can also be used with a unquoted or quoted name of an item on the search list such as package:tools. If a package has a namespace, detaching it does not by default unload the namespace (and may not even with unload=TRUE), and detaching will not in general unload any dynamically loaded compiled code (DLLs). Further, registered S3 methods from the namespace will not be removed. If you use library on a package whose namespace is loaded, it attaches the exports of the already loaded namespace. So detaching and re-attaching a package may not refresh some or all components of the package, and is inadvisable. Value The return value is invisible. It is NULL when a package is detached, otherwise the environment which was returned by attach when the object was attached (incorporating any changes since it was attached). 130 diag Note You cannot detach either the workspace (position 1) nor the base package (the last item in the search list), and attempting to do so will throw an error. Unloading some namespaces has undesirable side effects: e.g. unloading grid closes all graphics devices, and on most systems tcltk cannot be reloaded once it has been unloaded and may crash R if this is attempted. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also attach, library, search, objects, unloadNamespace, library.dynam.unload . Examples require(splines) # package detach(package:splines) ## or also library(splines) pkg <- "package:splines" detach(pkg, character.only = TRUE) ## careful: do not do this unless ’splines’ is not already attached. library(splines) detach(2) # ’pos’ used for ’name’ ## an example of the name argument to attach ## and of detaching a database named by a character vector attach_and_detach <- function(db, pos=2) { name <- deparse(substitute(db)) attach(db, pos=pos, name=name) print(search()[pos]) detach(name, character.only = TRUE) } attach_and_detach(women, pos=3) diag Matrix Diagonals Description Extract or replace the diagonal of a matrix, or construct a diagonal matrix. diag 131 Usage diag(x = 1, nrow, ncol) diag(x) <- value Arguments x a matrix, vector or 1D array, or missing. nrow, ncol Optional dimensions for the result when x is not a matrix. value either a single value or a vector of length equal to that of the current diagonal. Should be of a mode which can be coerced to that of x. Details diag has four distinct usages: 1. x is a matrix, when it extracts the diagonal. 2. x is missing and nrow is specified, it returns an identity matrix. 3. x is a scalar (length-one vector) and the only argument, it returns a square identity matrix of size given by the scalar. 4. x is a vector, either of length at least 2 or there were further arguments. This returns a matrix with the given diagonal and zero off-diagonal entries. It is an error to specify nrow or ncol in the first case. Value If x is a matrix then diag(x) returns the diagonal of x. The resulting vector will have names if the matrix x has matching column and rownames. The replacement form sets the diagonal of the matrix x to the given value(s). In all other cases the value is a diagonal matrix with nrow rows and ncol columns (if ncol is not given the matrix is square). Here nrow is taken from the argument if specified, otherwise inferred from x: if that is a vector (or 1D array) of length two or more, then its length is the number of rows, but if it is of length one and neither nrow nor ncol is specified, nrow = as.integer(x). When a diagonal matrix is returned, the diagonal elements are one except in the fourth case, when x gives the diagonal elements: it will be recycled or truncated as needed, but fractional recycling and truncation will give a warning. Note Using diag(x) can have unexpected effects if x is a vector that could be of length one. Use diag(x, nrow = length(x)) for consistent behaviour. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. 132 diff See Also upper.tri, lower.tri, matrix. Examples require(stats) dim(diag(3)) diag(10,3,4) # guess what? all(diag(1:3) == {m <- matrix(0,3,3); diag(m) <- 1:3; m}) diag(var(M <- cbind(X = 1:5, Y = stats::rnorm(5)))) #-> vector with names "X" and "Y" rownames(M) <- c(colnames(M),rep("",3)); M; diag(M) # named as well diff Lagged Differences Description Returns suitably lagged and iterated differences. Usage diff(x, ...) ## Default S3 method: diff(x, lag = 1, differences = 1, ...) ## S3 method for class ’POSIXt’ diff(x, lag = 1, differences = 1, ...) ## S3 method for class ’Date’ diff(x, lag = 1, differences = 1, ...) Arguments x a numeric vector or matrix containing the values to be differenced. lag an integer indicating which lag to use. differences an integer indicating the order of the difference. ... further arguments to be passed to or from methods. Details diff is a generic function with a default method and ones for classes "ts","POSIXt" and "Date". NA’s propagate. difftime 133 Value If x is a vector of length n and differences=1, then the computed result is equal to the successive differences x[(1+lag):n] - x[1:(n-lag)]. If difference is larger than one this algorithm is applied recursively to x. Note that the returned value is a vector which is shorter than x. If x is a matrix then the difference operations are carried out on each column separately. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also diff.ts, diffinv. Examples diff(1:10, 2) diff(1:10, 2, 2) x <- cumsum(cumsum(1:10)) diff(x, lag = 2) diff(x, differences = 2) diff(.leap.seconds) difftime Time Intervals Description Time intervals creation, printing, and some arithmetic. Usage time1 - time2 difftime(time1, time2, tz, units = c("auto", "secs", "mins", "hours", "days", "weeks")) as.difftime(tim, format = "%X", units = "auto") ## S3 method for class ’difftime’ format(x, ...) ## S3 method for class ’difftime’ units(x) 134 difftime ## S3 replacement method for class ’difftime’ units(x) <- value ## S3 method for class ’difftime’ as.double(x, units = "auto", ...) ## Group methods, notably for round(), signif(), floor(), ## ceiling(), trunc(), abs(); called directly, *not* as Math(): ## S3 method for class ’difftime’ Math(x, ...) Arguments time1, time2 date-time or date objects. tz an optional timezone specification to be used for the conversion, mainly for "POSIXlt" objects. units character string. Units in which the results are desired. Can be abbreviated. value character string. Like units, except that abbreviations are not allowed. tim character string or numeric value specifying a time interval. format character specifying the format of tim: see strptime. The default is a locale- specific time format. x an object inheriting from class "difftime". ... arguments to be passed to or from other methods. Details Function difftime calculates a difference of two date/time objects and returns an object of class "difftime" with an attribute indicating the units. The Math group method provides round, signif, floor, ceiling, trunc, abs, and sign methods for objects of this class, and there are methods for the group-generic (see Ops) logical and arithmetic operations. If units = "auto", a suitable set of units is chosen, the largest possible (excluding "weeks") in which all the absolute differences are greater than one. Subtraction of date-time objects gives an object of this class, by calling difftime with units = "auto". Alternatively, as.difftime() works on character-coded or numeric time intervals; in the latter case, units must be specified, and format has no effect. Limited arithmetic is available on "difftime" objects: they can be added or subtracted, and mul- tiplied or divided by a numeric vector. In addition, adding or subtracting a numeric vector by a "difftime" object implicitly converts the numeric vector to a "difftime" object with the same units as the "difftime" object. There are methods for mean and sum (via the Summary group generic). The units of a "difftime" object can be extracted by the units function, which also has an re- placement form. If the units are changed, the numerical value is scaled accordingly. The as.double method returns the numeric value expressed in the specified units. Using units = "auto" means the units of the object. The format method simply formats the numeric value and appends the units as a text string. dim 135 The default behaviour when time1 or time2 was a "POSIXlt" object changed in R 2.12.0: pre- viously such objects were regarded as in the timezone given by tz which defaulted to the current timezone. See Also DateTimeClasses. Examples (z <- Sys.time() - 3600) Sys.time() - z # just over 3600 seconds. ## time interval between releases of R 1.2.2 and 1.2.3. ISOdate(2001, 4, 26) - ISOdate(2001, 2, 26) as.difftime(c("0:3:20", "11:23:15")) as.difftime(c("3:20", "23:15", "2:"), format= "%H:%M")# 3rd gives NA (z <- as.difftime(c(0,30,60), units="mins")) as.numeric(z, units="secs") as.numeric(z, units="hours") format(z) dim Dimensions of an Object Description Retrieve or set the dimension of an object. Usage dim(x) dim(x) <- value Arguments x an R object, for example a matrix, array or data frame. value For the default method, either NULL or a numeric vector, which is coerced to integer (by truncation). Details The functions dim and dim<- are internal generic primitive functions. dim has a method for data.frames, which returns the lengths of the row.names attribute of x and of x (as the numbers of rows and columns respectively). 136 dimnames Value For an array (and hence in particular, for a matrix) dim retrieves the dim attribute of the object. It is NULL or a vector of mode integer. The replacement method changes the "dim" attribute (provided the new value is compatible) and removes any "dimnames" and "names" attributes. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also ncol, nrow and dimnames. Examples x <- 1:12 ; dim(x) <- c(3,4) x # simple versions of nrow and ncol could be defined as follows nrow0 <- function(x) dim(x)[1] ncol0 <- function(x) dim(x)[2] dimnames Dimnames of an Object Description Retrieve or set the dimnames of an object. Usage dimnames(x) dimnames(x) <- value Arguments x an R object, for example a matrix, array or data frame. value a possible value for dimnames(x): see the ‘Value’ section. dimnames 137 Details The functions dimnames and dimnames<- are generic. For an array (and hence in particular, for a matrix), they retrieve or set the dimnames attribute (see attributes) of the object. A list value can have names, and these will be used to label the dimensions of the array where appropriate. The replacement method for arrays/matrices coerces vector and factor elements of value to charac- ter, but does not dispatch methods for as.character. It coerces zero-length elements to NULL, and a zero-length list to NULL. If value is a list shorter than the number of dimensions, it is extended with NULLs to the needed length. Both have methods for data frames. The dimnames of a data frame are its row.names and its names. For the replacement method each component of value will be coerced by as.character. For a 1D matrix the names are the same thing as the (only) component of the dimnames. Both are primitive functions. Value The dimnames of a matrix or array can be NULL or a list of the same length as dim(x). If a list, its components are either NULL or a character vector with positive length of the appropriate dimension of x. The list can be named. For the "data.frame" method both dimnames are character vectors, and the rownames must con- tain no duplicates nor missing values. Note Setting components of the dimnames, e.g. dimnames(A)[[1]] <- value is a common paradigm, but note that it will not work if the value assigned is NULL. Use rownames instead, or (as it does) manipulate the whole dimnames list. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also rownames, colnames; array, matrix, data.frame. Examples ## simple versions of rownames and colnames ## could be defined as follows rownames0 <- function(x) dimnames(x)[[1]] colnames0 <- function(x) dimnames(x)[[2]] 138 do.call do.call Execute a Function Call Description do.call constructs and executes a function call from a name or a function and a list of arguments to be passed to it. Usage do.call(what, args, quote = FALSE, envir = parent.frame()) Arguments what either a function or a non-empty character string naming the function to be called. args a list of arguments to the function call. The names attribute of args gives the argument names. quote a logical value indicating whether to quote the arguments. envir an environment within which to evaluate the call. This will be most useful if what is a character string and the arguments are symbols or quoted expressions. Details If quote is FALSE, the default, then the arguments are evaluated (in the calling environment, not in envir). If quote is TRUE then each argument is quoted (see quote) so that the effect of argument evaluation is to remove the quotes – leaving the original arguments unevaluated when the call is constructed. The behavior of some functions, such as substitute, will not be the same for functions evaluated using do.call as if they were evaluated from the interpreter. The precise semantics are currently undefined and subject to change. Value The result of the (evaluated) function call. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also call which creates an unevaluated call. double 139 Examples do.call("complex", list(imag = 1:3)) ## if we already have a list (e.g. a data frame) ## we need c() to add further arguments tmp <- expand.grid(letters[1:2], 1:3, c("+", "-")) do.call("paste", c(tmp, sep="")) do.call(paste, list(as.name("A"), as.name("B")), quote=TRUE) ## examples of where objects will be found. A <- 2 f <- function(x) print(x^2) env <- new.env() assign("A", 10, envir = env) assign("f", f, envir = env) f <- function(x) print(x) f(A) # 2 do.call("f", list(A)) # 2 do.call("f", list(A), envir=env) # 4 do.call(f, list(A), envir=env) # 2 do.call("f", list(quote(A)), envir=env) # 100 do.call(f, list(quote(A)), envir=env) # 10 do.call("f", list(as.name("A")), envir=env) # 100 eval(call("f", A)) # 2 eval(call("f", quote(A))) # 2 eval(call("f", A), envir=env) # 4 eval(call("f", quote(A)), envir=env) # 100 double Double-Precision Vectors Description Create, coerce to or test for a double-precision vector. Usage double(length = 0) as.double(x, ...) is.double(x) single(length = 0) as.single(x, ...) 140 double Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. Details double creates a double-precision vector of the specified length. The elements of the vector are all equal to 0. It is identical to numeric (and real). as.double is a generic function. It is identical to as.numeric (and as.real). Methods should return an object of base type "double". is.double is a test of double type. R has no single precision data type. All real numbers are stored in double precision format. The functions as.single and single are identical to as.double and double except they set the at- tribute Csingle that is used in the .C and .Fortran interface, and they are intended only to be used in that context. Value double creates a double-precision vector of the specified length. The elements of the vector are all equal to 0. as.double attempts to coerce its argument to be of double type: like as.vector it strips attributes including names. (To ensure that an object is of double type without stripping attributes, use storage.mode.) Character strings containing optional whitespace followed by either a decimal rep- resentation or a hexadecimal representation (starting with 0x or 0X) can be converted. as.double for factors yields the codes underlying the factor levels, not the numeric representation of the labels, see also factor. is.double returns TRUE or FALSE depending on whether its argument is of double type or not. Double-precision values All R platforms are required to work with values conforming to the IEC 60559 (also known as IEEE 754) standard. This basically works with a precision of 53 bits, and represents to that precision a range of absolute values from about 2 × 10−308 to 2 × 10308. It also has special values NaN (many of them), plus and minus infinity and plus and minus zero (although R acts as if these are the same). There are also denormal(ized) (or subnormal) numbers with absolute values above or below the range given above but represented to less precision. See .Machine for precise information on these limits. Note that ultimately how double precision numbers are handled is down to the CPU/FPU and compiler. In IEEE 754-2008/IEC60559:2011 this is called ‘binary64’ format. dput 141 Note on names It is a historical anomaly that R has three names for its floating-point vectors, double, numeric and real. double is the name of the type. numeric is the name of the mode and also of the implicit class. As an S4 formal class, use "numeric". real is deprecated and should not be used in new code. The potential confusion is that R has used mode "numeric" to mean ‘double or integer’, which conflicts with the S4 usage. Thus is.numeric tests the mode, not the class, but as.numeric (which is identical to as.double) coerces to the class. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. http://en.wikipedia.org/wiki/IEEE_754-1985, http://en.wikipedia.org/wiki/IEEE_ 754-2008, http://en.wikipedia.org/wiki/Double_precision, http://en.wikipedia.org/ wiki/Denormal_number. http://grouper.ieee.org/groups/754/ for links to information on the standards. See Also integer, numeric, storage.mode. Examples is.double(1) all(double(3) == 0) dput Write an Object to a File or Recreate it Description Writes an ASCII text representation of an R object to a file or connection, or uses one to recreate the object. Usage dput(x, file = "", control = c("keepNA", "keepInteger", "showAttributes")) dget(file) 142 dput Arguments x an object. file either a character string naming a file or a connection."" indicates output to the console. control character vector indicating deparsing options. See .deparseOpts for their de- scription. Details dput opens file and deparses the object x into that file. The object name is not written (unlike dump). If x is a function the associated environment is stripped. Hence scoping information can be lost. Deparsing an object is difficult, and not always possible. With the default control, dput() attempts to deparse in a way that is readable, but for more complex or unusual objects (see dump, not likely to be parsed as identical to the original. Use control = "all" for the most complete deparsing; use control = NULL for the simplest deparsing, not even including attributes. dput will warn if fewer characters were written to a file than expected, which may indicate a full or corrupt file system. To display saved source rather than deparsing the internal representation include "useSource" in control.R currently saves source only for function definitions. Value For dput, the first argument invisibly. For dget, the object created. Note To avoid the risk of a source attribute out of sync with the actual function definition, the source attribute of a function will never be written as an attribute. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also deparse, dump, write. Examples ## Write an ASCII version of mean to the file "foo" dput(mean, "foo") ## And read it back into ’bar’ bar <- dget("foo") unlink("foo") ## Create a function with comments drop 143 baz <- function(x) { # Subtract from one 1-x } ## and display it dput(baz) ## and now display the saved source dput(baz, control = "useSource") drop Drop Redundant Extent Information Description Delete the dimensions of an array which have only one level. Usage drop(x) Arguments x an array (including a matrix). Value If x is an object with a dim attribute (e.g., a matrix or array), then drop returns an object like x, but with any extents of length one removed. Any accompanying dimnames attribute is adjusted and returned with x: if the result is a vector the names are taken from the dimnames (if any). If the result is a length-one vector, the names are taken from the first dimension with a dimname. Array subsetting ([) performs this reduction unless used with drop = FALSE, but sometimes it is useful to invoke drop directly. See Also drop1 which is used for dropping terms in models. Examples dim(drop(array(1:12, dim=c(1,3,1,1,2,1,2))))# = 3 2 2 drop(1:3 %*% 2:4)# scalar product 144 droplevels droplevels droplevels Description The function droplevels is used to drop unused levels from a factor or, more commonly, from factors in a data frame. Usage ## S3 method for class ’factor’ droplevels(x,...) ## S3 method for class ’data.frame’ droplevels(x, except, ...) Arguments x an object from which to drop unused factor levels. ... further arguments passed to methods except indices of columns from which not to drop levels Details The method for class "factor" is essentially equivalent to factor(x). The except argument follow the usual indexing rules. Value droplevels returns an object of the same class as x Note This function was introduced in R 2.12.0. It is primarily intended for cases where one or more factors in a data frame contains only elements from a reduced level set after subsetting. (Notice that subsetting does not in general drop unused levels). By default, levels are dropped from all factors in a data frame, but the except argument allows you to specify columns for which this is not wanted. See Also subset for subsetting data frames. factor for definition of factors. drop for dropping array di- mensions. drop1 for dropping terms from a model. [.factor for subsetting of factors. Examples aq <- transform(airquality, Month=factor(Month,labels=month.abb[5:9])) aq <- subset(aq, Month != "Jul") table(aq$Month) table(droplevels(aq)$Month) dump 145 dump Text Representations of R Objects Description This function takes a vector of names of R objects and produces text representations of the objects on a file or connection. A dump file can usually be sourced into another R(or S) session. Usage dump(list, file = "dumpdata.R", append = FALSE, control = "all", envir = parent.frame(), evaluate = TRUE) Arguments list character. The names of one or more R objects to be dumped. file either a character string naming a file or a connection."" indicates output to the console. append if TRUE and file is a character string, output will be appended to file; other- wise, it will overwrite the contents of file. control character vector indicating deparsing options. See .deparseOpts for their de- scription. envir the environment to search for objects. evaluate logical. Should promises be evaluated? Details If some of the objects named do not exist (in scope), they are omitted, with a warning. If file is a file and no objects exist then no file is created. sourceing may not produce an identical copy of dumped objects. A warning is issued if it is likely that problems will arise, for example when dumping exotic or complex objects (see the Note). dump will also warn if fewer characters were written to a file than expected, which may indicate a full or corrupt file system. A dump file can be sourced into another R(or perhaps S) session, but the function save is designed to be used for transporting R data, and will work with R objects that dump does not handle. To produce a more readable representation of an object, use control = NULL. This will skip attributes, and will make other simplifications that make source less likely to produce an identical copy. See deparse for details. To deparse the internal representation of a function rather than displaying the saved source, use control = c("keepInteger", "warnIncomplete", "keepNA"). This will lose all formatting and comments, but may be useful in those cases where the saved source is no longer correct. Promises will normally only be encountered by users as a result of lazy-loading (when the default evaluate = TRUE is essential) and after the use of delayedAssign, when evaluate = FALSE might be intended. 146 duplicated Value An invisible character vector containing the names of the objects which were dumped. Note As dump is defined in the base namespace, the base package will be searched before the global envi- ronment unless dump is called from the top level prompt or the envir argument is given explicitly. To avoid the risk of a source attribute becoming out of sync with the actual function definition, the source attribute of a function will never be dumped as an attribute. Currently environments, external pointers, weak references and objects of type S4 are not deparsed in a way that can be sourced. In addition, language objects are deparsed in a simple way whatever the value of control, and this includes not dumping their attributes (which will result in a warning). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also dput, dget, write. save for a more reliable way to save R objects. Examples x <- 1; y <- 1:10 dump(ls(pattern = ’^[xyz]’), "xyz.Rdmped") print(.Last.value) unlink("xyz.Rdmped") duplicated Determine Duplicate Elements Description duplicated() determines which elements of a vector or data frame are duplicates of elements with smaller subscripts, and returns a logical vector indicating which elements (rows) are duplicates. anyDuplicated(.) is a “generalized” more efficient shortcut for any(duplicated(.)). Usage duplicated(x, incomparables = FALSE, ...) ## Default S3 method: duplicated(x, incomparables = FALSE, fromLast = FALSE, ...) duplicated 147 ## S3 method for class ’array’ duplicated(x, incomparables = FALSE, MARGIN = 1, fromLast = FALSE, ...) anyDuplicated(x, incomparables = FALSE, ...) ## Default S3 method: anyDuplicated(x, incomparables = FALSE, fromLast = FALSE, ...) ## S3 method for class ’array’ anyDuplicated(x, incomparables = FALSE, MARGIN = 1, fromLast = FALSE, ...) Arguments x a vector or a data frame or an array or NULL. incomparables a vector of values that cannot be compared. FALSE is a special value, meaning that all values can be compared, and may be the only value accepted for methods other than the default. It will be coerced internally to the same type as x. fromLast logical indicating if duplication should be considered from the reverse side, i.e., the last (or rightmost) of identical elements would correspond to duplicated=FALSE. ... arguments for particular methods. MARGIN the array margin to be held fixed: see apply, and note that MARGIN = 0 maybe useful. Details These are generic functions with methods for vectors (including lists), data frames and arrays (in- cluding matrices). For the default methods, and whenever there are equivalent method definitions for duplicated and anyDuplicated, anyDuplicated(x,...) is a “generalized” shortcut for any(duplicated(x,...)), in the sense that it returns the index i of the first duplicated entry x[i] if there is one, and 0 otherwise. Their behaviours may be different when at least one of duplicated and anyDuplicated has a relevant method. duplicated(x, fromLast=TRUE) is equivalent to but faster than rev(duplicated(rev(x))). The data frame method works by pasting together a character representation of the rows separated by \r, so may be imperfect if the data frame has characters with embedded carriage returns or columns which do not reliably map to characters. The array method calculates for each element of the sub-array specified by MARGIN if the remaining dimensions are identical to those for an earlier (or later, when fromLast=TRUE) element (in row- major order). This would most commonly be used to find duplicated rows (the default) or columns (with MARGIN = 2). Note that MARGIN = 0 returns an array of the same dimensionality attributes as x. Missing values are regarded as equal, but NaN is not equal to NA_real_. Values in incomparables will never be marked as duplicated. This is intended to be used for a fairly small set of values and will not be efficient for a very large set. 148 duplicated When used on a data frame with more than one column, or an array or matrix when comparing dimensions of length greater than one, this tests for identity of character representations. This will catch people who unwisely rely on exact equality of floating-point numbers! Character strings will be compared as byte sequences if any input is marked as "bytes". Value duplicated(): For a vector input, a logical vector of the same length as x. For a data frame, a logical vector with one element for each row. For a matrix or array, and when MARGIN = 0, a logical array with the same dimensions and dimnames. anyDuplicated(): a non-negative integer (of length one). Warning Using this for lists is potentially slow, especially if the elements are not atomic vectors (see vector) or differ only in their attributes. In the worst case it is O(n2). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also unique. Examples x <- c(9:20, 1:5, 3:7, 0:8) ## extract unique elements (xu <- x[!duplicated(x)]) ## similar, same elements but different order: (xu2 <- x[!duplicated(x, fromLast = TRUE)]) ## xu == unique(x) but unique(x) is more efficient stopifnot(identical(xu, unique(x)), identical(xu2, unique(x, fromLast = TRUE))) duplicated(iris)[140:143] duplicated(iris3, MARGIN = c(1, 3)) anyDuplicated(iris) ## 143 anyDuplicated(x) anyDuplicated(x, fromLast = TRUE) dyn.load 149 dyn.load Foreign Function Interface Description Load or unload DLLs (also known as shared objects), and test whether a C function or Fortran subroutine is available. Usage dyn.load(x, local = TRUE, now = TRUE, ...) dyn.unload(x) is.loaded(symbol, PACKAGE = "", type = "") Arguments x a character string giving the pathname to a DLL, also known as a dynamic shared object. (See ‘Details’ for what these terms mean.) local a logical value controlling whether the symbols in the DLL are stored in their own local table and not shared across DLLs, or added to the global symbol table. Whether this has any effect is system-dependent. now a logical controlling whether all symbols are resolved (and relocated) immedi- ately the library is loaded or deferred until they are used. This control is useful for developers testing whether a library is complete and has all the necessary symbols, and for users to ignore missing symbols. Whether this has any effect is system-dependent. ... other arguments for future expansion. symbol a character string giving a symbol name. PACKAGE if supplied, confine the search for the name to the DLL given by this argument (plus the conventional extension, ‘.so’, ‘.sl’, ‘.dll’, . . . ). This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols. Use PACKAGE="base" for symbols linked in to R. This is used in the same way as in .C,.Call,.Fortran and .External functions type The type of symbol to look for: can be any ("", the default), "Fortran","Call" or "External". Details The objects dyn.load loads are called ‘dynamically loadable libraries’ (abbreviated to ‘DLL’ on all platforms except Mac OS X, which unfortunately uses the term for a different sort of sobject. On Unix-alikes they are also called ‘dynamic shared objects’ (‘DSO’), or ‘shared objects’ for short. (The POSIX standards use ‘executable object file’, but no one else does.) 150 dyn.load See ‘See Also’ and the ‘Writing R Extensions’ and ‘R Installation and Administration’ manuals for how to create and install a suitable DLL. Unfortunately a very few platforms (e.g. Compaq Tru64) do not handle the PACKAGE argument correctly, and may incorrectly find symbols linked into R. The additional arguments to dyn.load mirror the different aspects of the mode argument to the dlopen() routine on POSIX systems. They are available so that users can exercise greater control over the loading process for an individual library. In general, the default values are appropriate and you should override them only if there is good reason and you understand the implications. The local argument allows one to control whether the symbols in the DLL being attached are visible to other DLLs. While maintaining the symbols in their own namespace is good practice, the ability to share symbols across related ‘chapters’ is useful in many cases. Additionally, on certain platforms and versions of an operating system, certain libraries must have their symbols loaded globally to successfully resolve all symbols. One should be careful of the potential side-effect of using lazy loading via the now argument as FALSE. If a routine is called that has a missing symbol, the process will terminate immediately. The intended use is for library developers to call with value TRUE to check that all symbols are actually resolved and for regular users to call with FALSE so that missing symbols can be ignored and the available ones can be called. The initial motivation for adding these was to avoid such termination in the _init() routines of the Java virtual machine library. However, symbols loaded locally may not be (read probably) available to other DLLs. Those added to the global table are available to all other elements of the application and so can be shared across two different DLLs. Some (very old) systems do not provide (explicit) support for local/global and lazy/eager symbol resolution. This can be the source of subtle bugs. One can arrange to have warning messages emitted when unsupported options are used. This is done by setting either of the options verbose or warn to be non-zero via the options function. There is a short discussion of these additional arguments with some example code available at http://cm.bell-labs.com/stat/duncan/R/dynload. Value The function dyn.load is used for its side effect which links the specified DLL to the executing R image. Calls to .C,.Call,.Fortran and .External can then be used to execute compiled C functions or Fortran subroutines contained in the library. The return value of dyn.load is an object of class DLLInfo. See getLoadedDLLs for information about this class. The function dyn.unload unlinks the DLL. Note that unloading a DLL and then re-loading a DLL of the same name may or may not work: on Solaris it uses the first version loaded. is.loaded checks if the symbol name is loaded and hence available for use in .C or .Fortran or .Call or .External. It will succeed if any one of the four calling functions would succeed in using the entry point unless type is specified. (See .Fortran for how Fortran symbols are mapped.) Warning Do not use dyn.unload on a DLL loaded by library.dynam: use library.dynam.unload. This is needed for system housekeeping. eapply 151 Note is.loaded requires the name you would give to .C etc and not (as in S) that remapped by defunct functions symbol.C or symbol.For. The creation of DLLs and the runtime linking of them into executing programs is very platform de- pendent. In recent years there has been some simplification in the process because the C subroutine call dlopen has become the POSIX standard for doing this. Under Unix-alikes dyn.load uses the dlopen mechanism and should work on all platforms which support it. On Windows it uses the standard mechanism (LoadLibrary) for loading DLLs. The original code for loading DLLs in Unix-alikes was provided by Heiner Schwarte. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also library.dynam to be used inside a package’s .onLoad initialization. SHLIB for how to create suitable DLLs. .C,.Fortran,.External,.Call. Examples is.loaded("hcass2") #-> probably TRUE, as stats is loaded is.loaded("supsmu") # Fortran entry point in stats is.loaded("supsmu", "stats", "Fortran") is.loaded("PDF", type = "External") eapply Apply a Function Over Values in an Environment Description eapply applies FUN to the named values from an environment and returns the results as a list. The user can request that all named objects are used (normally names that begin with a dot are not). The output is not sorted and no enclosing environments are searched. This is a primitive function. Usage eapply(env, FUN, ..., all.names = FALSE, USE.NAMES = TRUE) 152 eigen Arguments env environment to be used. FUN the function to be applied, found via match.fun. In the case of functions like +, %*%, etc., the function name must be backquoted or quoted. ... optional arguments to FUN. all.names a logical indicating whether to apply the function to all values. USE.NAMES logical indicating whether the resulting list should have names. Value A named (unless USE.NAMES = FALSE) list. Note that the order of the components is arbitrary for hashed environments. See Also environment, lapply. Examples require(stats) env <- new.env(hash = FALSE) # so the order is fixed env$a <- 1:10 env$beta <- exp(-3:3) env$logic <- c(TRUE, FALSE, FALSE, TRUE) # what have we there? utils::ls.str(env) # compute the mean for each list element eapply(env, mean) unlist(eapply(env, mean, USE.NAMES = FALSE)) # median and quartiles for each element (making use of "..." passing): eapply(env, quantile, probs = 1:3/4) eapply(env, quantile) eigen Spectral Decomposition of a Matrix Description Computes eigenvalues and eigenvectors of real (double, integer, logical) or complex matrices. Usage eigen(x, symmetric, only.values = FALSE, EISPACK = FALSE) eigen 153 Arguments x a matrix whose spectral decomposition is to be computed. symmetric if TRUE, the matrix is assumed to be symmetric (or Hermitian if complex) and only its lower triangle (diagonal included) is used. If symmetric is not specified, the matrix is inspected for symmetry. only.values if TRUE, only the eigenvalues are computed and returned, otherwise both eigen- values and eigenvectors are returned. EISPACK logical. Should EISPACK be used (for compatibility with R < 1.7.0)? Details By default eigen uses the LAPACK routines DSYEVR, DGEEV, ZHEEV and ZGEEV whereas eigen(EISPACK = TRUE) provides an interface to the EISPACK routines RS, RG, CH and CG. If symmetric is unspecified, the code attempts to determine if the matrix is symmetric up to plausi- ble numerical inaccuracies. It is faster and surer to set the value yourself. eigen is preferred to eigen(EISPACK = TRUE) for new projects, but its eigenvectors may differ in sign and (in the asymmetric case) in normalization. (They may also differ between methods and between platforms.) Computing the eigenvectors is the slow part for large matrices. Computing the eigendecomposition of a matrix is subject to errors on a real-world computer: the definitive analysis is Wilkinson (1965). All you can hope for is a solution to a problem suitably close to x. So even though a real asymmetric x may have an algebraic solution with repeated real eigenvalues, the computed solution may be of a similar matrix with complex conjugate pairs of eigenvalues. Value The spectral decomposition of x is returned as components of a list with components values a vector containing the p eigenvalues of x, sorted in decreasing order, according to Mod(values) in the asymmetric case when they might be complex (even for real matrices). For real asymmetric matrices the vector will be complex only if complex conjugate pairs of eigenvalues are detected. vectors either a p × p matrix whose columns contain the eigenvectors of x, or NULL if only.values is TRUE. For eigen(, symmetric = FALSE, EISPACK =TRUE) the choice of length of the eigenvectors is not defined by EISPACK. In all other cases the vectors are normalized to unit length. Recall that the eigenvectors are only defined up to a constant: even when the length is specified they are still only defined up to a scalar of modulus one (the sign for real matrices). If r <- eigen(A), and V <- r$vectors; lam <- r$values, then A = VΛV −1 (up to numerical fuzz), where Λ =diag(lam). 154 encodeString References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Smith, B. T, Boyle, J. M., Dongarra, J. J., Garbow, B. S., Ikebe,Y., Klema, V., and Moler, C. B. (1976). Matrix Eigensystems Routines – EISPACK Guide. Springer-Verlag Lecture Notes in Computer Science 6. Anderson. E. and ten others (1999) LAPACK Users’ Guide. Third Edition. SIAM. Available on-line at http://www.netlib.org/lapack/lug/lapack_lug.html. Wilkinson, J. H. (1965) The Algebraic Eigenvalue Problem. Clarendon Press, Oxford. See Also svd, a generalization of eigen; qr, and chol for related decompositions. To compute the determinant of a matrix, the qr decomposition is much more efficient: det. Examples eigen(cbind(c(1,-1),c(-1,1))) eigen(cbind(c(1,-1),c(-1,1)), symmetric = FALSE) # same (different algorithm). eigen(cbind(1,c(1,-1)), only.values = TRUE) eigen(cbind(-1,2:1)) # complex values eigen(print(cbind(c(0,1i), c(-1i,0))))# Hermite ==> real Eigen values ## 3 x 3: eigen(cbind( 1,3:1,1:3)) eigen(cbind(-1,c(1:2,0),0:2)) # complex values encodeString Encode Character Vector as for Printing Description encodeString escapes the strings in a character vector in the same way print.default does, and optionally fits the encoded strings within a field width. Usage encodeString(x, width = 0, quote = "", na.encode = TRUE, justify = c("left", "right", "centre", "none")) encodeString 155 Arguments x A character vector, or an object that can be coerced to one by as.character. width integer: the minimum field width. If NULL or NA, this is taken to be the largest field width needed for any element of x. quote character: quoting character, if any. na.encode logical: should NA strings be encoded? justify character: partial matches are allowed. If padding to the minimum field width is needed, how should spaces be inserted? justify == "none" is equivalent to width = 0, for consistency with format.default. Details This escapes backslash and the control characters ‘\a’ (bell), ‘\b’ (backspace), ‘\f’ (formfeed), ‘\n’ (line feed), ‘\r’ (carriage return), ‘\t’ (tab) and ‘\v’ (vertical tab) as well as any non-printable characters in a single-byte locale, which are printed in octal notation (‘\xyz’ with leading zeroes). Which characters are non-printable depends on the current locale. Windows’ reporting of printable characters is unreliable, so there all other control characters are regarded as non-printable, and all characters with codes 32–255 as printable in a single-byte locale. See print.default for how non-printable characters are handled in multi-byte locales. If quote is a single or double quote any embedded quote of the same type is escaped. Note that justification is of the quoted string, hence spaces are added outside the quotes. Value A character vector of the same length as x, with the same attributes (including names and dimen- sions) but with no class set. Note The default for width is different from format.default, which does similar things for character vectors but without encoding using escapes. See Also print.default Examples x <- "ab\bc\ndef" print(x) cat(x) # interprets escapes cat(encodeString(x), "\n", sep="") # similar to print() factor(x) # makes use of this to print the levels x <- c("a", "ab", "abcde") encodeString(x, width = NA) # left justification encodeString(x, width = NA, justify = "c") 156 Encoding encodeString(x, width = NA, justify = "r") encodeString(x, width = NA, quote = "’", justify = "r") Encoding Read or Set the Declared Encodings for a Character Vector Description Read or set the declared encodings for a character vector. Usage Encoding(x) Encoding(x) <- value enc2native(x) enc2utf8(x) Arguments x A character vector. value A character vector of positive length. Details Character strings in R can be declared to be in "latin1" or "UTF-8" or "bytes". These declara- tions can be read by Encoding, which will return a character vector of values "latin1","UTF-8" "bytes" or "unknown", or set, when value is recycled as needed and other values are silently treated as "unknown". ASCII strings will never be marked with a declared encoding, since their representation is the same in all supported encodings. Strings marked as "bytes" are intended to be non-ASCII strings which should be manipulated as bytes, and never converted to a character encoding. enc2native and enc2utf8 convert elements of character vectors to the native encoding or UTF-8 respectively, taking any marked encoding into account. They are primitive functions, designed to do minimal copying. There are other ways for character strings to acquire a declared encoding apart from explicitly setting it (and these have changed as R has evolved). Functions scan, read.table, readLines, and parse have an encoding argument that is used to declare encodings, iconv declares encodings from its from argument, and console input in suitable locales is also declared. intToUtf8 declares its output as "UTF-8", and output text connections (see textConnection) are marked if running in a suitable locale. Under some circumstances (see its help page) source(encoding=) will mark encodings of character strings it outputs. Most character manipulation functions will set the encoding on output strings if it was declared on the corresponding input. These include chartr, strsplit(useBytes = FALSE), tolower and toupper as well as sub(useBytes = FALSE) and gsub(useBytes = FALSE). Note that such environment 157 functions do not preserve the encoding, but if they know the input encoding and that the string has been successfully re-encoded (to the current encoding or UTF-8), they mark the output. substr does preserve the encoding, and chartr, tolower and toupper preserve UTF-8 encoding on systems with Unicode wide characters. With their fixed and perl options, strsplit, sub and gsub will give a marked UTF-8 result if any of the inputs are UTF-8. paste and sprintf return elements marked as bytes if any of the corresponding inputs is marked as bytes, and otherwise marked as UTF-8 of any of the inputs is marked as UTF-8. match, pmatch, charmatch, duplicated and unique all match in UTF-8 if any of the elements are marked as UTF-8. Value A character vector. Examples ## x is intended to be in latin1 x <- "fa\xE7ile" Encoding(x) Encoding(x) <- "latin1" x xx <- iconv(x, "latin1", "UTF-8") Encoding(c(x, xx)) c(x, xx) Encoding(xx) <- "bytes" xx # will be encoded in hex cat("xx = ", xx, "\n", sep = "") environment Environment Access Description Get, set, test for and create environments. Usage environment(fun = NULL) environment(fun) <- value is.environment(x) .GlobalEnv globalenv() .BaseNamespaceEnv emptyenv() 158 environment baseenv() new.env(hash = TRUE, parent = parent.frame(), size = 29L) parent.env(env) parent.env(env) <- value environmentName(env) env.profile(env) Arguments fun a function, a formula, or NULL, which is the default. value an environment to associate with the function x an arbitrary R object. hash a logical, if TRUE the environment will use a hash table. parent an environment to be used as the enclosure of the environment created. env an environment size an integer specifying the initial size for a hashed environment. An internal de- fault value will be used if size is NA or zero. This argument is ignored if hash is FALSE. Details Environments consist of a frame, or collection of named objects, and a pointer to an enclosing envi- ronment. The most common example is the frame of variables local to a function call; its enclosure is the environment where the function was defined. The enclosing environment is distinguished from the parent frame: the latter (returned by parent.frame) refers to the environment of the caller of a function. Since confusion is so easy, it is best never to use ‘parent’ in connection with an environment (despite the presence of the function parent.env). When get or exists search an environment with the default inherits = TRUE, they look for the variable in the frame, then in the enclosing frame, and so on. The global environment .GlobalEnv, more often known as the user’s workspace, is the first item on the search path. It can also be accessed by globalenv(). On the search path, each item’s enclosure is the next item. The object .BaseNamespaceEnv is the namespace environment for the base package. The environ- ment of the base package itself is available as baseenv(). If one follows the chain of enclosures found by repeatedly calling parent.env from any envi- ronment, eventually one reaches the empty environment emptyenv(), into which nothing may be assigned. The replacement function parent.env<- is extremely dangerous as it can be used to destructively change environments in ways that violate assumptions made by the internal C code. It may be removed in the near future. The replacement form of environment, is.environment, baseenv, emptyenv and globalenv are primitive functions. environment 159 System environments, such as the base, global and empty environments, have names as do the package and namespace environments and those generated by attach(). Other environments can be named by giving a "name" attribute, but this needs to be done with care as environments have unusual copying semantics. Value If fun is a function or a formula then environment(fun) returns the environment associated with that function or formula. If fun is NULL then the current evaluation environment is returned. The replacement form sets the environment of the function or formula fun to the value given. is.environment(obj) returns TRUE if and only if obj is an environment. new.env returns a new (empty) environment with (by default) enclosure the parent frame. parent.env returns the enclosing environment of its argument. parent.env<- sets the enclosing environment of its first argument. environmentName returns a character string, that given when the environment is printed or "" if it is not a named environment. env.profile returns a list with the following components: size the number of chains that can be stored in the hash table, nchains the number of non-empty chains in the table (as reported by HASHPRI), and counts an integer vector giving the length of each chain (zero for empty chains). This function is intended to assess the performance of hashed environments. When env is a non- hashed environment, NULL is returned. See Also For the performance implications of hashing or not, see http://en.wikipedia.org/wiki/Hash_ table. The envir argument of eval, get, and exists. ls may be used to view the objects in an environment, and hence ls.str may be useful for an overview. sys.source can be used to populate an environment. Examples f <- function() "top level function" ##-- all three give the same: environment() environment(f) .GlobalEnv ls(envir=environment(stats::approxfun(1:2,1:2, method="const"))) is.environment(.GlobalEnv) # TRUE e1 <- new.env(parent = baseenv()) # this one has enclosure package:base. e2 <- new.env(parent = e1) assign("a", 3, envir=e1) 160 EnvVar ls(e1) ls(e2) exists("a", envir=e2) # this succeeds by inheritance exists("a", envir=e2, inherits = FALSE) exists("+", envir=e2) # this succeeds by inheritance eh <- new.env(hash = TRUE, size = NA) with(env.profile(eh), stopifnot(size == length(counts))) EnvVar Environment Variables Description Details of some of the environment variables which affect an R session. Details It is impossible to list all the environment variables which can affect an R session: some affect the OS system functions which R uses, and others will affect add-on packages. But here are notes on some of the more important ones. Those that set the defaults for options are consulted only at startup (as are some of the others). DVIPS: The path to dvips. Used at startup to set the default for options("dvipscmd") which used by the deprecated help(help_type="ps"). HOME: The user’s ‘home’ directory. LANGUAGE: Optional. The language(s) to be used for message translations. This is consulted when needed. LC_ALL:(etc) Optional. Use to set various aspects of the locale – see Sys.getlocale. Consulted at startup. MAKEINDEX: The path to makeindex. If unset to a value determined when R was built. Used by the emulation mode of texi2dvi and texi2pdf. R_BATCH: Optional – set in a batch session, that is one started by R CMD BATCH. Most often set to "", so test by something like !is.na(Sys.getenv("R_BATCH", NA)). R_BROWSER: The path to the default browser. Used to set the default value of options("browser"). R_COMPLETION: Optional. If set to FALSE, command-line completion is not used. (Not used by Mac OS GUI.) R_DEFAULT_PACKAGES: A comma-separated list of packages which are to be attached in every ses- sion. See options. R_DOC_DIR: The location of the R‘doc’ directory. Set by R. R_ENVIRON: Optional. The path to the site environment file: see Startup. Consulted at startup. R_GSCMD: Optional. The path to Ghostscript, used by dev2bitmap, bitmap and embedFonts. Con- sulted when those functions are invoked. R_HISTFILE: Optional. The path of the history file: see Startup. Consulted at startup and when the history is saved. EnvVar 161 R_HISTSIZE: Optional. The maximum size of the history file, in lines. Exactly how this is used depends on the interface. For the readline command-line interface it takes effect when the history is saved (by savehistory or at the end of a session). R_HOME: The top-level directory of the R installation: see R.home. Set by R. R_INCLUDE_DIR: The location of the R‘include’ directory. Set by R. R_LIBS: Optional. Used for initial setting of .libPaths. R_LIBS_SITE: Optional. Used for initial setting of .libPaths. R_LIBS_USER: Optional. Used for initial setting of .libPaths. R_PAPERSIZE: Optional. Used to set the default for options("papersize"), e.g. used by pdf and postscript. R_PDFVIEWER: The path to the default PDF viewer. Used by R CMD Rd2pdf. R_PLATFORM: The platform – a string of the form cpu-vendor-os, see R.Version. R_PROFILE: Optional. The path to the site profile file: see Startup. Consulted at startup. R_RD4PDF: Options for pdflatex processing of Rd files. Used by R CMD Rd2pdf. R_SHARE_DIR: The location of the R‘share’ directory. Set by R. R_TEXI2DVICMD: The path to texi2dvi. Defaults to the value of TEXI2DVI, and if that is un- set to a value determined when R was built. Consulted at startup to set the default for options("texi2dvi"), used by texi2dvi and texi2pdf in package tools. R_UNZIPCMD: The path to unzip. Sets the initial value for options("unzip") on a Unix-alike when namespace utils is loaded. R_ZIPCMD: The path to zip. Used by zip and by R CMD INSTALL --build on Windows. TMPDIR, TMP, TEMP: Consulted (in that order) when setting the temporary directory for the session: see tempdir. TMPDIR is also used by some of the utilities see the help for build. TZ: Optional. The current timezone. See Sys.timezone for the system-specific formats. Consulted as needed. no_proxy, http_proxy, ftp_proxy:(and more). Optional. Settings for download.file: see its help for further details. Unix-specific Some variables set on Unix-alikes, and not (in general) on Windows. DISPLAY: Optional: used by X11, Tk (in package tcltk), the data editor and various packages. EDITOR: The path to the default editor: sets the default for options("editor") when namespace utils is loaded. PAGER: The path to the pager with the default setting of options("pager"). The default value is chosen at configuration, usually as the path to less. R_PRINTCMD: Sets the default for options("printcmd"), which sets the default print command to be used by postscript. See Also Sys.getenv and Sys.setenv to read and set environmental variables in an R session. 162 eval eval Evaluate an (Unevaluated) Expression Description Evaluate an R expression in a specified environment. Usage eval(expr, envir = parent.frame(), enclos = if(is.list(envir) || is.pairlist(envir)) parent.frame() else baseenv()) evalq(expr, envir, enclos) eval.parent(expr, n = 1) local(expr, envir = new.env()) Arguments expr an object to be evaluated. See ‘Details’. envir the environment in which expr is to be evaluated. May also be NULL, a list, a data frame, a pairlist or an integer as specified to sys.call. enclos Relevant when envir is a (pair)list or a data frame. Specifies the enclosure, i.e., where R looks for objects not found in envir. This can be NULL (interpreted as the base package environment, baseenv()) or an environment. n number of parent generations to go back Details eval evaluates the expr argument in the environment specified by envir and returns the computed value. If envir is not specified, then the default is parent.frame() (the environment where the call to eval was made). Objects to be evaluated can be of types call or expression or name (when the name is looked up in the current scope and its binding is evaluated), a promise or any of the basic types such as vectors, functions and environments (which are returned unchanged). The evalq form is equivalent to eval(quote(expr), ...). eval evaluates its first argument in the current scope before passing it to the evaluator: evalq avoids this. eval.parent(expr, n) is a shorthand for eval(expr, parent.frame(n)). If envir is a list (such as a data frame) or pairlist, it is copied into a temporary environment (with enclosure enclos), and the temporary environment is used for evaluation. So if expr changes any of the components named in the (pair)list, the changes are lost. If envir is NULL it is interpreted as an empty list so no values could be found in envir and look-up goes directly to enclos. local evaluates an expression in a local environment. It is equivalent to evalq except that its default argument creates a new, empty environment. This is useful to create anonymous recursive functions and as a kind of limited namespace feature since variables defined in the environment are not visible from the outside. eval 163 Value The result of evaluating the object: for an expression vector this is the result of evaluating the last element. Note Due to the difference in scoping rules, there are some differences between R and S in this area. In particular, the default enclosure in S is the global environment. When evaluating expressions in a data frame that has been passed as an argument to a func- tion, the relevant enclosure is often the caller’s environment, i.e., one needs eval(x, data, parent.frame()). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (eval only.) See Also expression, quote, sys.frame, parent.frame, environment. Further, force to force evaluation, typically of function arguments. Examples eval(2 ^ 2 ^ 3) mEx <- expression(2^2^3); mEx; 1 + eval(mEx) eval({ xx <- pi; xx^2}) ; xx a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, list(a=1)), list(b=5)) # == 10 a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, -1), list(b=5)) # == 12 ev <- function() { e1 <- parent.frame() ## Evaluate a in e1 aa <- eval(expression(a),e1) ## evaluate the expression bound to a in e1 a <- expression(x+y) list(aa = aa, eval = eval(a, e1)) } tst.ev <- function(a = 7) { x <- pi; y <- 1; ev() } tst.ev()#-> aa : 7, eval : 4.14 a <- list(a=3, b=4) with(a, a <- 5) # alters the copy of a from the list, discarded. ## ## Example of evalq() ## N <- 3 164 exists env <- new.env() assign("N", 27, envir=env) ## this version changes the visible copy of N only, since the argument ## passed to eval is ’4’. eval(N <- 4, env) N get("N", envir=env) ## this version does the assignment in env, and changes N only there. evalq(N <- 5, env) N get("N", envir=env) ## ## Uses of local() ## # Mutually recursive. # gg gets value of last assignment, an anonymous version of f. gg <- local({ k <- function(y)f(y) f <- function(x) if(x) x*k(x-1) else 1 }) gg(10) sapply(1:5, gg) # Nesting locals: a is private storage accessible to k gg <- local({ k <- local({ a <- 1 function(y){print(a <<- a+1);f(y)} }) f <- function(x) if(x) x*k(x-1) else 1 }) sapply(1:5, gg) ls(envir=environment(gg)) ls(envir=environment(get("k", envir=environment(gg)))) exists Is an Object Defined? Description Look for an R object of the given name. Usage exists(x, where = -1, envir = , frame, mode = "any", inherits = TRUE) exists 165 Arguments x a variable name (given as a character string). where where to look for the object (see the details section); if omitted, the function will search as if the name of the object appeared unquoted in an expression. envir an alternative way to specify an environment to look in, but it is usually simpler to just use the where argument. frame a frame in the calling list. Equivalent to giving where as sys.frame(frame). mode the mode or type of object sought: see the ‘Details’ section. inherits should the enclosing frames of the environment be searched? Details The where argument can specify the environment in which to look for the object in any of several ways: as an integer (the position in the search list); as the character string name of an element in the search list; or as an environment (including using sys.frame to access the currently active function calls). The envir argument is an alternative way to specify an environment, but is primarily there for back compatibility. This function looks to see if the name x has a value bound to it in the specified environment. If inherits is TRUE and a value is not found for x in the specified environment, the enclosing frames of the environment are searched until the name x is encountered. See environment and the ‘R Language Definition’ manual for details about the structure of environments and their enclosures. Warning: inherits = TRUE is the default behaviour for R but not for S. If mode is specified then only objects of that type are sought. The mode may specify one of the collections "numeric" and "function" (see mode): any member of the collection will suffice. (This is true even if a member of a collection is specified, so for example mode="special" will seek any type of function.) Value Logical, true if and only if an object of the correct name and mode is found. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also get. For quite a different kind of “existence” checking, namely if function arguments were speci- fied, missing. Examples ## Define a substitute function if necessary: if(!exists("some.fun", mode="function")) some.fun <- function(x) { cat("some.fun(x)\n"); x } search() 166 expand.grid exists("ls", 2) # true even though ls is in pos=3 exists("ls", 2, inherits = FALSE) # false expand.grid Create a Data Frame from All Combinations of Factors Description Create a data frame from all combinations of the supplied vectors or factors. See the description of the return value for precise details of the way this is done. Usage expand.grid(..., KEEP.OUT.ATTRS = TRUE, stringsAsFactors = TRUE) Arguments ... vectors, factors or a list containing these. KEEP.OUT.ATTRS a logical indicating the "out.attrs" attribute (see below) should be computed and returned. stringsAsFactors logical specifying if character vectors are converted to factors. Value A data frame containing one row for each combination of the supplied factors. The first factors vary fastest. The columns are labelled by the factors if these are supplied as named arguments or named components of a list. The row names are ‘automatic’. Attribute "out.attrs" is a list which gives the dimension and dimnames for use by predict meth- ods. Note Conversion to a factor is done with levels in the order they occur in the character vectors (and not alphabetically, as is most common when converting to factors). References Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. See Also combn (package utils) for the generation of all combinations of n elements, taken m at a time. expression 167 Examples require(utils) expand.grid(height = seq(60, 80, 5), weight = seq(100, 300, 50), sex = c("Male","Female")) x <- seq(0,10, length.out=100) y <- seq(-1,1, length.out=20) d1 <- expand.grid(x=x, y=y) d2 <- expand.grid(x=x, y=y, KEEP.OUT.ATTRS = FALSE) object.size(d1) - object.size(d2) ##-> 5992 or 8832 (on 32- / 64-bit platform) expression Unevaluated Expressions Description Creates or tests for objects of mode "expression". Usage expression(...) is.expression(x) as.expression(x, ...) Arguments ... expression:R objects, typically calls, symbols or constants. as.expression: arguments to be passed to methods. x an arbitrary R object. Details ‘Expression’ here is not being used in its colloquial sense, that of mathematical expressions. Those are calls (see call) in R, and an R expression vector is a list of calls, symbols etc, for example as returned by parse. As an object of mode "expression" is a list, it can be subsetted by [,[[ or $, the latter two extracting individual calls etc. The replacement forms of these operators can be used to replace or delete elements. expression and is.expression are primitive functions. expression is ‘special’: it does not evaluate its arguments. 168 Extract Value expression returns a vector of type "expression" containing its arguments (unevaluated). is.expression returns TRUE if expr is an expression object and FALSE otherwise. as.expression attempts to coerce its argument into an expression object. It is generic, and only the default method is described here. (The default method calls as.vector(type="expression") and so may dispatch methods for as.vector.) NULL, calls, symbols (see as.symbol) and pairlists are returned as the element of a length-one expression vector. Atomic vectors are placed element-by- element into an expression vector (without using any names): lists are changed type to an expression vector (keeping all attributes). Other types are not currently supported. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also call, eval, function. Further, text and legend for plotting mathematical expressions. Examples length(ex1 <- expression(1+ 0:9))# 1 ex1 eval(ex1)# 1:10 length(ex3 <- expression(u,v, 1+ 0:9))# 3 mode(ex3 [3]) # expression mode(ex3[[3]])# call rm(ex3) Extract Extract or Replace Parts of an Object Description Operators acting on vectors, matrices, arrays and lists to extract or replace parts. Usage x[i] x[i, j, ... , drop = TRUE] x[[i, exact = TRUE]] x[[i, j, ..., exact = TRUE]] x$name getElement(object, name) x[i] <- value Extract 169 x[i, j, ...] <- value x[[i]] <- value x$i <- value Arguments x, object object from which to extract element(s) or in which to replace element(s). i, j, ... indices specifying elements to extract or replace. Indices are numeric or character vectors or empty (missing) or NULL. Numeric values are coerced to integer as by as.integer (and hence truncated towards zero). Character vectors will be matched to the names of the object (or for matrices/arrays, the dimnames): see ‘Character indices’ below for further details. For [-indexing only: i, j,... can be logical vectors, indicating elements/slices to select. Such vectors are recycled if necessary to match the corresponding extent. i, j,... can also be negative integers, indicating elements/slices to leave out of the selection. When indexing arrays by [ a single argument i can be a matrix with as many columns as there are dimensions of x; the result is then a vector with elements corresponding to the sets of indices in each row of i. An index value of NULL is treated as if it were integer(0). name A literal character string or a name (possibly backtick quoted). For extraction, this is normally (see under ‘Environments’) partially matched to the names of the object. drop For matrices and arrays. If TRUE the result is coerced to the lowest possible dimension (see the examples). This only works for extracting elements, not for the replacement. See drop for further details. exact Controls possible partial matching of [[ when extracting by a character vec- tor (for most objects, but see under ‘Environments’). The default is no partial matching. Value NA allows partial matching but issues a warning when it occurs. Value FALSE allows partial matching without any warning. value typically an array-like R object of a similar class as x. Details These operators are generic. You can write methods to handle indexing of specific classes of objects, see InternalMethods as well as [.data.frame and [.factor. The descriptions here apply only to the default methods. Note that separate methods are required for the replacement functions [<-, [[<- and $<- for use when indexing occurs on the assignment side of an expression. The most important distinction between [,[[ and $ is that the [ can select more than one element whereas the other two select a single element. The default methods work somewhat differently for atomic vectors, matrices/arrays and for recur- sive (list-like, see is.recursive) objects. $ is only valid for recursive objects, and is only discussed in the section below on recursive objects. Its use on non-recursive objects was deprecated in R 2.5.0 and removed in R 2.7.0. Subsetting (except by an empty index) will drop all attributes except names, dim and dimnames. 170 Extract 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 subassignment) then that part of x is set to the value of the right hand side of the assignment. In this case no partial matching of character indices is done, and the left-hand-side is coerced as needed to accept the values. Attributes are preserved (although names, dim and dimnames will be adjusted suitably). Subassignment is done sequentially, so if an index is specified more than once the latest assigned value for an index will result. It is an error to apply any of these operators to an object which is not subsettable (e.g. a function). Atomic vectors The usual form of indexing is "["."[[" can be used to select a single element dropping names, whereas "[" keeps them, e.g., in c(abc = 123)[1]. The index object i can be numeric, logical, character or empty. Indexing by factors is allowed and is equivalent to indexing by the numeric codes (see factor) and not by the character values which are printed (for which use [as.character(i)]). An empty index selects all values: this is most often used to replace all the entries but keep the attributes. Matrices and arrays 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 x is one-dimensional when it will be a one-dimensional array. The most common form of indexing a k-dimensional array is to specify k indices to [. 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 drop applies to this form of indexing. 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. NA and zero values are allowed: rows of an index matrix containing a zero are ignored, whereas rows containing an NA produce an NA in the result. Indexing via a character matrix with one column per dimensions is also supported if the array has dimension names. As with numeric matrix indexing, each row of the index matrix selects a single element of the array. Indices are matched against the appropriate dimension names. NA is allowed and will produce an NA in the result. Unmatched indices as well as the empty string ("") are not allowed and will result in an error. A vector obtained by matrix indexing will be unnamed unless x is one-dimensional when the row names (if any) will be indexed to provide names for the result. Recursive (list-like) objects Indexing by [ is similar to atomic vectors and selects a list of the specified element(s). Both [[ and $ select a single element of the list. The main difference is that $ does not allow computed indices, whereas [[ does. x$name is equivalent to x[["name", exact = FALSE]]. Also, the partial matching behavior of [[ can be controlled using the exact argument. Extract 171 getElement(x, name) is a version of x[[name, exact = TRUE]] which for formally classed (S4) objects returns slot(x, name), hence providing access to even more general list-like objects. [ and [[ are sometimes applied to other recursive objects such as calls and expressions. Pairlists are coerced to lists for extraction by [, but all three operators can be used for replacement. [[ can be applied recursively to lists, so that if the single index i is a vector of length p, alist[[i]] is equivalent to alist[[i1]]...[[ip]] providing all but the final indexing results in a list. Note that in all three kinds of replacement, a value of NULL deletes the corresponding item of the list. To set entries to NULL, you need x[i] <- list(NULL). When $<- is applied to a NULL x, it first coerces x to list(). This is what also happens with [[<- if the replacement value value is of length greater than one: if value has length 1 or 0, x is first coerced to a zero-length vector of the type of value. Environments Both $ and [[ can be applied to environments. Only character indices are allowed and no partial matching is done. The semantics of these operations are those of get(i, env=x, inherits=FALSE). If no match is found then NULL is returned. The replacement versions, $<- and [[<-, can also be used. Again, only character arguments are allowed. The semantics in this case are those of assign(i, value, env=x, inherits=FALSE). Such an assignment will either create a new binding or change the existing binding in x. NAs in indexing When extracting, a numerical, logical or character NA index picks an unknown element and so returns NA in the corresponding element of a logical, integer, numeric, complex or character result, and NULL for a list. (It returns 00 for a raw result.] When replacing (that is using indexing on the lhs of an assignment) NA 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). Argument matching 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 m[j=2,i=1] is equivalent to m[2,1] and not to m[1,2]. This may not be true for methods defined for them; for example it is not true for the data.frame methods described in [.data.frame which warn if i or j is named and have undocumented be- haviour in that case. To avoid confusion, do not name index arguments (but drop and exact must be named). S4 methods These operators are also implicit S4 generics, but as primitives, S4 methods will be dispatched only on S4 objects x. The implicit generics for the $ and $<- operators do not have name in their signature because the grammar only allows symbols or string constants for the name argument. 172 Extract Character indices Character indices can in some circumstances be partially matched (see pmatch) to the names or dimnames of the object being subsetted (but never for subassignment). Unlike S (Becker et al p. 358)), R has never used partial matching when extracting by [, and as from R 2.7.0 partial matching is not by default used by [[ (see argument exact). Thus the default behaviour is to use partial matching only when extracting from recursive objects (except environments) by $. Even in that case, warnings can be switched on by options(warnPartialMatchAttr = TRUE). Neither empty ("") nor NA indices match any names, not even empty nor missing names. If any object has no names or appropriate dimnames, they are taken as all "" and so match nothing. Note The documented behaviour of S is that an NA replacement index ‘goes nowhere’ but uses up an element of value (Becker et al p. 359). However, that has not been true of other implementations. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also names for details of matching to names, and pmatch for partial matching. list, array, matrix. [.data.frame and [.factor for the behaviour when applied to data.frame and factors. Syntax for operator precedence, and the R Language reference manual about indexing details. Examples x <- 1:12 m <- matrix(1:6, nrow=2, dimnames=list(c("a", "b"), LETTERS[1:3])) li <- list(pi=pi, e = exp(1)) x[10] # the tenth element of x x <- 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 numeric index ci <- cbind(c("a", "b", "a"), c("A", "C", "B")) m[ci] # matrix character index m <- m[,-1] # delete the first column of m li[[1]] # the first element of list li y <- 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 <- 3.999999999) # "4" is printed Extract.data.frame 173 (1:5)[i] # 3 ## named atomic vectors, compare "[" and "[[" : nx <- c(Abc = 123, pi = pi) nx[1] ; nx["pi"] # keeps names, whereas "[[" does not: nx[[1]] ; nx[["pi"]] ## recursive indexing into lists z <- 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")]] <- "new" unlist(z) ## check $ and [[ for environments e1 <- new.env() e1$a <- 10 e1[["a"]] e1[["b"]] <- 20 e1$b ls(e1) Extract.data.frame Extract or Replace Parts of a Data Frame Description Extract or replace subsets of data frames. Usage ## S3 method for class ’data.frame’ x[i, j, drop = ] ## S3 replacement method for class ’data.frame’ x[i, j] <- value ## S3 method for class ’data.frame’ x[[..., exact = TRUE]] ## S3 replacement method for class ’data.frame’ x[[i, j]] <- value ## S3 replacement method for class ’data.frame’ x$name <- value Arguments x data frame. i, j, ... elements to extract or replace. For [ and [[, these are numeric or character or, for [ only, empty. Numeric values are coerced to integer as if by as.integer. For replacement by [, a logical matrix is allowed. 174 Extract.data.frame name A literal character string or a name (possibly backtick quoted). drop logical. If TRUE the result is coerced to the lowest possible dimension. The default is to drop if only one column is left, but not to drop if only one row is left. value A suitable replacement value: it will be repeated a whole number of times if necessary and it may be coerced: see the Coercion section. If NULL, deletes the column if a single column is selected. exact logical: see [, and applies to column names. Details Data frames can be indexed in several modes. When [ and [[ are used with a single index (x[i] or x[[i]]), they index the data frame as if it were a list. In this usage a drop argument is ignored, with a warning. Note that there is no data.frame method for $, so x$name uses the default method which treats x as a list. There is a replacement method which checks value for the correct number of rows, and replicates it if necessary. When [ and [[ are used with two indices (x[i, j] and x[[i, j]]) they act like indexing a matrix: [[ can only be used to select one element. Note that for each selected column, xj say, typically (if it is not matrix-like), the resulting column will be xj[i], and hence rely on the corresponding [ method, see the examples section. If [ returns a data frame it will have unique (and non-missing) row names, if necessary transform- ing the row names using make.unique. Similarly, if columns are selected column names will be transformed to be unique if necessary (e.g. if columns are selected more than once, or if more than one column of a given name is selected if the data frame has duplicate column names). When drop = TRUE, this is applied to the subsetting of any matrices contained in the data frame as well as to the data frame itself. The replacement methods can be used to add whole column(s) by specifying non-existent col- umn(s), in which case the column(s) are added at the right-hand edge of the data frame and numer- ical indices must be contiguous to existing indices. On the other hand, rows can be added at any row after the current last row, and the columns will be in-filled with missing values. Missing values in the indices are not allowed for replacement. For [ the replacement value can be a list: each element of the list is used to replace (part of) one column, recycling the list as necessary. If columns specified by number are created, the names (if any) of the corresponding list elements are used to name the columns. If the replacement is not selecting rows, list values can contain NULL elements which will cause the corresponding columns to be deleted. (See the Examples.) Matrix indexing (x[i] with a logical or a 2-column integer matrix i) using [ is not recommended, and barely supported. For extraction, x is first coerced to a matrix. For replacement, a logical matrix (only) can be used to select the elements to be replaced in the same way as for a matrix. Both [ and [[ extraction methods partially match row names. By default neither partially match column names, but [[ will unless exact=TRUE. If you want to do exact matching on row names use match as in the examples. Extract.data.frame 175 Value For [ a data frame, list or a single column (the latter two only when dimensions have been dropped). If matrix indexing is used for extraction a matrix results. If the result would be a data frame an error results if undefined columns are selected (as there is no general concept of a ’missing’ column in a data frame). Otherwise if a single column is selected and this is undefined the result is NULL. For [[ a column of the data frame or NULL (extraction with one index) or a length-one vector (extraction with two indices). For $, a column of the data frame (or NULL). For [<-,[[<- and $<-, a data frame. Coercion The story over when replacement values are coerced is a complicated one, and one that has changed during R’s development. This section is a guide only. When [ and [[ are used to add or replace a whole column, no coercion takes place but value will be replicated (by calling the generic function rep) to the right length if an exact number of repeats can be used. When [ is used with a logical matrix, each value is coerced to the type of the column into which it is to be placed. When [ and [[ are used with two indices, the column will be coerced as necessary to accommodate the value. Note that when the replacement value is an array (including a matrix) it is not treated as a series of columns (as data.frame and as.data.frame do) but inserted as a single column. Warning The default behaviour when only one row is left is equivalent to specifying drop = FALSE. To drop from a data frame to a list, drop = TRUE has to be specified explicitly. Arguments other than drop and exact should not be named: there is a warning if they are and the behaviour differs from the description here. See Also subset which is often easier for extraction, data.frame, Extract. Examples sw <- swiss[1:5, 1:4] # select a manageable subset sw[1:3] # select columns sw[, 1:3] # same sw[4:5, 1:3] # select rows and columns sw[1] # a one-column data frame sw[, 1, drop = FALSE] # the same sw[, 1] # a (unnamed) vector sw[[1]] # the same 176 Extract.factor sw[1,] # a one-row data frame sw[1,, drop=TRUE] # a list sw["C", ] # partially matches sw[match("C", row.names(sw)), ] # no exact match try(sw[, "Ferti"]) # column names must match exactly swiss[ c(1, 1:2), ] # duplicate row, unique row names are created sw[sw <= 6] <- 6 # logical matrix indexing sw ## adding a column sw["new1"] <- LETTERS[1:5] # adds a character column sw[["new2"]] <- letters[1:5] # ditto sw[, "new3"] <- LETTERS[1:5] # ditto sw$new4 <- 1:5 sapply(sw, class) sw$new4 <- NULL # delete the column sw sw[6:8] <- list(letters[10:14], NULL, aa=1:5) # update col. 6, delete 7, append sw ## matrices in a data frame A <- data.frame(x=1:3, y=I(matrix(4:6)), z=I(matrix(letters[1:9],3,3))) A[1:3, "y"] # a matrix A[1:3, "z"] # a matrix A[, "y"] # a matrix ## keeping special attributes: use a class with a ## "as.data.frame" and "[" method: as.data.frame.avector <- as.data.frame.vector ‘[.avector‘ <- function(x,i,...) { r <- NextMethod("[") mostattributes(r) <- attributes(x) r } d <- data.frame(i= 0:7, f= gl(2,4), u= structure(11:18, unit = "kg", class="avector")) str(d[2:4, -1]) # ’u’ keeps its "unit" Extract.factor Extract or Replace Parts of a Factor Extract.factor 177 Description Extract or replace subsets of factors. Usage ## S3 method for class ’factor’ x[..., drop = FALSE] ## S3 method for class ’factor’ x[[...]] ## S3 replacement method for class ’factor’ x[...] <- value ## S3 replacement method for class ’factor’ x[[...]] <- value Arguments x a factor ... a specification of indices – see Extract. drop logical. If true, unused levels are dropped. value character: a set of levels. Factor values are coerced to character. Details When unused levels are dropped the ordering of the remaining levels is preserved. If value is not in levels(x), a missing value is assigned with a warning. Any contrasts assigned to the factor are preserved unless drop=TRUE. The [[ method supports argument exact. Value A factor with the same set of levels as x unless drop=TRUE. See Also factor, Extract. Examples ## following example(factor) (ff <- factor(substring("statistics", 1:10, 1:10), levels=letters)) ff[, drop=TRUE] factor(letters[7:10])[2:3, drop = TRUE] 178 Extremes Extremes Maxima and Minima Description Returns the (parallel) maxima and minima of the input values. Usage max(..., na.rm = FALSE) min(..., na.rm = FALSE) pmax(..., na.rm = FALSE) pmin(..., na.rm = FALSE) pmax.int(..., na.rm = FALSE) pmin.int(..., na.rm = FALSE) Arguments ... numeric or character arguments (see Note). na.rm a logical indicating whether missing values should be removed. Details max and min return the maximum or minimum of all the values present in their arguments, as integer if all are logical or integer, as double if all are numeric, and character otherwise. If na.rm is FALSE an NA value in any of the arguments will cause a value of NA to be returned, otherwise NA values are ignored. The minimum and maximum of a numeric empty set are +Inf and -Inf (in this order!) which ensures transitivity, e.g., min(x1, min(x2)) == min(x1, x2). For numeric x max(x) == -Inf and min(x) == +Inf whenever length(x) == 0 (after removing missing values if requested). However, pmax and pmin return NA if all the parallel elements are NA even for na.rm = TRUE. pmax and pmin take one or more vectors (or matrices) as arguments and return a single vector giving the ‘parallel’ maxima (or minima) of the vectors. The first element of the result is the maximum (minimum) of the first elements of all the arguments, the second element of the result is the maximum (minimum) of the second elements of all the arguments and so on. Shorter inputs (of non-zero length) are recycled if necessary. Attributes (see attributes: such as names or dim) are copied from the first argument (if applicable). pmax.int and pmin.int are faster internal versions only used when all arguments are atomic vec- tors and there are no classes: they drop all attributes. (Note that all versions fail for raw and complex vectors since these have no ordering.) max and min are generic functions: methods can be defined for them individually or via the Summary group generic. For this to work properly, the arguments ... should be unnamed, and dispatch is on the first argument. Extremes 179 By definition the min/max of a numeric vector containing an NaN is NaN, except that the min/max of any vector containing an NA is NA even if it also contains an NaN. Note that max(NA, Inf) == NA even though the maximum would be Inf whatever the missing value actually is. Character versions are sorted lexicographically, and this depends on the collating sequence of the locale in use: the help for ‘Comparison’ gives details. The max/min of an empty character vector is defined to be character NA. (One could argue that as "" is the smallest character element, the maximum should be "", but there is no obvious candidate for the minimum.) Value For min or max, a length-one vector. For pmin or pmax, a vector of length the longest of the input vectors. The type of the result will be that of the highest of the inputs in the hierarchy integer < real < character. For min and max if there are only numeric inputs and all are empty (after possible removal of NAs), the result is double (Inf or -Inf). S4 methods max and min are part of the S4 Summary group generic. Methods for them must use the signature x, ..., na.rm. Note ‘Numeric’ arguments are vectors of type integer and numeric, and logical (coerced to integer). For historical reasons, NULL is accepted as equivalent to integer(0). pmax and pmin will also work on classed objects with appropriate methods for comparison, is.na and rep (if recycling of arguments is needed). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also range (both min and max) and which.min (which.max) for the arg min, i.e., the location where an extreme value occurs. ‘plotmath’ for the use of min in plot annotation. Examples require(stats); require(graphics) min(5:1, pi) #-> one number pmin(5:1, pi) #-> 5 numbers x <- sort(rnorm(100)); cH <- 1.35 pmin(cH, quantile(x)) # no names pmin(quantile(x), cH) # has names 180 factor plot(x, pmin(cH, pmax(-cH, x)), type=’b’, main= "Huber’s function") factor Factors Description The function factor is used to encode a vector as a factor (the terms ‘category’ and ‘enumerated type’ are also used for factors). If argument ordered is TRUE, the factor levels are assumed to be ordered. For compatibility with S there is also a function ordered. is.factor, is.ordered, as.factor and as.ordered are the membership and coercion functions for these classes. Usage factor(x = character(), levels, labels = levels, exclude = NA, ordered = is.ordered(x)) ordered(x, ...) is.factor(x) is.ordered(x) as.factor(x) as.ordered(x) addNA(x, ifany=FALSE) Arguments x a vector of data, usually taking a small number of distinct values. levels an optional vector of the values that x might have taken. The default is the unique set of values taken by as.character(x), sorted into increasing order of x. Note that this set can be smaller than sort(unique(x)). labels either an optional vector of labels for the levels (in the same order as levels after removing those in exclude), or a character string of length 1. exclude a vector of values to be excluded when forming the set of levels. This should be of the same type as x, and will be coerced if necessary. ordered logical flag to determine if the levels should be regarded as ordered (in the order given). ... (in ordered(.)): any of the above, apart from ordered itself. ifany (in addNA): Only add an NA level if it is used, i.e. if any(is.na(x)). factor 181 Details The type of the vector x is not restricted; it only must have an as.character method and be sortable (by sort.list). Ordered factors differ from factors only in their class, but methods and the model-fitting functions treat the two classes quite differently. The encoding of the vector happens as follows. First all the values in exclude are removed from levels. If x[i] equals levels[j], then the i-th element of the result is j. If no match is found for x[i] in levels, then the i-th element of the result is set to NA. Normally the ‘levels’ used as an attribute of the result are the reduced set of levels after removing those in exclude, but this can be altered by supplying labels. This should either be a set of new labels for the levels, or a character string, in which case the levels are that character string with a sequence number appended. factor(x, exclude=NULL) applied to a factor is a no-operation unless there are unused levels: in that case, a factor with the reduced level set is returned. If exclude is used it should also be a factor with the same level set as x or a set of codes for the levels to be excluded. The codes of a factor may contain NA. For a numeric x, set exclude=NULL to make NA an extra level (prints as ); by default, this is the last level. If NA is a level, the way to set a code to be missing (as opposed to the code of the missing level) is to use is.na on the left-hand-side of an assignment (as in is.na(f)[i] <- TRUE; indexing inside is.na does not work). Under those circumstances missing values are currently printed as , i.e., identical to entries of level NA. is.factor is generic: you can write methods to handle specific classes of objects, see Internal- Methods. Value factor returns an object of class "factor" which has a set of integer codes the length of x with a "levels" attribute of mode character and unique (!anyDuplicated(.)) entries. If argument ordered is true (or ordered() is used) the result has class c("ordered", "factor"). Applying factor to an ordered or unordered factor returns a factor (of the same type) with just the levels which occur: see also [.factor for a more transparent way to achieve this. is.factor returns TRUE or FALSE depending on whether its argument is of type factor or not. Corre- spondingly, is.ordered returns TRUE when its argument is an ordered factor and FALSE otherwise. as.factor coerces its argument to a factor. It is an abbreviated form of factor. as.ordered(x) returns x if this is ordered, and ordered(x) otherwise. addNA modifies a factor by turning NA into an extra level (so that NA values are counted in tables, for instance). Warning The interpretation of a factor depends on both the codes and the "levels" attribute. Be careful only to compare factors with the same set of levels (in the same order). In particular, as.numeric applied to a factor is meaningless, and may happen by implicit coercion. To transform a factor f to approximately its original numeric values, as.numeric(levels(f))[f] is recommended and slightly more efficient than as.numeric(as.character(f)). 182 factor The levels of a factor are by default sorted, but the sort order may well depend on the locale at the time of creation, and should not be assumed to be ASCII. There are some anomalies associated with factors that have NA as a level. It is suggested to use them sparingly, e.g., only for tabulation purposes. Comparison operators and group generic methods There are "factor" and "ordered" methods for the group generic Ops which provide methods for the Comparison operators, and for the min,max, and range generics in Summary of "ordered". (The rest of the groups and the Math group generate an error as they are not meaningful for factors.) Only == and != can be used for factors: a factor can only be compared to another factor with an identical set of levels (not necessarily in the same ordering) or to a character vector. Ordered factors are compared in the same way, but the general dispatch mechanism precludes comparing ordered and unordered factors. All the comparison operators are available for ordered factors. Collation is done by the levels of the operands: if both operands are ordered factors they must have the same level set. Note In earlier versions of R, storing character data as a factor was more space efficient if there is even a small proportion of repeats. However, identical character strings share storage, so the difference is now small in most cases. (Integer values are stored in 4 bytes whereas each reference to a character string needs a pointer of 4 or 8 bytes.) References Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. See Also [.factor for subsetting of factors. gl for construction of balanced factors and C for factors with specified contrasts. levels and nlevels for accessing the levels, and unclass to get integer codes. Examples (ff <- factor(substring("statistics", 1:10, 1:10), levels=letters)) as.integer(ff) # the internal codes (f. <- factor(ff))# drops the levels that do not occur ff[, drop=TRUE] # the same, more transparently factor(letters[1:20], labels="letter") class(ordered(4:1)) # "ordered", inheriting from "factor" z <- factor(LETTERS[3:1], ordered = TRUE) ## and "relational" methods work: stopifnot(sort(z)[c(1,3)] == range(z), min(z) < max(z)) file.access 183 ## suppose you want "NA" as a level, and to allow missing values. (x <- factor(c(1, 2, NA), exclude = NULL)) is.na(x)[2] <- TRUE x # [1] 1 is.na(x) # [1] FALSE TRUE FALSE ## Using addNA() Month <- airquality$Month table(addNA(Month)) table(addNA(Month, ifany=TRUE)) file.access Ascertain File Accessibility Description Utility function to access information about files on the user’s file systems. Usage file.access(names, mode = 0) Arguments names character vector containing file names. Tilde-expansion will be done: see path.expand. mode integer specifying access mode required: see ‘Details’. Details The mode value can be the exclusive or of the following values 0 test for existence. 1 test for execute permission. 2 test for write permission. 4 test for read permission. Permission will be computed for real user ID and real group ID (rather than the effective IDs). Please note that it is not a good idea to use this function to test before trying to open a file. On a multi-tasking system, it is possible that the accessibility of a file will change between the time you call file.access() and the time you try to open the file. It is better to wrap file open attempts in try. Value An integer vector with values 0 for success and -1 for failure. 184 file.choose Note This is intended as a replacement for the S-PLUS function access, a wrapper for the C function of the same name, which explains the return value encoding. Note that the return value is false for success. See Also file.info for more details on permissions, Sys.chmod to change permissions, and try for a ‘test it and see’ approach. file_test for shell-style file tests. Examples fa <- file.access(dir(".")) table(fa) # count successes & failures file.choose Choose a File Interactively Description Choose a file interactively. Usage file.choose(new = FALSE) Arguments new Logical: choose the style of dialog box presented to the user: at present only new = FALSE is used. Value A character vector of length one giving the file path. See Also list.files for non-interactive selection. file.info 185 file.info Extract File Information Description Utility function to extract information about files on the user’s file systems. Usage file.info(...) Arguments ... character vectors containing file paths. Tilde-expansion is done: see path.expand. Details What constitutes a ‘file’ is OS-dependent but includes directories. (However, directory names must not include a trailing backslash or slash on Windows.) The file ‘mode’ follows POSIX conventions, giving three octal digits summarizing the permissions for the file owner, the owner’s group and for anyone respectively. Each digit is the logical or of read (4), write (2) and execute/search (1) permissions. On most systems symbolic links are followed, so information is given about the file to which the link points rather than about the link. Value A data frame with row names the file names and columns size double: File size in bytes. isdir logical: Is the file a directory? mode integer of class "octmode". The file permissions, printed in octal, for example 644. mtime, ctime, atime integer of class "POSIXct": file modification, ‘last status change’ and last access times. uid integer: the user ID of the file’s owner. gid integer: the group ID of the file’s group. uname character: uid interpreted as a user name. grname character: gid interpreted as a group name. 186 file.path Unknown user and group names will be NA. Entries for non-existent or non-readable files will be NA. The uid, gid, uname and grname columns may not be supplied on a non-POSIX Unix-alike system, and will not be on Windows. What is meant by the three file times depends on the OS and file system. On Windows native file systems ctime is the file creation time (something which is not recorded on most Unix-alike file systems). What is meant by ‘file access’ and hence the ‘last access time’ is system-dependent. The times are reported to an accuracy of seconds, and perhaps more on some systems. However, many file systems only record times in seconds, and some (e.g. modification time on FAT systems) are recorded in increments of 2 or more seconds. Note Some systems allow files of more than 2Gb to be created but not accessed by the stat system call. Such files will show up as non-readable (and very likely not be readable by any of R’s input functions) – fortunately such file systems are becoming rare. See Also Sys.readlink to find out about symbolic links, files, file.access, list.files, and DateTimeClasses for the date formats. Sys.chmod to change permissions. Examples ncol(finf <- file.info(dir()))# at least six ## Not run: finf # the whole list ## Those that are more than 100 days old : finf[difftime(Sys.time(), finf[,"mtime"], units="days") > 100 , 1:4] file.info("no-such-file-exists") file.path Construct Path to File Description Construct the path to a file from components in a platform-independent way. Usage file.path(..., fsep = .Platform$file.sep) Arguments ... character vectors. fsep the path separator to use. file.show 187 Details The implementation is designed to be fast (faster than paste) as this function is used extensively in R itself. It can also be used for environment paths such as PATH and R_LIBS with fsep = .Platform$path.sep. Value A character vector of the arguments concatenated term-by-term and separated by fsep if all argu- ments have positive length; otherwise, an empty character vector (unlike paste). Note The components are separated by /(not \) on Windows. file.show Display One or More Files Description Display one or more files. Usage file.show(..., header = rep("", nfiles), title = "R Information", delete.file = FALSE, pager = getOption("pager"), encoding = "") Arguments ... one or more character vectors containing the names of the files to be displayed. Paths with have tilde expansion. header character vector (of the same length as the number of files specified in ...) giving a header for each file being displayed. Defaults to empty strings. title an overall title for the display. If a single separate window is used for the display, title will be used as the window title. If multiple windows are used, their titles should combine the title and the file-specific header. delete.file should the files be deleted after display? Used for temporary files. pager the pager to be used: not used on all platforms encoding character string giving the encoding to be assumed for the file(s). 188 files Details This function provides the core of the R help system, but it can be used for other purposes as well, such as page. How the pager is implemented is highly system-dependent. The basic Unix version concatenates the files (using the headers) to a temporary file, and displays it in the pager selected by the pager argument, which is a character vector specifying a system command to run on the set of files. The ‘factory-fresh’ default is to use ‘R_HOME/bin/pager’, which is a shell script running the command specified by the environment variable PAGER whose default is set at configuration, usually to less. On a Unix-alike more is used if pager is empty. Most GUI systems will use a separate pager window for each file, and let the user leave it up while R continues running. The selection of such pagers could either be done using special pager names being intercepted by lower-level code (such as "internal" and "console" on Windows), or by letting pager be an R function which will be called with arguments (files, header, title, delete.file) corresponding to the first four arguments of file.show and take care of interfacing to the GUI. The R.app Mac OS X GUI uses its internal pager irrespective of the setting of pager. Not all implementations will honour delete.file. In particular, using an external pager on Win- dows does not, as there is no way to know when the external application has finished with the file. Author(s) Ross Ihaka, Brian Ripley. See Also files, list.files, help. file.edit. Examples file.show(file.path(R.home("doc"), "COPYRIGHTS")) files File Manipulation Description These functions provide a low-level interface to the computer’s file system. files 189 Usage file.create(..., showWarnings = TRUE) file.exists(...) file.remove(...) file.rename(from, to) file.append(file1, file2) file.copy(from, to, overwrite = recursive, recursive = FALSE, copy.mode = TRUE) file.symlink(from, to) file.link(from, to) Arguments ..., file1, file2 character vectors, containing file names or paths. from, to character vectors, containing file names or paths. For file.copy and file.symlink to can alternatively be the path to a single existing directory. overwrite logical; should existing destination files be overwritten? showWarnings logical; should the warnings on failure be shown? recursive logical. If to is a directory, should directories in from be copied (and their contents)? copy.mode logical: should file permission bits be copied where possible? This applies to both files and directories. Details The ... arguments are concatenated to form one character string: you can specify the files sepa- rately or as one vector. All of these functions expand path names: see path.expand. file.create creates files with the given names if they do not already exist and truncates them if they do. They are created with the maximal read/write permissions allowed by the ‘umask’ setting (where relevant). By default a warning is given (with the reason) if the operation fails. file.exists returns a logical vector indicating whether the files named by its argument exist. (Here ‘exists’ is in the sense of the system’s stat call: a file will be reported as existing only if you have the permissions needed by stat. Existence can also be checked by file.access, which might use different permissions and so obtain a different result. Note that the existence of a file does not imply that it is readable: for that use file.access.) What constitutes a ‘file’ is system-dependent, but should include directories. (However, directory names must not include a trailing backslash or slash on Windows.) Note that if the file is a symbolic link on a Unix-alike, the result indicates if the link points to an actual file, not just if the link exists. file.remove attempts to remove the files named in its argument. On most Unix platforms ‘file’ includes empty directories, symbolic links, fifos and sockets. On Windows, ‘file’ means a regular file and not, say, an empty directory. file.rename attempts to rename files (and from and to must be of the same length). Where file permissions allow this will overwrite an existing element of to. This is subject to the limitations of the OS’s corresponding system call (see something like man 2 rename on a Unix-alike): in 190 files particular in the interpretation of ‘file’: most platforms will not rename files across file systems. (On Windows, file.rename nowadays works for files (but not directories) across volumes.) file.append attempts to append the files named by its second argument to those named by its first. The R subscript recycling rule is used to align names given in vectors of different lengths. file.copy works in a similar way to file.append but with the arguments in the natural order for copying. Copying to existing destination files is skipped unless overwrite = TRUE. The to argument can specify a single existing directory. If copy.mode = TRUE (added in R 2.13.0) file read/write/execute permissions are copied where possible, restricted by ‘umask’. Other security attributes such as ACLs are not copied. file.symlink and file.link make symbolic and hard links on those file systems which support them. For file.symlink the to argument can specify a single existing directory. (Unix and Mac OS X native filesystems support both. Windows has hard links on NTFS file systems. What happens on a FAT or SMB-mounted file system is OS-specific.) Value These functions return a logical vector indicating which operation succeeded for each of the files attempted. Using a missing value for a file or path name will always be regarded as a failure. If showWarnings = TRUE, file.create will give a warning for an unexpected failure. Author(s) Ross Ihaka, Brian Ripley See Also file.info, file.access, file.path, file.show, list.files, unlink, basename, path.expand. dir.create. Sys.glob to expand wildcards in file specifications. file_test, Sys.readlink. http://en.wikipedia.org/wiki/Hard_link and http://en.wikipedia.org/wiki/ Symbolic_link for the concepts of links and their limitations. Examples cat("file A\n", file="A") cat("file B\n", file="B") file.append("A", "B") file.create("A") file.append("A", rep("B", 10)) if(interactive()) file.show("A") file.copy("A", "C") dir.create("tmp") file.copy(c("A", "B"), "tmp") list.files("tmp") setwd("tmp") file.remove("B") files2 191 file.symlink(file.path("..", c("A", "B")), ".") setwd("..") unlink("tmp", recursive=TRUE) file.remove("A", "B", "C") files2 Manipulaton of Directories and File Permissions Description These functions provide a low-level interface to the computer’s file system. Usage dir.create(path, showWarnings = TRUE, recursive = FALSE, mode = "0777") Sys.chmod(paths, mode = "0777", use_umask=TRUE) Sys.umask(mode = NA) Arguments path a character vector containing a single path name. Tilde expansion (see path.expand) is done. paths character vectors containing file or directory paths. Tilde expansion (see path.expand) is done. showWarnings logical; should the warnings on failure be shown? recursive logical. Should elements of the path other than the last be created? If true, like the Unix command mkdir -p. mode the mode to be used on Unix-alikes: it will be coerced by as.octmode. For Sys.chmod it is recycled along paths. use_umask logical: should the mode be restricted by the umask setting? Details dir.create creates the last element of the path, unless recursive = TRUE. Trailing path separators are discarded. The mode will be modified by the umask setting in the same way as for the system function mkdir. What modes can be set is OS-dependent, and it is unsafe to assume that more than three octal digits will be used. For more details see your OS’s documentation on the system call mkdir, e.g. man 2 mkdir (and not that on the command-line utility of that name). One of the idiosyncrasies of Windows is that directory creation may report success but create a directory with a different name, for example dir.create("G.S.") creates ‘"G.S"’. This is undoc- umented, and what are the precise circumstances is unknown (and might depend on the version of Windows). Also avoid directory names with a trailing space. Sys.chmod sets the file permissions of one or more files. It may not be supported on a system (when a warning is issued). See the comments for dir.create for how modes are interpreted. Changing mode on a symbolic link is unlikely to work (nor be necessary). For more details see your OS’s 192 find.package documentation on the system call chmod, e.g. man 2 chmod (and not that on the command-line utility of that name). Sys.umask sets the umask and returns the previous value: as a special case mode = NA just returns the current value. It may not be supported (when a warning is issued and "0" is returned). For more details see your OS’s documentation on the system call umask, e.g. man 2 umask. How modes are handled depends on the file system, even on Unix-alikes (although their documen- tation is often written assuming a POSIX file system). So treat documentation cautiously if you are using, say, a FAT/FAT32 or network-mounted file system. Value dir.create and Sys.chmod return invisibly a logical vector indicating if the operation succeeded for each of the files attempted. Using a missing value for a path name will always be regarded as a failure. dir.create indicates failure if the directory already exists. If showWarnings = TRUE, dir.create will give a warning for an unexpected failure (e.g. not for a missing value nor for an already existing component for recursive = TRUE). Sys.umask returns the previous value of the umask, as a length-one object of class "octmode": the visibility flag is off unless mode is NA. Author(s) Ross Ihaka, Brian Ripley See Also file.info, file.exists, file.path, list.files, unlink, basename, path.expand. Examples ## Not run: ## Fix up maximal allowed permissions in a file tree Sys.chmod(list.dirs("."), "777") f <- list.files(".", all.files = TRUE, full.names = TRUE, recursive =TRUE) Sys.chmod(f, (file.info(f)$mode | "664")) ## End(Not run) find.package Find Packages Description Find the paths to one or more packages. findInterval 193 Usage find.package(package, lib.loc = NULL, quiet = FALSE, verbose = getOption("verbose")) path.package(package, quiet = FALSE) Arguments package character vector: the names of packages. lib.loc a character vector describing the location of R library trees to search through, or NULL. The default value of NULL corresponds to checking the attached packages, then all libraries currently known in .libPaths(). quiet logical. Should this not give warnings or an error if the package is not found? verbose a logical. If TRUE, additional diagnostics are printed. Details find.package returns path to the locations where the given packages are found. If lib.loc is NULL, then attached packages are searched before the libraries. If a package is found more than once, the first match is used. Unless quiet = TRUE a warning will be given about the named packages which are not found, and an error if none are. If verbose is true, warnings about packages found more than once are given. For a package to be returned it must contain a either a ‘Meta’ subdirectory or a ‘DESCRIPTION’ file containing a valid version field, but it need not be installed. path.package returns the paths from which the named packages were loaded, or if none were named, for all currently attached packages. Unless quiet = TRUE it will warn if some of the packages named are not attached, and given an error if none are. Value A character vector of paths of package directories. Note .find.package and .path.package were internal-only versions prior to R 2.13.0, and are now wrappers for these public versions. findInterval Find Interval Numbers or Indices Description Find the indices of x in vec, where vec must be sorted (non-decreasingly); i.e., if i <- findInterval(x,v), we have vij ≤ xj < vij +1 where v0 := −∞, vN+1 := +∞, and N <- length(vec). At the two boundaries, the returned index may differ by 1, depending on the op- tional arguments rightmost.closed and all.inside. 194 findInterval Usage findInterval(x, vec, rightmost.closed = FALSE, all.inside = FALSE) Arguments x numeric. vec numeric, sorted (weakly) increasingly, of length N, say. rightmost.closed logical; if true, the rightmost interval, vec[N-1] .. vec[N] is treated as closed, see below. all.inside logical; if true, the returned indices are coerced into 1,...,N-1, i.e., 0 is mapped to 1 and N to N-1. Details The function findInterval finds the index of one vector x in another, vec, where the latter must be non-decreasing. Where this is trivial, equivalent to apply( outer(x, vec, ">="), 1, sum), as a matter of fact, the internal algorithm uses interval search ensuring O(n log N) complexity where n <- length(x) (and N <- length(vec)). For (almost) sorted x, it will be even faster, basically O(n). This is the same computation as for the empirical distribution function, and indeed, findInterval(t, sort(X)) is identical to nFn(t;X1,...,Xn) where Fn is the empirical dis- tribution function of X1,...,Xn. When rightmost.closed = TRUE, the result for x[j] = vec[N] (= max vec), is N - 1 as for all other values in the last interval. Value vector of length length(x) with values in 0:N (and NA) where N <- length(vec), or values coerced to 1:(N-1) if and only if all.inside = TRUE (equivalently coercing all x values inside the intervals). Note that NAs are propagated from x, and Inf values are allowed in both x and vec. Author(s) Martin Maechler See Also approx(*, method = "constant") which is a generalization of findInterval(), ecdf for computing the empirical distribution function which is (up to a factor of n) also basically the same as findInterval(.). Examples N <- 100 X <- sort(round(stats::rt(N, df=2), 2)) tt <- c(-100, seq(-2,2, len=201), +100) it <- findInterval(tt, X) tt[it < 1 | it >= N] # only first and last are outside range(X) force 195 force Force Evaluation of an Argument Description Forces the evaluation of a function argument. Usage force(x) Arguments x a formal argument of the enclosing function. Details force forces the evaluation of a formal argument. This can be useful if the argument will be captured in a closure by the lexical scoping rules and will later be altered by an explicit assignment or an implicit assignment in a loop or an apply function. Note This is semantic sugar: just evaluating the symbol will do the same thing (see the examples). force does not force the evaluation of other promises. (It works by forcing the promise that is created when the actual arguments of a call are matched to the formal arguments of a closure, the mechanism which implements lazy evaluation.) Examples f <- function(y) function() y lf <- vector("list", 5) for (i in seq_along(lf)) lf[[i]] <- f(i) lf[[1]]() # returns 5 g <- function(y) { force(y); function() y } lg <- vector("list", 5) for (i in seq_along(lg)) lg[[i]] <- g(i) lg[[1]]() # returns 1 ## This is identical to g <- function(y) { y; function() y } 196 Foreign Foreign Foreign Function Interface Description Functions to make calls to compiled code that has been loaded into R. Usage .C(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING) .Fortran(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING) .External(.NAME, ..., PACKAGE) .Call(.NAME, ..., PACKAGE) Arguments .NAME a character string giving the name of a C function or Fortran subroutine, or an object of class "NativeSymbolInfo","RegisteredNativeSymbol" or "NativeSymbol" referring to such a name. ... arguments to be passed to the foreign function. NAOK if TRUE then any NA or NaN or Inf values in the arguments are passed on to the foreign function. If FALSE, the presence of NA or NaN or Inf values is regarded as an error. DUP if TRUE then arguments are duplicated before their address is passed to C or Fortran. PACKAGE if supplied, confine the search for the .NAME to the DLL given by this argument (plus the conventional extension, ‘.so’, ‘.sl’, ‘.dll’, . . . ). This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols, and also speeds up the search (see ‘Note’). Use PACKAGE="base" for symbols linked in to R. ENCODING optional name for an encoding to be assumed for character vectors. See ‘De- tails’. Details The functions .C and .Fortran can be used to make calls to compiled C and Fortran code. .Call can be used to call compiled code which makes use of internal R objects, passing the argu- ments to the C code as a sequence of R objects. .External can be used to call compiled code that uses R objects in the same way as internal R functions: this allows for a variable number of arguments. Specifying ENCODING overrides any declared encodings (see Encoding) which are otherwise used to translate to the current locale before passing the strings to the compiled code. These functions are all primitive, and .NAME is always matched to the first argument supplied (which if named must partially match .NAME). The other named arguments follow ... and so cannot be Foreign 197 abbreviated. You should avoid using names in the arguments passed to ... that match or partially match .NAME in case the argument handling in .C or .Fortran should change to follow standard argument matching conventions. For details about how to write code to use with .Call and .External, see the chapter on “System and foreign language interfaces” in the “Writing R Extensions” manual. Value The functions .C and .Fortran return a list similar to the ... list of arguments passed in, but reflecting any changes made by the C or Fortran code. .External and .Call return an (arbitrary) R object. These calls are typically made in conjunction with dyn.load which links DLLs to R. Argument types The mapping of the types of R arguments to C or Fortran arguments in .C or .Fortran is R C Fortran integer int * integer numeric double * double precision – or – float * real complex Rcomplex * double complex logical int * integer character char ** [see below] raw unsigned char * not allowed list SEXP * not allowed other SEXP not allowed Numeric vectors in R will be passed as type double * to C (and as double precision to Fortran) unless (i) .C or .Fortran is used, (ii) DUP is true and (iii) the argument has attribute Csingle set to TRUE (use as.single or single). This mechanism is only intended to be used to facilitate the interfacing of existing C and Fortran code. The C type Rcomplex is defined in ‘Complex.h’ as a typedef struct {double r; double i;}. Fortran type double complex is an extension to the Fortran standard, and the availability of a mapping of complex to Fortran may be compiler dependent. Logical values are sent as 0 (FALSE), 1 (TRUE) or INT_MIN = -2147483648 (NA, but only if NAOK = TRUE), and the compiled code should return one of these three values: however non-zero value other than INT_MIN are mapped to TRUE. Note: The C types corresponding to integer and logical are int, not long as in S. This differ- ence matters on most 64-bit platforms, where int is 32-bit and long is 64-bit (but not on 64-bit Windows). Note: The Fortran type corresponding to logical is integer, not logical: the difference matters on some older Fortran compilers. The first character string of a character vector is passed as a C character array to Fortran: that string may be usable as character*255 if its true length is passed separately. Only up to 255 characters 198 Foreign of the string are passed back. (How well this works, or even if it works at all, depends on the C and Fortran compilers and the platform.) Missing (NA) string values are passed to .C as the string "NA". As the C char type can represent all possible bit patterns there appears to be no way to distinguish missing strings from the string "NA". If this distinction is important use .Call. Functions, expressions, environments and other language elements are passed as the internal R pointer type SEXP. This type is defined in ‘Rinternals.h’ or the arguments can be declared as generic pointers, void *. Lists are passed as C arrays of SEXP and can be declared as void * or SEXP *. Note that you cannot assign values to the elements of the list within the C routine. Assigning values to elements of the array corresponding to the list bypasses R’s memory management/garbage collection and will cause problems. Essentially, the array corresponding to the list is read-only. If you need to return S objects created within the C routine, use the .Call interface. R functions can be invoked using call_S or call_R and can be passed lists or the simple types as arguments. Warning DUP=FALSE is dangerous. There are two dangers with using DUP=FALSE. The first is that if you pass a local variable to .C/.Fortran with DUP=FALSE, your compiled code can alter the local variable and not just the copy in the return list. Worse, if you pass a local variable that is a formal parameter of the calling function, you may be able to change not only the local variable but the variable one level up. This will be very hard to trace. The second is that lists are passed as a single R SEXP with DUP=FALSE, not as an array of SEXP. This means the accessor macros in ‘Rinternals.h’ are needed to get at the list elements and the lists cannot be passed to call_S/call_R. New code using R objects should be written using .Call or .External, so this is now only a minor issue. In addition, character vectors and lists cannot be used with DUP=FALSE. It is safe and useful to set DUP=FALSE if you do not change any of the variables that might be affected, e.g., .C("Cfunction", input=x, output=numeric(10)). In this case the output variable did not exist before the call so it cannot cause trouble. If the input variable is not changed in the C code of Cfunction you are safe. Neither .Call nor .External copy their arguments. You should treat arguments you receive through these interfaces as read-only. Fortran symbol names All Fortran compilers that can be used to compile R map symbol names to lower case, and so does .Fortran. Symbol names containing underscores are not valid Fortran 77 (although they are valid in Fortran 9x). Many Fortran 77 compilers will allow them but may translate them in a different way to names not containing underscores. Such names will often work with .Fortran (since how they are translated is detected when R is built and the information used by .Fortran), but portable code should not use Fortran names containing underscores. formals 199 Use .Fortran with care for compiled Fortran 9x code: it may not work if the Fortran 9x compiler used differs from the Fortran compiler used when configuring R, especially if the subroutine name is not lower-case or includes an underscore. It is also possible to use .C and do any necessary symbol-name translation yourself. Header files for external code Writing code for use with .External and .Call will need to use internal R structures. If possible use just those defined in ‘Rinternals.h’ and/or the macros in ‘Rdefines.h’, as other header files are not installed and are even more likely to be changed. Note If one of these functions is to be used frequently, do specify PACKAGE (to confine the search to a single DLL) or pass name as one of the native symbol objects. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (.C and .Fortran.) Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. (.Call.) See Also dyn.load. formals Access to and Manipulation of the Formal Arguments Description Get or set the formal arguments of a function. Usage formals(fun = sys.function(sys.parent())) formals(fun, envir = environment(fun)) <- value Arguments fun a function object, or see ‘Details’. envir environment in which the function should be defined. value a list (or pairlist) of R expressions. 200 format Details For the first form, fun can also be a character string naming the function to be manipulated, which is searched for from the parent frame. If it is not specified, the function calling formals is used. Only closures have formals, not primitive functions. Value formals returns the formal argument list of the function specified, as a pairlist, or NULL for a non-function or primitive. The replacement form sets the formals of a function to the list/pairlist on the right hand side, and (potentially) resets the environment of the function. See Also args for a human-readable version, alist, body, function. Examples require(stats); require(graphics) length(formals(lm)) # the number of formal arguments names(formals(boxplot)) # formal arguments names f <- function(x) a+b formals(f) <- alist(a=,b=3) # function(a,b=3)a+b f(2) # result = 5 format Encode in a Common Format Description Format an R object for pretty printing. Usage format(x, ...) ## Default S3 method: format(x, trim = FALSE, digits = NULL, nsmall = 0L, justify = c("left", "right", "centre", "none"), width = NULL, na.encode = TRUE, scientific = NA, big.mark = "", big.interval = 3L, small.mark = "", small.interval = 5L, decimal.mark = ".", zero.print = NULL, drop0trailing = FALSE, ...) ## S3 method for class ’data.frame’ format 201 format(x, ..., justify = "none") ## S3 method for class ’factor’ format(x, ...) ## S3 method for class ’AsIs’ format(x, width = 12, ...) Arguments x any R object (conceptually); typically numeric. trim logical; if FALSE, logical, numeric and complex values are right-justified to a common width: if TRUE the leading blanks for justification are suppressed. digits how many significant digits are to be used for numeric and complex x. The default, NULL, uses getOption(digits). This is a suggestion: enough decimal places will be used so that the smallest (in magnitude) number has this many significant digits, and also to satisfy nsmall. (For the interpretation for complex numbers see signif.) nsmall the minimum number of digits to the right of the decimal point in format- ting real/complex numbers in non-scientific formats. Allowed values are 0 <= nsmall <= 20. justify should a character vector be left-justified (the default), right-justified, centred or left alone. width default method: the minimum field width or NULL or 0 for no restriction. AsIs method: the maximum field width for non-character objects. NULL corre- sponds to the default 12. na.encode logical: should NA strings be encoded? Note this only applies to elements of character vectors, not to numerical or logical NAs, which are always encoded as "NA". scientific Either a logical specifying whether elements of a real or complex vector should be encoded in scientific format, or an integer penalty (see options("scipen")). Missing values correspond to the current default penalty. ... further arguments passed to or from other methods. big.mark, big.interval, small.mark, small.interval, decimal.mark, zero.print, drop0trailing used for prettying (longish) decimal sequences, passed to prettyNum: that help page explains the details. Details format is a generic function. Apart from the methods described here there are methods for dates (see format.Date), date-times (see format.POSIXct)) and for other classes such as format.octmode and format.dist. format.data.frame formats the data frame column by column, applying the appropriate method of format for each column. Methods for columns are often similar to as.character but offer more control. Matrix and data-frame columns will be converted to separate columns in the result, and character columns (normally all) will be given class "AsIs". 202 format format.factor converts the factor to a character vector and then calls the default method (and so justify applies). format.AsIs deals with columns of complicated objects that have been extracted from a data frame. Character objects are passed to the default method (and so width does not apply). Otherwise it calls toString to convert the object to character (if a vector or list, element by element) and then right- justifies the result. Justification for character vectors (and objects converted to character vectors by their methods) is done on display width (see nchar), taking double-width characters and the rendering of spe- cial characters (as escape sequences, including escaping backslash but not double quote: see print.default) into account. Thus the width is as displayed by print(quote = FALSE) and not as displayed by cat. Character strings are padded with blanks to the display width of the widest. (If na.encode = FALSE missing character strings are not included in the width computations and are not encoded.) Numeric vectors are encoded with the minimum number of decimal places needed to display all the elements to at least the digits significant digits. However, if all the elements then have trailing ze- roes, the number of decimal places is reduced until at least one element has a non-zero final digit; see also the argument documentation for big.*, small.* etc, above. See the note in print.default about digits >= 16. Raw vectors are converted to their 2-digit hexadecimal representation by as.character. Value An object of similar structure to x containing character representations of the elements of the first argument x in a common format, and in the current locale’s encoding. For character, numeric, complex or factor x, dims and dimnames are preserved on matrices/arrays and names on vectors: no other attributes are copied. If x is a list, the result is a character vector obtained by applying format.default(x, ...) to each element of the list (after unlisting elements which are themselves lists), and then collapsing the result for each element with paste(collapse = ", "). The defaults in this case are trim = TRUE, justify = "none" since one does not usually want alignment in the collapsed strings. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also format.info indicates how an atomic vector would be formatted. formatC, paste, as.character, sprintf, print, prettyNum, toString, encodeString. Examples format(1:10) format(1:10, trim = TRUE) zz <- data.frame("(row names)"= c("aaaaa", "b"), check.names=FALSE) format(zz) format.info 203 format(zz, justify = "left") ## use of nsmall format(13.7) format(13.7, nsmall = 3) format(c(6.0, 13.1), digits = 2) format(c(6.0, 13.1), digits = 2, nsmall = 1) ## use of scientific format(2^31-1) format(2^31-1, scientific = TRUE) ## a list z <- list(a=letters[1:3], b=(-pi+0i)^((-2:2)/2), c=c(1,10,100,1000), d=c("a", "longer", "character", "string")) format(z, digits = 2) format(z, digits = 2, justify = "left", trim = FALSE) format.info format(.) Information Description Information is returned on how format(x, digits, nsmall) would be formatted. Usage format.info(x, digits = NULL, nsmall = 0) Arguments x an atomic vector; a potential argument of format(x, ...). digits how many significant digits are to be used for numeric and complex x. The default, NULL, uses getOption(digits). nsmall (see format(..., nsmall)). Value An integer vector of length 1, 3 or 6, say r. For logical, integer and character vectors a single element, the width which would be used by format if width = NULL. For numeric vectors: r[1] width (in characters) used by format(x) r[2] number of digits after decimal point. r[3] in 0:2; if ≥1, exponential representation would be used, with exponent length of r[3]+1. For a complex vector the first three elements refer to the real parts, and there are three further elements corresponding to the imaginary parts. 204 format.pval See Also format (notably about digits >= 16), formatC. Examples dd <- options("digits") ; options(digits = 7) #-- for the following format.info(123) # 3 0 0 format.info(pi) # 8 6 0 format.info(1e8) # 5 0 1 - exponential "1e+08" format.info(1e222) # 6 0 2 - exponential "1e+222" x <- pi*10^c(-10,-2,0:2,8,20) names(x) <- formatC(x, width=1, digits=3, format="g") cbind(sapply(x,format)) t(sapply(x, format.info)) ## using at least 8 digits right of "." t(sapply(x, format.info, nsmall = 8)) # Reset old options: options(dd) format.pval Format P Values Description format.pval is intended for formatting p-values. Usage format.pval(pv, digits = max(1, getOption("digits") - 2), eps = .Machine$double.eps, na.form = "NA", ...) Arguments pv a numeric vector. digits how many significant digits are to be used. eps a numerical tolerance: see ‘Details’. na.form character representation of NAs. ... further arguments to be passed to format such as nsmall. Details format.pval is mainly an auxiliary function for print.summary.lm etc., and does separate for- matting for fixed, floating point and very small values; those less than eps are formatted as "< [eps]" (where ‘[eps]’ stands for format(eps, digits)). formatC 205 Value A character vector. Examples format.pval(c(stats::runif(5), pi^-100, NA)) format.pval(c(0.1, 0.0001, 1e-27)) formatC Formatting Using C-style Formats Description Formatting numbers individually and flexibly, using C style format specifications. Usage formatC(x, digits = NULL, width = NULL, format = NULL, flag = "", mode = NULL, big.mark = "", big.interval = 3L, small.mark = "", small.interval = 5L, decimal.mark = ".", preserve.width = "individual", zero.print = NULL, drop0trailing = FALSE) prettyNum(x, big.mark = "", big.interval = 3L, small.mark = "", small.interval = 5L, decimal.mark = ".", preserve.width = c("common", "individual", "none"), zero.print = NULL, drop0trailing = FALSE, is.cmplx = NA, ...) Arguments x an atomic numerical or character object, possibly complex only for prettyNum(), typically a vector of real numbers. digits the desired number of digits after the decimal point (format = "f") or signifi- cant digits (format = "g", = "e" or = "fg"). Default: 2 for integer, 4 for real numbers. If less than 0, the C default of 6 digits is used. If specified as more than 50, 50 will be used with a warning unless format = "f" where it is limited to typically 324. (Not more than 15–21 digits need be accurate, depending on the OS and compiler used. This limit is just a precaution against segfaults in the underlying C runtime.) width the total field width; if both digits and width are unspecified, width defaults to 1, otherwise to digits + 1. width = 0 will use width = digits, width < 0 means left justify the number in this field (equivalent to flag ="-"). If necessary, the result will have more characters than width. For character data this is interpreted in characters (not bytes nor display width). 206 formatC format equal to "d" (for integers), "f","e","E","g","G","fg" (for reals), or "s" (for strings). Default is "d" for integers, "g" for reals. "f" gives numbers in the usual xxx.xxx format; "e" and "E" give n.ddde+nn or n.dddE+nn (scientific format); "g" and "G" put x[i] into scientific format only if it saves space to do so. "fg" uses fixed format as "f", but digits as the minimum number of significant digits. This can lead to quite long result strings, see examples below. Note that unlike signif this prints large numbers with more significant digits than digits. Trailing zeros are dropped in this format, unless flag contains "#". flag For formatC, a character string giving a format modifier as in Kernighan and Ritchie (1988, page 243). "0" pads leading zeros; "-" does left adjustment, others are "+","", and "#". There can be more than one of these, in any order. mode "double" (or "real"), "integer" or "character". Default: Determined from the storage mode of x. big.mark character; if not empty used as mark between every big.interval decimals before (hence big) the decimal point. big.interval see big.mark above; defaults to 3. small.mark character; if not empty used as mark between every small.interval decimals after (hence small) the decimal point. small.interval see small.mark above; defaults to 5. decimal.mark the character to be used to indicate the numeric decimal point. preserve.width string specifying if the string widths should be preserved where possible in those cases where marks (big.mark or small.mark) are added. "common", the de- fault, corresponds to format-like behavior whereas "individual" is the default in formatC(). zero.print logical, character string or NULL specifying if and how zeros should be formatted specially. Useful for pretty printing ‘sparse’ objects. drop0trailing logical, indicating if trailing zeros, i.e., "0" after the decimal mark, should be removed; also drops "e+00" in exponential formats. is.cmplx optional logical, to be used when x is "character" to indicate if it stems from complex vector or not. By default (NA), x is checked to ‘look like’ complex. ... arguments passed to format. Details If you set format it overrides the setting of mode, so formatC(123.45, mode="double", format="d") gives 123. The rendering of scientific format is platform-dependent: some systems use n.ddde+nnn or n.dddenn rather than n.ddde+nn. formatC does not necessarily align the numbers on the decimal point, so formatC(c(6.11, 13.1), digits=2, format="fg") gives c("6.1", " 13"). If you want common formatting for several numbers, use format. prettyNum is the utility function for prettifying x. x can be complex (or format(), here. If x is not a character, format(x[i], ...) is applied to each element, and then it is left unchanged formatC 207 if all the other arguments are at their defaults. Note that prettyNum(x) may behave unexpectedly if x is a character vector not resulting from something like format(): in particular it assumes that a period is a decimal mark. Because gsub is used to insert the big.mark and small.mark, special characters need escaping. In particular, to insert a single backslash, use "\\\\". In versions of R before 2.13.0, the big.mark would be reversed on insertion if it contained more than one character. Value A character object of same size and attributes as x, in the current locale’s encoding. Unlike format, each number is formatted individually. Looping over each element of x, the C function sprintf(...) is called for numeric inputs (inside the C function str_signif). formatC: for character x, do simple (left or right) padding with white space. Author(s) formatC was originally written by Bill Dunlap, later much improved by Martin Maechler. It was first adapted for R by Friedrich Leisch. References Kernighan, B. W. and Ritchie, D. M. (1988) The C Programming Language. Second edition. Pren- tice Hall. See Also format. sprintf for more general C like formatting. Examples xx <- pi * 10^(-5:4) cbind(format(xx, digits=4), formatC(xx)) cbind(formatC(xx, width = 9, flag = "-")) cbind(formatC(xx, digits = 5, width = 8, format = "f", flag = "0")) cbind(format(xx, digits=4), formatC(xx, digits = 4, format = "fg")) formatC( c("a", "Abc", "no way"), width = -7) # <=> flag = "-" formatC(c((-1:1)/0,c(1,100)*pi), width=8, digits=1) xx <- c(1e-12,-3.98765e-10,1.45645e-69,1e-70,pi*1e37,3.44e4) ## 1 2 3 4 5 6 formatC(xx) formatC(xx, format="fg") # special "fixed" format. formatC(xx[1:4], format="f", digits=75) #>> even longer strings formatC(c(3.24, 2.3e-6), format="f", digits=11, drop0trailing=TRUE) r <- c("76491283764.97430", "29.12345678901", "-7.1234", "-100.1","1123") 208 formatDL ## American: prettyNum(r, big.mark = ",") ## Some Europeans: prettyNum(r, big.mark = "’", decimal.mark = ",") (dd <- sapply(1:10, function(i)paste((9:0)[1:i],collapse=""))) prettyNum(dd, big.mark="’") ## examples of ’small.mark’ pN <- stats::pnorm(1:7, lower.tail = FALSE) cbind(format (pN, small.mark = " ", digits = 15)) cbind(formatC(pN, small.mark = " ", digits = 17, format = "f")) cbind(ff <- format(1.2345 + 10^(0:5), width = 11, big.mark = "’")) ## all with same width (one more than the specified minimum) ## individual formatting to common width: fc <- formatC(1.234 + 10^(0:8), format="fg", width=11, big.mark = "’") cbind(fc) ## complex numbers: r <- 10.0000001; rv <- (r/10)^(1:10) (zv <- (rv + 1i*rv)) op <- options(digits=7) ## (system default) (pnv <- prettyNum(zv)) stopifnot(pnv == "1+1i", pnv == format(zv), pnv == prettyNum(zv, drop0trailing=TRUE)) ## more digits change the picture: options(digits=8) head(fv <- format(zv), 3) prettyNum(fv) prettyNum(fv, drop0trailing=TRUE) # a bit nicer options(op) formatDL Format Description Lists Description Format vectors of items and their descriptions as 2-column tables or LaTeX-style description lists. Usage formatDL(x, y, style = c("table", "list"), width = 0.9 * getOption("width"), indent = NULL) Arguments x a vector giving the items to be described, or a list of length 2 or a matrix with 2 columns giving both items and descriptions. function 209 y a vector of the same length as x with the corresponding descriptions. Only used if x does not already give the descriptions. style a character string specifying the rendering style of the description informa- tion. If "table", a two-column table with items and descriptions as columns is produced (similar to Texinfo’s @table environment. If "list", a LaTeX-style tagged description list is obtained. width a positive integer giving the target column for wrapping lines in the output. indent a positive integer specifying the indentation of the second column in table style, and the indentation of continuation lines in list style. Must not be greater than width/2, and defaults to width/3 for table style and width/9 for list style. Details After extracting the vectors of items and corresponding descriptions from the arguments, both are coerced to character vectors. In table style, items with more than indent - 3 characters are displayed on a line of their own. Value a character vector with the formatted entries. Examples ## Not run: ## Use R to create the ’INDEX’ for package ’splines’ from its ’CONTENTS’ x <- read.dcf(file = system.file("CONTENTS", package = "splines"), fields = c("Entry", "Description")) x <- as.data.frame(x) writeLines(formatDL(x$Entry, x$Description)) ## or equivalently: writeLines(formatDL(x)) ## Same information in tagged description list style: writeLines(formatDL(x$Entry, x$Description, style = "list")) ## or equivalently: writeLines(formatDL(x, style = "list")) ## End(Not run) function Function Definition Description These functions provide the base mechanisms for defining new functions in the R language. Usage function( arglist ) expr return(value) 210 function Arguments arglist Empty or one or more name or name=expression terms. value An expression. Details The names in an argument list can be back-quoted non-standard names (see ‘backquote’). If value is missing, NULL is returned. If it is a single expression, the value of the evaluated expres- sion is returned. (The expression is evaluated as soon as return is called, in the evaluation frame of the function and before any on.exit expression is evaluated.) If the end of a function is reached without calling return, the value of the last evaluated expression is returned. Warning Prior to R 1.8.0, value could be a series of non-empty expressions separated by commas. In that case the value returned is a list of the evaluated expressions, with names set to the expressions where these are the names of R objects. That is, a=foo() names the list component a and gives it the value which results from evaluating foo(). This has been deprecated (and a warning is given), as it was never documented in S, and whether or not the list is named differs by S versions. Supply a (named) list value instead. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also args and body for accessing the arguments and body of a function. debug for debugging; using invisible inside return(.) for returning invisibly. Examples norm <- function(x) sqrt(x%*%x) norm(1:4) ## An anonymous function: (function(x,y){ z <- x^2 + y^2; x+y+z })(0:7, 1) funprog 211 funprog Common Higher-Order Functions in Functional Programming Lan- guages Description Reduce uses a binary function to successively combine the elements of a given vector and a possibly given initial value. Filter extracts the elements of a vector for which a predicate (logical) function gives true. Find and Position give the first or last such element and its position in the vector, respectively. Map applies a function to the corresponding elements of given vectors. Negate creates the negation of a given function. Usage Reduce(f, x, init, right = FALSE, accumulate = FALSE) Filter(f, x) Find(f, x, right = FALSE, nomatch = NULL) Map(f, ...) Negate(f) Position(f, x, right = FALSE, nomatch = NA_integer_) Arguments f a function of the appropriate arity (binary for Reduce, unary for Filter, Find and Position, k-ary for Map if this is called with k arguments). An arbitrary predicate function for Negate. x a vector. init an R object of the same kind as the elements of x. right a logical indicating whether to proceed from left to right (default) or from right to left. accumulate a logical indicating whether the successive reduce combinations should be ac- cumulated. By default, only the final combination is used. nomatch the value to be returned in the case when “no match” (no element satisfying the predicate) is found. ... vectors. Details If init is given, Reduce logically adds it to the start (when proceeding left to right) or the end of x, respectively. If this possibly augmented vector v has n > 1 elements, Reduce successively applies f to the elements of v from left to right or right to left, respectively. I.e., a left reduce computes l1 = f(v1, v2), l2 = f(l1, v3), etc., and returns ln−1 = f(ln−2, vn), and a right reduce does rn−1 = f(vn−1, vn), rn−2 = f(vn−2, rn−1) and returns r1 = f(v1, r2). (E.g., if v is the sequence (2, 3, 4) and f is division, left and right reduce give (2/3)/4 = 1/6 and 2/(3/4) = 8/3, respectively.) If v has only a single element, this is returned; if there are no elements, NULL is returned. Thus, it is ensured that f is always called with 2 arguments. 212 funprog The current implementation is non-recursive to ensure stability and scalability. Reduce is patterned after Common Lisp’s reduce. A reduce is also known as a fold (e.g., in Haskell) or an accumulate (e.g., in the C++ Standard Template Library). The accumulative version corre- sponds to Haskell’s scan functions. Filter applies the unary predicate function f to each element of x, coercing to logical if necessary, and returns the subset of x for which this gives true. Note that possible NA values are currently always taken as false; control over NA handling may be added in the future. Filter corresponds to filter in Haskell or remove-if-not in Common Lisp. Find and Position are patterned after Common Lisp’s find-if and position-if, respectively. If there is an element for which the predicate function gives true, then the first or last such element or its position is returned depending on whether right is false (default) or true, respectively. If there is no such element, the value specified by nomatch is returned. The current implementation is not optimized for performance. Map is a simple wrapper to mapply which does not attempt to simplify the result, similar to Common Lisp’s mapcar (with arguments being recycled, however). Future versions may allow some control of the result type. Negate corresponds to Common Lisp’s complement. Given a (predicate) function f, it creates a function which returns the logical negation of what f returns. See Also clusterMap in package parallel provides a parallel version of Map. Examples ## A general-purpose adder: add <- function(x) Reduce("+", x) add(list(1, 2, 3)) ## Like sum(), but can also used for adding matrices etc., as it will ## use the appropriate ’+’ method in each reduction step. ## More generally, many generics meant to work on arbitrarily many ## arguments can be defined via reduction: FOO <- function(...) Reduce(FOO2, list(...)) FOO2 <- function(x, y) UseMethod("FOO2") ## FOO() methods can then be provided via FOO2() methods. ## A general-purpose cumulative adder: cadd <- function(x) Reduce("+", x, accumulate = TRUE) cadd(seq_len(7)) ## A simple function to compute continued fractions: cfrac <- function(x) Reduce(function(u, v) u + 1 / v, x, right = TRUE) ## Continued fraction approximation for pi: cfrac(c(3, 7, 15, 1, 292)) ## Continued fraction approximation for Euler’s number (e): cfrac(c(2, 1, 2, 1, 1, 4, 1, 1, 6, 1, 1, 8)) ## Iterative function application: Funcall <- function(f, ...) f(...) gc 213 ## Compute log(exp(acos(cos(0)) Reduce(Funcall, list(log, exp, acos, cos), 0, right = TRUE) ## n-fold iterate of a function, functional style: Iterate <- function(f, n = 1) function(x) Reduce(Funcall, rep.int(list(f), n), x, right = TRUE) ## Continued fraction approximation to the golden ratio: Iterate(function(x) 1 + 1 / x, 30)(1) ## which is the same as cfrac(rep.int(1, 31)) ## Computing square root approximations for x as fixed points of the ## function t |-> (t + x / t) / 2, as a function of the initial value: asqrt <- function(x, n) Iterate(function(t) (t + x / t) / 2, n) asqrt(2, 30)(10) # Starting from a positive value => +sqrt(2) asqrt(2, 30)(-1) # Starting from a negative value => -sqrt(2) ## A list of all functions in the base environment: funs <- Filter(is.function, sapply(ls(baseenv()), get, baseenv())) ## Functions in base with more than 10 arguments: names(Filter(function(f) length(formals(args(f))) > 10, funs)) ## Number of functions in base with a ’...’ argument: length(Filter(function(f) any(names(formals(args(f))) %in% "..."), funs)) ## Find all objects in the base environment which are *not* functions: Filter(Negate(is.function), sapply(ls(baseenv()), get, baseenv())) gc Garbage Collection Description A call of gc causes a garbage collection to take place. gcinfo sets a flag so that automatic collection is either silent (verbose=FALSE) or prints memory usage statistics (verbose=TRUE). Usage gc(verbose = getOption("verbose"), reset=FALSE) gcinfo(verbose) Arguments verbose logical; if TRUE, the garbage collection prints statistics about cons cells and the space allocated for vectors. reset logical; if TRUE the values for maximum space used are reset to the current values. 214 gc Details A call of gc causes a garbage collection to take place. This will also take place automatically without user intervention, and the primary purpose of calling gc is for the report on memory usage. However, it can be useful to call gc after a large object has been removed, as this may prompt R to return memory to the operating system. R allocates space for vectors in multiples of 8 bytes: hence the report of "Vcells", a relict of an earlier allocator (that used a vector heap). When gcinfo(TRUE) is in force, messages are sent to the message connection at each garbage collection of the form Garbage collection 12 = 10+0+2 (level 0) ... 6.4 Mbytes of cons cells used (58%) 2.0 Mbytes of vectors used (32%) Here the last two lines give the current memory usage rounded up to the next 0.1Mb and as a percentage of the current trigger value. The first line gives a breakdown of the number of garbage collections at various levels (for an explanation see the ‘R Internals’ manual). Value gc returns a matrix with rows "Ncells" (cons cells), usually 28 bytes each on 32-bit systems and 56 bytes on 64-bit systems, and "Vcells" (vector cells, 8 bytes each), and columns "used" and "gc trigger", each also interpreted in megabytes (rounded up to the next 0.1Mb). If maxima have been set for either "Ncells" or "Vcells", a fifth column is printed giving the current limits in Mb (with NA denoting no limit). The final two columns show the maximum space used since the last call to gc(reset=TRUE) (or since R started). gcinfo returns the previous value of the flag. See Also The ‘R Internals’ manual. Memory on R’s memory management, and gctorture if you are an R developer. reg.finalizer for actions to happen at garbage collection. Examples gc() #- do it now gcinfo(TRUE) #-- in the future, show when R does it x <- integer(100000); for(i in 1:18) x <- c(x,i) gcinfo(verbose = FALSE)#-- don’t show it anymore gc(TRUE) gc(reset=TRUE) gc.time 215 gc.time Report Time Spent in Garbage Collection Description This function reports the time spent in garbage collection so far in the R session while GC timing was enabled. Usage gc.time(on = TRUE) Arguments on logical; if TRUE, GC timing is enabled. Details The timings are rounded up by the sampling interval for timing processes, and so are likely to be over-estimates. It is a primitive. Value A numerical vector of length 5 giving the user CPU time, the system CPU time, the elapsed time and children’s user and system CPU times (normally both zero), of time spent doing garbage collection whilst GC timing was enabled. Times of child processes are not available on Windows and will always be given as NA. See Also gc, proc.time for the timings for the session. Examples gc.time() 216 gctorture gctorture Torture Garbage Collector Description Provokes garbage collection on (nearly) every memory allocation. Intended to ferret out memory protection bugs. Also makes R run very slowly, unfortunately. Usage gctorture(on = TRUE) gctorture2(step, wait = step, inhibit_release = FALSE) Arguments on logical; turning it on/off. step integer; run GC every step allocations; step = 0 turns the GC torture off. wait integer; number of allocations to wait before starting GC torture. inhibit_release logical; do not release free objects for re-use: use with caution. Details Calling gctorture(TRUE) instructs the memory manager to force a full GC on every allocation. gctorture2 provides a more refined interface that allows the start of the GC torture to be deferred and also gives the option of running a GC only every step allocations. The third argument to gctorture2 is only used if R has been configured with a strict write barrier enabled. When this is the case all garbage collections are full collections, and the memory manager marks free nodes and enables checks in many situations that signal an error when a free node is used. This can greatly help in isolating unprotected values in C code. It does not detect the case where a node becomes free and is reallocated. The inhibit_release argument can be used to prevent such reallocation. This will cause memory to grow and should be used with caution and in conjunction with operating system facilities to monitor and limit process memory use. Value Previous value of first argument. Author(s) Peter Dalgaard and Luke Tierney get 217 get Return the Value of a Named Object Description Search for an R object with a given name and return it. Usage get(x, pos = -1, envir = as.environment(pos), mode = "any", inherits = TRUE) mget(x, envir, mode = "any", ifnotfound = list(function(x) stop(paste("value for ’", x, "’ not found", sep = ""), call. = FALSE)), inherits = FALSE) Arguments x a variable name (given as a character string). pos where to look for the object (see the details section); if omitted, the function will search as if the name of the object appeared unquoted in an expression. envir an alternative way to specify an environment to look in; see the ‘Details’ section. mode the mode or type of object sought: see the ‘Details’ section. inherits should the enclosing frames of the environment be searched? ifnotfound A list of values to be used if the item is not found: it will be coerced to list if necessary. Details The pos argument can specify the environment in which to look for the object in any of several ways: as an integer (the position in the search list); as the character string name of an element in the search list; or as an environment (including using sys.frame to access the currently active function calls). The envir argument is an alternative way to specify an environment, but is primarily there for back compatibility. This function looks to see if the name x has a value bound to it in the specified environment. If inherits is TRUE and a value is not found for x in the specified environment, the enclosing frames of the environment are searched until the name x is encountered. See environment and the ‘R Language Definition’ manual for details about the structure of environments and their enclosures. Warning: inherits = TRUE is the default behaviour for R but not for S. If mode is specified then only objects of that type are sought. The mode may specify one of the collections "numeric" and "function" (see mode): any member of the collection will suffice. Using a NULL environment is equivalent to using the current environment. 218 getDLLRegisteredRoutines For mget multiple values are returned in a named list. This is true even if only one value is requested. The value in mode and ifnotfound can be either the same length as the number of requested items or of length 1. The argument ifnotfound must be a list containing either the value to use if the requested item is not found or a function of one argument which will be called if the item is not found, with argument the name of the item being requested. The default value for inherits is FALSE, in contrast to the default behavior for get. mode here is a mixture of the meanings of typeof and mode:"function" covers primitive func- tions and operators, "numeric","integer","real" and "double" all refer to any numeric type, "symbol" and "name" are equivalent but "language" must be used. Value The object found. (If no object is found an error results.) Note The reverse of a <- get(nam) is assign(nam, a). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also exists, assign. Examples get("%o%") ##test mget e1 <- new.env() mget(letters, e1, ifnotfound = as.list(LETTERS)) getDLLRegisteredRoutines Reflectance Information for C/Fortran routines in a DLL Description This function allows us to query the set of routines in a DLL that are registered with R to enhance dynamic lookup, error handling when calling native routines, and potentially security in the future. This function provides a description of each of the registered routines in the DLL for the different interfaces, i.e. .C,.Call,.Fortran and .External. Usage getDLLRegisteredRoutines(dll, addNames = TRUE) getDLLRegisteredRoutines 219 Arguments dll a character string or DLLInfo object. The character string specifies the file name of the DLL of interest, and is given without the file name extension (e.g., the ‘.dll’ or ‘.so’) and with no directory/path information. So a file ‘MyPackage/libs/MyPackage.so’ would be specified as ‘MyPackage’. The DLLInfo objects can be obtained directly in calls to dyn.load and library.dynam, or can be found after the DLL has been loaded using getLoadedDLLs, which returns a list of DLLInfo objects (index-able by DLL file name). The DLLInfo approach avoids any ambiguities related to two DLLs having the same name but corresponding to files in different directories. addNames a logical value. If this is TRUE, the elements of the returned lists are named using the names of the routines (as seen by R via registration or raw name). If FALSE, these names are not computed and assigned to the lists. As a re- sult, the call should be quicker. The name information is also available in the NativeSymbolInfo objects in the lists. Details This takes the registration information after it has been registered and processed by the R internals. In other words, it uses the extended information Value A list with four elements corresponding to the routines registered for the .C, .Call, .Fortran and .External interfaces. Each element is a list with as many elements as there were routines registered for that interface. Each element identifies a routine and is an object of class NativeSymbolInfo. An object of this class has the following fields: name the registered name of the routine (not necessarily the name in the C code). address the memory address of the routine as resolved in the loaded DLL. This may be NULL if the symbol has not yet been resolved. dll an object of class DLLInfo describing the DLL. This is same for all elements returned. numParameters the number of arguments the native routine is to be called with. In the future, we will provide information about the types of the parameters also. Author(s) Duncan Temple Lang References "Writing R Extensions Manual" for symbol registration. R News, Volume 1/3, September 2001. "In search of C/C++ & Fortran Symbols" 220 getLoadedDLLs See Also getLoadedDLLs Examples dlls <- getLoadedDLLs() getDLLRegisteredRoutines(dlls[["base"]]) getDLLRegisteredRoutines("stats") getLoadedDLLs Get DLLs Loaded in Current Session Description This function provides a way to get a list of all the DLLs (see dyn.load) that are currently loaded in the R session. Usage getLoadedDLLs() Details This queries the internal table that manages the DLLs. Value An object of class "DLLInfoList" which is a list with an element corresponding to each DLL that is currently loaded in the session. Each element is an object of class "DLLInfo" which has the following entries. name the abbreviated name. path the fully qualified name of the loaded DLL. dynamicLookup a logical value indicating whether R uses only the registration information to resolve symbols or whether it searches the entire symbol table of the DLL. handle a reference to the C-level data structure that provides access to the contents of the DLL. This is an object of class "DLLHandle". Note that the class DLLInfo has an overloaded method for $ which can be used to resolve native symbols within that DLL. Therefore, one must access the R-level elements described above using [[, e.g. x[["name"]] or x[["handle"]]. Note We are starting to use the handle elements in the DLL object to resolve symbols more directly in R. getNativeSymbolInfo 221 Author(s) Duncan Temple Lang . See Also getDLLRegisteredRoutines, getNativeSymbolInfo Examples getLoadedDLLs() getNativeSymbolInfo Obtain a Description of one or more Native (C/Fortran) Symbols Description This finds and returns as comprehensive a description of one or more dynamically loaded or ‘ex- ported’ built-in native symbols. For each name, it returns information about the name of the symbol, the library in which it is located and, if available, the number of arguments it expects and by which interface it should be called (i.e .Call,.C,.Fortran, or .External). Additionally, it returns the address of the symbol and this can be passed to other C routines which can invoke. Specifically, this provides a way to explicitly share symbols between different dynamically loaded package li- braries. Also, it provides a way to query where symbols were resolved, and aids diagnosing strange behavior associated with dynamic resolution. This is vectorized in the name argument so can process multiple symbols in a single call. The result is a list that can be indexed by the given symbol names. Usage getNativeSymbolInfo(name, PACKAGE, unlist = TRUE, withRegistrationInfo = FALSE) Arguments name the name(s) of the native symbol(s) as used in a call to is.loaded, etc. Note that Fortran symbols should be supplied as-is, not wrapped in symbol.For. PACKAGE an optional argument that specifies to which DLL we restrict the search for this symbol. If this is "base", we search in the R executable itself. unlist a logical value which controls how the result is returned if the function is called with the name of a single symbol. If unlist is TRUE and the number of symbol names in name is one, then the NativeSymbolInfo object is returned. If it is FALSE, then a list of NativeSymbolInfo objects is returned. This is ignored if the number of symbols passed in name is more than one. To be compatible with earlier versions of this function, this defaults to TRUE. withRegistrationInfo a logical value indicating whether, if TRUE, to return information that was reg- istered with R about the symbol and its parameter types if such information is available, or if FALSE to return the address of the symbol. 222 getNativeSymbolInfo Details This uses the same mechanism for resolving symbols as is used in all the native interfaces (.Call, etc.). If the symbol has been explicitly registered by the DLL in which it is contained, information about the number of arguments and the interface by which it should be called will be returned. Otherwise, a generic native symbol object is returned. Value Generally, a list of NativeSymbolInfo elements whose elements can be indexed by the elements of name in the call. Each NativeSymbolInfo object is a list containing the following elements: name the name of the symbol, as given by the name argument. address if withRegistrationInfo is FALSE, this is the native memory address of the symbol which can be used to invoke the routine, and also to compare with other symbol addresses. This is an external pointer object and of class NativeSymbol. If withRegistrationInfo is TRUE and registration information is available for the symbol, then this is an object of class RegisteredNativeSymbol and is a reference to an internal data type that has access to the routine pointer and registration information. This too can be used in calls to .Call,.C,.Fortran and .External. package a list containing 3 elements: name the short form of the library name which can be used as the value of the PACKAGE argument in the different native interface functions. path the fully qualified name of the DLL. dynamicLookup a logical value indicating whether dynamic resolution is used when looking for symbols in this library, or only registered routines can be located. If the routine was explicitly registered by the dynamically loaded library, the list contains a fourth field numParameters the number of arguments that should be passed in a call to this routine. Additionally, the list will have an additional class, being CRoutine, CallRoutine, FortranRoutine or ExternalRoutine corresponding to the R interface by which it should be invoked. If any of the symbols is not found, an error is immediately raised. If name contains only one symbol name and unlist is TRUE, then the single NativeSymbolInfo is returned rather than the list containing that one element. Note One motivation for accessing this reflectance information is to be able to pass native routines to C routines as function pointers in C. This allows us to treat native routines and R functions in a similar manner, such as when passing an R function to C code that makes callbacks to that function at different points in its computation (e.g., nls). Additionally, we can resolve the symbol just once and avoid resolving it repeatedly or using the internal cache. In the future, one may be able to treat NativeSymbol objects directly as callback objects. gettext 223 Author(s) Duncan Temple Lang References For information about registering native routines, see “In Search of C/C++ & FORTRAN Routines”, R-News, volume 1, number 3, 2001, p20–23 (http://CRAN.R-project.org/doc/Rnews/). See Also getDLLRegisteredRoutines, is.loaded,.C,.Fortran,.External,.Call, dyn.load. Examples library(stats) # normally loaded getNativeSymbolInfo("dansari") getNativeSymbolInfo("hcass2") # a Fortran symbol gettext Translate Text Messages Description If Native Language Support was enabled in this build of R, attempt to translate character vectors or set where the translations are to be found. Usage gettext(..., domain = NULL) ngettext(n, msg1, msg2, domain = NULL) bindtextdomain(domain, dirname = NULL) Arguments ... One or more character vectors. domain The ‘domain’ for the translation. n a non-negative integer. msg1 the message to be used in English for n = 1. msg2 the message to be used in English for n = 0, 2, 3,.... dirname The directory in which to find translated message catalogs for the domain. 224 gettext Details If domain is NULL or "", a domain is searched for based on the namespace which contains the function calling gettext or ngettext. If a suitable domain can be found, each character string is offered for translation, and replaced by its translation into the current language if one is found. Conventionally the domain for R warning/error messages in package pkg is "R-pkg", and that for C-level messages is "pkg". For gettext, leading and trailing whitespace is ignored when looking for the translation. ngettext is used where the message needs to vary by a single integer. Translating such messages is subject to very specific rules for different languages: see the GNU Gettext Manual. The string will often contain a single instance of %d to be used in sprintf. If English is used, msg1 is returned if n == 1 and msg2 in all other cases. Value For gettext, a character vector, one element per string in .... If translation is not enabled or no domain is found or no translation is found in that domain, the original strings are returned. For ngettext, a character string. For bindtextdomain, a character string giving the current base directory, or NULL if setting it failed. See Also stop and warning make use of gettext to translate messages. xgettext for extracting translatable strings from R source files. Examples bindtextdomain("R") # non-null if and only if NLS is enabled for(n in 0:3) print(sprintf(ngettext(n, "%d variable has missing values", "%d variables have missing values"), n)) ## Not run: ## for translation, those strings should appear in R-pkg.pot as msgid "%d variable has missing values" msgid_plural "%d variables have missing values" msgstr[0] "" msgstr[1] "" ## End(Not run) miss <- c("one", "or", "another") cat(ngettext(length(miss), "variable", "variables"), paste(sQuote(miss), collapse=", "), ngettext(length(miss), "contains", "contain"), "missing values\n") ## better for translators would be to use cat(sprintf(ngettext(length(miss), getwd 225 "variable %s contains missing values\n", "variables %s contain missing values\n"), paste(sQuote(miss), collapse=", "))) getwd Get or Set Working Directory Description getwd returns an absolute filepath representing the current working directory of the R process; setwd(dir) is used to set the working directory to dir. Usage getwd() setwd(dir) Arguments dir A character string: tilde expansion will be done. Value getwd returns a character string or NULL if the working directory is not available. On Windows the path returned will use / as the path separator and be encoded in UTF-8. The path will not have a trailing / unless it is the root directory (of a drive or share on Windows). setwd returns the current directory before the change, invisibly and with the same conventions as getwd. It will give an error if it does not succeed (including if it is not implemented). Note Note that the return value is said to be an absolute filepath: there can be more than one repre- sentation of the path to a directory and on some OSes the value returned can differ after changing directories and changing back to the same directory (for example if symbolic links have been tra- versed). See Also list.files for the contents of a directory. normalizePath for a ‘canonical’ path name. Examples (WD <- getwd()) if (!is.null(WD)) setwd(WD) 226 gl gl Generate Factor Levels Description Generate factors by specifying the pattern of their levels. Usage gl(n, k, length = n*k, labels = 1:n, ordered = FALSE) Arguments n an integer giving the number of levels. k an integer giving the number of replications. length an integer giving the length of the result. labels an optional vector of labels for the resulting factor levels. ordered a logical indicating whether the result should be ordered or not. Value The result has levels from 1 to n with each value replicated in groups of length k out to a total length of length. gl is modelled on the GLIM function of the same name. See Also The underlying factor(). Examples ## First control, then treatment: gl(2, 8, labels = c("Control", "Treat")) ## 20 alternating 1s and 2s gl(2, 1, 20) ## alternating pairs of 1s and 2s gl(2, 2, 20) grep 227 grep Pattern Matching and Replacement Description grep, grepl, regexpr and gregexpr search for matches to argument pattern within each element of a character vector: they differ in the format of and amount of detail in the results. sub and gsub perform replacement of the first and all matches respectively. Usage grep(pattern, x, ignore.case = FALSE, perl = FALSE, value = FALSE, fixed = FALSE, useBytes = FALSE, invert = FALSE) grepl(pattern, x, ignore.case = FALSE, perl = FALSE, fixed = FALSE, useBytes = FALSE) sub(pattern, replacement, x, ignore.case = FALSE, perl = FALSE, fixed = FALSE, useBytes = FALSE) gsub(pattern, replacement, x, ignore.case = FALSE, perl = FALSE, fixed = FALSE, useBytes = FALSE) regexpr(pattern, text, ignore.case = FALSE, perl = FALSE, fixed = FALSE, useBytes = FALSE) gregexpr(pattern, text, ignore.case = FALSE, perl = FALSE, fixed = FALSE, useBytes = FALSE) regexec(pattern, text, ignore.case = FALSE, fixed = FALSE, useBytes = FALSE) Arguments pattern character string containing a regular expression (or character string for fixed = TRUE) to be matched in the given character vector. Coerced by as.character to a character string if possible. If a character vector of length 2 or more is supplied, the first element is used with a warning. Missing values are allowed except for regexpr and gregexpr. x, text a character vector where matches are sought, or an object which can be coerced by as.character to a character vector. ignore.case if FALSE, the pattern matching is case sensitive and if TRUE, case is ignored during matching. perl logical. Should perl-compatible regexps be used? Has priority over extended. 228 grep value if FALSE, a vector containing the (integer) indices of the matches determined by grep is returned, and if TRUE, a vector containing the matching elements themselves is returned. fixed logical. If TRUE, pattern is a string to be matched as is. Overrides all conflicting arguments. useBytes logical. If TRUE the matching is done byte-by-byte rather than character-by- character. See ‘Details’. invert logical. If TRUE return indices or values for elements that do not match. replacement a replacement for matched pattern in sub and gsub. Coerced to character if possible. For fixed = FALSE this can include backreferences "\1" to "\9" to parenthesized subexpressions of pattern. For perl = TRUE only, it can also contain "\U" or "\L" to convert the rest of the replacement to upper or lower case and "\E" to end case conversion. If a character vector of length 2 or more is supplied, the first element is used with a warning. If NA, all elements in the result corresponding to matches will be set to NA. Details Arguments which should be character strings or character vectors are coerced to character if possi- ble. Each of these functions (apart from regexec, which currently does not support Perl-style regular expressions) operates in one of three modes: 1. fixed = TRUE: use exact matching. 2. perl = TRUE: use Perl-style regular expressions. 3. fixed = FALSE, perl = FALSE: use POSIX 1003.2 extended regular expressions. See the help pages on regular expression for details of the different types of regular expressions. The two *sub functions differ only in that sub replaces only the first occurrence of a pattern whereas gsub replaces all occurrences. If replacement contains backreferences which are not defined in pattern the result is undefined (but most often the backreference is taken to be ""). For regexpr, gregexpr and regexec it is an error for pattern to be NA, otherwise NA is permitted and gives an NA match. The main effect of useBytes is to avoid errors/warnings about invalid inputs and spurious matches in multibyte locales, but for regexpr it changes the interpretation of the output. It inhibits the conversion of inputs with marked encodings, and is forced if any input is found which is marked as "bytes". Caseless matching does not make much sense for bytes in a multibyte locale, and you should expect it only to work for ASCII characters if useBytes = TRUE. As from R 2.14.0, regexpr and gregexpr with perl = TRUE allow Python-style named captures. Value grep(value = FALSE) returns an integer vector of the indices of the elements of x that yielded a match (or not, for invert = TRUE. grep 229 grep(value = TRUE) returns a character vector containing the selected elements of x (after coer- cion, preserving names but no other attributes). grepl returns a logical vector (match or not for each element of x). For sub and gsub return a character vector of the same length and with the same attributes as x (after possible coercion to character). Elements of character vectors x which are not substituted will be returned unchanged (including any declared encoding). If useBytes = FALSE a non-ASCII substituted result will often be in UTF-8 with a marked encoding (e.g. if there is a UTF-8 input, and in a multibyte locale unless fixed = TRUE). Such strings can be re-encoded by enc2native. regexpr returns an integer vector of the same length as text giving the starting position of the first match or −1 if there is none, with attribute "match.length", an integer vector giving the length of the matched text (or −1 for no match). The match positions and lengths are in characters unless useBytes = TRUE is used, when they are in bytes. If named capture is used there are further attributes "capture.start","capture.length" and "capture.names". gregexpr returns a list of the same length as text each element of which is of the same form as the return value for regexpr, except that the starting positions of every (disjoint) match are given. regexec returns a list of the same length as text each element of which is either −1 if there is no match, or a sequence of integers with the starting positions of the match and all substrings corre- sponding to parenthesized subexpressions of pattern, with attribute "match.length" an integer vector giving the lengths of the matches (or −1 for no match). Warning POSIX 1003.2 mode of gsub and gregexpr does not work correctly with repeated word-boundaries (e.g. pattern = "\b"). Use perl = TRUE for such matches (but that may not work as expected with non-ASCII inputs, as the meaning of ‘word’ is system-dependent). Performance considerations If you are doing a lot of regular expression matching, including on very long strings, you will want to consider the options used. Generally PCRE will be faster than the default regular expression engine, and fixed = TRUE faster still (especially when each pattern is matched only a few times). If you are working in a single-byte locale and have marked UTF-8 strings that are representable in that locale, convert them first as just one UTF-8 string will force all the matching to be done in Unicode, which attracts a penalty of around 3 × for the default POSIX 1003.2 mode. If you can make use of useBytes = TRUE, the strings will not be checked before matching, and the actual matching will be faster. Often byte-based matching suffices in a UTF-8 locale since byte patterns of one character never match part of another. Note Prior to R 2.11.0 there was an argument extended which could be used to select ‘basic’ regular expressions: this was often used when fixed = TRUE would be preferable. In the actual implemen- tation (as distinct from the POSIX standard) the only difference was that ‘?’, ‘+’, ‘{’, ‘|’, ‘(’, and ‘)’ were not interpreted as metacharacters. 230 grep Source The C code for POSIX-style regular expression matching has changed over the years. As from R 2.10.0 the TRE library of Ville Laurikari (http://laurikari.net/tre/) is used. From 2005 to R 2.9.2, code based on glibc was used (and before that, code from GNU grep). The POSIX standard does give some room for interpretation, especially in the handling of invalid regular expressions and the collation of character ranges, so the results will have changed slightly. For Perl-style matching PCRE (http://www.pcre.org) is used. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole (grep) See Also regular expression (aka regexp) for the details of the pattern specification. regmatches for extracting matched substrings based on the results of regexpr, gregexpr and regexec. glob2rx to turn wildcard matches into regular expressions. agrep for approximate matching. charmatch, pmatch for partial matching, match for matching to whole strings. tolower, toupper and chartr for character translations. apropos uses regexps and has more examples. grepRaw for matching raw vectors. Examples grep("[a-z]", letters) txt <- c("arm","foot","lefroo", "bafoobar") if(length(i <- grep("foo",txt))) cat("’foo’ appears at least once in\n\t",txt,"\n") i # 2 and 4 txt[i] ## Double all ’a’ or ’b’s; "\" must be escaped, i.e., ’doubled’ gsub("([ab])", "\\1_\\1_", "abc and ABC") txt <- c("The", "licenses", "for", "most", "software", "are", "designed", "to", "take", "away", "your", "freedom", "to", "share", "and", "change", "it.", "", "By", "contrast,", "the", "GNU", "General", "Public", "License", "is", "intended", "to", "guarantee", "your", "freedom", "to", "share", "and", "change", "free", "software", "--", "to", "make", "sure", "the", "software", "is", "free", "for", "all", "its", "users") ( i <- grep("[gu]", txt) ) # indices stopifnot( txt[i] == grep("[gu]", txt, value = TRUE) ) grep 231 ## Note that in locales such as en_US this includes B as the ## collation order is aAbBcCdEe ... (ot <- sub("[b-e]",".", txt)) txt[ot != gsub("[b-e]",".", txt)]#- gsub does "global" substitution txt[gsub("g","#", txt) != gsub("g","#", txt, ignore.case = TRUE)] # the "G" words regexpr("en", txt) gregexpr("e", txt) ## Using grepl() for filtering ## Find functions with argument names matching "warn": findArgs <- function(env, pattern) { nms <- ls(envir = as.environment(env)) nms <- nms[is.na(match(nms, c("F","T")))] # <-- work around "checking hack" aa <- sapply(nms, function(.) { o <- get(.) if(is.function(o)) names(formals(o)) }) iw <- sapply(aa, function(a) any(grepl(pattern, a, ignore.case=TRUE))) aa[iw] } findArgs("package:base", "warn") ## trim trailing white space str <- ’Now is the time ’ sub(’ +$’, ’’, str) ## spaces only sub(’[[:space:]]+$’, ’’, str) ## white space, POSIX-style sub(’\\s+$’, ’’, str, perl = TRUE) ## Perl-style white space ## capitalizing txt <- "a test of capitalizing" gsub("(\\w)(\\w*)", "\\U\\1\\L\\2", txt, perl=TRUE) gsub("\\b(\\w)", "\\U\\1", txt, perl=TRUE) txt2 <- "useRs may fly into JFK or laGuardia" gsub("(\\w)(\\w*)(\\w)", "\\U\\1\\E\\2\\U\\3", txt2, perl=TRUE) sub("(\\w)(\\w*)(\\w)", "\\U\\1\\E\\2\\U\\3", txt2, perl=TRUE) ## named capture notables <- c(" Ben Franklin and Jefferson Davis", "\tMillard Fillmore") # name groups ’first’ and ’last’ name.rex <- "(?[[:upper:]][[:lower:]]+) (?[[:upper:]][[:lower:]]+)" (parsed <- regexpr(name.rex, notables, perl = TRUE)) gregexpr(name.rex, notables, perl = TRUE)[[2]] parse.one <- function(res, result) { m <- do.call(rbind, lapply(seq_along(res), function(i) { if(result[i] == -1) return("") st <- attr(result, "capture.start")[i, ] substring(res[i], st, st + attr(result, "capture.length")[i, ] - 1) })) 232 grepRaw colnames(m) <- attr(result, "capture.names") m } parse.one(notables, parsed) ## Decompose a URL into its components. ## Example by LT (http://www.cs.uiowa.edu/~luke/R/regexp.html). x <- "http://stat.umn.edu:80/xyz" m <- regexec("^(([^:]+)://)?([^:/]+)(:([0-9]+))?(/.*)", x) m regmatches(x, m) ## Element 3 is the protocol, 4 is the host, 6 is the port, and 7 ## is the path. We can use this to make a function for extracting the ## parts of a URL: URL_parts <- function(x) { m <- regexec("^(([^:]+)://)?([^:/]+)(:([0-9]+))?(/.*)", x) parts <- do.call(rbind, lapply(regmatches(x, m), ‘[‘, c(3L, 4L, 6L, 7L))) colnames(parts) <- c("protocol","host","port","path") parts } URL_parts(x) grepRaw Pattern Matching for Raw Vectors Description grepRaw searches for substring pattern matches within a raw vector x. Usage grepRaw(pattern, x, offset = 1L, ignore.case = FALSE, value = FALSE, fixed = FALSE, all = FALSE, invert = FALSE) Arguments pattern raw vector containing a regular expression (or fixed pattern for fixed = TRUE) to be matched in the given raw vector. Coerced by charToRaw to a character string if possible. x a raw vector where matches are sought, or an object which can be coerced by charToRaw to a raw vector. ignore.case if FALSE, the pattern matching is case sensitive and if TRUE, case is ignored during matching. offset An integer specifying the offset from which the search should start. Must be positive. The beginning of line is defined to be at that offset so "^" will match there. value logical. Determines the return value: see ‘Value’. grepRaw 233 fixed logical. If TRUE, pattern is a pattern to be matched as is. all logical. If TRUE all matches are returned, otherwise just the first one. invert logical. If TRUE return indices or values for elements that do not match. Ignored (with a warning) unless value = TRUE. Details Unlike grep, seeks matching patterns within the raw vector x . This has implications especially in the all = TRUE case, e.g., patterns matching empty strings are inherently infinite and thus may lead to unexpected results. The argument invert is interpreted as asking to return the complement of the match, which is only meaningful for value = TRUE. Argument offset determines the start of the search, not of the complement. Note that invert = TRUE with all = TRUE will split x into pieces delimited by the pattern including leading and trailing empty strings (consequently the use of regular expressions with "^" or "$" in that case may lead to less intuitive results). Some combinations of arguments such as fixed = TRUE with value = TRUE are supported but are less meaningful. Value grepRaw(value = FALSE) returns an integer vector of the offsets at which matches have occurred. If all = FALSE then it will be either of length zero (no match) or length one (first matching position). grepRaw(value = TRUE, all = FALSE) returns a raw vector which is either empty (no match) or the matched part of x. grepRaw(value = TRUE, all = TRUE) returns a (potentially empty) list of raw vectors corre- sponding to the matched parts. Source The TRE library of Ville Laurikari (http://laurikari.net/tre/) is used except for fixed = TRUE. See Also regular expression (aka regexp) for the details of the pattern specification. grep for matching character vectors. 234 groupGeneric groupGeneric S3 Group Generic Functions Description Group generic methods can be defined for four pre-specified groups of functions, Math, Ops, Summary and Complex. (There are no objects of these names in base R, but there are in the methods package.) A method defined for an individual member of the group takes precedence over a method defined for the group as a whole. Usage ## S3 methods for group generics have prototypes: Math(x, ...) Ops(e1, e2) Complex(z) Summary(..., na.rm = FALSE) Arguments x, z, e1, e2 objects. ... further arguments passed to methods. na.rm logical: should missing values be removed? Details There are four groups for which S3 methods can be written, namely the "Math","Ops","Summary" and "Complex" groups. These are not R objects in base R, but methods can be supplied for them and base R contains factor, data.frame and difftime methods for the first three groups. (There is also a ordered method for Ops, POSIXt and Date methods for Math and Ops, package_version methods for Ops and Summary, as well as a ts method for Ops in package stats.) 1. Group "Math": • abs, sign, sqrt, floor, ceiling, trunc, round, signif • exp, log, expm1, log1p, cos, sin, tan, acos, asin, atan cosh, sinh, tanh, acosh, asinh, atanh • lgamma, gamma, digamma, trigamma • cumsum, cumprod, cummax, cummin Members of this group dispatch on x. Most members accept only one argument, but members log, round and signif accept one or two arguments, and trunc accepts one or more. groupGeneric 235 2. Group "Ops": •"+","-","*","/","^","%%","%/%" •"&","|","!" •"==","!=","<","<=",">=",">" This group contains both binary and unary operators (+,- and !): when a unary operator is encountered the Ops method is called with one argument and e2 is missing. The classes of both arguments are considered in dispatching any member of this group. For each argument its vector of classes is examined to see if there is a matching specific (preferred) or Ops method. If a method is found for just one argument or the same method is found for both, it is used. If different methods are found, there is a warning about ‘incompatible methods’: in that case or if no method is found for either argument the internal method is used. If the members of this group are called as functions, any argument names are removed to ensure that positional matching is always used. 3. Group "Summary": • all, any • sum, prod • min, max • range Members of this group dispatch on the first argument supplied. 4. Group "Complex": • Arg, Conj, Im, Mod, Re Members of this group dispatch on z. Note that a method will be used for one of these groups or one of its members only if it corresponds to a "class" attribute, as the internal code dispatches on oldClass and not on class. This is for efficiency: having to dispatch on, say, Ops.integer would be too slow. The number of arguments supplied for primitive members of the "Math" group generic methods is not checked prior to dispatch. There is no lazy evaluation of arguments for group-generic functions. Technical Details These functions are all primitive and internal generic. The details of method dispatch and variables such as .Generic are discussed in the help for UseMethod. There are a few small differences: • For the operators of group Ops, the object .Method is a length-two character vector with elements the methods selected for the left and right arguments respectively. (If no method was selected, the corresponding element is "".) • Object .Group records the group used for dispatch (if a specific method is used this is ""). Note Package methods does contain objects with these names, which it has re-used in confusing similar (but different) ways. See the help for that package. 236 gzcon References Appendix A, Classes and Methods of Chambers, J. M. and Hastie, T. J. eds (1992) Statistical Models in S. Wadsworth & Brooks/Cole. See Also methods for methods of non-internal generic functions. S4groupGeneric for group generics for S4 methods. Examples require(utils) d.fr <- data.frame(x=1:9, y=stats::rnorm(9)) class(1 + d.fr) == "data.frame" ##-- add to d.f. ... methods("Math") methods("Ops") methods("Summary") methods("Complex") # none in base R gzcon (De)compress I/O Through Connections Description gzcon provides a modified connection that wraps an existing connection, and decompresses reads or compresses writes through that connection. Standard gzip headers are assumed. Usage gzcon(con, level = 6, allowNonCompressed = TRUE) Arguments con a connection. level integer between 0 and 9, the compression level when writing. allowNonCompressed logical. When reading, should non-compressed input be allowed? Details If con is open then the modified connection is opened. Closing the wrapper connection will also close the underlying connection. Reading from a connection which does not supply a gzip magic header is equivalent to reading from the original connection if allowNonCompressed is true, otherwise an error. hexmode 237 Compressed output will contain embedded NUL bytes, and so con is not permitted to be a textConnection opened with open="w". Use a writable rawConnection to compress data into a variable. The original connection becomes unusable: any object pointing to it will now refer to the modified connection. For this reason, the new connection needs to be closed explicitly. Value An object inheriting from class "connection". This is the same connection number as supplied, but with a modified internal structure. It has binary mode. See Also gzfile Examples ## Uncompress a data file from a URL z <- gzcon(url("http://www.stats.ox.ac.uk/pub/datasets/csb/ch12.dat.gz")) # read.table can only read from a text-mode connection. raw <- textConnection(readLines(z)) close(z) dat <- read.table(raw) close(raw) dat[1:4, ] ## gzfile and gzcon can inter-work. ## Of course here one would use gzfile, but file() can be replaced by ## any other connection generator. zz <- gzfile("ex.gz", "w") cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n") close(zz) readLines(zz <- gzcon(file("ex.gz", "rb"))) close(zz) unlink("ex.gz") zz <- gzcon(file("ex2.gz", "wb")) cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n") close(zz) readLines(zz <- gzfile("ex2.gz")) close(zz) unlink("ex2.gz") hexmode Display Numbers in Hexadecimal 238 hexmode Description Convert or print integers in hexadecimal format, with as many digits as are needed to display the largest, using leading zeroes as necessary. Usage as.hexmode(x) ## S3 method for class ’hexmode’ as.character(x, ...) ## S3 method for class ’hexmode’ format(x, width = NULL, upper.case = FALSE, ...) ## S3 method for class ’hexmode’ print(x, ...) Arguments x An object, for the methods inheriting from class "hexmode". width NULL or a positive integer specifying the minimum field width to be used, with padding by leading zeroes. upper.case a logical indicating whether to use upper-case letters or lower-case letters (de- fault). ... further arguments passed to or from other methods. Details Class "hexmode" consists of integer vectors with that class attribute, used merely to ensure that they are printed in hex. If width = NULL (the default), the output is padded with leading zeroes to the smallest width needed for all the non-missing elements. as.hexmode can convert integers (of type "integer" or "double") and character vectors whose elements contain only 0-9, a-f, A-F (or are NA) to class "hexmode". There is a ! method and |,& and xor methods: these recycle their arguments to the length of the longer and then apply the operators bitwise to each element. See Also octmode, sprintf for other options in converting integers to hex, strtoi to convert hex strings to integers. Hyperbolic 239 Hyperbolic Hyperbolic Functions Description These functions give the obvious hyperbolic functions. They respectively compute the hyperbolic cosine, sine, tangent, and their inverses, arc-cosine, arc-sine, arc-tangent (or ‘area cosine’, etc). Usage cosh(x) sinh(x) tanh(x) acosh(x) asinh(x) atanh(x) Arguments x a numeric or complex vector Details These are internal generic primitive functions: methods can be defined for them individually or via the Math group generic. Branch cuts are consistent with the inverse trigonometric functions asin et seq, and agree with those defined in Abramowitz and Stegun, figure 4.7, page 86. The behaviour actually on the cuts follows the C99 standard which requires continuity coming round the endpoint in a counter-clockwise di- rection. S4 methods All are S4 generic functions: methods can be defined for them individually or via the Math group generic. References Abramowitz, M. and Stegun, I. A. (1972) Handbook of Mathematical Functions. New York: Dover. Chapter 4. Elementary Transcendental Functions: Logarithmic, Exponential, Circular and Hyper- bolic Functions See Also The trigonometric functions, cos, sin, tan, and their inverses acos, asin, atan. The logistic distribution function plogis is a shifted version of tanh() for numeric x. 240 iconv iconv Convert Character Vector between Encodings Description This uses system facilities to convert a character vector between encodings: the ‘i’ stands for ‘in- ternationalization’. Usage iconv(x, from = "", to = "", sub = NA, mark = TRUE, toRaw = FALSE) iconvlist() Arguments x A character vector, or an object to be converted to a character vector by as.character, or a list with NULL and raw elements as returned by iconv(toRaw = TRUE). from A character string describing the current encoding. to A character string describing the target encoding. sub character string. If not NA it is used to replace any non-convertible bytes in the input. (This would normally be a single character, but can be more.) If "byte", the indication is "" with the hex code of the byte. mark logical, for expert use. Should encodings be marked? toRaw logical. Should a list of raw vectors be returned rather than a character vector? Details The names of encodings and which ones are available are platform-dependent. All R platforms support "" (for the encoding of the current locale), "latin1" and "UTF-8". Generally case is ignored when specifying an encoding. On many platforms, including Windows, iconvlist provides an alphabetical list of the supported encodings. On others, the information is on the man page for iconv(5) or elsewhere in the man pages (but beware that the system command iconv may not support the same set of encodings as the C functions R calls). Unfortunately, the names are rarely valid across all platforms. Elements of x which cannot be converted (perhaps because they are invalid or because they cannot be represented in the target encoding) will be returned as NA unless sub is specified. Most versions of iconv will allow transliteration by appending ‘//TRANSLIT’ to the to encoding: see the examples. Encoding "ASCII" is also accepted, and on most systems "C" and "POSIX" are synonyms for ASCII. Any encoding bits (see Encoding) on elements of x are ignored: they will always be translated as if from from even if declared otherwise. "UTF8" will be accepted as meaning the (more correct) "UTF-8". iconv 241 Value If toRaw = FALSE (the default), the value is a character vector of the same length and the same attributes as x (after conversion to a character vector). If mark = TRUE (the default) the elements of the result have a declared encoding if from is "latin1" or "UTF-8", or if from = "" and the current locale’s encoding is detected as Latin-1 or UTF-8. If toRaw = TRUE, the value is a vector of the same length and the same attributes as x whose elements are either NULL (if conversion fails) or a raw vector. For iconvlist(), a character vector (typically of a few hundred elements). Implementation Details There are three main implementations of iconv in use. ‘glibc’ (as used on Linux) contains one. Several platforms supply GNU ‘libiconv’, including Mac OS X, FreeBSD and Cygwin. On Win- dows we use a version of Yukihiro Nakadaira’s ‘win_iconv’, which is based on Windows’ code- pages. All three have iconvlist, ignore case in encoding names and support ‘//TRANSLIT’ (but with different results, and for ‘win_iconv’ currently a ‘best fit’ strategy is used except for to = "ASCII"). Most commercial Unixes contain an implemetation of iconv but none we have encountered have supported the encoding names we need: the “R Installation and Administration Manual” recom- mends installing GNU ‘libiconv’ on Solaris and AIX, for example. There are other implementations, e.g. NetBSD uses one from the Citrus project (which does not support ‘//TRANSLIT’) and there is an older FreeBSD port (‘libiconv’ is usually used there): it has not been reported whether or not these work with R. See Also localeToCharset, file. Examples ## In principle, not all systems have iconvlist try(utils::head(iconvlist(), n = 50)) ## Not run: ## convert from Latin-2 to UTF-8: two of the glibc iconv variants. iconv(x, "ISO_8859-2", "UTF-8") iconv(x, "LATIN2", "UTF-8") ## End(Not run) ## Both x below are in latin1 and will only display correctly in a ## locale that can represent and display latin1. x <- "fa\xE7ile" Encoding(x) <- "latin1" x charToRaw(xx <- iconv(x, "latin1", "UTF-8")) xx iconv(x, "latin1", "ASCII") # NA 242 icuSetCollate iconv(x, "latin1", "ASCII", "?") # "fa?ile" iconv(x, "latin1", "ASCII", "") # "faile" iconv(x, "latin1", "ASCII", "byte") # "faile" ## Extracts from old R help files (they are nowadays in UTF-8) x <- c("Ekstr\xf8m", "J\xf6reskog", "bi\xdfchen Z\xfcrcher") Encoding(x) <- "latin1" x try(iconv(x, "latin1", "ASCII//TRANSLIT")) # platform-dependent iconv(x, "latin1", "ASCII", sub="byte") ## and for Windows’ ’Unicode’ str(xx <- iconv(x, "latin1", "UTF-16LE", toRaw = TRUE)) iconv(xx, "UTF-16LE", "UTF-8") icuSetCollate Setup Collation by ICU Description Controls the way collation is done by ICU (an optional part of the R build). Usage icuSetCollate(...) Arguments ... Named arguments, see ‘Details’. Details Optionally, R can be built to collate character strings by ICU (http://site.icu-project.org). For such systems, icuSetCollate can be used to tune the way collation is done. On other builds calling this function does nothing, with a warning. Possible arguments are locale: A character string such as "da_DK" giving the country whose collation rules are to be used. If present, this should be the first argument. case_first:"upper","lower" or "default", asking for upper- or lower-case characters to be sorted first. The default is usually lower-case first, but not in all languages (see the Danish example). alternate_handling: Controls the handling of ‘variable’ characters (mainly punctuation and symbols). Possible values are "non_ignorable" (primary strength) and "shifted" (qua- ternary strength). strength: Which components should be used? Possible values "primary","secondary", "tertiary" (default), "quaternary" and "identical". identical 243 french_collation: In a French locale the way accents affect collation is from right to left, whereas in most other locales it is from left to right. Possible values "on","off" and "default". normalization: Should strings be normalized? Possible values are "on" and "off" (default). This affects the collation of composite characters. case_level: An additional level between secondary and tertiary, used to distinguish large and small Japanese Kana characters. Possible values "on" and "off" (default). hiragana_quaternary: Possible values "on" (sort Hiragana first at quaternary level) and "off". Only the first three are likely to be of interest except to those with a detailed understanding of collation and specialized requirements. Some examples are case_level="on", strength="primary" to ignore accent differences and alternate_handling="shifted" to ignore space and punctuation characters. Note that these settings have no effect if collation is set to the C locale, unless locale is specified. Note As from R 2.9.0, ICU is used by default wherever it is available: this include Mac OS >= 10.4 and many Linux installations. See Also Comparison, sort The ICU user guide chapter on collation (http://userguide.icu-project.org/collation). Examples ## these examples depend on having ICU available, and on the locale x <- c("Aarhus", "aarhus", "safe", "test", "Zoo") sort(x) icuSetCollate(case_first="upper"); sort(x) icuSetCollate(case_first="lower"); sort(x) icuSetCollate(locale="da_DK", case_first="default"); sort(x) icuSetCollate(locale="et_EE"); sort(x) identical Test Objects for Exact Equality Description The safe and reliable way to test two objects for being exactly equal. It returns TRUE in this case, FALSE in every other case. Usage identical(x, y, num.eq = TRUE, single.NA = TRUE, attrib.as.set = TRUE, ignore.bytecode = TRUE) 244 identical Arguments x, y any R objects. num.eq logical indicating if (double and complex non-NA) numbers should be compared using == (‘equal’), or by bitwise comparison. The latter (non-default) differen- tiates between -0 and +0. single.NA logical indicating if there is conceptually just one numeric NA and one NaN; single.NA = FALSE differentiates bit patterns. attrib.as.set logical indicating if attributes of x and y should be treated as unordered tagged pairlists (“sets”); this currently also applies to slots of S4 objects. It may well be too strict to set attrib.as.set = FALSE. ignore.bytecode logical indicating if byte code should be ignored when comparing functions. Details A call to identical is the way to test exact equality in if and while statements, as well as in logical expressions that use && or ||. In all these applications you need to be assured of getting a single logical value. Users often use the comparison operators, such as == or !=, in these situations. It looks natural, but it is not what these operators are designed to do in R. They return an object like the arguments. If you expected x and y to be of length 1, but it happened that one of them wasn’t, you will not get a single FALSE. Similarly, if one of the arguments is NA, the result is also NA. In either case, the expression if(x == y).... won’t work as expected. The function all.equal is also sometimes used to test equality this way, but was intended for something different: it allows for small differences in numeric results. The computations in identical are also reliable and usually fast. There should never be an error. The only known way to kill identical is by having an invalid pointer at the C level, generating a memory fault. It will usually find inequality quickly. Checking equality for two large, complicated objects can take longer if the objects are identical or nearly so, but represent completely independent copies. For most applications, however, the computational cost should be negligible. If single.NA is true, as by default, identical sees NaN as different from NA_real_, but all NaNs are equal (and all NA of the same type are equal). Character strings are regarded as identical if they are in different marked encodings but would agree when translated to UTF-8. If attrib.as.set is true, as by default, comparison of attributes view them as a set (and not a vector, so order is not tested). If ignore.bytecode is true (the default), the compiled bytecode of a function (see cmpfun) will be ignored in the comparison. If it is false, functions will compare equal only if they are copies of the same compiled object (or both are uncompiled). To check whether two different compiles are equal, you should compare the results of disassemble(). Note that identical(x,y,FALSE,FALSE,FALSE,FALSE) pickily tests for very exact equality. Value A single logical value, TRUE or FALSE, never NA and never anything other than a single value. identical 245 Author(s) John Chambers and R Core References Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also all.equal for descriptions of how two objects differ; Comparison for operators that generate ele- mentwise comparisons. isTRUE is a simple wrapper based on identical. Examples identical(1, NULL) ## FALSE -- don’t try this with == identical(1, 1.) ## TRUE in R (both are stored as doubles) identical(1, as.integer(1)) ## FALSE, stored as different types x <- 1.0; y <- 0.99999999999 ## how to test for object equality allowing for numeric fuzz : (E <- all.equal(x,y)) isTRUE(E) # which is simply defined to just use identical(TRUE, E) ## If all.equal thinks the objects are different, it returns a ## character string, and the above expression evaluates to FALSE ## even for unusual R objects : identical(.GlobalEnv, environment()) ### ------- Pickyness Flags : ----------------------------- ## the infamous example: identical(0., -0.) # TRUE, i.e. not differentiated identical(0., -0., num.eq = FALSE) ## similar: identical(NaN, -NaN) # TRUE identical(NaN, -NaN, single.NA=FALSE) # differ on bit-level ## for functions: f <- function(x) x f g <- compiler::cmpfun(f) g identical(f, g) identical(f, g, ignore.bytecode=FALSE) 246 ifelse identity Identity Function Description A trivial identity function returning its argument. Usage identity(x) Arguments x an R object. ifelse Conditional Element Selection Description ifelse returns a value with the same shape as test which is filled with elements selected from either yes or no depending on whether the element of test is TRUE or FALSE. Usage ifelse(test, yes, no) Arguments test an object which can be coerced to logical mode. yes return values for true elements of test. no return values for false elements of test. Details If yes or no are too short, their elements are recycled. yes will be evaluated if and only if any element of test is true, and analogously for no. Missing values in test give missing values in the result. Value A vector of the same length and attributes (including dimensions and "class") as test and data values from the values of yes or no. The mode of the answer will be coerced from logical to accommodate first any values taken from yes and then any values taken from no. integer 247 Warning The mode of the result may depend on the value of test (see the examples), and the class attribute (see oldClass) of the result is taken from test and may be inappropriate for the values selected from yes and no. Sometimes it is better to use a construction such as (tmp <- yes; tmp[!test] <- no[!test]; tmp), possibly extended to handle missing values in test. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also if. Examples x <- c(6:-4) sqrt(x) #- gives warning sqrt(ifelse(x >= 0, x, NA)) # no warning ## Note: the following also gives the warning ! ifelse(x >= 0, sqrt(x), NA) ## example of different return modes: yes <- 1:3 no <- pi^(0:3) typeof(ifelse(NA, yes, no)) # logical typeof(ifelse(TRUE, yes, no)) # integer typeof(ifelse(FALSE, yes, no)) # double integer Integer Vectors Description Creates or tests for objects of type "integer". Usage integer(length = 0) as.integer(x, ...) is.integer(x) 248 integer Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. Details Integer vectors exist so that data can be passed to C or Fortran code which expects them, and so that (small) integer data can be represented exactly and compactly. Note that current implementations of R use 32-bit integers for integer vectors, so the range of representable integers is restricted to about ±2 × 109: doubles can hold much larger integers exactly. Value integer creates a integer vector of the specified length. Each element of the vector is equal to 0. as.integer attempts to coerce its argument to be of integer type. The answer will be NA unless the coercion succeeds. Real values larger in modulus than the largest integer are coerced to NA (unlike S which gives the most extreme integer of the same sign). Non-integral numeric values are truncated towards zero (i.e., as.integer(x) equals trunc(x) there), and imaginary parts of complex numbers are discarded (with a warning). Character strings containing optional whitespace followed by either a decimal representation or a hexadecimal representation (starting with 0x or 0X) can be converted, as well as any allowed by the platform for real numbers. Like as.vector it strips attributes including names. (To ensure that an object x is of integer type without stripping attributes, use storage.mode(x) <- "integer".) is.integer returns TRUE or FALSE depending on whether its argument is of integer type or not, unless it is a factor when it returns FALSE. Note is.integer(x) does not test if x contains integer numbers! For that, use round, as in the function is.wholenumber(x) in the examples. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also numeric, storage.mode. round (and ceiling and floor on that help page) to convert to integral values. interaction 249 Examples ## as.integer() truncates: x <- pi * c(-1:1,10) as.integer(x) is.integer(1) # is FALSE ! is.wholenumber <- function(x, tol = .Machine$double.eps^0.5) abs(x - round(x)) < tol is.wholenumber(1) # is TRUE (x <- seq(1,5, by=0.5) ) is.wholenumber( x ) #--> TRUE FALSE TRUE ... interaction Compute Factor Interactions Description interaction computes a factor which represents the interaction of the given factors. The result of interaction is always unordered. Usage interaction(..., drop = FALSE, sep = ".", lex.order = FALSE) Arguments ... the factors for which interaction is to be computed, or a single list giving those factors. drop if drop is TRUE, unused factor levels are dropped from the result. The default is to retain all factor levels. sep string to construct the new level labels by joining the constituent ones. lex.order logical indicating if the order of factor concatenation should be lexically or- dered. Value A factor which represents the interaction of the given factors. The levels are labelled as the levels of the individual factors joined by sep which is . by default. By default, when lex.order = FALSE, the levels are ordered so the level of the first factor varies fastest, then the second and so on. This is the reverse of lexicographic ordering (which you can get by lex.order = TRUE), and differs from :. (It is done this way for compatibility with S.) References Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. 250 interactive See Also factor;: where f:g is similar to interaction(f, g, sep=":") when f and g are factors. Examples a <- gl(2, 4, 8) b <- gl(2, 2, 8, labels = c("ctrl", "treat")) s <- gl(2, 1, 8, labels = c("M", "F")) interaction(a, b) interaction(a, b, s, sep = ":") stopifnot(identical(a:s, interaction(a, s, sep = ":", lex.order = TRUE)), identical(a:s:b, interaction(a, s, b, sep = ":", lex.order = TRUE))) interactive Is R Running Interactively? Description Return TRUE when R is being used interactively and FALSE otherwise. Usage interactive() Details An interactive R session is one in which it is assumed that there is a human operator to interact with, so for example R can prompt for corrections to incorrect input or ask what to do next or if it is OK to move to the next plot. GUI consoles will arrange to start R in an interactive session. When R is run in a terminal (via Rterm.exe on Windows), it assumes that it is interactive if ‘stdin’ is connected to a (pseudo- )terminal and not if ‘stdin’ is redirected to a file or pipe. Command-line options ‘--interactive’ (Unix) and ‘--ess’ (Windows, Rterm.exe) override the default assumption. (On a Unix-alike, whether the readline command-line editor is used is not overridden by ‘--interactive’.) Embedded uses of R can set a session to be interactive or not. Internally, whether a session is interactive determines • how some errors are handled and reported, e.g. see stop and options("showWarnCalls"). • whether one of ‘--save’, ‘--no-save’ or ‘--vanilla’ is required, and if R ever asks whether to save the workspace. • the choice of default graphics device launched when needed and by dev.new: see options("device") • whether graphics devices ever ask for confirmation of a new page. In addition, R’s own R code makes use of interactive(): for example help, debugger and install.packages do. Internal 251 Note This is a primitive function. See Also source,.First Examples .First <- function() if(interactive()) x11() Internal Call an Internal Function Description .Internal performs a call to an internal code which is built in to the R interpreter. Only true R wizards should even consider using this function, and only R developers can add to the list of internal functions. Usage .Internal(call) Arguments call a call expression See Also .Primitive,.External (the nearest equivalent available to users). InternalMethods Internal Generic Functions Description Many R-internal functions are generic and allow methods to be written for. 252 invisible Details The following primitive and internal functions are generic, i.e., you can write methods for them: [,[[, $,[<-,[[<-, $<-, length, length<-, dimnames, dimnames<-, dim, dim<-, names, names<-, levels<-, c, unlist, cbind, rbind, as.character, as.complex, as.double, as.integer, as.logical, as.raw, as.vector, is.array, is.matrix, is.na, is.nan, is.numeric, rep, seq.int (which dispatches methods for "seq") and xtfrm In addition, is.name is a synonym for is.symbol and dispatches methods for the latter. Note that all of the group generic functions are also internal/primitive and allow methods to be written for them. .S3PrimitiveGenerics is a character vector listing the primitives which are internal generic and not group generic. Currently as.vector, cbind, rbind and unlist are the internal non-primitive functions which are internally generic. For efficiency, internal dispatch only occurs on objects, that is those for which is.object returns true. See Also methods for the methods which are available. invisible Change the Print Mode to Invisible Description Return a (temporarily) invisible copy of an object. Usage invisible(x) Arguments x an arbitrary R object. Details This function can be useful when it is desired to have functions return values which can be assigned, but which do not print when they are not assigned. This is a primitive function. is.finite 253 References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also withVisible, return, function. Examples # These functions both return their argument f1 <- function(x) x f2 <- function(x) invisible(x) f1(1)# prints f2(1)# does not is.finite Finite, Infinite and NaN Numbers Description is.finite and is.infinite return a vector of the same length as x, indicating which elements are finite (not infinite and not missing) or infinite. Inf and -Inf are positive and negative infinity whereas NaN means ‘Not a Number’. (These apply to numeric values and real and imaginary parts of complex values but not to values of integer vectors.) Inf and NaN are reserved words in the R language. Usage is.finite(x) is.infinite(x) Inf NaN is.nan(x) Arguments x R object to be tested: the default methods handle atomic vectors. Details is.finite returns a vector of the same length as x the jth element of which is TRUE if x[j] is finite (i.e., it is not one of the values NA, NaN, Inf or -Inf) and FALSE otherwise. Complex numbers are finite if both the real and imaginary parts are. is.infinite returns a vector of the same length as x the jth element of which is TRUE if x[j] is infinite (i.e., equal to one of Inf or -Inf) and FALSE otherwise. This will be false unless x is numeric or complex. Complex numbers are infinite if either the real or the imaginary part is. 254 is.finite is.nan tests if a numeric value is NaN. Do not test equality to NaN, or even use identical, since systems typically have many different NaN values. One of these is used for the numeric missing value NA, and is.nan is false for that value. A complex number is regarded as NaN if either the real or imaginary part is NaN but not NA. All elements of logical, integer and raw vectors are considered not to be NaN. All three functions accept NULL as input and return a length zero result. The default methods accept character and raw vectors, and return FALSE for all entries. Prior to R version 2.14.0 they accepted all input, returning FALSE for most non-numeric values; cases which are not atomic vectors are now signalled as errors. All three functions are generic: you can write methods to handle specific classes of objects, see InternalMethods. Value A logical vector of the same length as x: dim, dimnames and names attributes are preserved. Note In R, basically all mathematical functions (including basic Arithmetic), are supposed to work properly with +/- Inf and NaN as input or output. The basic rule should be that calls and relations with Infs really are statements with a proper mathematical limit. Computations involving NaN will return NaN or perhaps NA: which of those two is not guaranteed and may depend on the R platform (since compilers may re-order computations). References The IEC 60559 standard, also known as the ANSI/IEEE 754 Floating-Point Standard. http://en.wikipedia.org/wiki/NaN. D. Goldberg (1991) What Every Computer Scientist Should Know about Floating-Point Arithmetic ACM Computing Surveys, 23(1). Postscript version available at http://www.validlab.com/goldberg/paper.ps Extended PDF version at http://www.validlab.com/goldberg/paper.pdf The C99 function isfinite is used for is.finite if available. See Also NA,‘Not Available’ which is not a number as well, however usually used for missing values and applies to many modes, not just numeric and complex. Arithmetic, double. Examples pi / 0 ## = Inf a non-zero number divided by zero creates infinity 0 / 0 ## = NaN 1/0 + 1/0 # Inf is.function 255 1/0 - 1/0 # NaN stopifnot( 1/0 == Inf, 1/Inf == 0 ) sin(Inf) cos(Inf) tan(Inf) is.function Is an Object of Type (Primitive) Function? Description Checks whether its argument is a (primitive) function. Usage is.function(x) is.primitive(x) Arguments x an R object. Details is.primitive(x) tests if x is a primitive function (either a "builtin" or "special" as described for typeof)? It is a primitive function. Value TRUE if x is a (primitive) function, and FALSE otherwise. Examples is.function(1) # FALSE is.function(is.primitive) # TRUE: it is a function, but .. is.primitive(is.primitive) # FALSE:it’s not a primitive one, whereas is.primitive(is.function) # TRUE: that one *is* 256 is.object is.language Is an Object a Language Object? Description is.language returns TRUE if x is a variable name, a call, or an expression. Usage is.language(x) Arguments x object to be tested. Note This is a primitive function. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Examples ll <- list(a = expression(x^2 - 2*x + 1), b = as.name("Jim"), c = as.expression(exp(1)), d = call("sin", pi)) sapply(ll, typeof) sapply(ll, mode) stopifnot(sapply(ll, is.language)) is.object Is an Object ‘internally classed’? Description A function rather for internal use. It returns TRUE if the object x has the R internal OBJECT bit set, and FALSE otherwise. The OBJECT bit is set when a "class" attribute is added and removed when that attribute is removed, so this is a very efficient way to check if an object has a class attribute. (S4 objects always should.) Usage is.object(x) is.R 257 Arguments x object to be tested. Note This is a primitive function. See Also class, and methods. isS4. Examples is.object(1) # FALSE is.object(as.factor(1:3)) # TRUE is.R Are we using R, rather than S? Description Test if running under R. Usage is.R() Details The function has been written such as to correctly run in all versions of R, S and S-PLUS. In order for code to be runnable in both R and S dialects previous to S-PLUS 8.0, your code must either define is.R or use it as if (exists("is.R") && is.function(is.R) && is.R()) { ## R-specific code } else { ## S-version of code } Value is.R returns TRUE if we are using R and FALSE otherwise. See Also R.version, system. 258 is.recursive Examples x <- stats::runif(20); small <- x < 0.4 ## In the early years of R, ’which()’ only existed in R: if(is.R()) which(small) else seq(along=small)[small] is.recursive Is an Object Atomic or Recursive? Description is.atomic returns TRUE if x is an atomic vector (or NULL) and FALSE otherwise. is.recursive returns TRUE if x has a recursive (list-like) structure and FALSE otherwise. Usage is.atomic(x) is.recursive(x) Arguments x object to be tested. Details is.atomic is true for the atomic vector types ("logical","integer","numeric","complex", "character" and "raw") and NULL. Most types of objects are regarded as recursive, except for atomic vector types, NULL and symbols (as given by as.name). These are primitive functions. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also is.list, is.language, etc, and the demo("is.things"). is.single 259 Examples require(stats) is.a.r <- function(x) c(is.atomic(x), is.recursive(x)) is.a.r(c(a=1,b=3)) # TRUE FALSE is.a.r(list()) # FALSE TRUE - a list is a list is.a.r(list(2)) # FALSE TRUE is.a.r(lm) # FALSE TRUE is.a.r(y ~ x) # FALSE TRUE is.a.r(expression(x+1)) # FALSE TRUE (nowadays) is.single Is an Object of Single Precision Type? Description is.single reports an error. There are no single precision values in R. Usage is.single(x) Arguments x object to be tested. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. is.unsorted Test if an Object is Not Sorted Description Test if an object is not sorted, without the cost of sorting it. Usage is.unsorted(x, na.rm = FALSE, strictly = FALSE) 260 ISOdatetime Arguments x an R object with a class or a numeric, complex, character or logical vector. na.rm logical. Should missing values be removed before checking? strictly logical indicating if the check should be for strictly increasing values. Value A length-one logical value. All objects of length 0 or 1 are sorted: the result will be NA for objects of length 2 or more except for atomic vectors and objects with a class (where the >= or > method is used). See Also sort, order. ISOdatetime Date-time Conversion Functions from Numeric Representations Description Convenience wrappers to create date-times from numeric representations. Usage ISOdatetime(year, month, day, hour, min, sec, tz = "") ISOdate(year, month, day, hour = 12, min = 0, sec = 0, tz = "GMT") Arguments year, month, day numerical values to specify a day. hour, min, sec numerical values for a time within a day. Fractional seconds are allowed. tz A timezone specification to be used for the conversion. "" is the current time zone and "GMT" is UTC. Details ISOdatetime and ISOdate are convenience wrappers for strptime that differ only in their defaults and that ISOdate sets UTC as the timezone. For dates without times it would normally be better to use the "Date" class. The main arguments will be recycled using the usual recycling rules. Value An object of class "POSIXct". isS4 261 See Also DateTimeClasses for details of the date-time classes; strptime for conversions from character strings. isS4 Test for an S4 object Description Tests whether the object is an instance of an S4 class. Usage isS4(object) asS4(object, flag = TRUE, complete = TRUE) asS3(object, flag = TRUE, complete = TRUE) Arguments object Any R object. flag, complete Optional arguments to indicate direction of conversion and whether conversion to S3 is completed. Not usually needed, but see the details section. Details Note that isS4 does not rely on the methods package, so in particular it can be used to detect the need to require that package. (The other functions do depend on methods.) asS3 uses the value of complete to control whether an attempt is made to transform object into a valid object of the implied S3 class. If complete is TRUE, then an object from an S4 class extending an S3 class will be transformed into an S3 object with the corresponding S3 class (see S3Part). This includes classes extending the pseudo-classes array and matrix: such objects will have their class attribute set to NULL. Value isS4 always returns TRUE or FALSE according to whether the internal flag marking an S4 object has been turned on for this object. asS4 and asS3 will turn this flag on or off, and asS3 will set the class from the objects .S3Class slot if one exists. Note that asS3 will not turn the object into an S3 object unless there is a valid conversion; that is, an object of type other than "S4" for which the S4 object is an extension, unless argument complete is FALSE. See Also is.object for a more general test; Methods for general information on S4. 262 isSymmetric Examples isS4(pi) # FALSE isS4(getClass("MethodDefinition")) # TRUE isSymmetric Test if a Matrix or other Object is Symmetric Description Generic function to test if object is symmetric or not. Currently only a matrix method is imple- mented. Usage isSymmetric(object, ...) ## S3 method for class ’matrix’ isSymmetric(object, tol = 100 * .Machine$double.eps, ...) Arguments object any R object; a matrix for the matrix method. tol numeric scalar >= 0. Smaller differences are not considered, see all.equal.numeric. ... further arguments passed to methods; the matrix method passes these to all.equal. Details The matrix method is used inside eigen by default to test symmetry of matrices up to rounding error, using all.equal. It might not be appropriate in all situations. Note that a matrix is only symmetric if its rownames and colnames are identical. Value logical indicating if object is symmetric or not. See Also eigen which calls isSymmetric when its symmetric argument is missing. Examples isSymmetric(D3 <- diag(3)) # -> TRUE D3[2,1] <- 1e-100 D3 isSymmetric(D3) # TRUE isSymmetric(D3, tol = 0) # FALSE for zero-tolerance jitter 263 jitter ‘Jitter’ (Add Noise) to Numbers Description Add a small amount of noise to a numeric vector. Usage jitter(x, factor=1, amount = NULL) Arguments x numeric vector to which jitter should be added. factor numeric amount numeric; if positive, used as amount (see below), otherwise, if = 0 the default is factor * z/50. Default (NULL): factor * d/5 where d is about the smallest difference between x values. Details The result, say r, is r <- x + runif(n, -a, a) where n <- length(x) and a is the amount argument (if specified). Let z <- max(x) - min(x) (assuming the usual case). The amount a to be added is either provided as positive argument amount or otherwise computed from z, as follows: If amount == 0, we set a <- factor * z/50 (same as S). If amount is NULL (default), we set a <- factor * d/5 where d is the smallest difference between adjacent unique (apart from fuzz) x values. Value jitter(x,...) returns a numeric of the same length as x, but with an amount of noise added in order to break ties. Author(s) Werner Stahel and Martin Maechler, ETH Zurich References Chambers, J. M., Cleveland, W. S., Kleiner, B. and Tukey, P.A. (1983) Graphical Methods for Data Analysis. Wadsworth; figures 2.8, 4.22, 5.4. Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. 264 kappa See Also rug which you may want to combine with jitter. Examples round(jitter(c(rep(1,3), rep(1.2, 4), rep(3,3))), 3) ## These two ’fail’ with S-plus 3.x: jitter(rep(0, 7)) jitter(rep(10000,5)) kappa Compute or Estimate the Condition Number of a Matrix Description The condition number of a regular (square) matrix is the product of the norm of the matrix and the norm of its inverse (or pseudo-inverse), and hence depends on the kind of matrix-norm. kappa() computes by default (an estimate of) the 2-norm condition number of a matrix or of the R matrix of a QR decomposition, perhaps of a linear fit. The 2-norm condition number can be shown to be the ratio of the largest to the smallest non-zero singular value of the matrix. rcond() computes an approximation of the reciprocal condition number, see the details. Usage kappa(z, ...) ## Default S3 method: kappa(z, exact = FALSE, norm = NULL, method = c("qr", "direct"), ...) ## S3 method for class ’lm’ kappa(z, ...) ## S3 method for class ’qr’ kappa(z, ...) kappa.tri(z, exact = FALSE, LINPACK = TRUE, norm=NULL, ...) rcond(x, norm = c("O","I","1"), triangular = FALSE, ...) Arguments z,x A matrix or a the result of qr or a fit from a class inheriting from "lm". exact logical. Should the result be exact? norm character string, specifying the matrix norm with respect to which the condition number is to be computed, see also norm. For rcond, the default is "O", meaning the One- or 1-norm. The (currently only) other possible value is "I" for the infinity norm. kappa 265 method character string, specifying the method to be used; "qr" is default for back- compatibility, mainly. triangular logical. If true, the matrix used is just the lower triangular part of z. LINPACK logical. If true and z is not complex, the Linpack routine dtrco() is called; otherwise the relevant Lapack routine is. ... further arguments passed to or from other methods; for kappa.*(), notably LINPACK when norm is not "2". Details For kappa(), if exact = FALSE (the default) the 2-norm condition number is estimated by a cheap approximation. Following S, by default, this uses the LINPACK routine dtrco(). However, in R (or S) the exact calculation (via svd) is also likely to be quick enough. Note that the 1- and Inf-norm condition numbers are much faster to calculate, and rcond() com- putes these reciprocal condition numbers, also for complex matrices, using standard Lapack rou- tines. kappa and rcond are different interfaces to partly identical functionality. kappa.tri is an internal function called by kappa.qr. Value The condition number, kappa, or an approximation if exact = FALSE. Author(s) The design was inspired by (but differs considerably from) the S function of the same name de- scribed in Chambers (1992). References Chambers, J. M. (1992) Linear models. Chapter 4 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. See Also norm; svd for the singular value decomposition and qr for the QR one. Examples kappa(x1 <- cbind(1,1:10))# 15.71 kappa(x1, exact = TRUE) # 13.68 kappa(x2 <- cbind(x1,2:11))# high! [x2 is singular!] hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") } sv9 <- svd(h9 <- hilbert(9))$ d kappa(h9)# pretty high! kappa(h9, exact = TRUE) == max(sv9) / min(sv9) kappa(h9, exact = TRUE) / kappa(h9) # .677 (i.e., rel.error = 32%) 266 kronecker kronecker Kronecker Products on Arrays Description Computes the generalised kronecker product of two arrays, X and Y. kronecker(X, Y) returns an array A with dimensions dim(X) * dim(Y). Usage kronecker(X, Y, FUN = "*", make.dimnames = FALSE, ...) X %x% Y Arguments X A vector or array. Y A vector or array. FUN a function; it may be a quoted string. make.dimnames Provide dimnames that are the product of the dimnames of X and Y. ... optional arguments to be passed to FUN. Details If X and Y do not have the same number of dimensions, the smaller array is padded with dimensions of size one. The returned array comprises submatrices constructed by taking X one term at a time and expanding that term as FUN(x, Y, ...). %x% is an alias for kronecker (where FUN is hardwired to "*"). Author(s) Jonathan Rougier References Shayle R. Searle (1982) Matrix Algebra Useful for Statistics. John Wiley and Sons. See Also outer, on which kronecker is built and %*% for usual matrix multiplication. l10n_info 267 Examples # simple scalar multiplication ( M <- matrix(1:6, ncol=2) ) kronecker(4, M) # Block diagonal matrix: kronecker(diag(1, 3), M) # ask for dimnames fred <- matrix(1:12, 3, 4, dimnames=list(LETTERS[1:3], LETTERS[4:7])) bill <- c("happy" = 100, "sad" = 1000) kronecker(fred, bill, make.dimnames = TRUE) bill <- outer(bill, c("cat"=3, "dog"=4)) kronecker(fred, bill, make.dimnames = TRUE) l10n_info Localization Information Description Report on localization information. Usage l10n_info() Value A list with three logical components: MBCS If a multi-byte character set in use? UTF-8 Is this a UTF-8 locale? Latin-1 Is this a Latin-1 locale? See Also Sys.getlocale, localeconv Examples l10n_info() 268 lapply labels Find Labels from Object Description Find a suitable set of labels from an object for use in printing or plotting, for example. A generic function. Usage labels(object, ...) Arguments object Any R object: the function is generic. ... further arguments passed to or from other methods. Value A character vector or list of such vectors. For a vector the results is the names or seq_along(x) and for a data frame or array it is the dimnames (with NULL expanded to seq_len(d[i]). References Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. lapply Apply a Function over a List or Vector Description lapply returns a list of the same length as X, each element of which is the result of applying FUN to the corresponding element of X. sapply is a user-friendly version and wrapper of lapply by default returning a vector, matrix or, if simplify="array", an array if appropriate, by applying simplify2array(). sapply(x, f, simplify=FALSE, USE.NAMES=FALSE) is the same as lapply(x,f). vapply is similar to sapply, but has a pre-specified type of return value, so it can be safer (and sometimes faster) to use. replicate is a wrapper for the common use of sapply for repeated evaluation of an expression (which will usually involve random number generation). simplify2array() is the utility called from sapply() when simplify is not false and is similarly called from mapply(). lapply 269 Usage lapply(X, FUN, ...) sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE) vapply(X, FUN, FUN.VALUE, ..., USE.NAMES = TRUE) replicate(n, expr, simplify = "array") simplify2array(x, higher=TRUE) Arguments X a vector (atomic or list) or an expression object. Other objects (including classed objects) will be coerced by base::as.list. FUN the function to be applied to each element of X: see ‘Details’. In the case of functions like +,%*%, the function name must be backquoted or quoted. ... optional arguments to FUN. simplify logical or character string; should the result be simplified to a vector, matrix or higher dimensional array if possible? For sapply it must be named and not abbreviated. The default value, TRUE, returns a vector or matrix if appropri- ate, whereas if simplify = "array" the result may be an array of “rank” (=length(dim(.))) one higher than the result of FUN(X[[i]]). USE.NAMES logical; if TRUE and if X is character, use X as names for the result unless it had names already. Since this argument follows ... its name cannot be abbreviated. FUN.VALUE a (generalized) vector; a template for the return value from FUN. See ‘Details’. n integer: the number of replications. expr the expression (language object, usually a call) to evaluate repeatedly. x a list, typically returned from lapply(). higher logical; if true, simplify2array() will produce a (“higher rank”) array when appropriate, whereas higher = FALSE would return a matrix (or vector) only. These two cases correspond to sapply(*, simplify = "array") or simplify = TRUE, respectively. Details FUN is found by a call to match.fun and typically is specified as a function or a symbol (e.g. a back- quoted name) or a character string specifying a function to be searched for from the environment of the call to lapply. Function FUN must be able to accept as input any of the elements of X. If the latter is an atomic vector, FUN will always be passed a length-one vector of the same type as X. Arguments in ... cannot have the same name as any of the other arguments, and care may be needed to avoid partial matching to FUN. In general-purpose code it is good practice to name the first two arguments X and FUN if ... is passed through: this both avoids partial matching to FUN and ensures that a sensible error message is given if arguments named X or FUN are passed through .... 270 lapply Simplification in sapply is only attempted if X has length greater than zero and if the return values from all elements of X are all of the same (positive) length. If the common length is one the result is a vector, and if greater than one is a matrix with a column corresponding to each element of X. Simplification is always done in vapply. This function checks that all values of FUN are compatible with the FUN.VALUE, in that they must have the same length and type. (Types may be promoted to a higher type within the ordering logical < integer < real < complex, but not demoted.) Users of S4 classes should pass a list to lapply and vapply: the internal coercion is done by the as.list in the base namespace and not one defined by a user (e.g. by setting S4 methods on the base function). lapply and vapply are primitive functions. Value For lapply, sapply(simplify = FALSE) and replicate(simplify = FALSE), a list. For sapply(simplify = TRUE) and replicate(simplify = TRUE): if X has length zero or n = 0, an empty list. Otherwise an atomic vector or matrix or list of the same length as X(of length n for replicate). If simplification occurs, the output type is determined from the highest type of the return values in the hierarchy NULL < raw < logical < integer < real < complex < character < list < expression, after coercion of pairlists to lists. vapply returns a vector or array of type matching the FUN.VALUE. If length(FUN.VALUE) == 1 a vector of the same length as X is returned, otherwise an array. If FUN.VALUE is not an array, the result is a matrix with length(FUN.VALUE) rows and length(X) columns, otherwise an array a with dim(a) == c(dim(FUN.VALUE), length(X)). The (Dim)names of the array value are taken from the FUN.VALUE if it is named, otherwise from the result of the first function call. Column names of the matrix or more generally the names of the last dimension of the array value or names of the vector value are set from X as in sapply. Note sapply(*, simplify = FALSE, USE.NAMES = FALSE) is equivalent to lapply(*). For historical reasons, the calls created by lapply are unevaluated, and code has been written (e.g. bquote) that relies on this. This means that the recorded call is always of the form FUN(X[[0L]], ...), with 0L replaced by the current integer index. This is not normally a problem, but it can be if FUN uses sys.call or match.call or if it is a primitive function that makes use of the call. This means that it is often safer to call primitive functions with a wrapper, so that e.g. lapply(ll, function(x) is.numeric(x)) is required in R 2.7.1 to ensure that method dispatch for is.numeric occurs correctly. If expr is a function call, be aware of assumptions about where it is evaluated, and in particular what ... might refer to. You can pass additional named arguments to a function call as additional named arguments to replicate: see ‘Examples’. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Last.value 271 See Also apply, tapply, mapply for applying a function to multiple arguments, and rapply for a recursive version of lapply(), eapply for applying a function to each entry in an environment. Examples require(stats); require(graphics) x <- list(a = 1:10, beta = exp(-3:3), logic = c(TRUE,FALSE,FALSE,TRUE)) # compute the list mean for each list element lapply(x,mean) # median and quartiles for each list element lapply(x, quantile, probs = 1:3/4) sapply(x, quantile) i39 <- sapply(3:9, seq) # list of vectors sapply(i39, fivenum) vapply(i39, fivenum, c(Min. = 0, "1st Qu." = 0, Median = 0, "3rd Qu." = 0, Max. = 0)) ## sapply(*, "array") -- artificial example (v <- structure(10*(5:8), names=LETTERS[1:4])) f2 <- function(x,y) outer(rep(x, length.out=3), y) (a2 <- sapply(v, f2, y = 2*(1:5), simplify="array")) a.2 <- vapply(v, f2, outer(1:3, 1:5), y = 2*(1:5)) stopifnot(dim(a2) == c(3,5,4), all.equal(a2, a.2), identical(dimnames(a2), list(NULL,NULL,LETTERS[1:4]))) hist(replicate(100, mean(rexp(10)))) ## use of replicate() with parameters: foo <- function(x=1, y=2) c(x,y) # does not work: bar <- function(n, ...) replicate(n, foo(...)) bar <- function(n, x) replicate(n, foo(x=x)) bar(5, x=3) Last.value Value of Last Evaluated Expression Description The value of the internal evaluation of a top-level R expression is always assigned to .Last.value (in package:base) before further processing (e.g., printing). Usage .Last.value 272 length Details The value of a top-level assignment is put in .Last.value, unlike S. Do not assign to .Last.value in the workspace, because this will always mask the object of the same name in package:base. See Also eval Examples ## These will not work correctly from example(), ## but they will in make check or if pasted in, ## as example() does not run them at the top level gamma(1:15) # think of some intensive calculation... fac14 <- .Last.value # keep them library("splines") # returns invisibly .Last.value # shows what library(.) above returned length Length of an Object Description Get or set the length of vectors (including lists) and factors, and of any other R object for which a method has been defined. Usage length(x) length(x) <- value Arguments x an R object. For replacement, a vector or factor. value an integer: double values will be coerced to integer. Details Both functions are generic: you can write methods to handle specific classes of objects, see Inter- nalMethods. length<- has a "factor" method. The replacement form can be used to reset the length of a vector. If a vector is shortened, extra values are discarded and when a vector is lengthened, it is padded out to its new length with NAs (nul for raw vectors). Both are primitive functions. levels 273 Value The default method currently returns an integer of length 1. Since this may change in the future and may differ for other methods, programmers should not rely on it. (Should the length exceed the maximum representable integer, it is returned as NA.) For vectors (including lists) and factors the length is the number of elements. For an environment it is the number of objects in the environment, and NULL has length 0. For expressions and pairlists (including language objects and dotlists) it is the length of the pairlist chain. All other objects (including functions) have length one: note that for functions this differs from S. The replacement form removes all the attributes of x except its names. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also nchar for counting the number of characters in character vectors. Examples length(diag(4))# = 16 (4 x 4) length(options())# 12 or more length(y ~ x1 + x2 + x3)# 3 length(expression(x, {y <- x^2; y+2}, x^y)) # 3 ## from example(warpbreaks) require(stats) fm1 <- lm(breaks ~ wool * tension, data = warpbreaks) length(fm1$call) # 3, lm() and two arguments. length(formula(fm1)) # 3, ~ lhs rhs levels Levels Attributes Description levels provides access to the levels attribute of a variable. The first form returns the value of the levels of its argument and the second sets the attribute. Usage levels(x) levels(x) <- value 274 levels Arguments x an object, for example a factor. value A valid value for levels(x). For the default method, NULL or a character vector. For the factor method, a vector of character strings with length at least the number of levels of x, or a named list specifying how to rename the levels. Details Both the extractor and replacement forms are generic and new methods can be written for them. The most important method for the replacement function is that for factors. For the factor replacement method, a NA in value causes that level to be removed from the levels and the elements formerly with that level to be replaced by NA. Note that for a factor, replacing the levels via levels(x) <- value is not the same as (and is preferred to) attr(x, "levels") <- value. The replacement function is primitive. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also nlevels, relevel, reorder. Examples ## assign individual levels x <- gl(2, 4, 8) levels(x)[1] <- "low" levels(x)[2] <- "high" x ## or as a group y <- gl(2, 4, 8) levels(y) <- c("low", "high") y ## combine some levels z <- gl(3, 2, 12) levels(z) <- c("A", "B", "A") z ## same, using a named list z <- gl(3, 2, 12) levels(z) <- list(A=c(1,3), B=2) z ## we can add levels this way: libPaths 275 f <- factor(c("a","b")) levels(f) <- c("c", "a", "b") f f <- factor(c("a","b")) levels(f) <- list(C="C", A="a", B="b") f libPaths Search Paths for Packages Description .libPaths gets/sets the library trees within which packages are looked for. Usage .libPaths(new) .Library .Library.site Arguments new a character vector with the locations of R library trees. Tilde expansion (path.expand) is done, and if any element contains one of *?[, globbing is done where supported by the platform: see Sys.glob. Details .Library is a character string giving the location of the default library, the ‘library’ subdirectory of R_HOME. .Library.site is a (possibly empty) character vector giving the locations of the site libraries, by default the ‘site-library’ subdirectory of R_HOME (which may not exist). .libPaths is used for getting or setting the library trees that R knows about (and hence uses when looking for packages). If called with argument new, the library search path is set to the existing directories in unique(c(new, .Library.site, .Library)) and this is returned. If given no argument, a character vector with the currently active library trees is returned. The library search path is initialized at startup from the environment variable R_LIBS (which should be a colon-separated list of directories at which R library trees are rooted) followed by those in environment variable R_LIBS_USER. Only directories which exist at the time will be included. By default R_LIBS is unset, and R_LIBS_USER is set to directory ‘R/R.version$platform-library/x.y’ of the home directory (or ‘Library/R/x.y/library’ for Mac OS X AQUA builds), for R x.y.z. .Library.site can be set via the environment variable R_LIBS_SITE (as a colon-separated list of library trees). 276 library Both R_LIBS_USER and R_LIBS_SITE feature possible expansion of specifiers for R version specific information as part of the startup process. The possible conversion specifiers all start with a ‘%’ and are followed by a single letter (use ‘%%’ to obtain ‘%’), with currently available conversion specifications as follows: ‘%V’R version number including the patchlevel (e.g., ‘2.5.0’). ‘%v’R version number excluding the patchlevel (e.g., ‘2.5’). ‘%p’ the platform for which R was built, the value of R.version$platform. ‘%o’ the underlying operating system, the value of R.version$os. ‘%a’ the architecture (CPU) R was built on/for, the value of R.version$arch. (See version for details on R version information.) Function .libPaths always uses the values of .Library and .Library.site in the base names- pace. .Library.site can be set by the site in ‘Rprofile.site’, which should be followed by a call to .libPaths(.libPaths()) to make use of the updated value. For consistency, the paths are always normalized by normalizePath(winslash="/"). Value A character vector of file paths. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also library Examples .libPaths() # all library trees R knows about library Loading and Listing of Packages Description library and require load add-on packages. library 277 Usage library(package, help, pos = 2, lib.loc = NULL, character.only = FALSE, logical.return = FALSE, warn.conflicts = TRUE, quietly = FALSE, keep.source = getOption("keep.source.pkgs"), verbose = getOption("verbose")) require(package, lib.loc = NULL, quietly = FALSE, warn.conflicts = TRUE, keep.source = getOption("keep.source.pkgs"), character.only = FALSE) Arguments package, help the name of a package, given as a name or literal character string, or a character string, depending on whether character.only is FALSE (default) or TRUE). pos the position on the search list at which to attach the loaded package. Can also be the name of a position on the current search list as given by search(). lib.loc a character vector describing the location of R library trees to search through, or NULL. The default value of NULL corresponds to all libraries currently known to .libPaths(). Non-existent library trees are silently ignored. character.only a logical indicating whether package or help can be assumed to be character strings. logical.return logical. If it is TRUE, FALSE or TRUE is returned to indicate success. warn.conflicts logical. If TRUE, warnings are printed about conflicts from attaching the new package, unless that package contains an object .conflicts.OK. A conflict is a function masking a function, or a non-function masking a non-function. keep.source logical. Now ignored. This argument does not apply to packages using lazy- loading: whether they have kept source is determined when they are installed. verbose a logical. If TRUE, additional diagnostics are printed. quietly a logical. If TRUE, no message confirming package loading is printed, and most often, no errors/warnings are printed if package loading fails. Details library(package) and require(package) both load the package with name package. require is designed for use inside other functions; it returns FALSE and gives a warning (rather than an error as library() does by default) if the package does not exist. Both functions check and update the list of currently loaded packages and do not reload a package which is already loaded. (Furthermore, if the package has a namespace and a name space of that name is already loaded, they work from the existing namespace rather than reloading from the file system. If you want to reload such a package, call detach(unload = TRUE) or unloadNamespace first.) To suppress messages during the loading of packages use suppressPackageStartupMessages: this will suppress all messages from R itself but not necessarily all those from package authors. If library is called with no package or help argument, it lists all available packages in the libraries specified by lib.loc, and returns the corresponding information in an object of class 278 library "libraryIQR". The structure of this class may change in future versions. In earlier versions of R, only the names of all available packages were returned; use .packages(all = TRUE) for obtaining these. Note that installed.packages() returns even more information. library(help = somename) computes basic information about the package somename, and returns this in an object of class "packageInfo". The structure of this class may change in future versions. When used with the default value (NULL) for lib.loc, the attached packages are searched before the libraries. In versions of R prior to 2.14.0, a .First.lib function would be called when a package without a namespace was attached. As of 2.14.0, all functions have namespaces; see .onLoad for current behaviour, and ‘Writing R Extensions’ for a description of the older mechanism. Value Normally library returns (invisibly) the list of attached packages, but TRUE or FALSE if logical.return is TRUE. When called as library() it returns an object of class "libraryIQR", and for library(help=), one of class "packageInfo". require returns (invisibly) a logical indicating whether the required package is available. (Before R 2.12.0 it could also fail with an error.) Licenses Some packages have restrictive licenses, and as from R 2.11.0 there is a mechanism to ensure that users are aware of such licenses. If getOption("checkPackageLicense") == TRUE, then at first use of a package with a not-known-to-be-FOSS (see below) license the user is asked to view and accept the license: a list of accepted licenses is stored in file ‘~/.R/licensed’. In a non-interactive session it is an error to use such a package whose license has not already been accepted. Free or Open Source Software (FOSS, e.g., http://en.wikipedia.org/wiki/FOSS) packages are determined by the same filters used by available.packages but applied to just the current package, not its dependencies. There can also be a site-wide file ‘R_HOME/etc/licensed.site’ of packages (one per line). Formal methods library takes some further actions when package methods is attached (as it is by default). Pack- ages may define formal generic functions as well as re-defining functions in other packages (notably base) to be generic, and this information is cached whenever such a package is loaded after meth- ods and re-defined functions (implicit generics) are excluded from the list of conflicts. The caching and check for conflicts require looking for a pattern of objects; the search may be avoided by defin- ing an object .noGenerics (with any value) in the package. Naturally, if the package does have any such methods, this will prevent them from being used. Note library and require can only load an installed package, and this is detected by having a ‘DESCRIPTION’ file containing a ‘Built:’ field. Under Unix-alikes, the code checks that the package was installed under a similar operating system as given by R.version$platform (the canonical name of the platform under which R was com- piled), provided it contains compiled code. Packages which do not contain compiled code can be library 279 shared between Unix-alikes, but not to other OSes because of potential problems with line endings and OS-specific help files. If sub-architectures are used, the OS similarity is not checked since the OS used to build may differ (e.g. i386-pc-linux-gnu code can be built on an x86_64-unknown- linux-gnu OS). The package name given to library and require must match the name given in the package’s ‘DESCRIPTION’ file exactly, even on case-insensitive file systems such as are common on MS Win- dows and Mac OS X. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also .libPaths,.packages. attach, detach, search, objects, autoload, library.dynam, data, install.packages and installed.packages; INSTALL, REMOVE. The initial set of packages attached is set by options(defaultPackages=): see also Startup. Examples library() # list all available packages library(lib.loc = .Library) # list all packages in the default library library(help = splines) # documentation on package ’splines’ library(splines) # load package ’splines’ require(splines) # the same search() # "splines", too detach("package:splines") # if the package name is in a character vector, use pkg <- "splines" library(pkg, character.only = TRUE) detach(pos = match(paste("package", pkg, sep=":"), search())) require(pkg, character.only = TRUE) detach(pos = match(paste("package", pkg, sep=":"), search())) require(nonexistent) # FALSE ## Not run: ## if you want to mask as little as possible, use library(mypkg, pos = "package:base") ## End(Not run) 280 library.dynam library.dynam Loading DLLs from Packages Description Load the specified file of compiled code if it has not been loaded already, or unloads it. Usage library.dynam(chname, package = NULL, lib.loc = NULL, verbose = getOption("verbose"), file.ext = .Platform$dynlib.ext, ...) library.dynam.unload(chname, libpath, verbose = getOption("verbose"), file.ext = .Platform$dynlib.ext) .dynLibs(new) Arguments chname a character string naming a DLL (also known as a dynamic shared object or library) to load. package a character vector with the names of packages to search through, or NULL. By default, all packages in the search path are used. lib.loc a character vector describing the location of R library trees to search through, or NULL. The default value of NULL corresponds to all libraries currently known to .libPaths(). libpath the path to the loaded package whose DLL is to be unloaded. verbose a logical value indicating whether an announcement is printed on the console before loading the DLL. The default value is taken from the verbose entry in the system options. file.ext the extension (including ‘.’ if used) to append to the file name to specify the library to be loaded. This defaults to the appropriate value for the operating system. ... additional arguments needed by some libraries that are passed to the call to dyn.load to control how the library and its dependencies are loaded. new a list of "DLLInfo" objects corresponding to the DLLs loaded by packages. Can be missing. Details See dyn.load for what sort of objects these functions handle. library.dynam 281 library.dynam is designed to be used inside a package rather than at the command line, and should really only be used inside .onLoad. The system-specific extension for DLLs (e.g., ‘.so’ or ‘.sl’ on Unix-alike systems, ‘.dll’ on Windows) should not be added. library.dynam.unload is designed for use in .onUnload: it unloads the DLL and updates the value of .dynLibs() .dynLibs is used for getting (with no argument) or setting the DLLs which are currently loaded by packages (using library.dynam). lib.loc should contain absolute paths: versions of R prior to 2.12.0 may get confused by relative paths. Using the defaults for package or lib.loc is deprecated, not least because they will not give work as intended from .onLoad. Value If chname is not specified, library.dynam returns an object of class "DLLInfoList" corresponding to the DLLs loaded by packages. If chname is specified, an object of class "DLLInfo" that identifies the DLL and which can be used in future calls is returned invisibly. Note that the class "DLLInfo" has a method for $ which can be used to resolve native symbols within that DLL. library.dynam.unload invisibly returns an object of class "DLLInfo" identifying the DLL suc- cessfully unloaded. .dynLibs returns an object of class "DLLInfoList" corresponding corresponding to its current value. Warning Do not use dyn.unload on a DLL loaded by library.dynam: use library.dynam.unload to ensure that .dynLibs gets updated. Otherwise a subsequent call to library.dynam will be told the object is already loaded. Note that whether or not it is possible to unload a DLL and then reload a revised version of the same file is OS-dependent: see the ‘Value’ section of the help for dyn.unload. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also getLoadedDLLs for information on "DLLInfo" and "DLLInfoList" objects. .onLoad, library, dyn.load,.packages,.libPaths SHLIB for how to create suitable DLLs. Examples ## Which DLLs were dynamically loaded by packages? library.dynam() 282 list license The R License Terms Description The license terms under which R is distributed. Usage license() licence() Details R is distributed under the terms of the GNU GENERAL PUBLIC LICENSE, either Version 2, June 1991 or Version 3, June 2007. A copy of the version 2 license is in file ‘R_HOME/COPYING’ and can be viewed by RShowDoc("COPYING"). Version 3 of the license can be displayed by RShowDoc("GPL-3"). A small number of files (some of the API header files) are distributed under the LESSER GNU GENERAL PUBLIC LICENSE, version 2.1 or later. A copy of this license is in file ‘$R_SHARE_DIR/licenses/LGPL-2.1’ and can be viewed by RShowDoc("LGPL-2.1"). Version 3 of the license can be displayed by RShowDoc("LGPL-3"). list Lists – Generic and Dotted Pairs Description Functions to construct, coerce and check for both kinds of R lists. Usage list(...) pairlist(...) as.list(x, ...) ## S3 method for class ’environment’ as.list(x, all.names = FALSE, ...) as.pairlist(x) is.list(x) is.pairlist(x) alist(...) list 283 Arguments ... objects, possibly named. x object to be coerced or tested. all.names a logical indicating whether to copy all values or (default) only those whose names do not begin with a dot. Details Most lists in R internally are Generic Vectors, whereas traditional dotted pair lists (as in LISP) are available but rarely seen by users (except as formals of functions). The arguments to list or pairlist are of the form value or tag = value. The functions return a list or dotted pair list composed of its arguments with each value either tagged or untagged, depending on how the argument was specified. alist handles its arguments as if they described function arguments. So the values are not evalu- ated, and tagged arguments with no value are allowed whereas list simply ignores them. alist is most often used in conjunction with formals. as.list attempts to coerce its argument to a list. For functions, this returns the concatenation of the list of formal arguments and the function body. For expressions, the list of constituent elements is returned. as.list is generic, and as the default method calls as.vector(mode="list") for a non-list, methods for as.vector may be invoked. as.list turns a factor into a list of one- element factors. Attributes may be dropped unless the argument already is a list or expression. (This is inconsistent with functions such as as.character which always drop attributes, and is for efficiency since lists can be expensive to copy.) is.list returns TRUE if and only if its argument is a list or a pairlist of length > 0. is.pairlist returns TRUE if and only if the argument is a pairlist or NULL (see below). The "environment" method for as.list copies the name-value pairs (for names not beginning with a dot) from an environment to a named list. The user can request that all named objects are copied. The list is in no particular order (the order depends on the order of creation of objects and whether the environment is hashed). No enclosing environments are searched. (Objects copied are duplicated so this can be an expensive operation.) Note that there is an inverse operation, the as.environment() method for list objects. An empty pairlist, pairlist() is the same as NULL. This is different from list(). as.pairlist is implemented as as.vector(x, "pairlist"), and hence will dispatch methods for the generic function as.vector. Lists are copied element-by-element into a pairlist and the names of the list used as tags for the pairlist: the return value for other types of argument is undocumented. list, is.list and is.pairlist are primitive functions. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. 284 list.files See Also vector("list", length) for creation of a list with empty components; c, for concatenation; formals. unlist is an approximate inverse to as.list(). ‘plotmath’ for the use of list in plot annotation. Examples require(graphics) # create a plotting structure pts <- list(x=cars[,1], y=cars[,2]) plot(pts) is.pairlist(.Options) # a user-level pairlist ## "pre-allocate" an empty list of length 5 vector("list", 5) # Argument lists f <- function() x # Note the specification of a "..." argument: formals(f) <- al <- alist(x=, y=2+3, ...=) f al ## environment->list coercion e1 <- new.env() e1$a <- 10 e1$b <- 20 as.list(e1) list.files List the Files in a Directory/Folder Description These functions produce a character vector of the names of files or directories in the named direc- tory. Usage list.files(path = ".", pattern = NULL, all.files = FALSE, full.names = FALSE, recursive = FALSE, ignore.case = FALSE, include.dirs = FALSE) dir(path = ".", pattern = NULL, all.files = FALSE, full.names = FALSE, recursive = FALSE, list.files 285 ignore.case = FALSE, include.dirs = FALSE) list.dirs(path = ".", full.names = TRUE, recursive = TRUE) Arguments path a character vector of full path names; the default corresponds to the working directory, getwd(). Tilde expansion (see path.expand) is performed. Missing values will be ignored. pattern an optional regular expression. Only file names which match the regular expres- sion will be returned. all.files a logical value. If FALSE, only the names of visible files are returned. If TRUE, all file names will be returned. full.names a logical value. If TRUE, the directory path is prepended to the file names to give a relative file path. If FALSE, the file names (rather than paths) are returned. recursive logical. Should the listing recurse into directories? ignore.case logical. Should pattern-matching be case-insensitive? include.dirs logical. Should subdirectory names be included in recursive listings? (There always are in non-recursive ones). Value A character vector containing the names of the files in the specified directories, or "" if there were no files. If a path does not exist or is not a directory or is unreadable it is skipped, with a warning. The files are sorted in alphabetical order, on the full path if full.names = TRUE. list.dirs implicitly has all.files = TRUE, and if recursive = TRUE, the answer includes path itself (provided it is a readable directory). Note File naming conventions are platform dependent. The pattern matching works with the case of file names as returned by the OS Author(s) Ross Ihaka, Brian Ripley See Also file.info, file.access and files for many more file handling functions and file.choose for interactive selection. glob2rx to convert wildcards (as used by system file commands and shells) to regular expressions. Sys.glob for wildcard expansion on file paths. 286 list2env Examples list.files(R.home()) ## Only files starting with a-l or r ## Note that a-l is locale-dependent, but using case-insensitive ## matching makes it unambiguous in English locales dir("../..", pattern = "^[a-lr]", full.names=TRUE, ignore.case = TRUE) list.dirs(R.home("doc")) list2env From A List, Build or Add To an Environment Description From a named listx , create an environment containing all list components as objects, or “multi- assign” from x into a pre-existing environment. Usage list2env(x, envir = NULL, parent = parent.frame(), hash = (length(x) > 100), size = max(29L, length(x))) Arguments x a list, where names(x) must not contain empty ("") elements. envir an environment or NULL. parent (for the case envir = NULL): a parent frame aka enclosing environment, see new.env. hash (for the case envir = NULL): logical indicating if the created environment should use hashing, see new.env. size (in the case envir = NULL, hash = TRUE): hash size, see new.env. Details This will be very slow for large inputs unless hashing is used on the environment. Environments must have uniquely named entries, but named lists need not: where the list has du- plicate names it is the last element with the name that is used. Empty names throw an error. Value An environment, either newly created (as by new.env) if the envir argument was NULL, otherwise the updated environment envir. Since environments are never duplicated, the argument envir is also changed. Author(s) Martin Maechler load 287 See Also environment, new.env, as.environment; further, assign. The (semantical) “inverse”: as.list.environment. Examples L <- list(a=1, b=2:4, p = pi, ff = gl(3,4,labels=LETTERS[1:3])) e <- list2env(L) ls(e) stopifnot(ls(e) == sort(names(L)), identical(L$b, e$b)) # "$" working for environments as for lists ## consistency, when we do the inverse: ll <- as.list(e) # -> dispatching to the as.list.environment() method rbind(names(L), names(ll)) # not in the same order, typically, # but the same content: stopifnot(identical(L [sort.list(names(L ))], ll[sort.list(names(ll))])) ## now add to e -- can be seen as a fast "multi-assign": list2env(list(abc = LETTERS, note = "just an example", df = data.frame(x=rnorm(20), y = rbinom(20,1, pr=0.2))), envir = e) utils::ls.str(e) load Reload Saved Datasets Description Reload datasets written with the function save. Usage load(file, envir = parent.frame()) Arguments file a (readable binary-mode) connection or a character string giving the name of the file to load (when tilde expansion is done). envir the environment where the data should be loaded. Details load can load R objects saved in the current or any earlier format. It can read a compressed file (see save) directly from a file or from a suitable connection (including a call to url). A not-open connection will be opened in mode "rb" and closed after use. Any connection other than a gzfile or gzcon connection will be wrapped in gzcon to allow compressed saves to be 288 load handled: note that this leaves the connection in an altered state (in particular, binary-only), and that it needs to be closed explicitly (it will not be garbage-collected). Only R objects saved in the current format (used since R 1.4.0) can be read from a connection. If no input is available on a connection a warning will be given, but any input not in the current format will result in a error. Loading from an earlier version will give a warning about the ‘magic number’: magic numbers 1971:1977 are from R < 0.99.0, and RD[ABX]1 from R 0.99.0 to R 1.3.1. These are all obsolete, and you are strongly recommended to re-save such files in a current format. Value A character vector of the names of objects created, invisibly. Warning Saved R objects are binary files, even those saved with ascii = TRUE, so ensure that they are transferred without conversion of end of line markers. load tries to detect such a conversion and gives an informative error message. See Also save, download.file. For other interfaces to the underlying serialization format, see unserialize and readRDS. Examples ## save all data xx <- pi # to ensure there is some data save(list = ls(all=TRUE), file= "all.RData") rm(xx) ## restore the saved values to the current environment local({ load("all.RData") ls() }) ## restore the saved values to the user’s workspace load("all.RData", .GlobalEnv) unlink("all.RData") ## Not run: con <- url("http://some.where.net/R/data/example.rda") ## print the value to see what objects were created. print(load(con)) close(con) # url() always opens the connection ## End(Not run) locales 289 locales Query or Set Aspects of the Locale Description Get details of or set aspects of the locale for the R process. Usage Sys.getlocale(category = "LC_ALL") Sys.setlocale(category = "LC_ALL", locale = "") Arguments category character string. The following categories should always be supported: "LC_ALL","LC_COLLATE","LC_CTYPE","LC_MONETARY","LC_NUMERIC" and "LC_TIME". Some systems (not Windows) will also support "LC_MESSAGES", "LC_PAPER" and "LC_MEASUREMENT". locale character string. A valid locale name on the system in use. Normally "" (the default) will pick up the default locale for the system. Details The locale describes aspects of the internationalization of a program. Initially most aspects of the locale of R are set to "C" (which is the default for the C language and reflects North-American usage). R sets "LC_CTYPE" and "LC_COLLATE", which allow the use of a different character set and alphabetic comparisons in that character set (including the use of sort), "LC_MONETARY" (for use by Sys.localeconv) and "LC_TIME" may affect the behaviour of as.POSIXlt and strptime and functions which use them (but not date). The first seven categories described here are those specified by POSIX. "LC_MESSAGES" will be "C" on systems that do not support message translation, and is not supported on Windows. Trying to use an unsupported category is an error for Sys.setlocale. Note that setting category "LC_ALL" sets only "LC_COLLATE","LC_CTYPE","LC_MONETARY" and "LC_TIME". Attempts to set an invalid locale are ignored. There may or may not be a warning, depending on the OS. Attempts to change the character set (by Sys.setlocale("LC_TYPE", ), if that implies a different character set) during a session may not work and are likely to lead to some confusion. Value A character string of length one describing the locale in use (after setting for Sys.setlocale), or an empty character string if the current locale settings are invalid or NULL if locale information is unavailable. For category = "LC_ALL" the details of the string are system-specific: it might be a single locale name or a set of locale names separated by "/" (Solaris, Mac OS X) or ";" (Windows, Linux). For 290 log portability, it is best to query categories individually: it is not necessarily the case that the result of foo <- Sys.getlocale() can be used in Sys.setlocale("LC_ALL", locale = foo). Warning Setting "LC_NUMERIC" may cause R to function anomalously, so gives a warning. Input conver- sions in R itself are unaffected, but the reading and writing of ASCII save files will be, as may packages. Setting it temporarily to produce graphical or text output may work well enough, but options(OutDec) is often preferable. Note Changing the values of locale categories whilst R is running ought to be noticed by the OS services, and usually is but exceptions have been seen (usually in collation services). See Also strptime for uses of category = "LC_TIME". Sys.localeconv for details of numerical and monetary representations. l10n_info gives some summary facts about the locale and its encoding. The ‘R Installation and Administration’ manual for background on locales and how to find out locale names on your system. Examples Sys.getlocale() Sys.getlocale("LC_TIME") ## Not run: Sys.setlocale("LC_TIME", "de") # Solaris: details are OS-dependent Sys.setlocale("LC_TIME", "de_DE.utf8") # Modern Linux etc. Sys.setlocale("LC_TIME", "de_DE.UTF-8") # ditto Sys.setlocale("LC_TIME", "de_DE") # Mac OS X, in UTF-8 Sys.setlocale("LC_TIME", "German") # Windows ## End(Not run) Sys.getlocale("LC_PAPER") # may or may not be set Sys.setlocale("LC_COLLATE", "C") # turn off locale-specific sorting, # usually log Logarithms and Exponentials log 291 Description log computes logarithms, by default natural logarithms, log10 computes common (i.e., base 10) logarithms, and log2 computes binary (i.e., base 2) logarithms. The general form log(x, base) computes logarithms with base base. log1p(x) computes log(1 + x) accurately also for |x|  1 (and less accurately when x ≈ −1). exp computes the exponential function. expm1(x) computes exp(x) − 1 accurately also for |x|  1. Usage log(x, base = exp(1)) logb(x, base = exp(1)) log10(x) log2(x) log1p(x) exp(x) expm1(x) Arguments x a numeric or complex vector. base a positive or complex number: the base with respect to which logarithms are computed. Defaults to e=exp(1). Details All except logb are generic functions: methods can be defined for them individually or via the Math group generic. log10 and log2 are only convenience wrappers, but logs to bases 10 and 2 (whether computed via log or the wrappers) will be computed more efficiently and accurately where supported by the OS. Methods can be set for them individually (and otherwise methods for log will be used). logb is a wrapper for log for compatibility with S. If (S3 or S4) methods are set for log they will be dispatched. Do not set S4 methods on logb itself. All except log are primitive functions. Value A vector of the same length as x containing the transformed values. log(0) gives -Inf, and log(x) for negative values of x is NaN. exp(-Inf) is 0. For complex inputs to the log functions, the value is a complex number with imaginary part in the range [−π, π]: which end of the range is used might be platform-specific. 292 Logic S4 methods exp, expm1, log, log10, log2 and log1p are S4 generic and are members of the Math group generic. Note that this means that the S4 generic for log has a signature with only one argument, x, but that base can be passed to methods (but will not be used for method selection). On the other hand, if you only set a method for the Math group generic then base argument of log will be ignored for your class. Source log1p and expm1 may be taken from the operating system, but if not available there are based on the Fortran subroutine dlnrel by W. Fullerton of Los Alamos Scientific Laboratory (see http:// www.netlib.org/slatec/fnlib/dlnrel.f and (for small x) a single Newton step for the solution of log1p(y) = x respectively. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (for log, log10 and exp.) Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. (for logb.) See Also Trig, sqrt, Arithmetic. Examples log(exp(3)) log10(1e7)# = 7 x <- 10^-(1+2*1:9) cbind(x, log(1+x), log1p(x), exp(x)-1, expm1(x)) Logic Logical Operators Description These operators act on logical and number-like vectors. Usage ! x x & y x && y x | y x || y xor(x, y) isTRUE(x) Logic 293 Arguments x, y logical or ‘number-like’ vectors (i.e., of type double (class numeric), integer, complex or raw), or objects for which methods have been written. Details ! indicates logical negation (NOT). & and && indicate logical AND and | and || indicate logical OR. The shorter form performs ele- mentwise comparisons in much the same way as arithmetic operators. The longer form evaluates left to right examining only the first element of each vector. Evaluation proceeds only until the result is determined. The longer form is appropriate for programming control-flow and typically preferred in if clauses. xor indicates elementwise exclusive OR. isTRUE(x) is an abbreviation of identical(TRUE, x), and so is true if and only if x is a length-one logical vector whose only element is TRUE and which has no attributes (not even names). Numeric and complex vectors will be coerced to logical values, with zero being false and all non- zero values being true. Raw vectors are handled without any coercion for !,&, | and xor, with these operators being applied bitwise (so ! is the 1s-complement). The operators !,& and | are generic functions: methods can be written for them individually or via the Ops (or S4 Logic, see below) group generic function. (See Ops for how dispatch is computed.) NA is a valid logical object. Where a component of x or y is NA, the result will be NA if the outcome is ambiguous. In other words NA & TRUE evaluates to NA, but NA & FALSE evaluates to FALSE. See the examples below. See Syntax for the precedence of these operators: unlike many other languages (including S) the AND and OR operators do not have the same precedence (the AND operators are higher than the OR operators). Value For !, a logical or raw vector of the same length as x: names, dims and dimnames are copied from x. For |,& and xor a logical or raw vector. The elements of shorter vectors are recycled as necessary (with a warning when they are recycled only fractionally). The rules for determining the attributes of the result are rather complicated. Most attributes are taken from the longer argument, the first if they are of the same length. Names will be copied from the first if it is the same length as the answer, otherwise from the second if that is. For time series, these operations are allowed only if the series are compatible, when the class and tsp attribute of whichever is a time series (the same, if both are) are used. For arrays (and an array result) the dimensions and dimnames are taken from first argument if it is an array, otherwise the second. For ||,&& and isTRUE, a length-one logical vector. S4 methods !,& and | are S4 generics, the latter two part of the Logic group generic (and hence methods need argument names e1, e2). 294 logical References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also TRUE or logical. any and all for OR and AND on many scalar arguments. Syntax for operator precedence. Examples y <- 1 + (x <- stats::rpois(50, lambda=1.5) / 4 - 1) x[(x > 0) & (x < 1)] # all x values between 0 and 1 if (any(x == 0) || any(y == 0)) "zero encountered" ## construct truth tables : x <- c(NA, FALSE, TRUE) names(x) <- as.character(x) outer(x, x, "&")## AND table outer(x, x, "|")## OR table logical Logical Vectors Description Create or test for objects of type "logical", and the basic logical constants. Usage TRUE FALSE T; F logical(length = 0) as.logical(x, ...) is.logical(x) Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. lower.tri 295 Details TRUE and FALSE are reserved words denoting logical constants in the R language, whereas T and F are global variables whose initial values set to these. All four are logical(1) vectors. Logical vectors are coerced to integer vectors in contexts where a numerical value is required, with TRUE being mapped to 1L, FALSE to 0L and NA to NA_integer_. Value logical creates a logical vector of the specified length. Each element of the vector is equal to FALSE. as.logical attempts to coerce its argument to be of logical type. For factors, this uses the levels (labels). Like as.vector it strips attributes including names. Character strings c("T", "TRUE", "True", "true") are regarded as true, c("F", "FALSE", "False", "false") as false, and all others as NA. is.logical returns TRUE or FALSE depending on whether its argument is of logical type or not. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also NA, the other logical constant. lower.tri Lower and Upper Triangular Part of a Matrix Description Returns a matrix of logicals the same size of a given matrix with entries TRUE in the lower or upper triangle. Usage lower.tri(x, diag = FALSE) upper.tri(x, diag = FALSE) Arguments x a matrix. diag logical. Should the diagonal be included? See Also diag, matrix. 296 ls Examples (m2 <- matrix(1:20, 4, 5)) lower.tri(m2) m2[lower.tri(m2)] <- NA m2 ls List Objects Description ls and objects return a vector of character strings giving the names of the objects in the specified environment. When invoked with no argument at the top level prompt, ls shows what data sets and functions a user has defined. When invoked with no argument inside a function, ls returns the names of the functions local variables. This is useful in conjunction with browser. Usage ls(name, pos = -1, envir = as.environment(pos), all.names = FALSE, pattern) objects(name, pos= -1, envir = as.environment(pos), all.names = FALSE, pattern) Arguments name which environment to use in listing the available objects. Defaults to the current environment. Although called name for back compatibility, in fact this argument can specify the environment in any form; see the details section. pos an alternative argument to name for specifying the environment as a position in the search list. Mostly there for back compatibility. envir an alternative argument to name for specifying the environment. Mostly there for back compatibility. all.names a logical value. If TRUE, all object names are returned. If FALSE, names which begin with a ‘.’ are omitted. pattern an optional regular expression. Only names matching pattern are returned. glob2rx can be used to convert wildcard patterns to regular expressions. Details The name argument can specify the environment from which object names are taken in one of several forms: as an integer (the position in the search list); as the character string name of an element in the search list; or as an explicit environment (including using sys.frame to access the currently active function calls). By default, the environment of the call to ls or objects is used. The pos and envir arguments are an alternative way to specify an environment, but are primarily there for back compatibility. Note that the order of the resulting strings is locale dependent, see Sys.getlocale. make.names 297 References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also glob2rx for converting wildcard patterns to regular expressions. ls.str for a long listing based on str. apropos (or find) for finding objects in the whole search path; grep for more details on ‘regular expressions’; class, methods, etc., for object-oriented programming. Examples .Ob <- 1 ls(pattern = "O") ls(pattern= " O", all.names = TRUE) # also shows ".[foo]" # shows an empty list because inside myfunc no variables are defined myfunc <- function() {ls()} myfunc() # define a local variable inside myfunc myfunc <- function() {y <- 1; ls()} myfunc() # shows "y" make.names Make Syntactically Valid Names Description Make syntactically valid names out of character vectors. Usage make.names(names, unique = FALSE, allow_ = TRUE) Arguments names character vector to be coerced to syntactically valid names. This is coerced to character if necessary. unique logical; if TRUE, the resulting elements are unique. This may be desired for, e.g., column names. allow_ logical. For compatibility with R prior to 1.9.0. 298 make.unique Details A syntactically valid name consists of letters, numbers and the dot or underline characters and starts with a letter or the dot not followed by a number. Names such as ".2way" are not valid, and neither are the reserved words. The definition of a letter depends on the current locale, but only ASCII digits are considered to be digits. The character "X" is prepended if necessary. All invalid characters are translated to ".". A miss- ing value is translated to "NA". Names which match R keywords have a dot appended to them. Duplicated values are altered by make.unique. Value A character vector of same length as names with each changed to a syntactically valid name, in the current locale’s encoding. Note Prior to R version 1.9.0, underscores were not valid in variable names, and code that relies on them being converted to dots will no longer work. Use allow_ = FALSE for back-compatibility. allow_ = FALSE is also useful when creating names for export to applications which do not allow underline in names (for example, S-PLUS and some DBMSs). See Also make.unique, names, character, data.frame. Examples make.names(c("a and b", "a-and-b"), unique=TRUE) # "a.and.b" "a.and.b.1" make.names(c("a and b", "a_and_b"), unique=TRUE) # "a.and.b" "a_and_b" make.names(c("a and b", "a_and_b"), unique=TRUE, allow_=FALSE) # "a.and.b" "a.and.b.1" state.name[make.names(state.name) != state.name] # those 10 with a space make.unique Make Character Strings Unique Description Makes the elements of a character vector unique by appending sequence numbers to duplicates. Usage make.unique(names, sep = ".") mapply 299 Arguments names a character vector sep a character string used to separate a duplicate name from its sequence number. Details The algorithm used by make.unique has the property that make.unique(c(A, B)) == make.unique(c(make.unique(A), B)). In other words, you can append one string at a time to a vector, making it unique each time, and get the same result as applying make.unique to all of the strings at once. If character vector A is already unique, then make.unique(c(A, B)) preserves A. Value A character vector of same length as names with duplicates changed, in the current locale’s encod- ing. Author(s) Thomas P. Minka See Also make.names Examples make.unique(c("a", "a", "a")) make.unique(c(make.unique(c("a", "a")), "a")) make.unique(c("a", "a", "a.2", "a")) make.unique(c(make.unique(c("a", "a")), "a.2", "a")) rbind(data.frame(x=1), data.frame(x=2), data.frame(x=3)) rbind(rbind(data.frame(x=1), data.frame(x=2)), data.frame(x=3)) mapply Apply a Function to Multiple List or Vector Arguments Description mapply is a multivariate version of sapply. mapply applies FUN to the first elements of each . . . argument, the second elements, the third elements, and so on. Arguments are recycled if neces- sary. 300 mapply Usage mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE) Arguments FUN function to apply, found via match.fun. ... arguments to vectorize over (vectors or lists of strictly positive length, or all of zero length). MoreArgs a list of other arguments to FUN. SIMPLIFY logical or character string; attempt to reduce the result to a vector, matrix or higher dimensional array; see the simplify argument of sapply. USE.NAMES logical; use names if the first . . . argument has names, or if it is a character vector, use that character vector as the names. Details mapply calls FUN for the values of ... (re-cycled to the length of the longest, unless any have length zero), followed by the arguments given in MoreArgs. The arguments in the call will be named if ... or MoreArgs are named. Value A list, or for SIMPLIFY = TRUE, a vector, array or list. See Also sapply, after which mapply() is modelled. outer, which applies a vectorized function to all combinations of two arguments. Examples mapply(rep, 1:4, 4:1) mapply(rep, times = 1:4, x = 4:1) mapply(rep, times = 1:4, MoreArgs = list(x = 42)) mapply(function(x,y) seq_len(x) + y, c(a = 1, b = 2, c = 3), # names from first c(A = 10, B = 0, C = -10)) word <- function(C,k) paste(rep.int(C,k), collapse = ’’) utils::str(mapply(word, LETTERS[1:6], 6:1, SIMPLIFY = FALSE)) margin.table 301 margin.table Compute table margin Description For a contingency table in array form, compute the sum of table entries for a given index. Usage margin.table(x, margin=NULL) Arguments x an array margin index number (1 for rows, etc.) Details This is really just apply(x, margin, sum) packaged up for newbies, except that if margin has length zero you get sum(x). Value The relevant marginal table. The class of x is copied to the output table, except in the summation case. Author(s) Peter Dalgaard See Also prop.table and addmargins. Examples m <- matrix(1:4,2) margin.table(m,1) margin.table(m,2) 302 match mat.or.vec Create a Matrix or a Vector Description mat.or.vec creates an nr by nc zero matrix if nc is greater than 1, and a zero vector of length nr if nc equals 1. Usage mat.or.vec(nr, nc) Arguments nr, nc numbers of rows and columns. Examples mat.or.vec(3, 1) mat.or.vec(3, 2) match Value Matching Description match returns a vector of the positions of (first) matches of its first argument in its second. %in% is a more intuitive interface as a binary operator, which returns a logical vector indicating if there is a match or not for its left operand. Usage match(x, table, nomatch = NA_integer_, incomparables = NULL) x %in% table Arguments x vector or NULL: the values to be matched. table vector or NULL: the values to be matched against. nomatch the value to be returned in the case when no match is found. Note that it is coerced to integer. incomparables a vector of values that cannot be matched. Any value in x matching a value in this vector is assigned the nomatch value. For historical reasons, FALSE is equivalent to NULL. match 303 Details %in% is currently defined as "%in%" <- function(x, table) match(x, table, nomatch = 0) > 0 Factors, raw vectors and lists are converted to character vectors, and then x and table are coerced to a common type (the later of the two types in R’s ordering, logical < integer < numeric < complex < character) before matching. If incomparables has positive length it is coerced to the common type. Matching for lists is potentially very slow and best avoided except in simple cases. Exactly what matches what is to some extent a matter of definition. For all types, NA matches NA and no other value. For real and complex values, NaN values are regarded as matching any other NaN value, but not matching NA. That %in% never returns NA makes it particularly useful in if conditions. Character strings will be compared as byte sequences if any input is marked as "bytes". Value A vector of the same length as x. match: An integer vector giving the position in table of the first match if there is a match, otherwise nomatch. If x[i] is found to equal table[j] then the value returned in the i-th position of the return value is j, for the smallest possible j. If no match is found, the value is nomatch. %in%: A logical vector, indicating if a match was located for each element of x: thus the values are TRUE or FALSE and never NA. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also pmatch and charmatch for (partial) string matching, match.arg, etc for function argument match- ing. findInterval similarly returns a vector of positions, but finds numbers within intervals, rather than exact matches. is.element for an S-compatible equivalent of %in%. Examples ## The intersection of two sets can be defined via match(): ## Simple version: ## intersect <- function(x, y) y[match(x, y, nomatch = 0)] intersect # the R function in base, slightly more careful intersect(1:10, 7:20) 1:10 %in% c(1,3,5,9) sstr <- c("c","ab","B","bba","c",NA,"@","bla","a","Ba","%") sstr[sstr %in% c(letters, LETTERS)] 304 match.arg "%w/o%" <- function(x, y) x[!x %in% y] #-- x without y (1:10) %w/o% c(3,7,12) match.arg Argument Verification Using Partial Matching Description match.arg matches arg against a table of candidate values as specified by choices, where NULL means to take the first one. Usage match.arg(arg, choices, several.ok = FALSE) Arguments arg a character vector (of length one unless several.ok is TRUE) or NULL. choices a character vector of candidate values several.ok logical specifying if arg should be allowed to have more than one element. Details In the one-argument form match.arg(arg), the choices are obtained from a default setting for the formal argument arg of the function from which match.arg was called. (Since default argu- ment matching will set arg to choices, this is allowed as an exception to the ‘length one unless several.ok is TRUE’ rule, and returns the first element.) Matching is done using pmatch, so arg may be abbreviated. Value The unabbreviated version of the exact or unique partial match if there is one; otherwise, an error is signalled if several.ok is false, as per default. When several.ok is true and more than one element of arg has a match, all unabbreviated versions of matches are returned. See Also pmatch, match.fun, match.call. match.call 305 Examples require(stats) ## Extends the example for ’switch’ center <- function(x, type = c("mean", "median", "trimmed")) { type <- match.arg(type) switch(type, mean = mean(x), median = median(x), trimmed = mean(x, trim = .1)) } x <- rcauchy(10) center(x, "t") # Works center(x, "med") # Works try(center(x, "m")) # Error stopifnot(identical(center(x), center(x, "mean")), identical(center(x, NULL), center(x, "mean")) ) ## Allowing more than one match: match.arg(c("gauss", "rect", "ep"), c("gaussian", "epanechnikov", "rectangular", "triangular"), several.ok = TRUE) match.call Argument Matching Description match.call returns a call in which all of the specified arguments are specified by their full names. Usage match.call(definition = NULL, call = sys.call(sys.parent()), expand.dots = TRUE) Arguments definition a function, by default the function from which match.call is called. See details. call an unevaluated call to the function specified by definition, as generated by call. expand.dots logical. Should arguments matching ... in the call be included or left as a ... argument? Details ‘function’ on this help page means an interpreted function (also known as a ‘closure’): match.call does not support primitive functions (where argument matching is normally positional). match.call is most commonly used in two circumstances: 306 match.fun • To record the call for later re-use: for example most model-fitting functions record the call as element call of the list they return. Here the default expand.dots = TRUE is appropriate. • To pass most of the call to another function, often model.frame. Here the common idiom is that expand.dots = FALSE is used, and the ... element of the matched call is removed. An alternative is to explicitly select the arguments to be passed on, as is done in lm. Calling match.call outside a function without specifying definition is an error. Value An object of class call. References Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also sys.call() is similar, but does not expand the argument names; call, pmatch, match.arg, match.fun. Examples match.call(get, call("get", "abc", i = FALSE, p = 3)) ## -> get(x = "abc", pos = 3, inherits = FALSE) fun <- function(x, lower = 0, upper = 1) { structure((x - lower) / (upper - lower), CALL = match.call()) } fun(4 * atan(1), u = pi) match.fun Extract a Function Specified by Name Description When called inside functions that take a function as argument, extract the desired function object while avoiding undesired matching to objects of other types. Usage match.fun(FUN, descend = TRUE) Arguments FUN item to match as function: a function, symbol or character string. See ‘Details’. descend logical; control whether to search past non-function objects. match.fun 307 Details match.fun is not intended to be used at the top level since it will perform matching in the parent of the caller. If FUN is a function, it is returned. If it is a symbol (for example, enclosed in backquotes) or a character vector of length one, it will be looked up using get in the environment of the parent of the caller. If it is of any other mode, it is attempted first to get the argument to the caller as a symbol (using substitute twice), and if that fails, an error is declared. If descend = TRUE, match.fun will look past non-function objects with the given name; otherwise if FUN points to a non-function object then an error is generated. This is used in base functions such as apply, lapply, outer, and sweep. Value A function matching FUN or an error is generated. Bugs The descend argument is a bit of misnomer and probably not actually needed by anything. It may go away in the future. It is impossible to fully foolproof this. If one attaches a list or data frame containing a length-one character vector with the same name as a function, it may be used (although namespaces will help). Author(s) Peter Dalgaard and Robert Gentleman, based on an earlier version by Jonathan Rougier. See Also match.arg, get Examples # Same as get("*"): match.fun("*") # Overwrite outer with a vector outer <- 1:5 ## Not run: match.fun(outer, descend = FALSE) #-> Error: not a function ## End(Not run) match.fun(outer) # finds it anyway is.function(match.fun("outer")) # as well 308 MathFun MathFun Miscellaneous Mathematical Functions Description These functions compute miscellaneous mathematical functions. The naming follows the standard for computer languages such as C or Fortran. Usage abs(x) sqrt(x) Arguments x a numeric or complex vector or array. Details These are internal generic primitive functions: methods can be defined for them individually or via the Math group generic. For complex arguments (and the default method), z, abs(z) == Mod(z) and sqrt(z) == z^0.5. abs(x) returns an integer vector when x is integer or logical. S4 methods Both are S4 generic and members of the Math group generic. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also Arithmetic for simple, log for logarithmic, sin for trigonometric, and Special for special math- ematical functions. ‘plotmath’ for the use of sqrt in plot annotation. Examples require(stats) # for spline require(graphics) xx <- -9:9 plot(xx, sqrt(abs(xx)), col = "red") lines(spline(xx, sqrt(abs(xx)), n=101), col = "pink") matmult 309 matmult Matrix Multiplication Description Multiplies two matrices, if they are conformable. If one argument is a vector, it will be promoted to either a row or column matrix to make the two arguments conformable. If both are vectors it will return the inner product (as a matrix). Usage x %*% y Arguments x, y numeric or complex matrices or vectors. Details When a vector is promoted to a matrix, its names are not promoted to row or column names, unlike as.matrix. This operator is S4 generic but not S3 generic. S4 methods need to be written for a function of two arguments named x and y. Value A double or complex matrix product. Use drop to remove dimensions which have only one level. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also matrix, Arithmetic, diag. Examples x <- 1:4 (z <- x %*% x) # scalar ("inner") product (1 x 1 matrix) drop(z) # as scalar y <- diag(x) z <- matrix(1:12, ncol = 3, nrow = 4) y %*% z y %*% x x %*% z 310 matrix matrix Matrices Description matrix creates a matrix from the given set of values. as.matrix attempts to turn its argument into a matrix. is.matrix tests if its argument is a (strict) matrix. Usage matrix(data = NA, nrow = 1, ncol = 1, byrow = FALSE, dimnames = NULL) as.matrix(x, ...) ## S3 method for class ’data.frame’ as.matrix(x, rownames.force = NA, ...) is.matrix(x) Arguments data an optional data vector (including a list or expression vector). Other R objects are coerced by as.vector. nrow the desired number of rows. ncol the desired number of columns. byrow logical. If FALSE (the default) the matrix is filled by columns, otherwise the matrix is filled by rows. dimnames A dimnames attribute for the matrix: NULL or a list of length 2 giving the row and column names respectively. An empty list is treated as NULL, and a list of length one as row names. The list can be named, and the list names will be used as names for the dimensions. x an R object. ... additional arguments to be passed to or from methods. rownames.force logical indicating if the resulting matrix should have character (rather than NULL) rownames. The default, NA, uses NULL rownames if the data frame has ‘auto- matic’ row.names or for a zero-row data frame. Details If one of nrow or ncol is not given, an attempt is made to infer it from the length of data and the other parameter. If neither is given, a one-column matrix is returned. If there are too few elements in data to fill the matrix, then the elements in data are recycled. If data has length zero, NA of an appropriate type is used for atomic vectors (0 for raw vectors) and NULL for lists. matrix 311 is.matrix returns TRUE if x is a vector and has a "dim" attribute of length 2) and FALSE otherwise. Note that a data.frame is not a matrix by this test. The function is generic: you can write methods to handle specific classes of objects, see InternalMethods. as.matrix is a generic function. The method for data frames will return a character matrix if there is any non-(numeric/logical/complex) column, applying format to non-character columns. Otherwise, the usual coercion hierarchy (logical < integer < double < complex) will be used, e.g., all-logical data frames will be coerced to a logical matrix, mixed logical-integer will give a integer matrix, etc. When coercing a vector, it produces a one-column matrix, and promotes the names (if any) of the vector to the rownames of the matrix. is.matrix is a primitive function. Note If you just want to convert a vector to a matrix, something like dim(x) <- c(nx, ny) dimnames(x) <- list(row_names, col_names) will avoid duplicating x. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also data.matrix, which attempts to convert to a numeric matrix. A matrix is the special case of a two-dimensional array. Examples is.matrix(as.matrix(1:10)) !is.matrix(warpbreaks)# data.frame, NOT matrix! warpbreaks[1:10,] as.matrix(warpbreaks[1:10,]) #using as.matrix.data.frame(.) method # Example of setting row and column names mdat <- matrix(c(1,2,3, 11,12,13), nrow = 2, ncol=3, byrow=TRUE, dimnames = list(c("row1", "row2"), c("C.1", "C.2", "C.3"))) mdat 312 maxCol maxCol Find Maximum Position in Matrix Description Find the maximum position for each row of a matrix, breaking ties at random. Usage max.col(m, ties.method=c("random", "first", "last")) Arguments m numerical matrix ties.method a character string specifying how ties are handled, "random" by default; can be abbreviated; see ‘Details’. Details When ties.method = "random", as per default, ties are broken at random. In this case, the determination of a tie assumes that the entries are probabilities: there is a relative tolerance of 10−5, relative to the largest (in magnitude, omitting infinity) entry in the row. If ties.method = "first", max.col returns the column number of the first of several maxima in every row, the same as unname(apply(m, 1, which.max)). Correspondingly, ties.method = "last" returns the last of possibly several indices. Value index of a maximal value for each row, an integer vector of length nrow(m). References Venables, W. N. and Ripley, B. D. (2002) Modern Applied Statistics with S. New York: Springer (4th ed). See Also which.max for vectors. Examples table(mc <- max.col(swiss))# mostly "1" and "5", 5 x "2" and once "4" swiss[unique(print(mr <- max.col(t(swiss)))) , ] # 3 33 45 45 33 6 set.seed(1)# reproducible example: (mm <- rbind(x = round(2*stats::runif(12)), y = round(5*stats::runif(12)), z = round(8*stats::runif(12)))) mean 313 ## Not run: [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] x111202211000 y324245245131 z230373454175 ## End(Not run) ## column indices of all row maxima : utils::str(lapply(1:3, function(i) which(mm[i,] == max(mm[i,])))) max.col(mm) ; max.col(mm) # "random" max.col(mm, "first")# -> 4 6 5 max.col(mm, "last") # -> 7 9 11 mean Arithmetic Mean Description Generic function for the (trimmed) arithmetic mean. Usage mean(x, ...) ## Default S3 method: mean(x, trim = 0, na.rm = FALSE, ...) Arguments x An R object. Currently there are methods for numeric/logical vectors and date, date-time and time interval objects, and for data frames all of whose columns have a method. Complex vectors are allowed for trim = 0, only. trim the fraction (0 to 0.5) of observations to be trimmed from each end of x before the mean is computed. Values of trim outside that range are taken as the nearest endpoint. na.rm a logical value indicating whether NA values should be stripped before the com- putation proceeds. ... further arguments passed to or from other methods. Value If trim is zero (the default), the arithmetic mean of the values in x is computed, as a numeric or complex vector of length one. If x is not logical (coerced to numeric), numeric (including integer) or complex, NA_real_ is returned, with a warning. If trim is non-zero, a symmetrically trimmed mean is computed with a fraction of trim observa- tions deleted from each end before the mean is computed. 314 memCompress References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also weighted.mean, mean.POSIXct, colMeans for row and column means. Examples x <- c(0:10, 50) xm <- mean(x) c(xm, mean(x, trim = 0.10)) memCompress In-memory Compression and Decompression Description In-memory compression or decompression for raw vectors. Usage memCompress(from, type = c("gzip", "bzip2", "xz", "none")) memDecompress(from, type = c("unknown", "gzip", "bzip2", "xz", "none"), asChar = FALSE) Arguments from A raw vector. For memCompress a character vector will be converted to a raw vector with character strings separated by "\n". type character string, the type of compression. May be abbreviated to a single letter, defaults to the first of the alternatives. asChar logical: should the result be converted to a character string? Details type = "none" passes the input through unchanged, but may be useful if type is a variable. type = "unknown" attempts to detect the type of compression applied (if any): this will always succeed for bzip2 compression, and will succeed for other forms if there is a suitable header. It will auto-detect the ‘magic’ header ("\x1f\x8b") added to files by the gzip program (and to files written by gzfile), but memCompress does not add such a header. bzip2 compression always adds a header ("BZh"). Memory 315 Compressing with type = "xz" is equivalent to compressing a file with xz -9e (including adding the ‘magic’ header): decompression should cope with the contents of any file compressed with xz version 4.999 and some versions of lzma. There are other versions, in particular ‘raw’ streams, that are not currently handled. All the types of compression can expand the input: for "gzip" and "bzip" the maximum expansion is known and so memCompress can always allocate sufficient space. For "xz" it is possible (but extremely unlikely) that compression will fail if the output would have been too large. Value A raw vector or a character string (if asChar = TRUE). See Also connections. http://en.wikipedia.org/wiki/Data_compression for background on data compression, http://zlib.net/, http://en.wikipedia.org/wiki/Gzip, http://www.bzip.org/, http:// en.wikipedia.org/wiki/Bzip2, http://tukaani.org/xz/ and http://en.wikipedia.org/ wiki/Xz for references about the particular schemes used. Examples txt <- readLines(file.path(R.home("doc"), "COPYING")) sum(nchar(txt)) txt.gz <- memCompress(txt, "g") length(txt.gz) txt2 <- strsplit(memDecompress(txt.gz, "g", asChar = TRUE), "\n")[[1]] stopifnot(identical(txt, txt2)) txt.bz2 <- memCompress(txt, "b") length(txt.bz2) ## can auto-detect bzip2: txt3 <- strsplit(memDecompress(txt.bz2, asChar = TRUE), "\n")[[1]] stopifnot(identical(txt, txt3)) ## xz compression is only worthwhile for large objects txt.xz <- memCompress(txt, "x") length(txt.xz) txt3 <- strsplit(memDecompress(txt.xz, asChar = TRUE), "\n")[[1]] stopifnot(identical(txt, txt3)) Memory Memory Available for Data Storage Description How R manages its workspace. mem;limits is deprecated as of R 2.14.0 316 Memory Usage mem.limits(nsize = NA, vsize = NA) Arguments vsize Heap memory in bytes. nsize Number of cons cells. Details R has a variable-sized workspace which is sized automatically. These limits are mainly historical, and now used only exceptionally. R maintains separate areas for fixed and variable sized objects. The first of these is allocated as an array of cons cells (Lisp programmers will know what they are, others may think of them as the building blocks of the language itself, parse trees, etc.), and the second are thrown on a heap of ‘Vcells’ of 8 bytes each. Each cons cell occupies 28 bytes on a 32-bit build of R, (usually) 56 bytes on a 64-bit build. The default values are (currently) an initial setting of 350k cons cells, 6Mb of vector heap: note that the areas are not actually allocated initially: rather these values are the sizes for triggering garbage collection. Thereafter R will grow or shrink the areas depending on usage, never decreasing below the initial values. You can find out the current memory consumption (the heap and cons cells used as numbers and megabytes) by typing gc() at the R prompt. Note that following gcinfo(TRUE), automatic garbage collection always prints memory use statistics. The function mem.limits is deprecated: use gc instead, which reports the limits in the exceptional case that they are set. The command-line option ‘--max-ppsize’ controls the maximum size of the pointer protection stack. This defaults to 50000, but can be increased to allow deep recursion or large and complicated calculations to be done. Note that parts of the garbage collection process goes through the full reserved pointer protection stack and hence becomes slower when the size is increased. Currently the maximum value accepted is 500000. Value mem.limits() returns a numeric vector giving the current settings of the maxima, possibly NA (for unlimited). See Also An Introduction to R for more command-line options. Memory-limits for the design limitations. gc for information on the garbage collector and total memory usage, object.size(a) for the (ap- proximate) size of R object a. memory.profile for profiling the usage of cons cells. Memory-limits 317 Memory-limits Memory Limits in R Description R holds objects it is using in virtual memory. This help file documents the current design limitations on large objects: these differ between 32-bit and 64-bit builds of R. Details Currently R runs on 32- and 64-bit operating systems, and most 64-bit OSes (including Linux, Solaris, Windows and Mac OS X) can run either 32- or 64-bit builds of R. The memory limits depends mainly on the build, but for a 32-bit build of R on Windows they also depend on the underlying OS version. R holds all objects in memory, and there are limits based on the amount of memory that can be used by all objects: • There may be limits on the size of the heap and the number of cons cells allowed – see Memory – but these are usually not imposed. • There is a limit on the (user) address space of a single process such as the R executable. This is system-specific, and can depend on the executable. • The environment may impose limitations on the resources available to a single process: Win- dows’ versions of R do so directly. Error messages beginning cannot allocate vector of size indicate a failure to obtain memory, either because the size exceeded the address-space limit for a process or, more likely, because the system was unable to provide the memory. Note that on a 32-bit build there may well be enough free memory available, but not a large enough contiguous block of address space into which to map it. There are also limits on individual objects. On all builds of R, the maximum length (number of elements) of a vector is 231 − 1 ≈ 2 109, as lengths are stored as signed integers. In addition, the storage space cannot exceed the address limit, and if you try to exceed that limit, the error message begins cannot allocate vector of length. The number of characters in a character string is in theory only limited by the address space. Unix The address-space limit is system-specific: 32-bit OSes imposes a limit of no more than 4Gb: it is often 3Gb. Running 32-bit executables on a 64-bit OS will have similar limits: 64-bit executables will have an essentially infinite system-specific limit (e.g. 128Tb for Linux on x86_64 cpus). See the OS/shell’s help on commands such as limit or ulimit for how to impose limitations on the resources available to a single process. For example a bash user could use ulimit -t 600 -m 2000000 whereas a csh user might use 318 memory.profile limit cputime 10m limit memoryuse 2048m to limit a process to 10 minutes of CPU time and (around) 2Gb of memory. Windows The address-space limit is 2Gb under 32-bit Windows unless the OS’s default has been changed to allow more (up to 3Gb). See http://www.microsoft.com/whdc/system/platform/ server/PAE/PAEmem.mspx and http://msdn.microsoft.com/en-us/library/bb613473(VS. 85).aspx. Under most 64-bit versions of Windows the limit for a 32-bit build of R is 4Gb: for the oldest ones it is 2Gb. The limit for a 64-bit build of R(imposed by the OS) is 8Tb. It is not normally possible to allocate as much as 2Gb to a single vector in a 32-bit build of R even on 64-bit Windows because of preallocations by Windows in the middle of the address space. Under Windows, R imposes limits on the total memory allocation available to a single session as the OS provides no way to do so: see memory.size and memory.limit. See Also object.size(a) for the (approximate) size of R object a. memory.profile Profile the Usage of Cons Cells Description Lists the usage of the cons cells by SEXPREC type. Usage memory.profile() Details The current types and their uses are listed in the include file ‘Rinternals.h’. Value A vector of counts, named by the types. See typeof for an explanation of types. See Also gc for the overall usage of cons cells. Rprofmem and tracemem allow memory profiling of specific code or objects, but need to be enabled at compile time. Examples memory.profile() merge 319 merge Merge Two Data Frames Description Merge two data frames by common columns or row names, or do other versions of database join operations. Usage merge(x, y, ...) ## Default S3 method: merge(x, y, ...) ## S3 method for class ’data.frame’ merge(x, y, by = intersect(names(x), names(y)), by.x = by, by.y = by, all = FALSE, all.x = all, all.y = all, sort = TRUE, suffixes = c(".x",".y"), incomparables = NULL, ...) Arguments x, y data frames, or objects to be coerced to one. by, by.x, by.y specifications of the common columns. See ‘Details’. all logical; all = L is shorthand for all.x = L and all.y = L, where L is either TRUE or FALSE. all.x logical; if TRUE, then extra rows will be added to the output, one for each row in x that has no matching row in y. These rows will have NAs in those columns that are usually filled with values from y. The default is FALSE, so that only rows with data from both x and y are included in the output. all.y logical; analogous to all.x above. sort logical. Should the results be sorted on the by columns? suffixes character(2) specifying the suffixes to be used for making non-by names() unique. incomparables values which cannot be matched. See match. ... arguments to be passed to or from methods. Details By default the data frames are merged on the columns with names they both have, but separate specifications of the columns can be given by by.x and by.y. Columns can be specified by name, number or by a logical vector: the name "row.names" or the number 0 specifies the row names. The rows in the two data frames that match on the specified columns are extracted, and joined 320 merge together. If there is more than one match, all possible matches contribute one row each. For the precise meaning of ‘match’, see match. If by or both by.x and by.y are of length 0 (a length zero vector or NULL), the result, r, is the Cartesian product of x and y, i.e., dim(r) = c(nrow(x)*nrow(y), ncol(x) + ncol(y)). If all.x is true, all the non matching cases of x are appended to the result as well, with NA filled in the corresponding columns of y; analogously for all.y. If the remaining columns in the data frames have any common names, these have suffixes (".x" and ".y" by default) appended to make the names of the result unique. The complexity of the algorithm used is proportional to the length of the answer. In SQL database terminology, the default value of all = FALSE gives a natural join, a special case of an inner join. Specifying all.x = TRUE gives a left (outer) join, all.y = TRUE a right (outer) join, and both (all=TRUE a (full) outer join. DBMSes do not match NULL records, equivalent to incomparables = NA in R. Value A data frame. The rows are by default lexicographically sorted on the common columns, but for sort = FALSE are in an unspecified order. The columns are the common columns followed by the remaining columns in x and then those in y. If the matching involved row names, an extra character column called Row.names is added at the left, and in all cases the result has ‘automatic’ row names. See Also data.frame, by, cbind Examples ## use character columns of names to get sensible sort order authors <- data.frame( surname = I(c("Tukey", "Venables", "Tierney", "Ripley", "McNeil")), nationality = c("US", "Australia", "US", "UK", "Australia"), deceased = c("yes", rep("no", 4))) books <- data.frame( name = I(c("Tukey", "Venables", "Tierney", "Ripley", "Ripley", "McNeil", "R Core")), title = c("Exploratory Data Analysis", "Modern Applied Statistics ...", "LISP-STAT", "Spatial Statistics", "Stochastic Simulation", "Interactive Data Analysis", "An Introduction to R"), other.author = c(NA, "Ripley", NA, NA, NA, NA, "Venables & Smith")) (m1 <- merge(authors, books, by.x = "surname", by.y = "name")) (m2 <- merge(books, authors, by.x = "name", by.y = "surname")) stopifnot(as.character(m1[,1]) == as.character(m2[,1]), all.equal(m1[, -1], m2[, -1][ names(m1)[-1] ]), dim(merge(m1, m2, by = integer(0))) == c(36, 10)) message 321 ## "R core" is missing from authors and appears only here : merge(authors, books, by.x = "surname", by.y = "name", all = TRUE) ## example of using ’incomparables’ x <- data.frame(k1=c(NA,NA,3,4,5), k2=c(1,NA,NA,4,5), data=1:5) y <- data.frame(k1=c(NA,2,NA,4,5), k2=c(NA,NA,3,4,5), data=1:5) merge(x, y, by=c("k1","k2")) # NA’s match merge(x, y, by=c("k1","k2"), incomparables=NA) merge(x, y, by="k1") # NA’s match, so 6 rows merge(x, y, by="k2", incomparables=NA) # 2 rows message Diagnostic Messages Description Generate a diagnostic message from its arguments. Usage message(..., domain = NULL, appendLF = TRUE) suppressMessages(expr) packageStartupMessage(..., domain = NULL, appendLF = TRUE) suppressPackageStartupMessages(expr) .makeMessage(..., domain = NULL, appendLF = FALSE) Arguments ... zero or more objects which can be coerced to character (and which are pasted together with no separator) or (for message only) a single condition object. domain see gettext. If NA, messages will not be translated. appendLF logical: should messages given as a character string have a newline appended? expr expression to evaluate. Details message is used for generating ‘simple’ diagnostic messages which are neither warnings nor errors, but nevertheless represented as conditions. Unlike warnings and errors, a final newline is regarded as part of the message, and is optional. The default handler sends the message to the stderr() connection. If a condition object is supplied to message it should be the only argument, and further arguments will be ignored, with a warning. While the message is being processed, a muffleMessage restart is available. 322 missing suppressMessages evaluates its expression in a context that ignores all ‘simple’ diagnostic mes- sages. packageStartupMessage is a variant whose messages can be suppressed separately by suppressPackageStartupMessages. (They are still messages, so can be suppressed by suppressMessages.) .makeMessage is a utility used by message, warning and stop to generate a text message from the ... arguments by possible translation (see gettext) and concatenation (with no separator). See Also warning and stop for generating warnings and errors; conditions for condition handling and recovery. gettext for the mechanisms for the automated translation of text. Examples message("ABC", "DEF") suppressMessages(message("ABC")) testit <- function() { message("testing package startup messages") packageStartupMessage("initializing ...", appendLF = FALSE) Sys.sleep(1) packageStartupMessage(" done") } testit() suppressPackageStartupMessages(testit()) suppressMessages(testit()) missing Does a Formal Argument have a Value? Description missing can be used to test whether a value was specified as an argument to a function. Usage missing(x) Arguments x a formal argument. mode 323 Details missing(x) is only reliable if x has not been altered since entering the function: in particular it will always be false after x <- match.arg(x). The example shows how a plotting function can be written to work with either a pair of vectors giving x and y coordinates of points to be plotted or a single vector giving y values to be plotted against their indices. Currently missing can only be used in the immediate body of the function that defines the argument, not in the body of a nested function or a local call. This may change in the future. This is a ‘special’ primitive function: it must not evaluate its argument. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also substitute for argument expression; NA for missing values in data. Examples myplot <- function(x,y) { if(missing(y)) { y <- x x <- 1:length(y) } plot(x,y) } mode The (Storage) Mode of an Object Description Get or set the type or storage mode of an object. Usage mode(x) mode(x) <- value storage.mode(x) storage.mode(x) <- value 324 mode Arguments x any R object. value a character string giving the desired mode or ‘storage mode’ (type) of the object. Details Both mode and storage.mode return a character string giving the (storage) mode of the object — often the same — both relying on the output of typeof(x), see the example below. mode(x) <- "newmode" changes the mode of object x to newmode. This is only supported if there is an appropriate as.newmode function, for example "logical","integer","double","complex", "raw","character","list","expression","name","symbol" and "function". Attributes are preserved (but see below). storage.mode(x) <- "newmode" is a more efficient primitive version of mode<-, which works for "newmode" which is one of the internal types (see typeof), but not for "single". Attributes are preserved. As storage mode "single" is only a pseudo-mode in R, it will not be reported by mode or storage.mode: use attr(object, "Csingle") to examine this. However, mode<- can be used to set the mode to "single", which sets the real mode to "double" and the "Csingle" attribute to TRUE. Setting any other mode will remove this attribute. Note (in the examples below) that some calls have mode "(" which is S compatible. Mode names Modes have the same set of names as types (see typeof) except that • types "integer" and "double" are returned as "numeric". • types "special" and "builtin" are returned as "function". • type "symbol" is called mode "name". • type "language" is returned as "(" or "call". References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also typeof for the R-internal ‘mode’, attributes. Examples require(stats) sapply(options(),mode) cex3 <- c("NULL","1","1:1","1i","list(1)","data.frame(x=1)", "pairlist(pi)", "c", "lm", "formals(lm)[[1]]", "formals(lm)[[2]]", NA 325 "y~x","expression((1))[[1]]", "(y~x)[[1]]", "expression(x <- pi)[[1]][[1]]") lex3 <- sapply(cex3, function(x) eval(parse(text=x))) mex3 <- t(sapply(lex3, function(x) c(typeof(x), storage.mode(x), mode(x)))) dimnames(mex3) <- list(cex3, c("typeof(.)","storage.mode(.)","mode(.)")) mex3 ## This also makes a local copy of ’pi’: storage.mode(pi) <- "complex" storage.mode(pi) rm(pi) NA ‘Not Available’ / Missing Values Description NA is a logical constant of length 1 which contains a missing value indicator. NA can be coerced to any other vector type except raw. There are also constants NA_integer_, NA_real_, NA_complex_ and NA_character_ of the other atomic vector types which support missing values: all of these are reserved words in the R language. The generic function is.na indicates which elements are missing. The generic function is.na<- sets elements to NA. Usage NA is.na(x) ## S3 method for class ’data.frame’ is.na(x) is.na(x) <- value Arguments x an R object to be tested: the default method handles atomic vectors, lists and pairlists. value a suitable index vector for use with x. Details The NA of character type is distinct from the string "NA". Programmers who need to specify an explicit string NA should use NA_character_ rather than "NA", or set elements to NA using is.na<- . is.na(x) works elementwise when x is a list. It is generic: you can write methods to handle specific classes of objects, see InternalMethods. A complex value is regarded as NA if either its real or imaginary part is NA or NaN. 326 name Function is.na<- may provide a safer way to set missingness. It behaves differently for factors, for example. Computations using NA will normally result in NA: a possible exception is where NaN is also involved, in which case either might result. Value The default method for is.na applied to an atomic vector returns a logical vector of the same length as its argument x, containing TRUE for those elements marked NA or, for numeric or complex vectors, NaN (!) and FALSE otherwise. dim, dimnames and names attributes are preserved. The default method also works for lists and pairlists: the result for an element is false unless that element is a length-one atomic vector and the single element of that vector is regarded as NA or NaN. The method is.na.data.frame returns a logical matrix with the same dimensions as the data frame, and with dimnames taken from the row and column names of the data frame. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also NaN, is.nan, etc., and the utility function complete.cases. na.action, na.omit, na.fail on how methods can be tuned to deal with missing values. Examples is.na(c(1, NA)) #> FALSE TRUE is.na(paste(c(1, NA))) #> FALSE FALSE (xx <- c(0:4)) is.na(xx) <- c(2, 4) xx #> 0 NA 2 NA 4 name Names and Symbols Description A ‘name’ (also known as a ‘symbol’) is a way to refer to R objects by name (rather than the value of the object, if any, bound to that name). as.name and as.symbol are identical: they attempt to coerce the argument to a name. is.symbol and the identical is.name return TRUE or FALSE depending on whether the argument is a name or not. name 327 Usage as.symbol(x) is.symbol(x) as.name(x) is.name(x) Arguments x object to be coerced or tested. Details Names are limited to 10,000 bytes (and were to 256 bytes in versions of R before 2.13.0). as.name first coerces its argument internally to a character vector (so methods for as.character are not used). It then takes the first element and provided it is not "", returns a symbol of that name (and if the element is NA_character_, the name is ‘NA‘). as.name is implemented as as.vector(x, "symbol"), and hence will dispatch methods for the generic function as.vector. is.name and is.symbol are primitive functions. Value For as.name and as.symbol, an R object of type "symbol" (see typeof). For is.name and is.symbol, a length-one logical vector with value TRUE or FALSE. Note The term ‘symbol’ is from the LISP background of R, whereas ‘name’ has been the standard S term for this. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also call, is.language. For the internal object mode, typeof. plotmath for another use of ‘symbol’. Examples an <- as.name("arrg") is.name(an) # TRUE mode(an) # name typeof(an) # symbol 328 names names The Names of an Object Description Functions to get or set the names of an object. Usage names(x) names(x) <- value Arguments x an R object. value a character vector of up to the same length as x, or NULL. Details names is a generic accessor function, and names<- is a generic replacement function. The default methods get and set the "names" attribute of a vector (including a list) or pairlist. If value is shorter than x, it is extended by character NAs to the length of x. It is possible to update just part of the names attribute via the general rules: see the examples. This works because the expression there is evaluated as z <- "names<-"(z, "[<-"(names(z), 3, "c2")). The name "" is special: it is used to indicate that there is no name associated with an element of a (atomic or generic) vector. Subscripting by "" will match nothing (not even elements which have no name). A name can be character NA, but such a name will never be matched and is likely to lead to confusion. Both are primitive functions. Value For names, NULL or a character vector of the same length as x.(NULL is given if the object has no names, including for objects of types which cannot have names.) For names<-, the updated object. (Note that the value of names(x) <- value is that of the assign- ment, value, not the return value from the left-hand side.) Note For vectors, the names are one of the attributes with restrictions on the possible values. For pairlists, the names are the tags and converted to and from a character vector. For a one-dimensional array the names attribute really is dimnames[[1]]. Formally classed aka “S4” objects typically have slotNames() (and no names()). nargs 329 References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also slotNames, dimnames. Examples # print the names attribute of the islands data set names(islands) # remove the names attribute names(islands) <- NULL islands rm(islands) # remove the copy made z <- list(a=1, b="c", c=1:3) names(z) # change just the name of the third element. names(z)[3] <- "c2" z z <- 1:3 names(z) ## assign just one name names(z)[2] <- "b" z nargs The Number of Arguments to a Function Description When used inside a function body, nargs returns the number of arguments supplied to that function, including positional arguments left blank. Usage nargs() Details The count includes empty (missing) arguments, so that foo(x,,z) will be considered to have three arguments (see ‘Examples’). This can occur in rather indirect ways, so for example x[] might dispatch a call to ‘[.some_method‘(x, ) which is considered to have two arguments. This is a primitive function. 330 nchar References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also args, formals and sys.call. Examples tst <- function(a, b = 3, ...) {nargs()} tst() # 0 tst(clicketyclack) # 1 (even non-existing) tst(c1, a2, rr3) # 3 foo <- function(x, y, z, w) { cat("call was", deparse(match.call()), "\n") nargs() } foo() # 0 foo(,,3) # 3 foo(z=3) # 1, even though this is the same call nargs()# not really meaningful nchar Count the Number of Characters (or Bytes or Width) Description nchar takes a character vector as an argument and returns a vector whose elements contain the sizes of the corresponding elements of x. nzchar is a fast way to find out if elements of a character vector are non-empty strings. Usage nchar(x, type = "chars", allowNA = FALSE) nzchar(x) Arguments x character vector, or a vector to be coerced to a character vector. type character string: partial matching to one of c("bytes", "chars", "width"). See ‘Details’. allowNA logical: should NA be returned for invalid multibyte strings or "bytes"-encoded strings (rather than throwing an error)? nchar 331 Details The ‘size’ of a character string can be measured in one of three ways bytes The number of bytes needed to store the string (plus in C a final terminator which is not counted). chars The number of human-readable characters. width The number of columns cat will use to print the string in a monospaced font. The same as chars if this cannot be calculated. These will often be the same, and almost always will be in single-byte locales. There will be differences between the first two with multibyte character sequences, e.g. in UTF-8 locales. The internal equivalent of the default method of as.character is performed on x (so there is no method dispatch). If you want to operate on non-vector objects passing them through deparse first will be required. Value For nchar, an integer vector giving the sizes of each element, currently always 2 for missing values (for NA). If allowNA = TRUE and an element is invalid in a multi-byte character set such as UTF-8, its number of characters and the width will be NA. Otherwise the number of characters will be non-negative, so !is.na(nchar(x, "chars", TRUE)) is a test of validity. A character string marked with "bytes" encoding has a number of bytes, but neither a known number of characters nor a width, so the latter two types are NA if allowNA = TRUE, otherwise an error. Names, dims and dimnames are copied from the input. For nzchar, a logical vector of the same length as x, true if and only if the element has non-zero length. Note This does not by default give the number of characters that will be used to print() the string. Use encodeString to find the characters used to print the string. Where character strings have been marked as UTF-8, the number of characters and widths will be computed in UTF-8, even though printing may use escapes such as ‘’ in a non-UTF-8 locale. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also strwidth giving width of strings for plotting; paste, substr, strsplit 332 nlevels Examples x <- c("asfef", "qwerty", "yuiop[", "b", "stuff.blah.yech") nchar(x) # 5 6 6 1 15 nchar(deparse(mean)) # 18 17 nlevels The Number of Levels of a Factor Description Return the number of levels which its argument has. Usage nlevels(x) Arguments x an object, usually a factor. Details This is usually applied to a factor, but other objects can have levels. The actual factor levels (if they exist) can be obtained with the levels function. Value The length of levels(x), which is zero if x has no levels. See Also levels, factor. Examples nlevels(gl(3,7)) # = 3 noquote 333 noquote Class for ‘no quote’ Printing of Character Strings Description Print character strings without quotes. Usage noquote(obj) ## S3 method for class ’noquote’ print(x, ...) ## S3 method for class ’noquote’ c(..., recursive = FALSE) Arguments obj any R object, typically a vector of character strings. x an object of class "noquote". ... further options passed to next methods, such as print. recursive for compatibility with the generic c function. Details noquote returns its argument as an object of class "noquote". There is a method for c() and subscript method ("[.noquote") which ensures that the class is not lost by subsetting. The print method (print.noquote) prints character strings without quotes ("..."). These functions exist both as utilities and as an example of using (S3) class and object orientation. Author(s) Martin Maechler See Also methods, class, print. Examples letters nql <- noquote(letters) nql nql[1:4] <- "oh" nql[1:12] 334 norm cmp.logical <- function(log.v) { ## Purpose: compact printing of logicals log.v <- as.logical(log.v) noquote(if(length(log.v)==0)"()" else c(".","|")[1+log.v]) } cmp.logical(stats::runif(20) > 0.8) norm Compute the Norm of a Matrix Description Computes a matrix norm of x using Lapack. The norm can be the one norm, the infinity norm, the Frobenius norm, or the maximum modulus among elements of a matrix, as determined by the value of type. Usage norm(x, type = c("O", "I", "F", "M")) Arguments x numeric matrix; note that packages such as Matrix define more norm() meth- ods. type character string, specifying the type of matrix norm to be computed. A character indicating the type of norm desired. "O","o" or "1" specifies the one norm, (maximum absolute column sum); "I" or "i" specifies the infinity norm (maximum absolute row sum); "F" or "f" specifies the Frobenius norm (the Euclidean norm of x treated as if it were a vector); and "M" or "m" specifies the maximum modulus of all the elements in x. The default is "O". Only the first character of type[1] is used. Details The base method of norm() calls the Lapack function dlange. Note that the 1-, Inf- and "M" norm is faster to calculate than the Frobenius one. Value The matrix norm, a non-negative number. References Anderson, E., et al. (1994). LAPACK User’s Guide, 2nd edition, SIAM, Philadelphia. normalizePath 335 See Also rcond for the (reciprocal) condition number. Examples (x1 <- cbind(1,1:10)) norm(x1) norm(x1, "I") norm(x1, "M") stopifnot(all.equal(norm(x1, "F"), sqrt(sum(x1^2)))) hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") } h9 <- hilbert(9) ## all 4 types of norm: (nTyp <- eval(formals(base::norm)$type)) sapply(nTyp, norm, x=h9) normalizePath Express File Paths in Canonical Form Description Convert file paths to canonical form for the platform, to display them in a user-understandable form and so that relative and absolute paths can be compared. Usage normalizePath(path, winslash = "\\", mustWork = NA) Arguments path character vector of file paths. winslash the separator to be used on Windows – ignored elsewhere. Must be one of c("/", "\\"). mustWork logical: if TRUE then an error is given if the result cannot be determined; if NA then a warning. Details Tilde-expansion (see path.expand) is first done on paths (as from R 2.13.0). Where the Unix-alike platform supports it attempts to turn paths into absolute paths in their canon- ical form (no ‘./’, ‘../’ nor symbolic links). It relies on the POSIX system function realpath: if the platform does not have that (we know of no current example) then the result will be an absolute path but might not be canonical. Even where realpath is used the canonical path need not be unique, for example via hard links or multiple mounts. 336 NotYet On Windows it converts relative paths to absolute paths, converts short names for path elements to long names and ensures the separator is that specified by winslash. It will match paths case- insensitively and return the canonical case. UTF-8-encoded paths not valid in the current locale can be used. mustWork = FALSE is useful for expressing paths for use in messages. Value A character vector. If an input is not a real path the result is system-dependent (unless mustWork = TRUE, when this should be an error). It will be either the corresponding input element or a transformation of it into an absolute path. Converting to an absolute file path can fail for a large number of reasons. The most common are • One of more components of the file path does not exist. • A component before the last is not a directory, or there is insufficient permission to read the directory. • For a relative path, the current directory cannot be determined. • A symbolic link points to a non-existent place or links form a loop. • The canonicalized path would be exceed the maximum supported length of a file path. Examples # random tempdir cat(normalizePath(c(R.home(), tempdir())), sep = "\n") NotYet Not Yet Implemented Functions and Unused Arguments Description In order to pinpoint missing functionality, the R core team uses these functions for missing R func- tions and not yet used arguments of existing R functions (which are typically there for compatibility purposes). You are very welcome to contribute your code . . . Usage .NotYetImplemented() .NotYetUsed(arg, error = TRUE) Arguments arg an argument of a function that is not yet used. error a logical. If TRUE, an error is signalled; if FALSE; only a warning is given. nrow 337 See Also the contrary, Deprecated and Defunct for outdated code. Examples require(graphics) require(stats) plot.mlm # to see how the "NotYetImplemented" # reference is made automagically try(plot.mlm()) barplot(1:5, inside = TRUE) # ’inside’ is not yet used nrow The Number of Rows/Columns of an Array Description nrow and ncol return the number of rows or columns present in x. NCOL and NROW do the same treating a vector as 1-column matrix. Usage nrow(x) ncol(x) NCOL(x) NROW(x) Arguments x a vector, array or data frame Value an integer of length 1 or NULL. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole (ncol and nrow.) See Also dim which returns all dimensions; array, matrix. 338 ns-dblcolon Examples ma <- matrix(1:12, 3, 4) nrow(ma) # 3 ncol(ma) # 4 ncol(array(1:24, dim = 2:4)) # 3, the second dimension NCOL(1:12) # 1 NROW(1:12) # 12 ns-dblcolon Double Colon and Triple Colon Operators Description Accessing exported and internal variables in a namespace. Usage pkg::name pkg:::name Arguments pkg package name: symbol or literal character string. name variable name: symbol or literal character string. Details For a package pkg, pkg::name returns the value of the exported variable name in namespace pkg, whereas pkg:::name returns the value of the internal variable name. The namespace will be loaded if it was not loaded before the call, but the package will not be attached to the search path. Specifying a variable or package that does not exist is an error. Note that pkg::name does not access the objects in the environment package:pkg (which does not exist until the package’s namespace is attached): the latter may contain objects not exported from the namespace. As from R 2.14.0 it can access datasets made available by lazy-loading. Note It is typically a design mistake to use ::: in your code since the corresponding object has probably been kept internal for a good reason. Consider contacting the package maintainer if you feel the need to access the object for anything but mere inspection. See Also get to access an object masked by another of the same name. ns-hooks 339 Examples base::log base::"+" ## Beware -- use ’:::’ at your own risk! (see "Details") stats:::coef.default ns-hooks Hooks for Namespace Events Description Packages can supply functions to be called when loaded, attached, detached or unloaded. Usage .onLoad(libname, pkgname) .onAttach(libname, pkgname) .onUnload(libpath) .Last.lib(libpath) Arguments libname a character string giving the library directory where the package defining the namespace was found. pkgname a character string giving the name of the package. libpath a character string giving the complete path to the package. Details After loading, loadNamespace looks for a hook function named .onLoad and calls it (with two unnamed arguments) before sealing the namespace and processing exports. When the package is attached (via library or attachNamespace), the hook function .onAttach is looked for and if found is called (with two unnamed arguments) before the package environment is sealed. If a function .Last.lib is exported in the package, it will be called (with a single argument) when the package is detached. Beware that it might be called if .onAttach has failed, so it should be written defensively. (It is called within try, so errors will not stop the package being detached.) If a namespace is unloaded (via unloadNamespace), a hook function .onUnload is run (with a single argument) before final unloading. Note that the code in .onLoad and .onUnload is run without the package being on the search path, but (unless circumvented) lexical scope will make objects in the namespace and its imports visible. (Do not use the double colon operator in .onLoad as exports have not been processed at the point it is run.) 340 ns-load .onLoad,.onUnload and .onAttach are looked for as internal objects in the namespace and should not be exported (whereas .Last.lib should be). Anything needed for the functioning of the namespace should be handled at load/unload times by the .onLoad and .onUnload hooks. For example, DLLs can be loaded (unless done by a useDynLib directive in the ‘NAMESPACE’ file) and initialized in .onLoad and unloaded in .onUnload. Use .onAttach only for actions that are needed only when the package becomes visible to the user (for example a start-up message) or need to be run after the package environment has been created. Good practice Loading a namespace should where possible be silent, with startup messages given by .onAttach. These messages (and any essential ones from .onLoad) should use packageStartupMessage so they can be silenced where they would be a distraction. There should be no calls to library nor require in these hooks. The way for a package to load other packages is via the ‘Depends’ field in the ‘DESCRIPTION’ file: this ensures that the dependence is documented and packages are loaded in the correct order. Loading a namespace should not change the search path, so rather than attach a package, dependence of a namespace on another package should be achieved by (selectively) importing from the other package’s namespace. As from R 2.14.0, uses of library with argument help to display basic information about the package should use format on the computed package information object and pass this to packageStartupMessage. See Also setHook shows how users can set hooks on the same events, and lists the sequence of events in- volving all of the hooks. ns-load Loading and Unloading Namespaces Description Functions to load and unload namespaces. Usage attachNamespace(ns, pos = 2, dataPath = NULL, depends = NULL) loadNamespace(package, lib.loc = NULL, keep.source = getOption("keep.source.pkgs"), partial = FALSE) requireNamespace(package, ..., quietly = FALSE) loadedNamespaces() unloadNamespace(ns) ns-load 341 Arguments ns string or namespace object. pos integer specifying position to attach. dataPath path to directory containing a database of datasets to be lazy-loaded into the attached environment. depends NULL or a character vector of dependencies to be recorded in object .Depends in the package. package string naming the package/namespace to load. lib.loc character vector specifying library search path. keep.source Now ignored except during package installation. For more details see this argu- ment to library. partial logical; if true, stop just after loading code. quietly logical: should progress and error messages be suppressed? ... further arguments to be passed to loadNamespace. Details The functions loadNamespace and attachNamespace are usually called implicitly when library is used to load a name space and any imports needed. However it may be useful to call these functions directly at times. loadNamespace loads the specified namespace and registers it in an internal data base. A request to load a namespace when one of that name is already loaded has no effect. The arguments have the same meaning as the corresponding arguments to library, whose help page explains the details of how a particular installed package comes to be chosen. After loading, loadNamespace looks for a hook function named .onLoad as an internal variable in the namespace (it should not be exported). This function is called with the same arguments as .First.lib. Partial loading is used to support installation with the ‘--lazy’ option. loadNamespace does not attach the namespace it loads to the search path. attachNamespace can be used to attach a frame containing the exported values of a namespace to the search path (but this is almost always done via library). The hook function .onAttach is run after the namespace exports are attached. requireNamespace is a wrapper for loadNamespace analogous to require that returns a logical value. loadedNamespaces returns a character vector of the names of the loaded namespaces. unloadNamespace can be used to attempt to force a namespace to be unloaded. If the namespace is attached, it is first detached, thereby running a .Last.lib function in the namespace if one is exported. Then an error is signaled if the namespace is imported by other loaded namespaces, and the namespace is not unloaded. If defined, a hook function .onUnload is run before removing the namespace from the internal registry. See the comments in the help for detach about some issues with unloading and reloading names- paces. 342 ns-topenv Value attachNamespace returns invisibly the package environment it adds to the search path. loadNamespace returns the namespace environment, either one already loaded or the one the func- tion causes to be loaded. requireNamespace returns TRUE if it succeeds or FALSE. loadedNamespaces returns a character vector. unloadNamespace returns NULL, invisibly. Author(s) Luke Tierney and R-core ns-topenv Top Level Environment Description Finding the top level environment. Usage topenv(envir = parent.frame(), matchThisEnv = getOption("topLevelEnvironment")) Arguments envir environment. matchThisEnv return this environment, if it matches before any other criterion is satisfied. The default, the option ‘topLevelEnvironment’, is set by sys.source, which treats a specific environment as the top level environment. Supplying the argument as NULL means it will never match. Details topenv returns the first top level environment found when searching envir and its enclosing envi- ronments. An environment is considered top level if it is the internal environment of a namespace, a package environment in the search path, or .GlobalEnv. Examples topenv(.GlobalEnv) topenv(new.env()) NULL 343 NULL The Null Object Description NULL represents the null object in R: it is a reserved word. NULL is often returned by expressions and functions whose value is undefined: it is also used as the empty pairlist. as.null ignores its argument and returns the value NULL. is.null returns TRUE if its argument is NULL and FALSE otherwise. Usage NULL as.null(x, ...) is.null(x) Arguments x an object to be tested or coerced. ... ignored. Note is.null is a primitive function. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Examples is.null(list()) # FALSE (on purpose!) is.null(integer(0))# F is.null(logical(0))# F as.null(list(a=1,b=’c’)) 344 numeric numeric Numeric Vectors Description Creates or coerces objects of type "numeric". is.numeric is a more general test of an object being interpretable as numbers. Usage numeric(length = 0) as.numeric(x, ...) is.numeric(x) Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. Details numeric is identical to double (and real). It creates a double-precision vector of the specified length with each element equal to 0. as.numeric is a generic function, but S3 methods must be written for as.double. It is identical to as.double (and as.real). is.numeric is an internal generic primitive function: you can write methods to handle specific classes of objects, see InternalMethods. It is not the same as is.double. Factors are handled by the default method, and there are methods for classes "Date","POSIXt" and "difftime"(all of which return false). Methods for is.numeric should only return true if the base type of the class is double or integer and values can reasonably be regarded as numeric (e.g. arithmetic on them makes sense, and comparison should be done via the base type). Value for numeric and as.numeric see double. The default method for is.numeric returns TRUE if its argument is of mode "numeric" (type "double" or type "integer") and not a factor, and FALSE otherwise. That is, is.integer(x) || is.double(x), or (mode(x) == "numeric") && !is.factor(x). S4 methods as.numeric and is.numeric are internally S4 generic and so methods can be set for them via setMethod. To ensure that as.numeric, as.double and as.real remain identical, S4 methods can only be set for as.numeric. NumericConstants 345 Note on names It is a historical anomaly that R has three names for its floating-point vectors, double, numeric and real. double is the name of the type. numeric is the name of the mode and also of the implicit class. As an S4 formal class, use "numeric". real is deprecated and should not be used in new code. The potential confusion is that R has used mode "numeric" to mean ‘double or integer’, which conflicts with the S4 usage. Thus is.numeric tests the mode, not the class, but as.numeric (which is identical to as.double) coerces to the class. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also double, integer, storage.mode. Examples as.numeric(c("-.1"," 2.7 ","B")) # (-0.1, 2.7, NA) + warning as.numeric(factor(5:10)) NumericConstants Numeric Constants Description How R parses numeric constants. Details R parses numeric constants in its input in a very similar way to C99 floating-point constants. Inf and NaN are numeric constants (with typeof(.) "double"). These are recognized ignoring case, as is infinity as an alternative to Inf. NA_real_ and NA_integer_ are constants of types "double" and "integer" representing missing values. All other numeric constants start with a digit or period and are either a decimal or hexadecimal constant optionally followed by L. Hexadecimal constants start with 0x or 0X followed by a nonempty sequence from 0-9 a-f A-F . which is interpreted as a hexadecimal number, optionally followed by a binary exponent. A binary exponent consists of a P or p followed by an optional plus or minus sign followed by a non-empty sequence of (decimal) digits, and indicates multiplication by a power of two. Thus 0x123p456 is 291 × 2456. Decimal constants consist of a nonempty sequence of digits possibly containing a period (the dec- imal point), optionally followed by a decimal exponent. A decimal exponent consists of an E or 346 numeric_version e followed by an optional plus or minus sign followed by a non-empty sequence of digits, and indicates multiplication by a power of ten. Values which are too large or too small to be representable will overflow to Inf or underflow to 0.0. A numeric constant immediately followed by i is regarded as an imaginary complex number. An numeric constant immediately followed by L is regarded as an integer number when possible (and with a warning if it contains a "."). Only the ASCII digits 0–9 are recognized as digits, even in languages which have other representa- tions of digits. The ‘decimal separator’ is always a period and never a comma. Note that a leading plus or minus is not regarded by the parser as part of a numeric constant but as a unary operator applied to the constant. Note When a string is parsed to input a numeric constant, the number may or may not be representable exactly in the C double type used. If not one of the nearest representable numbers will be returned. R’s own C code is used to convert constants to binary numbers, so the effect can be expected to be the same on all platforms implementing full IEC 600559 arithmetic (the most likely area of difference being the handling of numbers less than .Machine$double.xmin). The same code is used by scan. See Also Syntax. Quotes for the parsing of character constants, Examples 2.1 typeof(2) sqrt(1i) # remember elementary math? utils::str(0xA0) identical(1L, as.integer(1)) ## You can combine the "0x" prefix with the "L" suffix : identical(0xFL, as.integer(15)) numeric_version Numeric Versions Description A simple S3 class for representing numeric versions including package versions, and associated methods. numeric_version 347 Usage numeric_version(x, strict = TRUE) package_version(x, strict = TRUE) R_system_version(x, strict = TRUE) getRversion() Arguments x a character vector with suitable numeric version strings (see ‘Details’); for package_version, alternatively an R version object as obtained by R.version. strict a logical indicating whether invalid numeric versions should results in an error (default) or not. Details Numeric versions are sequences of one or more non-negative integers, usually (e.g., in package ‘DESCRIPTION’ files) represented as character strings with the elements of the sequence concate- nated and separated by single ‘.’ or ‘-’ characters. R package versions consist of at least two such integers, an R system version of exactly three (major, minor and patchlevel). Functions numeric_version, package_version and R_system_version create a representation from such strings (if suitable) which allows for coercion and testing, combination, comparison, summaries (min/max), inclusion in data frames, subscripting, and printing. The classes can hold a vector of such representations. getRversion returns the version of the running R as an R system version object. The [[ operator extracts or replaces a single version. To access the integers of a version use two indices: see the examples. See Also compareVersion Examples x <- package_version(c("1.2-4", "1.2-3", "2.1")) x < "1.4-2.3" c(min(x), max(x)) x[2, 2] x$major x$minor if(getRversion() <= "2.5.0") { ## work around missing feature cat("Your version of R, ", as.character(getRversion()), ", is outdated.\n", "Now trying to work around that ...\n", sep = "") } x[[c(1,3)]] # ’4’ as a numeric vector, same as x[1, 3] x[1, 3] # 4 as an integer x[[2, 3]] <- 0 # zero the patchlevel 348 octmode x[[c(2,3)]] <- 0 # same x x[[3]] <- "2.2.3"; x octmode Display Numbers in Octal Description Convert or print integers in octal format, with as many digits as are needed to display the largest, using leading zeroes as necessary. Usage as.octmode(x) ## S3 method for class ’octmode’ as.character(x, ...) ## S3 method for class ’octmode’ format(x, width = NULL, ...) ## S3 method for class ’octmode’ print(x, ...) Arguments x An object, for the methods inheriting from class "octmode". width NULL or a positive integer specifying the minimum field width to be used, with padding by leading zeroes. ... further arguments passed to or from other methods. Details Class "octmode" consists of integer vectors with that class attribute, used merely to ensure that they are printed in octal notation, specifically for Unix-like file permissions such as 755. Subsetting ([) works too. If width = NULL (the default), the output is padded with leading zeroes to the smallest width needed for all the non-missing elements. as.octmode can convert integers (of type "integer" or "double") and character vectors whose elements contain only digits 0-7 (or are NA) to class "octmode". There is a ! method and |,& and xor methods: these recycle their arguments to the length of the longer and then apply the operators bitwise to each element. on.exit 349 See Also These are auxiliary functions for file.info. hexmode, sprintf for other options in converting integers to octal, strtoi to convert octal strings to integers. Examples (on <- as.octmode(c(16,32, 127:129))) # "020" "040" "177" "200" "201" unclass(on[3:4]) # subsetting ## manipulate file modes fmode <- as.octmode("170") (fmode | "644") & "755" umask <- Sys.umask(NA) # depends on platform c(fmode, "666", "755") & !umask on.exit Function Exit Code Description on.exit records the expression given as its argument as needing to be executed when the current function exits (either naturally or as the result of an error). This is useful for resetting graphical parameters or performing other cleanup actions. If no expression is provided, i.e., the call is on.exit(), then the current on.exit code is removed. Usage on.exit(expr = NULL, add = FALSE) Arguments expr an expression to be executed. add if TRUE, add expr to be executed after any previously set expressions; other- wise (the default) expr will overwrite any previously set expressions. Details Where expr was evaluated changed in R 2.8.0, and the following applies only to that and later versions. The expr argument passed to on.exit is recorded without evaluation. If it is not subsequently removed/replaced by another on.exit call in the same function, it is evaluated in the evaluation frame of the function when it exits (including during standard error handling). Thus any functions or variables in the expression will be looked for in the function and its environment at the time of exit: to capture the current value in expr use substitute or similar. This is a ‘special’ primitive function: it only evaluates the argument add. 350 Ops.Date Value Invisible NULL. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also sys.on.exit which returns the expression stored for use by on.exit() in the function in which sys.on.exit() is evaluated. Examples require(graphics) opar <- par(mai = c(1,1,1,1)) on.exit(par(opar)) Ops.Date Operators on the Date Class Description Operators for the "Date" class. There is an Ops method and specific methods for + and - for the Date class. Usage date + x x + date date - x date1 lop date2 Arguments date date objects date1, date2 date objects or character vectors. (Character vectors are converted by as.Date.) x a numeric vector (in days) or an object of class "difftime", rounded to the nearest whole day. lop One of ==,!=, <, <=, > or >=. options 351 Details x does not need to be integer if specified as a numeric vector, but see the comments about fractional days in the help for Dates. Examples (z <- Sys.Date()) z + 10 z < c("2009-06-01", "2010-01-01", "2015-01-01") options Options Settings Description Allow the user to set and examine a variety of global options which affect the way in which R computes and displays its results. Usage options(...) getOption(x, default = NULL) .Options Arguments ... any options can be defined, using name = value or by passing a list of such tagged values. However, only the ones below are used in base R. Further, options(’name’) == options()[’name’], see the example. x a character string holding an option name. default if the specified option is not set in the options list, this value is returned. This facilitates retrieving an option and checking whether it is set and setting it sepa- rately if not. Details Invoking options() with no arguments returns a list with the current values of the options. Note that not all options listed below are set initially. To access the value of a single option, one should use getOption("width"), e.g., rather than options("width") which is a list of length one. .Options also always contains the options() list (as a pairlist, unsorted), for S compatibility. Assigning to it will make a local copy and not change the original. 352 options Value For getOption, the current value set for option x, or NULL if the option is unset. For options(), a list of all set options sorted by name. For options(name), a list of length one containing the set value, or NULL if it is unset. For uses setting one or more options, a list with the previous values of the options changed (returned invisibly). Options used in base R add.smooth: typically logical, defaulting to TRUE. Could also be set to an integer for specifying how many (simulated) smooths should be added. This is currently only used by plot.lm. browserNLdisabled: logical: whether newline is disabled as a synonym for "n" is the browser. checkPackageLicense: logical, not set by default. If true, library asks a user to accept any non-standard license at first use. check.bounds: logical, defaulting to FALSE. If true, a warning is produced whenever a vector (atomic or list) is extended, by something like x <- 1:3; x[5] <- 6. continue: a non-empty string setting the prompt used for lines which continue over one line. defaultPackages: the packages that are attached by default when R starts up. Initially set from value of the environment variable R_DEFAULT_PACKAGES, or if that is unset to c("datasets", "utils", "grDevices", "graphics", "stats", "methods"). (Set R_DEFAULT_PACKAGES to NULL or a comma-separated list of package names.) A call to options should be in your ‘.Rprofile’ file to ensure that the change takes effect before the base package is initialized (see Startup). deparse.max.lines: controls the number of lines used when deparsing in traceback, browser, and upon entry to a function whose debugging flag is set. Initially unset, and only used if set to a positive integer. digits: controls the number of digits to print when printing numeric values. It is a suggestion only. Valid values are 1. . . 22 with default 7. See the note in print.default about values greater than 15. digits.secs: controls the maximum number of digits to print when formatting time values in seconds. Valid values are 0. . . 6 with default 0. See strftime. download.file.extra: Extra command-line argument(s) for non-default methods: see download.file. download.file.method: Method to be used for download.file. Currently download methods "internal","wget" and "lynx" are available. There is no default for this option, when method = "auto" is chosen: see download.file. echo: logical. Only used in non-interactive mode, when it controls whether input is echoed. Command-line option ‘--slave’ sets this to FALSE, but otherwise it starts the session as TRUE. encoding: The name of an encoding, default "native.enc"). See connections. error: either a function or an expression governing the handling of non-catastrophic errors such as those generated by stop as well as by signals and internally detected errors. If the option is a function, a call to that function, with no arguments, is generated as the expression. The default value is NULL: see stop for the behaviour in that case. The functions dump.frames and recover provide alternatives that allow post-mortem debugging. Note that these need to specified as e.g. options(error=utils::recover) in startup files such as ‘.Rprofile’. options 353 expressions: sets a limit on the number of nested expressions that will be evaluated. Valid values are 25. . . 500000 with default 5000. If you increase it, you may also want to start R with a larger protection stack; see ‘--max-ppsize’ in Memory. Note too that you may cause a segfault from overflow of the C stack, and on OSes where it is possible you may want to increase that. keep.source: When TRUE, the source code for functions (newly defined or loaded) is stored in- ternally allowing comments to be kept in the right places. Retrieve the source by printing or using deparse(fn, control = "useSource"). The default is interactive(), i.e., TRUE for interactive use. keep.source.pkgs: As for keep.source, used only when packages are installed. Defaults to FALSE unless the environment variable R_KEEP_PKG_SOURCE is set to yes. max.print: integer, defaulting to 99999. print or show methods can make use of this option, to limit the amount of information that is printed, to something in the order of (and typically slightly less than) max.print entries. OutDec: character string containing a single-byte character. The character to be used as the decimal point in output conversions, that is in printing, plotting and as.character but not deparsing. pager: the command used for displaying text files by file.show. Defaults to ‘R_HOME/bin/pager’, which selects a pager via the \link{PAGER} environment variable (and that usually defaults to less). Can be a character string or an R function, in which case it needs to accept the arguments (files, header, title, delete.file) corresponding to the first four arguments of file.show. papersize: the default paper format used by postscript; set by environment variable R_PAPERSIZE when R is started: if that is unset or invalid it defaults to a value derived from the locale category LC_PAPER, or if that is unavailable to a default set when R was built. pdfviewer: default PDF viewer. The default is set from the environment variable R_PDFVIEWER, the default value of which is set when R is configured. printcmd: the command used by postscript for printing; set by environment variable R_PRINTCMD when R is started. This should be a command that expects either input to be piped to ‘stdin’ or to be given a single filename argument. Usually set to "lpr" on a Unix- alike. prompt: a non-empty string to be used for R’s prompt; should usually end in a blank (""). rl_word_breaks: Used for the readline-based terminal interface. Default value " \t\n\"\\’‘><=%;,|&\{()\}". This is the set of characters use to break the input line up into tokens for object- and file-name completion. Those who do not use spaces around operators may prefer " \t\n\"\\’‘><=+-*%;,|&\{()\}" which was the default in R 2.5.0. (The default in pre-2.5.0 versions of R was " \t\n\"\\’‘@$><=;|&\{(".) save.defaults, save.image.defaults: see save. scipen: integer. A penalty to be applied when deciding to print numeric values in fixed or expo- nential notation. Positive values bias towards fixed and negative towards scientific notation: fixed notation will be preferred unless it is more than scipen digits wider. showWarnCalls, showErrorCalls: a logical. Should warning and error messages show a sum- mary of the call stack? By default error calls are shown in non-interactive sessions. showNCalls: a integer. Controls how long the sequence of calls must be (in bytes) before ellipses are used. Defaults to 40 and should be at least 30 and no more than 500. 354 options show.error.messages: a logical. Should error messages be printed? Intended for use with try or a user-installed error handler. stringsAsFactors: The default setting for arguments of data.frame and read.table. texi2dvi: used by functions texi2dvi and texi2pdf in package tools. Set at startup from the environment variable R_TEXI2DVICMD. timeout: integer. The timeout for some Internet operations, in seconds. Default 60 seconds. See download.file and connections. topLevelEnvironment: see topenv and sys.source. useFancyQuotes: controls the use of directional quotes in sQuote, dQuote and in rendering text help (see Rd2txt in package tools). Can be TRUE, FALSE,"TeX" or "UTF-8". verbose: logical. Should R report extra information on progress? Set to TRUE by the command- line option ‘--verbose’. warn: sets the handling of warning messages. If warn is negative all warnings are ignored. If warn is zero (the default) warnings are stored until the top–level function returns. If fewer than 10 warnings were signalled they will be printed otherwise a message saying how many (max 50) were signalled. An object called last.warning is created and can be printed through the function warnings. If warn is one, warnings are printed as they occur. If warn is two or larger all warnings are turned into errors. warnPartialMatchArgs: logical. If true, warns if partial matching is used in argument matching. warnPartialMatchAttr: logical. If true, warns if partial matching is used in extracting attributes via attr. warnPartialMatchDollar: logical. If true, warns if partial matching is used for extraction by $. warning.expression: an R code expression to be called if a warning is generated, replacing the standard message. If non-null it is called irrespective of the value of option warn. warning.length: sets the truncation limit for error and warning messages. A non-negative integer, with allowed values 100. . . 8170, default 1000. width: controls the maximum number of columns on a line used in printing vectors, matrices and arrays, and when filling by cat. Columns are normally the same as characters except in CJK languages. You may want to change this if you re-size the window that R is running in. Valid values are 10. . . 10000 with default normally 80. (The limits on valid values are in file ‘Print.h’ and can be changed by re-compiling R.) Some R consoles automatically change the value when they are resized. See the examples on Startup for one way to set this automatically from the terminal width when R is started. The ‘factory-fresh’ default settings of some of these options are add.smooth TRUE check.bounds FALSE continue "+ " digits 7 echo TRUE encoding "native.enc" error NULL options 355 expressions 5000 keep.source interactive() keep.source.pkgs FALSE max.print 99999 OutDec "." prompt "> " scipen 0 show.error.messages TRUE timeout 60 verbose FALSE warn 0 warning.length 1000 width 80 Others are set from environment variables or are platform-dependent. Options set in package grDevices These will be set when package grDevices (or its namespace) is loaded if not already set. bitmapType:(Unix-only) character. The default type for the bitmap devices such as png. Defaults to "cairo" on systems where that is available, or to "quartz" on Mac OS X where that is available. device: a character string giving the name of a function, or the function object itself, which when called creates a new graphics device of the default type for that session. The value of this option defaults to the normal screen device (e.g., X11, windows or quartz) for an interactive session, and pdf in batch use or if a screen is not available. If set to the name of a device, the device is looked for first from the global environment (that is down the usual search path) and then in the grDevices namespace. The default values in interactive and non-interactive sessions are configurable via environment variables R_INTERACTIVE_DEVICE and R_DEFAULT_DEVICE respectively. device.ask.default: logical. The default for devAskNewPage("ask") when a device is opened. locatorBell: logical. Should selection in locator and identify be confirmed by a bell? Default TRUE. Honoured at least on X11 and windows devices. Other options used by package graphics max.contour.segments: positive integer, defaulting to 25000 if not set. A limit on the number of segments in a single contour line in contour or contourLines. Options set in package stats These will be set when package stats (or its namespace) is loaded if not already set. contrasts: the default contrasts used in model fitting such as with aov or lm. A character vector of length two, the first giving the function to be used with unordered factors and the second the function to be used with ordered factors. By default the elements are named c("unordered", "ordered"), but the names are unused. 356 options na.action: the name of a function for treating missing values (NA’s) for certain situations. show.coef.Pvalues: logical, affecting whether P values are printed in summary tables of coeffi- cients. See printCoefmat. show.nls.convergence: logical, should nls convergence messages be printed for successful fits? show.signif.stars: logical, should stars be printed on summary tables of coefficients? See printCoefmat. ts.eps: the relative tolerance for certain time series (ts) computations. Default 1e-05. ts.S.compat: logical. Used to select S compatibility for plotting time-series spectra. See the description of argument log in plot.spec. Options set in package utils These will be set when package utils (or its namespace) is loaded if not already set. BioC_mirror: The URL of a Bioconductor mirror for use by setRepositories, e.g. the default ‘"http://www.bioconductor.org"’ or the European mir- ror ‘"http://bioconductor.statistik.tu-dortmund.de"’. Can be set by chooseBioCmirror. browser: default HTML browser used by help.start() and browseURL on UNIX, or a non- default browser on Windows. Alternatively, an R function that is called with a URL as its argument. ccaddress: default Cc: address used by create.post (and hencebug.report and help.request). Can be FALSE or "". de.cellwidth: integer: the cell widths (number of characters) to be used in the data editor dataentry. If this is unset (the default), 0, negative or NA, variable cell widths are used. demo.ask: default for the ask argument of demo. editor: a non-empty string, or a function that is called with a file path as argument. Sets the default text editor, e.g., for edit. Set from the environment variable EDITOR on UNIX, or if unset VISUAL or vi. example.ask: default for the ask argument of example. help.ports: optional integer vector for setting ports of the internal HTTP server, see startDynamicHelp. help.search.types: default types of documentation to be searched by help.search and ??. help.try.all.packages: default for an argument of help. help_type: default for an argument of help, used also as the help type by ?. HTTPUserAgent: string used as the user agent in HTTP requests. If NULL, HTTP requests will be made without a user agent header. The default is R ( ) install.lock: logical: should per-directory package locking be used by install.packages? Most useful for binary installs on Mac OS X and Windows, but can be used in a startup file for source installs via R CMD INSTALL. For binary installs, can also be the character string "pkgloack". internet.info: The minimum level of information to be printed on URL downloads etc. Default is 2, for failure causes. Set to 1 or 0 to get more information. options 357 mailer: default emailing method used by create.post and hence bug.report and help.request. menu.graphics: Logical: should graphical menus be used if available?. Defaults to TRUE. Cur- rently applies to select.list, chooseCRANmirror, setRepositories and to select from multiple (text) help files in help. pkgType: The default type of packages to be downloaded and installed – see install.packages. Possible values are "source" (the default except under the CRAN Mac OS X build) and "mac.binary.leopard". Windows uses "win.binary".("mac.binary" and "mac.binary.universal" are no longer in use.) repos: URLs of the repositories for use by update.packages. Defaults to c(CRAN="@CRAN@"), a value that causes some utilities to prompt for a CRAN mirror. To avoid this do set the CRAN mirror, by something like local({r <- getOption("repos"); r["CRAN"] <- "http://my.local.cran"; options(repos=r)}). Note that you can add more repositories (Bioconductor and Omegahat, notably) using setRepositories(). SweaveHooks, SweaveSyntax: see Sweave. unzip: a character string, the path of the command used for unzipping help files, or "internal". Defaults to the value of R_UNZIPCMD, which is set in ‘etc/Renviron’ if an unzip command was found during configuration. Options set in package parallel These will be set when package parallel (or its namespace) is loaded if not already set. mc.cores: a integer giving the maximum allowed number of additional R processes allowed to be run in parallel to the current R process. Defaults to the setting of the environment variable MC_CORES if set. Most applications which use this assume a limit of 2 if it is unset. Options used on Unix only dvipscmd: character string giving a command to be used in the (deprecated) off-line printing of help pages via PostScript. Defaults to "dvips". Options used on Windows only warn.FPU: logical, by default undefined. If true, a warning is produced whenever dyn.load repairs the control word damaged by a buggy DLL. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Examples op <- options(); utils::str(op) # op() may contain functions. getOption("width") == options()$width # the latter needs more memory options(digits = 15) 358 options pi # set the editor, and save previous value old.o <- options(editor = "nedit") old.o options(check.bounds = TRUE, warn = 1) x <- NULL; x[4] <- "yes" # gives a warning options(digits=5) print(1e5) options(scipen=3); print(1e5) options(op) # reset (all) initial options options("digits") ## Not run: ## set contrast handling to be like S options(contrasts = c("contr.helmert", "contr.poly")) ## End(Not run) ## Not run: ## on error, terminate the R session with error status 66 options(error = quote(q("no", status=66, runLast=FALSE))) stop("test it") ## End(Not run) ## Not run: ## Set error actions for debugging: ## enter browser on error, see ?recover: options(error = recover) ## allows to call debugger() afterwards, see ?debugger: options(error = dump.frames) ## A possible setting for non-interactive sessions options(error = quote({dump.frames(to.file=TRUE); q()})) ## End(Not run) # Compare the two ways to get an option and use it # acconting for the possibility it might not be set. if(as.logical(getOption("performCleanp", TRUE))) cat("do cleanup\n") ## Not run: # a clumsier way of expressing the above w/o the default. tmp <- getOption("performCleanup") if(is.null(tmp)) tmp <- TRUE if(tmp) cat("do cleanup\n") ## End(Not run) order 359 order Ordering Permutation Description order returns a permutation which rearranges its first argument into ascending or descending order, breaking ties by further arguments. sort.list is the same, using only one argument. See the examples for how to use these functions to sort data frames, etc. Usage order(..., na.last = TRUE, decreasing = FALSE) sort.list(x, partial = NULL, na.last = TRUE, decreasing = FALSE, method = c("shell", "quick", "radix")) Arguments ... a sequence of numeric, complex, character or logical vectors, all of the same length, or a classed R object. x an atomic vector. partial vector of indices for partial sorting. (Non-NULL values are not implemented.) decreasing logical. Should the sort order be increasing or decreasing? na.last for controlling the treatment of NAs. If TRUE, missing values in the data are put last; if FALSE, they are put first; if NA, they are removed. method the method to be used: partial matches are allowed. Details In the case of ties in the first vector, values in the second are used to break the ties. If the values are still tied, values in the later arguments are used to break the tie (see the first example). The sort used is stable (except for method = "quick"), so any unresolved ties will be left in their original ordering. Complex values are sorted first by the real part, then the imaginary part. The sort order for character vectors will depend on the collating sequence of the locale in use: see Comparison. The default method for sort.list is a good compromise. Method "quick" is only supported for numeric x with na.last=NA, and is not stable, but will be faster for long vectors. Method "radix" is only implemented for integer x with a range of less than 100,000. For such x it is very fast (and stable), and hence is ideal for sorting factors. partial = NULL is supported for compatibility with other implementations of S, but no other values are accepted and ordering is always complete. For a classed R object, the sort order is taken from xtfrm: as its help page notes, this can be slow unless a suitable method has been defined or is.numeric(x) is true. For factors, this sorts on the internal codes, which is particularly appropriate for ordered factors. 360 order Note sort.list can get called by mistake as a method for sort with a list argument, and gives a suitable error message for list x. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also sort, rank, xtfrm. Examples require(stats) (ii <- order(x <- c(1,1,3:1,1:4,3), y <- c(9,9:1), z <-c(2,1:9))) ## 6 5 2 1 7 4 10 8 3 9 rbind(x,y,z)[,ii] # shows the reordering (ties via 2nd & 3rd arg) ## Suppose we wanted descending order on y. ## A simple solution for numeric ’y’ is rbind(x,y,z)[, order(x, -y, z)] ## More generally we can make use of xtfrm cy <- as.character(y) rbind(x,y,z)[, order(x, -xtfrm(cy), z)] ## Sorting data frames: dd <- transform(data.frame(x,y,z), z = factor(z, labels=LETTERS[9:1])) ## Either as above {for factor ’z’ : using internal coding}: dd[ order(x, -y, z) ,] ## or along 1st column, ties along 2nd, ... *arbitrary* no.{columns}: dd[ do.call(order, dd) ,] set.seed(1)# reproducible example: d4 <- data.frame(x = round( rnorm(100)), y = round(10*runif(100)), z = round( 8*rnorm(100)), u = round(50*runif(100))) (d4s <- d4[ do.call(order, d4) ,]) (i <- which(diff(d4s[,3]) == 0)) # in 2 places, needed 3 cols to break ties: d4s[ rbind(i,i+1), ] ## rearrange matched vectors so that the first is in ascending order x <- c(5:1, 6:8, 12:9) y <- (x - 5)^2 o <- order(x) rbind(x[o], y[o]) ## tests of na.last a <- c(4, 3, 2, NA, 1) outer 361 b <- c(4, NA, 2, 7, 1) z <- cbind(a, b) (o <- order(a, b)); z[o, ] (o <- order(a, b, na.last = FALSE)); z[o, ] (o <- order(a, b, na.last = NA)); z[o, ] ## Not run: ## speed examples for long vectors: x <- factor(sample(letters, 1e6, replace=TRUE)) system.time(o <- sort.list(x)) ## 0.4 secs stopifnot(!is.unsorted(x[o])) system.time(o <- sort.list(x, method="quick", na.last=NA)) # 0.1 sec stopifnot(!is.unsorted(x[o])) system.time(o <- sort.list(x, method="radix")) # 0.01 sec stopifnot(!is.unsorted(x[o])) xx <- sample(1:26, 1e7, replace=TRUE) system.time(o <- sort.list(xx, method="radix")) # 0.1 sec xx <- sample(1:100000, 1e7, replace=TRUE) system.time(o <- sort.list(xx, method="radix")) # 0.5 sec system.time(o <- sort.list(xx, method="quick", na.last=NA)) # 1.3 sec ## End(Not run) outer Outer Product of Arrays Description The outer product of the arrays X and Y is the array A with dimension c(dim(X), dim(Y)) where element A[c(arrayindex.x, arrayindex.y)] = FUN(X[arrayindex.x], Y[arrayindex.y], ...). Usage outer(X, Y, FUN="*", ...) X %o% Y Arguments X, Y First and second arguments for function FUN. Typically a vector or array. FUN a function to use on the outer products, found via match.fun (except for the special case "*"). ... optional arguments to be passed to FUN. 362 Paren Details X and Y must be suitable arguments for FUN. Each will be extended by rep to length the products of the lengths of X and Y before FUN is called. FUN is called with these two extended vectors as arguments. Therefore, it must be a vectorized function (or the name of one), expecting at least two arguments. Where they exist, the [dim]names of X and Y will be copied to the answer, and a dimension assigned which is the concatenation of the dimensions of X and Y(or lengths if dimensions do not exist). FUN = "*" is handled internally as a special case, via as.vector(X) %*% t(as.vector(Y)), and is intended only for numeric vectors and arrays. %o% is binary operator providing a wrapper for outer(x, y, "*"). Author(s) Jonathan Rougier References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also %*% for usual (inner) matrix vector multiplication; kronecker which is based on outer; Vectorize for vectorizing a non-vectorized function. Examples x <- 1:9; names(x) <- x # Multiplication & Power Tables x %o% x y <- 2:8; names(y) <- paste(y,":",sep="") outer(y, x, "^") outer(month.abb, 1999:2003, FUN = "paste") ## three way multiplication table: x %o% x %o% y[1:3] Paren Parentheses and Braces Description Open parenthesis, (, and open brace, {, are .Primitive functions in R. Effectively, ( is semantically equivalent to the identity function(x) x, whereas { is slightly more interesting, see examples. parse 363 Usage ( ... ) { ... } Value For (, the result of evaluating the argument. This has visibility set, so will auto-print if used at top-level. For {, the result of the last expression evaluated. This has the visibility of the last evaluation. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also if, return, etc for other objects used in the R language itself. Syntax for operator precedence. Examples f <- get("(") e <- expression(3 + 2 * 4) identical(f(e), e) do <- get("{") do(x <- 3, y <- 2*x-3, 6-x-y); x; y ## note the differences (2+3) {2+3; 4+5} (invisible(2+3)) {invisible(2+3)} parse Parse Expressions Description parse returns the parsed but unevaluated expressions in a list. Usage parse(file = "", n = NULL, text = NULL, prompt = "?", srcfile, encoding = "unknown") 364 parse Arguments file a connection, or a character string giving the name of a file or a URL to read the expressions from. If file is "" and text is missing or NULL then input is taken from the console. n integer (or coerced to integer). The maximum number of expressions to parse. If n is NULL or negative or NA the input is parsed in its entirety. text character vector. The text to parse. Elements are treated as if they were lines of a file. Other R objects will be coerced to character if possible. prompt the prompt to print when parsing from the keyboard. NULL means to use R’s prompt, getOption("prompt"). srcfile NULL, or a srcfile object. See the ‘Details’ section. encoding encoding to be assumed for input strings. If the value is "latin1" or "UTF-8" it is used to mark character strings as known to be in Latin-1 or UTF-8: it is not used to re-encode the input. To do the latter, specify the encoding as part of the connection con or via options(encoding=): see the example under file. Details If text has length greater than zero (after coercion) it is used in preference to file. All versions of R accept input from a connection with end of line marked by LF (as used on Unix), CRLF (as used on DOS/Windows) or CR (as used on classic Mac OS). The final line can be incom- plete, that is missing the final EOL marker. See source for the limits on the size of functions that can be parsed (by default). When input is taken from the console, n = NULL is equivalent to n = 1, and n < 0 will read until an EOF character is read. (The EOF character is Ctrl-Z for the Windows front-ends.) The line-length limit is 4095 bytes when reading from the console (which may impose a lower limit: see ‘An Introduction to R’). The default for srcfile is set as follows. If options("keep.source") is FALSE, srcfile defaults to NULL. Otherwise, if text is used, srcfile will be set to a srcfilecopy containing the text. If a character string is used for file, a srcfile object referring to that file will be used. Value An object of type "expression", with up to n elements if specified as a non-negative integer. When srcfile is non-NULL, a "srcref" attribute will be attached to the result containing a list of srcref records corresponding to each element, a "srcfile" attribute will be attached containing a copy of srcfile, and a "wholeSrcref" attribute will be attached containing a srcref record corresponding to all of the parsed text. A syntax error (including an incomplete expression) will throw an error. Character strings in the result will have a declared encoding if encoding is "latin1" or "UTF-8", or if text is supplied with every element of known encoding in a Latin-1 or UTF-8 locale. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. paste 365 See Also scan, source, eval, deparse. Examples cat("x <- c(1,4)\n x ^ 3 -10 ; outer(1:7,5:9)\n", file="xyz.Rdmped") # parse 3 statements from the file "xyz.Rdmped" parse(file = "xyz.Rdmped", n = 3) unlink("xyz.Rdmped") paste Concatenate Strings Description Concatenate vectors after converting to character. Usage paste(..., sep = " ", collapse = NULL) Arguments ... one or more R objects, to be converted to character vectors. sep a character string to separate the terms. Not NA_character_. collapse an optional character string to separate the results. Not NA_character_. Details paste converts its arguments (via as.character) to character strings, and concatenates them (sep- arating them by the string given by sep). If the arguments are vectors, they are concatenated term- by-term to give a character vector result. Vector arguments are recycled as needed, with zero-length arguments being recycled to "". Note that paste() coerces NA_character_, the character missing value, to "NA" which may seem undesirable, e.g., when pasting two character vectors, or very desirable, e.g. in paste("the value of p is ", p). If a value is specified for collapse, the values in the result are then concatenated into a single string, with the elements being separated by the value of collapse. 366 path.expand Value A character vector of the concatenated values. This will be of length zero if all the objects are, unless collapse is non-NULL in which case it is a single empty string. If any input into an element of the result is in UTF-8 (and none are declared with encoding "bytes"), that element will be in UTF-8, otherwise in the current encoding in which case the encoding of the element is declared if the current locale is either Latin-1 or UTF-8, at least one of the corresponding inputs (including separators) had a declared encoding and all inputs were either ASCII or declared. If an input into an element is declared with encoding "bytes", no translation will be done of any of the elements and the resulting element will have encoding "bytes". If collapse is non-NULL, this applies also to the second, collapsing, phase, but some translation may have been done in pasting object together in the first phase. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also String manipulation with as.character, substr, nchar, strsplit; further, cat which concate- nates and writes to a file, and sprintf for C like string construction. ‘plotmath’ for the use of paste in plot annotation. Examples paste(1:12) # same as as.character(1:12) paste("A", 1:6, sep = "") paste("Today is", date()) path.expand Expand File Paths Description Expand a path name, for example by replacing a leading tilde by the user’s home directory (if defined on that platform). Usage path.expand(path) Arguments path character vector containing one or more path names. pmatch 367 Details On some Unix builds of R, a leading ~user will expand to the home directory of user, but not on Unix versions without readline installed, nor if R is invoked with ‘--no-readline’. In an interactive session capabilities("cledit") will report if readline is available. See Also basename, normalizePath. Examples path.expand("~/foo") pmatch Partial String Matching Description pmatch seeks matches for the elements of its first argument among those of its second. Usage pmatch(x, table, nomatch = NA_integer_, duplicates.ok = FALSE) Arguments x the values to be matched: converted to a character vector by as.character. table the values to be matched against: converted to a character vector. nomatch the value to be returned at non-matching or multiply partially matching posi- tions. Note that it is coerced to integer. duplicates.ok should elements be in table be used more than once? Details The behaviour differs by the value of duplicates.ok. Consider first the case if this is true. First exact matches are considered, and the positions of the first exact matches are recorded. Then unique partial matches are considered, and if found recorded. (A partial match occurs if the whole of the element of x matches the beginning of the element of table.) Finally, all remaining elements of x are regarded as unmatched. In addition, an empty string can match nothing, not even an exact match to an empty string. This is the appropriate behaviour for partial matching of character indices, for example. If duplicates.ok is FALSE, values of table once matched are excluded from the search for subse- quent matches. This behaviour is equivalent to the R algorithm for argument matching, except for the consideration of empty strings (which in argument matching are matched after exact and partial matching to any remaining arguments). 368 polyroot charmatch is similar to pmatch with duplicates.ok true, the differences being that it differentiates between no match and an ambiguous partial match, it does match empty strings, and it does not allow multiple exact matches. NA values are treated as if they were the string constant "NA". Value An integer vector (possibly including NA if nomatch = NA) of the same length as x, giving the indices of the elements in table which matched, or nomatch. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also match, charmatch and match.arg, match.fun, match.call, for function argument matching etc., grep etc for more general (regexp) matching of strings. Examples pmatch("", "") # returns NA pmatch("m", c("mean", "median", "mode")) # returns NA pmatch("med", c("mean", "median", "mode")) # returns 2 pmatch(c("", "ab", "ab"), c("abc", "ab"), dup=FALSE) pmatch(c("", "ab", "ab"), c("abc", "ab"), dup=TRUE) ## compare charmatch(c("", "ab", "ab"), c("abc", "ab")) polyroot Find Zeros of a Real or Complex Polynomial Description Find zeros of a real or complex polynomial. Usage polyroot(z) Arguments z the vector of polynomial coefficients in increasing order. pos.to.env 369 Details A polynomial of degree n − 1, p(x) = z1 + z2x + ··· + znxn−1 is given by its coefficient vector z[1:n]. polyroot returns the n − 1 complex zeros of p(x) using the Jenkins-Traub algorithm. If the coefficient vector z has zeroes for the highest powers, these are discarded. There is no maximum degree, but numerical stability may be an issue for all but low-degree poly- nomials. Value A complex vector of length n − 1, where n is the position of the largest non-zero element of z. References Jenkins and Traub (1972) TOMS Algorithm 419. Comm. ACM, 15, 97–99. See Also uniroot for numerical root finding of arbitrary functions; complex and the zero example in the demos directory. Examples polyroot(c(1, 2, 1)) round(polyroot(choose(8, 0:8)), 11) # guess what! for (n1 in 1:4) print(polyroot(1:n1), digits = 4) polyroot(c(1, 2, 1, 0, 0)) # same as the first pos.to.env Convert Positions in the Search Path to Environments Description Returns the environment at a specified position in the search path. Usage pos.to.env(x) Arguments x an integer between 1 and length(search()), the length of the search path. 370 pretty Details Several R functions for manipulating objects in environments (such as get and ls) allow specifying environments via corresponding positions in the search path. pos.to.env is a convenience function for programmers which converts these positions to corresponding environments; users will typically have no need for it. It is primitive. Examples pos.to.env(1) # R_GlobalEnv # the next returns the base environment pos.to.env(length(search())) pretty Pretty Breakpoints Description Compute a sequence of about n+1 equally spaced ‘round’ values which cover the range of the values in x. The values are chosen so that they are 1, 2 or 5 times a power of 10. Usage pretty(x, ...) ## Default S3 method: pretty(x, n = 5, min.n = n %/% 3, shrink.sml = 0.75, high.u.bias = 1.5, u5.bias = .5 + 1.5*high.u.bias, eps.correct = 0, ...) Arguments x an object coercible to numeric by as.numeric. n integer giving the desired number of intervals. Non-integer values are rounded down. min.n nonnegative integer giving the minimal number of intervals. If min.n == 0, pretty(.) may return a single value. shrink.sml positive numeric by a which a default scale is shrunk in the case when range(x) is very small (usually 0). high.u.bias non-negative numeric, typically > 1. The interval unit is determined as {1,2,5,10} times b, a power of 10. Larger high.u.bias values favor larger units. u5.bias non-negative numeric multiplier favoring factor 5 over 2. Default and ‘optimal’: u5.bias = .5 + 1.5*high.u.bias. eps.correct integer code, one of {0,1,2}. If non-0, an epsilon correction is made at the boundaries such that the result boundaries will be outside range(x); in the small case, the correction is only done if eps.correct >=2. ... further arguments for methods. pretty 371 Details pretty ignores non-finite values in x. Let d <- max(x) - min(x) ≥ 0. If d is not (very close) to 0, we let c <- d/n, otherwise more or less c <- max(abs(range(x)))*shrink.sml / min.n. Then, the 10 base b is 10blog10(c)c such that b ≤ c < 10b. Now determine the basic unit u as one of {1, 2, 5, 10}b, depending on c/b ∈ [1, 10) and the two ‘bias’ coefficients, h =high.u.bias and f =u5.bias. ......... References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also axTicks for the computation of pretty axis tick locations in plots, particularly on the log scale. Examples pretty(1:15) # 0 2 4 6 8 10 12 14 16 pretty(1:15, h=2)# 0 5 10 15 pretty(1:15, n=4)# 0 5 10 15 pretty(1:15 * 2) # 0 5 10 15 20 25 30 pretty(1:20) # 0 5 10 15 20 pretty(1:20, n=2) # 0 10 20 pretty(1:20, n=10)# 0 2 4 ... 20 for(k in 5:11) { cat("k=",k,": "); print(diff(range(pretty(100 + c(0, pi*10^-k)))))} ##-- more bizarre, when min(x) == max(x): pretty(pi) add.names <- function(v) { names(v) <- paste(v); v} utils::str(lapply(add.names(-10:20), pretty)) utils::str(lapply(add.names(0:20), pretty, min.n = 0)) sapply( add.names(0:20), pretty, min.n = 4) pretty(1.234e100) pretty(1001.1001) pretty(1001.1001, shrink = .2) for(k in -7:3) cat("shrink=", formatC(2^k, width=9),":", formatC(pretty(1001.1001, shrink.sml = 2^k), width=6),"\n") 372 print Primitive Look Up a Primitive Function Description .Primitive looks up by name a ‘primitive’ (internally implemented) function. Usage .Primitive(name) Arguments name name of the R function. Details The advantage of .Primitive over .Internal functions is the potential efficiency of argument passing, and that positional matching can be used where desirable, e.g. in switch. For more details, see the ‘R Internals Manual’. All primitive functions are in the base namespace. This function is almost never used: ‘name‘ or, more carefully, get(name, envir=baseenv()) work equally well and do not depend on knowing which functions are primitive (which does change as R evolves). See Also .Internal. Examples mysqrt <- .Primitive("sqrt") c .Internal # this one *must* be primitive! ‘if‘ # need backticks print Print Values Description print prints its argument and returns it invisibly (via invisible(x)). It is a generic function which means that new printing methods can be easily added for new classes. print 373 Usage print(x, ...) ## S3 method for class ’factor’ print(x, quote = FALSE, max.levels = NULL, width = getOption("width"), ...) ## S3 method for class ’table’ print(x, digits = getOption("digits"), quote = FALSE, na.print = "", zero.print = "0", justify = "none", ...) ## S3 method for class ’function’ print(x, useSource = TRUE, ...) Arguments x an object used to select a method. ... further arguments passed to or from other methods. quote logical, indicating whether or not strings should be printed with surrounding quotes. max.levels integer, indicating how many levels should be printed for a factor; if 0, no extra "Levels" line will be printed. The default, NULL, entails choosing max.levels such that the levels print on one line of width width. width only used when max.levels is NULL, see above. digits minimal number of significant digits, see print.default. na.print character string (or NULL) indicating NA values in printed output, see print.default. zero.print character specifying how zeros (0) should be printed; for sparse tables, using "." can produce stronger results. justify character indicating if strings should left- or right-justified or left alone, passed to format. useSource logical indicating if internally stored source should be used for printing when present, e.g., if options(keep.source=TRUE) has been in use. Details The default method, print.default has its own help page. Use methods("print") to get all the methods for the print generic. print.factor allows some customization and is used for printing ordered factors as well. print.table for printing tables allows other customization. See noquote as an example of a class whose main purpose is a specific print method. References Chambers, J. M. and Hastie, T. J. (1992) Statistical Models in S. Wadsworth & Brooks/Cole. 374 print.data.frame See Also The default method print.default, and help for the methods above; further options, noquote. For more customizable (but cumbersome) printing, see cat, format or also write. Examples require(stats) ts(1:20)#-- print is the "Default function" --> print.ts(.) is called for(i in 1:3) print(1:i) ## Printing of factors attenu$station ## 117 levels -> ’max.levels’ depending on width ## ordered factors: levels "l1 < l2 < .." esoph$agegp[1:12] esoph$alcgp[1:12] ## Printing of sparse (contingency) tables set.seed(521) t1 <- round(abs(rt(200, df=1.8))) t2 <- round(abs(rt(200, df=1.4))) table(t1,t2) # simple print(table(t1,t2), zero.print = ".")# nicer to read print.data.frame Printing Data Frames Description Print a data frame. Usage ## S3 method for class ’data.frame’ print(x, ..., digits = NULL, quote = FALSE, right = TRUE, row.names = TRUE) Arguments x object of class data.frame. ... optional arguments to print or plot methods. digits the minimum number of significant digits to be used: see print.default. quote logical, indicating whether or not entries should be printed with surrounding quotes. right logical, indicating whether or not strings should be right-aligned. The default is right-alignment. print.default 375 row.names logical (or character vector), indicating whether (or what) row names should be printed. Details This calls format which formats the data frame column-by-column, then converts to a character matrix and dispatches to the print method for matrices. When quote = TRUE only the entries are quoted not the row names nor the column names. See Also data.frame. Examples (dd <- data.frame(x=1:8, f=gl(2,4), ch=I(letters[1:8]))) # print() with defaults print(dd, quote = TRUE, row.names = FALSE) # suppresses row.names and quotes all entries print.default Default Printing Description print.default is the default method of the generic print function which prints its argument. Usage ## Default S3 method: print(x, digits = NULL, quote = TRUE, na.print = NULL, print.gap = NULL, right = FALSE, max = NULL, useSource = TRUE, ...) Arguments x the object to be printed. digits a non-null value for digits specifies the minimum number of significant digits to be printed in values. The default, NULL, uses getOption(digits). (For the interpretation for complex numbers see signif.) Non-integer values will be rounded down, and only values greater than or equal to 1 and no greater than 22 are accepted. quote logical, indicating whether or not strings (characters) should be printed with surrounding quotes. na.print a character string which is used to indicate NA values in printed output, or NULL (see ‘Details’). 376 print.default print.gap a non-negative integer ≤ 1024, or NULL (meaning 1), giving the spacing between adjacent columns in printed vectors, matrices and arrays. right logical, indicating whether or not strings should be right aligned. The default is left alignment. max a non-null value for max specifies the approximate maximum number of entries to be printed. The default, NULL, uses getOption(max.print); see that help page for more details. useSource logical, indicating whether to use source references or copies rather than depars- ing language objects. The default is to use the original source if it is available. ... further arguments to be passed to or from other methods. They are ignored in this function. Details The default for printing NAs is to print NA (without quotes) unless this is a character NA and quote = FALSE, when ‘’ is printed. The same number of decimal places is used throughout a vector. This means that digits specifies the minimum number of significant digits to be used, and that at least one entry will be encoded with that minimum number. However, if all the encoded elements then have trailing zeroes, the number of decimal places is reduced until at least one element has a non-zero final digit. Decimal points are only included if at least one decimal place is selected. Attributes are printed respecting their class(es), using the values of digits to print.default, but using the default values (for the methods called) of the other arguments. When the methods package is attached, print will call show for R objects with formal classes if called with no optional arguments. Large number of digits Note that for large values of digits, currently for digits >= 16, the calculation of the number of significant digits will depend on the platform’s internal (C library) implementation of ‘sprintf()’ functionality. Single-byte locales If a non-printable character is encountered during output, it is represented as one of the ANSI escape sequences (‘\a’, ‘\b’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’, ‘\\’ and ‘\0’: see Quotes), or failing that as a 3- digit octal code: for example the UK currency pound sign in the C locale (if implemented correctly) is printed as ‘\243’. Which characters are non-printable depends on the locale. (Because some versions of Windows get this wrong, all bytes with the upper bit set are regarded as printable on Windows in a single-byte locale.) Unicode and other multi-byte locales In all locales, the characters in the ASCII range (‘0x00’ to ‘0x7f’) are printed in the same way, as-is if printable, otherwise via ANSI escape sequences or 3-digit octal escapes as described for single-byte locales. prmatrix 377 Multi-byte non-printing characters are printed as an escape sequence of the form ‘\uxxxx’ or ‘\Uxxxxxxxx’ (in hexadecimal). This is the internal code for the wide-character representation of the character. If this is not known to be the Unicode point, a warning is issued. The only known exceptions are certain Japanese ISO2022 locales on commercial Unixes, which use a concatenation of the bytes: it is unlikely that R compiles on such a system. It is possible to have a character string in a character vector that is not valid in the current locale. If a byte is encountered that is not part of a valid character it is printed in hex in the form ‘\xab’ and this is repeated until the start of a valid character. (This will rapidly recover from minor errors in UTF-8.) See Also The generic print, options. The "noquote" class and print method. encodeString, which encodes a character vector the way it would be printed. Examples pi print(pi, digits = 16) LETTERS[1:16] print(LETTERS, quote = FALSE) M <- cbind(I = 1, matrix(1:10000, ncol = 10, dimnames = list(NULL, LETTERS[1:10]))) utils::head(M) # makes more sense than print(M, max = 1000)# prints 90 rows and a message about omitting 910 prmatrix Print Matrices, Old-style Description An earlier method for printing matrices, provided for S compatibility. Usage prmatrix(x, rowlab =, collab =, quote = TRUE, right = FALSE, na.print = NULL, ...) Arguments x numeric or character matrix. rowlab,collab (optional) character vectors giving row or column names respectively. By de- fault, these are taken from dimnames(x). quote logical; if TRUE and x is of mode "character", quotes (‘"’) are used. right if TRUE and x is of mode "character", the output columns are right-justified. na.print how NAs are printed. If this is non-null, its value is used to represent NA. ... arguments for print methods. 378 proc.time Details prmatrix is an earlier form of print.matrix, and is very similar to the S function of the same name. Value Invisibly returns its argument, x. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also print.default, and other print methods. Examples prmatrix(m6 <- diag(6), rowlab = rep("",6), collab =rep("",6)) chm <- matrix(scan(system.file("help", "AnIndex", package = "splines"), what = ""), , 2, byrow = TRUE) chm # uses print.matrix() prmatrix(chm, collab = paste("Column",1:3), right=TRUE, quote=FALSE) proc.time Running Time of R Description proc.time determines how much real and CPU time (in seconds) the currently running R process has already taken. Usage proc.time() Details proc.time returns five elements for backwards compatibility, but its print method prints a named vector of length 3. The first two entries are the total user and system CPU times of the current R process and any child processes on which it has waited, and the third entry is the ‘real’ elapsed time since the process was started. prod 379 Value An object of class "proc_time" which is a numeric vector of length 5, containing the user, system, and total elapsed times for the currently running R process, and the cumulative sum of user and system times of any child processes spawned by it on which it has waited. (The print method combines the child times with those of the main process.) The definition of ‘user’ and ‘system’ times is from your OS. Typically it is something like The ‘user time’ is the CPU time charged for the execution of user instructions of the calling process. The ‘system time’ is the CPU time charged for execution by the system on behalf of the calling process. Times of child processes are not available on Windows and will always be given as NA. The resolution of the times will be system-specific and on Unix-alikes times are rounded down to milliseconds. On modern systems they will be that accurate, but on older systems they might be accurate to 1/100 or 1/60 sec. They are typically available to 10ms on Windows. This is a primitive function. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also system.time for timing an R expression, gc.time for how much of the time was spent in garbage collection. Examples ## Not run: ## a way to time an R expression: system.time is preferred ptm <- proc.time() for (i in 1:50) mad(stats::runif(500)) proc.time() - ptm ## End(Not run) prod Product of Vector Elements Description prod returns the product of all the values present in its arguments. Usage prod(..., na.rm = FALSE) 380 prop.table Arguments ... numeric or complex or logical vectors. na.rm logical. Should missing values be removed? Details If na.rm is FALSE an NA value in any of the arguments will cause a value of NA to be returned, otherwise NA values are ignored. This is a generic function: methods can be defined for it directly or via the Summary group generic. For this to work properly, the arguments ... should be unnamed, and dispatch is on the first argument. Logical true values are regarded as one, false values as zero. For historical reasons, NULL is accepted and treated as if it were numeric(0). Value The product, a numeric (of type "double") or complex vector of length one. NB: the product of an empty set is one, by definition. S4 methods This is part of the S4 Summary group generic. Methods for it must use the signature x, ..., na.rm. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also sum, cumprod, cumsum. ‘plotmath’ for the use of prod in plot annotation. Examples print(prod(1:7)) == print(gamma(8)) prop.table Express Table Entries as Fraction of Marginal Table Description This is really sweep(x, margin, margin.table(x, margin), "/") for newbies, except that if margin has length zero, then one gets x/sum(x). pushBack 381 Usage prop.table(x, margin=NULL) Arguments x table margin index, or vector of indices to generate margin for Value Table like x expressed relative to margin Author(s) Peter Dalgaard See Also margin.table Examples m <- matrix(1:4,2) m prop.table(m,1) pushBack Push Text Back on to a Connection Description Functions to push back text lines onto a connection, and to enquire how many lines are currently pushed back. Usage pushBack(data, connection, newLine = TRUE) pushBackLength(connection) Arguments data a character vector. connection A connection. newLine logical. If true, a newline is appended to each string pushed back. 382 qr Details Several character strings can be pushed back on one or more occasions. The occasions form a stack, so the first line to be retrieved will be the first string from the last call to pushBack. Lines which are pushed back are read prior to the normal input from the connection, by the normal text-reading functions such as readLines and scan. Pushback is only allowed for readable connections in text mode. Not all uses of connections respect pushbacks, in particular the input connection is still wired di- rectly, so for example parsing commands from the console and scan("") ignore pushbacks on stdin. When character strings with a marked encoding (see Encoding) are pushed back they are converted to the current encoding. This may involve representing characters as ‘’ if they cannot be converted. Value pushBack returns nothing. pushBackLength returns number of lines currently pushed back. See Also connections, readLines. Examples zz <- textConnection(LETTERS) readLines(zz, 2) pushBack(c("aa", "bb"), zz) pushBackLength(zz) readLines(zz, 1) pushBackLength(zz) readLines(zz, 1) readLines(zz, 1) close(zz) qr The QR Decomposition of a Matrix Description qr computes the QR decomposition of a matrix. It provides an interface to the techniques used in the LINPACK routine DQRDC or the LAPACK routines DGEQP3 and (for complex matrices) ZGEQP3. qr 383 Usage qr(x, ...) ## Default S3 method: qr(x, tol = 1e-07 , LAPACK = FALSE, ...) qr.coef(qr, y) qr.qy(qr, y) qr.qty(qr, y) qr.resid(qr, y) qr.fitted(qr, y, k = qr$rank) qr.solve(a, b, tol = 1e-7) ## S3 method for class ’qr’ solve(a, b, ...) is.qr(x) as.qr(x) Arguments x a matrix whose QR decomposition is to be computed. tol the tolerance for detecting linear dependencies in the columns of x. Only used if LAPACK is false and x is real. qr a QR decomposition of the type computed by qr. y, b a vector or matrix of right-hand sides of equations. a a QR decomposition or (qr.solve only) a rectangular matrix. k effective rank. LAPACK logical. For real x, if true use LAPACK otherwise use LINPACK. ... further arguments passed to or from other methods Details The QR decomposition plays an important role in many statistical techniques. In particular it can be used to solve the equation Ax = b for given matrix A, and vector b. It is useful for computing regression coefficients and in applying the Newton-Raphson algorithm. The functions qr.coef, qr.resid, and qr.fitted return the coefficients, residuals and fitted val- ues obtained when fitting y to the matrix with QR decomposition qr. (If pivoting is used, some of the coefficients will be NA.) qr.qy and qr.qty return Q %*% y and t(Q) %*% y, where Q is the (complete) Q matrix. All the above functions keep dimnames (and names) of x and y if there are. solve.qr is the method for solve for qr objects. qr.solve solves systems of equations via the QR decomposition: if a is a QR decomposition it is the same as solve.qr, but if a is a rectangular matrix the QR decomposition is computed first. Either will handle over- and under-determined systems, providing a least-squares fit if appropriate. is.qr returns TRUE if x is a list with components named qr, rank and qraux and FALSE otherwise. It is not possible to coerce objects to mode "qr". Objects either are QR decompositions or they are not. 384 qr Value The QR decomposition of the matrix as computed by LINPACK or LAPACK. The components in the returned value correspond directly to the values returned by DQRDC/DGEQP3/ZGEQP3. qr a matrix with the same dimensions as x. The upper triangle contains the R of the decomposition and the lower triangle contains information on the Q of the decomposition (stored in compact form). Note that the storage used by DQRDC and DGEQP3 differs. qraux a vector of length ncol(x) which contains additional information on Q. rank the rank of x as computed by the decomposition: always full rank in the LA- PACK case. pivot information on the pivoting strategy used during the decomposition. Non-complex QR objects computed by LAPACK have the attribute "useLAPACK" with value TRUE. Note To compute the determinant of a matrix (do you really need it?), the QR decomposition is much more efficient than using Eigen values (eigen). See det. Using LAPACK (including in the complex case) uses column pivoting and does not attempt to detect rank-deficient matrices. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications. Anderson. E. and ten others (1999) LAPACK Users’ Guide. Third Edition. SIAM. Available on-line at http://www.netlib.org/lapack/lug/lapack_lug.html. See Also qr.Q, qr.R, qr.X for reconstruction of the matrices. lm.fit, lsfit, eigen, svd. det (using qr) to compute the determinant of a matrix. Examples hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") } h9 <- hilbert(9); h9 qr(h9)$rank #--> only 7 qrh9 <- qr(h9, tol = 1e-10) qrh9$rank #--> 9 ##-- Solve linear equation system H %*% x = y : y <- 1:9/10 x <- qr.solve(h9, y, tol = 1e-10) # or equivalently : x <- qr.coef(qrh9, y) #-- is == but much better than #-- solve(h9) %*% y QR.Auxiliaries 385 h9 %*% x # = y ## overdetermined system A <- matrix(runif(12), 4) b <- 1:4 qr.solve(A, b) # or solve(qr(A), b) solve(qr(A, LAPACK=TRUE), b) # this is a least-squares solution, cf. lm(b ~ 0 + A) ## underdetermined system A <- matrix(runif(12), 3) b <- 1:3 qr.solve(A, b) solve(qr(A, LAPACK=TRUE), b) # solutions will have one zero, not necessarily the same one QR.Auxiliaries Reconstruct the Q, R, or X Matrices from a QR Object Description Returns the original matrix from which the object was constructed or the components of the decom- position. Usage qr.X(qr, complete = FALSE, ncol =) qr.Q(qr, complete = FALSE, Dvec =) qr.R(qr, complete = FALSE) Arguments qr object representing a QR decomposition. This will typically have come from a previous call to qr or lsfit. complete logical expression of length 1. Indicates whether an arbitrary orthogonal com- pletion of the Q or X matrices is to be made, or whether the R matrix is to be completed by binding zero-value rows beneath the square upper triangle. ncol integer in the range 1:nrow(qr$qr). The number of columns to be in the re- constructed X. The default when complete is FALSE is the first min(ncol(X), nrow(X)) columns of the original X from which the qr object was constructed. The default when complete is TRUE is a square matrix with the original X in the first ncol(X) columns and an arbitrary orthogonal completion (unitary com- pletion in the complex case) in the remaining columns. Dvec vector (not matrix) of diagonal values. Each column of the returned Q will be multiplied by the corresponding diagonal value. Defaults to all 1s. 386 quit Value qr.X returns X, the original matrix from which the qr object was constructed, provided ncol(X) <= nrow(X). If complete is TRUE or the argument ncol is greater than ncol(X), additional columns from an arbitrary orthogonal (unitary) completion of X are returned. qr.Q returns part or all of Q, the order-nrow(X) orthogonal (unitary) transformation represented by qr. If complete is TRUE,Q has nrow(X) columns. If complete is FALSE,Q has ncol(X) columns. When Dvec is specified, each column of Q is multiplied by the corresponding value in Dvec. qr.R returns R. The number of rows of R is either nrow(X) or ncol(X) (and may depend on whether complete is TRUE or FALSE. See Also qr, qr.qy. Examples p <- ncol(x <- LifeCycleSavings[,-1]) # not the ’sr’ qrstr <- qr(x) # dim(x) == c(n,p) qrstr $ rank # = 4 = p Q <- qr.Q(qrstr) # dim(Q) == dim(x) R <- qr.R(qrstr) # dim(R) == ncol(x) X <- qr.X(qrstr) # X == x range(X - as.matrix(x))# ~ < 6e-12 ## X == Q %*% R if there has been no pivoting, as here. Q %*% R quit Terminate an R Session Description The function quit or its alias q terminate the current R session. Usage quit(save = "default", status = 0, runLast = TRUE) q(save = "default", status = 0, runLast = TRUE) Arguments save a character string indicating whether the environment (workspace) should be saved, one of "no","yes","ask" or "default". status the (numerical) error status to be returned to the operating system, where rele- vant. Conventionally 0 indicates successful completion. runLast should .Last() be executed? quit 387 Details save must be one of "no","yes","ask" or "default". In the first case the workspace is not saved, in the second it is saved and in the third the user is prompted and can also decide not to quit. The default is to ask in interactive use but may be overridden by command-line arguments (which must be supplied in non-interactive use). Immediately before terminating, .Last() is executed if the function .Last exists and runLast is true. If in interactive use there are errors in the .Last function, control will be returned to the command prompt, so do test the function thoroughly. There is a system analogue, .Last.sys(), which is run after .Last() if runLast is true. Exactly what happens at termination of an R session depends on the platform and GUI interface in use. A typical sequence is to run .Last() and .Last.sys() (unless runLast is false), to save the workspace if requested (and in most cases also to save the session history: see savehistory), then run any finalizers (see reg.finalizer) that have been set to be run on exit, close all open graphics devices, remove the session temporary directory and print any remaining warnings (e.g. from .Last() and device closure). Some error statuses are used by R itself. The default error handler for non-interactive use effectively calls q("no", 1, FALSE) and returns error code 1. Error status 2 is used for R‘suicide’, that is a catastrophic failure, and other small numbers are used by specific ports for initialization failures. It is recommended that users choose statuses of 10 or more. Valid values of status are system-dependent, but 0:255 are normally valid. (Many OSes will report the last byte of the value, that is report the number modulo 256. But not all.) References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also .First for setting things on startup. Examples ## Not run: ## Unix-flavour example .Last <- function() { cat("Now sending PostScript graphics to the printer:\n") system("lpr Rplots.ps") cat("bye bye...\n") } quit("yes") ## End(Not run) 388 Quotes Quotes Quotes Description Descriptions of the various uses of quoting in R. Details Three types of quotes are part of the syntax of R: single and double quotation marks and the backtick (or back quote, ‘‘’). In addition, backslash is used to escape the following character inside character constants. Character constants Single and double quotes delimit character constants. They can be used interchangeably but double quotes are preferred (and character constants are printed using double quotes), so single quotes are normally only used to delimit character constants containing double quotes. Backslash is used to start an escape sequence inside character constants. Escaping a character not in the following table is an error. Single quotes need to be escaped by backslash in single-quoted strings, and double quotes in double- quoted strings. ‘\n’ newline ‘\r’ carriage return ‘\t’ tab ‘\b’ backspace ‘\a’ alert (bell) ‘\f’ form feed ‘\v’ vertical tab ‘\\’ backslash ‘\’ ‘\’’ ASCII apostrophe ‘’’ ‘\"’ ASCII quotation mark ‘"’ ‘\nnn’ character with given octal code (1, 2 or 3 digits) ‘\xnn’ character with given hex code (1 or 2 hex digits) ‘\unnnn’ Unicode character with given code (1–4 hex digits) ‘\Unnnnnnnn’ Unicode character with given code (1–8 hex digits) Alternative forms for the last two are ‘\u{nnnn}’ and ‘\U{nnnnnnnn}’. All except the Unicode escape sequences are also supported when reading character strings by scan and read.table if allowEscapes = TRUE. Unicode escapes can be used to enter Unicode characters not in the current locale’s charset (when the string will be stored internally in UTF-8). The parser does not allow the use of both octal/hex and Unicode escapes in a single string. These forms will also be used by print.default when outputting non-printable characters (in- cluding backslash). R.Version 389 Embedded nuls are not allowed in character strings, so using escapes (such as ‘\0’) for a nul will result in the string being truncated at that point (usually with a warning). Names and Identifiers Identifiers consist of a sequence of letters, digits, the period (.) and the underscore. They must not start with a digit nor underscore, nor with a period followed by a digit. Reserved words are not valid identifiers. The definition of a letter depends on the current locale, but only ASCII digits are considered to be digits. Such identifiers are also known as syntactic names and may be used directly in R code. Almost always, other names can be used provided they are quoted. The preferred quote is the backtick (‘‘’), and deparse will normally use it, but under many circumstances single or double quotes can be used (as a character constant will often be converted to a name). One place where backticks may be essential is to delimit variable names in formulae: see formula. See Also Syntax for other aspects of the syntax. sQuote for quoting English text. shQuote for quoting OS commands. The R Language Definition manual. R.Version Version Information Description R.Version() provides detailed information about the version of R running. R.version is a variable (a list) holding this information (and version is a copy of it for S com- patibility). Usage R.Version() R.version R.version.string version Value R.Version returns a list with character-string components platform the platform for which R was built. A triplet of the form CPU-VENDOR-OS, as determined by the configure script. E.g, "i586-unknown-linux" or "i386- pc-mingw32". 390 R.Version arch the architecture (CPU) R was built on/for. os the underlying operating system system CPU and OS, separated by a comma. status the status of the version (e.g., "Alpha") major the major version number minor the minor version number, including the patchlevel year the year the version was released month the month the version was released day the day the version was released svn rev the Subversion revision number, which should be either "unknown" or a single number. (A range of numbers or a number with ‘M’ or ‘S’ appended indicates inconsistencies in the sources used to build this version of R.) language always "R". version.string a character string concatenating some of the info above, useful for plotting, etc. R.version and version are lists of class "simple.list" which has a print method. Note Do not use R.version$os to test the platform the code is running on: use .Platform$OS.type instead. Slightly different versions of the OS may report different values of R.version$os, as may different versions of R. R.version.string is a copy of R.version$version.string for simplicity and backwards com- patibility. See Also sessionInfo which provides additional information; getRversion typically used inside R code, .Platform. Examples require(graphics) R.version$os # to check how lucky you are ... plot(0) # any plot mtext(R.version.string, side=1,line=4,adj=1)# a useful bottom-right note Random 391 Random Random Number Generation Description .Random.seed is an integer vector, containing the random number generator (RNG) state for ran- dom number generation in R. It can be saved and restored, but should not be altered by the user. RNGkind is a more friendly interface to query or set the kind of RNG in use. RNGversion can be used to set the random generators as they were in an earlier R version (for reproducibility). set.seed is the recommended way to specify seeds. Usage .Random.seed <- c(rng.kind, n1, n2, ...) RNGkind(kind = NULL, normal.kind = NULL) RNGversion(vstr) set.seed(seed, kind = NULL, normal.kind = NULL) Arguments kind character or NULL. If kind is a character string, set R’s RNG to the kind desired. Use "default" to return to the R default. See ‘Details’ for the interpretation of NULL. normal.kind character string or NULL. If it is a character string, set the method of Normal generation. Use "default" to return to the R default. NULL makes no change. seed a single value, interpreted as an integer. vstr a character string containing a version number, e.g., "1.6.2" rng.kind integer code in 0:k for the above kind. n1, n2, ... integers. See the details for how many are required (which depends on rng.kind). Details The currently available RNG kinds are given below. kind is partially matched to this list. The default is "Mersenne-Twister". "Wichmann-Hill" The seed, .Random.seed[-1] == r[1:3] is an integer vector of length 3, where each r[i] is in 1:(p[i] - 1), where p is the length 3 vector of primes, p = (30269, 30307, 30323). The Wichmann–Hill generator has a cycle length of 6.9536 × 1012 (= prod(p-1)/4, see Applied Statistics (1984) 33, 123 which corrects the original article). "Marsaglia-Multicarry":A multiply-with-carry RNG is used, as recommended by George Marsaglia in his post to the mailing list ‘sci.stat.math’. It has a period of more than 260 and has passed all tests (according to Marsaglia). The seed is two integers (all values allowed). 392 Random "Super-Duper": Marsaglia’s famous Super-Duper from the 70’s. This is the original version which does not pass the MTUPLE test of the Diehard battery. It has a period of ≈ 4.6 × 1018 for most initial seeds. The seed is two integers (all values allowed for the first seed: the second must be odd). We use the implementation by Reeds et al.\ (1982–84). The two seeds are the Tausworthe and congruence long integers, respectively. A one-to-one mapping to S’s .Random.seed[1:12] is possible but we will not publish one, not least as this generator is not exactly the same as that in recent versions of S-PLUS. "Mersenne-Twister": From Matsumoto and Nishimura (1998). A twisted GFSR with period 219937 − 1 and equidistribution in 623 consecutive dimensions (over the whole period). The ‘seed’ is a 624-dimensional set of 32-bit integers plus a current position in that set. "Knuth-TAOCP-2002": A 32-bit integer GFSR using lagged Fibonacci sequences with subtraction. That is, the recurrence used is Xj = (Xj−100 − Xj−37) mod 230 and the ‘seed’ is the set of the 100 last numbers (actually recorded as 101 numbers, the last being a cyclic shift of the buffer). The period is around 2129. "Knuth-TAOCP": An earlier version from Knuth (1997). The 2002 version was not backwards compatible with the earlier version: the initialization of the GFSR from the seed was altered. R did not allow you to choose consecutive seeds, the reported ‘weakness’, and already scrambled the seeds. Initialization of this generator is done in interpreted R code and so takes a short but noticeable time. "L’Ecuyer-CMRG": A ‘combined multiple-recursive generator’ from L’Ecuyer (1999), each ele- ment of which is a feedback multiplicative generator with three integer elements: thus the seed is a (signed) integer vector of length 6. The period is around 2191. The 6 elements of the seed are internally regarded as 32-bit unsigned integers. Neither the first three nor the last three should be all zero, and they are limited to less than 4294967087 and 4294944443 respectively. This is not particularly interesting of itself, but provides the basis for the multiple streams used in package parallel. "user-supplied": Use a user-supplied generator. See Random.user for details. normal.kind can be "Kinderman-Ramage","Buggy Kinderman-Ramage" (not for set.seed), "Ahrens-Dieter","Box-Muller","Inversion" (the default), or "user-supplied". (For inver- sion, see the reference in qnorm.) The Kinderman-Ramage generator used in versions prior to 1.7.1 (now called "Buggy") had several approximation errors and should only be used for reproduction of old results. The "Box-Muller" generator is stateful as pairs of normals are generated and returned sequentially. The state is reset whenever it is selected (even if it is the current normal generator) and when kind is changed. set.seed uses its single integer argument to set as many seeds as are required. It is intended as a simple way to get quite different seeds by specifying small integer arguments, and also as a way to get valid seed sets for the more complicated methods (especially "Mersenne-Twister" and "Knuth-TAOCP"). There is no guarantee that different values of seed will seed the RNG differently, although any exceptions would be extremely rare. Random 393 The use of kind=NULL or normal.kind=NULL in RNGkind or set.seed selects the currently-used generator (including that used in the previous session if the workspace has been restored): if no generator has been used it selects "default". Value .Random.seed is an integer vector whose first element codes the kind of RNG and normal gener- ator. The lowest two decimal digits are in 0:(k-1) where k is the number of available RNGs. The hundreds represent the type of normal generator (starting at 0). In the underlying C, .Random.seed[-1] is unsigned; therefore in R.Random.seed[-1] can be negative, due to the representation of an unsigned integer by a signed integer. RNGkind returns a two-element character vector of the RNG and normal kinds selected before the call, invisibly if either argument is not NULL. A type starts a session as the default, and is selected either by a call to RNGkind or by setting .Random.seed in the workspace. RNGversion returns the same information as RNGkind about the defaults in a specific R version. set.seed returns NULL, invisibly. Note Initially, there is no seed; a new one is created from the current time (and since R 2.14.0, the process ID) when one is required. Hence different sessions will give different simulation results, by default. However, the seed might be restored from a previous session if a previously saved workspace is restored. .Random.seed saves the seed set for the uniform random-number generator, at least for the system generators. It does not necessarily save the state of other generators, and in particular does not save the state of the Box–Muller normal generator. If you want to reproduce work later, call set.seed (preferably with explicit values for kind and normal.kind) rather than set .Random.seed. The object .Random.seed is only looked for in the user’s workspace. Do not rely on randomness of low-order bits from RNGs. Most of the supplied uniform generators return 32-bit integer values that are converted to doubles, so they take at most 232 distinct values and long runs will return duplicated values (Wichmann-Hill is the exception, and all give at least 30 varying bits.) Author(s) of RNGkind: Martin Maechler. Current implementation, B. D. Ripley References Ahrens, J. H. and Dieter, U. (1973) Extensions of Forsythe’s method for random sampling from the normal distribution. Mathematics of Computation 27, 927-937. Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (set.seed, storing in .Random.seed.) Box, G. E. P. and Muller, M. E. (1958) A note on the generation of normal random deviates. Annals of Mathematical Statistics 29, 610–611. 394 Random De Matteis, A. and Pagnutti, S. (1993) Long-range Correlation Analysis of the Wichmann-Hill Random Number Generator, Statist. Comput., 3, 67–70. Kinderman, A. J. and Ramage, J. G. (1976) Computer generation of normal random variables. Journal of the American Statistical Association 71, 893-896. Knuth, D. E. (1997) The Art of Computer Programming. Volume 2, third edition. Source code at http://www-cs-faculty.stanford.edu/~knuth/taocp.html. Knuth, D. E. (2002) The Art of Computer Programming. Volume 2, third edition, ninth printing. See http://Sunburn.Stanford.EDU/~knuth/news02.html. L’Ecuyer, P. (1999) Good parameters and implementations for combined multiple recursive random number generators. Operations Research 47, 159–164. Marsaglia, G. (1997) A random number generator for C. Discussion paper, posting on Usenet news- group sci.stat.math on September 29, 1997. Marsaglia, G. and Zaman, A. (1994) Some portable very-long-period random number generators. Computers in Physics, 8, 117–121. Matsumoto, M. and Nishimura, T. (1998) Mersenne Twister: A 623-dimensionally equidistributed uniform pseudo-random number generator, ACM Transactions on Modeling and Computer Simula- tion, 8, 3–30. Source code at http://www.math.keio.ac.jp/~matumoto/emt.html. Reeds, J., Hubert, S. and Abrahams, M. (1982–4) C implementation of SuperDuper, University of California at Berkeley. (Personal communication from Jim Reeds to Ross Ihaka.) Wichmann, B. A. and Hill, I. D. (1982) Algorithm AS 183: An Efficient and Portable Pseudo- random Number Generator, Applied Statistics, 31, 188–190; Remarks: 34, 198 and 35, 89. See Also sample for random sampling with and without replacement. Distributions for functions for random-variate generation from standard distributions. Examples require(stats) ## the default random seed is 626 integers, so only print a few runif(1); .Random.seed[1:6]; runif(1); .Random.seed[1:6] ## If there is no seed, a "random" new one is created: rm(.Random.seed); runif(1); .Random.seed[1:6] ok <- RNGkind() RNGkind("Wich")# (partial string matching on ’kind’) ## This shows how ’runif(.)’ works for Wichmann-Hill, ## using only R functions: p.WH <- c(30269, 30307, 30323) a.WH <- c( 171, 172, 170) next.WHseed <- function(i.seed = .Random.seed[-1]) { (a.WH * i.seed) %% p.WH } Random.user 395 my.runif1 <- function(i.seed = .Random.seed) { ns <- next.WHseed(i.seed[-1]); sum(ns / p.WH) %% 1 } rs <- .Random.seed (WHs <- next.WHseed(rs[-1])) u <- runif(1) stopifnot( next.WHseed(rs[-1]) == .Random.seed[-1], all.equal(u, my.runif1(rs)) ) ## ---- .Random.seed RNGkind("Super")#matches "Super-Duper" RNGkind() .Random.seed # new, corresponding to Super-Duper ## Reset: RNGkind(ok[1]) ## ---- sum(duplicated(runif(1e6))) # around 110 for default generator ## and we would expect about almost sure duplicates beyond about qbirthday(1-1e-6, classes=2e9) # 235,000 Random.user User-supplied Random Number Generation Description Function RNGkind allows user-coded uniform and normal random number generators to be supplied. The details are given here. Details A user-specified uniform RNG is called from entry points in dynamically-loaded compiled code. The user must supply the entry point user_unif_rand, which takes no arguments and returns a pointer to a double. The example below will show the general pattern. Optionally, the user can supply the entry point user_unif_init, which is called with an unsigned int argument when RNGkind (or set.seed) is called, and is intended to be used to initialize the user’s RNG code. The argument is intended to be used to set the ‘seeds’; it is the seed argument to set.seed or an essentially random seed if RNGkind is called. If only these functions are supplied, no information about the generator’s state is recorded in .Random.seed. Optionally, functions user_unif_nseed and user_unif_seedloc can be supplied which are called with no arguments and should return pointers to the number of seeds and to an integer (specifically, ‘Int32’) array of seeds. Calls to GetRNGstate and PutRNGstate will then copy this array to and from .Random.seed. A user-specified normal RNG is specified by a single entry point user_norm_rand, which takes no arguments and returns a pointer to a double. 396 Random.user Warning As with all compiled code, mis-specifying these functions can crash R. Do include the ‘R_ext/Random.h’ header file for type checking. Examples ## Not run: ## Marsaglia’s congruential PRNG #include static Int32 seed; static double res; static int nseed = 1; double * user_unif_rand() { seed = 69069 * seed + 1; res = seed * 2.32830643653869e-10; return &res; } void user_unif_init(Int32 seed_in) { seed = seed_in; } int * user_unif_nseed() { return &nseed; } int * user_unif_seedloc() { return (int *) &seed; } /* ratio-of-uniforms for normal */ #include static double x; double * user_norm_rand() { double u, v, z; do { u = unif_rand(); v = 0.857764 * (2. * unif_rand() - 1); x = v/u; z = 0.25 * x * x; if (z < 1. - u) break; if (z > 0.259/u + 0.35) continue; } while (z > -log(u)); return &x; } ## Use under Unix: R CMD SHLIB urand.c R > dyn.load("urand.so") > RNGkind("user") > runif(10) > .Random.seed > RNGkind(, "user") > rnorm(10) > RNGkind() range 397 [1] "user-supplied" "user-supplied" ## End(Not run) range Range of Values Description range returns a vector containing the minimum and maximum of all the given arguments. Usage range(..., na.rm = FALSE) ## Default S3 method: range(..., na.rm = FALSE, finite = FALSE) Arguments ... any numeric or character objects. na.rm logical, indicating if NA’s should be omitted. finite logical, indicating if all non-finite elements should be omitted. Details range is a generic function: methods can be defined for it directly or via the Summary group generic. For this to work properly, the arguments ... should be unnamed, and dispatch is on the first argument. If na.rm is FALSE, NA and NaN values in any of the arguments will cause NA values to be returned, otherwise NA values are ignored. If finite is TRUE, the minimum and maximum of all finite values is computed, i.e., finite=TRUE includes na.rm=TRUE. A special situation occurs when there is no (after omission of NAs) nonempty argument left, see min. S4 methods This is part of the S4 Summary group generic. Methods for it must use the signature x, ..., na.rm. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. 398 rank See Also min, max. The extendrange() utility in package grDevices. Examples (r.x <- range(stats::rnorm(100))) diff(r.x) # the SAMPLE range x <- c(NA, 1:3, -1:1/0); x range(x) range(x, na.rm = TRUE) range(x, finite = TRUE) rank Sample Ranks Description Returns the sample ranks of the values in a vector. Ties (i.e., equal values) and missing values can be handled in several ways. Usage rank(x, na.last = TRUE, ties.method = c("average", "first", "random", "max", "min")) Arguments x a numeric, complex, character or logical vector. na.last for controlling the treatment of NAs. If TRUE, missing values in the data are put last; if FALSE, they are put first; if NA, they are removed; if "keep" they are kept with rank NA. ties.method a character string specifying how ties are treated, see ‘Details’; can be abbrevi- ated. Details If all components are different (and no NAs), the ranks are well defined, with values in seq_len(x). With some values equal (called ‘ties’), the argument ties.method determines the result at the corresponding indices. The "first" method results in a permutation with increasing values at each index set of ties. The "random" method puts these in random order whereas the default, "average", replaces them by their mean, and "max" and "min" replaces them by their maximum and minimum respectively, the latter being the typical sports ranking. NA values are never considered to be equal: for na.last = TRUE and na.last = FALSE they are given distinct ranks in the order in which they occur in x. rapply 399 NB: rank is not itself generic but xtfrm is, and rank(xtfrm(x), ....) will have the desired result if there is a xtfrm method. Otherwise, rank will make use of ==, > and is.na methods for classed objects, possibly rather slowly. Value A numeric vector of the same length as x with names copied from x (unless na.last = NA, when missing values are removed). The vector is of integer type unless ties.method = "average" when it is of double type (whether or not there are any ties). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also order and sort. Examples (r1 <- rank(x1 <- c(3, 1, 4, 15, 92))) x2 <- c(3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5) names(x2) <- letters[1:11] (r2 <- rank(x2)) # ties are averaged ## rank() is "idempotent": rank(rank(x)) == rank(x) : stopifnot(rank(r1) == r1, rank(r2) == r2) ## ranks without averaging rank(x2, ties.method= "first") # first occurrence wins rank(x2, ties.method= "random") # ties broken at random rank(x2, ties.method= "random") # and again ## keep ties ties, no average (rma <- rank(x2, ties.method= "max")) # as used classically (rmi <- rank(x2, ties.method= "min")) # as in Sports stopifnot(rma + rmi == round(r2 + r2)) rapply Recursively Apply a Function to a List Description rapply is a recursive version of lapply. Usage rapply(object, f, classes = "ANY", deflt = NULL, how = c("unlist", "replace", "list"), ...) 400 rapply Arguments object A list. f A function of a single argument. classes A character vector of class names, or "ANY" to match any class. deflt The default result (not used if how = "replace"). how A character string matching the three possibilities given: see ‘Details’. ... additional arguments passed to the call to f. Details This function has two basic modes. If how = "replace", each element of the list which is not itself a list and has a class included in classes is replaced by the result of applying f to the element. If the mode is how = "list" or how = "unlist", the list is copied, all non-list elements which have a class included in classes are replaced by the result of applying f to the element and all others are replaced by deflt. Finally, if how = "unlist", unlist(recursive = TRUE) is called on the result. The semantics differ in detail from lapply: in particular the arguments are evaluated before calling the C code. Value If how = "unlist", a vector, otherwise a list of similar structure to object. References Chambers, J. A. (1998) Programming with Data. Springer. (rapply is only described briefly there.) See Also lapply, dendrapply. Examples X <- list(list(a=pi, b=list(c=1:1)), d="a test") rapply(X, function(x) x, how="replace") rapply(X, sqrt, classes="numeric", how="replace") rapply(X, nchar, classes="character", deflt = as.integer(NA), how="list") rapply(X, nchar, classes="character", deflt = as.integer(NA), how="unlist") rapply(X, nchar, classes="character", how="unlist") rapply(X, log, classes="numeric", how="replace", base=2) raw 401 raw Raw Vectors Description Creates or tests for objects of type "raw". Usage raw(length = 0) as.raw(x) is.raw(x) Arguments length desired length. x object to be coerced. Details The raw type is intended to hold raw bytes. It is possible to extract subsequences of bytes, and to replace elements (but only by elements of a raw vector). The relational operators (see Comparison) work, as do the logical operators (see Logic) with a bitwise interpretation. A raw vector is printed with each byte separately represented as a pair of hex digits. If you want to see a character representation (with escape sequences for non-printing characters) use rawToChar. Coercion to raw treats the input values as representing small (decimal) integers, so the input is first coerced to integer, and then values which are outside the range [0 ... 255] or are NA are set to 0 (the nul byte). as.raw and is.raw are primitive functions. Value raw creates a raw vector of the specified length. Each element of the vector is equal to 0. Raw vectors are used to store fixed-length sequences of bytes. as.raw attempts to coerce its argument to be of raw type. The (elementwise) answer will be 0 unless the coercion succeeds (or if the original value successfully coerces to 0). is.raw returns true if and only if typeof(x) == "raw". See Also charToRaw, rawShift, etc. 402 rawConnection Examples xx <- raw(2) xx[1] <- as.raw(40) # NB, not just 40. xx[2] <- charToRaw("A") xx x <- "A test string" (y <- charToRaw(x)) is.vector(y) # TRUE rawToChar(y) is.raw(x) is.raw(y) isASCII <- function(txt) all(charToRaw(txt) <= as.raw(127)) isASCII(x) # true isASCII("\x9c25.63") # false (in Latin-1, this is an amount in UK pounds) rawConnection Raw Connections Description Input and output raw connections. Usage rawConnection(object, open = "r") rawConnectionValue(con) Arguments object character or raw vector. A description of the connection. For an input this is an R raw vector object, and for an output connection the name for the connection. open character. Any of the standard connection open modes. con An output raw connection. Details An input raw connection is opened and the raw vector is copied at the time the connection object is created, and close destroys the copy. An output raw connection is opened and creates an R raw vector internally. The raw vector can be retrieved via rawConnectionValue. If a connection is open for both input and output the initial raw vector supplied is copied when the connections is open rawConversion 403 Value For rawConnection, a connection object of class "rawConnection" which inherits from class "connection". For rawConnectionValue, a raw vector. Note As output raw connections keep the internal raw vector up to date call-by-call, they are relatively expensive to use (although over-allocation is used), and it may be better to use an anonymous file() connection to collect output. On (rare) platforms where vsnprintf does not return the needed length of output there is a 100,000 character limit on the length of line for output connections: longer lines will be truncated with a warning. See Also connections, showConnections. Examples zz <- rawConnection(raw(0), "r+") # start with empty raw vector writeBin(LETTERS, zz) seek(zz, 0) readLines(zz) # raw vector has embedded nuls seek(zz, 0) writeBin(letters[1:3], zz) rawConnectionValue(zz) close(zz) rawConversion Convert to or from Raw Vectors Description Conversion and manipulation of objects of type "raw". Usage charToRaw(x) rawToChar(x, multiple = FALSE) rawShift(x, n) rawToBits(x) intToBits(x) packBits(x, type = c("raw", "integer")) 404 rawConversion Arguments x object to be converted or shifted. multiple logical: should the conversion be to a single character string or multiple individ- ual characters? n the number of bits to shift. Positive numbers shift right and negative numbers shift left: allowed values are -8 ... 8. type the result type. Details packBits accepts raw, integer or logical inputs, the last two without any NAs. Note that ‘bytes’ are not necessarily the same as characters, e.g. in UTF-8 locales. Value charToRaw converts a length-one character string to raw bytes. It does so without taking into account any declared encoding (see Encoding). rawToChar converts raw bytes either to a single character string or a character vector of single bytes (with "" for 0). (Note that a single character string could contain embedded nuls; only trailing nulls are allowed and will be removed.) In either case it is possible to create a result which is invalid in a multibyte locale, e.g. one using UTF-8. rawShift(x,n) shift the bits in x by n positions to the right, see the argument n, above. rawToBits returns a raw vector of 8 times the length of a raw vector with entries 0 or 1. intToBits returns a raw vector of 32 times the length of an integer vector with entries 0 or 1. (Non-integral numeric values are truncated to integers.) In both cases the unpacking is least-significant bit first. packBits packs its input (using only the lowest bit for raw or integer vectors) least-significant bit first to a raw or integer vector. Examples x <- "A test string" (y <- charToRaw(x)) is.vector(y) # TRUE rawToChar(y) rawToChar(y, multiple = TRUE) (xx <- c(y, charToRaw("&"), charToRaw("more"))) rawToChar(xx) rawShift(y, 1) rawShift(y, -2) rawToBits(y) showBits <- function(r) stats::symnum(as.logical(rawToBits(r))) z <- as.raw(5) z ; showBits(z) RdUtils 405 showBits(rawShift(z, 1)) # shift to right showBits(rawShift(z, 2)) showBits(z) showBits(rawShift(z, -1)) # shift to left showBits(rawShift(z, -2)) # .. showBits(rawShift(z, -3)) # shifted off entirely RdUtils Utilities for Processing Rd Files Description Utilities for converting files in R documentation (Rd) format to other formats or create indices from them, and for converting documentation in other formats to Rd format. Usage R CMD Rdconv [options] file R CMD Rd2dvi [options] files R CMD Rd2pdf [options] files Arguments file the path to a file to be processed. files a list of file names specifying the R documentation sources to use, by either giving the paths to the files, or the path to a directory with the sources of a package. options further options to control the processing, or for obtaining information about us- age and version of the utility. Details R CMD Rdconv converts Rd format to plain text, HTML or LaTeX formats: it can also extract the examples. R CMD Rd2pdf is the user-level program for producing PDF output from Rd sources. It will make use of the environment variables R_PAPERSIZE (set by R CMD, with a default set when R was installed: values for R_PAPERSIZE are a4, letter, legal and executive) and R_PDFVIEWER (the PDF pre- viewer). Also, RD2DVI_INPUTENC can be set to inputenx to make use of the LaTeX package of that name rather than inputenc: this might be needed for better support of the UTF-8 encoding. R CMD Rd2dvi is a deprecated alternative to R CMD Rd2pdf, which is equivalent to Rd2dvi --pdf; it will be removed in R 2.15.0. When used for DVI output (without the ‘--pdf’ flag) it will also make use of the environment variable xdvi (the DVI previewer, default xdvi) Use R CMD foo --help to obtain usage information on utility foo. See Also The chapter “Processing Rd format” in the “Writing R Extensions” manual. 406 readBin readBin Transfer Binary Data To and From Connections Description Read binary data from a connection, or write binary data to a connection. Usage readBin(con, what, n = 1L, size = NA_integer_, signed = TRUE, endian = .Platform$endian) writeBin(object, con, size = NA_integer_, endian = .Platform$endian, useBytes = FALSE) Arguments con A connection object or a character string naming a file or a raw vector. what Either an object whose mode will give the mode of the vector to be read, or a character vector of length one describing the mode: one of "numeric", "double","integer","int","logical","complex","character","raw". n integer. The (maximal) number of records to be read. You can use an over- estimate here, but not too large as storage is reserved for n items. size integer. The number of bytes per element in the byte stream. The default, NA_integer_, uses the natural size. Size changing is not supported for raw and complex vectors. signed logical. Only used for integers of sizes 1 and 2, when it determines if the quantity on file should be regarded as a signed or unsigned integer. endian The endian-ness ("big" or "little" of the target system for the file. Using "swap" will force swapping endian-ness. object An R object to be written to the connection. useBytes See writeLines. Details These functions are intended to be used with binary-mode connections. If con is a character string, the functions call file to obtain a binary-mode file connection which is opened for the duration of the function call. If the connection is open it is read/written from its current position. If it is not open, it is opened for the duration of the call in an appropriate mode (binary read or write) and then closed again. An open connection must be in binary mode. If readBin is called with con a raw vector, the data in the vector is used as input. If writeBin is called with con a raw vector, it is just an indication that a raw vector should be returned. readBin 407 If size is specified and not the natural size of the object, each element of the vector is coerced to an appropriate type before being written or as it is read. Possible sizes are 1, 2, 4 and possibly 8 for integer or logical vectors, and 4, 8 and possibly 12/16 for numeric vectors. (Note that coercion occurs as signed types except if signed = FALSE when reading integers of sizes 1 and 2.) Changing sizes is unlikely to preserve NAs, and the extended precision sizes are unlikely to be portable across platforms. readBin and writeBin read and write C-style zero-terminated character strings. Input strings are limited to 10000 characters. readChar and writeChar can be used to read and write fixed-length strings. No check is made that the string is valid in the current locale. Handling R’s missing and special (Inf,-Inf and NaN) values is discussed in the R Data Im- port/Export manual. Only 231 −1 bytes can be written in a single call (and that is the maximum capacity of a raw vector). Value For readBin, a vector of appropriate mode and length the number of items read (which might be less than n). For writeBin, a raw vector (if con is a raw vector) or invisibly NULL. Note Integer read/writes of size 8 will be available if either C type long is of size 8 bytes or C type long long exists and is of size 8 bytes. Real read/writes of size sizeof(long double) (usually 12 or 16 bytes) will be available only if that type is available and different from double. If readBin(what = character()) is used incorrectly on a file which does not contain C-style character strings, warnings (usually many) are given. From a file or connection, the input will be broken into pieces of length 10000 with any final part being discarded. Using these functions on a text-mode connection may work but should not be mixed with text-mode access to the connection, especially if the connection was opened with an encoding argument. See Also The R Data Import/Export manual. readChar to read/write fixed-length strings. connections, readLines, writeLines. .Machine for the sizes of long, long long and long double. Examples zz <- file("testbin", "wb") writeBin(1:10, zz) writeBin(pi, zz, endian="swap") writeBin(pi, zz, size=4) writeBin(pi^2, zz, size=4, endian="swap") writeBin(pi+3i, zz) writeBin("A test of a connection", zz) 408 readChar z <- paste("A very long string", 1:100, collapse=" + ") writeBin(z, zz) if(.Machine$sizeof.long == 8 || .Machine$sizeof.longlong == 8) writeBin(as.integer(5^(1:10)), zz, size = 8) if((s <-.Machine$sizeof.longdouble) > 8) writeBin((pi/3)^(1:10), zz, size = s) close(zz) zz <- file("testbin", "rb") readBin(zz, integer(), 4) readBin(zz, integer(), 6) readBin(zz, numeric(), 1, endian="swap") readBin(zz, numeric(), size=4) readBin(zz, numeric(), size=4, endian="swap") readBin(zz, complex(), 1) readBin(zz, character(), 1) z2 <- readBin(zz, character(), 1) if(.Machine$sizeof.long == 8 || .Machine$sizeof.longlong == 8) readBin(zz, integer(), 10, size = 8) if((s <-.Machine$sizeof.longdouble) > 8) readBin(zz, numeric(), 10, size = s) close(zz) unlink("testbin") stopifnot(z2 == z) ## signed vs unsigned ints zz <- file("testbin", "wb") x <- as.integer(seq(0, 255, 32)) writeBin(x, zz, size=1) writeBin(x, zz, size=1) x <- as.integer(seq(0, 60000, 10000)) writeBin(x, zz, size=2) writeBin(x, zz, size=2) close(zz) zz <- file("testbin", "rb") readBin(zz, integer(), 8, size=1) readBin(zz, integer(), 8, size=1, signed=FALSE) readBin(zz, integer(), 7, size=2) readBin(zz, integer(), 7, size=2, signed=FALSE) close(zz) unlink("testbin") ## use of raw z <- writeBin(pi^{1:5}, raw(), size = 4) readBin(z, numeric(), 5, size = 4) z <- writeBin(c("a", "test", "of", "character"), raw()) readBin(z, character(), 4) readChar Transfer Character Strings To and From Connections readChar 409 Description Transfer character strings to and from connections, without assuming they are null-terminated on the connection. Usage readChar(con, nchars, useBytes = FALSE) writeChar(object, con, nchars = nchar(object, type="chars"), eos = "", useBytes = FALSE) Arguments con A connection object, or a character string naming a file, or a raw vector. nchars integer, giving the lengths in characters of (unterminated) character strings to be read or written. Must be >= 0 and not missing. useBytes logical: For readChar, should nchars be regarded as a number of bytes not characters in a multi-byte locale? For writeChar, see writeLines. object A character vector to be written to the connection, at least as long as nchars. eos ‘end of string’: character string . The terminator to be written after each string, followed by an ASCII nul; use NULL for no terminator at all. Details These functions complement readBin and writeBin which read and write C-style zero-terminated character strings. They are for strings of known length, and can optionally write an end-of-string mark. They are intended only for character strings valid in the current locale. These functions are intended to be used with binary-mode connections. If con is a character string, the functions call file to obtain a binary-mode file connection which is opened for the duration of the function call. If the connection is open it is read/written from its current position. If it is not open, it is opened for the duration of the call in an appropriate mode (binary read or write) and then closed again. An open connection must be in binary mode. If readChar is called with con a raw vector, the data in the vector is used as input. If writeChar is called with con a raw vector, it is just an indication that a raw vector should be returned. Character strings containing ASCII nul(s) will be read correctly by readChar but truncated at the first nul with a warning. If the character length requested for readChar is longer than the data available on the connection, what is available is returned. For writeChar if too many characters are requested the output is zero-padded, with a warning. Missing strings are written as NA. 410 readline Value For readChar, a character vector of length the number of items read (which might be less than length(nchars)). For writeChar, a raw vector (if con is a raw vector) or invisibly NULL. Note Earlier versions of R allowed embedded nul bytes within character strings, but not R >= 2.8.0. readChar was commonly used to read fixed-size zero-padded byte fields for which readBin was unsuitable. readChar can still be used for such fields if there are no embedded nuls: otherwise readBin(what="raw") provides an alternative. nchars will be interpreted in bytes not characters in a non-UTF-8 multi-byte locale, with a warning. There is little validity checking of UTF-8 reads. Using these functions on a text-mode connection may work but should not be mixed with text-mode access to the connection, especially if the connection was opened with an encoding argument. See Also The R Data Import/Export manual. connections, readLines, writeLines, readBin Examples ## test fixed-length strings zz <- file("testchar", "wb") x <- c("a", "this will be truncated", "abc") nc <- c(3, 10, 3) writeChar(x, zz, nc, eos=NULL) writeChar(x, zz, eos="\r\n") close(zz) zz <- file("testchar", "rb") readChar(zz, nc) readChar(zz, nchar(x)+3) # need to read the terminator explicitly close(zz) unlink("testchar") readline Read a Line from the Terminal Description readline reads a line from the terminal (in interactive use). Usage readline(prompt = "") readLines 411 Arguments prompt the string printed when prompting the user for input. Should usually end with a space "". Details The prompt string will be truncated to a maximum allowed length, normally 256 chars (but can be changed in the source code). This can only be used in an interactive session. Value A character vector of length one. Both leading and trailing spaces and tabs are stripped from the result. In non-interactive use the result is as if the response was RETURN and the value is "". See Also readLines for reading text lines from connections, including files. Examples fun <- function() { ANSWER <- readline("Are you a satisfied R user? ") ## a better version would check the answer less cursorily, and ## perhaps re-prompt if (substr(ANSWER, 1, 1) == "n") cat("This is impossible. YOU LIED!\n") else cat("I knew it.\n") } if(interactive()) fun() readLines Read Text Lines from a Connection Description Read some or all text lines from a connection. Usage readLines(con = stdin(), n = -1L, ok = TRUE, warn = TRUE, encoding = "unknown") 412 readLines Arguments con a connection object or a character string. n integer. The (maximal) number of lines to read. Negative values indicate that one should read up to the end of input on the connection. ok logical. Is it OK to reach the end of the connection before n > 0 lines are read? If not, an error will be generated. warn logical. Warn if a text file is missing a final EOL. encoding encoding to be assumed for input strings. It is used to mark character strings as known to be in Latin-1 or UTF-8: it is not used to re-encode the input. To do the latter, specify the encoding as part of the connection con or via options(encoding=): see the example under file. Details If the con is a character string, the function calls file to obtain a file connection which is opened for the duration of the function call. As from R 2.10.0 this can be a compressed file. If the connection is open it is read from its current position. If it is not open, it is opened in "rt" mode for the duration of the call and then closed again. If the final line is incomplete (no final EOL marker) the behaviour depends on whether the con- nection is blocking or not. For a non-blocking text-mode connection the incomplete line is pushed back, silently. For all other connections the line will be accepted, with a warning. Whatever mode the connection is opened in, any of LF, CRLF or CR will be accepted as the EOL marker for a line. If con is a not-already-open connection with a non-default encoding argument, the text is converted to UTF-8 and declared as such (and the encoding argument to readLines is ignored). See the examples. Value A character vector of length the number of lines read. The elements of the result have a declared encoding if encoding is "latin1" or "UTF-8", Note The default connection, stdin, may be different from con = "stdin": see file. See Also connections, writeLines, readBin, scan Examples cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file="ex.data", sep="\n") readLines("ex.data", n=-1) unlink("ex.data") # tidy up readRDS 413 ## difference in blocking cat("123\nabc", file = "test1") readLines("test1") # line with a warning con <- file("test1", "r", blocking = FALSE) readLines(con) # empty cat(" def\n", file = "test1", append = TRUE) readLines(con) # gets both close(con) unlink("test1") # tidy up ## Not run: # read a ’Windows Unicode’ file A <- readLines(file("Unicode.txt", encoding="UCS-2LE")) unique(Encoding(A)) # will most likely be UTF-8 ## End(Not run) readRDS Serialization Interface for Single Objects Description Functions to write a single R object to a file, and to restore it. Usage saveRDS(object, file = "", ascii = FALSE, version = NULL, compress = TRUE, refhook = NULL) readRDS(file, refhook = NULL) Arguments object R object to serialize. file a connection or the name of the file where the R object is saved to or read from. ascii a logical. If TRUE, an ASCII representation is written; otherwise (default except for text-mode connections), a binary one is used. See the comments in the help for save. version the workspace format version to use. NULL specifies the current default version (2). Versions prior to 2 are not supported, so this will only be relevant when there are later versions. compress a logical specifying whether saving to a named file is to use "gzip" compres- sion, or one of "gzip","bzip2" or "xz" to indicate the type of compression to be used. Ignored if file is a connection. refhook a hook function for handling reference objects. 414 readRDS Details These functions provide the means to save a single R object to a connection (typically a file) and to restore the object, quite possibly under a different name. This differs from save and load, which save and restore one or more named objects into an environment. They are widely used by R itself, for example to store metadata for a package and to store the help.search databases: the ".rds" file extension is most often used. Functions serialize and unserialize provide a slightly lower-level interface to serialization: objects serialized to a connection by serialize can be read back by readRDS and conversely. All of these interfaces use the same serialization format, which has been used since R 1.4.0 (but extended from time to time as new object types have been added to R). However, save writes a single line header (typically "RDXs\n") before the serialization of a single object (a pairlist of all the objects to be saved). Compression is handled by the connection opened when file is a file name, so is only possible when file is a connection if handled by the connection. So e.g. url connections will needed to be wrapped in a call to gzcon. If a connection is supplied it will be opened (in binary mode) for the duration of the function if not already open: if it is already open it must be in binary mode for saveRDS(ascii = FALSE) (the default). Value For readRDS, an R object. For saveRDS, NULL invisibly. See Also serialize, save and load. The ‘R Internals’ manual for details of the format used. Examples ## save a single object to file saveRDS(women, "women.rds") ## restore it under a different name women2 <- readRDS("women.rds") identical(women, women2) ## or examine the object via a connection, which will be opened as needed. con <- gzfile("women.rds") str(readRDS(con)) close(con) ## Less convenient ways to restore the object ## which demonstrate compatibility with unserialize() con <- gzfile("women.rds", "rb") identical(unserialize(con), women) close(con) con <- gzfile("women.rds", "rb") wm <- readBin(con, "raw", n = 1e4) # size is a guess readRenviron 415 close(con) identical(unserialize(wm), women) ## Format compatibility with serialize(): con <- file("women2", "w") serialize(women, con) # ASCII, uncompressed close(con) identical(women, readRDS("women2")) con <- bzfile("women3", "w") serialize(women, con) # binary, bzip2-compressed close(con) identical(women, readRDS("women2")) readRenviron Set Environment Variables from a File Description Read as file such as ‘.Renviron’ or ‘Renviron.site’ in the format described in the help for Startup, and set environment variables as defined in the file. Usage readRenviron(path) Arguments path A length-one character vector giving the path to the file. Tilde-expansion is performed where supported. Value Scalar logical indicating if the file was read successfully. Returned invisibly. If the file cannot be opened for reading, a warning is given. See Also Startup for the file format. Examples ## Not run: ## re-read a startup file (or read it in a vanilla session) readRenviron("~/.Renviron") ## End(Not run) 416 Recall real Real Vectors Description These functions are the same as their double equivalents and are provided for backwards compati- bility only. Usage real(length = 0) as.real(x, ...) is.real(x) Arguments length A non-negative integer specifying the desired length. Double values will be coerced to integer: supplying an argument of length other than one is an error. x object to be coerced or tested. ... further arguments passed to or from other methods. Details as.real is a generic function, but S3 methods must be written for as.double. Recall Recursive Calling Description Recall is used as a placeholder for the name of the function in which it is called. It allows the definition of recursive functions which still work after being renamed, see example below. Usage Recall(...) Arguments ... all the arguments to be passed. Note Recall will not work correctly when passed as a function argument, e.g. to the apply family of functions. reg.finalizer 417 See Also do.call and call. local for another way to write anonymous recursive functions. Examples ## A trivial (but inefficient!) example: fib <- function(n) if(n<=2) { if(n>=0) 1 else 0 } else Recall(n-1) + Recall(n-2) fibonacci <- fib; rm(fib) ## renaming wouldn’t work without Recall fibonacci(10) # 55 reg.finalizer Finalization of Objects Description Registers an R function to be called upon garbage collection of object or (optionally) at the end of an R session. Usage reg.finalizer(e, f, onexit = FALSE) Arguments e Object to finalize. Must be an environment or an external pointer. f Function to call on finalization. Must accept a single argument, which will be the object to finalize. onexit logical: should the finalizer be run if the object is still uncollected at the end of the R session? Value NULL. Note The purpose of this function is mainly to allow objects that refer to external items (a temporary file, say) to perform cleanup actions when they are no longer referenced from within R. This only makes sense for objects that are never copied on assignment, hence the restriction to environments and external pointers. See Also gc and Memory for garbage collection and memory management. 418 regex Examples f <- function(e) print("cleaning....") g <- function(x){ e <- environment(); reg.finalizer(e,f) } g() invisible(gc()) # trigger cleanup regex Regular Expressions as used in R Description This help page documents the regular expression patterns supported by grep and related functions grepl, regexpr, gregexpr, sub and gsub, as well as by strsplit. Details A ‘regular expression’ is a pattern that describes a set of strings. Two types of regular expressions are used in R, extended regular expressions (the default) and Perl-like regular expressions used by perl = TRUE. There is a also fixed = TRUE which can be considered to use a literal regular expression. Other functions which use regular expressions (often via the use of grep) include apropos, browseEnv, help.search, list.files and ls. These will all use extended regular expressions. Patterns are described here as they would be printed by cat:(do remember that backslashes need to be doubled when entering R character strings, e.g. from the keyboard). Extended Regular Expressions This section covers the regular expressions allowed in the default mode of grep, regexpr, gregexpr, sub, gsub and strsplit. They use an implementation of the POSIX 1003.2 stan- dard: that allows some scope for interpretation and the interpretations here are those used as from R 2.10.0. Regular expressions are constructed analogously to arithmetic expressions, by using various opera- tors to combine smaller expressions. The whole expression matches zero or more characters (read ‘character’ as ‘byte’ if useBytes = TRUE). The fundamental building blocks are the regular expressions that match a single character. Most characters, including all letters and digits, are regular expressions that match themselves. Any metacharacter with special meaning may be quoted by preceding it with a backslash. The metachar- acters in EREs are ‘.\ |()[{^$*+?’, but note that whether these have a special meaning depends on the context. Escaping non-metacharacters with a backslash is implementation-dependent. The current imple- mentation interprets ‘\a’ as ‘BEL’, ‘\e’ as ‘ESC’, ‘\f’ as ‘FF’, ‘\n’ as ‘LF’, ‘\r’ as ‘CR’ and ‘\t’ as ‘TAB’. (Note that these will be interpreted by R’s parser in literal character strings.) A character class is a list of characters enclosed between ‘[’ and ‘]’ which matches any single character in that list; unless the first character of the list is the caret ‘^’, when it matches any character not in the list. For example, the regular expression ‘[0123456789]’ matches any single regex 419 digit, and ‘[^abc]’ matches anything except the characters ‘a’, ‘b’ or ‘c’. A range of characters may be specified by giving the first and last characters, separated by a hyphen. (Because their interpretation is locale- and implementation-dependent, they are best avoided.) The only portable way to specify all ASCII letters is to list them all as the character class ‘[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz]’. (The current implementation uses numerical order of the encoding: prior to R 2.10.0 locale-specific collation was used, and might be again.) Certain named classes of characters are predefined. Their interpretation depends on the locale (see locales); the interpretation below is that of the POSIX locale. ‘[:alnum:]’ Alphanumeric characters: ‘[:alpha:]’ and ‘[:digit:]’. ‘[:alpha:]’ Alphabetic characters: ‘[:lower:]’ and ‘[:upper:]’. ‘[:blank:]’ Blank characters: space and tab, and possibly other locale-dependent characters such as non-breaking space. ‘[:cntrl:]’ Control characters. In ASCII, these characters have octal codes 000 through 037, and 177 (DEL). In another character set, these are the equivalent characters, if any. ‘[:digit:]’ Digits: ‘0 1 2 3 4 5 6 7 8 9’. ‘[:graph:]’ Graphical characters: ‘[:alnum:]’ and ‘[:punct:]’. ‘[:lower:]’ Lower-case letters in the current locale. ‘[:print:]’ Printable characters: ‘[:alnum:]’, ‘[:punct:]’ and space. ‘[:punct:]’ Punctuation characters: ‘!"#$%&’()*+,-./:;<=>?@[\]^_‘{|}~’. ‘[:space:]’ Space characters: tab, newline, vertical tab, form feed, carriage return, space and possibly other locale-dependent characters. ‘[:upper:]’ Upper-case letters in the current locale. ‘[:xdigit:]’ Hexadecimal digits: ‘0123456789ABCDEFabcdef’. For example, ‘[[:alnum:]]’ means ‘[0-9A-Za-z]’, except the latter depends upon the locale and the character encoding, whereas the former is independent of locale and character set. (Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list.) Most metacharacters lose their special meaning inside a character class. To include a literal ‘]’, place it first in the list. Similarly, to include a literal ‘^’, place it anywhere but first. Finally, to include a literal ‘-’, place it first or last (or, for perl = TRUE only, precede it by a backslash.). (Only ‘^ - \ ]’ are special inside character classes.) The period ‘.’ matches any single character. The symbol ‘\w’ matches a ‘word’ character (a synonym for ‘[[:alnum:]_]’) and ‘\W’ is its negation. Symbols ‘\d’, ‘\s’, ‘\D’ and ‘\S’ denote the digit and space classes and their negations. The caret ‘^’ and the dollar sign ‘$’ are metacharacters that respectively match the empty string at the beginning and end of a line. The symbols ‘\<’ and ‘\>’ match the empty string at the beginning and end of a word. The symbol ‘\b’ matches the empty string at either edge of a word, and ‘\B’ matches the empty string provided it is not at an edge of a word. (The interpretation of ‘word’ depends on the locale and implementation.) A regular expression may be followed by one of several repetition quantifiers: 420 regex ‘?’ The preceding item is optional and will be matched at most once. ‘*’ The preceding item will be matched zero or more times. ‘+’ The preceding item will be matched one or more times. ‘{n}’ The preceding item is matched exactly n times. ‘{n,}’ The preceding item is matched n or more times. ‘{n,m}’ The preceding item is matched at least n times, but not more than m times. By default repetition is greedy, so the maximal possible number of repeats is used. This can be changed to ‘minimal’ by appending ? to the quantifier. (There are further quantifiers that allow approximate matching: see the TRE documentation.) Regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating the substrings that match the concatenated subexpressions. Two regular expressions may be joined by the infix operator ‘|’; the resulting regular expression matches any string matching either subexpression. For example, ‘abba|cde’ matches either the string abba or the string cde. Note that alternation does not work inside character classes, where ‘|’ has its literal meaning. Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may be enclosed in parentheses to override these precedence rules. The backreference ‘\N’, where ‘N = 1 ... 9’, matches the substring previously matched by the Nth parenthesized subexpression of the regular expression. (This is an extension for extended regular expressions: POSIX defines them only for basic ones.) Perl-like Regular Expressions The perl = TRUE argument to grep, regexpr, gregexpr, sub, gsub and strsplit switches to the PCRE library that implements regular expression pattern matching using the same syntax and semantics as Perl 5.10, with just a few differences. For complete details please consult the man pages for PCRE, especially man pcrepattern and man pcreapi), on your system or from the sources at http://www.pcre.org. If PCRE support was compiled from the sources within R, the PCRE version is 8.12 as described here. Perl regular expressions can be computed byte-by-byte or (UTF-8) character-by-character: the latter is used in all multibyte locales and if any of the inputs are marked as UTF-8 (see Encoding). All the regular expressions described for extended regular expressions are accepted except ‘\<’ and ‘\>’: in Perl all backslashed metacharacters are alphanumeric and backslashed symbols always are interpreted as a literal character. ‘{’ is not special if it would be the start of an invalid interval specification. There can be more than 9 backreferences (but the replacement in sub can only refer to the first 9). Character ranges are interpreted in the numerical order of the characters, either as bytes in a single- byte locale or as Unicode points in UTF-8 mode. So in either case ‘[A-Za-z]’ specifies the set of ASCII letters. In UTF-8 mode the named character classes only match ASCII characters: see ‘\p’ below for an alternative. The construct ‘(?...)’ is used for Perl extensions in a variety of ways depending on what imme- diately follows the ‘?’. regex 421 Perl-like matching can work in several modes, set by the options ‘(?i)’ (caseless, equivalent to Perl’s ‘/i’), ‘(?m)’ (multiline, equivalent to Perl’s ‘/m’), ‘(?s)’ (single line, so a dot matches all characters, even new lines: equivalent to Perl’s ‘/s’) and ‘(?x)’ (extended, whitespace data characters are ignored unless escaped and comments are allowed: equivalent to Perl’s ‘/x’). These can be concatenated, so for example, ‘(?im)’ sets caseless multiline matching. It is also possible to unset these options by preceding the letter with a hyphen, and to combine setting and unsetting such as ‘(?im-sx)’. These settings can be applied within patterns, and then apply to the remainder of the pattern. Additional options not in Perl include ‘(?U)’ to set ‘ungreedy’ mode (so matching is minimal unless ‘?’ is used as part of the repetition quantifier, when it is greedy). Initially none of these options are set. If you want to remove the special meaning from a sequence of characters, you can do so by putting them between ‘\Q’ and ‘\E’. This is different from Perl in that ‘$’ and ‘@’ are handled as literals in ‘\Q...\E’ sequences in PCRE, whereas in Perl, ‘$’ and ‘@’ cause variable interpolation. The escape sequences ‘\d’, ‘\s’ and ‘\w’ represent any decimal digit, space character and ‘word’ character (letter, digit or underscore in the current locale: in UTF-8 mode only ASCII letters and digits are considered) respectively, and their upper-case versions represent their negation. Unlike POSIX, vertical tab is not regarded as a space character. Sequences ‘\h’, ‘\v’, ‘\H’ and ‘\V’ match horizontal and vertical space or the negation. (In UTF-8 mode, these do match non-ASCII Unicode points.) There are additional escape sequences: ‘\cx’ is ‘cntrl-x’ for any ‘x’, ‘\ddd’ is the octal character (for up to three digits unless interpretable as a backreference, as ‘\1’ to ‘\7’ always are), and ‘\xhh’ specifies a character by two hex digits. In a UTF-8 locale, ‘\x{h...}’ specifies a Unicode point by one or more hex digits. (Note that some of these will be interpreted by R’s parser in literal character strings.) Outside a character class, ‘\A’ matches at the start of a subject (even in multiline mode, unlike ‘^’), ‘\Z’ matches at the end of a subject or before a newline at the end, ‘\z’ matches only at end of a subject. and ‘\G’ matches at first matching position in a subject (which is subtly different from Perl’s end of the previous match). ‘\C’ matches a single byte, including a newline, but its use is warned against. In UTF-8 mode, ‘\R’ matches any Unicode newline character (not just CR), and ‘\X’ matches any number of Unicode characters that form an extended Unicode sequence. In UTF-8 mode, some Unicode properties are supported via ‘\p{xx}’ and ‘\P{xx}’ which match characters with and without property ‘xx’ respectively. For a list of supported properties see the PCRE documentation, but for example ‘Lu’ is ‘upper case letter’ and ‘Sc’ is ‘currency symbol’. The sequence ‘(?#’ marks the start of a comment which continues up to the next closing parenthesis. Nested parentheses are not permitted. The characters that make up a comment play no part at all in the pattern matching. If the extended option is set, an unescaped ‘#’ character outside a character class introduces a comment that continues up to the next newline character in the pattern. The pattern ‘(?:...)’ groups characters just as parentheses do but does not make a backreference. Patterns ‘(?=...)’ and ‘(?!...)’ are zero-width positive and negative lookahead assertions: they match if an attempt to match the ... forward from the current position would succeed (or not), but use up no characters in the string being processed. Patterns ‘(?<=...)’ and ‘(?[A-Z][a-z]+)" then the positions of the matches are also returned by name. (Named backreferences are not supported by sub.) 422 regmatches Atomic grouping, possessive qualifiers and conditional and recursive patterns are not covered here. Author(s) This help page is based on the documentation of GNU grep 2.4.2, the TRE documentation and the POSIX standard, and the pcrepattern man page from PCRE 8.0. See Also grep, apropos, browseEnv, glob2rx, help.search, list.files, ls and strsplit. The TRE documentation at http://laurikari.net/tre/documentation/regex-syntax/). The POSIX 1003.2 standard at http://pubs.opengroup.org/onlinepubs/9699919799/ basedefs/V1_chap09.html#tag_09 The pcrepattern can be found as part of http://www.pcre.org/pcre.txt, and details of Perl’s own implementation at http://perldoc.perl.org/perlre.html. regmatches Extract or Replace Matched Substrings Description Extract or replace matched substrings from match data obtained by regexpr, gregexpr or regexec. Usage regmatches(x, m, invert = FALSE) regmatches(x, m, invert = FALSE) <- value Arguments x a character vector m an object with match data invert a logical: if TRUE, extract the non-matched substrings. value an object with suitable replacement values for the matched or non-matched sub- strings (see Details). Details If invert is TRUE (default), regmatches extracts the matched substrings as specified by the match data. For vector match data (as obtained from regexpr), empty matches are dropped; for list match data, empty matches give empty components (zero-length character vectors). If invert is FALSE, regmatches extracts the non-matched substrings, i.e., the strings are split ac- cording to the matches similar to strsplit (for vector match data, at most a single split is per- formed). regmatches 423 Note that the match data can be obtained from regular expression matching on a modified version of x with the same numbers of characters. The replacement function can be used for replacing the matched or non-matched substrings. For vector match data, if invert is TRUE, value should be a character vector with length the number of matched elements in m. Otherwise, it should be a list of character vectors with the same length as m, each as long as the number of replacements needed. Replacement coerces values to character or list and generously recycles values as needed. Missing replacement values are not allowed. Value For regmatches, a character vector with the matched substrings if m is a vector and invert is FALSE. Otherwise, a list with the matched or non-matched substrings. For regmatches<-, the updated character vector. Examples x <- c("A and B", "A, B and C", "A, B, C and D", "foobar") pattern <- "[[:space:]]*(,|and)[[:space:]]" ## Match data from regexpr() m <- regexpr(pattern, x) regmatches(x, m) regmatches(x, m, invert = TRUE) ## Match data from gregexpr() m <- gregexpr(pattern, x) regmatches(x, m) regmatches(x, m, invert = TRUE) ## Consider x <- "John (fishing, hunting), Paul (hiking, biking)" ## Suppose we want to split at the comma (plus spaces) between the ## persons, but not at the commas in the parenthesized hobby lists. ## One idea is to "blank out" the parenthesized parts to match the ## parts to be used for splitting, and extract the persons as the ## non-matched parts. ## First, match the parenthesized hobby lists. m <- gregexpr("\\([^)]*\\)", x) ## Write a little utility for creating blank strings with given numbers ## of characters. blanks <- function(n) { vapply(Map(rep.int, rep.int(" ", length(n)), n, USE.NAMES = FALSE), paste, "", collapse = "") } ## Create a copy of x with the parenthesized parts blanked out. s <- x regmatches(s, m) <- Map(blanks, lapply(regmatches(s, m), nchar)) s ## Compute the positions of the split matches (note that we cannot call ## strsplit() on x with match data from s). m <- gregexpr(", *", s) ## And finally extract the non-matched parts. regmatches(x, m, invert = TRUE) 424 remove remove Remove Objects from a Specified Environment Description remove and rm can be used to remove objects. These can be specified successively as character strings, or in the character vector list, or through a combination of both. All objects thus specified will be removed. If envir is NULL then the currently active environment is searched first. If inherits is TRUE then parents of the supplied directory are searched until a variable with the given name is encountered. A warning is printed for each variable that is not found. Usage remove(..., list = character(), pos = -1, envir = as.environment(pos), inherits = FALSE) rm (..., list = character(), pos = -1, envir = as.environment(pos), inherits = FALSE) Arguments ... the objects to be removed, as names (unquoted) or character strings (quoted). list a character vector naming objects to be removed. pos where to do the removal. By default, uses the current environment. See ‘details’ for other possibilities. envir the environment to use. See ‘details’. inherits should the enclosing frames of the environment be inspected? Details The pos argument can specify the environment from which to remove the objects in any of several ways: as an integer (the position in the search list); as the character string name of an element in the search list; or as an environment (including using sys.frame to access the currently active function calls). The envir argument is an alternative way to specify an environment, but is primarily there for back compatibility. It is not allowed to remove variables from the base environment and base namespace, nor from any environment which is locked (see lockEnvironment). Earlier versions of R incorrectly claimed that supplying a character vector in ... removed the objects named in the character vector, but it removed the character vector. Use the list argument to specify objects via a character vector. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. rep 425 See Also ls, objects Examples tmp <- 1:4 ## work with tmp and cleanup rm(tmp) ## Not run: ## remove (almost) everything in the working environment. ## You will get no warning, so don’t do this unless you are really sure. rm(list = ls()) ## End(Not run) rep Replicate Elements of Vectors and Lists Description rep replicates the values in x. It is a generic function, and the (internal) default method is described here. rep.int is a faster simplified version for the most common case. Usage rep(x, ...) rep.int(x, times) Arguments x a vector (of any mode including a list) or a pairlist or a factor or (except for rep.int) a POSIXct or POSIXlt or date object; or also, an S4 object containing a vector of the above kind. ... further arguments to be passed to or from other methods. For the internal default method these can include: times A integer vector giving the (non-negative) number of times to repeat each element if of length length(x), or to repeat the whole vector if of length 1. Negative or NA values are an error. length.out non-negative integer. The desired length of the output vector. Other inputs will be coerced to an integer vector and the first element taken. Ignored if NA or invalid. each non-negative integer. Each element of x is repeated each times. Other in- puts will be coerced to an integer vector and the first element taken. Treated as 1 if NA or invalid. times see .... 426 rep Details The default behaviour is as if the call was rep(x, times=1, length.out=NA, each=1). Normally just one of the additional arguments is specified, but if each is specified with either of the other two, its replication is performed first, and then that implied by times or length.out. If times consists of a single integer, the result consists of the whole input repeated this many times. If times is a vector of the same length as x (after replication by each), the result consists of x[1] repeated times[1] times, x[2] repeated times[2] times and so on. length.out may be given in place of times, in which case x is repeated as many times as is necessary to create a vector of this length. If both are given, length.out takes priority and times is ignored. Non-integer values of times will be truncated towards zero. If times is a computed quantity it is prudent to add a small fuzz. If x has length zero and length.out is supplied and is positive, the values are filled in using the extraction rules, that is by an NA of the appropriate class for an atomic vector (0 for raw vectors) and NULL for a list. Value An object of the same type as x (except that rep will coerce pairlists to vector lists). rep.int returns no attributes. The default method of rep gives the result names (which will almost always contain duplicates) if x had names, but retains no other attributes except for factors. Note Function rep.int is a simple case handled by internal code, and provided as a separate function purely for S compatibility. Function rep is a primitive, but (partial) matching of argument names is performed as for normal functions. You can no longer pass a missing argument to e.g. length.out. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also seq, sequence, replicate. Examples rep(1:4, 2) rep(1:4, each = 2) # not the same. rep(1:4, c(2,2,2,2)) # same as second. rep(1:4, c(2,1,2,1)) rep(1:4, each = 2, len = 4) # first 4 only. rep(1:4, each = 2, len = 10) # 8 integers plus two recycled 1’s. replace 427 rep(1:4, each = 2, times = 3) # length 24, 3 complete replications rep(1, 40*(1-.8)) # length 7 on most platforms rep(1, 40*(1-.8)+1e-7) # better ## replicate a list fred <- list(happy = 1:10, name = "squash") rep(fred, 5) # date-time objects x <- .leap.seconds[1:3] rep(x, 2) rep(as.POSIXlt(x), rep(2, 3)) ## named factor x <- factor(LETTERS[1:4]); names(x) <- letters[1:4] x rep(x, 2) rep(x, each=2) rep.int(x, 2) # no names replace Replace Values in a Vector Description replace replaces the values in x with indices given in list by those given in values. If necessary, the values in values are recycled. Usage replace(x, list, values) Arguments x vector list an index vector values replacement values Value A vector with the values replaced. Note x is unchanged: remember to assign the result. 428 rev References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Reserved Reserved Words in R Description The reserved words in R’s parser are if else repeat while function for in next break TRUE FALSE NULL Inf NaNNA NA_integer_ NA_real_ NA_complex_ NA_character_ ... and ..1,..2 etc, which are used to refer to arguments passed down from an enclosing function. Details Reserved words outside quotes are always parsed to be references to the objects linked to in the ‘Description’, and hence they are not allowed as syntactic names (see make.names). They are allowed as non-syntactic names, e.g. inside backtick quotes. rev Reverse Elements Description rev provides a reversed version of its argument. It is generic function with a default method for vectors and one for dendrograms. Note that this is no longer needed (nor efficient) for obtaining vectors sorted into descending order, since that is now rather more directly achievable by sort(x, decreasing = TRUE). Usage rev(x) Arguments x a vector or another object for which reversal is defined. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Rhome 429 See Also seq, sort. Examples x <- c(1:5,5:3) ## sort into descending order; first more efficiently: stopifnot(sort(x, decreasing = TRUE) == rev(sort(x))) stopifnot(rev(1:7) == 7:1)#- don’t need ’rev’ here Rhome Return the R Home Directory Description Return the R home directory. Usage R.home(component="home") Arguments component As well as "home" which gives the R home directory, other known values are "bin","doc","etc","modules" and "share" giving the paths to the corre- sponding parts of an R installation. Details The R home directory is the top-level directory of the R installation being run. The R home directory is often referred to as R_HOME, and is the value of an environment variable of that name in an R session. It can be found outside an R session by R RHOME. Value A character string giving the R home directory or path to a particular component. Normally the components are all subdirectories of the R home directory, but this may not be the case in a Unix- like installation. The return value for "modules" and on Windows "bin" is to a sub-architecture-specific location. The function R.home() bases the constructed paths on the current value of the environment variable R_HOME which is normally set on startup. On Windows the values of R.home() and R_HOME are guaranteed not to contain spaces, switching to the 8.3 short form of path elements if required. From R 2.13.0 the value of R_HOME is set on startup to use forward slashes (since many package maintainers pass it unquoted to shells, for example in Makefiles). 430 rle rle Run Length Encoding Description Compute the lengths and values of runs of equal values in a vector – or the reverse operation. Usage rle(x) inverse.rle(x, ...) ## S3 method for class ’rle’ print(x, digits = getOption("digits"), prefix = "", ...) Arguments x an atomic vector for rle(); an object of class "rle" for inverse.rle(). ... further arguments; ignored here. digits number of significant digits for printing, see print.default. prefix character string, prepended to each printed line. Details Missing values are regarded as unequal to the previous value, even if that is also missing. inverse.rle() is the inverse function of rle(), reconstructing x from the runs. Value rle() returns an object of class "rle" which is a list with components: lengths an integer vector containing the length of each run. values a vector of the same length as lengths with the corresponding values. inverse.rle() returns an atomic vector. Examples x <- rev(rep(6:10, 1:5)) rle(x) ## lengths [1:5] 5 4 3 2 1 ## values [1:5] 10 9 8 7 6 z <- c(TRUE,TRUE,FALSE,FALSE,TRUE,FALSE,TRUE,TRUE,TRUE) rle(z) rle(as.character(z)) print(rle(z), prefix = "..| ") Round 431 N <- integer(0) stopifnot(x == inverse.rle(rle(x)), identical(N, inverse.rle(rle(N))), z == inverse.rle(rle(z))) Round Rounding of Numbers Description ceiling takes a single numeric argument x and returns a numeric vector containing the smallest integers not less than the corresponding elements of x. floor takes a single numeric argument x and returns a numeric vector containing the largest integers not greater than the corresponding elements of x. trunc takes a single numeric argument x and returns a numeric vector containing the integers formed by truncating the values in x toward 0. round rounds the values in its first argument to the specified number of decimal places (default 0). signif rounds the values in its first argument to the specified number of significant digits. Usage ceiling(x) floor(x) trunc(x, ...) round(x, digits = 0) signif(x, digits = 6) Arguments x a numeric vector. Or, for round and signif, a complex vector. digits integer indicating the number of decimal places (round) or significant digits (signif) to be used. Negative values are allowed (see ‘Details’). ... arguments to be passed to methods. Details These are generic functions: methods can be defined for them individually or via the Math group generic. Note that for rounding off a 5, the IEC 60559 standard is expected to be used, ‘go to the even digit’. Therefore round(0.5) is 0 and round(-1.5) is -2. However, this is dependent on OS services and on representation error (since e.g. 0.15 is not represented exactly, the rounding rule applies to the represented number and not to the printed number, and so round(0.15, 1) could be either 0.1 or 0.2). 432 round.POSIXt Rounding to a negative number of digits means rounding to a power of ten, so for example round(x, digits = -2) rounds to the nearest hundred. For signif the recognized values of digits are 1...22, and non-missing values are rounded to the nearest integer in that range. Complex numbers are rounded to retain the specified number of digits in the larger of the components. Each element of the vector is rounded individually, unlike printing. These are all primitive functions. S4 methods These are all (internally) S4 generic. ceiling, floor and trunc are members of the Math group generic. As an S4 generic, trunc has only one argument. round and signif are members of the Math2 group generic. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also as.integer. Examples round(.5 + -2:4) # IEEE rounding: -2 0 0 2 2 4 4 ( x1 <- seq(-2, 4, by = .5) ) round(x1)#-- IEEE rounding ! x1[trunc(x1) != floor(x1)] x1[round(x1) != floor(x1 + .5)] (non.int <- ceiling(x1) != floor(x1)) x2 <- pi * 100^(-1:3) round(x2, 3) signif(x2, 3) round.POSIXt Round / Truncate Data-Time Objects Description Round or truncate date-time objects. row 433 Usage ## S3 method for class ’POSIXt’ round(x, units = c("secs", "mins", "hours", "days")) ## S3 method for class ’POSIXt’ trunc(x, units = c("secs", "mins", "hours", "days"), ...) ## S3 method for class ’Date’ round(x, ...) ## S3 method for class ’Date’ trunc(x, ...) Arguments x an object inheriting from "POSIXt" or "Date". units one of the units listed. Can be abbreviated. ... arguments to be passed to or from other methods, notably digits for round. Details The time is rounded or truncated to the second, minute, hour or day. Timezones are only relevant to days, when midnight in the current timezone is used. The methods for class "Date" are of little use except to remove fractional days. Value An object of class "POSIXlt" or "Date". See Also round for the generic function and default methods. DateTimeClasses, Date Examples round(.leap.seconds + 1000, "hour") trunc(Sys.time(), "day") row Row Indexes Description Returns a matrix of integers indicating their row number in a matrix-like object, or a factor indicat- ing the row labels. 434 row+colnames Usage row(x, as.factor = FALSE) Arguments x a matrix-like object, that is one with a two-dimensional dim. as.factor a logical value indicating whether the value should be returned as a factor of row labels (created if necessary) rather than as numbers. Value An integer (or factor) matrix with the same dimensions as x and whose ij-th element is equal to i (or the i-th row label). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also col to get columns. Examples x <- matrix(1:12, 3, 4) # extract the diagonal of a matrix dx <- x[row(x) == col(x)] dx # create an identity 5-by-5 matrix x <- matrix(0, nrow = 5, ncol = 5) x[row(x) == col(x)] <- 1 x row+colnames Row and Column Names Description Retrieve or set the row or column names of a matrix-like object. Usage rownames(x, do.NULL = TRUE, prefix = "row") rownames(x) <- value colnames(x, do.NULL = TRUE, prefix = "col") colnames(x) <- value row.names 435 Arguments x a matrix-like R object, with at least two dimensions for colnames. do.NULL logical. Should this create names if they are NULL? prefix for created names. value a valid value for that component of dimnames(x). For a matrix or array this is either NULL or a character vector of non-zero length equal to the appropriate dimension. Details The extractor functions try to do something sensible for any matrix-like object x. If the object has dimnames the first component is used as the row names, and the second component (if any) is used for the column names. For a data frame, rownames and colnames eventually call row.names and names respectively, but the latter are preferred. If do.NULL is FALSE, a character vector (of length NROW(x) or NCOL(x)) is returned in any case, prepending prefix to simple numbers, if there are no dimnames or the corresponding component of the dimnames is NULL. The replacement methods for arrays/matrices coerce vector and factor values of value to character, but do not dispatch methods for as.character. For a data frame, value for rownames should be a character vector of non-duplicated and non- missing names (this is enforced), and for colnames a character vector of (preferably) unique syntactically-valid names. In both cases, value will be coerced by as.character, and setting colnames will convert the row names to character. See Also dimnames, case.names, variable.names. Examples m0 <- matrix(NA, 4, 0) rownames(m0) m2 <- cbind(1,1:4) colnames(m2, do.NULL = FALSE) colnames(m2) <- c("x","Y") rownames(m2) <- rownames(m2, do.NULL = FALSE, prefix = "Obs.") m2 row.names Get and Set Row Names for Data Frames 436 row.names Description All data frames have a row names attribute, a character vector of length the number of rows with no duplicates nor missing values. For convenience, these are generic functions for which users can write other methods, and there are default methods for arrays. The description here is for the data.frame method. Usage row.names(x) row.names(x) <- value Arguments x object of class "data.frame", or any other class for which a method has been defined. value an object to be coerced to character unless an integer vector. It should have (after coercion) the same length as the number of rows of x with no duplicated nor missing values. NULL is also allowed: see ‘Details’. Details A data frame has (by definition) a vector of row names which has length the number of rows in the data frame, and contains neither missing nor duplicated values. Where a row names sequence has been added by the software to meet this requirement, they are regarded as ‘automatic’. Row names are currently allowed to be integer or character, but for backwards compatibility (with R <= 2.4.0) row.names will always return a character vector. (Use attr(x, "row.names") if you need to retrieve an integer-valued set of row names.) Using NULL for the value resets the row names to seq_len(nrow(x)), regarded as ‘automatic’. Value row.names returns a character vector. row.names<- returns a data frame with the row names changed. Note row.names is similar to rownames for arrays, and it has a method that calls rownames for an array argument. Row names of the form 1:n for n > 2 are stored internally in a compact form, which might be seen from C code or by deparsing but never via row.names or attr(x, "row.names"). Addition- ally, some names of this sort are marked as ‘automatic’ and handled differently by as.matrix and data.matrix (and potentially other functions). (All zero-row data frames are regarded as having automatic row.names.) References Chambers, J. M. (1992) Data for models. Chapter 3 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole. rowsum 437 See Also data.frame, rownames, names. .row_names_info for the internal representations. rowsum Give Column Sums of a Matrix or Data Frame, Based on a Grouping Variable Description Compute column sums across rows of a numeric matrix-like object for each level of a grouping variable. rowsum is generic, with a method for data frames and a default method for vectors and matrices. Usage rowsum(x, group, reorder = TRUE, ...) ## S3 method for class ’data.frame’ rowsum(x, group, reorder = TRUE, na.rm = FALSE, ...) ## Default S3 method: rowsum(x, group, reorder = TRUE, na.rm = FALSE, ...) Arguments x a matrix, data frame or vector of numeric data. Missing values are allowed. A numeric vector will be treated as a column vector. group a vector or factor giving the grouping, with one element per row of x. Missing values will be treated as another group and a warning will be given. reorder if TRUE, then the result will be in order of sort(unique(group)), if FALSE, it will be in the order that groups were encountered. na.rm logical (TRUE or FALSE). Should NA (including NaN) values be discarded? ... other arguments to be passed to or from methods Details The default is to reorder the rows to agree with tapply as in the example below. Reordering should not add noticeably to the time except when there are very many distinct values of group and x has few columns. The original function was written by Terry Therneau, but this is a new implementation using hashing that is much faster for large matrices. To sum over all the rows of a matrix (ie, a single group) use colSums, which should be even faster. For integer arguments, over/underflow in forming the sum results in NA. 438 sample Value A matrix or data frame containing the sums. There will be one row per unique value of group. See Also tapply, aggregate, rowSums Examples require(stats) x <- matrix(runif(100), ncol=5) group <- sample(1:8, 20, TRUE) (xsum <- rowsum(x, group)) ## Slower versions tapply(x, list(group[row(x)], col(x)), sum) t(sapply(split(as.data.frame(x), group), colSums)) aggregate(x, list(group), sum)[-1] sample Random Samples and Permutations Description sample takes a sample of the specified size from the elements of x using either with or without replacement. Usage sample(x, size, replace = FALSE, prob = NULL) sample.int(n, size = n, replace = FALSE, prob = NULL) Arguments x Either a vector of one or more elements from which to choose, or a positive integer. See ‘Details.’ n a positive number, the number of items to choose from. See ‘Details.’ size a non-negative integer giving the number of items to choose. replace Should sampling be with replacement? prob A vector of probability weights for obtaining the elements of the vector being sampled. sample 439 Details If x has length 1, is numeric (in the sense of is.numeric) and x >= 1, sampling via sample takes place from 1:x. Note that this convenience feature may lead to undesired behaviour when x is of varying length in calls such as sample(x). See the examples. Otherwise x can be any R object for which length and subsetting by integers make sense: S3 or S4 methods for these operations will be dispatched as appropriate. For sample the default for size is the number of items inferred from the first argument, so that sample(x) generates a random permutation of the elements of x (or 1:x). As from R 2.11.0 it is allowed to ask for size = 0 samples with n = 0 or a length-zero x, but otherwise n > 0 or positive length(x) is required. Non-integer positive numerical values of n or x will be truncated to the next smallest integer, which has to be no larger than .Machine$integer.max. The optional prob argument can be used to give a vector of weights for obtaining the elements of the vector being sampled. They need not sum to one, but they should be non-negative and not all zero. If replace is true, Walker’s alias method (Ripley, 1987) is used when there are more than 250 reasonably probable values: this gives results incompatible with those from R < 2.2.0, and there will be a warning the first time this happens in a session. If replace is false, these probabilities are applied sequentially, that is the probability of choosing the next item is proportional to the weights amongst the remaining items. The number of nonzero weights must be at least size in this case. sample.int is a bare interface in which both n and size must be supplied as integers. Value For sample a vector of length size with elements drawn from either x or from the integers 1:x. For sample.int, an integer vector of length size with elements from 1:n, References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Ripley, B. D. (1987) Stochastic Simulation. Wiley. See Also RNG about random number generation. CRAN package sampling for other methods of weighted sampling without replacement. Examples x <- 1:12 # a random permutation sample(x) # bootstrap resampling -- only if length(x) > 1 ! sample(x, replace=TRUE) 440 save # 100 Bernoulli trials sample(c(0,1), 100, replace = TRUE) ## More careful bootstrapping -- Consider this when using sample() ## programmatically (i.e., in your function or simulation)! # sample()’s surprise -- example x <- 1:10 sample(x[x > 8]) # length 2 sample(x[x > 9]) # oops -- length 10! sample(x[x > 10]) # length 0 ## For R >= 2.11.0 only resample <- function(x, ...) x[sample.int(length(x), ...)] resample(x[x > 8]) # length 2 resample(x[x > 9]) # length 1 resample(x[x > 10]) # length 0 save Save R Objects Description save writes an external representation of R objects to the specified file. The objects can be read back from the file at a later date by using the function load (or data in some cases). save.image() is just a short-cut for ‘save my current workspace’, i.e., save(list = ls(all=TRUE), file = ".RData"). It is also what happens with q("yes"). Usage save(..., list = character(), file = stop("’file’ must be specified"), ascii = FALSE, version = NULL, envir = parent.frame(), compress = !ascii, compression_level, eval.promises = TRUE, precheck = TRUE) save.image(file = ".RData", version = NULL, ascii = FALSE, compress = !ascii, safe = TRUE) Arguments ... the names of the objects to be saved (as symbols or character strings). list A character vector containing the names of objects to be saved. file a (writable binary-mode) connection or the name of the file where the data will be saved (when tilde expansion is done). Must be a file name for version = 1. ascii if TRUE, an ASCII representation of the data is written. The default value of ascii is FALSE which leads to a binary file being written. save 441 version the workspace format version to use. NULL specifies the current default format. The version used from R 0.99.0 to R 1.3.1 was version 1. The default format as from R 1.4.0 is version 2. envir environment to search for objects to be saved. compress logical or character string specifying whether saving to a named file is to use compression. TRUE corresponds to gzip compression, and (from R 2.10.0) char- acter strings "gzip","bzip2" or "xz" specify the type of compression. Ignored when file is a connection and for workspace format version 1. compression_level integer: the level of compression to be used. Defaults to 6 for gzip compression and to 9 for bzip2 or xz compression. eval.promises logical: should objects which are promises be forced before saving? precheck logical: should the existence of the objects be checked before starting to save (and in particular before opening the file/connection)? Does not apply to version 1 saves. safe logical. If TRUE, a temporary file is used for creating the saved workspace. The temporary file is renamed to file if the save succeeds. This preserves an ex- isting workspace file if the save fails, but at the cost of using extra disk space during the save. Details The names of the objects specified either as symbols (or character strings) in ... or as a character vector in list are used to look up the objects from environment envir. By default promises are evaluated, but if eval.promises = FALSE promises are saved (together with their evaluation environments). (Promises embedded in objects are always saved unevaluated.) All R platforms use the XDR (bigendian) representation of C ints and doubles in binary save-d files, and these are portable across all R platforms. (ASCII saves used to be useful for moving data between platforms but are now mainly of historical interest. They can be more compact than binary saves where compression is not used, but are almost always slower to both read and write: binary saves compress much better than ASCII ones.) Default values for the ascii, compress, safe and version arguments can be modified with the "save.defaults" option (used both by save and save.image), see also the ‘Examples’ section. If a "save.image.defaults" option is set it is used in preference to "save.defaults" for function save.image (which allows this to have different defaults). A connection that is not already open will be opened in mode "wb". Compression Large files can be reduced considerably in size by compression. A particular 46MB dataset was saved as 35MB without compression in 2 seconds, 22MB with gzip compression in 8 secs, 19MB with bzip2 compression in 13 secs and 9.4MB with xz compression in 40 secs. The load times were 1.3, 2.8, 5.5 and 5.7 seconds respectively. These results are indicative, but the relative performances do depend on the actual file and xz did unusually well here. It is possible to compress later (with gzip, bzip2 or xz) a file saved with compress = FALSE: the effect is the same as saving with compression. Also, a saved file can be uncompressed and 442 save re-compressed under a different compression scheme (and see resaveRdaFiles for a way to do so from within R). Warnings The ... arguments only give the names of the objects to be saved: they are searched for in the environment given by the envir argument, and the actual objects given as arguments need not be those found. Saved R objects are binary files, even those saved with ascii = TRUE, so ensure that they are transferred without conversion of end of line markers and of 8-bit characters. The lines are delimited by LF on all platforms. Although the default version has not changed since R 1.4.0, this does not mean that saved files are necessarily backwards compatible. You will be able to load a saved image into an earlier version of R unless use is made of later additions (for example, raw vectors or external pointers). Note The most common reason for failure is lack of write permission in the current directory. For save.image and for saving at the end of a session this will shown by messages like Error in gzfile(file, "wb") : unable to open connection In addition: Warning message: In gzfile(file, "wb") : cannot open compressed file ’.RDataTmp’, probable reason ’Permission denied’ The defaults were changed to use compressed saves for save in 2.3.0 and for save.image in 2.4.0. Any recent version of R can read compressed save files, and a compressed file can be uncompressed (by gzip -d) for use with very old versions of R. See Also dput, dump, load, data. For other interfaces to the underlying serialization format, see serialize and saveRDS. Examples x <- stats::runif(20) y <- list(a = 1, b = TRUE, c = "oops") save(x, y, file = "xy.RData") save.image() unlink("xy.RData") unlink(".RData") # set save defaults using option: options(save.defaults=list(ascii=TRUE, safe=FALSE)) save.image() unlink(".RData") scale 443 scale Scaling and Centering of Matrix-like Objects Description scale is generic function whose default method centers and/or scales the columns of a numeric matrix. Usage scale(x, center = TRUE, scale = TRUE) Arguments x a numeric matrix(like object). center either a logical value or a numeric vector of length equal to the number of columns of x. scale either a logical value or a numeric vector of length equal to the number of columns of x. Details The value of center determines how column centering is performed. If center is a numeric vector with length equal to the number of columns of x, then each column of x has the corresponding value from center subtracted from it. If center is TRUE then centering is done by subtracting the column means (omitting NAs) of x from their corresponding columns, and if center is FALSE, no centering is done. The value of scale determines how column scaling is performed (after centering). If scale is a numeric vector with length equal to the number of columns of x, then each column of x is divided by the corresponding value from scale. If scale is TRUE then scaling is done by dividing the (centered) columns of x by their standard deviations if center is TRUE, and the root mean square otherwise. If scale is FALSE, no scaling is done. The root-mean-square for a (possibly centered) column is defined as pP(x2)/(n − 1), where x is a vector of the non-missing values and n is the number of non-missing values. In the case center=TRUE, this is the same as the standard deviation, but in general it is not. (To scale by the standard deviations without centering, use scale(x,center=FALSE,scale=apply(x,2,sd,na.rm=TRUE)).) Value For scale.default, the centered, scaled matrix. The numeric centering and scalings used (if any) are returned as attributes "scaled:center" and "scaled:scale" References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. 444 scan See Also sweep which allows centering (and scaling) with arbitrary statistics. For working with the scale of a plot, see par. Examples require(stats) x <- matrix(1:10, ncol=2) (centered.x <- scale(x, scale=FALSE)) cov(centered.scaled.x <- scale(x))# all 1 scan Read Data Values Description Read data into a vector or list from the console or file. Usage scan(file = "", what = double(), nmax = -1, n = -1, sep = "", quote = if(identical(sep, "\n")) "" else "’\"", dec = ".", skip = 0, nlines = 0, na.strings = "NA", flush = FALSE, fill = FALSE, strip.white = FALSE, quiet = FALSE, blank.lines.skip = TRUE, multi.line = TRUE, comment.char = "", allowEscapes = FALSE, fileEncoding = "", encoding = "unknown", text) Arguments file the name of a file to read data values from. If the specified file is "", then input is taken from the keyboard (or whatever stdin() reads if input is redirected or R is embedded). (In this case input can be terminated by a blank line or an EOF signal, ‘Ctrl-D’ on Unix and ‘Ctrl-Z’ on Windows.) Otherwise, the file name is interpreted relative to the current working directory (given by getwd()), unless it specifies an absolute path. Tilde-expansion is performed where supported. When running R from a script, file="stdin" can be used to refer to the process’s stdin file stream. As from R 2.10.0 this can be a compressed file (see file). Alternatively, file can be a connection, which will be opened if necessary, and if so closed at the end of the function call. Whatever mode the connection is opened in, any of LF, CRLF or CR will be accepted as the EOL marker for a line and so will match sep = "\n". file can also be a complete URL. (For the supported URL schemes, see the ‘URLs’ section of the help for url.) To read a data file not in the current encoding (for example a Latin-1 file in a UTF-8 locale or conversely) use a file connection setting its encoding argu- ment (or scan’s fileEncoding argument). scan 445 what the type of what gives the type of data to be read. The supported types are logical, integer, numeric, complex, character, raw and list. If what is a list, it is assumed that the lines of the data file are records each containing length(what) items (‘fields’) and the list components should have elements which are one of the first six types listed or NULL, see section ‘Details’ below. nmax integer: the maximum number of data values to be read, or if what is a list, the maximum number of records to be read. If omitted or not positive or an invalid value for an integer (and nlines is not set to a positive value), scan will read to the end of file. n integer: the maximum number of data values to be read, defaulting to no limit. Invalid values will be ignored. sep by default, scan expects to read ‘white-space’ delimited input fields. Alterna- tively, sep can be used to specify a character which delimits fields. A field is always delimited by an end-of-line marker unless it is quoted. If specified this should be the empty character string (the default) or NULL or a character string containing just one single-byte character. quote the set of quoting characters as a single character string or NULL. In a multibyte locale the quoting characters must be ASCII (single-byte). dec decimal point character. This should be a character string containing just one single-byte character. (NULL and a zero-length character vector are also ac- cepted, and taken as the default.) skip the number of lines of the input file to skip before beginning to read data values. nlines if positive, the maximum number of lines of data to be read. na.strings character vector. Elements of this vector are to be interpreted as missing (NA) values. Blank fields are also considered to be missing values in logical, integer, numeric and complex fields. flush logical: if TRUE, scan will flush to the end of the line after reading the last of the fields requested. This allows putting comments after the last field, but precludes putting more that one record on a line. fill logical: if TRUE, scan will implicitly add empty fields to any lines with fewer fields than implied by what. strip.white vector of logical value(s) corresponding to items in the what argument. It is used only when sep has been specified, and allows the stripping of leading and trail- ing ‘white space’ from character fields (numeric fields are always stripped). Note: white space inside quoted strings is not stripped. If strip.white is of length 1, it applies to all fields; otherwise, if strip.white[i] is TRUE and the i-th field is of mode character (because what[i] is) then the leading and trailing unquoted white space from field i is stripped. quiet logical: if FALSE (default), scan() will print a line, saying how many items have been read. blank.lines.skip logical: if TRUE blank lines in the input are ignored, except when counting skip and nlines. 446 scan multi.line logical. Only used if what is a list. If FALSE, all of a record must appear on one line (but more than one record can appear on a single line). Note that using fill = TRUE implies that a record will be terminated at the end of a line. comment.char character: a character vector of length one containing a single character or an empty string. Use "" to turn off the interpretation of comments altogether (the default). allowEscapes logical. Should C-style escapes such as ‘\n’ be processed (the default) or read verbatim? Note that if not within quotes these could be interpreted as a delimiter (but not as a comment character). The escapes which are interpreted are the control characters ‘\a, \b, \f, \n, \r, \t, \v’ and octal and hexadecimal represen- tations like ‘\040’ and ‘\0x2A’. Any other escaped character is treated as itself, including backslash. Note that Unicode escapes (starting ‘\u’ or ‘\U’: see Quotes) are never processed. fileEncoding character string: if non-empty declares the encoding used on a file (not a con- nection nor the keyboard) so the character data can be re-encoded. See the ‘En- coding’ section of the help for file, and the ‘R Data Import/Export Manual’. encoding encoding to be assumed for input strings. If the value is "latin1" or "UTF-8" it is used to mark character strings as known to be in Latin-1 or UTF-8: it is not used to re-encode the input (see fileEncoding. See also ‘Details’. text character string: if file is not supplied and this is, then data are read from the value of text via a text connection. Details The value of what can be a list of types, in which case scan returns a list of vectors with the types given by the types of the elements in what. This provides a way of reading columnar data. If any of the types is NULL, the corresponding field is skipped (but a NULL component appears in the result). The type of what or its components can be one of the six atomic vector types or NULL (see is.atomic). ‘White space’ is defined for the purposes of this function as one or more contiguous characters from the set space, horizontal tab, carriage return and line feed. It does not include form feed or vertical tab, but in Latin-1 and Windows 8-bit locales ’space’ includes non-breaking space. Empty numeric fields are always regarded as missing values. Empty character fields are scanned as empty character vectors, unless na.strings contains "" when they are regarded as missing values. The allowed input for a numeric field is optional whitespace followed either NA or an optional sign followed by a decimal or hexadecimal constant (see NumericConstants), or NaN, Inf or infinity (ignoring case). Out-of-range values are recorded as Inf,-Inf or 0. For an integer field the allowed input is optional whitespace, followed by either NA or an optional sign and one or more digits (‘0-9’): all out-of-range values are converted to NA_integer_. If sep is the default (""), the character ‘\’ in a quoted string escapes the following character, so quotes may be included in the string by escaping them. If sep is non-default, the fields may be quoted in the style of ‘.csv’ files where separators inside quotes (” or "") are ignored and quotes may be put inside strings by doubling them. However, if sep = "\n" it is assumed by default that one wants to read entire lines verbatim. scan 447 Quoting is only interpreted in character fields and in NULL fields (which might be skipping character fields). Note that since sep is a separator and not a terminator, reading a file by scan("foo", sep="\n", blank.lines.skip=FALSE) will give an empty final line if the file ends in a linefeed and not if it does not. This might not be what you expected; see also readLines. If comment.char occurs (except inside a quoted character field), it signals that the rest of the line should be regarded as a comment and be discarded. Lines beginning with a comment character (possibly after white space with the default separator) are treated as blank lines. There is a line-length limit of 4095 bytes when reading from the console (which may impose a lower limit: see ‘An Introduction to R’). There is a check for a user interrupt every 1000 lines if what is a list, otherwise every 10000 items. If file is a character string and fileEncoding is non-default, or it it is a not-already-open connec- tion with a non-default encoding argument, the text is converted to UTF-8 and declared as such (and the encoding argument to scan is ignored). See the examples of readLines. Value if what is a list, a list of the same length and same names (as any) as what. Otherwise, a vector of the type of what. Character strings in the result will have a declared encoding if encoding is "latin1" or "UTF-8". Note The default for multi.line differs from S. To read one record per line, use flush = TRUE and multi.line = FALSE. (Note that quoted character strings can still include embedded newlines.) If number of items is not specified, the internal mechanism re-allocates memory in powers of two and so could use up to three times as much memory as needed. (It needs both old and new copies.) If you can, specify either n or nmax whenever inputting a large vector, and nmax or nlines when inputting a large list. Using scan on an open connection to read partial lines can lose chars: use an explicit separator to avoid this. Having nul bytes in fields (including ‘\0’ if allowEscapes = TRUE) may lead to interpretation of the field being terminated at the nul. They not normally present in text files – see readBin. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also read.table for more user-friendly reading of data matrices; readLines to read a file a line at a time. write. Quotes for the details of C-style escape sequences. readChar and readBin to read fixed or variable length character strings or binary representations of numbers a few at a time from a connection. 448 search Examples cat("TITLE extra line", "2 3 5 7", "11 13 17", file="ex.data", sep="\n") pp <- scan("ex.data", skip = 1, quiet= TRUE) scan("ex.data", skip = 1) scan("ex.data", skip = 1, nlines=1) # only 1 line after the skipped one scan("ex.data", what = list("","","")) # flush is F -> read "7" scan("ex.data", what = list("","",""), flush = TRUE) unlink("ex.data") # tidy up ## "inline" usage scan(text="1 2 3") search Give Search Path for R Objects Description Gives a list of attached packages (see library), and R objects, usually data.frames. Usage search() searchpaths() Value A character vector, starting with ".GlobalEnv", and ending with "package:base" which is R’s base package required always. searchpaths gives a similar character vector, with the entries for packages being the path to the package used to load the code. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (search.) Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. (searchPaths.) See Also .packages to list just the packages on search path. loadedNamespaces to list loaded namespaces. attach and detach to change the search path, objects to find R objects in there. seek 449 Examples search() searchpaths() seek Functions to Reposition Connections Description Functions to re-position connections. Usage seek(con, ...) ## S3 method for class ’connection’ seek(con, where = NA, origin = "start", rw = "", ...) isSeekable(con) truncate(con, ...) Arguments con a connection. where numeric. A file position (relative to the origin specified by origin), or NA. rw character. Empty or "read" or "write", partial matches allowed. origin character. One of "start","current","end": see ‘Details’. ... further arguments passed to or from other methods. Details seek with where = NA returns the current byte offset of a connection (from the beginning), and with a non-missing where argument the connection is re-positioned (if possible) to the specified position. isSeekable returns whether the connection in principle supports seek: currently only (possibly gz-compressed) file connections do. where is stored as a real but should represent an integer: non-integer values are likely to be trun- cated. Note that the possible values can exceed the largest representable number in an R integer on 64-bit builds, and on some 32-bit builds. File connections can be open for both writing/appending, in which case R keeps separate positions for reading and writing. Which seek refers to can be set by its rw argument: the default is the last mode (reading or writing) which was used. Most files are only opened for reading or writing and so default to that state. If a file is open for both reading and writing but has not been used, the default is to give the reading position (0). The initial file position for reading is always at the beginning. The initial position for writing is at the beginning of the file for modes "r+" and "r+b", otherwise at the end of the file. Some platforms 450 seq only allow writing at the end of the file in the append modes. (The reported write position for a file opened in an append mode will typically be unreliable until the file has been written to.) gzfile connections support seek with a number of limitations, using the file position of the un- compressed file. They do not support origin = "end". When writing, seeking is only possible forwards: when reading seeking backwards is supported by rewinding the file and re-reading from its start. If seek is called with a non-NA value of where, any pushback on a text-mode connection is dis- carded. truncate truncates a file opened for writing at its current position. It works only for file connec- tions, and is not implemented on all platforms: on others (including Windows) it will not work for large (> 2Gb) files. None of these should be expected to work on text-mode connections with re-encoding selected. Value seek returns the current position (before any move), as a (numeric) byte offset from the origin, if relevant, or 0 if not. Note that the position can exceed the largest representable number in an R integer on 64-bit builds, and on some 32-bit builds. truncate returns NULL: it stops with an error if it fails (or is not implemented). isSeekable returns a logical value, whether the connection supports seek. Warning Use of seek on Windows is discouraged. We have found so many errors in the Windows imple- mentation of file positioning that users are advised to use it only at their own risk, and asked not to waste the R developers’ time with bug reports on Windows’ deficiencies. See Also connections seq Sequence Generation Description Generate regular sequences. seq is a standard generic with a default method. seq.int is a primitive which can be much faster but has a few restrictions. seq_along and seq_len are very fast primitives for two common cases. seq 451 Usage seq(...) ## Default S3 method: seq(from = 1, to = 1, by = ((to - from)/(length.out - 1)), length.out = NULL, along.with = NULL, ...) seq.int(from, to, by, length.out, along.with, ...) seq_along(along.with) seq_len(length.out) Arguments ... arguments passed to or from methods. from, to the starting and (maximal) end value of the sequence. by number: increment of the sequence. length.out desired length of the sequence. A non-negative number, which for seq and seq.int will be rounded up if fractional. along.with take the length from the length of this argument. Details The interpretation of the unnamed arguments of seq and seq.int is not standard, and it is recom- mended always to name the arguments when programming. seq is generic, and only the default method is described here. Note that it dispatches on the class of the first argument irrespective of argument names. This can have unintended consequences if it is called with just one argument intending this to be taken as along.with: it is much better to use seg_along in that case. seq.int is an internal generic which dispatches on methods for "seq" based on the class of the first supplied argument (before argument matching). Typical usages are seq(from, to) seq(from, to, by= ) seq(from, to, length.out= ) seq(along.with= ) seq(from) seq(length.out= ) The first form generates the sequence from, from+/-1, ..., to (identical to from:to). The second form generates from, from+by, . . . , up to the sequence value less than or equal to to. Specifying to - from and by of opposite signs is an error. Note that the computed final value can go just beyond to to allow for rounding error, but is truncated to to. (‘Just beyond’ is by up to 10−10 times abs(from - to).) 452 seq The third generates a sequence of length.out equally spaced values from from to to.(length.out is usually abbreviated to length or len, and seq_len is much faster.) The fourth form generates the integer sequence 1, 2, ..., length(along.with).(along.with is usually abbreviated to along, and seq_along is much faster.) The fifth form generates the sequence 1, 2, ..., length(from) (as if argument along.with had been specified), unless the argument is numeric of length 1 when it is interpreted as 1:from (even for seq(0) for compatibility with S). Using either seq_along or seq_len is much preferred (unless strict S compatibility is essential). The final form generates the integer sequence 1, 2, ..., length.out unless length.out = 0, when it generates integer(0). Very small sequences (with from - to of the order of 10−14 times the larger of the ends) will return from. For seq (only), up to two of from, to and by can be supplied as complex values provided length.out or along.with is specified. More generally, the default method of seq will handle classed objects with methods for the Math, Ops and Summary group generics. seq.int, seq_along and seq_len are primitive. Value seq.int and the default method of seq for numeric arguments return a vector of type "integer" or "double": programmers should not rely on which. seq_along and seq_len always return an integer vector. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also The methods seq.Date and seq.POSIXt. :, rep, sequence, row, col. Examples seq(0, 1, length.out=11) seq(stats::rnorm(20)) # effectively ’along’ seq(1, 9, by = 2) # matches ’end’ seq(1, 9, by = pi) # stays below ’end’ seq(1, 6, by = 3) seq(1.575, 5.125, by=0.05) seq(17) # same as 1:17, or even better seq_len(17) seq.Date 453 seq.Date Generate Regular Sequences of Dates Description The method for seq for objects of class class "Date" representing calendar dates. Usage ## S3 method for class ’Date’ seq(from, to, by, length.out = NULL, along.with = NULL, ...) Arguments from starting date. Required to end date. Optional. by increment of the sequence. Optional. See ‘Details’. length.out integer, optional. Desired length of the sequence. along.with take the length from the length of this argument. ... arguments passed to or from other methods. Details by can be specified in several ways. • A number, taken to be in days. • A object of class difftime • A character string, containing one of "day","week","month" or "year". This can optionally be preceded by a (positive or negative) integer and a space, or followed by "s". See seq.POSIXt for the details of "month". Value A vector of class "Date". See Also Date 454 seq.POSIXt Examples ## first days of years seq(as.Date("1910/1/1"), as.Date("1999/1/1"), "years") ## by month seq(as.Date("2000/1/1"), by="month", length.out=12) ## quarters seq(as.Date("2000/1/1"), as.Date("2003/1/1"), by="3 months") ## find all 7th of the month between two dates, the last being a 7th. st <- as.Date("1998-12-17") en <- as.Date("2000-1-7") ll <- seq(en, st, by="-1 month") rev(ll[ll > st & ll < en]) seq.POSIXt Generate Regular Sequences of Times Description The method for seq for date-time classes. Usage ## S3 method for class ’POSIXt’ seq(from, to, by, length.out = NULL, along.with = NULL, ...) Arguments from starting date. Required. to end date. Optional. by increment of the sequence. Optional. See ‘Details’. length.out integer, optional. Desired length of the sequence. along.with take the length from the length of this argument. ... arguments passed to or from other methods. Details by can be specified in several ways. • A number, taken to be in seconds. • A object of class difftime • A character string, containing one of "sec","min","hour","day","DSTday","week", "month" or "year". This can optionally be preceded by a (positive or negative) integer and a space, or followed by "s". sequence 455 The difference between "day" and "DSTday" is that the former ignores changes to/from daylight savings time and the latter takes the same clock time each day. ("week" ignores DST (it is a period of 144 hours), but "7 DSTdays") can be used as an alternative. "month" and "year" allow for DST.) The timezone of the result is taken from from: remember that GMT means UTC (and not the timezone of Greenwich, England) and so does not have daylight savings time. Using "month" first advances the month without changing the day: if this results in an invalid day of the month, it is counted forward into the next month: see the examples. Value A vector of class "POSIXct". See Also DateTimeClasses Examples ## first days of years seq(ISOdate(1910,1,1), ISOdate(1999,1,1), "years") ## by month seq(ISOdate(2000,1,1), by = "month", length.out = 12) seq(ISOdate(2000,1,31), by = "month", length.out = 4) ## quarters seq(ISOdate(1990,1,1), ISOdate(2000,1,1), by = "3 months") ## days vs DSTdays: use c() to lose the timezone. seq(c(ISOdate(2000,3,20)), by = "day", length.out = 10) seq(c(ISOdate(2000,3,20)), by = "DSTday", length.out = 10) seq(c(ISOdate(2000,3,20)), by = "7 DSTdays", length.out = 4) sequence Create A Vector of Sequences Description For each element of nvec the sequence seq_len(nvec[i]) is created. These are concatenated and the result returned. Usage sequence(nvec) Arguments nvec a non-negative integer vector each element of which specifies the end point of a sequence. 456 serialize Details Earlier versions of sequence used to work for 0 or negative inputs as seq(x) == 1:x. Note that sequence <- function(nvec) unlist(lapply(nvec, seq_len)) and it mainly exists in reverence to the very early history of R. See Also gl, seq, rep. Examples sequence(c(3,2))# the concatenated sequences 1:3 and 1:2. #> [1] 1 2 3 1 2 serialize Simple Serialization Interface Description A simple low-level interface for serializing to connections. Usage serialize(object, connection, ascii, version = NULL, refhook = NULL) unserialize(connection, refhook = NULL) Arguments object R object to serialize. connection an open connection or (for serialize) NULL or (for unserialize) a raw vector (see ‘Details’). ascii a logical. If TRUE, an ASCII representation is written; otherwise binary one. The default is TRUE for a text-mode connection and FALSE otherwise. See also the comments in the help for save. version the workspace format version to use. NULL specifies the current default version (2). Versions prior to 2 are not supported, so this will only be relevant when there are later versions. refhook a hook function for handling reference objects. serialize 457 Details The function serialize serializes object to the specified connection. If connection is NULL then object is serialized to a raw vector, which is returned as the result of serialize. Sharing of reference objects is preserved within the object but not across separate calls to serialize. unserialize reads an object (as written by serialize) from connection or a raw vector. The refhook functions can be used to customize handling of non-system reference objects (all external pointers and weak references, and all environments other than namespace and package environments and .GlobalEnv). The hook function for serialize should return a character vector for references it wants to handle; otherwise it should return NULL. The hook for unserialize will be called with character vectors supplied to serialize and should return an appropriate object. For a text-mode connection, the default value of ascii is set to TRUE: only ASCII representations can be written to text-mode connections and attempting to use ascii = FALSE will throw an error. The format consists of a single line followed by the data: the first line contains a single character: X for binary serialization and A for ASCII serialization, followed by a new line. (The format used is identical to that used by readRDS.) Value For serialize, NULL unless connection = NULL, when the result is returned in a raw vector. For unserialize an R object. Warning These functions have provided a stable interface since R 2.4.0 (when the storage of serialized objects was changed from character to raw vectors). However, the serialization format may change in future versions of R, so this interface should not be used for long-term storage of R objects. A raw vector is limited to 231 − 1 bytes, but R objects can exceed this and their serializations will normally be larger than the objects. See Also saveRDS for a more convenient interface to serialize an object to a file or connection. save and load to serialize and restore one or more named objects. The ‘R Internals’ manual for details of the format used. Examples x <- serialize(list(1,2,3), NULL) unserialize(x) ## see also the examples for saveRDS 458 sets sets Set Operations Description Performs set union, intersection, (asymmetric!) difference, equality and membership on two vec- tors. Usage union(x, y) intersect(x, y) setdiff(x, y) setequal(x, y) is.element(el, set) Arguments x, y, el, set vectors (of the same mode) containing a sequence of items (conceptually) with no duplicated values. Details Each of union, intersect, setdiff and setequal will discard any duplicated values in the argu- ments, and they apply as.vector to their arguments (and so in particular coerce factors to character vectors). is.element(x, y) is identical to x %in% y. Value A vector of the same mode as x or y for setdiff and intersect, respectively, and of a common mode for union. A logical scalar for setequal and a logical of the same length as x for is.element. See Also %in% ‘plotmath’ for the use of union and intersect in plot annotation. Examples (x <- c(sort(sample(1:20, 9)),NA)) (y <- c(sort(sample(3:23, 7)),NA)) union(x, y) intersect(x, y) setdiff(x, y) setTimeLimit 459 setdiff(y, x) setequal(x, y) ## True for all possible x & y : setequal( union(x,y), c(setdiff(x,y), intersect(x,y), setdiff(y,x))) is.element(x, y)# length 10 is.element(y, x)# length 8 setTimeLimit Set CPU and/or Elapsed Time Limits Description Functions to set CPU and/or elapsed time limits for top-level computations or the current session. Usage setTimeLimit(cpu = Inf, elapsed = Inf, transient = FALSE) setSessionTimeLimit(cpu = Inf, elapsed = Inf) Arguments cpu double. Limit on total cpu time. elapsed double. Limit on elapsed time. transient logical. If TRUE, the limits apply only to the rest of the current computation. Details setTimeLimit sets limits which apply to each top-level computation, that is a command line (in- cluding any continuation lines) entered at the console or from a file. If it is called from within a computation the limits apply to the rest of the computation and (unless transient = TRUE) to subsequent top-level computations. setSessionTimeLimit sets limits for the rest of the session. Once a session limit is reached it is reset to Inf. Setting any limit has a small overhead – well under 1% on the systems measured. Time limits are checked whenever a user interrupt could occur. This will happen frequently in R code and during Sys.sleep, but only at points in compiled C and Fortran code identified by the code author. ‘Total cpu time’ includes that used by child processes where the latter is reported. 460 showConnections showConnections Display Connections Description Display aspects of connections. Usage showConnections(all = FALSE) getConnection(what) closeAllConnections() stdin() stdout() stderr() isatty(con) Arguments all logical: if true all connections, including closed ones and the standard ones are displayed. If false only open user-created connections are included. what integer: a row number of the table given by showConnections. con a connection. Details stdin(), stdout() and stderr() are standard connections corresponding to input, output and error on the console respectively (and not necessarily to file streams). They are text-mode connec- tions of class "terminal" which cannot be opened or closed, and are read-only, write-only and write-only respectively. The stdout() and stderr() connections can be re-directed by sink (and in some circumstances the output from stdout() can be split: see the help page). The encoding for stdin() when redirected can be set by the command-line flag ‘--encoding’. showConnections returns a matrix of information. If a connection object has been lost or forgotten, getConnection will take a row number from the table and return a connection object for that connection, which can be used to close the connection, for example. However, if there is no R level object referring to the connection it will be closed automatically at the next garbage collection. closeAllConnections closes (and destroys) all user connections, restoring all sink diversions as it does so. isatty returns true if the connection is one of the class "terminal" connections and it is appar- ently connected to a terminal, otherwise false. This may not be reliable in embedded applications, including GUI consoles. shQuote 461 Value stdin(), stdout() and stderr() return connection objects. showConnections returns a character matrix of information with a row for each connection, by default only for open non-standard connections. getConnection returns a connection object, or NULL. Note stdin() refers to the ‘console’ and not to the C-level ‘stdin’ of the process. The distinction matters in GUI consoles (which may not have an active ‘stdin’, and if they do it may not be connected to console input), and also in embedded applications. If you want access to the C-level file stream ‘stdin’, use file("stdin"). When R is reading a script from a file, the file is the ‘console’: this is traditional usage to allow in-line data (see ‘An Introduction to R’ for an example). See Also connections Examples showConnections(all = TRUE) textConnection(letters) # oops, I forgot to record that one showConnections() # class description mode text isopen can read can write #3 "letters" "textConnection" "r" "text" "opened" "yes" "no" ## Not run: close(getConnection(3)) showConnections() c(isatty(stdin()), isatty(stdout()), isatty(stderr())) shQuote Quote Strings for Use in OS Shells Description Quote a string to be passed to an operating system shell. Usage shQuote(string, type = c("sh", "csh", "cmd")) 462 shQuote Arguments string a character vector, usually of length one. type character: the type of shell. Partial matching is supported. "cmd" refers to the Windows NT shell, and is the default under Windows. Details The default type of quoting supported under Unix-alikes is that for the Bourne shell sh. If the string does not contain single quotes, we can just surround it with single quotes. Otherwise, the string is surrounded in double quotes, which suppresses all special meanings of metacharacters except dollar, backquote and backslash, so these (and of course double quote) are preceded by backslash. This type of quoting is also appropriate for bash, ksh and zsh. The other type of quoting is for the C-shell (csh and tcsh). Once again, if the string does not contain single quotes, we can just surround it with single quotes. If it does contain single quotes, we can use double quotes provided it does not contain dollar or backquote (and we need to escape backslash, exclamation mark and double quote). As a last resort, we need to split the string into pieces not containing single quotes and surround each with single quotes, and the single quotes with double quotes. References Loukides, M. et al (2002) Unix Power Tools Third Edition. O’Reilly. Section 27.12. http://www.mhuffman.com/notes/dos/bash_cmd.htm See Also Quotes for quoting R code. sQuote for quoting English text. Examples test <- "abc$def‘gh‘i\\j" cat(shQuote(test), "\n") ## Not run: system(paste("echo", shQuote(test))) test <- "don’t do it!" cat(shQuote(test), "\n") tryit <- paste("use the", sQuote("-c"), "switch\nlike this") cat(shQuote(tryit), "\n") ## Not run: system(paste("echo", shQuote(tryit))) cat(shQuote(tryit, type="csh"), "\n") ## Windows-only example. perlcmd <- ’print "Hello World\n";’ ## Not run: shell(paste("perl -e", shQuote(perlcmd, type="cmd"))) sign 463 sign Sign Function Description sign returns a vector with the signs of the corresponding elements of x (the sign of a real number is 1, 0, or −1 if the number is positive, zero, or negative, respectively). Note that sign does not operate on complex vectors. Usage sign(x) Arguments x a numeric vector Details This is an internal generic primitive function: methods can be defined for it directly or via the Math group generic. See Also abs Examples sign(pi) # == 1 sign(-2:3)# -1 -1 0 1 1 1 Signals Interrupting Execution of R Description On receiving SIGUSR1 R will save the workspace and quit. SIGUSR2 has the same result except that the .Last function and on.exit expressions will not be called. Usage kill -USR1 pid kill -USR2 pid 464 sink Arguments pid The process ID of the R process Warning It is possible that one or more R objects will be undergoing modification at the time the signal is sent. These objects could be saved in a corrupted form. sink Send R Output to a File Description sink diverts R output to a connection. sink.number() reports how many diversions are in use. sink.number(type = "message") reports the number of the connection currently being used for error messages. Usage sink(file = NULL, append = FALSE, type = c("output", "message"), split = FALSE) sink.number(type = c("output", "message")) Arguments file a writable connection or a character string naming the file to write to, or NULL to stop sink-ing. append logical. If TRUE, output will be appended to file; otherwise, it will overwrite the contents of file. type character. Either the output stream or the messages stream. split logical: if TRUE, output will be sent to the new sink and to the current output stream, like the Unix program tee. Details sink diverts R output to a connection. If file is a character string, a file connection with that name will be established for the duration of the diversion. Normal R output (to connection stdout) is diverted by the default type = "output". Only prompts and (most) messages continue to appear on the console. Messages sent to stderr() (including those from message, warning and stop) can be diverted by sink(type = "message") (see below). sink() or sink(file=NULL) ends the last diversion (of the specified type). There is a stack of diversions for normal output, so output reverts to the previous diversion (if there was one). The stack is of up to 21 connections (20 diversions). sink 465 If file is a connection it will be opened if necessary (in "wt" mode) and closed once it is removed from the stack of diversions. split = TRUE only splits R output (via Rvprintf) and the default output from writeLines: it does not split all output that might be sent to stdout(). Sink-ing the messages stream should be done only with great care. For that stream file must be an already open connection, and there is no stack of connections. If file is a character string, the file will be opened using the current encoding. If you want a differ- ent encoding (e.g. to represent strings which have been stored in UTF-8), use a file connection — but some ways to produce R output will already have converted such strings to the current encoding. Value sink returns NULL. For sink.number() the number (0, 1, 2, . . . ) of diversions of output in place. For sink.number("message") the connection number used for messages, 2 if no diversion has been used. Warning Do not use a connection that is open for sink for any other purpose. The software will stop you closing one such inadvertently. Do not sink the messages stream unless you understand the source code implementing it and hence the pitfalls. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. See Also capture.output Examples sink("sink-examp.txt") i <- 1:10 outer(i, i, "*") sink() unlink("sink-examp.txt") ## Not run: ## capture all the output to a file. zz <- file("all.Rout", open="wt") sink(zz) sink(zz, type="message") try(log("a")) ## back to the console 466 slice.index sink(type="message") sink() try(log("a")) ## End(Not run) slice.index Slice Indexes in an Array Description Returns a matrix of integers indicating the number of their slice in a given array. Usage slice.index(x, MARGIN) Arguments x an array. If x has no dimension attribute, it is considered a one-dimensional array. MARGIN an integer giving the dimension number to slice by. Value An integer array y with dimensions corresponding to those of x such that all elements of slice number i with respect to dimension MARGIN have value i. See Also row and col for determining row and column indexes; in fact, these are special cases of slice.index corresponding to MARGIN equal to 1 and 2, respectively when x is a matrix. Examples x <- array(1 : 24, c(2, 3, 4)) slice.index(x, 2) slotOp 467 slotOp Extract Slots Description Extract the contents of a slot in a object with a formal (S4) class structure. Usage object@name Arguments object An object from a formally defined (S4) class. name The character-string name of the slot. Details This operator supports the formal classes of package methods, and is enabled only when methods is loaded (as per default). See slot for further details. It is checked that object is an S4 object (see isS4), and it is an error to attempt to use @ on any other object. (There is an exception for name .Data for internal use only.) If name is not a slot name, an error is thrown. Value The current contents of the slot. See Also Extract, slot socketSelect Wait on Socket Connections Description Waits for the first of several socket connections to become available. Usage socketSelect(socklist, write = FALSE, timeout = NULL) 468 solve Arguments socklist list of open socket connections write logical. If TRUE wait for corresponding socket to become available for writing; otherwise wait for it to become available for reading. timeout numeric or NULL. Time in seconds to wait for a socket to become available; NULL means wait indefinitely. Details The values in write are recycled if necessary to make up a logical vector the same length as socklist. Socket connections can appear more than once in socklist; this can be useful if you want to determine whether a socket is available for reading or writing. Value Logical the same length as socklist indicating whether the corresponding socket connection is available for output or input, depending on the corresponding value of write. Examples ## Not run: ## test whether socket connection s is available for writing or reading socketSelect(list(s,s),c(TRUE,FALSE),timeout=0) ## End(Not run) solve Solve a System of Equations Description This generic function solves the equation a %*% x = b for x, where b can be either a vector or a matrix. Usage solve(a, b, ...) ## Default S3 method: solve(a, b, tol, LINPACK = FALSE, ...) solve 469 Arguments a a square numeric or complex matrix containing the coefficients of the linear system. b a numeric or complex vector or matrix giving the right-hand side(s) of the linear system. If missing, b is taken to be an identity matrix and solve will return the inverse of a. tol the tolerance for detecting linear dependencies in the columns of a. If LINPACK is TRUE the default is 1e-7, otherwise it is .Machine$double.eps. Future versions of R may use a tighter tolerance. Not currently used with complex matrices a. LINPACK logical. Should LINPACK be used (for compatibility with R < 1.7.0)? Other- wise LAPACK is used. ... further arguments passed to or from other methods Details a or b can be complex, but this uses double complex arithmetic which might not be available on all platforms and LAPACK will always be used. The row and column names of the result are taken from the column names of a and of b respectively. If b is missing the column names of the result are the row names of a. No check is made that the column names of a and the row names of b are equal. For back-compatibility a can be a (real) QR decomposition, although qr.solve should be called in that case. qr.solve can handle non-square systems. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also solve.qr for the qr method, chol2inv for inverting from the Choleski factor backsolve, qr.solve. Examples hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") } h8 <- hilbert(8); h8 sh8 <- solve(h8) round(sh8 %*% h8, 3) A <- hilbert(4) A[] <- as.complex(A) ## might not be supported on all platforms try(solve(A)) 470 sort sort Sorting or Ordering Vectors Description Sort (or order) a vector or factor (partially) into ascending or descending order. For ordering along more than one variable, e.g., for sorting data frames, see order. Usage sort(x, decreasing = FALSE, ...) ## Default S3 method: sort(x, decreasing = FALSE, na.last = NA, ...) sort.int(x, partial = NULL, na.last = NA, decreasing = FALSE, method = c("shell", "quick"), index.return = FALSE) Arguments x for sort an R object with a class or a numeric, complex, character or logical vector. For sort.int, a numeric, complex, character or logical vector, or a factor. decreasing logical. Should the sort be increasing or decreasing? Not available for partial sorting. ... arguments to be passed to or from methods or (for the default methods and objects without a class) to sort.int. na.last for controlling the treatment of NAs. If TRUE, missing values in the data are put last; if FALSE, they are put first; if NA, they are removed. partial NULL or an integer vector of indices for partial sorting. method character string specifying the algorithm used. Not available for partial sorting. index.return logical indicating if the ordering index vector should be returned as well; this is only available for a few cases, the default na.last = NA and full sorting of non-factors. Details sort is a generic function for which methods can be written, and sort.int is the internal method which is compatible with S if only the first three arguments are used. The default sort method makes use of order for classed objects, which in turn makes use of the generic function xtfrm (and can be slow unless a xtfrm method has been defined unless is.numeric(x) is true). If partial is not NULL, it is taken to contain indices of elements of the result which are to be placed in their correct positions in the sorted array by partial sorting. For each of the result values in a specified position, any values smaller than that one are guaranteed to have a smaller index in the sort 471 sorted array and any values which are greater are guaranteed to have a bigger index in the sorted array. (This is included for efficiency, and many of the options are not available for partial sorting. It is only substantially more efficient if partial has a handful of elements, and a full sort is done (a quick sort if possible) if there are more than 10.) Names are discarded for partial sorting. Complex values are sorted first by the real part, then the imaginary part. The sort order for character vectors will depend on the collating sequence of the locale in use: see Comparison. The sort order for factors is the order of their levels (which is particularly appropriate for ordered factors). Method "shell" uses Shellsort (an O(n4/3) variant from Sedgewick (1996)). If x has names a stable sort is used, so ties are not reordered. (This only matters if names are present.) Method "quick" uses Singleton’s Quicksort implementation and is only available when x is nu- meric (double or integer) and partial is NULL. (For other types of x Shellsort is used, silently.) It is normally somewhat faster than Shellsort (perhaps twice as fast on vectors of length a million) but has poor performance in the rare worst case. (Peto’s modification using a pseudo-random midpoint is used to make the worst case rarer.) This is not a stable sort, and ties may be reordered. Value For sort, the result depends on the S3 method which is dispatched. If x does not have a class the rest of this section applies. For classed objects which do not have a specific method the default method will be used and is equivalent to x[order(x, ...)]: this depends on the class having a suitable method for [(and also that order will work, which is not the case for a class based on a list). For sort.int the value is the sorted vector unless index.return is true, when the result is a list with components named x and ix containing the sorted numbers and the ordering index vector. In the latter case, if method == "quick" ties may be reversed in the ordering, unlike sort.list, as quicksort is not stable. NB: the index vector refers to element numbers after removal of NAs. All attributes are removed from the return value (see Becker et al, 1988, p.146) except names, which are sorted. (If partial is specified even the names are removed.) Note that this means that the returned value has no class, except for factors and ordered factors (which are treated specially and whose result is transformed back to the original class). References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Sedgewick, R. (1986) A new upper bound for Shell sort. J. Algorithms 7, 159–173. Singleton, R. C. (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347. Communications of the ACM 12, 185–187. See Also ‘Comparison’ for how character strings are collated. order for sorting on or reordering multiple variables. is.unsorted. rank. 472 source Examples require(stats) x <- swiss$Education[1:25] x; sort(x); sort(x, partial = c(10, 15)) median.default # shows you another example for ’partial’ ## illustrate ’stable’ sorting (of ties): sort(c(10:3,2:12), method = "sh", index.return=TRUE) # is stable ## $x : 2 3 3 4 4 5 5 6 6 7 7 8 8 9 9 10 10 11 12 ## $ix: 9 8 10 7 11 6 12 5 13 4 14 3 15 2 16 1 17 18 19 sort(c(10:3,2:12), method = "qu", index.return=TRUE) # is not ## $x : 2 3 3 4 4 5 5 6 6 7 7 8 8 9 9 10 10 11 12 ## $ix: 9 10 8 7 11 6 12 5 13 4 14 3 15 16 2 17 1 18 19 ## ^^^^^ x <- c(1:3, 3:5, 10) is.unsorted(x) # FALSE: is sorted is.unsorted(x, strictly=TRUE) # TRUE : is not (and cannot be) # sorted strictly ## Not run: ## Small speed comparison simulation: N <- 2000 Sim <- 20 rep <- 1000 # << adjust to your CPU c1 <- c2 <- numeric(Sim) for(is in 1:Sim){ x <- rnorm(N) c1[is] <- system.time(for(i in 1:rep) sort(x, method = "shell"))[1] c2[is] <- system.time(for(i in 1:rep) sort(x, method = "quick"))[1] stopifnot(sort(x, method = "s") == sort(x, method = "q")) } rbind(ShellSort = c1, QuickSort = c2) cat("Speedup factor of quick sort():\n") summary({qq <- c1 / c2; qq[is.finite(qq)]}) ## A larger test x <- rnorm(1e7) system.time(x1 <- sort(x, method = "shell")) system.time(x2 <- sort(x, method = "quick")) stopifnot(identical(x1, x2)) ## End(Not run) source Read R Code from a File or a Connection Description source causes R to accept its input from the named file or URL or connection. Input is read and parsed from that file until the end of the file is reached, then the parsed expressions are evaluated source 473 sequentially in the chosen environment. Usage source(file, local = FALSE, echo = verbose, print.eval = echo, verbose = getOption("verbose"), prompt.echo = getOption("prompt"), max.deparse.length = 150, chdir = FALSE, encoding = getOption("encoding"), continue.echo = getOption("continue"), skip.echo = 0, keep.source = getOption("keep.source")) Arguments file a connection or a character string giving the pathname of the file or URL to read from. "" indicates the connection stdin(). local TRUE, FALSE or an environment, determining where the parsed expressions are evaluated. TRUE corresponds to the user’s workspace (the global environment) and FALSE to the environment from source is called. echo logical; if TRUE, each expression is printed after parsing, before evaluation. print.eval logical; if TRUE, the result of eval(i) is printed for each expression i; defaults to the value of echo. verbose if TRUE, more diagnostics (than just echo = TRUE) are printed during parsing and evaluation of input, including extra info for each expression. prompt.echo character; gives the prompt to be used if echo = TRUE. max.deparse.length integer; is used only if echo is TRUE and gives the maximal number of characters output for the deparse of a single expression. chdir logical; if TRUE and file is a pathname, the R working directory is temporarily changed to the directory containing file for evaluating. encoding character vector. The encoding(s) to be assumed when file is a character string: see file. A possible value is "unknown" when the encoding is guessed: see the ‘Encodings’ section. continue.echo character; gives the prompt to use on continuation lines if echo = TRUE. skip.echo integer; how many comment lines at the start of the file to skip if echo = TRUE. keep.source logical: should the source formatting be retained when echoing expressions, if possible? Details Note that running code via source differs in a few respects from entering it at the R command line. Since expressions are not executed at the top level, auto-printing is not done. So you will need to include explicit print calls for things you want to be printed (and remember that this includes plotting by lattice, FAQ Q7.22). Since the complete file is parsed before any of it is run, syntax errors result in none of the code being run. If an error occurs in running a syntactically correct script, anything assigned into the workspace by code that has been run will be kept (just as from 474 source the command line), but diagnostic information such as traceback() will contain additional calls to eval.with.vis, an undocumented internal function. All versions of R accept input from a connection with end of line marked by LF (as used on Unix), CRLF (as used on DOS/Windows) or CR (as used on classic Mac OS) and map this to newline. The final line can be incomplete, that is missing the final end-of-line marker. If keep.source is true (the default in interactive use), the source of functions is kept so they can be listed exactly as input. Unlike input from a console, lines in the file or on a connection can contain an unlimited number of characters. When skip.echo > 0, that many comment lines at the start of the file will not be echoed. This does not affect the execution of the code at all. If there are executable lines within the first skip.echo lines, echoing will start with the first of them. If echo is true and a deparsed expression exceeds max.deparse.length, that many characters are output followed by .... [TRUNCATED] . Encodings By default the input is read and parsed in the current encoding of the R session. This is usually what it required, but occasionally re-encoding is needed, e.g. if a file from a UTF-8-using system is to be read on Windows (or vice versa). The rest of this paragraph applies if file is an actual filename or URL (and not "" nor a con- nection). If encoding = "unknown", an attempt is made to guess the encoding: the result of localeToCharset() is used as a guide. If encoding has two or more elements, they are tried in turn until the file/URL can be read without error in the trial encoding. If an actual encoding is specified (rather than the default or "unknown") in a Latin-1 or UTF-8 locale then character strings in the result will be translated to the current encoding and marked as such (see Encoding). If file is a connection (including one specified by "", it is not possible to re-encode the input inside source, and so the encoding argument is just used to mark character strings in the parsed input in Latin-1 and UTF-8 locales: see parse. References Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. See Also demo which uses source; eval, parse and scan; options("keep.source"). sys.source which is a streamlined version to source a file into an environment. ‘The R Language Definition’ for a discussion of source directives. Examples ## If you want to source() a bunch of files, something like ## the following may be useful: sourceDir <- function(path, trace = TRUE, ...) { for (nm in list.files(path, pattern = "\\.[RrSsQq]$")) { Special 475 if(trace) cat(nm,":") source(file.path(path, nm), ...) if(trace) cat("\n") } } Special Special Functions of Mathematics Description Special mathematical functions related to the beta and gamma functions. Usage beta(a, b) lbeta(a, b) gamma(x) lgamma(x) psigamma(x, deriv = 0) digamma(x) trigamma(x) choose(n, k) lchoose(n, k) factorial(x) lfactorial(x) Arguments a, b non-negative numeric vectors. x, n numeric vectors. k, deriv integer vectors. Details The functions beta and lbeta return the beta function and the natural logarithm of the beta function, B(a, b) = Γ(a)Γ(b) Γ(a + b). The formal definition is B(a, b) = Z 1 0 ta−1(1 − t)b−1dt (Abramowitz and Stegun section 6.2.1, page 258). Note that it is only defined in R for non-negative a and b, and is infinite if either is zero. 476 Special The functions gamma and lgamma return the gamma function Γ(x) and the natural logarithm of the absolute value of the gamma function. The gamma function is defined by (Abramowitz and Stegun section 6.1.1, page 255) Γ(x) = Z ∞ 0 tx−1e−tdt for all real x except zero and negative integers (when NaN is re