Description

R utility functions

Details

This package contains a collection of utility functions.

For a completelist, uselibrary(help = "utils").

Author(s)

R Core Team and contributors worldwide

Maintainer: R Core Team[email protected]

Description

Compute the approximate string distance between character vectors.The distance is a generalized Levenshtein (edit) distance, giving theminimal possibly weighted number of insertions, deletions andsubstitutions needed to transform one string into another.

Usage

adist(x, y=NULL, costs=NULL, counts=FALSE, fixed=TRUE,      partial=!fixed, ignore.case=FALSE, useBytes=FALSE)

Arguments

Details

The (generalized) Levenshtein (or edit) distance between two stringss andt is the minimal possibly weighted number ofinsertions, deletions and substitutions needed to transformsintot (so that the transformation exactly matchest).This distance is computed forpartial = FALSE, currently usinga dynamic programming algorithm (see, e.g.,https://en.wikipedia.org/wiki/Levenshtein_distance) with spaceand time complexity$O(mn)$O(mn), where$m$m and$n$n are thelengths ofs andt, respectively. Additionally computingthe transformation sequence and counts is$O(\max (m,n))$O(max(m,n)).

The generalized Levenshtein distance can also be used for approximate(fuzzy) string matching, in which case one finds the substring oft with minimal distance to the patterns (which could betaken as a regular expression, in which case the principle of usingthe leftmost and longest match applies), see, e.g.,https://en.wikipedia.org/wiki/Approximate_string_matching. Thisdistance is computed forpartial = TRUE using ‘⁠tre⁠’ byVille Laurikari (https://github.com/laurikari/tre) andcorresponds to the distance used byagrep. In thiscase, the given cost values are coerced to integer.

Note that the costs for insertions and deletions can be different, inwhich case the distance betweens andt can be differentfrom the distance betweent ands.

Value

A matrix with the approximate string distances of the elements ofx andy, with rows and columns corresponding toxandy, respectively.

Ifcounts isTRUE, the transformation counts arereturned as the"counts" attribute of this matrix, as a3-dimensional array with dimensions corresponding to the elements ofx, the elements ofy, and the type of transformation(insertions, deletions and substitutions), respectively.Additionally, ifpartial = FALSE, the transformation sequencesare returned as the"trafos" attribute of the return value, ascharacter strings with elements ‘⁠M⁠’, ‘⁠I⁠’, ‘⁠D⁠’ and‘⁠S⁠’ indicating a match, insertion, deletion and substitution,respectively. Ifpartial = TRUE, the offsets (positions ofthe first and last element) of the matched substrings are returned asthe"offsets" attribute of the return value (with both offsets$-1$−1 in case of no match).

See Also

agrep for approximate string matching (fuzzy matching)using the generalized Levenshtein distance.

Examples

## Cf. https://en.wikipedia.org/wiki/Levenshtein_distanceadist("kitten","sitting")## To see the transformation counts for the Levenshtein distance:drop(attr(adist("kitten","sitting", counts=TRUE),"counts"))## To see the transformation sequences:attr(adist(c("kitten","sitting"), counts=TRUE),"trafos")## Cf. the examples for agrep:adist("lasy","1 lazy 2")## For a "partial approximate match" (as used for agrep):adist("lasy","1 lazy 2", partial=TRUE)

Description

Gives an audible or visual signal to the user.

Usage

alarm()

Details

alarm() works by sending a"\a" character to the console.On most platforms this will ring a bell, beep, or give some other signalto the user (unless standard output has been redirected).

It attempts to flush the console (seeflush.console).

Value

No useful value is returned.

Examples

alarm()

Description

apropos() returns a character vector giving the names ofobjects in the search list matching (as a regular expression)what.

find() returns where objects of a given name can be found.

Usage

apropos(what, where=FALSE, ignore.case=TRUE,        dot_internals=FALSE, mode="any")find(what, mode="any", numeric=FALSE, simple.words=TRUE)

Arguments

Details

Ifmode != "any" only those objects which are of modemodeare considered.

find is a different user interface for a similar task toapropos. By default (simple.words == TRUE),only whole names are matched. Unlikeapropos, matching isalways case-sensitive.

Unlike the default behaviour ofls, names whichbegin with a ‘⁠.⁠’ are included, but base ‘internal’ objectsare included only whendot_internals is true.

Value

Forapropos, a character vector sorted by name. Forwhere = TRUE this has names giving the (numerical) positions onthe search path.

Forfind, either a character vector of environment names or(fornumeric = TRUE) a numerical vector of positions on thesearch path with names the names of the corresponding environments.

Author(s)

Originally, Kurt Hornik and Martin Maechler (May 1997).

See Also

glob2rx to convert wildcard patterns to regular expressions.

objects for listing objects from one place,help.search for searching the help system,search for the search path.

Examples

require(stats)## Not run: apropos("lm")apropos("GLM")# severalapropos("GLM", ignore.case=FALSE)# not oneapropos("lq")cor<-1:pifind("cor")#> ".GlobalEnv"   "package:stats"find("cor", numeric=TRUE)# numbers with these namesfind("cor", numeric=TRUE, mode="function")# only the second onerm(cor)## Not run: apropos(".", mode = "list")  # includes many datasets# extraction/replacement methods (need a DOUBLE backslash '\\')apropos("\\[")# everything % not diff-ablelength(apropos("."))# those starting with 'pr'apropos("^pr")# the 1-letter thingsapropos("^.$")# the 1-2-letter thingsapropos("^..?$")# the 2-to-4 letter thingsapropos("^.{2,4}$")# frequencies of 8-and-more letter thingstable(nchar(apropos("^.{8,}$")))

Description

Determine positions of approximate string matches.

Usage

aregexec(pattern, text, max.distance=0.1, costs=NULL,         ignore.case=FALSE, fixed=FALSE, useBytes=FALSE)

Arguments

Details

aregexec provides a different interface to approximate stringmatching thanagrep (along the lines of the interfacesto exact string matching provided byregexec andgrep).

Note that by default,agrep performs literal matches,whereasaregexec performs regular expression matches.

Seeagrep andadist for more informationabout approximate string matching and distances.

Comparisons are byte-by-byte ifpattern or any element oftext is marked as"bytes".

Value

A list of the same length astext, each element of which iseither$-1$−1 if there is no match, or a sequence of integers withthe starting positions of the match and all substrings correspondingto parenthesized subexpressions ofpattern, with attribute"match.length" an integer vector giving the lengths of thematches (or$-1$−1 for no match).

See Also

regmatches for extracting the matched substrings.

Examples

## Cf. the examples for agrep.x<- c("1 lazy","1","1 LAZY")aregexec("laysy", x, max.distance=2)aregexec("(lay)(sy)", x, max.distance=2)aregexec("(lay)(sy)", x, max.distance=2, ignore.case=TRUE)m<- aregexec("(lay)(sy)", x, max.distance=2)regmatches(x, m)

Description

This function allows you to tile or cascade windows, or to minimize orrestore them (on Windows, i.e. when(.Platform$OS.type == "windows")).This may include windows not “belonging” toR.

Usage

arrangeWindows(action, windows, preserve=TRUE, outer=FALSE)

Arguments

Details

The actions are as follows:

"vertical"

Tile vertically.

"horizontal"

Tile horizontally.

"cascade"

Cascade the windows.

"minimize"

Minimize all of the windows.

"restore"

Restore all of the windows to normal size (not minimized, not maximized).

The tiling and cascading are done by the standard Windows API functions, but unlike those functions,they will apply to all of the windows in thewindows list.

By default,windows is set to the result ofgetWindowsHandles() (with one exception describedbelow). This will select windows belonging to the currentR process.However, if the global environment contains a variable named.arrangeWindowsDefaults, it will be used as the argument listinstead. See thegetWindowsHandles man page for adiscussion of the optional arguments to that function.

Whenaction = "restore" is used withwindows unspecified,minimized = TRUE is added to the argument list ofgetWindowsHandles so that minimized windows will be restored.

In MDI mode, by default tiling and cascading will happen within theRGUI frame. However, ifouter = TRUE, tiling is done on the systemdesktop. This will generally not give desirable results if anyR childwindows are included withinwindows.

Value

This function is called for the side effect of arranging the windows.The list of window handles is returned invisibly.

Note

This is only available on Windows.

Author(s)

Duncan Murdoch

See Also

getWindowsHandles

Examples

## Not run: ## Only available on Windows :arrangeWindows("v")# This default is useful only in SDI mode:  it will tile any Firefox window# along with the R windows.arrangeWindowsDefaults<- list(c("R","all"), pattern= c("","Firefox"))arrangeWindows("v")## End(Not run)

Description

askYesNo provides a standard way to ask the user a yes/no question. It provides a way for front-ends to substitute their own dialogs.

Usage

askYesNo(msg, default=TRUE,          prompts= getOption("askYesNo", gettext(c("Yes","No","Cancel"))),...)

Arguments

Details

askYesNo will accept case-independent partial matches to the prompts. If no responseis given the value ofdefault will be returned; if a non-emptystring that doesn't match any of the prompts is entered, an error will be raised.

If a function or single character string naming a functionis given forprompts, it will be called asfn(msg = msg, default = default, prompts = prompts, ...). OnWindows, the GUI uses the unexportedutils:::askYesNoWinDialogfunction for this purpose.

If strings (or a string such as"Y/N/C") are given asprompts, the choices will be mapped to lowercase for the non-default choices, and left as-is for the default choice.

Value

TRUE for yes,FALSE for no, andNA for cancel.

See Also

readline for more general user input.

Examples

if(interactive())    askYesNo("Do you want to use askYesNo?")

Description

Spell check given files via Aspell, Hunspell or Ispell.

Usage

aspell(files, filter, control= list(), encoding="unknown",       program=NULL, dictionaries= character())

Arguments

Details

The spell check programs employed must support the so-called Ispellpipe interface activated via command line option-a. Inaddition to the programs, suitable dictionaries need to be available.Seehttp://aspell.net,https://hunspell.github.io/ andhttps://www.cs.hmc.edu/~geoff/ispell.html, respectively, forobtaining the Aspell, Hunspell and (International) Ispell programs anddictionaries.

On Windows, Aspell is available viaMSYS2. One should use a non-Cygwinversion, e.g. packagemingw-w64-x86_64-aspell. The version builtagainst the Cygwin runtime (packageaspell) requires Unix lineendings in files and Unix-style paths, which is incompatible withaspell().

The currently available built-in filters are"Rd"(corresponding toRdTextFilter, with additional argumentignore allowing to give regular expressions for parts of thetext to be ignored for spell checking),"Sweave"(corresponding toSweaveTeXFilter),"R","pot","dcf" and"md".

Filter"R" is for R code and extracts the message stringconstants in calls tomessage,warning,stop,packageStartupMessage,gettext,gettextf, andngettext (the unnamed string constants for the firstfive, andfmt andmsg1/msg2 string constants,respectively, for the latter two).

Filter"pot" is for message string catalog ‘.pot’ files.Both have an argumentignore allowing to give regularexpressions for parts of message strings to be ignored for spellchecking: e.g., using"[ \t]'[^']*'[ \t[:punct:]]" ignores alltext inside single quotes.

Filter"dcf" is for files in Debian Control File format.The fields to keep can be controlled by argumentkeep (acharacter vector with the respective field names). By default,‘⁠Title⁠’ and ‘⁠Description⁠’ fields are kept.

Filter"md" is for files inMarkdown format(‘.md’ and ‘.Rmd’ files), and needs packagescommonmark andxml2 to be available.

The print method for the objects returned byaspell has anindent argument controlling the indentation of the positions ofpossibly misspelled words. The default is 2; Emacs users may find ituseful to use an indentation of 0 and visit output in grep-mode. Italso has averbose argument: when this is true, suggestions forreplacements are shown as well.

It is possible to employ additional R level dictionaries. Currently,these are files with extension ‘.rds’ obtained by serializingcharacter vectors of word lists usingsaveRDS. If suchdictionaries are employed, they are combined into a single word listfile which is then used as the spell checker's personal dictionary(option-p): hence, the default personal dictionary is notused in this case.

Value

A data frame inheriting fromaspell (which has a useful printmethod) with the information about possibly misspelled words.

References

Kurt Hornik and Duncan Murdoch (2011).“Watch your spelling!”The R Journal,3(2), 22–28.doi:10.32614/RJ-2011-014.

See Also

aspell-utils for utilities for spell checking packages.

Examples

## Not run:## To check all Rd files in a directory, (additionally) skipping the## \references sections.files<- Sys.glob("*.Rd")aspell(files, filter= list("Rd", drop="\\references"))## To check all Sweave filesfiles<- Sys.glob(c("*.Rnw","*.Snw","*.rnw","*.snw"))aspell(files, filter="Sweave", control="-t")## To check all Texinfo files (Aspell only)files<- Sys.glob("*.texi")aspell(files, control="--mode=texinfo")## End(Not run)## List the available R system dictionaries.Sys.glob(file.path(R.home("share"),"dictionaries","*.rds"))

Description

Utilities for spell checking packages via Aspell, Hunspell or Ispell.

Usage

aspell_package_Rd_files(dir,                        drop= c("\\abbr","\\acronym","\\author","\\references"),                        control= list(), program=NULL,                        dictionaries= character())aspell_package_vignettes(dir,                         control= list(), program=NULL,                         dictionaries= character())aspell_package_R_files(dir, ignore= character(), control= list(),                       program=NULL, dictionaries= character())aspell_package_C_files(dir, ignore= character(), control= list(),                       program=NULL, dictionaries= character())aspell_write_personal_dictionary_file(x, out, language="en",                                      program=NULL)

Arguments

Details

Functionsaspell_package_Rd_files,aspell_package_vignettes,aspell_package_R_files andaspell_package_C_files perform spell checking on the Rd files,vignettes, R files, and C-level messages of the package with rootdirectorydir. They determine the respective files, apply theappropriate filters, and run the spell checker.

Seeaspell for details on filters.

The C-level message string are obtained from the‘po/PACKAGE.pot’ message catalog file, withPACKAGEthe basename ofdir.See the section on ‘C-level messages’ in‘Writing R Extensions’ for more information.

When using Aspell, the vignette checking skips parameters and/oroptions of commands⁠\Sexpr⁠,⁠\citep⁠,⁠\code⁠,⁠\pkg⁠,⁠\proglang⁠ and⁠\samp⁠ (in addition to thewhat the Aspell TeX/LaTeX filter skips by default). Furthercommands can be skipped by adding⁠--add-tex-command⁠ options tothecontrol argument. E.g., to skip both option and parameterof⁠\mycmd⁠, add⁠--add-tex-command='mycmd op'⁠.

Suitable values forcontrol,program,dictionaries,drop andignore can also bespecified using a package defaults file which should go as‘defaults.R’ into the ‘.aspell’ subdirectory ofdir,and provides defaults via assignments of suitable named lists, e.g.,

vignettes <- list(control = "--add-tex-command='mycmd op'")

for vignettes (when using Aspell) and similarly assigning toRd_files,R_files andC_files for Rd files, Rfiles and C level message defaults.

Maintainers of packages using both English and American spelling willfind it convenient to pass control options--master=en_US and--add-extra-dicts=en_GB to Aspell and control options-d en_US,en_GB to Hunspell (provided that the correspondingdictionaries are installed).

Older versions ofR had no support for R level dictionaries, andhence provided the functionaspell_write_personal_dictionary_file to create (spell check)program-specific personal dictionary files from words to be accepted.The new mechanism is to use R level dictionaries, i.e., ‘.rds’files obtained by serializing character vectors of such words usingsaveRDS. For such dictionaries specified via thepackage defaults mechanism, elements with no path separator can be Rsystem dictionaries or dictionaries in the ‘.aspell’subdirectory.

See Also

aspell

List Available Packages atCRAN-like Repositories

Description

available.packages returns a matrix of details corresponding topackages currently available at one or more repositories. Thecurrent list of packages is downloaded over the internet (or copiedfrom a local mirror).

Usage

available.packages(contriburl= contrib.url(repos, type), method,                   fields= getOption("available_packages_fields"),                   type= getOption("pkgType"), filters=NULL,                   repos= getOption("repos"),                   ignore_repo_cache=FALSE, max_repo_cache_age,                   cache_user_dir=                       str2logical(Sys.getenv("R_PACKAGES_CACHE_USER_DIR",FALSE)),                   quiet=TRUE, verbose=FALSE,...)

Arguments

Details

The list of packages is either copied from a local mirror (specified by a‘⁠file://⁠’URI) or downloaded. If downloaded andignore_repo_cache is false (the default), the list is cachedfor theR session in a per-repository file intempdir()with a name like

repos_http%3a%2f%2fcran.r-project.org%2fsrc%2fcontrib.rds

The cached values are renewed when found to be too old, with the agelimit controlledvia argumentmax_repo_cache_age.This defaults to the current value of the environment variableR_AVAILABLE_PACKAGES_CACHE_CONTROL_MAX_AGE, or if unset, to3600 (one hour).

By default, the return value includes only packages whose version andOS requirements are met by the running version ofR, and only givesinformation on the latest versions of packages.

Argumentfilters can be used to select which of the packages on therepositories are reported. It is called with its default value(NULL) by functions such asinstall.packages: this valuecorresponds togetOption("available_packages_filters")and toc("R_version", "OS_type", "subarch", "duplicates") ifthat is unset or set toNULL.

The built-in filters are

"R_version"

Exclude packages whoseR versionrequirements are not met.

"OS_type"

Exclude packages whose OS requirement isincompatible with this version ofR: that is excludeWindows-only packages on a Unix-alike platformandvice versa.

"subarch"

For binary packages, exclude those withcompiled code that is not available for the currentsub-architecture, e.g. exclude packages only compiled for32-bit Windows on a 64-bit WindowsR.

"duplicates"

Only report the latest version where morethan one version is available, and only report the first-namedrepository (incontriburl) with the latest version if thatis in more than one repository.

"license/FOSS"

Include only packages for whichinstallation can proceed solely based on packages which can beverified as Free or Open Source Software (FOSS, e.g.,https://en.wikipedia.org/wiki/FOSS) employing the availablelicense specifications. Thus both the package and any packagesthat it depends on to load need to beknown to beFOSS.

Note that this does depend on the repository supplying licenseinformation.

"license/restricts_use"

Include only packages forwhich installation can proceed solely based on packages which areknown not to restrict use.

"CRAN"

UseCRAN versions in preference to versionsfrom other repositories (even if these have a higher versionnumber). This needs to be appliedbefore the default"duplicates" filter, so cannot be used withadd = TRUE.

If all the filters are from this set, then they can be specified as acharacter vector; otherwisefilters should be a list withelements which are character strings, user-defined functions oradd = TRUE (see below).

User-defined filters are functions which take a single argument, amatrix of the form returned byavailable.packages, andreturn a matrix consisting of a subset of the rows of the argument.

The special ‘filter’add = TRUE appends the otherelements of the filter list to the default filters.

Value

A character matrix with one row per package, row names the package names andcolumn names including"Package","Version","Priority","Depends","Imports","LinkingTo","Suggests","Enhances","File" and"Repository". Additional columns can bespecified using thefields argument.

Where provided by the repository, fields"OS_type","License","License_is_FOSS","License_restricts_use","Archs","MD5sum" and"NeedsCompilation" are reported for use by the filters andpackage management tools, includinginstall.packages.

See Also

packageStatus,update.packages,install.packages,download.packages,contrib.url.

The ‘R Installation and Administration’ manual for how toset up a repository.

Examples

## Count package licensesdb<- available.packages(repos= findCRANmirror("web"), filters="duplicates")table(db[,"License"])## Use custom filter function to only keep recommended packages## which do not require compilationavailable.packages(repos= findCRANmirror("web"),  filters= list(    add=TRUE,function(db) db[db[,"Priority"]%in%"recommended"&                     db[,"NeedsCompilation"]=="no",]))## Not run:## Restrict install.packages() (etc) to known-to-be-FOSS packagesoptions(available_packages_filters=  c("R_version","OS_type","subarch","duplicates","license/FOSS"))## oroptions(available_packages_filters= list(add=TRUE,"license/FOSS"))## Give priority to released versions on CRAN, rather than development## versions on R-Forge etc.options(available_packages_filters=     c("R_version","OS_type","subarch","CRAN","duplicates"))## End(Not run)

Description

RunR non-interactively with input frominfile andsend output (stdout/stderr) to another file.

Usage

R CMD BATCH[options] infile[outfile]

Arguments

Details

UseR CMD BATCH --help to be reminded of the usage.

By default, the input commands are printed along with the output. Tosuppress this behavior, addoptions(echo = FALSE) at thebeginning ofinfile, or use option--no-echo.

Theinfile can have end of line marked byLF orCRLF (but notjustCR), and files with an incomplete last line (missing end of line(EOL) mark) are processed correctly.

A final expression ‘⁠proc.time()⁠’ will be executed after the inputscript unless the latter callsq(runLast = FALSE) or is aborted.This can be suppressed by the option--no-timing.

Additional options can be set by the environment variableR_BATCH_OPTIONS: these come after the default options (see thedescription of theoptions argument) and before any optionsgiven on the command line.

Note

On Unix-alikes only: UnlikeSplus BATCH, this does not run theRprocess in the background.In most shells,

R CMD BATCH [options] infile [outfile] &

will do so.

Description

Functionality for representing and manipulating bibliographicinformation in enhanced BibTeX style.

Usage

bibentry(bibtype, textVersion=NULL, header=NULL, footer=NULL,         key=NULL,..., other= list(),         mheader=NULL, mfooter=NULL)## S3 method for class 'bibentry'print(x, style="text", .bibstyle,      bibtex= length(x)<= getOption("citation.bibtex.max",1),...)## S3 method for class 'bibentry'format(x, style="text", .bibstyle=NULL,       bibtex= length(x)<=1,       citMsg= missing(bibtex),       sort=FALSE, macros=NULL,...)## S3 method for class 'bibentry'sort(x, decreasing=FALSE, .bibstyle=NULL, drop=FALSE,...)## S3 method for class 'citation' print(x, style="citation",...)## S3 method for class 'citation'format(x, style="citation",...)## S3 method for class 'bibentry'toBibtex(object, escape=FALSE,...)

Arguments

Details

The bibentry objects created bybibentry can represent anarbitrary positive number of references. One can usec() tocombine bibentry objects, and hence in particular build a multiplereference object from single reference ones. Alternatively, one canusebibentry to directly create a multiple reference object byspecifying the arguments as lists of character strings.

Theprint method for bibentry objects is based on acorrespondingformat method and provides a choicebetween seven different styles:plain text (style"text"),BibTeX ("bibtex"),a mixture of plain text and BibTeX as traditionally used for citations("citation"),HTML ("html"),LaTeX ("latex"),R code ("R"),and a simple copy of thetextVersion elements (style"textVersion").

The"text","html" and"latex" styles make useof the.bibstyle argument: a style defined by thebibstyle function for rendering the bibentry into(intermediate) Rd format.The Rd format uses markup commands documented in the ‘Rd format’section of the ‘Writing R Extensions’ manual, e.g.⁠\bold⁠.In addition, one can use themacros argument toprovide additional (otherwise unknown, presumably LaTeX-style) Rdmacros, either by giving the path to a file with Rd macros to beloaded vialoadRdMacros, or an object with macrosalready loaded.Note that the"latex" result may contain commands from theLaTeX style file ‘Rd.sty’ shipped withR;put⁠\usepackage{Rd}⁠ in the preamble of a LaTeX documentto make these available when compiling,e.g. withtexi2pdf.

When printing bibentry objects in citation style, aheader/footer for each item can be displayed as well asamheader/mfooter for the whole vector of references.

For formatting as R code,a choice between giving a character vector with onebibentry()call for each bibentry (as commonly used in ‘CITATION’ files), ora character string with one collapsed call, obtained by combining theindividual calls withc() if there is more than one bibentry.This can be controlled by passing the argumentcollapse=FALSE(default) orTRUE, respectively, to theformat() method.(Printing in R style always collapses to a single call.)

It is possible to subscript bibentry objects by their keys (which areused for character subscripts if the names areNULL).

There is also atoBibtex method for direct conversion toBibTeX.

As ofR 4.3.0, there is also atransform method whichallows to directly use the current fields, see the examples.

Value

bibentry produces an object of class"bibentry".

Entry Types

bibentry creates"bibentry" objects, which are modeledafter BibTeX entries. The entry should be a valid BibTeX entry type,e.g.,

Article:

An article from a journal or magazine.

Book:

A book with an explicit publisher.

InBook:

A part of a book, which may be a chapter (or sectionor whatever) and/or a range of pages.

InCollection:

A part of a book having its own title.

InProceedings:

An article in a conference proceedings.

Manual:

Technical documentation like a software manual.

MastersThesis:

A Master's thesis.

Misc:

Use this type when nothing else fits.

PhdThesis:

A PhD thesis.

Proceedings:

The proceedings of a conference.

TechReport:

A report published by a school or otherinstitution, usually numbered within a series.

Unpublished:

A document having an author and title, but notformally published.

Entry Fields

The... argument ofbibentry can be any number ofBibTeX fields, including

address:

The address of the publisher or other type ofinstitution.

author:

The name(s) of the author(s), either as aperson object, or as a character string whichas.person correctly coerces to such.

booktitle:

Title of a book, part of which is being cited.

chapter:

A chapter (or section or whatever) number.

doi:

TheDOI(https://en.wikipedia.org/wiki/Digital_Object_Identifier)for the reference.

editor:

Name(s) of editor(s), same format asauthor.

institution:

The publishing institution of a technical report.

journal:

A journal name.

note:

Any additional information that can help the reader.The first word should be capitalized.

number:

The number of a journal, magazine, technical report,or of a work in a series.

pages:

One or more page numbers or range of numbers.

publisher:

The publisher's name.

school:

The name of the school where a thesis was written.

series:

The name of a series or set of books.

title:

The work's title.

url:

A URL for the reference.(If the URL is an expandedDOI, we recommend to use the‘⁠doi⁠’ field with the unexpandedDOI instead.)

volume:

The volume of a journal or multi-volume book.

year:

The year of publication.

See Also

person

Examples

## R referencerref<- bibentry(   bibtype="Manual",   title="R: A Language and Environment for Statistical Computing",   author= person("R Core Team"),   organization="R Foundation for Statistical Computing",   address="Vienna, Austria",   year=2014,   url="https://www.R-project.org/")## Different printing stylesprint(rref)print(rref, style="bibtex")print(rref, style="citation")print(rref, style="html")print(rref, style="latex")print(rref, style="R")## References for boot package and associated bookbref<- c(   bibentry(     bibtype="Manual",     title="boot: Bootstrap R (S-PLUS) Functions",     author= c(       person("Angelo","Canty", role="aut",         comment="S original"),       person(c("Brian","D."),"Ripley", role= c("aut","trl","cre"),         comment="R port, author of parallel support",         email="[email protected]")),     year="2012",     note="R package version 1.3-4",     url="https://CRAN.R-project.org/package=boot",     key="boot-package"),   bibentry(     bibtype="Book",     title="Bootstrap Methods and Their Applications",     author= as.person("Anthony C. Davison [aut], David V. Hinkley [aut]"),     year="1997",     publisher="Cambridge University Press",     address="Cambridge",     isbn="0-521-57391-2",     url="http://statwww.epfl.ch/davison/BMA/",     key="boot-book"))## Combining and subsettingc(rref, bref)bref[2]bref["boot-book"]## Extracting fieldsbref$authorbref[1]$authorbref[1]$author[2]$email## Field names are case-insensitiverref$Yearrref$Year<- R.version$yearstopifnot(identical(rref$year, R.version$year))## Convert to BibTeXtoBibtex(bref)## Transformtransform(rref, address= paste0(address,", Europe"))## BibTeX reminder message (in case of >= 2 refs):print(bref, style="citation")## Format in R style## One bibentry() call for each bibentry:writeLines(paste(format(bref,"R"), collapse="\n\n"))## One collapsed call:writeLines(format(bref,"R", collapse=TRUE))

Description

ThebrowseEnv function opens a browser with list of objectscurrently insys.frame() environment.

Usage

browseEnv(envir= .GlobalEnv, pattern,          excludepatt="^last\\.warning",          html= .Platform$GUI!="AQUA",          expanded=TRUE, properties=NULL,          main=NULL, debugMe=FALSE)

Arguments

Details

Very experimental code: displays a static HTML page on all platformsexceptR.app on macOS.

Only allows one level of recursion into object structures.

It can be generalized. See sources for details.Most probably, this should rather work through using thetkWidgetpackage (fromhttps://www.bioconductor.org).

See Also

str,ls.

Examples

if(interactive()){## create some interesting objects :   ofa<- ordered(4:1)   ex1<- expression(1+0:9)   ex3<- expression(u, v,1+0:9)   example(factor, echo=FALSE)   example(table, echo=FALSE)   example(ftable, echo=FALSE)   example(lm, echo=FALSE, ask=FALSE)   example(str, echo=FALSE)## and browse them:   browseEnv()## a (simple) function's environment:   af12<- approxfun(1:2,1:2, method="const")   browseEnv(envir= environment(af12))}

Description

Load a given URL into an HTML browser.

Usage

browseURL(url, browser= getOption("browser"),          encodeIfNeeded=FALSE)

Arguments

Details

On Unix-alikes:

The default browser is set by option"browser", in turn set bythe environment variableR_BROWSER which is by default set infile ‘R_HOME/etc/Renviron’ to a choicemade manually or automatically whenR was configured. (SeeStartup for where to override that default value.)To suppress showing URLs altogether, use the value"false".

On many platforms it is best to set option"browser" to ageneric program/script and let that invoke the user's choice ofbrowser. For example, on macOS useopen and on many otherUnix-alikes usexdg-open.

Ifbrowser supports remote control andR knows how to performit, the URL is opened in any already-running browser or a new one ifnecessary. This mechanism currently is available for browsers whichsupport the"-remote openURL(...)" interface (which includesMozilla and Opera), Galeon, KDE konqueror (via kfmclient) andthe GNOME interface to Mozilla. (Firefox has dropped support, butdefaults to using an already-running browser.) Note that the type ofbrowser is determined from its name, so this mechanism will only beused if the browser is installed under its canonical name.

Because"-remote" will use any browser displaying on the Xserver (whatever machine it is running on), the remote controlmechanism is only used ifDISPLAY points to the local host.This may not allow displaying more than one URL at a time from aremote host.

It is the caller's responsibility to encodeurl if necessary(seeURLencode).

To suppress showing URLs altogether, setbrowser = "false".

The behaviour for argumentsurl which are not URLs isplatform-dependent. Some platforms accept absolute file paths; feweraccept relative file paths.

On Windows:

The default browser is set by option"browser", in turn set bythe environment variableR_BROWSER if that is set, otherwise toNULL.To suppress showing URLs altogether, use the value"false".

Some browsers have required ‘⁠:⁠’ be replaced by ‘⁠|⁠’ in filepaths: others do not accept that. All seem to accept ‘⁠\⁠’ as apath separator even though the RFC1738 standard requires ‘⁠/⁠’.

To suppress showing URLs altogether, setbrowser = "false".

URL schemes

Which URL schemes are accepted is platform-specific: expect‘⁠http://⁠’, ‘⁠https://⁠’ and ‘⁠ftp://⁠’ to work, but‘⁠mailto:⁠’ may or may not (and if it does may not use the user'spreferred email client). However, modern browsers are unlikely to handle‘⁠ftp://⁠’.

For the ‘⁠file://⁠’ scheme the format accepted (if any) can depend onboth browser and OS.

Examples

## Not run:## for KDE users who want to open files in a new taboptions(browser="kfmclient newTab")browseURL("https://www.r-project.org")## On Windows-only, something likebrowseURL("file://d:/R/R-2.5.1/doc/html/index.html",          browser="C:/Program Files/Mozilla Firefox/firefox.exe")## End(Not run)

Description

List available vignettes in an HTML browser with links to PDF,LaTeX/Noweb source, and (tangled) R code (if available).

Usage

browseVignettes(package=NULL, lib.loc=NULL, all=TRUE)## S3 method for class 'browseVignettes'print(x,...)

Arguments

Details

FunctionbrowseVignettes returns an object of the same class;the print method displays it as an HTML page in a browser (usingbrowseURL).

See Also

browseURL,vignette

Examples

## List vignettes from all *attached* packagesbrowseVignettes(all=FALSE)## List vignettes from a specific packagebrowseVignettes("grid")

Description

Invokes an editor or email program to write a bug report or opens aweb page for bug submission. Some standard information on the currentversion and configuration ofR are included automatically.

Usage

bug.report(subject="",  address,           file="R.bug.report", package=NULL, lib.loc=NULL,...)

Arguments

Details

Ifpackage isNULL or a base package, this opens the Rbugs tracker athttps://bugs.r-project.org/.

Ifpackage is specified, it is assumed that the bug report isabout that package, and parts of its ‘DESCRIPTION’ file are addedto the standard information. If the package has a non-emptyBugReports field in the ‘DESCRIPTION’ file specifying theURL of a webpage, that URL will be opened usingbrowseURL, otherwise an email directed to the packagemaintainer will be generated usingcreate.post. Ifthere is any other form ofBugReports field or aContactfield, this is examined as it may provide a preferred email address.

Value

Nothing useful.

When is there a bug?

IfR executes an illegal instruction, or dies with an operatingsystem error message that indicates a problem in the program (asopposed to something like “disk full”), then it is certainly abug.

Taking forever to complete a command can be a bug, but you must makecertain that it was reallyR's fault. Some commands simply take along time. If the input was such that you KNOW it should have beenprocessed quickly, report a bug. If you don't know whether thecommand should take a long time, find out by looking in the manual orby asking for assistance.

If a command you are familiar with causes anR error message in acase where its usual definition ought to be reasonable, it is probablya bug. If a command does the wrong thing, that is a bug. But be sureyou know for certain what it ought to have done. If you aren'tfamiliar with the command, or don't know for certain how the commandis supposed to work, then it might actually be working right. Ratherthan jumping to conclusions, show the problem to someone who knows forcertain.

Finally, a command's intended definition may not be best forstatistical analysis. This is a very important sort of problem, butit is also a matter of judgement. Also, it is easy to come to such aconclusion out of ignorance of some of the existing features. It isprobably best not to complain about such a problem until you havechecked the documentation in the usual ways, feel confident that youunderstand it, and know for certain that what you want is notavailable. The mailing list[email protected] is a betterplace for discussions of this sort than the bug list.

If you are not sure what the command is supposed to doafter a careful reading of the manual this indicates a bug in themanual. The manual's job is to make everything clear. It is just asimportant to report documentation bugs as program bugs.

If the online argument list of a function disagrees with the manual,one of them must be wrong, so report the bug.

How to report a bug

When you decide that there is a bug, it is important to report it andto report it in a way which is useful. What is most useful is anexact description of what commands you type, from when you startRuntil the problem happens. Always include the version ofR, machine,and operating system that you are using; typeversion inR toprint this. To help us keep track of which bugs have been fixed andwhich are still open please send a separate report for each bug.

The most important principle in reporting a bug is to report FACTS,not hypotheses or categorizations. It is always easier to report thefacts, but people seem to prefer to strain to posit explanations andreport them instead. If the explanations are based on guesses abouthowR is implemented, they will be useless; we will have to try tofigure out what the facts must have been to lead to suchspeculations. Sometimes this is impossible. But in any case, it isunnecessary work for us.

For example, suppose that on a data set which you know to be quitelarge the commanddata.frame(x, y, z, monday, tuesday) neverreturns. Do not report thatdata.frame() fails for large datasets. Perhaps it fails when a variable name is a day of the week. Ifthis is so then when we got your report we would try out thedata.frame() command on a large data set, probably with no dayof the week variable name, and not see any problem. There is no way inthe world that we could guess that we should try a day of the weekvariable name.

Or perhaps the command fails because the last command you used was a[ method that had a bug causingR's internal data structuresto be corrupted and making thedata.frame() command fail fromthen on. This is why we need to know what other commands you havetyped (or read from your startup file).

It is very useful to try and find simple examples that produceapparently the same bug, and somewhat useful to find simple examplesthat might be expected to produce the bug but actually do not. If youwant to debug the problem and find exactly what caused it, that iswonderful. You should still report the facts as well as anyexplanations or solutions.

InvokingR with the--vanilla option may help in isolating abug. This ensures that the site profile and saved data files are notread.

A bug report can be generated using the functionbug.report().For reports onR this will open the Web page athttps://bugs.r-project.org/: for a contributed package it willopen the package's bug tracker Web page or help you compose an emailto the maintainer.

Bug reports oncontributed packages should not be sent to theR bug tracker: rather make use of thepackage argument.

Author(s)

This help page is adapted from the Emacs manual and the R FAQ

See Also

help.request which you possibly should trybeforebug.report.

create.post, which handles emailing reports.

The R FAQ, alsosessionInfo() from which you may addto the bug report.

Description

Evaluates its arguments with the output being returned as a characterstring or sent to a file. Related tosink similarly to howwith is related toattach.

Usage

capture.output(..., file=NULL, append=FALSE,               type= c("output","message"), split=FALSE)

Arguments

Details

It works viasink(<file connection>) and hence theR codeindots mustnot interfere with the connection (e.g., bycallingcloseAllConnections()).

An attempt is made to write output as far as possible tofileif there is an error in evaluating the expressions, but forfile = NULL all output will be lost.

Messages sent tostderr() (including those frommessage,warning andstop)are captured bytype = "message". Note that this can be“unsafe” and should only be used with care.

Value

A character string (iffile = NULL), or invisibleNULL.

See Also

sink,textConnection

Examples

require(stats)glmout<- capture.output(summary(glm(case~ spontaneous+induced,                                     data= infert, family= binomial())))glmout[1:5]capture.output(1+1,2+2)capture.output({1+1;2+2})## Not run: ## on Unix-alike with a2ps availableop<- options(useFancyQuotes=FALSE)pdf<- pipe("a2ps -o - | ps2pdf - tempout.pdf","w")capture.output(example(glm), file= pdf)close(pdf); options(op); system("evince tempout.pdf &")## End(Not run)

Description

fileSnapshot takes a snapshot of a selection of files,recording summary information about each.changedFilescompares two snapshots, or compares one snapshot to the current stateof the file system. The snapshots need not be the same directory;this could be used to compare two directories.

Usage

fileSnapshot(path=".", file.info=TRUE, timestamp=NULL,     md5sum=FALSE, digest=NULL, full.names= length(path)>1,...) changedFiles(before, after, path= before$path, timestamp= before$timestamp,     check.file.info= c("size","isdir","mode","mtime"),     md5sum= before$md5sum, digest= before$digest,     full.names= before$full.names,...)## S3 method for class 'fileSnapshot'print(x, verbose=FALSE,...)## S3 method for class 'changedFiles'print(x, verbose=FALSE,...)

Arguments

Details

ThefileSnapshot function useslist.files toobtain a list of files, and depending on thefile.info,md5sum, anddigest arguments, records information abouteach file.

ThechangedFiles function compares two snapshots.

If thetimestamp argument tofileSnapshot is length 1, afile with that name is created. If it is length 1 inchangedFiles, thefile_test function is used tocompare the age of all files common to bothbefore andafter to it. This test may be unreliable: it compares thecurrent modification time of theafter files to the timestamp;that may not be the same as the modification time when theafter snapshot was taken. It may also give incorrect resultsif the clock on the file system holding the timestamp differs from theone holding the snapshot files.

If thecheck.file.info argument contains a non-empty charactervector, the indicated columns from the result of a call tofile.info will be compared.

Ifmd5sum isTRUE,fileSnapshot will call thetools::md5sum function to record the 32 byte MD5checksum for each file, andchangedFiles will compare thevalues. Thedigest argument allows users to provide their owndigest function.

Value

fileSnapshot returns an object of class"fileSnapshot".This is a list containing the fields

changedFiles produces an object of class"changedFiles".This is a list containing

print methods are defined for each of these types. Theprint method for"fileSnapshot" objectsdisplays the arguments used to produce them, while the one for"changedFiles" displays theadded,deleted andchanged fields if non-empty, and a submatrix of thechanges matrix containing all of theTRUE values.

Author(s)

Duncan Murdoch, using suggestions from Karl Millar and others.

See Also

file.info,file_test,md5sum.

Examples

# Create some files in a temporary directorydir<- tempfile()dir.create(dir)writeBin(1L, file.path(dir,"file1"))writeBin(2L, file.path(dir,"file2"))dir.create(file.path(dir,"dir"))# Take a snapshotsnapshot<- fileSnapshot(dir, timestamp= tempfile("timestamp"), md5sum=TRUE)# Change one of the files.writeBin(3L:4L, file.path(dir,"file2"))# Display the detected changes.  We may or may not see mtime change...changedFiles(snapshot)changedFiles(snapshot)$changes

Description

An interface to the (C99) wide character classification functions in use.

Usage

charClass(x, class)

Arguments

Details

The classification into character classes is platform-dependent. Theclasses are determined by internal tables on Windows and (optionallybut by default) on macOS and AIX.

The character classes are interpreted as follows:

"alnum"

Alphabetic or numeric.

"alpha"

Alphabetic.

"blank"

Space or tab.

"cntrl"

Control characters.

"digit"

Digits0-9.

"graph"

Graphical characters (printable charactersexcept whitespace).

"lower"

Lower-case alphabetic.

"print"

Printable characters.

"punct"

Punctuation characters. Some platforms treat allnon-alphanumeric graphical characters as punctuation.

"space"

Whitespace, including tabs, form and linefeeds and carriage returns. Some OSes include non-breakingspaces, some exclude them.

"upper"

Upper-case alphabetic.

"xdigit"

Hexadecimal character, one of0-9A-fa-f.

Alphabetic characters contain all lower- and upper-case ones and someothers (for example, those in ‘title case’).

Whether a character is printable is used to decide whether to escapeit when printing – see the help forprint.default.

Ifx is a character string it should either be ASCII or declaredas UTF-8 – seeEncoding.

charClass was added inR 4.1.0. A less direct way to examinecharacter classes which also worked in earlier versions is to usesomething likegrepl("[[:print:]]", intToUtf8(x)) – however,the regular-expression code might not use the same classificationfunctions as printing and on macOS used not to.

Value

A logical vector of the length the number of characters or integers inx.

Note

Non-ASCII digits are excluded by the C99 standard from the class"digit": most platforms will have them as alphabetic.

It is an assumption that the system's wide character classificationfunctions are coded in Unicode points, but this is known to be truefor all recent platforms.

The classification may depend on the locale even on one platform.

See Also

Character classes are used inregular expressions.

The OS'sman pages foriswctype andwctype.

Examples

x<- c(48:70,32,0xa0)# Last is non-breaking spacecl<- c("alnum","alpha","blank","digit","graph","punct","upper","xdigit")X<- lapply(cl,function(y) charClass(x,y)); names(X)<- clX<- as.data.frame(X); row.names(X)<- sQuote(intToUtf8(x, multiple=TRUE))XcharClass("ABC123","alpha")## Some accented capital Greek characters(x<-"\u0386\u0388\u0389")charClass(x,"upper")## How many printable characters are there? (Around 280,000 in Unicode 13.)## There are 2^21-1 possible Unicode points (most not yet assigned).pr<- charClass(1:0x1fffff,"print") table(pr)

Description

Use a Windows shell folder widget to choose a folder interactively.

Usage

choose.dir(default="", caption="Select folder")

Arguments

Details

This brings up the Windows shell folder selection widget. With thedefaultdefault = "", ‘My Computer’ (or similar) isinitially selected.

To workaround a bug, on Vista and later only folders under‘Computer’ are accessible via the widget.

Value

A length-one character vector, characterNA if‘Cancel’ was selected.

Note

This is only available on Windows.

See Also

choose.files (on Windows) andfile.choose(on all platforms).

Examples

if(interactive()&& .Platform$OS.type=="windows")        choose.dir(getwd(),"Choose a suitable folder")

Description

Use a Windows file dialog to choose a list of zero or more filesinteractively.

Usage

choose.files(default="", caption="Select files",             multi=TRUE, filters= Filters,             index= nrow(Filters))Filters

Arguments

Details

Unlikefile.choose,choose.files will alwaysattempt to return a character vector giving a list of files. If theuser cancels the dialog, then zero files are returned, whereasfile.choose would signal an error.choose.dirchooses a directory.

Windows file dialog boxes include a list of ‘filters’, which allowthe file selection to be limited to files of specific types.Thefilters argument tochoose.files allows the listof filters to be set. It should be ann by2 charactermatrix. The first column gives, for each filter, the description theuser will see, while the second column gives the mask(s) to selectthose files. If more than one mask is used, separate them bysemicolons, with no spaces. Theindex argument chooses whichfilter will be used initially.

Filters is a matrix giving the descriptions and masks forthe file types thatR knows about. Print it to see typical formatsfor filter specifications. The examples below show how particularfilters may be selected.

If you would like to display files in a particular directory,give a fully qualified file mask (e.g.,"c:\\*.*")in thedefault argument. If a directory is not given, thedialog will start in the current directory the first time, andremember the last directory used on subsequent invocations.

There is a buffer limit on the total length of the selected filenames:it is large but this function is not intended to select thousands offiles, when the limit might be reached.

Value

A character vector giving zero or more file paths.

Note

This is only available on Windows.

See Also

file.choose,choose.dir.

Sys.glob orlist.files to select multiplefiles by pattern.

Examples

if(interactive()&& .Platform$OS.type=="windows")       choose.files(filters= Filters[c("zip","All"),])

Description

Interact with the user to choose a Bioconductor mirror.

Usage

chooseBioCmirror(graphics= getOption("menu.graphics"), ind=NULL,                 local.only=FALSE)

Arguments

Details

This sets theoption"BioC_mirror": it is usedbefore a call tosetRepositories. The out-of-the-boxdefault for that option isNULL, which currently corresponds tothe mirrorhttps://bioconductor.org.

The ‘Bioconductor (World-wide)’ ‘mirror’ is a network ofmirrors providing reliable world-wide access; other mirrors mayprovide faster access on a geographically local scale.

ind chooses a row in‘R_HOME/doc/BioC_mirrors.csv’,by number.

Value

None: this function is invoked for itsside effect of updatingoptions("BioC_mirror").

See Also

setRepositories,chooseCRANmirror.

Description

Interact with the user to choose a CRAN mirror.

Usage

chooseCRANmirror(graphics= getOption("menu.graphics"), ind=NULL,                 local.only=FALSE)getCRANmirrors(all=FALSE, local.only=FALSE)

Arguments

Details

A list of mirrors is stored in file‘R_HOME/doc/CRAN_mirrors.csv’, but first an on-linelist of current mirrors is consulted, and the file copy used only ifthe on-line list is inaccessible.

chooseCRANmirror is called by a Windows GUI menu item and bycontrib.url if it finds the initial dummy value ofoptions("repos").

HTTPS mirrors with mirroring overssh will be offered inpreference to other mirrors (which are listed in a sub-menu).

ind chooses a row in the list of current mirrors, by number. Itis best used withlocal.only = TRUE and row numbers in‘R_HOME/doc/CRAN_mirrors.csv’.

Value

None forchooseCRANmirror(), this function is invoked for itsside effect of updatingoptions("repos").

getCRANmirrors() returns a data frame with mirror information.

See Also

setRepositories,findCRANmirror,chooseBioCmirror,contrib.url.

Description

How to citeR andR packages in publications.

Usage

citation(package="base", lib.loc=NULL, auto=NULL)readCitationFile(file, meta=NULL)citHeader(...)citFooter(...)

Arguments

Details

TheR core development team and the very active community of packageauthors have invested a lot of time and effort in creatingR as it istoday. Please give credit where credit is due and citeR andRpackages when you use them for data analysis.

Usecitation() (without arguments) for information on how tocite the base R system in publications.

Ifcitation() is called withpackage the name of anon-base package, as controlled by theauto argument it eitherreturns the information contained in the package ‘CITATION’ fileor auto-generates citation information from the package‘DESCRIPTION’ file. By default (auto = NULL), the‘CITATION’ file is used if it exists, in which case it is readviareadCitationFile withmeta equal topackageDescription(package, lib.loc). One can forceauto-generation viaauto = TRUE.

The auto-generated citation includesURLs for packagesinstalled from the standard repositories CRAN and Bioconductor andfrom development platforms such as GitHub, GitLab, orR-Forge. In case of CRAN and Bioconductor,DOIs areincluded as well.

Packages can use an ‘⁠Authors@R⁠’ field in their‘DESCRIPTION’ to provide (R code giving) aperson object with a refined, machine-readabledescription of the package “authors” (in particular specifyingtheir precise roles). Only those with an author role will beincluded in the auto-generated citation.

If the object returned bycitation() contains only one reference,the associated print method shows both a text version and a BibTeXentry for it. If a package has more than one reference then only thetext versions are shown. This threshold is controlled byoptions("citation.bibtex.max").The BibTeX versions can also be obtained usingfunctiontoBibtex() (see the examples below).

The ‘CITATION’ file of an R package should be placed in the‘inst’ subdirectory of the package source. The file is an Rsource file and may contain arbitrary R commands includingconditionals and computations. FunctionreadCitationFile() isused bycitation() to extract the information in‘CITATION’ files. The file issource()ed by the Rparser in a temporary environment and all resulting bibliographicobjects (specifically, inheriting from"bibentry") arecollected.These are typically produced by one or morebibentry()calls, optionally preceded by acitHeader() and followedby acitFooter() call.One can include an auto-generated package citation in the‘CITATION’ file viacitation(auto = meta).

readCitationFile makes use of theEncoding element (ifany) ofmeta to determine the encoding of the file.

Value

An object of class"citation", inheriting from class"bibentry"; see there, notably for theprint andformat methods.

citHeader andcitFooter return an empty"bibentry" storing “outer” header/footer textfor the package citation.

See Also

bibentry

Examples

## the basic R referencecitation()## extract the BibTeX entry from the return valuex<- citation()toBibtex(x)## references for a packagecitation("lattice")citation("lattice", auto=TRUE)# request the Manual-type referencecitation("foreign")## a CITATION file with more than one bibentry:file.show(system.file("CITATION", package="mgcv"))cm<- citation("mgcv")cm# header, text references, plus "reminder" about getting BibTeXprint(cm, bibtex=TRUE)# each showing its bibtex code## a CITATION file including citation(auto = meta)file.show(system.file("CITATION", package="nlme"))citation("nlme")

Description

Cite abibentry object in text. Thecite() functionuses thecite() function from the defaultbibstyle if present, orciteNatbib() if not.citeNatbib() uses a style similar to that used by the LaTeXpackage ‘⁠natbib⁠’.

Usage

cite(keys, bib,...)citeNatbib(keys, bib, textual=FALSE, before=NULL, after=NULL,           mode= c("authoryear","numbers","super"),           abbreviate=TRUE, longnamesfirst=TRUE,           bibpunct= c("(",")",";","a","",","), previous)

Arguments

Details

Argument names are chosen based on the documentation for the LaTeX ‘⁠natbib⁠’package. See that documentation for the interpretation of thebibpunct entries.

The entries inbibpunct are as follows:

1. The left delimiter.

2. The right delimiter.

3. The separator between references within a citation.

4. An indicator of the “mode”:"n" for numbers,"s" for superscripts, anything else for author-year.

5. Punctuation to go between the author and year.

6. Punctuation to go between years when authorship is suppressed.

Note that ifmode is specified, it overrides themode specification inbibpunct[4]. Partial matching is used formode.

The defaults forciteNatbib have been chosen to match theJSS style, andby default these are used incite. Seebibstylefor how to set a different default style.

Value

A single element character string is returned, containing the citation.

Author(s)

Duncan Murdoch

Examples

## R referencerref<- bibentry(   bibtype="Manual",   title="R: A Language and Environment for Statistical Computing",   author= person("R Core Team"),   organization="R Foundation for Statistical Computing",   address="Vienna, Austria",   year=2013,   url="https://www.R-project.org/",   key="R")## References for boot package and associated bookbref<- c(   bibentry(     bibtype="Manual",     title="boot: Bootstrap R (S-PLUS) Functions",     author= c(       person("Angelo","Canty", role="aut",         comment="S original"),       person(c("Brian","D."),"Ripley", role= c("aut","trl","cre"),         comment="R port, author of parallel support",         email="[email protected]")),     year="2012",     note="R package version 1.3-4",     url="https://CRAN.R-project.org/package=boot",     key="boot-package"),   bibentry(     bibtype="Book",     title="Bootstrap Methods and Their Applications",     author= as.person("Anthony C. Davison [aut], David V. Hinkley [aut]"),     year="1997",     publisher="Cambridge University Press",     address="Cambridge",     isbn="0-521-57391-2",     url="http://statwww.epfl.ch/davison/BMA/",     key="boot-book"))## Combine and citerefs<- c(rref, bref)cite("R, boot-package", refs)## Cite numericallysavestyle<- tools::getBibstyle()tools::bibstyle("JSSnumbered", .init=TRUE,         fmtPrefix=function(paper) paste0("[", paper$.index,"]"),         cite=function(key, bib,...)         citeNatbib(key, bib, mode="numbers",             bibpunct= c("[","]",";","n","",","),...))cite("R, boot-package", refs, textual=TRUE)refs## restore the old styletools::bibstyle(savestyle, .default=TRUE)

Description

Old interface providing functionality for specifying bibliographic information in enhanced BibTeX style. Since R 2.14.0 this has been superseded bybibentry.

Usage

citEntry(entry, textVersion=NULL, header=NULL, footer=NULL,...)

Arguments

Value

citEntry produces an object of class"bibentry".

See Also

citation for more information about citing R and Rpackages and ‘CITATION’ files;bibentry for the newer functionality for representingand manipulating bibliographic information.

Description

Transfer text between a character vector and the Windows clipboard inMS Windows (only).

Usage

getClipboardFormats(numeric=FALSE)readClipboard(format=13, raw=FALSE)writeClipboard(str, format=13)

Arguments

Details

The Windows clipboard offers data in a number of formats: seee.g.https://learn.microsoft.com/en-gb/windows/desktop/dataxchg/clipboard-formats.

The standard formats include

Applications normally make data available in one or more of these andpossibly additional private formats. Useraw = TRUE to read binaryformats,raw = FALSE (the default) for text formats. Thecurrent codepage is used to convert text to Unicode text, andinformation on that is contained in theCF_LOCALE format.(Take care if you are running R in a different locale from Windows. It isrecommended to read as Unicode text, so that Windows does the conversionbased onCF_LOCALE, if available.)

ThewriteClipboard function will write a character vector astext or Unicode text with standardCRLF line terminators. It willcopy a raw vector directly to the clipboard without any changes. It isrecommended to use Unicode text (the default) instead of text to avoid interoperabilityproblems. (Note thatR 4.2 and newer on recent systems uses UTF-8 as thenative encoding but the machine's locale uses a different encoding.)

Value

ForgetClipboardFormats, a character or integer vector ofavailable formats, in numeric order. If non human-readable characterrepresentation is known, the number is returned.

ForreadClipboard, a character vector by default, a raw vectorifraw isTRUE, orNULL, if the format isunavailable.

ForwriteClipboard an invisible logical indicating success orfailure.

Note

This is only available on Windows.

See Also

file which can be used to set up a connection to a clipboard.

Description

Closes the socket and frees the space in the file descriptor table. Theport may not be freed immediately.

Usage

close.socket(socket,...)

Arguments

Value

logical indicating success or failure

Author(s)

Thomas Lumley

See Also

make.socket,read.socket

Compiling in support for sockets was optional prior toR 3.3.0: seecapabilities("sockets") to see if it is available.

Description

Generate all combinations of the elements ofx takenmat a time. Ifx is a positive integer, returns allcombinations of the elements ofseq(x) takenm at atime. If argumentFUN is notNULL, applies a function givenby the argument to each point. If simplify is FALSE, returnsa list; otherwise returns anarray, typically amatrix.... are passed unchanged to theFUN function, if specified.

Usage

combn(x, m, FUN=NULL, simplify=TRUE,...)

Arguments

Details

Factorsx are accepted.

Value

Alist orarray, see thesimplifyargument above. In the latter case, the identitydim(combn(n, m)) == c(m, choose(n, m)) holds.

Author(s)

Scott Chasalow wrote the original in 1994 for S;R packagecombinat and documentation by Vince Carey[email protected];small changes by the R core team, notably to return an array in allcases ofsimplify = TRUE, e.g., forcombn(5,5).

References

Nijenhuis, A. and Wilf, H.S. (1978)Combinatorial Algorithms for Computers and Calculators;Academic Press, NY.

See Also

choose for fast computation of thenumber ofcombinations.expand.grid for creating a data frame fromall combinations of factors or vectors.

Examples

combn(letters[1:4],2)(m<- combn(10,5, min))# minimum value in each combinationmm<- combn(15,6,function(x) matrix(x,2,3))stopifnot(round(choose(10,5))== length(m), is.array(m),# 1-dimensional          c(2,3, round(choose(15,6)))== dim(mm))## Different way of encoding points:combn(c(1,1,1,1,2,2,2,3,3,4),3, tabulate, nbins=4)## Compute support points and (scaled) probabilities for a## Multivariate-Hypergeometric(n = 3, N = c(4,3,2,1)) p.f.:# table.mat(t(combn(c(1,1,1,1,2,2,2,3,3,4), 3, tabulate, nbins = 4)))## Assuring the identityfor(nin1:7)for(min0:n) stopifnot(is.array(cc<- combn(n, m)),                         dim(cc)== c(m, choose(n, m)),                         identical(cc, combn(n, m, identity))|| m==1)

Description

Compare two package version numbers to see which is later.

Usage

compareVersion(a, b)

Arguments

Details

R package version numbers are of the formx.y-z for integersx,y andz, with components afterxoptionally missing (in which case the version number is older thanthose with the components present).

Value

0 if the numbers are equal,-1 ifb is laterand1 ifa is later (analogous to the C functionstrcmp).

Gives anR error on malformed inputs.

See Also

package_version,library,packageStatus.

Examples

compareVersion("1.0","1.0-1")compareVersion("7.2-0","7.1-12")

Description

Compile given source files so that they can subsequently be collectedinto a shared object usingR CMD SHLIB or an executableprogram usingR CMD LINK. Not available on Windows.

Usage

R CMD COMPILE[options] srcfiles

Arguments

Details

R CMD SHLIB can both compile and link files into ashared object: since it knows what run-time libraries are neededwhen passed C++, Fortran and Objective C(++) sources, passing sourcefiles toR CMD SHLIB is more reliable.

Objective C and Objective C++ support is optional and will work onlyif the corresponding compilers were available atR configure time:their main usage is on macOS.

Compilation arranges to include the paths to theR public C/C++ headers.

As this compiles code suitable for incorporation into a shared object,it generates PIC code: that might occasionally be undesirable for themain code of an executable program.

This is amake-based facility, so will not compile a source fileif a newer corresponding ‘.o’ file is present.

Note

Some binary distributions ofR haveCOMPILE in a separatebundle, e.g. anR-devel RPM.

This is not available on Windows.

See Also

LINK,SHLIB,dyn.load

The section on “Customizing package compilation” inthe ‘R Administration and Installation’ manual:RShowDoc("R-admin").

Description

contrib.url adds the appropriate type-specific path within arepository to each URL inrepos.

Usage

contrib.url(repos, type= getOption("pkgType"))

Arguments

Details

Iftype = "both" this will use the source repository.

Value

A character vector of the same length asrepos.

See Also

setRepositories to setoptions("repos"),the most common value used for argumentrepos.

available.packages,download.packages,install.packages.

The ‘R Installation and Administration’ manual for how toset up a repository.

Description

count.fields counts the number of fields, as separated bysep, in each of the lines offile read.

Usage

count.fields(file, sep="", quote="\"'", skip=0,             blank.lines.skip=TRUE, comment.char="#")

Arguments

Details

This used to be used byread.table and can still beuseful in discovering problems in reading a file by that function.

For the handling of comments, seescan.

Consistent withscan,count.fields allowsquoted strings to contain newline characters. In such a case thestarting line will have the field count recorded asNA, andthe ending line will include the count of all fields from thebeginning of the record.

Value

A vector with the numbers of fields found.

See Also

read.table

Examples

fil<- tempfile()cat("NAME","1:John","2:Paul", file= fil, sep="\n")count.fields(fil, sep=":")unlink(fil)

Description

An ancillary function used bybug.report andhelp.request to prepare emails for submission to packagemaintainers or toR mailing lists.

Usage

create.post(instructions= character(), description="post",            subject="",            method= getOption("mailer"),            address="the relevant mailing list",            ccaddress= getOption("ccaddress",""),            filename="R.post", info= character())

Arguments

Details

What this does depends on themethod. The function firstcreates a template email body.

none

A file editor (seefile.edit) isopened with instructions and the template email. When this returns,the completed email is in filefile ready to be read/pastedinto an email program.

mailto

This opens the default email program with a template email(including address, Cc: address and subject) for you to edit andsend.

This works where default mailers are set up (usual on macOS andWindows, and wherexdg-open is available and configured onother Unix-alikes: if that fails it tries the browser set byR_BROWSER).

This is the ‘factory-fresh’ default method.

mailx

(Unix-alikes only.)A file editor (seefile.edit) isopened with instructions and the template email. When thisreturns, it is mailed using a Unix command line mail utility suchasmailx, to the address (and optionally, the Cc: address)given.

gnudoit

An (X)emacs mail buffer is opened for the email to be edited andsent: this requires thegnudoit program to beavailable. Currentlysubject is ignored.

ess

The body of the template email is sent tostdout.

Value

InvisibleNULL.

See Also

bug.report,help.request.

Description

Loads specified data sets, or list the available data sets.

Usage

data(..., list= character(), package=NULL, lib.loc=NULL,     verbose= getOption("verbose"), envir= .GlobalEnv,     overwrite=TRUE)

Arguments

Details

Currently, four formats of data files are supported:

1. files ending ‘.R’ or ‘.r’ aresource()d in, with theR working directory changedtemporarily to the directory containing the respective file.(data ensures that theutils package is attached, incase it had been runviautils::data.)

2. files ending ‘.RData’ or ‘.rdata’ or ‘.rda’ areload()ed.

3. files ending ‘.tab’, ‘.txt’ or ‘.TXT’ are readusingread.table(..., header = TRUE, as.is=FALSE),and henceresult in a data frame.

4. files ending ‘.csv’ or ‘.CSV’ are read usingread.table(..., header = TRUE, sep = ";", as.is=FALSE),and also result in a data frame.

If more than one matching file name is found, the first on this listis used. (Files with extensions ‘.txt’, ‘.tab’ or‘.csv’ can be compressed, with or without further extension‘.gz’, ‘.bz2’ or ‘.xz’.)

The data sets to be loaded can be specified as a set of characterstrings or names, or as the character vectorlist, or as both.

For each given data set, the first two types (‘.R’ or ‘.r’,and ‘.RData’ or ‘.rda’ files) can create several variablesin the load environment, which might all be named differently from thedata set. The third and fourth types will always result in thecreation of a single variable with the same name (without extension)as the data set.

If no data sets are specified,data lists the available datasets. For each package,it looks for a data index in the ‘Meta’ subdirectory or, ifthis is not found, scans the ‘data’ subdirectory for data filesusinglist_files_with_type.The information aboutavailable data sets is returned in an object of class"packageIQR". The structure of this class is experimental.Where the datasets have a different name from the argument that shouldbe used to retrieve them the index will have an entry likebeaver1 (beavers) which tells us that datasetbeaver1can be retrieved by the calldata(beavers).

Iflib.loc andpackage are bothNULL (thedefault), the data sets are searched for in all the currently loadedpackages then in the ‘data’ directory (if any) of the currentworking directory.

Iflib.loc = NULL butpackage is specified as acharacter vector, the specified package(s) are searched for firstamongst loaded packages and then in the default libraries(see.libPaths).

Iflib.locis specified (and notNULL), packagesare searched for in the specified libraries, even if they arealready loaded from another library.

To just look in the ‘data’ directory of the current workingdirectory, setpackage = character(0)(andlib.loc = NULL, the default).

Value

A character vector of all data sets specified (whether found or not),or information about all available data sets in an object of class"packageIQR" if none were specified.

Good practice

There is no requirement fordata(foo) to create an objectnamedfoo (nor to create one object), although it muchreduces confusion if this convention is followed (and it is enforcedif datasets are lazy-loaded).

data() was originally intended to allow users to load datasetsfrom packages for use in their examples, and as such it loaded thedatasets into the workspace.GlobalEnv. This avoidedhaving large datasets in memory when not in use: that need has beenalmost entirely superseded by lazy-loading of datasets.

The ability to specify a dataset by name (without quotes) is aconvenience: in programming the datasets should be specified bycharacter strings (with quotes).

Use ofdata within a function without anenvir argumenthas the almost always undesirable side-effect of putting an object inthe user's workspace (and indeed, of replacing any object of that namealready there). It would almost always be better to put the object inthe current evaluation environment bydata(..., envir = environment()).However, two alternatives are usually preferable,both described in the ‘Writing R Extensions’ manual.

• For sets of data, set up a package to use lazy-loading of data.

• For objects which are system data, for example lookup tablesused in calculations within the function, use a file‘R/sysdata.rda’ in the package sources or create the objects byR code at package installation time.

A sometimes important distinction is that the second approach placesobjects in the namespace but the first does not. So if it is importantthat the function seesmytable as an object from the package,it is system data and the second approach should be used. In theunusual case that a package uses a lazy-loaded dataset as a defaultargument to a function, that needs to be specified by::,e.g.,survival::survexp.us.

Warning

This function creates objects in theenvir environment (bydefault the user's workspace) replacing any which alreadyexisted.data("foo") can silently create objects other thanfoo: there have been instances in published packages where itcreated/replaced.Random.seed and hence change the seedfor the session.

Note

One can take advantage of the search order and the fact that a‘.R’ file will change directory. If raw data are stored in‘mydata.txt’ then one can set up ‘mydata.R’ to read‘mydata.txt’ and pre-process it, e.g., usingtransform().For instance one can convert numeric vectors to factors with theappropriate labels. Thus, the ‘.R’ file can effectively containa metadata specification for the plaintext formats.

See Also

help for obtaining documentation on data sets,save forcreating the second (‘.rda’) kindof data, typically the most efficient one.

The ‘Writing R Extensions’ manual for considerations in preparing the‘data’ directory of a package.

Examples

require(utils)data()# list all available data setstry(data(package="rpart"), silent=TRUE)# list the data sets in the rpart packagedata(USArrests,"VADeaths")# load the data sets 'USArrests' and 'VADeaths'## Not run: ## Alternativelyds<- c("USArrests","VADeaths"); data(list= ds)## End(Not run)help(USArrests)# give information on data set 'USArrests'

Description

A spreadsheet-like editor for entering or editing data.

Usage

data.entry(..., Modes=NULL, Names=NULL)dataentry(data, modes)de(..., Modes= list(), Names=NULL)

Arguments

Details

The data entry editor is only available on some platforms and GUIs.Where available it provides a means to visually edit a matrix ora collection of variables (including a data frame) as described in theNotes section.

data.entry has side effects, any changes made in thespreadsheet are reflected in the variables. Functionde andthe internal functionsde.ncols,de.setupandde.restore are designed to help achieve these side effects. If the user passes in a matrix,X say, then the matrix is broken into columns beforedataentry is called. Then on return the columns are collectedand glued back together and the result assigned to the variableX. If you don't want this behaviour usedataentry directly.

The primitive function isdataentry. It takes a list ofvectors of possibly different lengths and modes (the second argument)and opens a spreadsheet with these variables being the columns.The columns of the data entry window are returned as vectors in alist when the spreadsheet is closed.

de.ncols counts the number of columns which are supplied as argumentstodata.entry. It attempts to count columns in lists, matricesand vectors.de.setup sets things up so that on return thecolumns can be regrouped and reassigned to the correct name. Thisis handled byde.restore.

Value

de anddataentry return the edited value of theirarguments.data.entry invisibly returns a vector of variablenames but its main value is its side effect of assigning new versionof those variables in the user's workspace.

Resources

The data entry window responds to X resources of classR_dataentry. Resourcesforeground,background andgeometry are utilized.

Note

The details of interface to the data grid may differ by platform andGUI. The following description applies tothe X11-based implementation under Unix.

You can navigate around the grid using the cursor keys or by clickingwith the (left) mouse button on any cell. The active cell ishighlighted by thickening the surrounding rectangle. Moving to theright or down will scroll the grid as needed: there is no constraintto the rows or columns currently in use.

There are alternative ways to navigate using the keys. Return and(keypad) Enter and LineFeed all move down. Tab moves right andShift-Tab move left. Home moves to the top left.

PageDown or Control-F moves down a page, and PageUp orControl-B up by a page. End will show the last used column and thelast few rows used (in any column).

Using any other key starts an editing process on the currentlyselected cell: moving away from that cell enters the edited valuewhereas Esc cancels the edit and restores the previous value. Whenthe editing process starts the cell is cleared.

In numerical columns(the default) only letters making up a valid number (including-.eE) are accepted, and entering an invalid edited value (suchas blank) entersNA in that cell. The last entered value canbe deleted using the BackSpace or Del(ete) key. Only a limitednumber of characters (currently 29) can be entered in a cell, and ifnecessary only the start or end of the string will be displayed, with theomissions indicated by> or<. (The start is shownexcept when editing.)

Entering a value in a cell further down a column than the last usedcell extends the variable and fills the gap (if any) byNAs (notshown on screen).

The column names can only be selected by clicking in them. This givesa popup menu to select the column type (currently Real (numeric) orCharacter) or to change the name. Changing the type converts thecurrent contents of the column (and converting from Character to Realmay generateNAs.)If changing the name is selected theheader cell becomes editable (and is cleared). As with all cells, thevalue is entered by moving away from the cell by clicking elsewhere orby any of the keys for moving down (only).

New columns are created by entering values in them (and not by justassigning a new name). The mode of the column is auto-detected fromthe first value entered: if this is a valid number it gives a numericcolumn. Unused columns are ignored, soadding data invar5 to a three-column grid adds one extravariable, not two.

TheCopy button copies the currently selected cell:paste copies the last copied value to the current cell, andright-clicking selects a celland copies in the value.Initially the value is blank, and attempts to paste a blank value willhave no effect.

Control-L will refresh the display, recalculating field widths to fitthe current entries.

In the default mode the column widths are chosen to fit the contentsof each column, with a default of 10 characters for empty columns.you can specify fixed column widths by setting optionde.cellwidth to the required fixed width (in characters).(set it to zero to return to variable widths). The displayedwidth of any field is limited to600 pixels (and by the window width).

See Also

vi,edit:edit usesdataentry to edit data frames.

Examples

# call data entry with variables x and y## Not run: data.entry(x, y)

Description

Set or unset debugging flags based on a call to a function. Takes intoaccount S3/S4 method dispatch based on the classes of the arguments inthe call.

Usage

debugcall(call, once=FALSE)undebugcall(call)

Arguments

Details

debugcall debugs the non-generic function, S3 method or S4method that would be called by evaluatingcall. Thus, the userdoes not need to specify the signature when debuggingmethods. Although the call is actually to the generic, it is themethod that is debugged, not the generic, except for non-standard S3generics (seeisS3stdGeneric).

Value

debugcall invisibly returns the debugged call expression.

Note

Non-standard evaluation is used to retrieve thecall (viasubstitute). For this reason, passing a variablecontaining a call expression, rather than the call expression itself,will not work.

See Also

debug for the primary debugging interface

Examples

## Not run:## Evaluate call after setting debugging##f<- factor(1:10)res<- eval(debugcall(summary(f)))## End(Not run)

Description

Functions to dump the evaluation environments (frames) and to examinedumped frames.

Usage

dump.frames(dumpto="last.dump", to.file=FALSE,            include.GlobalEnv=FALSE)debugger(dump= last.dump)limitedLabels(value, maxwidth= getOption("width")-5L)

Arguments

Details

To use post-mortem debugging, set the optionerror to be a calltodump.frames. By default this dumps to anR objectlast.dump in the workspace, but it can be set to dump to afile (a dump of the object produced by a call tosave).The dumped object contain the call stack, the active environments andthe last error message as returned bygeterrmessage.

When dumping to file,dumpto gives the name of the dumpedobject and the file name has ‘.rda’ appended.

A dump object of class"dump.frames" can be examined by callingdebugger. This will give the error message and a list ofenvironments from which to select repeatedly. When an environment isselected, it is copied and thebrowser called fromwithin the copy. Note that not all the information in the originalframe will be available, e.g. promises which have not yet beenevaluated and the contents of any... argument.

Ifdump.frames is installed as the error handler, executionwill continue even in non-interactive sessions. See the examples forhow to dump and then quit.

limitedLabels(v) takes alist of calls whoseelements may have asrcref attribute and returns a vector thatpastes a formatted version of those attributes onto the formatted versionof the elements, all finallystrtrim()med tomaxwidth.

Value

InvisibleNULL.

Note

Functions such assys.parent andenvironment applied to closures will not work correctlyinsidedebugger.

If the error occurred when computing the default value of a formalargument the debugger will report “recursive default argumentreference” when trying to examine that environment.

Of course post-mortem debugging will not work ifR is too damaged toproduce and save the dump, for example if it has run out of workspace.

References

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

See Also

browser for the actions available at theBrowseprompt.

options for settingerror options;recover is an interactive debugger working similarly todebugger but directly after the error occurs.

Examples

## Not run:options(error= quote(dump.frames("testdump",TRUE)))f<-function(){    g<-function() stop("test dump.frames")    g()}f()# will generate a dump on file "testdump.rda"options(error=NULL)## possibly in another R sessionload("testdump.rda")debugger(testdump)Available environments had calls:1: f()2: g()3: stop("test dump.frames")Enter an environment number, or0 to exitSelection:1Browsingin the environment with call:f()Called from: debugger.look(ind)Browse[1]> ls()[1]"g"Browse[1]> gfunction() stop("test dump.frames")<environment:759818>Browse[1]>Available environments had calls:1: f()2: g()3: stop("test dump.frames")Enter an environment number, or0 to exitSelection:0## A possible setting for non-interactive sessionsoptions(error= quote({dump.frames(to.file=TRUE); q(status=1)}))## End(Not run)

Description

demo is a user-friendly interface to running some demonstrationR scripts.demo() gives the list of available topics.

Usage

demo(topic, package=NULL, lib.loc=NULL,     character.only=FALSE, verbose= getOption("verbose"),     type= c("console","html"), echo=TRUE,     ask= getOption("demo.ask"),     encoding= getOption("encoding"))

Arguments

Details

If no topics are given,demo lists the available demos. Fortype = "console", the corresponding information is returned inan object of class"packageIQR".

See Also

source anddevAskNewPage whichare called bydemo.example to run codein the Examples section of help pages.

Examples

demo()# for attached packages## All available demos:demo(package= .packages(all.available=TRUE))## Display a demo, pausing between pagesdemo(lm.glm, package="stats", ask=TRUE)## Display it without pausingdemo(lm.glm, package="stats", ask=FALSE)## Not run: ch<-"scoping" demo(ch, character=TRUE)## End(Not run)## Find the location of a demosystem.file("demo","lm.glm.R", package="stats")

Description

On MS Windows only, return the version of the package and the version ofR used tobuild the DLL, if available.

Usage

DLL.version(path)

Arguments

Value

If the DLL does not exist,NULL.

A character vector of length two, giving the DLL version and the version ofR used to build the DLL. If the information is not available, thecorresponding string is empty.

Note

This is only available on Windows.

Examples

if(.Platform$OS.type=="windows") withAutoprint({  DLL.version(file.path(R.home("bin"),"R.dll"))  DLL.version(file.path(R.home(),"library/stats/libs", .Platform$r_arch,"stats.dll"))})

Description

This function can be used to download a file from the Internet.

Usage

download.file(url, destfile, method, quiet=FALSE, mode="w",              cacheOK=TRUE,              extra= getOption("download.file.extra"),              headers=NULL,...)

Arguments

Details

The functiondownload.file can be used to download a singlefile as described byurl from the internet and store it indestfile.

Theurl must start with a scheme such as ‘⁠http://⁠’,‘⁠https://⁠’ or ‘⁠file://⁠’. Which methods support whichschemes varies byR version, butmethod = "auto" will try tofind a method which supports the scheme.

Formethod = "auto" (the default) currently the"internal" method is used for ‘⁠file://⁠’ URLs and"libcurl" for all others.

Support for method"libcurl" was optional on Windows prior toR 4.2.0: usecapabilities("libcurl") to see if it issupported on an earlier version. It uses an external library of thatname (https://curl.se/libcurl/) against whichR can becompiled.

When method"libcurl" is used, there is support forsimultaneous downloads, sourl anddestfile can becharacter vectors of the same length greater than one (but the methodhas to be specified explicitly and notvia"auto"). Fora single URL andquiet = FALSE a progress bar is shown ininteractive use.

Nowadays the"internal" method only supports the ‘⁠file://⁠’scheme (for which it is the default). On Windows the"wininet"method currently supports ‘⁠file://⁠’ and (but deprecated with awarning) ‘⁠http://⁠’ and ‘⁠https://⁠’ schemes.

For methods"wget" and"curl" a system call is made tothe tool given bymethod, and the respective program must beinstalled on your system and be in the search path for executables.They will block all other activity on theR process until theycomplete: this may make a GUI unresponsive.

cacheOK = FALSE is useful for ‘⁠http://⁠’ and‘⁠https://⁠’ URLs: it will attempt to get a copy directly from thesite rather than from an intermediate cache. It is used byavailable.packages.

The"libcurl" and"wget" methods follow ‘⁠http://⁠’and ‘⁠https://⁠’ redirections to any scheme they support. (Formethod"curl" use argumentextra = "-L". To disableredirection inwget, useextra = "--max-redirect=0".)The"wininet" method supports some redirections but not all.(For method"libcurl", messages will quote the endpoint ofredirections.)

Seeurl for how ‘⁠file://⁠’ URLs are interpreted,especially on Windows. The"internal" and"wininet"methods do not percent-decode, but the"libcurl" and"curl" methods do: method"wget" does not support them.

Most methods do not percent-encode special characters such as spacesin URLs (seeURLencode), but it seems the"wininet" method does.

The remaining details apply to the"wininet" and"libcurl" methods only.

The timeout for many parts of the transfer can be set by the optiontimeout which defaults to 60 seconds. This is ofteninsufficient for downloads of large files (50MB or more) andso should be increased whendownload.file is used in packagesto do so. Note that the user can set the default timeout by theenvironment variableR_DEFAULT_INTERNET_TIMEOUT in recentversions ofR, so to ensure that this is not decreased packages shoulduse something like

    options(timeout = max(300, getOption("timeout")))

(It is unrealistic to require download times of less than 1s/MB.)

The level of detail provided during transfer can be set by thequiet argument and theinternet.info option: the detailsdepend on the platform and scheme. For the"libcurl" methodvalues of the option less than 2 give verbose output.

A progress bar tracks the transfer platform-specifically:

On Windows

If the file length is known, thefull width of the bar is the known length. Otherwise the initialwidth represents 100Kbytes and is doubled whenever the current widthis exceeded. (In non-interactive use this uses a text version. If thefile length is known, an equals sign represents 2% of the transfercompleted: otherwise a dot represents 10Kb.)

On a Unix-alike

If the file length is known, anequals sign represents 2% of the transfer completed: otherwise a dotrepresents 10Kb.

The choice of binary transfer (mode = "wb" or"ab") isimportant on Windows, since unlike Unix-alikes it does distinguishbetween text and binary files and for text transfers changes ‘⁠\n⁠’line endings to ‘⁠\r\n⁠’ (aka ‘CRLF’).

On Windows, ifmode is not supplied (missing())andurl ends in one of ‘⁠.gz⁠’, ‘⁠.bz2⁠’, ‘⁠.xz⁠’,‘⁠.tgz⁠’, ‘⁠.zip⁠’, ‘⁠.jar⁠’, ‘⁠.rda⁠’, ‘⁠.rds⁠’,‘⁠.RData⁠’ or ‘⁠.pdf⁠’,mode = "wb" is set so that a binarytransfer is done to help unwary users.

Code written to download binary files must usemode = "wb" (or"ab"), but the problems incurred by a text transfer will onlybe seen on Windows.

Value

An (invisible) integer code,0 for success and non-zero forfailure. For the"wget" and"curl" methods this is thestatus code returned by the external program. The"internal"method can return1, but will in most cases throw an error. Whensimultaneously downloading two or more files (see theurl argument)and download of at least one file succeeds,0 is returned withattributeretvals, which provides an integer vector of the samelength asurl with a result code for each file (0 forsuccess and non-zero for failure).

What happens to the destination file(s) in the case of error dependson the method andR version. Currently the"internal","wininet" and"libcurl" methods will remove the file ifthe URL is unavailable except whenmode specifiesappending when the file should be unchanged.

Setting Proxies

For the Windows-only method"wininet", the ‘InternetOptions’ of the system are used to choose proxies and so on; these areset in the Control Panel and are those used for system browsers.

For the"libcurl" and"curl" methods, proxies can be setvia the environment variableshttp_proxy orftp_proxy. Seehttps://curl.se/libcurl/c/libcurl-tutorial.html for furtherdetails.

Secure URLs

Methods which access ‘⁠https://⁠’ and (wheresupported) ‘⁠ftps://⁠’ URLs should try to verify the sitecertificates. This is usually done using the CA root certificatesinstalled by the OS (although we have seen instances in which thesegot removed rather than updated). For further information seehttps://curl.se/docs/sslcerts.html.

On Windows withmethod = "libcurl", the CA root certificatesare provided by the OS whenR was linked withlibcurl withSchannel enabled, which is the current default in Rtools. Thiscan be verified by checking thatlibcurlVersion() returns aversion string containing ‘⁠"Schannel"⁠’. If it does not, forverification to be on the environment variableCURL_CA_BUNDLEmust be set to a path to a certificate bundle file, usually named‘ca-bundle.crt’ or ‘curl-ca-bundle.crt’. (This is normallydone automatically for a binary installation ofR, which installs‘R_HOME/etc/curl-ca-bundle.crt’ and setsCURL_CA_BUNDLE to point to it if that environment variable isnot already set.) For an updated certificate bundle, seehttps://curl.se/docs/sslcerts.html. Currently one can downloada copy fromhttps://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crtand setCURL_CA_BUNDLE to the full path to the downloaded file.

On Windows withmethod = "libcurl", whenR was linked withlibcurl withSchannel enabled, the connection fails if itcannot be established that the certificate has not been revoked. SomeMITM proxies present particularly in corporate environments do not workwith this behavior. It can be changed by setting environment variableR_LIBCURL_SSL_REVOKE_BEST_EFFORT toTRUE, with theconsequence of reducing security.

Note that the root certificates used byR may or may not be the sameas used in a browser, and indeed different browsers may use differentcertificate bundles (there is typically a build option to chooseeither their own or the system ones).

Good practice

Setting themethod should be left to the end user. Neither ofthewget norcurl commands is widely available:you can check if one is availableviaSys.which,and should do so in a package or script.

If you usedownload.file in a package or script, you must checkthe return value, since it is possible that the download will failwith a non-zero status but not anR error.

The supportedmethods do change: methodlibcurl wasintroduced inR 3.2.0 and was optional on Windows untilR 4.2.0 –usecapabilities("libcurl") in a program to see if it isavailable.

‘⁠ftp://⁠’ URLs

Most modern browsers do not support such URLs, and ‘⁠https://⁠’ones are much preferred for use inR. ‘⁠ftps://⁠’ URLs have alwaysbeen rare, and are nowadays even less supported.

It is intended thatR will continue to allow such URLs for as long aslibcurl does, but as they become rarer this is increasinglyuntested. What ‘protocols’ the version oflibcurlbeing used supports can be seen by callinglibcurlVersion().

These URLs are accessed using the FTP protocol which has anumber of variants. One distinction is between ‘active’ and‘(extended) passive’ modes: which is used is chosen by theclient. The"libcurl" method uses passive mode which wasalmost universally used by browsers before they dropped supportaltogether.

Note

Files of more than 2GB are supported on 64-bit builds ofR; theymay be truncated on some 32-bit builds.

Methods"wget" and"curl" are mainly for historicalcompatibility but provide may provide capabilities not supported bythe"libcurl" or"wininet" methods.

Method"wget" can be used with proxy firewalls which requireuser/password authentication if proper values are stored in theconfiguration file forwget.

wget (https://www.gnu.org/software/wget/) is commonlyinstalled on Unix-alikes (but not macOS). Windows binaries areavailable fromMSYS2 and elsewhere.

curl (https://curl.se/) is installed on macOS andincreasingly commonly on Unix-alikes. Windows binaries are availableat that URL.

See Also

options to set theHTTPUserAgent,timeoutandinternet.info options used by some of the methods.

url for a finer-grained way to read data from URLs.

url.show,available.packages,download.packages for applications.

Contributed packagesRCurl andcurl provide morecomprehensive facilities to download from URLs.

Description

These functions can be used to automatically compare the versionnumbers of installed packages with the newest available version onthe repositories and update outdated packages on the fly.

Usage

download.packages(pkgs, destdir, available=NULL,                  repos= getOption("repos"),                  contriburl= contrib.url(repos, type),                  method, type= getOption("pkgType"),...)

Arguments

Details

download.packages takes a list of package names and adestination directory, downloads the newest versions and saves them indestdir. If the list of available packages is not given asargument, it is obtained from repositories. If a repository is local,i.e. the URL starts with"file:", then the packages are notdownloaded but used directly. Both"file:" and"file:///" are allowed as prefixes to a file path. Use thelatter only for URLs: seeurl for their interpretation.(Other forms of ‘⁠file://⁠’ URLs are not supported.)

Fordownload.packages,type = "both" looks at sourcepackages only.

Value

A two-column matrix of names and destination file names of thosepackages successfully downloaded. If packages are not available orthere is a problem with the download, suitable warnings are given.

See Also

available.packages,contrib.url.

The main use is byinstall.packages.

Seedownload.file for how to handle proxies andother options to monitor file transfers.

The ‘R Installation and Administration’ manual for how toset up a repository.

Description

Invoke a text editor on anR object.

Usage

edit(name,...)## Default S3 method:edit(name=NULL, file="", title=NULL,     editor= getOption("editor"),...)vi(name=NULL, file="")emacs(name=NULL, file="")pico(name=NULL, file="")xemacs(name=NULL, file="")xedit(name=NULL, file="")

Arguments

Details

edit invokes the text editor specified byeditor withthe objectname to be edited. It is a generic function,currently with a default method and one for data frames and matrices.

data.entry can be used to edit data, and is used byeditto edit matrices and data frames on systems for whichdata.entry is available.

It is important to realize thatedit does not change the objectcalledname. Instead, a copy of name is made and it is thatcopy which is changed. Should you want the changes to apply to theobjectname you must assign the result ofedit toname. (Tryfix if you want to make permanentchanges to an object.)

In the formedit(name),edit deparsesname into a temporary file and invokes theeditoreditor on this file. Quitting from the editor causesfile to be parsed and that value returned.Should an error occur in parsing, possibly due to incorrect syntax, novalue is returned. Callingedit(), with no arguments, willresult in the temporary file being reopened for further editing.

Note that deparsing is not perfect, and the object recreated afterediting can differ in subtle ways from that deparsed: seedput and.deparseOpts. (The deparse optionsused are the same as the defaults fordump.) Editing afunction will preserve its environment. Seeedit.data.frame for further changes that can occur whenediting a data frame or matrix.

Currently only the internal editor in Windows makes use of thetitle option; it displays the given name in the windowheader.

Note

The functionsvi,emacs,pico,xemacs,xedit rely on the corresponding editor being available andbeing on the path. This is system-dependent.

See Also

edit.data.frame,data.entry,fix.

Examples

## Not run:# use xedit on the function mean and assign the changesmean<- edit(mean, editor="xedit")# use vi on mean and write the result to file mean.outvi(mean, file="mean.out")## End(Not run)

Description

Use data editor on data frame or matrix contents.

Usage

## S3 method for class 'data.frame'edit(name, factor.mode= c("character","numeric"),     edit.row.names= any(row.names(name)!=1:nrow(name)),...)## S3 method for class 'matrix'edit(name, edit.row.names=!is.null(dn[[1]]),...)

Arguments

Details

At present, this only works on simple data frames containing numeric,logical or character vectors and factors, and numeric, logical orcharacter matrices. Any other mode of matrix will give an error, anda warning is given when the matrix has a class (which will be discarded).

Data frame columns are coerced on input tocharacter unlessnumeric (in the sense ofis.numeric), logical or factor. Awarning is given when classes are discarded. Special characters(tabs, non-printing ASCII, etc.) will be displayed as escape sequences.

Factors columns are represented in the spreadsheet as either numericvectors (which are more suitable for data entry) or character vectors(better for browsing). After editing, vectors are padded withNA to have the same length and factor attributes are restored.The set of factor levels can not be changed by editing in numericmode; invalid levels are changed toNA and a warning is issued.If new factor levels are introduced in character mode, they are addedat the end of the list of levels in the order in which theyencountered.

It is possible to use the data-editor's facilities to select the modeof columns to swap between numerical and factor columns in a dataframe. Changing any column in a numerical matrix to character willcause the result to be coerced to a character matrix. Changingthe mode of logical columns is not supported.

For a data frame, the row names will be taken from the original objectifedit.row.names = FALSE and the number of rows is unchanged,and from the edited output ifedit.row.names = TRUE and thereare no duplicates. (If therow.names column is incomplete, itis extended by entries likerow223.) In all other cases therow names are replaced byseq(length = nrows).

For a matrix, colnames will be added (of the formcol7) ifneeded. The rownames will be taken from the original object ifedit.row.names = FALSE and the number of rows is unchanged(otherwiseNULL), and from the edited output ifedit.row.names = TRUE. (If therow.names column isincomplete, it is extended by entries likerow223.)

Editing a matrix or data frame will lose all attributes apart from therow and column names.

Value

The edited data frame or matrix.

Note

fix(dataframe) works for in-place editing by calling thisfunction.

If the data editor is not available, a dump of the object is presentedfor editing using the default method ofedit.

At present the data editor is limited to 65535 rows.

Author(s)

Peter Dalgaard

See Also

data.entry,edit

Examples

## Not run:edit(InsectSprays)edit(InsectSprays, factor.mode="numeric")## End(Not run)

Description

Run all theR code from theExamples part ofR's online helptopictopic, with possible exceptions due to⁠\dontrun⁠,⁠\dontshow⁠, and⁠\donttest⁠ tags, see ‘Details’ below.

Usage

example(topic, package=NULL, lib.loc=NULL,        character.only=FALSE, give.lines=FALSE, local=FALSE,        type= c("console","html"), echo=TRUE,        verbose= getOption("verbose"),        setRNG=FALSE, ask= getOption("example.ask"),        prompt.prefix= abbreviate(topic,6),        catch.aborts=FALSE,        run.dontrun=FALSE, run.donttest= interactive())

Arguments