48  ヘルプ

この章では、R や R パッケージに関する質問や、報告すべき不具合を Github に Issue (イシュー)として投稿する方法を説明することに加え、R や R パッケージについて質問がある場合に、再現可能なサンプルコード(英語で reprex と呼ばれる)を用いて Stack Overflow 等のオンラインフォーラムに投稿する方法を解説します。

48.1 Github に Issue を投稿する

多くの R パッケージやプロジェクトのコードは、 Github.com にアップロードされています。Github に「Issue」を投稿することで、パッケージやプロジェクトの作成者と直に連絡をとることができます。

作成した R パッケージやプロジェクトを Github にアップロードする方法は、第 46 章 Git と Github を使用したバージョン管理と共同作業の章で詳しく説明しています。

Github では、各プロジェクトがリポジトリに保管されます。各リポジトリには、コード、データ、アウトプット、ヘルプドキュメントなどが含まれています。また、「Issues」と呼ばれる作成者とのコミュニケーションの手段もあります。

下の図は、incidence2 パッケージ(流行曲線(エピカーブ)を作成するために使用)の Github ページです。黄色で着色された箇所が「Issues」タブです。このパッケージには、5 つの Issue (未解決の質問、問題点、不具合の修正リクエスト等)があることがわかります。

「Issues」タブを開くと、現在までに投稿されている Issue が表示されます。自分の質問や修正リクエストを新たに Issue として投稿する前に、既に投稿されている Issue に目を通し、同じ質問や修正リクエストがすでに投稿されていないかを確認しましょう。まだ投稿されていない場合は、右側にある緑色の「New issue」ボタンをクリックし、新しい Issue を作成・投稿することができます。新しい Issue の作成には、Github アカウントが必要です。

新たに Issue を投稿する際は、以下で説明する方法で、最低限の再現可能なサンプルコード(reprex)を提示してください。また、Issue を投稿する際は R パッケージやプロジェクトの作成者に敬意を払い、あなたの質問や修正リクエストについて、丁寧に説明しましょう。R パッケージやプロジェクトの作成者の多くは、空き時間にボランティアで開発しています。(このハンドブックもそのような有志が集まって作成されました!)

自分の Github リポジトリに投稿された Issue の取り扱い方法については、 Issue に関する Github のページをご覧ください。

48.2 再現可能なサンプルコードを作成する

オンラインフォーラムや Github の Issue に投稿する際には、再現可能なサンプルコード(英語で reprex と呼ばれる)を記載することが重要です。多くの人は、あなたが投稿した質問や不具合を解決するために、力を貸したいと思っています。第三者があなたの質問を理解し、解決の手助けをするためには、その問題を手元で再現できるサンプルコードが必要です。サンプルコードに必要な要件は以下の通りです。

  • ヘルプが必要な質問や問題を明確に説明する
  • 問題を再現するのに必要な最小限のデータとコードが含まれている
  • すべてのオブジェクト(データ等)やパッケージを読み込むコード (library()p_load())が含まれているなど、再現性がある

投稿する際は、機密データを含まないように注意してください! 機密上の理由または他の理由で、実際に使用したデータをオンラインフォーラムや Github に投稿したくない、またはすべきでない場合は、データフレーム(data frame)を用いて別の異なるデータセットを作成する、または、R に組み込まれているデータセットを使用することをおすすめします(data() を入力すると、R に組み込まれているデータセットのリストが表示されます)。

reprex パッケージとは?

reprex パッケージを使用すると、再現可能なサンプルコードを簡単に作成することができます。

  1. tidyverse パッケージを読み込む(reprex は tidyverse パッケージに含まれています)。
# tidyverse をインストールし、読み込む
pacman::p_load(tidyverse)
  1. R スクリプトで、投稿したい質問や問題のサンプルコードを作成する(パッケージやデータの読み込みに関するコードを始めに記載し、質問や問題について明確に説明するコードを段階的に書きましょう)。
# 必要なパッケージを読む込む
pacman::p_load(
     tidyverse,  # データ管理とデータ可視化のためのパッケージ
     outbreaks)  # アウトブレイクについてのサンプルデータを提供するパッケージ

# インフルエンザ流行曲線(エピカーブ)のラインリスト
outbreak_raw <- outbreaks::fluH7N9_china_2013  # outbreaks パッケージからデータを読み込む

# データクリーニング(前処理)
outbreak <- outbreak_raw %>% 
     mutate(across(contains("date"), as.Date))

# 流行曲線(エピカーブ)をプロットする

ggplot(data = outbreak)+
     geom_histogram(
          mapping = aes(x = date_of_onset),
          binwidth = 7
     )+
  scale_x_date(
    date_format = "%d %m"
  )

作成したコードをクリップボードにコピーし、以下のコマンドを実行します。

reprex::reprex()

RStudio の Viewer パネル(pane)に HTML で出力されたアウトプットが表示されます。このアウトプットには、すべてのコードと、警告メッセージ(warnings)、エラー、ならびに作成したプロットが含まれます。このアウトプットはクリップボードにもコピーされているので、Github の Issue やオンラインフォーラムに投稿する際、貼り付けて使用できます。

  • session_info = TRUE とした場合、sessioninfo::session_info() で出力されるアウトプットと、使用している R ならびに R パッケージのバージョンが表示されます。
  • wd = 引数を使用した場合、作業ディレクトリを表示できます。
  • 引数についての詳細は、 こちらのページ を参照いただくか、 R で ?reprex コマンドを実行してください。

上記で紹介したサンプルコードでは、 ggplot() 関数がエラーを引き起こしました。date_format = ではなく、date_labels = を使用する必要があります。

最小限のデータとは?

第三者があなたの質問に回答するためには、あなたのデータを使用する必要があります。理想は、第三者がコードを用いてデータを作成できることです。

第三者が利用できる最小限のデータセットを作成するためには、データの匿名化や、実際のデータの一部のみを使用することが必要になります。

dput() 関数を使用し、最小限のデータセットを作成することもできます(詳細については、後日追記します)。

48.3 オンラインフォーラムに質問を投稿する

質問をオンラインフォーラムに投稿する前に、既に投稿されている質問をたくさん読み、上手に質問を説明している投稿と、そうではない投稿との違いを理解しましょう。質問を投稿する手順は、以下の通りです。

  1. まず、質問を投稿するかどうかを決めます。あなたの質問と同じ質問が既に投稿されていないか、そのフォーラムのウェブサイトを様々なキーワードで徹底的に検索しましょう。

  2. 質問を投稿すると決めた場合、質問には、第三者にわかりやすい具体的なタイトルをつけましょう(「ヘルプが必要です!」「助けてください!」等、質問内容が明記されていないタイトルは避けましょう)。

  3. 質問を書き始めます。質問を書く際の注意点は、以下の通りです。

  • 質問や問題に直面した状況とその問題を説明する
  • 似たような質問・問題の投稿に言及し、その投稿がどのようにあなたの質問に答えていないかを説明する
  • 第三者があなたの質問・問題についてよく理解するため、質問・問題に関連する情報を含める
  • 最低限の再現可能なサンプルコードを R セッションの情報(あなたがそのコードを実行した環境)とともに示す
  • タイプミスや文法ミスに注意し、質問を段落に分けて読みやすくする
  1. 質問投稿後は、投稿の更新状況を常にモニターし、第三者が更なる説明を求めた場合は、応答してください。ほとんどの回答者はボランティアであなたを助けています。回答者の方には、礼儀正しく、親切に対応しましょう。追加の質問がある場合は、先に投稿した質問内容に追加するべきか、別の質問として投稿すべきかを検討してください。

  2. 回答が得られて質問が解決した場合は、投稿のステータスを解決済みに変更してください。解決済みのマークを付けることで、あなたと同じ質問をもつ他の人が、解決策を見つけやすくなります。

良い質問をする方法についての詳細は、こちらの記事 や、 Stack Overflow の行動規範 をご覧ください。

48.4 参考資料

Tidyverse ウェブサイトのヘルプページは こちら

最小限のデータセットを作成するためのヒントは こちら

dput() 関数についての公式ドキュメントは こちら