Need help? RTFM!

Read The Fine Manual

---

English

1 “Help!” (Lennon-McCartney, 1965)

Above, we used the sample() function as an example of a base R function. But how could we possibly know, that sample() expects an input argument called x and that x should be one or more elements from which to sample (e.g. a sequence of the numbers 1 to 5)?

Inline help is always available in R and RStudio – this is especially convenient when you need help with a function.

The help files can be accessed in a number of ways:

• In the console, typing ?sample will bring up the help file for the R object of that name, in this case a function.
• In the console, typing ??sample will search the content of all help files, and present a list of ‘hits’.
• In the tab Help (lower, right hand pane by default) includes two search fields: the right on to search for topics and the left to seach within (the current) topic.

A simple example

Try to look at the help page for the sample() function, by typing ?sample in the console. Have a look around and see what you can make of it.

Hint

The first line tells us this is the help-page sample which is part of the base package .. i.e. base R.

“Random Samples and Permutations” is a heading for the function and its help page.

Description provides a short description (surprise!) of what the function does.

Usage describes how to use the function, and in this case we learn, that sample() requires four input arguments: x, size, replace and prob. Note, that two of them, replace and prob have default values (FALSE and NULL) – as x and size do not have default values, the programmer must provide these input arguments when calling the function. We also learn, that there is a derivative version of sample() called sample.int().

Arguments gives us a description of each of the required input arguments. E.g. size should be a non-negative integer which defines how many samples to extract from the set x.

Details explains the function in greater detail.

Value describes what the function will return, in this case a vector (of length size) of randomly sampled elements from the set x, or if x was simply a positive integer, the set of integers from 1 to x.

References speaks for itself

See also links to other functions and help files which may be relevant

Examples provides a number of use-cases, as generic stand-alone examples.

Now try this

We previously (under Console vs Editor) made use of the sqrt() function but got an error when testing sqrt(my_number), when my_number was "64".

You probably remember, that the problem was, that my_number was a string literal (in the same way that "sixty-four" is a string literal), but:

• what, actually, is a valid argument for the sqrt() function?
• what is the name of that argument, within the sqrt() function?
• what is the name of the help-page which describes the sqrt() function?

The solution

Typing ?sqrt in the console and we will learn that:

• The sqrt() function accepts as input a numeric or complex vector or array
  • sqrt() will also work with complex numbers and not just single values like 64, but vectors like 1:10 and even arrays (multi-dimensional matrices) of numeric or complex numbers.
• The name of the argument used within the function is x
• The help-page is called MathFun and is part of the {base} package (base R).

Dansk

2 “Help!” (Lennon-McCartney, 1965)

Ovenfor brugte vi funktionen sample() som et eksempel på en basisfunktion i R. Men hvordan kan vi overhovedet vide, at sample() forventer et inputargument kaldet x, og at x skal være et eller flere elementer, hvorfra der skal samples (f.eks. en sekvens af tallene 1 til 5)?

Inline-hjælp er altid tilgængelig i R og RStudio – dette er især praktisk, når du har brug for hjælp til en funktion.

Hjælpefilerne kan tilgås på flere måder:

• I konsollen vil indtastning af ?sample åbne hjælpefilen til R-objektet med det samme navn, i dette tilfælde en funktion.

• I konsollen vil indtastning af ??sample søge i indholdet af alle hjælpefiler og præsentere en liste over ‘hits’.

• Fanen Hjælp (nederste højre rude som standard) indeholder to søgefelter: det højre til at søge efter emner og det venstre til at søge inden for (det aktuelle) emne.

Et simpelt eksempel

Prøv at se på hjælpesiden for sample()-funktionen ved at skrive ?sample i konsollen. Kig dig omkring og se, hvad du kan få ud af det.

Tip

Den første linje fortæller os, at dette er hjælpesiden sample, som er en del af base-pakken .. dvs. base R.

“Random Samples and Permutations” er en overskrift for funktionen og dens hjælpeside.

Description giver en kort beskrivelse (surprise!) af, hvad funktionen gør.

Usage beskriver, hvordan man bruger funktionen, og i dette tilfælde lærer vi, at sample() kræver fire inputargumenter: x, size, replace og prob. Bemærk, at to af dem, replace og prob, har standardværdier (FALSE og NULL) – da x og size ikke har standardværdier, skal programmøren angive disse inputargumenter, når funktionen kaldes. Vi lærer også, at der findes en afledt version af sample() kaldet sample.int().

Arguments giver os en beskrivelse af hvert af de nødvendige inputargumenter. F.eks. skal size være et ikke-negativt heltal, der definerer, hvor mange prøver der skal udtrækkes fra sættet x.

Details forklarer funktionen mere detaljeret.

Value beskriver, hvad funktionen vil returnere, i dette tilfælde en vektor (med længden size) af tilfældigt samplede elementer fra sættet x, eller hvis x blot var et positivt heltal, sættet af heltal fra 1 til x.

References taler for sig selv

See also links til andre funktioner og hjælpefiler, der kan være relevante

Examples giver en række use-cases som generiske, selvstændige eksempler.

Prøv nu dette

Vi brugte tidligere (under Console vs Editor) sqrt()-funktionen, men fik en fejl, da vi testede sqrt(mit_nummer), da mit_nummer var "64".

Du husker sikkert, at problemet var, at mit_nummer var en strengliteral (på samme måde som "fire-og-treds" er en strengliteral), men:

• hvad er egentlig et gyldigt argument for sqrt()-funktionen?
• hvad hedder det argument i sqrt()-funktionen?
• hvad hedder hjælpesiden, der beskriver sqrt()-funktionen?

Løsningen

Ved at skrive ?sqrt i konsollen lærer vi, at:

• Funktionen sqrt() accepterer en numerisk eller kompleks vektor eller et array som input
• sqrt() fungerer også med komplekse tal og ikke kun enkeltværdier som 64, men vektorer som 1:10 og endda arrays (flerdimensionelle matricer) af numeriske eller komplekse tal.
• Navnet på argumentet, der bruges i funktionen, er x
• Hjælpesiden hedder MathFun og er en del af {base}-pakken (base R).