8

私は R パッケージを作成しており、ドキュメントのビネットに多くの時間を費やしています。のようなものを追加する必要があるかどうか疑問に思っています

.onAttach <- function( libname , pkgname ){
   packageStartupMessage("use `browseVignettes('packagename')` to see vignettes")
}

ユーザーが電話をかけるとすぐに表示されます

library(packagename)

パッケージのビネットについてユーザーに知らせる最善の方法は何ですか? それとも、明示的な通知なしにユーザーがそれらを探すと想定しているだけですか?

4

2 に答える 2

7

ビネットの遍在

日常的な R ユーザーの目には、ビネットについて留意すべき点がいくつかあります...

  1. CRAN パッケージ ページで入手できます (作成者がパッケージを持っている場合は、パッケージの優れた品質チェックになります!)
  2. パッケージ バイナリに追加され、browseVignettes(package = "pkgname")[ご指摘のとおり]を介してビネット ヘルプ セクションに表示されます。
  3. Rパッケージソース内に埋め込まれています
  4. ビネットに埋め込まれたコードを別のスクリプト デモとして使用する可能/demos性demo()
  5. すべての中で最も重要な部分:ビネットについて実際に知っているユーザーはまったくいません。

したがって、パッケージのドキュメントにかなりの時間を費やす場合は、少なくとも起動時にそのような機能が存在することを示す必要があります。

ユーザーの利益のためにpackageStartupMessage()内部で悪用する。.onAttach()

パッケージのロード時に、コンソールは比較的クリアであり、通常の青色の R テキストとのコントラストが比較的高いため (クレヨンがない場合)、ユーザーには赤色のテキストが確実に表示されます。ただし、ビネットの存在をユーザーに警告しても意味がない場合がいくつかあります。

  1. セッションが非対話型 (bash スクリプトなど) の場合。
  2. ユーザーが R 'pro' の場合
  3. ユーザーが長い間あなたのパッケージを使用している場合、ユーザーはメッセージを無視するようになります。

したがって、不十分な実装には否定的packageStartupMessage()です。

その結果、4 つの異なる条件で起動メッセージを導入することをお勧めします。

  1. (すべて) を照会して、人間が存在するかどうかを確認しますinteractive()。その場合は、次に進みます。
  2. (標準) 少なくとも 3 つの異なる起動メッセージのリストを用意し、起動ごとにランダムに 1 つを選択して表示します。
  3. (通常) ランダムに番号を生成して、起動メッセージを表示するかどうかを決定します。
  4. (Pro) パッケージの読み込みをカウントし、パッケージの読み込み後x、ユーザーがパッケージを再インストールするまで起動メッセージを強制終了します。

次に、(1) から (3) の原則に従う 2 つのソリューションを紹介し、簡単にするために (1) と (4) のみを示します。

パッケージヒントをランダムに選択する

このバージョンでは、単純に人間をチェックし、パッケージの読み込みメッセージを追加するのを中断し、表示するヒントをランダムに 1 つ選択します。[0,1] の間の確率を生成するコマンドbaseである の範囲外で必要な依存関係は 1 つだけです。stats::runif

#' @importFrom stats runif
.onAttach <- function(...) {

  # If interactive, hide message
  # o.w. check against rng seed.
  if (!interactive() || stats::runif(1) > 0.5){
     return()
  }

  # Create a list of helpful tips
  pkg_hints = c(
    "Check for updates and report bugs at https://cran.r-project.org/web/packages/pkgname/.",
    "Use `suppressPackageStartupMessages()` to remove package startup messages.",
    "To see the user guides use `browseVignettes('pkgname')`"
  )

  # Randomly pick one hint
  startup_hint = sample(pkg_hints, 1)

  # Display hint
  packageStartupMessage(paste(strwrap(startup_hint), collapse = "\n"))
}

パッケージの読み込みをカウントする

カウンターを使用するには、「作業」ディレクトリ/ユーザー空間ではなく、パッケージのインストール ディレクトリに保存する機能を利用します。これにはいくつかの問題が関連しており、簡単に説明します。

  1. ユーザーはライブラリを表示する権限しか持たず、systemライブラリを変更できない場合があります (ユーザー ライブラリは問題ありません)。
    • したがって、カウンターをインクリメントできないため、常にこのメソッドでパッケージ ヒントを受け取ります。
  2. systemパッケージがライブラリ にある場合、カウンターは共有される可能性があります。
    • これにより、すべてのヒントがすばやく使用されます。
  3. エラー ログのサイズが大きくなる場合があります。

もちろん、これらの問題を無効にするために、R_USERまたはHOME環境変数を介してユーザー空間内に独自のフォルダーを作成することもできます。(演習は読者に委ねます。ヒント: と を使用Sys.getenv()してくださいdir.create()。)

いずれにせよ、この機能の優れた点の 1 つは、後でパッケージ内に「パッケージ使用統計の送信」機能を含めることができることです。これにより、実際には、現在の RStudio CRAN ミラー パッケージのダウンロード情報と比較して、かなり正確な - phone home - 統計が得られます。しかし、私は脱線します。

この方法を機能させるには、CRAN に提供される初期パッケージに対してもう少し準備作業を行う必要があります。具体的には、おそらく次の方法でカウンターを事前にセットアップする必要があります。

# Set working directory to package
setwd("package_dir")

# Create the inst directory if it does not exist
if(!dir.exists("inst")){
  dir.create("inst")
}

# Create a counter variable
pkg_count = 0

# Save it into a .rda file
save(pkg_count, file="inst/counter.rda")

そして今、.onAttach()カウンターの実装に！

.onAttach <- function(...){
  if (!interactive()) return()

  # Get the install directory location of the counter
  path_count = system.file("counter.rda", package = "pkgname")

  # Suppress messages by default
  displayMsg = FALSE

  # Are we able to load the counter?
  a = tryCatch(load(path_count), error = function(e){"error"}, warning = function(e){"warning"})

  # Set error variable
  count_error = a %in% c("error","warning")

  # Check if the count is loaded
  if(!count_error){

    # Check if load count is low... 
    if(pkg_count < 10){
      pkg_count = pkg_count + 1

      # Try to save out
      try(save(pkg_count, file = path_count), silent=TRUE)
      displayMsg = T
    }
  }

  # Display message (can be suppressed with suppressPackageStartupMessages)
  if(displayMsg){
    packageStartupMessage("use `browseVignettes('packagename')` to see vignettes")
  }
}

最後の考え

パッケージの依存関係がある場合 (例: など) 、パッケージに記述されたメッセージよりも前に表示される独自の起動メッセージのセットがある可能性があることに注意してください。Depend:DESCRIPTION

于 2016-05-28T04:33:26.697 に答える