當我有多個函數來執行復合任務時，如何編寫 R 包文檔？

Question

我有以下 R 函數，我想用它們來獲取任何數值向量的總和、平方和和立方和：

功能更正

ss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i}
}
sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i^2}
}

ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i^3}
}

我想產生向量的總和，向量的平方和和相同向量的立方的總和。 我希望它在我只運行一個函數時打印三個結果，並將包含在 R 包文檔中。

我知道如何通過記錄 R 文件夾及其文件以及描述文件來為一項任務編寫只有一個功能的 R 包，而帶有devtools roxygen2為我完成剩下的工作。

我想要

如果 x <- c(1, 2) 我想要這樣的格式。

ss sss sss

3 5 9

只用包中的一個函數。

請說明您在輸出中使用的向量。

Answer 1

有多種方法可以整合您的功能及其文檔。

警告

因為你問如何整合和記錄你現有的功能，我沒有改進你的功能。 您選擇如何實現ss*()函數取決於您。

力求符合模塊化編程的原則。 您有責任確保您的每個功能都完成自己的工作，以便其他功能可以依賴它們。 因此，您有責任從源頭上糾正任何錯誤。 如果你這樣做，那么修正將從你的輔助函數中“冒泡”到你的包的其余部分——你將“一石激起千層浪”。

但是，就目前而言，您的代碼存在一些明顯的問題。

更正

---

更新

截至目前，根據我的第一個建議，該問題已被編輯以更正以下錯誤。 此外， **運算符已被明智地替換為^ 。

---

您的函數實際上是多余的平方和立方體x ：

sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x*x, .combine = "+") %dopar% {i**2}
  #                     ^^                            ^^^
  #            First time squaring.          Second time squaring.
}


ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x*x*x, .combine = "+") %dopar% {i**3}
  #                     ^^^^                            ^^^
  #             First time cubing.              Second time cubing.
}

結果是sss()實際上使用了 4 次（不是 2 次）冪，而ssq()使用了 9 次（不是 3 次）冪：

sss(x = c(1,2))
# [1] 17

ssq(x = c(1,2))
# [1] 513

你必須要么避免乘以x本身

sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**2}
  #                    ^
  #                Corrected
}


ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**3}
  #                    ^
  #                Corrected
}

或移除**2和**3之后%dopar% {i

sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x*x, .combine = "+") %dopar% {i}
  #                                                  ^
  #                                              Corrected
}


ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x*x*x, .combine = "+") %dopar% {i}
  #                                                    ^
  #                                                Corrected
}

得到你想要的輸出：

sss(x = c(1,2))
# [1] 5

ssq(x = c(1,2))
# [1] 9

筆記

第一次修正更具擴展性，因為

  foreach::foreach(i = x, .combine = "+") %dopar% {i**10}

比輸入短

  foreach::foreach(i = x*x*x*x*x*x*x*x*x*x, .combine = "+") %dopar% {i}

對於更高的權力，如10 。

改進

坦率地說，對於如此簡單的操作，您的代碼非常復雜。 如果你真的需要自定義函數——並且每個和都有一個單獨的函數——你可以用base R 來做到這一點：

ss <- function(x){
  sum(x)
}

sss <- function(x){
  sum(x^2)
}

ssq <- function(x){
  sum(x^3)
}

綜合文件

根據R 文檔...好吧...記錄 R，您可以在同一個.Rd文檔中描述幾個相關的函數。

例子

考慮如何base::nrow()與像相關功能一起記錄ncol ：

描述

nrow和ncol返回行或列的數量存在於x 。 NCOL和NROW將向量視為 1 列矩陣，甚至是 0 長度向量，與as.matrix()或cbind()兼容，請參見示例。

用法

nrow(x) ncol(x) NCOL(x) NROW(x)

參數

x

向量、數組、數據框或NULL 。

⋮

應用

您可能希望在同一頁面上一起記錄ss() 、 sss()和ssq() 。 這可以通過roxygen2完成，使用@describeIn標簽

#' Obtain the sum.
#  ⋮
#' @param x A vector of \code{numeric} values.
#  ⋮
ss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i}
}

#' @describeIn ss Obtain the sum of squares.
sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**2}
}

#' @describeIn ss Obtain the sum of cubes.
ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**3}
}

或者使用@rdname標簽：

#' Obtain the sums of various powers: \code{ss} for original values, \code{sss} for their squares, and \code{ssq} for their cubes.
#  ⋮
#' @param x A vector of \code{numeric} values.
#  ⋮
ss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i}
}

#' @rdname ss
sss <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**2}
}

#' @rdname ss
ssq <- function(x){
  `%dopar%` <- foreach::`%dopar%`
  foreach::foreach(i = x, .combine = "+") %dopar% {i**3}
}

綜合功能

您可能想要“整理”您的一組@export ed 函數。

使用現有功能

一方面，您可以創建一個新函數one_sum()來包裝現有函數； 其中one_sum()將是唯一的@export ed 函數：

#' Obtain the sum of any available power.
#  ⋮
#' @param x A vector of \code{numeric} values.
#' @param mode \code{character}. The approach to use when summing: \code{"ss"} to sum the values themselves; \code{"sss"} to sum their squares; and \code{"ssq"} to sum their cubes.
#  ⋮
#' @export
#  ⋮
one_sum <- function(x, mode = c("ss", "sss", "ssq")) {
  if(mode == "ss") {
    ss(x)
  } else if(mode == "sss") {
    sss(x)
  } else if(mode == "ssq") {
    ssq(x)
  } else {
    stop("'mode' must be one of \"ss\", \"sss\", or \"ssq\".")
  }
}

可擴展

另一方面，您可以使用單個函數any_sum()替換所有內容，該函數具有另一個參數power作為用於計算總和的冪：

#' Obtain the sum of any power.
#  ⋮
#' @param x A vector of \code{numeric} values.
#' @param power \code{numeric}. The power to which the addends in \code{x} should be raised.
#  ⋮
any_sum <- function(x, power) {
  sum(x^power)
}

綜合產出

實現您指定的特定輸出

我想要

ss sss qss 30 300 90000

只用包中的一個函數。

您可以利用現有功能或創建全新的功能。

使用現有功能

一方面，您可以在新的three_sums()函數中利用現有函數； 其中three_sums()將是唯一的@export ed 函數：

#' Obtain at once the sums of the three available powers.
#  ⋮
#' @param x A vector of \code{numeric} values.
#  ⋮
#' @export
three_sums <- function(x) {
  setnames(c(ss(x), sss(x), ssq(x)), c("ss", "sss", "qss"))
}

可擴展

另一方面，您可以使用單個函數all_sums()替換所有內容，該函數具有另一個參數powers作為用於計算總和的不同冪。

#' Obtain at once the sums of all given powers.
#  ⋮
#' @param x A vector of \code{numeric} values, to raise to powers and add.
#' @param powers A vector of \code{numeric} values: the powers to which the addends will be raised.
#  ⋮
all_sums <- function(x, powers = 1:3) {
  setNames(object = sapply(X = powers,
                           FUN = function(n){sum(x^n)},
                           simplify = TRUE),
           nm = powers)
}

在這里，您可以指定要查看其總和的每個冪。 例如，下面的調用

all_sums(x = c(1, 2), powers = c(3, 4, 6, 9))

會給你立方體（ 3次方）、 4次方、 6次方和9次方的總和； 全部用於向量c(1, 2) ：

  3   4   6   9 
  9  17  65 513 

筆記

如果未指定powers ，則默認情況下

all_sums(x = c(1, 2))

將使用1 、 2 （平方）和3次（三次）冪

  1  2  3 
  3  5  9 

根據您在示例輸出中的需要。

Answer 2

編輯：我已經更改了代碼，以便輸出是一個向量而不是一個列表。

您可以將您的功能組合成一個功能。 下面是一個例子：

sums <- function(x, methods = c("sum", "squaredsum", "cubedsum")){
  
  output <- c()
  
  if("sum" %in% methods){
    output <- c(output, ss = ss(x))
  }
  
  if("squaredsum" %in% methods){
    output <- c(output, sss = sss(x))
  }
  
  if("cubedsum" %in% methods){
    output <- c(output, ssq = ssq(x))
  }
  
  return(output)
}

默認情況下，所有三個函數都會被調用，結果以列表形式返回。

您可以只指定一個或多個函數，在這種情況下它只會返回被調用函數的輸出。

在您的文檔中，您現在可以將每個可能的方法視為可以設置的變量。

編輯

您的多維數據集函數中存在錯誤。 i***2不占用立方體。 這是i**3 。 正確的函數是：

ssq <- function(x){
`%dopar%` <- foreach::`%dopar%`
foreach::foreach(i = x*x*x, .combine = "+") %dopar% {i**3}
}