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」を実行する

特にF1キーは、ソースコードの読み書きに際して困ったときに素早くヘルプを表示できる協力な武器です。コンソールに?printやhelp(print)と入力する手間が不要なうえ、コンソールに不要なログが溜まりません。

また、RStudioアドインの「Fuzzy Search on R Help」を使う方法は、参照したいヘルプに確信がない場合に便利です[2]。あいまい検索できるのでオブジェクト名を正確に覚える必要がない、複数のキーワードで絞り込み検索できるなど、さまざまなメリットがあります。本記事の筆者が開発しており、以下のブログ記事にて特徴や使い方を解説しています。

• felpパッケージでRのヘルプをあいまいに検索しよう

特定のパッケージ由来のオブジェクトのヘルプ

tidyverseパッケージを読み込んだ後にhelp(filter)などとしてfilter関数のヘルプを参照すると、見慣れぬページが表示されて戸惑う人がいるかもしれません。

1行目にある通り、複数のパッケージがfilter関数のヘルプを提供しているため、どのパッケージのヘルプが必要か、ユーザーに選択を委ねています。ここではstatsパッケージとdplyrパッケージの2択です。落ち着いて必要な項目を選びましょう。

ところでR言語にはパッケージ名::オブジェクト名という記法を使って、特定のパッケージのオブジェクトを参照する記法があります。この記法を応用すると、同名のオブジェクトを複数のパッケージが提供していても、明示的に必要なヘルプを表示できます。たとえばdplyr::filterの「filter」の部分にカーソルを合わせてキーボードショートカットのF1を入力すると、dplyrパッケージのfilter関数のヘルプを一発で表示できます。?関数を使う場合は?dplyr::filterを実行してください。help関数を使う場合は書き方が異なり、help(filter, package = dplyr)といった具合にpackage引数にパッケージ名を指定します。

特定のS3メソッドのヘルプ

Rの関数の中には、第一引数に与えたオブジェクトのクラスに応じて挙動が変わるものがあります。print関数もその一種です。たとえば、print関数に与えたデータが通常のデータフレームか、tibble::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_df変数は「data.frame」クラスを持つのに対し、airquality_tibble変数は「tbl_df⁠」⁠、「⁠tbl⁠」⁠、「⁠data.frame」の3つのクラスを持ちます。

# 2種類のデータフレームの持つクラスを確認

class(airquality_df)
[1] "data.frame"

class(airquality_tibble)
[1] "tbl_df"     "tbl"        "data.frame"

print関数は、自身の関数名に入力されたオブジェクトのクラス名を加えたprint.data.frame関数などを探し、該当するものに処理を引き継ぎます。オブジェクトが複数のクラスを持つ場合は、最適な候補を選択します。たとえばairquality_tibble変数は先述の通り3つのクラスを持つので、候補も3つです。

1. print.tbl_df関数
2. print.tbl関数
3. print.data.frame関数

優先順位は、class関数で表示されるクラス名の順です。ここでは、print.tbl_df関数が最も優先順位が高く、tibbleパッケージ内に定義が存在するため、print.tbl_df関数が採用されます。もし、print.tbl_df関数が存在しない場合は、print.tbl関数が存在すればprint.tbl関数が採用され、それもなければprint.data.frame関数が採用されます。

したがって、print.data.frame関数やprint.tbl_df関数のヘルプを見れば、実際の挙動に関する詳細がわかります。

ここで、print関数は総称関数（generic function）と呼ばれ、print.data.frame関数やprint.tbl_df関数はS3メソッドと呼ばれます。

親切なヘルプであれば、「⁠it is a generic function」などのキーフレーズが登場するかどうかで、調査中の関数が総称関数か判断できます。また、関数の実装を確認すると、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_tibble変数に対してはprint.tbl_dfのヘルプを見ればいいと分かりました。

S3メソッドに関するヘルプの検索は、RStudioアドインの「Fuzzy Search on R Help」も便利です。下記のブログ記事で紹介しているので、ご参照ください。

• felpパッケージでRのヘルプをあいまいに検索しよう

パッケージのヘルプ

パッケージに関して徹底的に学びたいときは、パッケージの提供するヘルプの一覧を開いてみましょう。help関数にpackage引数だけ指定して実行すると、表示できます。

# ggplot2パッケージのヘルプ一覧を表示
help(package = ggplot2)

ヘルプの読み方

ヘルプはTitle（タイトル）やDescription（概要）などを始めとしたいくつかのセクションに構造化されています。構成はさまざまですが、共通して重要なセクションがあります。ここでは、重要なセクションの概要を説明した後、目的に応じて、どのような順番で読み進めればいいか説明します。最初から最後まで読もうと気負うことはありません。

関数のヘルプの読み方

ヘルプの大半は関数に関するものなので、本稿では関数のヘルプの読み方に重きを置いて紹介します。データセットのヘルプの読み方も後述しますが、基本は関数のヘルプの読み方に共通します。

1. ヘルプの構造を把握する
2. 最初に注目するセクションを決める
3. 必要なら次に注目するセクションを決める

では実際に、これらのステップについて解説します。

関数のヘルプの構造

多くの関数に共通する重要なセクションは以下の通りです。

• Title（タイトル⁠）⁠
  • ヘルプのタイトル
• Description（概要⁠）⁠
  • 一段落で関数の用途を簡潔に説明
• Usage（用法⁠）⁠
  • 主に引数の既定値を表示
  • help関数のヘルプの例：

    help(topic, package = NULL, lib.loc = NULL,
         verbose = getOption("verbose"),
         try.all.packages = getOption("help.try.all.packages"),
         help_type = getOption("help_type"))
    

• Arguments（引数⁠）⁠
  • 各引数の説明
• Examples（用例⁠）⁠
  • 関数の具体的な使い方の例
  • 先の4セクションはすべての関数に必ず存在するが、Examplesは作者次第

最初に注目するセクション

最初にどのセクションに注目するべきかは、ヘルプを開いた目的から自ずと決まります。

• 用途について知りたい → TitleセクションとDescriptionセクション
• 引数について知りたい → UsageセクションとArgumentsセクション
• 具体的な使い方を知りたい → Examplesセクション

次に注目するセクション

次に注目するセクションも当然、目的次第です。用途について知った後、引数について知りたければUsageセクションやArgumentsセクションに進みましょう。

親切なヘルプであれば、次に注目すべきセクションを案内している場合もあります。特にDescriptionセクションやArgumentsセクションの記述は比較的簡素にまとまっており、踏み込んだ説明は別にセクションを立てている傾向にあります。例として、一般化線型モデルのglm関数のArgumentsセクションを見ると、formula引数について詳しくは「Details」を参照せよとの一文が添えられています。

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点をぜひ覚えておいてください。

繰り返しになりますが、必要な情報を手早く得る術を身につければ、その分、分析に集中する時間を確保できます。

ただ、ヘルプは「説明書」の性質が強く、無機質で頭に入りにくいと感じることもあるでしょう。そういったときは、技術書と合わせて学習を進めるのも一手です。本連載の執筆陣が手がけた「Rが生産性を高める」は、さまざまなパッケージを駆使して、データ分析ワークフロー効率化を実践します。ぜひ、手にとってみてください。