R言語はもちろんのこと、どのプログラミング言語でも、関数などの使い方は必須の知識です。とはいえ、すべての関数の使い方を網羅的に記憶するのは現実的ではありません。したがって、コーディングは、必然的にドキュメントを片手に進める作業になります。関数などの使い方に関するドキュメントを、R言語ではヘルプと呼びます。
本稿ではRStudioでの作業を念頭に、必要な情報に素早くたどり着くためのヘルプの表示方法と読み方を紹介します。
特に読み方に関しては、ただでさえ英語を読むのが辛いのに文量も多いために、せっかくヘルプを開いたにもかかわらず挫折してしまう人もいるかもしれません。本稿が、あなたにとって必要な情報がどこにあるか、あたりをつけて最小限にヘルプを読むヒントになれば幸いです。必要な情報を手早く得る術を身につければ、その分、分析に集中でき、生産的な時間を確保できます。
ヘルプの表示方法
必要なヘルプを手早く確実に呼び出せると、それだけでヘルプを読む敷居が下がるように思います。実は、RStudioでは調べたい関数やデータセットにカーソルを合わせ、F1キーを押すと簡単にヘルプを表示できます。しかしRStudioを使えない場面やF1キーだけでは不足する場面に備え、ヘルプの表示方法を少しく解説します。
オブジェクトのヘルプ
関数やデータセットなどのオブジェクトに関するヘルプを参照する方法はいくつかあります。たとえばprint
関数のヘルプを表示したい場合、大きく2種類の方法があります。
- ヘルプを表示する関数を実行する
?print
(Rでは ?
や+
などの演算子も関数の一種)help(print)
- RStudioのキーボードショートカットを使い、カーソル位置のオブジェクトのヘルプを表示する
- キーボードショートカットのF1を実行する
- コマンドパレット[1]
(WindowsならCtrl+Shift+P、macOSならCmd+Shift+P) から 「Show Help for Current Function」 を実行する
- RStudioアドインであいまい検索する
- felpパッケージをインストールの上、コマンドパレットから
「Fuzzy Search on R Help」 を実行する
- felpパッケージをインストールの上、コマンドパレットから
特にF1キーは、ソースコードの読み書きに際して困ったときに素早くヘルプを表示できる協力な武器です。コンソールに?print
やhelp(print)
と入力する手間が不要なうえ、コンソールに不要なログが溜まりません。
また、RStudioアドインの
特定のパッケージ由来のオブジェクトのヘルプ
tidyverseパッケージを読み込んだ後にhelp(filter)
などとしてfilter
関数のヘルプを参照すると、見慣れぬページが表示されて戸惑う人がいるかもしれません。
1行目にある通り、複数のパッケージがfilter
関数のヘルプを提供しているため、どのパッケージのヘルプが必要か、ユーザーに選択を委ねています。ここではstatsパッケージとdplyrパッケージの2択です。落ち着いて必要な項目を選びましょう。
ところでR言語にはパッケージ名::オブジェクト名
という記法を使って、特定のパッケージのオブジェクトを参照する記法があります。この記法を応用すると、同名のオブジェクトを複数のパッケージが提供していても、明示的に必要なヘルプを表示できます。たとえばdplyr::
のfilter
関数のヘルプを一発で表示できます。?
関数を使う場合は?dplyr::
を実行してください。help
関数を使う場合は書き方が異なり、help(filter, package = dplyr)
といった具合にpackage
引数にパッケージ名を指定します。
特定のS3メソッドのヘルプ
Rの関数の中には、第一引数に与えたオブジェクトのクラスに応じて挙動が変わるものがあります。print
関数もその一種です。たとえば、print
関数に与えたデータが通常のデータフレームか、tibble::
関数によるtidyverse流のデータフレームかで表示が変わります。
# 通常のデータフレームの中身を表示
airquality_df <- head(airquality)
print(airquality_df)
Ozone Solar.R Wind Temp Month Day 1 41 190 7.4 67 5 1 2 36 118 8.0 72 5 2 3 12 149 12.6 74 5 3 4 18 313 11.5 62 5 4 5 NA NA 14.3 56 5 5 6 28 NA 14.9 66 5 6
# tibble化したデータフレームの中身を表示
airquality_tibble <- tibble::tibble(airquality_df)
print(airquality_tibble)
# A tibble: 6 × 6 Ozone Solar.R Wind Temp Month Day <int> <int> <dbl> <int> <int> <int> 1 41 190 7.4 67 5 1 2 36 118 8 72 5 2 3 12 149 12.6 74 5 3 4 18 313 11.5 62 5 4 5 NA NA 14.3 56 5 5 6 28 NA 14.9 66 5 6
しかし、print
関数のヘルプにはオブジェクトのクラスに合わせた挙動の説明がありません。print
関数の実際の挙動は、他の関数に処理を引き継いだものなので、引き継ぎ先の関数を特定し、そのヘルプを参照する必要があります。
引き継ぎ先を知るには、まず、class
関数を使ってオブジェクトに割り当てられたクラスの確認します。たとえばairquality_
変数はairquality_
変数は
# 2種類のデータフレームの持つクラスを確認
class(airquality_df)
[1] "data.frame"
class(airquality_tibble)
[1] "tbl_df" "tbl" "data.frame"
print
関数は、自身の関数名に入力されたオブジェクトのクラス名を加えたprint.
関数などを探し、該当するものに処理を引き継ぎます。オブジェクトが複数のクラスを持つ場合は、最適な候補を選択します。たとえばairquality_
変数は先述の通り3つのクラスを持つので、候補も3つです。
print.
関数tbl_ df print.
関数tbl print.
関数data. frame
優先順位は、class
関数で表示されるクラス名の順です。ここでは、print.
関数が最も優先順位が高く、tibbleパッケージ内に定義が存在するため、print.
関数が採用されます。もし、print.
関数が存在しない場合は、print.
関数が存在すればprint.
関数が採用され、それもなければprint.
関数が採用されます。
したがって、print.
関数やprint.
関数のヘルプを見れば、実際の挙動に関する詳細がわかります。
ここで、print
関数は総称関数print.
関数やprint.
関数はS3メソッドと呼ばれます。
親切なヘルプであれば、UseMethod
関数を使っている関数は総称関数と判断できます。
# 総称関数は内部でUseMethodを使う
print(print)
function (x, ...) UseMethod("print") <bytecode: 0x557d9dce2fb8> <environment: namespace:base>
調査中の関数が総称関数と分かれば、必要なメソッドに関するヘルプも見ておくといいでしょう。ヘルプの表示方法はこれまで紹介した通りで、?
演算子やF1キーが使えます。
総称関数のメソッド一覧を得るにはmethods
関数を使います。
# print関数のメソッド一覧
# 数が多いので一部のみ表示
head(methods("print"))
[1] "print.acf" "print.AES" "print.anova" "print.aov" [5] "print.aovlist" "print.ar"
methods
関数を応用すると、ある総称関数とオブジェクトに対して、どのメソッドが利用されるか調べられます。
# 総称関数から特定のオブジェクトに適合するメソッドを探索する関数の定義
find_method <- function(func, obj) {
# funcの全メソッドを取得
methods_all <- methods(func)
# objに適用されうるメソッドの候補を生成
candidates <- paste0(func, ".", c(class(obj), "default"))
# 候補の中から最初に該当した候補を返す
# 該当なしならNAを返す
candidates[candidates %in% methods_all][1L]
}
# airquality_tibble変数に適合するprintメソッドを探索
find_method("print", airquality_tibble)
[1] "print.tbl_df"
これで、airquality_
変数に対してはprint.
のヘルプを見ればいいと分かりました。
S3メソッドに関するヘルプの検索は、RStudioアドインの
パッケージのヘルプ
パッケージに関して徹底的に学びたいときは、パッケージの提供するヘルプの一覧を開いてみましょう。help
関数にpackage
引数だけ指定して実行すると、表示できます。
# ggplot2パッケージのヘルプ一覧を表示
help(package = ggplot2)
ヘルプの読み方
ヘルプはTitle
関数のヘルプの読み方
ヘルプの大半は関数に関するものなので、本稿では関数のヘルプの読み方に重きを置いて紹介します。データセットのヘルプの読み方も後述しますが、基本は関数のヘルプの読み方に共通します。
- ヘルプの構造を把握する
- 最初に注目するセクションを決める
- 必要なら次に注目するセクションを決める
では実際に、これらのステップについて解説します。
関数のヘルプの構造
多くの関数に共通する重要なセクションは以下の通りです。
- Title
(タイトル) - ヘルプのタイトル
- Description
(概要) - 一段落で関数の用途を簡潔に説明
- Usage
(用法) - 主に引数の既定値を表示
help
関数のヘルプの例:help(topic, package = NULL, lib.
loc = NULL, verbose = getOption("verbose"), try. all. packages = getOption("help. try. ), help_all. packages" type = getOption("help_ type" ))
- Arguments
(引数) - 各引数の説明
- Examples
(用例) - 関数の具体的な使い方の例
- 先の4セクションはすべての関数に必ず存在するが、Examplesは作者次第
最初に注目するセクション
最初にどのセクションに注目するべきかは、ヘルプを開いた目的から自ずと決まります。
- 用途について知りたい → TitleセクションとDescriptionセクション
- 引数について知りたい → UsageセクションとArgumentsセクション
- 具体的な使い方を知りたい → Examplesセクション
次に注目するセクション
次に注目するセクションも当然、目的次第です。用途について知った後、引数について知りたければUsageセクションやArgumentsセクションに進みましょう。
親切なヘルプであれば、次に注目すべきセクションを案内している場合もあります。特にDescriptionセクションやArgumentsセクションの記述は比較的簡素にまとまっており、踏み込んだ説明は別にセクションを立てている傾向にあります。例として、一般化線型モデルのglm
関数のArgumentsセクションを見ると、formula
引数について詳しくは
The details of model specification are given under ‘Details’
.
残念ながら、そこまで親切ではないケースもあります。たとえばk平均法のkmeans
関数のalgorithm
引数の説明は非常に簡素で、アルゴリズムの選択肢が不明なうえに、詳細を得る術を案内していません。このような場合は、セクションタイトルを眺めてみましょう。そもそも記載がない場合を除けば、DetailsやNoteといった細かい話題に触れるためのセクションや、Algorithmセクションなどの独自のセクションを用意しています。kmeans
関数の場合はDetailsに各アルゴリズムの説明をしています。
データセットのヘルプの読み方
データセットのヘルプも基本的には関数のヘルプと同様の手順で読めます。重要なセクションを把握したうえで、目的に応じて注目すべきセクションを見定ましょう。
特に重要なセクションは以下の通りです。
- Title
(タイトル) - Description
(概要) - Usage
(用法) - Format
(フォーマット) - Examples
(用例)
多くが関数のヘルプと共通していますが、Formatセクションは関数のヘルプでは見かけません。Formatセクションはデータセットの構造やそれぞれの値の意味について記述しています。
例としてmtcars
データセットのヘルプのFormatセクションを見てみましょう。1行目は11の変数に対して32点のデータを収録したデータフレームであると記載しています。
A data frame with 32 observations on 11 (numeric) variables.
2行目からはデータフレームの各列について説明しています。たとえば以下の行は、mtcars
データセットの1列目が車の燃費に関するデータである旨を記載しています。
[, 1] mpg Miles/(US) gallon
以上を把握しておけば、データセットのヘルプも必要なところから読み進められることでしょう。
まとめ
本稿ではヘルプの表示方法と読み方について紹介しました。
- RStudioではF1キーで、カーソル位置のオブジェクトに関するヘルプを簡単に表示できる
- ヘルプは重要なセクションを把握しておけば、必要なところだけ読めばいい
この2点をぜひ覚えておいてください。
繰り返しになりますが、必要な情報を手早く得る術を身につければ、その分、分析に集中する時間を確保できます。
ただ、ヘルプは