Would it make sense for use_data or another fonction to also help with data documenting, like the roxygen2 function skeleton one gets from RStudio menu?
I asked in https://community.rstudio.com/t/template-for-documenting-a-dataset/5365/2 whether such functionality already existed somewhere and it doesn't seem so from the (1!) answer I received.
maelle
All 10 comments
Yes, it is interesting to think out loud whether this advice could be automated:
Documenting datasets section in http://r-pkgs.had.co.nz/data.html
If we can agree to an implementation, then you (or someone else) could implement in a PR!
Are you game to propose a sketch?
jennybc
on 21 Feb 2018
:tada: I am happy to discuss, but couldn't implement it myself in the short term 馃槩
I've thought a bit, not much, about it and here what came to mind:
if the template creating becomes part of
use_datathen there should be an overwrite parameter, FALSE by default (because I could run the data preparation script again if I update the data, without wanting to overwrite the existing documentation).the template would be loaded in a brand new (if non existing) .R file called nameofthedata-docs.R?
if the data in say
usethis::use_data_docis a data.frame the items could be filled with the names and types of the variables (a bit like what the roxygen2 skeleton does with function parameters), so the function wouldn't "just" load a template. Not sure about other data types.btw should the script where data is prepared when there's one be linked in the data documentation in details? not that this could be automated.
maelle
on 21 Feb 2018
This would basically be a roxygen equivalent to the confusingly named utils::prompt function. I agree this would be useful!
prompt(mtcars)
#> Created file named 'mtcars.Rd'.
#> Edit the file and move it to the appropriate directory.
readLines("mtcars.Rd")
#> [1] "\\name{mtcars}"
#> [2] "\\alias{mtcars}"
#> [3] "\\docType{data}"
#> [4] "\\title{"
#> [5] "%% ~~ data name/kind ... ~~"
#> [6] "}"
#> [7] "\\description{"
#> [8] "%% ~~ A concise (1-5 lines) description of the dataset. ~~"
#> [9] "}"
#> [10] "\\usage{data(\"mtcars\")}"
#> [11] "\\format{"
#> [12] " A data frame with 32 observations on the following 11 variables."
#> [13] " \\describe{"
#> [14] " \\item{\\code{mpg}}{a numeric vector}"
#> [15] " \\item{\\code{cyl}}{a numeric vector}"
#> [16] " \\item{\\code{disp}}{a numeric vector}"
#> [17] " \\item{\\code{hp}}{a numeric vector}"
#> [18] " \\item{\\code{drat}}{a numeric vector}"
#> [19] " \\item{\\code{wt}}{a numeric vector}"
#> [20] " \\item{\\code{qsec}}{a numeric vector}"
#> [21] " \\item{\\code{vs}}{a numeric vector}"
#> [22] " \\item{\\code{am}}{a numeric vector}"
#> [23] " \\item{\\code{gear}}{a numeric vector}"
#> [24] " \\item{\\code{carb}}{a numeric vector}"
#> [25] " }"
#> [26] "}"
#> [27] "\\details{"
#> [28] "%% ~~ If necessary, more details than the __description__ above ~~"
#> [29] "}"
#> [30] "\\source{"
#> [31] "%% ~~ reference to a publication or URL from which the data were obtained ~~"
#> [32] "}"
#> [33] "\\references{"
#> [34] "%% ~~ possibly secondary sources and usages ~~"
#> [35] "}"
#> [36] "\\examples{"
#> [37] "data(mtcars)"
#> [38] "## maybe str(mtcars) ; plot(mtcars) ..."
#> [39] "}"
#> [40] "\\keyword{datasets}"
Created on 2018-02-21 by the reprex package (v0.2.0).
jimhester
on 21 Feb 2018
I wonder if a similar idea could be used for documenting the _output_ of a function. When a function outputs a data.frame with quite a few columns for instance, it'd generate the list of items.
maelle
on 21 Feb 2018
I like the idea of the documenting the output of a function. But in terms of reproducibility you would properly want the function-call to be documented somewhere to avoid confusion with functions of variable output sizes.
You could for example have
usethis::use_data_doc(data.frame_producing_function())
Saved in a .R somewhere?
EmilHvitfeldt
on 4 Mar 2018
For documentation creating this function could be expanded on if we want to avoid dependence on utils
library(magrittr)
data_frame_roxygen <- function(obj) {
if (inherits(obj, c("data.frame", "tibble"))) {
cl <- sapply(obj, typeof)
items <- paste0(sprintf("#' \\item{\\code{%s}}{%s ---DESCRIPTION---}", names(cl), cl))
if(length(items) > 10) {
items <- paste0(c(items[seq_len(10)], "#' ..."), collapse = "\n")
} else {
items <- paste0(items, collapse = "\n")
}
header <- c(
title = paste0("#' @title ", deparse(substitute(obj))),
description = "#' @description ---COLUMN DESCRIPTION---",
format = sprintf("#' @format A data frame with %s rows and %s variables:", nrow(obj), length(cl))
)
ret <- sprintf(
"%s\n%s\n%s",
paste(header, collapse = "\n"),
sprintf("#' \\describe{\n%s \n#'}", items),
sprintf('\n"%s"', deparse(substitute(obj)))
)
}
ret
}
data_frame_roxygen(iris) %>% stringr::str_split("\n")
#> [[1]]
#> [1] "#' @title iris"
#> [2] "#' @description ---COLUMN DESCRIPTION---"
#> [3] "#' @format A data frame with 150 rows and 5 variables:"
#> [4] "#' \\describe{"
#> [5] "#' \\item{\\code{Sepal.Length}}{double ---DESCRIPTION---}"
#> [6] "#' \\item{\\code{Sepal.Width}}{double ---DESCRIPTION---}"
#> [7] "#' \\item{\\code{Petal.Length}}{double ---DESCRIPTION---}"
#> [8] "#' \\item{\\code{Petal.Width}}{double ---DESCRIPTION---}"
#> [9] "#' \\item{\\code{Species}}{integer ---DESCRIPTION---} "
#> [10] "#'}"
#> [11] ""
#> [12] "\"iris\""
data_frame_roxygen(ggplot2::mpg) %>% stringr::str_split("\n")
#> [[1]]
#> [1] "#' @title ggplot2::mpg"
#> [2] "#' @description ---COLUMN DESCRIPTION---"
#> [3] "#' @format A data frame with 234 rows and 11 variables:"
#> [4] "#' \\describe{"
#> [5] "#' \\item{\\code{manufacturer}}{character ---DESCRIPTION---}"
#> [6] "#' \\item{\\code{model}}{character ---DESCRIPTION---}"
#> [7] "#' \\item{\\code{displ}}{double ---DESCRIPTION---}"
#> [8] "#' \\item{\\code{year}}{integer ---DESCRIPTION---}"
#> [9] "#' \\item{\\code{cyl}}{integer ---DESCRIPTION---}"
#> [10] "#' \\item{\\code{trans}}{character ---DESCRIPTION---}"
#> [11] "#' \\item{\\code{drv}}{character ---DESCRIPTION---}"
#> [12] "#' \\item{\\code{cty}}{integer ---DESCRIPTION---}"
#> [13] "#' \\item{\\code{hwy}}{integer ---DESCRIPTION---}"
#> [14] "#' \\item{\\code{fl}}{character ---DESCRIPTION---}"
#> [15] "#' ... "
#> [16] "#'}"
#> [17] ""
#> [18] "\"ggplot2::mpg\""
avoid dependence on utils
Just a quick comment on this point: utils is one of the base packages, so I would not worry about this.
jennybc
on 4 Mar 2018
I'd personally love to see not only a data documentation template, but also one for regular R functions that reminds users of all the different roxygen tags/where they should go/quick tips on them within the template.
robertamezquita
on 9 Mar 2018
I think this should probably start in roxygen2. We first need a function that produces default documentation before figuring out how to automate its use.
hadley
on 24 Nov 2018
I'm going to close this issue here; if you're interested in this feature please create an issue in roxygen2.
hadley
on 30 Nov 2018
Related issues
uribo
路
5Comments
pieterjanvc
路
5Comments
maxheld83
路
3Comments
lwjohnst86
路
7Comments
hadley
路
3Comments
Most helpful comment
This would basically be a roxygen equivalent to the confusingly named utils::prompt function. I agree this would be useful!
Created on 2018-02-21 by the reprex package (v0.2.0).