当我有多个函数来执行复合任务时，如何编写 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}
}