Description

Base R functions

Details

This package contains the basic functions which letRfunction as a language: arithmetic, input/output, basicprogramming support, etc. Its contents are available throughinheritance from any environment.

For a complete list of functions, uselibrary(help = "base").

Description

Bin a numeric vector and return integer codes for the binning.

Usage

.bincode(x, breaks, right=TRUE, include.lowest=FALSE)

Arguments

Details

This is a ‘barebones’ version ofcut.default(labels = FALSE) intended for use in other functions which have checked thearguments passed. (Note the different order of the arguments they havein common.)

Unlikecut, thebreaks do not need to be unique.An input can only fall into a zero-length interval if it is closedat both ends, so only ifinclude.lowest = TRUE and it is thefirst (or last forright = FALSE) interval.

Value

An integer vector of the same length asx indicating which bineach element falls into (the leftmost bin being bin1).NaN andNA elements ofx are mapped toNA codes, as are values outside range ofbreaks.

See Also

cut,tabulate

Examples

## An example with non-unique breaks:x<- c(0,0.01,0.5,0.99,1)b<- c(0,0,1,1).bincode(x, b,TRUE).bincode(x, b,FALSE).bincode(x, b,TRUE,TRUE).bincode(x, b,FALSE,TRUE)

Description

A pairlist of the names of open graphics devices is stored in.Devices. The name of the active device (seedev.cur) is stored in.Device. Both are symbolsand so appear in the base namespace.

Usage

.Device.Devices

Details

.Device is a length-one character vector.

.Devices is apairlist of length-one character vectors.The first entry is always"null device", and there are as manyentries as the maximal number of graphics devices which have beensimultaneously active. If a device has been removed, its entry will be"" until the device number is reused.

Devices may add attributes to the character vector: for exampledevices which write to a file may record its path in attribute"filepath".

Description

.Machine is a variable holding information on the numericalcharacteristics of the machineR is running on, such as the largestdouble or integer and the machine's precision.

Usage

.Machine

Details

The algorithm is based on Cody's (1988) subroutineMACHAR. As allcurrent implementations ofR use 32-bit integers and useIEC 60559floating-point (double precision) arithmetic, the"integer" and"double" related values are the same for almost allR builds.

Note that on most platforms smaller positive values than.Machine$double.xmin can occur. On a typicalR platform thesmallest positive double is about5e-324.

Value

A list with components

Note

In the (typical) case wherecapabilities("long.double") istrue,R uses the ‘⁠long double⁠’ C type in quite a few places internallyfor accumulators in e.g.sum, reading non-integernumeric constants into (binary) double precision numbers, or arithmeticsuch asx %% y; also, ‘⁠long double⁠’ can be read byreadBin.
For this reason, in that case,.Machine contains ten further components,longdouble.eps,*.neg.eps,*.digits,*.rounding*.guard,*.ulp.digits,*.neg.ulp.digits,*.exponent,*.min.exp, and*.max.exp, computedentirely analogously to theirdouble.* counterparts, see there.

sizeof.longdouble only tells you the amount of storageallocated for a long double. Often what is stored is the 80-bit extendeddouble type ofIEC 60559, padded to the double alignment used on theplatform — this seems to be the case for the commonR platformsusing ix86 and x86_64 chips. There are other implementation of longdouble, usually in software for example on Sparc Solaris and AIX.

Note that it is legal for a platform to have a ‘⁠long double⁠’ Ctype which is identical to the ‘⁠double⁠’ type — this happens onARM CPUs. In that casecapabilities("long.double") willbe false but on versions ofR prior to 4.0.4,.Machine may contain"longdouble.kind" elements.

Source

Uses a C translation of Fortran code in the reference, modified by theR Core Team to defeat over-optimization in modern compilers.

References

Cody, W. J. (1988).MACHAR: A subroutine to dynamically determine machine parameters.Transactions on Mathematical Software,14(4), 303–311.doi:10.1145/50063.51907.

See Also

.Platform for details of the platform.

Examples

.Machine## or for a neat printoutnoquote(unlist(format(.Machine)))

Description

.Platform is a list with some details of the platform underwhichR was built. This provides means to write OS-portableRcode.

Usage

.Platform

Value

A list with at least the following components:

AQUA

.Platform$GUI is set to"AQUA" under the macOS GUI,R.app. This has a number of consequences:

• ‘/usr/local/bin’ isappended to thePATHenvironment variable.

• the default graphics device is set toquartz.

• selects native (rather than Tk) widgets for thegraphics = TRUE options ofmenu andselect.list.

• HTML help is displayed in the internal browser.

• the spreadsheet-like data editor/viewer uses a Quartz versionrather than the X11 one.

See Also

R.version andSys.info give more detailsabout the OS. In particular,R.version$platform is thecanonical name of the platform under whichR was compiled.osVersion may give more details about the platformR is running on.

.Machine for details of the arithmetic used, andsystem for invoking platform-specific system commands.

capabilities andextSoftVersion (and linksthere) for availability of capabilities partlyexternal toRbut used fromR functions.

Examples

## Note: this can be done in a system-independent way by dir.exists()if(.Platform$OS.type=="unix"){   system.test<-function(...) system(paste("test",...))==0L   dir.exists2<-function(dir)       sapply(dir,function(d) system.test("-d", d))   dir.exists2(c(R.home(),"/tmp","~","/NO"))# > T T T F}

Description

Abbreviate strings to at leastminlength characters,such that they remainunique (if they were),unlessstrict = TRUE.

Usage

abbreviate(names.arg, minlength=4, use.classes=TRUE,           dot=FALSE, strict=FALSE,           method= c("left.kept","both.sides"), named=TRUE)

Arguments

Details

The default algorithm (method = "left.kept") used is similarto that of S. For a single string it works as follows.First spaces at the ends of the string are stripped.Then (if necessary) any other spaces are stripped.Next, lower case vowels are removed followed by lower case consonants.Finally if the abbreviation is still longer thanminlengthupper case letters and symbols are stripped.

Characters are always stripped from the end of the strings first. Ifan element ofnames.arg contains more than one word (words areseparated by spaces) then at least one letter from each word will beretained.

Missing (NA) values are unaltered.

Ifuse.classes isFALSE then the only distinction is tobe between letters and space.

Value

A character vector containing abbreviations for the character stringsin its first argument. Duplicates in the originalnames.argwill be given identical abbreviations. If any non-duplicated elementshave the sameminlength abbreviations then, ifmethod = "both.sides" the basic internalabbreviate() algorithm isapplied to the characterwisereversed strings; if there arestill duplicated abbreviations and ifstrict = FALSE as bydefault,minlength is incremented by one and new abbreviationsare found for those elements only. This process is repeated until allunique elements ofnames.arg have unique abbreviations.

Ifnames is true, the character version ofnames.arg isattached to the returned value as anames attribute: noother attributes are retained.

If a input element contains non-ASCII characters, the correspondingvalue will be in UTF-8 and marked as such (seeEncoding).

Warning

Ifuse.classes is true (the default), this is really onlysuitable for English, and prior toR 3.3.0 did not work correctlywith non-ASCII characters in multibyte locales. It will warn if usedwith non-ASCII characters (and required to reduce the length). It isunlikely to work well with inputs not in the Unicode Basic MultilingualPlane nor on (rare) platforms where wide characters are not encoded inUnicode.

As fromR 3.3.0 the concept of ‘vowel’ is extended fromEnglish vowels by including characters which are accented versions oflower-case English vowels (including ‘o with stroke’). Ofcourse, there are languages (even Western European languages such asWelsh) with other vowels.

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))stopifnot(identical(unname(st.abb),           abbreviate(state.name,2, named=FALSE)))table(nchar(st.abb))# out of 50, 3 need 4 letters :as<- abbreviate(state.name,3, strict=TRUE)as[which(as=="Mss")]## and without distinguishing vowels:st.abb2<- abbreviate(state.name,2,FALSE)cbind(st.abb, st.abb2)[st.abb2!= st.abb,]## 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)

Description

Searches for approximate matches topattern (the first argument)within each element of the stringx (the second argument) usingthe generalized Levenshtein edit distance (the minimal possiblyweighted number of insertions, deletions and substitutions needed totransform one string into another).

Usage

agrep(pattern, x, max.distance=0.1, costs=NULL,      ignore.case=FALSE, value=FALSE, fixed=TRUE,      useBytes=FALSE)agrepl(pattern, x, max.distance=0.1, costs=NULL,       ignore.case=FALSE, fixed=TRUE, useBytes=FALSE)

Arguments

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 intoanother.

This uses thetre code by Ville Laurikari(https://github.com/laurikari/tre), which supportsMBCScharacter matching.

The main effect ofuseBytes = TRUE is to avoid errors/warningsabout invalid inputs and spurious matches in multibyte locales.It inhibits the conversion of inputs with marked encodings, and isforced if any input is found which is marked as"bytes" (seeEncoding).

Value

agrep returns a vector giving the indices of the elements thatyielded a match, or, ifvalue isTRUE, the matchedelements (after coercion, preserving names but no other attributes).

agrepl returns a logical vector.

Note

Since someone who read the description carelessly even filed a bugreport on it, do note that this matches substrings of each element ofx (just asgrep does) andnot wholeelements. See alsoadist in packageutils, whichoptionally returns the offsets of the matched substrings.

Author(s)

Original version inR < 2.10.0 by David Meyer.Current version by Brian Ripley and Kurt Hornik.

See Also

grep,adist.A different interface to approximate string matching is provided byaregexec().

Examples

agrep("lasy","1 lazy 2")agrep("lasy", c(" 1 lazy 2","1 lasy 2"), max.distance= list(sub=0))agrep("laysy", c("1 lazy","1","1 LAZY"), max.distance=2)agrep("laysy", c("1 lazy","1","1 LAZY"), max.distance=2, value=TRUE)agrep("laysy", c("1 lazy","1","1 LAZY"), max.distance=2, ignore.case=TRUE)

Description

Given a set of logical vectors, are all of the values true?

Usage

all(..., na.rm=FALSE)

Arguments

Details

This is a generic function: methods can be defined for itdirectly or via theSummary group generic.For this to work properly, the arguments... should beunnamed, 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 aprimitive function.

Value

The value is a logical vector of length one.

Letx denote the concatenation of all the logical vectors in... (after coercion), after removingNAs if requested byna.rm = TRUE.

The value returned isTRUE if all of the values inx areTRUE (including if there are no values), andFALSE if atleast one of the values inx isFALSE. Otherwise thevalue isNA (which can only occur ifna.rm = FALSE and... contains noFALSE values and at least oneNA value).

S4 methods

This is part of the S4Summarygroup generic. Methods for it must use the signaturex, ..., na.rm.

Note

Thatall(logical(0)) is true is a useful convention:it ensures that

all(all(x), all(y)) == all(x, y)

even ifx 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’ ofall, andstopifnot(*) which is anall(*)‘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.

Description

all.equal(x, y) is a utility to compareR objectsxandy testing ‘near equality’. If they are different,comparison is still made to some extent, and a report of thedifferences is returned. Do not useall.equal directly inif expressions—either useisTRUE(all.equal(....)) oridentical if appropriate.

Usage

all.equal(target, current,...)## Default S3 method:all.equal(target, current,..., check.class=TRUE)## S3 method for class 'numeric'all.equal(target, current,          tolerance= sqrt(.Machine$double.eps), scale=NULL,          countEQ=FALSE,          formatFUN=function(err, what) format(err),..., check.attributes=TRUE, check.class=TRUE, giveErr=FALSE)## S3 method for class 'list'all.equal(target, current,...,          check.attributes=TRUE, use.names=TRUE)## S3 method for class 'environment'all.equal(target, current, all.names=TRUE,          evaluate=TRUE,...)## S3 method for class 'function'all.equal(target, current, check.environment=TRUE,...)## S3 method for class 'POSIXt'all.equal(target, current,..., tolerance=1e-3, scale,          check.tzone=TRUE)attr.all.equal(target, current,...,               check.attributes=TRUE, check.names=TRUE)

Arguments

Details

all.equal is a generic function, dispatching methods on thetarget argument. To see the available methods, usemethods("all.equal"), but note that the default methodalso does some dispatching, e.g. using the raw method for logicaltargets.

Remember that arguments which follow... must be specified by(unabbreviated) name. It is inadvisable to pass unnamed arguments in... as these will match different arguments in differentmethods.

Numerical comparisons forscale = NULL (the default) aretypically on arelative difference scale unless thetarget values are close to zero or infinite. Specifically,the scale is computed as the mean absolute value oftarget.If this scale is finite and exceedstolerance, differencesare expressed relative to it; otherwise, absolute differences are used.Note that this scale and all further steps are computed only for thosevector elementswheretarget is notNA and differs fromcurrent.IfcountEQ is true, the equal andNA cases arecounted in determining the “sample” size.

Ifscale is numeric (and positive), absolute comparisons aremade after scaling (dividing) byscale. Note that if all ofscale is close to 1 (specifically, within 1e-7), the difference is stillreported as being on an absolute scale.

For complextarget, the modulus (Mod) of thedifference is used:all.equal.numeric is called so argumentstolerance andscale are available.

Thelist method compares components oftarget andcurrent recursively, passing all otherarguments, as long as both are “list-like”, i.e., fulfilleitheris.vector oris.list.

Theenvironment method works via thelist method,and is also used for reference classes (unless a specificall.equal method is defined).

The method for date-time objects usesall.equal.numeric tocompare times (in"POSIXct" representation) with adefaulttolerance of 0.001 seconds, ignoringscale.A time zone mismatch betweentarget andcurrent isreported unlesscheck.tzone = FALSE.

attr.all.equal is used for comparingattributes, returningNULL or acharacter vector.

Value

EitherTRUE (NULL forattr.all.equal) or a vectorofmode"character" describing the differencesbetweentarget andcurrent.

References

Chambers, J. M. (1998)Programming with Data. A Guide to the S Language.Springer (for=).

See Also

identical,isTRUE,==, andall for exact equality testing.

Examples

all.equal(pi,355/113)# not precise enough (default tol) > relative errorquarts<-1/4+1:10# exactd45<- pi*quarts; one<- rep(1,10)tan(d45)== one# mostly FALSE, as typically exact; embarrassingly,tanpi(quarts)== one# (is always FALSE (Fedora 34; gcc 11.2.1))stopifnot(all.equal(          tan(d45), one))# TRUE, but not if we are picky:all.equal(tan(d45), one, tolerance=0)# to see differenceall.equal(tan(d45), one, tolerance=0, scale=1)# "absolute diff.."all.equal(tan(d45), one, tolerance=0, scale=1+(-2:2)/1e9)# "absolute"all.equal(tan(d45), one, tolerance=0, scale=1+(-2:2)/1e6)# "scaled"## advanced: equality of environmentsae<- all.equal(as.environment("package:stats"),                asNamespace("stats"))stopifnot(is.character(ae), length(ae)>10,## were incorrectly "considered equal" in R <= 3.1.1          all.equal(asNamespace("stats"), asNamespace("stats")))## A situation where  'countEQ = TRUE' makes sense:x1<- x2<-(1:100)/10;  x2[2]<-1.1*x1[2]## 99 out of 100 pairs (x1[i], x2[i]) are equal:plot(x1,x2, main="all.equal.numeric() -- not counting equal parts")all.equal(x1,x2)## "Mean relative difference: 0.1"mtext(paste("all.equal(x1,x2) :", all.equal(x1,x2)), line=-2)##' extract the 'Mean relative difference' as number:all.eqNum<-function(...) as.numeric(sub(".*:",'', all.equal(...)))set.seed(17)## When x2 is jittered, typically all pairs (x1[i],x2[i]) do differ:summary(r<- replicate(100, all.eqNum(x1, x2*(1+rnorm(x1)*1e-7))))mtext(paste("mean(all.equal(x1, x2*(1 + eps_k))) {100 x} Mean rel.diff.=",            signif(mean(r),3)), line=-4, adj=0)## With argument  countEQ=TRUE, get "the same" (w/o need for jittering):mtext(paste("all.equal(x1,x2, countEQ=TRUE) :",          signif(all.eqNum(x1,x2, countEQ=TRUE),3)), line=-6, col=2)## Using giveErr=TRUE :x1.<- x1*(1+1e-9*rnorm(x1))str(all.equal(x1, x1., giveErr=TRUE))## logi TRUE## - attr(*,  "err")= num 8.66e-10## - attr(*, "what")= chr "relative"## Used with stopifnot(), still *showing* diff:all.equalShow<-function(...){   r<- all.equal(..., giveErr=TRUE)   cat(attr(r,"what"),"err:", attr(r,"err"),"\n")   c(r)# can drop attributes, as not used anymore}# checks, showing error in any case:stopifnot(all.equalShow(x1, x1.))# -> relative err: 8.66002e-10tryCatch(error=identity, stopifnot(all.equalShow(x1,2*x1)))-> eAestopifnot(inherits(eAe,"error"))# stopifnot(all.equal....()) giving smart msg:cat(conditionMessage(eAe),"\n")two<- structure(2, foo=1, class="bar")all.equal(two^20,2^20)# lots of diffall.equal(two^20,2^20, check.attributes=FALSE)# "target is bar, current is numeric"all.equal(two^20,2^20, check.attributes=FALSE, check.class=FALSE)# TRUE## comparison of date-time objectsnow<- Sys.time()stopifnot(all.equal(now, now+1e-4)# TRUE (default tolerance = 0.001 seconds))all.equal(now, now+0.2)all.equal(now, as.POSIXlt(now,"UTC"))stopifnot(all.equal(now, as.POSIXlt(now,"UTC"), check.tzone=FALSE)# TRUE)

Description

Return a character vector containing all the names which occur in anexpression or call.

Usage

all.names(expr, functions=TRUE, max.names=-1L, unique=FALSE)all.vars(expr, functions=FALSE, max.names=-1L, unique=TRUE)

Arguments

Details

These functions differ only in the default values for theirarguments.

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 callall.vars(expression(sin(x+y)))

Description

Given a set of logical vectors, is at least one of the values true?

Usage

any(..., na.rm=FALSE)

Arguments

Details

This is a generic function: methods can be defined for itdirectly or via theSummary group generic.For this to work properly, the arguments... should beunnamed, 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 aprimitive function.

Value

The value is a logical vector of length one.

Letx denote the concatenation of all the logical vectors in... (after coercion), after removingNAs if requested byna.rm = TRUE.

The value returned isTRUE if at least one of the values inx isTRUE, andFALSE if all of the values inx areFALSE (including if there are no values). Otherwisethe value isNA (which can only occur ifna.rm = FALSEand... contains noTRUE values and at least oneNA value).

S4 methods

This is part of the S4Summarygroup generic. Methods for it must use the signaturex, ..., 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’ ofany.

Examples

range(x<- sort(round(stats::rnorm(10)-1.2,1)))if(any(x<0)) cat("x contains negative values\n")

Description

Transpose an array by permuting its dimensions and optionally resizingit.

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,...)

Arguments

Value

A transposed version of arraya, with subscripts permuted asindicated by the arrayperm. Ifresize isTRUE,the array is reshaped as well as having its elements permuted, thedimnames are also permuted; ifresize = FALSE then thereturned object has the same dimensions asa, and the dimnamesare dropped. In each case other attributes are copied froma.

The functiont provides a faster and more convenient way oftransposing matrices.

Author(s)

Jonathan Rougier,[email protected] did thefaster 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 xx<- 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 contingency table

Description

Add elements to a vector.

Usage

append(x, values, after= length(x))

Arguments

Value

A vector containing the values inx with the elements ofvalues appended after the specified element ofx.

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)

Description

Returns a vector or array or list of values obtained by applying afunction to margins of an array or matrix.

Usage

apply(X, MARGIN, FUN,..., simplify=TRUE)

Arguments

Details

IfX is not an array but an object of a class with a non-nulldim value (such as a data frame),apply attemptsto coerce it to an array viaas.matrix if it is two-dimensional(e.g., a data frame) or viaas.array.

FUN is found by a call tomatch.fun and typicallyis either a function or a symbol (e.g., a backquoted name) or acharacter string specifying a function to be searched for from theenvironment of the call toapply.

Arguments in... cannot have the same name as any of theother arguments, and care may be needed to avoid partial matching toMARGIN orFUN. In general-purpose code it is goodpractice to name the first three arguments if... is passedthrough: this both avoids partial matching toMARGINorFUN and ensures that a sensible error message is given ifarguments namedX,MARGIN orFUN are passedthrough....

Value

If each call toFUN returns a vector of lengthn,andsimplify isTRUE, thenapply returns an array of dimensionc(n, dim(X)[MARGIN])ifn > 1. Ifn equals1,apply returns avector ifMARGIN has length 1 and an array of dimensiondim(X)[MARGIN] otherwise.Ifn is0, the result has length 0 but not necessarilythe ‘correct’ dimension.

If the calls toFUN return vectors of different lengths,or ifsimplify isFALSE,apply returns a list of lengthprod(dim(X)[MARGIN]) withdim set toMARGIN if this has length greater than one.

In all cases the result is coerced byas.vector to oneof the basic vector types before the dimensions are set, so that (forexample) 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 functionssweep andaggregate.

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)))stopifnot( apply(x,2, is.vector))## Sort the columns of a matrixapply(x,2, sort)## keeping named dimnamesnames(dimnames(x))<- c("row","col")x3<- array(x, dim= c(dim(x),3),    dimnames= c(dimnames(x), list(C= paste0("cop.",1:3))))identical(x,  apply( x,2,  identity))identical(x3, apply(x3,2:3, identity))##- 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)maapply(ma,1, table)#--> a list of length 2apply(ma,1, stats::quantile)# 5 x n matrix with rownamesstopifnot(dim(ma)== dim(apply(ma,1:2, sum)))## Example with different lengths for each callz<- array(1:24, dim=2:4)zseq<- apply(z,1:2,function(x) seq_len(max(x)))zseq## a 2 x 3 matrixtypeof(zseq)## listdim(zseq)## 2 3zseq[1,]apply(z,3,function(x) seq_len(max(x)))# a list without a dim attribute

Description

Displays the argument names and corresponding default values of a(non-primitive or primitive) function.

Usage

args(name)

Arguments

Details

This function is mainly used interactively to print the argument listof a function. For programming, consider usingformalsinstead.

Value

For a closure, a closure with identical formal argument list but anempty (NULL) body.

For a primitive (function), a closure with the documented usage andNULLbody. Note that some primitives do not make use of named argumentsand 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;str also prints the argument list of a function.

Examples

## "regular" (non-primitive) functions "print their arguments"## (by returning another function with NULL body which you also see):args(ls)args(graphics::plot.default)utils::str(ls)# (just "prints": does not show a NULL)## You can also pass a string naming a function.args("scan")## ...but :: package specification doesn't work in this case.tryCatch(args("graphics::plot.default"), error= print)## As explained above, args() gives a function with empty body:list(is.f= is.function(args(scan)), body= body(args(scan)))## Primitive functions mostly behave like non-primitive functions.args(c)args(`+`)## primitive functions without well-defined argument list return NULL:args(`if`)

Description

These unary and binary operators perform arithmetic on numeric orcomplex vectors (or objects which can be coerced to them).

Usage

+ x- xx+ yx- yx* yx/ yx^ yx%% yx%/% y

Arguments

Details

The unary and binary arithmetic operators are generic functions:methods can be written for them individually or via theOps group generic function. (SeeOps 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 andTRUE having value one.

1 ^ y andy ^ 0 are1,always.x ^ y should also give the proper limit result wheneither (numeric) argument isinfinite (one ofInf or-Inf).

Objects such as arrays or time-series can be operated on thisway provided they are conformable.

For double arguments,%% can be subject to catastrophic loss ofaccuracy ifx is much larger thany, and a warning isgiven if this is detected.

%% andx %/% y can be used for non-integery,e.g.1 %/% 0.2, but the results are subject to representationerror and so may be platform-dependent. Mathematically, the answer to1 %/% 0.2 should be5, but because theIEC 60559representation of0.2 is a binary fraction slightly larger than0.2 most platforms give4.

Users are sometimes surprised by the value returned, for example why(-8)^(1/3) isNaN. Fordouble inputs,R makesuse ofIEC 60559 arithmetic on all platforms, together with the Csystem function ‘⁠pow⁠’ for the^ operator. The relevantstandards define the result in many corner cases. In particular, theresult in the example above is mandated by the C99 standard. On manyUnix-alike systems the commandman pow gives details of thevalues in a large number of corner cases.

Arithmetic on typedouble inR is supposed to be done in‘round to nearest, ties to even’ mode, but this does depend onthe compiler andFPU being set up correctly.

Value

Unary+ and unary- return a numeric or complex vector.All attributes (including class) are preserved if there is nocoercion: logicalx is coerced to integer and names, dims anddimnames are preserved.

The binary operators return vectors containing the result of the elementby element operations. If involving a zero-length vector the resulthas length zero. Otherwise, the elements of shorter vectors are recycledas necessary (with awarning when they are recycled onlyfractionally). The operators are+ for addition,- for subtraction,* for multiplication,/ fordivision and^ for exponentiation.

%% indicatesx mod y (“x modulo y”), i.e.,computes the ‘remainder’r <- x %% y, and%/% indicates integer division, whereR uses “floored”integer division, i.e.,q <- x %/% y := floor(x/y), as promotedby Donald Knuth, see the Wikipedia page on ‘Modulo operation’,and hencesign(r) == sign(y). It is guaranteed that

x == (x %% y) + y * (x %/% y)

(up to rounding error)

unlessy == 0 where the result of%% isNA_integer_ orNaN (depending on thetypeof of the arguments) or for some non-finitearguments, e.g., when the RHS of the identity aboveamounts toInf - Inf.

If either argument is complex the result will be complex, otherwise ifone or both arguments are numeric, the result will be numeric. Ifboth arguments are of typeinteger, the type of the result of/ and^ isnumeric and for the other operators itis integer (with overflow, which occurs at$\pm (2^{31}-1)$±(231−1),returned asNA_integer_ with a warning).

The rules for determining the attributes of the result are rathercomplicated. Most attributes are taken from the longer argument.Names will be copied from the first if it is the same length as theanswer, otherwise from the second if that is. If the arguments arethe same length, attributes will be copied from both, with those ofthe first argument taking precedence when the same attribute ispresent in both arguments. For time series, these operations areallowed only if the series are compatible, when the class andtsp attribute of whichever is a time series (the same,if both are) are used. For arrays (and an array result) thedimensions and dimnames are taken from first argument if it is anarray, otherwise the second.

S4 methods

These operators are members of the S4Arith group generic,and so methods can be written for them individually as well as for thegroup generic (or theOps group generic), with argumentsc(e1, e2) (withe2 missing for a unary operator).

Implementation limits

R is dependent on OS services (and they onFPUs) for floating-pointarithmetic. On all currentR platformsIEC 60559 (also known as IEEE754) arithmetic is used, but some things in those standards areoptional. In particular, the support fordenormal akasubnormal numbers(those outside the range given by.Machine) may differbetween platforms and even between calculations on a single platform.

Another potential issue is signed zeroes: onIEC 60559 platforms thereare two zeroes with internal representations differing by sign. WherepossibleR treats them as the same, but for example direct outputfrom C code often does not do so and may output ‘⁠-0.0⁠’ (and onWindows whether it does so or not depends on the version of Windows).One place inR where the difference might be seen is in division byzero:1/x isInf or-Inf depending on the sign ofzerox. Another place isidentical(0, -0, num.eq = FALSE).

Note

All logical operations involving a zero-length vector have azero-length result.

The binary operators are sometimes called as functions ase.g.`&`(x, y): see the description of howargument-matching is done inOps.

** is translated in the parser to^, but this wasundocumented for many years. It appears as an index entry in Beckeret al. (1988), pointing to the help forDeprecated butis not actually mentioned on that page. Even though it had beendeprecated in S for 20 years, it was still accepted inR 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-PointArithmetic.ACM Computing Surveys,23(1), 5–48.doi:10.1145/103162.103163.
Also available athttps://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html.

For theIEC 60559 (aka IEEE 754) standard:https://www.iso.org/standard/57469.html andhttps://en.wikipedia.org/wiki/IEEE_754.

On the integer division and remainder (modulo) computations,%%and%/%:https://en.wikipedia.org/wiki/Modulo_operation, andDonald Knuth (1972)The Art of Computer Programming, Vol.1.

See Also

sqrt for miscellaneous andSpecial for specialmathematical functions.

Syntax for operator precedence.

%*% for matrix multiplication.

Examples

x<--1:12x+12* x+3x%%3# is periodic  2 0  1  2 0  1 ...x%%-3#  (ditto)    -1 0 -2 -1 0 -2 ...x%/%5x%%Inf# now is defined by limit (gave NaN in earlier versions of R)## Illustrating PR#18677, see above1%/% print(0.2, digits=19)

Description

Creates or tests for arrays.

Usage

array(data=NA, dim= length(data), dimnames=NULL)as.array(x,...)is.array(x)

Arguments

Details

An array inR can have one, two or more dimensions. It is simply avector which is stored with additionalattributes giving thedimensions (attribute"dim") and optionally names for thosedimensions (attribute"dimnames").

A two-dimensional array is the same thing as amatrix.

One-dimensional arrays often look like vectors, but may be handleddifferently by some functions:str does distinguishthem in recent versions ofR.

The"dim" attribute is an integer vector of length one or morecontaining non-negative values: the product of the values must matchthe length of the array.

The"dimnames" attribute is optional: if present it is a listwith one component for each dimension, eitherNULL or acharacter vector of the length given by the element of the"dim" attribute for that dimension.

is.array is aprimitive function.

For a list array, theprint methods prints entries of lengthnot one in the form ‘⁠integer,7⁠’ indicating the type and length.

Value

array returns an array with the extents specified indimand naming information indimnames. The values indata aretaken to be those in the array with the leftmost subscript movingfastest. If there are too few elements indata to fill the array,then the elements indata are recycled. Ifdata haslength zero,NA of an appropriate type is used for atomicvectors (0 for raw vectors) andNULL for lists.

Unlikematrix,array does not currently removeany attributes left byas.vector from a classed listdata, so can return a list array with a class attribute.

as.array is a generic function for coercing to arrays. Thedefault method does so by attaching adim attribute toit. It also attachesdimnames ifx hasnames. The sole purpose of this is to make it possibleto access thedim[names] attribute at a later time.

is.array returnsTRUE orFALSE depending onwhether its argument is an array (i.e., has adim attribute ofpositive length) or not. It is generic: you can write methods to handlespecific classes of objects, seeInternalMethods.

Note

is.array is aprimitive function.

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

Description

array2DF converts an array, including list arrays commonlyreturned bytapply, into data frames for use in furtheranalysis or plotting functions.

Usage

array2DF(x, responseName="Value",         sep="", base= list(LETTERS),         simplify=TRUE, allowLong=TRUE)

Arguments

Details

The main use ofarray2DF is to convert an array, as typicallyreturned bytapply, into a data frame.

Whensimplify = FALSE, this is similar toas.data.frame.table, except that it works for listarrays as well as atomic arrays. Specifically, the resulting dataframe has one row for each element of the array, with one column foreach dimension of the array giving the correspondingdimnames. The contents of the array are placed in acolumn whose name is given by theresponseName argument. Themode of this column is the same as that ofx, usually an atomicvector or a list.

Ifx does not havedimnames, they areautomatically created usingbase andsep.

In the default case, whensimplify = TRUE, some common casesare handled specially.

If all components ofx are data frames with identical columnnames (with possibly different numbers of rows), they arerbind-ed to form the response. The additional columnsgivingdimnames are repeated according to the number ofrows, andresponseName is ignored in this case.

If all components ofx areunnamed atomic vectorsandallowLong = TRUE, each component is treated as asingle-column data frame with column name given byresponseName, and processed as above.

In all other cases, an attempt to simplify is made bysimplify2array. If this results in multiple unnamedcolumns, names are constructed usingresponseName andsep.

Value

A data frame with at leastlength(dim(x)) + 1 columns. Thefirstlength(dim(x)) columns each represent one dimension ofx and gives the corresponding values ofdimnames, whichare implicitly created if necessary. The remaining columns contain thecontents ofx, after attempted simplification if requested.

See Also

tapply,as.data.frame.table,split,aggregate.

Examples

s1<- with(ToothGrowth,           tapply(len, list(dose, supp), mean, simplify=TRUE))s2<- with(ToothGrowth,           tapply(len, list(dose, supp), mean, simplify=FALSE))str(s1)# atomic arraystr(s2)# list arraystr(array2DF(s1, simplify=FALSE))# Value column is vectorstr(array2DF(s2, simplify=FALSE))# Value column is liststr(array2DF(s2, simplify=TRUE))# simplified to vector### The remaining examples use the default 'simplify = TRUE'## List array with list components: columns are lists (no simplification)with(ToothGrowth,     tapply(len, list(dose, supp),function(x) t.test(x)[c("p.value","alternative")]))|>  array2DF()|> str()## List array with data frame components: columns are atomic (simplified)with(ToothGrowth,     tapply(len, list(dose, supp),function(x) with(t.test(x), data.frame(p.value, alternative))))|>  array2DF()|> str()## named vectorswith(ToothGrowth,     tapply(len, list(dose, supp),            quantile))|> array2DF()## unnamed vectors: long formatwith(ToothGrowth,     tapply(len, list(dose, supp),            sample, size=5))|> array2DF()## unnamed vectors: wide formatwith(ToothGrowth,     tapply(len, list(dose, supp),            sample, size=5))|> array2DF(allowLong=FALSE)## unnamed vectors of unequal lengthwith(ToothGrowth[-1,],     tapply(len, list(dose, supp),            sample, replace=TRUE))|>  array2DF(allowLong=FALSE)## unnamed vectors of unequal length with allowLong = TRUE## (within-group bootstrap)with(ToothGrowth[-1,],     tapply(len, list(dose, supp), sample, replace=TRUE))|>  array2DF()|> str()## data frame inputtapply(ToothGrowth,~ dose+ supp, FUN= with,       data.frame(n= length(len), mean= mean(len), sd= sd(len)))|>  array2DF()

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=FALSE)## S3 method for class 'list'as.data.frame(x, row.names=NULL, optional=FALSE,...,              cut.names=FALSE, col.names= names(x), fix.empty.names=TRUE,              check.names=!optional,              stringsAsFactors=FALSE)## S3 method for class 'matrix'as.data.frame(x, row.names=NULL, optional=FALSE,              make.names=TRUE,...,              stringsAsFactors=FALSE)as.data.frame.vector(x, row.names=NULL, optional=FALSE,...,                     nm= deparse1(substitute(x)))is.data.frame(x)

Arguments

Details

as.data.frame is a generic function with many methods, andusers and packages can supply further methods. For classes that actas vectors, often a copy ofas.data.frame.vector will workas the method.

SinceR 4.3.0, thedefault method will callas.data.frame.vector for atomic (as byis.atomic)x.

Direct calls ofas.data.frame.class are still possible (base package!),for 12 atomic base classes, but are deprecatedwhere callingas.data.frame.vector instead is recommended.

If a list is supplied, each element is converted to a column in thedata frame. Similarly, each column of a matrix is converted separately.This can be overridden if the object has a class which hasa method foras.data.frame: two examples arematrices of class"model.matrix" (which areincluded 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 aretreated like vectors and two-dimensional arrays like matrices. Arrayswith more than two dimensions are converted to matrices by‘flattening’ all dimensions after the first and creatingsuitable column labels.

Character variables are converted to factor columns unless protectedbyI.

If a data frame is supplied, all classes preceding"data.frame"are stripped, and the row names are changed if that argument is supplied.

Ifrow.names = NULL, row names are constructed from the namesor dimnames ofx, otherwise are the integer sequencestarting at one. Few of the methods check for duplicated row names.Names are removed from vector columns unlessI.

Value

as.data.frame returns a data frame, normally with all row names"" ifoptional = TRUE.

is.data.frame returnsTRUE if its argument is a dataframe (that is, has"data.frame" amongst its classes)andFALSE otherwise.

References

Chambers, J. M. (1992)Data for models.Chapter 3 ofStatistical Models in Seds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

See Also

data.frame,as.data.frame.table for thetable method (which has additional arguments if called directly).

Description

Functions to convert between character representations and objects ofclass"Date" representing calendar dates.

Usage

as.Date(x,...)## S3 method for class 'character'as.Date(x, format, tryFormats= c("%Y-%m-%d","%Y/%m/%d"),        optional=FALSE,...)## 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, format="%Y-%m-%d",...)## S3 method for class 'Date'as.character(x,...)

Arguments

Details

The usual vector re-cycling rules are applied tox andformat so the answer will be of length that of the longer of thevectors.

Locale-specific conversions to and from character strings are usedwhere appropriate and available. This affects the names of the daysand months.

Theas.Date methods accept character strings, factors, logicalNA and objects of classes"POSIXlt" and"POSIXct". (The last is converted to days by ignoringthe time after midnight in the representation of the time in specifiedtime zone, default UTC.) Also objects of class"date" (frompackagedate) and"dates" (frompackagechron). Character strings are processedas far as necessary for the format specified: any trailing charactersare ignored.

as.Date will accept numeric data (the number of days since anepoch), sinceR 4.3.0 also whenorigin is not supplied.

Theformat andas.character methods ignore anyfractional part of the date.

Value

Theformat andas.character methods return a character vectorrepresenting the date.NA dates are returned asNA_character_.

Theas.Date methods return an object of class"Date".

Conversion from other Systems

Most systems record dates internally as the number of days since someorigin, 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 theirignorance of calendar systems. For example, Excel's designerthought 1900 was a leap year (claiming to copy the error fromearlier DOS spreadsheets), and Matlab's designer chose thenon-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 saythat it is only to be used for years before 1582 with the agreementof the parties in information exchange.)

The only safe procedure is to check the other systems values for knowndates: reports on the Internet (including R-help) are more often wrongthan right.

Note

The default formats follow the rules of the ISO 8601 internationalstandard which expresses a day as"2001-02-03".

If the date string does not specify the date completely, the returnedanswer may be system-specific. The most common behaviour is to assumethat a missing year, month or day is the current one. If it specifiesa date incorrectly, reliable implementations will give an error andthe date is reported asNA. Unfortunately some commonimplementations (such as ‘⁠glibc⁠’) are unreliable and guess at theintended meaning.

Years before 1CE (aka 1AD) will probably not be handled correctly.

References

International Organization for Standardization (2004, 1988, 1997,...)ISO 8601. Data elements and interchange formats –Information interchange – Representation of dates and times.For links to versions available on-line see (at the time of writing)https://www.qsl.net/g1smd/isopdf.htm.

See Also

Date for details of the date class;locales to query or set a locale.

Your system's help pages onstrftime andstrptime to seehow to specify their formats. Windows users will find no help pageforstrptime: code based on ‘⁠glibc⁠’ is used (withcorrections), so all the format specifiers described here aresupported, but with no alternative number representation nor eraavailable in any locale.

Examples

## locale-specific version of the dateformat(Sys.Date(),"%a %b %d")## read in date info in format 'ddmmmyyyy'## 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## incorrectly treating 1900 as a leap year.## So for dates (post-1901) from Windows Excelas.Date(35981, origin="1899-12-30")# 1998-07-05## and Mac Excelas.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,## (it takes the non-existent 0000-01-01 as day 1)## so Matlab day 734373 can be imported asas.Date(734373)-719529# 2010-08-23## (value from## http://www.mathworks.de/de/help/matlab/matlab_prog/represent-date-and-times-in-MATLAB.html)## Time zone effectz<- ISOdate(2010,04,13, c(0,12))# midnight and midday UTCas.Date(z)# in UTC## these time zone names are commonas.Date(z, tz="NZ")as.Date(z, tz="HST")# Hawaii

Description

A generic function coercing anR object to anenvironment. A number or a character string isconverted to the corresponding environment on the search path.

Usage

as.environment(x)

Arguments

Details

This is aprimitive generic function: you can write methods tohandle specific classes of objects, seeInternalMethods.

Value

The corresponding environment object.

Author(s)

John Chambers

See Also

environment for creation and manipulation,search;list2env.

Examples

as.environment(1)## the global environmentidentical(globalenv(), as.environment(1))## is TRUEtry(## <<- 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 eeutils::ls.str(ee)

Description

as.function is a generic function which is used to convertobjects to functions.

as.function.default works on a listx, which should contain theconcatenation of a formal argument list and an expression or anobject of mode"call" which will become the function body.The function will be defined in a specified environment, by defaultthat of the caller.

Usage

as.function(x,...)## Default S3 method:as.function(x, envir= parent.frame(),...)

Arguments

Value

The desired function.

Author(s)

Peter Dalgaard

See Also

function;alist which is handy for the construction ofargument lists, etc.

Examples

as.function(alist(a=, b=2, a+b))as.function(alist(a=, b=2, a+b))(3)

Description

Functions to manipulate objects of classes"POSIXlt" and"POSIXct" representing calendar dates and times.

Usage

as.POSIXct(x, tz="",...)as.POSIXlt(x, tz="",...)## S3 method for class 'character'as.POSIXlt(x, tz="", format,           tryFormats= c("%Y-%m-%d %H:%M:%OS","%Y/%m/%d %H:%M:%OS","%Y-%m-%d %H:%M","%Y/%m/%d %H:%M","%Y-%m-%d","%Y/%m/%d"),           optional=FALSE,...)## Default S3 method:as.POSIXlt(x, tz="",           optional=FALSE,...)## S3 method for class 'numeric'as.POSIXlt(x, tz="", origin,...)## S3 method for class 'Date'as.POSIXct(x, tz="UTC",...)## S3 method for class 'Date'as.POSIXlt(x, tz="UTC",...)## S3 method for class 'numeric'as.POSIXct(x, tz="", origin,...)## S3 method for class 'POSIXlt'as.double(x,...)

Arguments

Details

Theas.POSIX* functions convert an object to one of the twoclasses used to represent date/times (calendar dates plus time to thenearest second). They can convert objects of the other class and ofclass"Date" to these classes. Dates without times aretreated as being at midnight UTC.

They can also convert character strings of the formats"2001-02-03" and"2001/02/03" optionally followed bywhite space and a time in the format"14:52" or"14:52:03". (Formats such as"01/02/03" are ambiguousbut can be converted via a format specification bystrptime.) Fractional seconds are allowed.Alternatively,format can be specified for character vectors orfactors: if it is not specified and no standard format works forall non-NA inputs an error is thrown.

Ifformat is specified, remember that some of the formatspecifications are locale-specific, and you may need to set theLC_TIME category appropriatelyviaSys.setlocale. This most often affects the use of%a,%A (weekday names),%b,%B (month names) and%p (AM/PM).

LogicalNAs can be converted to either of the classes, but noother logical vectors can be.

If you are given a numeric time as the number of seconds since anepoch, see the examples.

Character input is first converted to class"POSIXlt" bystrptime: numeric input is first converted to"POSIXct". Any conversion that needs to go between the twodate-time classes requires a time zone: conversion from"POSIXlt" to"POSIXct" will validate times in theselected time zone. One issue is what happens at transitionsto and from DST, for example in the UK

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:00BST) and ambiguous (the clocks went back at 2:00BST to 1:00 GMT). Whathappens in such cases is OS-specific: one should expect the first tobeNA, but the second could be interpreted as eitherBST orGMT (and common OSes give both possible values). Note too (seestrftime) that OS facilities may not format invalidtimes correctly.

Value

as.POSIXct andas.POSIXlt return an object of theappropriate class. Iftz was specified,as.POSIXltwill give an appropriate"tzone" attribute. Date-times knownto be invalid will be returned asNA.

Note

Some of the concepts used have to be extended backwards in time (theusage is said to be ‘proleptic’). For example, the origin oftime for the"POSIXct" class, ‘1970-01-01 00:00.00 UTC’,is before UTC was defined. More importantly, conversion is doneassuming the Gregorian calendar which was introduced in 1582 and notused near-universally until the 20th century. One of there-interpretations assumed by ISO 8601:2004 is that there was a yearzero, even though current year numbering (and zero) is a much laterconcept (525 CE for year numbers from 1 CE).

Conversions between"POSIXlt" and"POSIXct" of futuretimes are speculative except in UTC. The main uncertainty is in theuse of and transitions to/from DST (most systems will assume thecontinuation of current rules but these can be changed at shortnotice).

If you want to extract specific aspects of a time (such as the day ofthe week) just convert it to class"POSIXlt" and extract therelevant component(s) of the list, or if you want a characterrepresentation (such as a named day of the week) use theformat method.

If a time zone is needed and that specified is invalid on your system,what happens is system-specific but attempts to set it will probablybe ignored.

Conversion from character needs to find a suitable format unless oneis supplied (by trying common formats in turn): this can be slow forlong inputs.

See Also

DateTimeClasses for details of the classes;strptime for conversion to and from characterrepresentations.

Sys.timezone for details of the (system-specific) namingof time zones.

locales for locale-specific aspects.

Examples

(z<- Sys.time())# the current datetime, as class "POSIXct"unclass(z)# a large integerfloor(unclass(z)/86400)# the number of days since 1970-01-01 (UTC)(now<- as.POSIXlt(Sys.time()))# the current datetime, as class "POSIXlt"str(unclass(now))# the internal list ; use now$hour, etc :now$year+1900# see ?DateTimeClassesmonths(now); weekdays(now)# see ?months; using LC_TIME locale## 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 thisas.POSIXct(z, origin="1960-01-01")# localas.POSIXct(z, origin="1960-01-01", tz="GMT")# in UTC## SPSS dates (R-help 2006-02-16)z<- c(10485849600,10477641600,10561104000,10562745600)as.Date(as.POSIXct(z, origin="1582-10-14", tz="GMT"))## Stata date-times: milliseconds since 1960-01-01 00:00:00 GMT## format %tc excludes leap-seconds, assumed here## For format %tC including leap seconds, see foreign::read.dta()z<-1579598122120op<- options(digits.secs=3)# avoid rounding down: milliseconds are not exactly representableas.POSIXct((z+0.1)/1000, origin="1960-01-01")options(op)## Matlab 'serial day number' (days and fractional days)z<-7.343736909722223e5# 2010-08-23 16:35:00as.POSIXct((z-719529)*86400, origin="1970-01-01", tz="UTC")as.POSIXlt(Sys.time(),"GMT")# the current time in UTC## These may not be correct names on your systemas.POSIXlt(Sys.time(),"America/New_York")# in New Yorkas.POSIXlt(Sys.time(),"EST5EDT")# alternative.as.POSIXlt(Sys.time(),"EST")# somewhere in Eastern Canadaas.POSIXlt(Sys.time(),"HST")# in Hawaiias.POSIXlt(Sys.time(),"Australia/Darwin")tab<- file.path(R.home("share"),"zoneinfo","zone1970.tab")if(file.exists(tab)){# typically on Windows; *not* on Linux  cols<- c("code","coordinates","TZ","comments")  tmp<- read.delim(tab,                    header=FALSE, comment.char="#", col.names= cols)if(interactive()) View(tmp)  head(tmp,10)}

Description

Change the class of an object to indicate that it should be treated‘as is’.

Usage

I(x)

Arguments

Details

FunctionI has two main uses.

• In functiondata.frame. Protecting an object byenclosing it inI() in a call todata.frame inhibits theconversion of character vectors to factors and the dropping ofnames, and ensures that matrices are inserted as single columns.I can also be used to protect objects which are to beadded to a data frame, or converted to a data frameviaas.data.frame.

  It achieves this by prepending the class"AsIs" to the object'sclasses. Class"AsIs" has a few of its own methods, includingfor[,as.data.frame,print andformat.

• In functionformula. There it is used toinhibit the interpretation of operators such as"+","-","*" and"^" as formula operators, so theyare used as arithmetical operators. This is interpreted as a symbolbyterms.formula.

Value

A copy of the object with class"AsIs" prepended to the class(es).

References

Chambers, J. M. (1992)Linear models.Chapter 4 ofStatistical Models in Seds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

See Also

data.frame,formula

Description

Split an array or matrix by its margins.

Usage

asplit(x, MARGIN)

Arguments

Details

SinceR 4.1.0, one can also obtain the splits (less efficiently)usingapply(x, MARGIN, identity, simplify = FALSE).The values of the splits can also be obtained (less efficiently) bysplit(x, slice.index(x, MARGIN)).

Value

A “list array” with dimension$dv$dv and each element anarray of dimension$de$de and dimnames preserved as available, where$dv$dv and$de$de are, respectively, the dimensions ofxincluded and not included inMARGIN.

Examples

## A 3-dimensional array of dimension 2 x 3 x 4:d<-2:4x<- array(seq_len(prod(d)), d)x## Splitting by margin 2 gives a 1-d list array of length 3## consisting of 2 x 4 arrays:asplit(x,2)## Splitting by margins 1 and 2 gives a 2 x 3 list array## consisting of 1-d arrays of length 4:asplit(x, c(1,2))## Compare tosplit(x, slice.index(x, c(1,2)))## A 2 x 3 matrix:(x<- matrix(1:6,2,3))## To split x by its rows, one can useasplit(x,1)## or less efficientlysplit(x, slice.index(x,1))split(x, row(x))

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

Details

There are no restrictions on the name given asx: it can be anon-syntactic name (seemake.names).

Thepos argument can specify the environment in which to assignthe object in any of several ways: as-1 (the default),as a positive integer (the position in thesearch list); asthe character string name of an element in the search list; or as anenvironment (including usingsys.frame toaccess the currently active function calls).Theenvir argument is an alternative way to specify anenvironment, but is primarily for back compatibility.

assign does not dispatch assignment methods, so it cannot beused to set elements of vectors, names, attributes, etc.

Note that assignment to an attached list or data frame changes theattached copy and not the original object: seeattachandwith.

Value

This function is invoked for its side effect, which is assigningvalue to the variablex. If noenvir isspecified, then the assignment takes place in the currently activeenvironment.

Ifinherits isTRUE, enclosing environments of the suppliedenvironment are searched until the variablex is encountered.The value is then assigned in the environment in which the variable isencountered (provided that the binding is not locked: seelockBinding: if it is, an error is signaled). If thesymbol is not encountered then assignment takes place in the user'sworkspace (the global environment).

Ifinherits isFALSE, assignment takes place in theinitial frame ofenvir, unless an existing binding is locked orthere is no existing binding and the environment is locked (when anerror is signaled).

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)The New S Language.Wadsworth & Brooks/Cole.

See Also

<-,get, the inverse ofassign(),exists,environment.

Examples

for(iin1: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# 16a<-1:4assign("a[1]",2)a[1]==2# FALSEget("a[1]")==2# TRUE

Description

Assign a value to a name.

Usage

x<- valuex<<- valuevalue-> xvalue->> xx= value

Arguments

Details

There are three different assignment operators: two of themhave leftwards and rightwards forms.

The operators<- and= assign into the environment inwhich they are evaluated. The operator<- can be usedanywhere, whereas the operator= is only allowed at the toplevel (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->> are normally only used infunctions, and cause a search to be made through parent environmentsfor an existing definition of the variable being assigned. If sucha variable is found (and its binding is not locked) then its valueis redefined, otherwise assignment takes place in the globalenvironment. Note that their semantics differ from that in the Slanguage, but are useful in conjunction with the scoping rules ofR. See ‘The R Language Definition’ manual for furtherdetails and examples.

In all the assignment operator expressions,x can be a nameor 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 bybackticks).

The leftwards forms of assignment<- = <<- group right to left,the other from left to right.

Value

value. Thus one can usea <- b <- c <- 6.

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 (for=).

See Also

assign (and its inverseget),for “subassignment” such asx[i] <- v,see[<-; further,environment.

Description

The database is attached to theR search path. This means that thedatabase is searched byR when evaluating a variable, so objects inthe database can be accessed by simply giving their names.

Usage

attach(what, pos=2L, name= deparse1(substitute(what), backtick=FALSE),       warn.conflicts=TRUE)

Arguments

Details

When evaluating a variable or function nameR searches forthat name in the databases listed bysearch. The firstname of the appropriate type is used.

By attaching a data frame (or list) to the search path it is possibleto 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 thanwomen$height).

By default the database is attached in position 2 in the search path,immediately after the user's workspace and before all previouslyattached packages and previously attached databases. This can bealtered to attach later in the search path with thepos option,but you cannot attach atpos = 1.

The database is not actually attached. Rather, a new environment iscreated on the search path and the elements of a list (includingcolumns of a data frame) or objects in a save file or an environmentarecopied into the new environment. If you use<<- orassign to assign to an attacheddatabase, you only alter the attached copy, not the original object.(Normal assignment will place a modified version in the user'sworkspace: see the examples.) For this reasonattach can leadto confusion.

One useful ‘trick’ is to usewhat = NULL (or equivalently alength-zero list) to create a new environment on the search path intowhich objects can be assigned byassign orload orsys.source.

Names starting"package:" are reserved forlibrary and should not be used by end users. Attachedfiles are by default given the namefile:what. Thename argument given for the attached environment will be usedbysearch and can be used as the argument toas.environment.

Value

Theenvironment is returned invisibly with a"name" attribute.

Good practice

attach has the side effect of altering the search path and thiscan easily lead to the wrong object of a particular name being found.People do often forget todetach databases.

In interactive use,with is usually preferable to theuse ofattach/detach, unlesswhat is asave()-produced file in which caseattach() is a (safety) wrapper forload().

In programming, functions should not change the search path unlessthat is their purpose. Oftenwith can be used within afunction. If not, good practice is to

• Always use a distinctivename argument, and

• To immediately follow theattach call by anon.exit call todetach using the distinctive name.

This ensures that the search path is left unchanged even if thefunction is interrupted or if code after theattach callchanges the search path.

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 frameattach(women)summary(height)# The same variable now available by nameheight<- height*2.54# Don't do this. It creates a new variable# in the user's workspacefind("height")summary(height)# The new variable in the workspacerm(height)summary(height)# The original variable.height<<- height*25.4# Change the copy in the attached environmentfind("height")summary(height)# The changed copydetach("women")summary(women$height)# unchanged## Not run: ## create an environment on the search path and populate itsys.source("myfuns.R", envir= attach(NULL, name="myfuns"))## End(Not run)

Description

Get or set specific attributes of an object.

Usage

attr(x, which, exact=FALSE)attr(x, which)<- value

Arguments

Details

These functions provide access to a single attribute of an object.The replacement form causes the named attribute to take the valuespecified (or create a new attribute with the value given).

The extraction function first looks for an exact match towhichamongst the attributes ofx, then (unlessexact = TRUE)a unique partial match.(Settingoptions(warnPartialMatchAttr = TRUE) causespartial matches to give warnings.)

The replacement function only uses exact matches.

Note that some attributes (namelyclass,comment,dim,dimnames,names,row.names andtsp) are treated specially and have restrictions onthe values which can be set. (Note that this is not true oflevels which should be set for factors via thelevels replacement function.)

The extractor function allows (and does not match) empty and missingvalues ofwhich: the replacement function does not.

NULL objects cannot have attributes and attempting toassign one byattr gives an error.

Both areprimitive functions.

Value

For the extractor, the value of the attribute matched, orNULLif 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 matrixx<-1:10attr(x,"dim")<- c(2,5)

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-handside of the assignment as the object's attributes (if appropriate).

Usage

attributes(x)attributes(x)<- valuemostattributes(x)<- value

Arguments

Details

Unlikeattr it is not an error to set attributes on aNULL object: it will first be coerced to an empty list.

Note that some attributes (namelyclass,comment,dim,dimnames,names,row.names andtsp) are treated specially and have restrictions onthe values which can be set. (Note that this is not true oflevels which should be set for factors via thelevels replacement function.)

Attributes are not stored internally as a list and should be thoughtof as a set and not a vector, i.e, theorder of the elements ofattributes() does not matter. This is also reflected byidentical()'s behaviour with the default argumentattrib.as.set = TRUE. Attributes must have unique names (andNA is taken as"NA", not a missing value).

Assigning attributes first removes all attributes, then sets anydim attribute and then the remaining attributes in the ordergiven: this ensures that setting adim attribute always precedesthedimnames attribute.

Themostattributes assignment takes special care for thedim,names anddimnamesattributes, and assigns them only when known to be valid whereas anattributes assignment would give an error if any are not. Itis principally intended for arrays, and should be used with care onclassed objects. For example, it does not check thatrow.names are assigned correctly for data frames.

The names of a pairlist are not stored as attributes, but are reportedas if they were (and can be set by the replacement form ofattributes).

NULL objects cannot have attributes and attempts toassign them will promote the object to an empty list.

Both assignment and replacement forms ofattributes areprimitive functions.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)The New S Language.Wadsworth & Brooks/Cole.

See Also

attr,structure.

Examples

x<- cbind(a=1:3, pi= pi)# simple matrix with dimnamesattributes(x)## strip an object's attributes:attributes(x)<-NULLx# now just a vector of length 6mostattributes(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

Description

autoload creates a promise-to-evaluateautoloader andstores it with namename in.AutoloadEnv environment.WhenR attempts to evaluatename,autoloader is run,the package is loaded andname is re-evaluated in the newpackage's environment. The result is thatR behaves as ifpackage was loaded but it does not occupy memory.

.Autoloaded contains the names of the packages forwhich autoloading has been promised.

Usage

autoload(name, package, reset=FALSE,...)autoloader(name, package,...).AutoloadEnv.Autoloaded

Arguments

Value

This function is invoked for its side-effect. It has no return value.

See Also

delayedAssign,library

Examples

require(stats)autoload("interpSpline","splines")search()ls("Autoloads").Autoloadedx<- sort(stats::rnorm(12))y<- x^2is<- interpSpline(x, y)search()## now has splinesdetach("package:splines")search()is2<- interpSpline(x, y+x)search()## and againdetach("package:splines")

Description

Solves a triangular system of linear equations.

Usage

backsolve(r, x, k= ncol(r), upper.tri=TRUE,             transpose=FALSE)forwardsolve(l, x, k= ncol(l), upper.tri=FALSE,             transpose=FALSE)

Arguments

Details

Solves a system of linear equations where the coefficient matrix isupper (or ‘right’, ‘R’) or lower (‘left’,‘L’) triangular.

x <- backsolve (R, b) solves$Rx=b$Rx=b, and
x <- forwardsolve(L, b) solves$Lx=b$Lx=b, respectively.

Ther/l must have at leastk rows and columns,andx must have at leastk rows.

This is a wrapper for the level-3 BLAS routinedtrsm.

Value

The solution of the triangular system. The result will be a vector ifx is a vector and a matrix ifx is a matrix.

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 1r%*% y# == x = (8,4,2)backsolve(r, x, transpose=TRUE)# 8 -12 -5

Description

Utilities to ‘balance’ objects of class"POSIXlt".

unCfillPOSIXlt(x) is a fastprimitive version ofbalancePOSIXlt(x, fill.only=TRUE, classed=FALSE) or equivalently,unclass(balancePOSIXlt(x, fill.only=TRUE)) from where it is named.

Usage

balancePOSIXlt(x, fill.only=FALSE, classed=TRUE)unCfillPOSIXlt(x)

Arguments

“Ragged” and Out-of-rangevs “Balanced” POSIXlt

Note that"POSIXlt" objectsx may have their (9 to 11)list components of differentlengths, by simplyrecycling them to full length. Prior toR 4.3.0, this has worked inprinting, formatting, and conversion to"POSIXct", but oftennot forlength(), conversion to"Date" or indexing,i.e., subsetting,[, or subassigning,[<-.

Relatedly, componentssec,min,hour,mdayandmon could have been out of their designated range (say, 0–23for hours) and still work correctly, e.g. in conversions and printing.This is supported as well, sinceR 4.3.0, at least when the values arenot extreme.

FunctionbalancePOSIXlt(x) will now return a version of the"POSIXlt" objectx which by default is balanced in both ways:All the internal list components are of full length, and their values areinside their ranges as specified inas.POSIXlt's‘Details on POSIXlt’.Settingfill.only = TRUE will only recycle the list componentsto full length, but not check them at all. This is particularly fasterwhen all components ofx are already of full length.

Experimentally,balancePOSIXlt() and other functions returningPOSIXlt objects now set alogical attribute"balanced" withNA meaning “filled-in”, i.e.,not “ragged” andTRUE means (fully) balanced.

See Also

For more details about many aspects of validPOSIXlt objects, notablytheir internal list components, see ‘DateTimeClasses’, e.g.,as.POSIXlt, notably the section ‘Details on POSIXlt’.

Examples

## FIXME: this should also work for regular (non-UTC) time zones.TZ<-"UTC"# Could be# d1 <- as.POSIXlt("2000-01-02 3:45", tz = TZ)# on systems (almost all) which have tm_zone.oldTZ<- Sys.getenv('TZ', unset="unset")Sys.setenv(TZ="UTC")d1<- as.POSIXlt("2000-01-02 3:45")d1$min<- d1$min+(0:16)*20L(f1<- format(d1))str(unclass(d1))# only $min is of length > 1df<- balancePOSIXlt(d1, fill.only=TRUE)# a "POSIXlt" objectstr(unclass(df))# all of length 17; 'min' unchangeddb<- balancePOSIXlt(d1, classed=FALSE)# a liststopifnot(identical(    unCfillPOSIXlt(d1),    balancePOSIXlt(d1, fill.only=TRUE, classed=FALSE)))str(db)# of length 17 *and* in rangeif(oldTZ=="unset") Sys.unsetenv('TZ')else Sys.setenv(TZ= oldTZ)

Description

basename removes all of the path up to and including the lastpath separator (if any).

dirname returns the part of thepath up to butexcluding the last path separator, or"." if there is no pathseparator.

Usage

basename(path)dirname(path)

Arguments

Details

tilde expansion of the path will be performed.

Trailing path separators are removed before dissecting the path,and fordirname any trailing file separators are removedfrom the result.

Value

A character vector of the same length aspath. A zero-lengthinput will give a zero-length output with no error.

Paths not containing any separators are taken to be in the currentdirectory, sodirname returns".".

If an element ofpath isNA, so is the result.

"" is not a valid pathname, but is returned unchanged.

Behaviour on Windows

On Windows this will accept either\ or/ as the pathseparator, butdirname will return a path using/(except if on a network share, when the leading\\ will bepreserved). Expect these only to be able to handle completepaths, and not for example just a network share or a drive.

UTF-8-encoded path names not valid in the current locale can be used.

Note

These are not wrappers for the POSIX system functions of the samenames: in particular they donot have the special handling ofthe path"/" and of returning"." for empty strings.

See Also

file.path,path.expand.

Examples

basename(file.path("","p1","p2","p3", c("file1","file2")))dirname(file.path("","p1","p2","p3","filename"))

Description

Bessel Functions of integer and fractional order, of firstand second kind,$J_{\nu }$Jν​ and$Y_{\nu }$Yν​, andModified Bessel functions (of first and third kind),$I_{\nu }$Iν​ and$K_{\nu }$Kν​.

Usage

besselI(x, nu, expon.scaled=FALSE)besselK(x, nu, expon.scaled=FALSE)besselJ(x, nu)besselY(x, nu)

Arguments

Details

Ifexpon.scaled = TRUE,$e^{-x}{I}_{\nu }(x)$e−xIν​(x),or$e^x{K}_{\nu }(x)$exKν​(x) are returned.

Forν<0, formulae 9.1.2 and 9.6.2 fromAbramowitz & Stegunare applied (which is probably suboptimal), except forbesselK which is symmetric innu.

The current algorithms will give warnings about accuracy loss forlarge arguments. In some cases, these warnings are exaggerated, andthe precision is perfect. For largenu, say in the order ofmillions, the current algorithms are rarely useful.

Value

Numeric vector with the (scaled, ifexpon.scaled = TRUE)values of the corresponding Bessel function.

The length of the result is the maximum of the lengths of theparameters. All parameters are recycled to that length.

Author(s)

Original Fortran code:W. J. Cody, Argonne National Laboratory
Translation to C and adaptation toR:Martin Maechler[email protected].

Source

The C code is a translation of Fortran routines fromhttps://netlib.org/specfun/ribesl, ‘⁠../rjbesl⁠’, etc.The four source code files for bessel[IJKY] each contain a paragraph“Acknowledgement” and “References”, a short summary ofwhich is

besselI

based on (code) by David J. Sookne, see Sookne (1973)...Modifications... An earlier version was published in Cody (1983).

besselJ

asbesselI

besselK

based on (code) by J. B. Campbell (1980)... Modifications...

besselY

draws heavily on Temme's Algol program for$Y$Y... and on Campbell's programs for$Y_{\nu }(x)$Yν​(x).... ... heavily modified.