2.4 Nápověda

Nikdo si nemůže pamatovat všechno – a pamatovat si detaily použití jednotlivých funkcí je absurdní. Proto má R velmi dobrý systém nápovědy a dokumentace. RStudio tento systém ještě dále vylepšuje. Je velmi důležité, abyste se naučili dokumentaci k funkcím číst.

Nápovědu ke zvolené funkci můžete získat jedním ze tří způsobů. V konzoli napíšete jméno funkce (např. funkce mean()) bez závorek za otazníkem nebo jako argument funkce help()

?mean        # za otazníkem je jméno funkce
help("mean") # v uvozovkách je jméno funkce

nebo po napsání jména funkce do konzoly nebo editoru zmáčknete v RStudiu klávesu F1. Všechny tyto cesty vedou ke stejnému výsledku: RStudio zobrazí stránku nápovědy k dané funkci.

Jedna stránka nápovědy může dokumentovat několik různých funkcí, které mají něco společného. Stránky dokumentace mají v R standardní strukturu. Je potřeba, abyste se s ní seznámili. Stránka dokumentace má následující strukturu:

• Název funkce nebo tématu a balíku, např. mean {base}. To znamená, že strana dokumentuje funkci mean() definovanou v balíku base.
• Jméno stránky dokumentace, zde “Arithmetic Mean.”
• Popis, co funkce dělají (Description).
• Popis syntaxe, jak se funkce používají (Usage). Zde se uvádí zejména to, jaké má funkce parametry a jaké mají tyto parametry implicitní hodnoty (pokud nějaké mají) a. Ve funkci mean() je prvním parametrem x, který žádnou implicitní hodnotu nemá. Naproti tomu parametry trim a na.rm implicitní hodnoty mají. Pokud jejich hodnoty nezadáte, použijí se tyto implicitní hodnoty, tj. např. trim bude mít hodnotu 0. Všimněte si, že jednotlivé parametry jsou oddělené čárkou (,).
• Vysvětlení parametrů (Arguments). V této části se vysvětluje, co parametr představuje a v jaké datové struktuře má být parametr uložený.
• Hodnota funkce (Value) je oddíl, kde se vysvětluje, jaké hodnoty funkce vrací, co znamenají a v jaké datové struktuře je hodnota funkce uložená.
• Odkazy na literaturu (References).
• Odkazy na jiné funkce, balíky nebo data (See Also) uvádějí seznam funkcí, které nějak souvisejí s funkcemi, jejichž dokumentaci právě čtete.
• Příklady použití funkcí (Examples) ukazují, jak funkci použít. Často pomáhají pochopit, jak funkce funguje a jak ji použít.

Pokud dokumentaci otevřete v RStudiu, budou všechny odkazy klikací.

V R nemají dokumentaci jen jednotlivé funkce a datasety, ale i celé balíky. Dokumentaci k balíkům včetně seznamu funkcí, které jsou v ní obsažené, je možné získat dvěma způsoby. Buď v konzoli zavoláte funkci help() s parametrem package

help(package = "dplyr")  # v uvozovkách je jméno balíku

nebo v RStudiu v záložce Packages kliknete na jméno zvoleného balíku. Dokumentace k balíkům ukazuje, co vše daný balík nabízí. Obsahuje zejména soubor DESCRIPTION, který vysvětluje, kdo balík napsal, k čemu slouží a na jakých jiných balících závisí. Často obsahuje i odkaz na webovou stránku, kde se o daném balíku můžete dozvědět více. Dále může dokumentace balíků obsahovat seznam vinět a seznam funkcí a dat, které vám balík poskytuje.

Viněty jsou texty, které se nezaměřují na jednotlivé funkce, nýbrž ukazují, jak se balík používá jako celek, nebo vysvětlují nějaký princip, na kterém balík stojí. Seznam vinět přítomných v daném balíku je možné zobrazit v dokumentaci balíku kliknutím na “User guides, package vignettes and other documentation” nebo v konzoli pomocí funkce vignette():

vignette(package = "dplyr") # v uvozovkách je jméno balíku

Jednotlivou vinětu můžete zobrazit zobrazit kliknutím na její jméno v seznamu v RStudiu, nebo můžete v konzoli zadat jméno viněty do funkce vignette():

vignette("introduction", package = "dplyr") # první parametr je jméno viněty

Mnoho funkcí a balíků má k dispozici i demonstrační kód. Tyto kódy ukazují možnosti použití balíku nebo funkce nebo jejich obecné schopnosti. Tento kód můžete spustit takto:

demo("graphics") # parametr funkce je téma / jméno demonstrace
demo("bench-set", package = "dplyr") # pokud není balík načtený

Pokud chcete zjistit, jaké demonstrace obsahuje nějaký balík, zadejte

demo(package = "dplyr") # v uvozovkách je jméno balíku

a RStudio otevře záložku se jmény demonstrací přítomných v daném balíku. Pak vyvoláte demonstraci obvyklým způsobem.