Giter Club home page Giter Club logo

r-pkgs's Introduction

R Packages

render Netlify Status

This repo holds the code and text behind the R Packages book. The site is built with Quarto.

  • The first edition is no longer available online.
  • A second edition is under development and available at https://r-pkgs.org.

Notes on mechanics

Quarto callouts look like this:

::: callout-tip
Here's a super handy nifty thing!
:::

At the time of writing (2022-08-31), we use callout-tip, callout-warning, callout-note, and callout-important. The XXX of callout-XXX is its type and controls the icon and color:

  • -tip green
  • -warning orange
  • -note blue
  • -important red

Use a ##-level header to caption the callout.

Do this for tips specific to RStudio:

::: callout-tip
## RStudio
Here's a super handy nifty thing about RStudio specifically.
:::

The other callout that appears multiple times is:

::: callout-warning
## Submitting to CRAN
Here's something to be super careful about.
:::

r-pkgs's People

Contributors

ahmad-alsaleh avatar ateucher avatar bklamer avatar daattali avatar davidkane9 avatar earino avatar hadley avatar imchoyoung avatar ironholds avatar ismayc avatar jacobbien avatar jdblischak avatar jennybc avatar jimhester avatar jonthegeek avatar lindbrook avatar maelle avatar michaelmikebuckley avatar mikejohnpage avatar petermeissner avatar pursuitofdatascience avatar renkun-ken avatar rmsharp avatar salim-b avatar srushe avatar stewid avatar tmstauss avatar wibeasley avatar xiaosongz avatar zkamvar avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

r-pkgs's Issues

p. 35: devtools::use_package (here: Import and Suggests)

Hi Hadley,

I follow your workflow throughout the book. When reading p. 35 I tried to use devtools::use_packages("mypackage") on my newly created package but got the error:

Error: mypackage must be installed before you can take a dependency on it

At this point of time (in the book) I have not yet loaded my newly created package.

Should there be another step first?

Kind regards

Georg

Contraction: Source comment example contradicts guide

The source code comment examples used following passage [https://github.com/hadley/r-pkgs/blob/master/r.rmd] contradicts the "Comments should explain the why, not the what.":


Commenting guidelines

Comment your code. Each line of a comment should begin with the comment symbol and a single space: #. Comments should explain the why, not the what. \index{comments}

Use commented lines of - and = to break up your file into easily readable chunks.

# Load data ---------------------------

# Plot data ---------------------------

"Documenting datasets" is out of sync?

It seems to me that the section "Documenting datasets" is quite largely out of sync with the actual code being used in the documentation of the diamonds dataset in the ggplot2 package. I do not know whether this is intential, but it can be confusing.

Moreover, a short note on where to place this documentation block (in the ggplot2.r file) would be nice. At least I was wondering where I should put that.

(I assign the copyright of this contribution to Hadley Wickham.)

Minor typos in figure captions in Kobo reader version

Caption to Figure 13-6 "...changed in the seclted [selected] file"
Caption to Figure 13-8 "...all the commits in your at top.."? Perhaps "...all the commits in your file at the top..."

I assign the copyright of this contribution to Hadley Wickham

New readme policies?

Hi, Hadley!

It seems CRAN has new readme.md policies:

It was recently pointed out to us that some README.html files (generated
from the corresponding README.md ones) on the CRAN package web pages are
incomplete, missing 'local' images not available from the web page and
in most cases actually not even shipped with the package. This clearly
should be changed, so we will move to using '--self-contained' for the
pandoc conversion to ensure that the README.html files are "complete".

Of course, this implies that all 'local' images used in README.md are
needed in the package sources.

If the images are also used for vignettes or Rd files, you can put them
in the 'vignettes' or 'man/figures' directories. Otherwise, please put
them in the top-level 'tools' directory, or a subdirectory of it.

The CRAN incoming checks in r-devel were changed to perform the pandoc
conversion checks with '--self-contained', and hence will warn about
missing images.

Pls ensure completeness in the next regular update of your package.

So I guess the suggestion of including the figures in .Rbuildignore might not be appropriate anymore.

Import advice generates unfortunate NOTE in R CMD check

From namespace/import-r:

If you are using just a few functions from another package, my recommendation is to note the package name in the Imports: field of the DESCRIPTION file and call the function(s) explicitly using ::, e.g., pkg::fun().

This generates CMD check note Namespace in Imports field not imported from .... For example in the current lubridate:

* checking dependencies in R code ... NOTE
Namespace in Imports field not imported from: ‘memoise’
  All declared Imports should be used.

To silence this note one would need to use @importFrom pkg func at least once in the package.

why the recommendation to export methods for internal S3 generics?

"However, I recommend exporting every S3 method you write because it's simpler and makes it less likely that you'll introduce hard to find bugs." in the Namespaces page.

AFAICT, if the S3 generic function is not exported, exporting the S3 methods results in polluting the exported namespace with the S3 methods. FWIW I'm using #' @keywords internal also. When the generic is exported the namespace is unchanged whether they are exported or not. Given these things, I don't understand the recommendation.

roxygen2   * 5.0.1       2015-11-11 CRAN (R 3.2.3)

Comments on Comments

The section on roxygen says:

Each block includes some text before the first tag. This is called the introduction, and is parsed specially:

Does this not introduce the potential for confusion as to why none of my packages have text before the first tag, which is @title? ;p. That is, it's possibly to write valid roxygen syntax that includes that text after tags, as well as valid roxygen with no tags for that text.

@param x,y Description: Not parseable

The syntax @param x,y Description suggested in http://r-pkgs.had.co.nz/man.html#man-functions is as far as I know not documented in Doxygen/roxygen.

This is a problem for instance when using tidyr with Rstudio, where the contextual help does not show for some arguments of the tidyr::spread function:

image

For other arguments the description is well given:

image

I think it would be good to either try to document the @param x,y Description behaviour in roxygen/doxygen and push to fix the RStudio contextual help issue, or to refrain from using it.

This is a very minor issue, I may be able to help fixing it but I would like feedback on your opinion on which way we should move to.

In case you need it, I assign any copyright of this contribution to Hadley Wickham.

git/github, really necessary to use keys? https is so nice

Although it looks like RStudio makes it easy to use ssh keys, they can be a pain to setup on some platforms, and as soon as you want multiple github accounts, it can be really painful. https is really nice, and is useful in that one does not have to maintain the ssh keys, but simply remember their username and password. I know it would add to the chapter, but I don't think it would add much, and could be more of an addendum at the end??

update when Hadley will be in DC

Sidebar note:

Want to learn from me in person? I'm next teaching in DC, Sep 14-15.

refers to last year (2015).

I'm in DC and would love to know when Hadley will be teaching this course again!

Add LICENSE

Check in contract exactly what CC license I need.

Namespaces and Generics

I work with a bunch of actuaries who recently switched from matlab to R.

While working on s3 classes, we could not figure out how to write a generic that may or may not already be defined and not interfere with it.

For ex: lets pretend we don't a'ready know that a generic exists for plot. So we write our s3 class, add a generic for plot:

plot <- function(x){ UseMethod("plot", x)}

then I have a function:

plot.myclass <- function(x){{#some code)}

The generic above will cause plot to stop working for other objects that have a plot function because of how we only require x and not x, y, etc.

I think this may be a common question that others may have. How can you write a generic function without interfering if it is already defined or may be defined?

I thought I made some headway on this by using a package and a namespace.

I manually exported my plot.myclass in the namespace file and this seemed to work.

I can call plot with myclass and plot can still be called from other objects.

But when I switched to roxygen and used the export attribute to both the generic plot and plot.myclass this did not work as expected.

Maybe there is a way to force the s3 plot.myclass to be exported using export rather then s3method through roxygen.

I thought this may be something worth adding to your book. I wouldn't be surprised if other noobs wanted to do something like this as well.

My code looks like:

#' @export
my_class_less <- function(x=1){
  object <- list(my_val = 666*x, our_val=999*x)
  class(object) <- "my_class_less"
  return (object)
}

plot <- function(x){
  UseMethod("plot", x)
}

#' @export
plot.my_class_less <- function(obj)  {
  obj$my_val <- 1234
  return(obj)
}

The namespace file looks like:

# Generated by roxygen2 (4.0.2): do not edit by hand

S3method(plot,my_class_less)
export(my_class_less)

This situation can happen if a user defines a generic with its own signature in a package, but another package is loaded first with a different signature.

Stephen

Coding style: class predicates and coercion functions

r-pkgs' coding style advocates an underscore convention. However, there appears to be some exceptions in various packages following this coding style. Class predicates (is.class()) and coercion functions (as.class()) generally use dots.

Maybe this issue should be clarified.

Add richer license discussion

  • Clarify use of LICENSE, LICENSE.note, COPYING, COPYING.lib, AUTHORS, COPYRIGHTS and NOTICE
  • Describe which go in package dir and which in inst/
  • More information about the GPL and how it plays with packages that link to R

Markdown ordered lists guidance

The guidance for Markdown ordered lists caught me for a loop. It recommends a syntax of leaving all numbered list elements the same:

1. Item 1
1. Item 2
1. Items are numbered automatically, even though they all start with 1.

While this is perfectly valid Markdown, I think it confuses rather than clarifies. Any numbers will be parsed the same way, and insertion of random numbers into the list doesn't affect its rendering. It'd be better to be consistent with the other resources showing ordered lists in a simple ascending fashion, as that leads to clearer raw text, and in most cases leads to a consistency of referencing between the raw and rendered versions. That the numbers are arbitrary is perhaps worth mentioning as an aside.

A few other presentations of ordered lists:

Happy to make a pull request, but figured an issue was in order first since this is in effect a nit.

"I assign the copyright of this contribution to Hadley Wickham".

p. 39: Saving options

Hi Hadley,

I do not understand the command sequence for saving options. Shouldn't it be that way:

old <- options()
options(stringsAsFactors = FALSE)
on.exit(options = old, add = TRUE)

and likewise

old <- getwd()
setwd(tempdir())
on.exit(setwd(old), add = TRUE) ?

If I am mistaken please say so.

Kind regards

Georg

typo change: Git and Github page

On the Git and Github page, "Record Changes" paragraph, the following text is written:
"Using a Git commit is like using an anchors and other protection when climbing.".
Suggested revision:
"using anchors and ..."

Or alternatively:
"using an anchor" and...

"I assign the copyright of this contribution to Hadley Wickham".

Failed to install devtools

I used to rely (succesfully) on your contribution for setting-up my MDFA-package on gitHub. I just installed the most recent versions of R and Rstudio and I tried to install your package on my machines (one running Windows 7, the other two computers running Windows 10). Strangely, I got the same error "Error : package 'devtools' is not installed for 'arch = i386'" on all three machines. I searched thoroughly on the web, trying to identify the source of this error and I must admit that I failed to do so, at least so far. In particular, I meticulously reread and followed the "Getting Started" section on your website (http://r-pkgs.had.co.nz/intro.html). Can you infer some advice from the following output (the error message is at the end)? I installed Rtools and all libraries (including the incriminated devtools) seem to be properly installed.

devtools::install_github("hadley/devtools")
Downloading GitHub repo hadley/devtools@master
from URL https://api.github.com/repos/hadley/devtools/zipball/master
Installing devtools
Downloading GitHub repo r-pkgs/pkgload@master
from URL https://api.github.com/repos/r-pkgs/pkgload/zipball/master
Installing pkgload
Installing 1 package: bitops
trying URL 'https://cran.rstudio.com/bin/windows/contrib/3.3/bitops_1.0-6.zip'
Content type 'application/zip' length 36404 bytes (35 KB)
downloaded 35 KB

package ‘bitops’ successfully unpacked and MD5 sums checked

The downloaded binary packages are in
C:\Users\wlmr\AppData\Local\Temp\RtmpKEF1jE\downloaded_packages
Downloading GitHub repo r-pkgs/pkgbuild@master
from URL https://api.github.com/repos/r-pkgs/pkgbuild/zipball/master
Installing pkgbuild
Downloading GitHub repo mangothecat/callr@master
from URL https://api.github.com/repos/mangothecat/callr/zipball/master
Installing callr
"C:/PROGRA1/R/R-331.3/bin/x64/R" --no-site-file --no-environ --no-save
--no-restore --quiet CMD INSTALL
"C:/Users/wlmr/AppData/Local/Temp/RtmpKEF1jE/devtools74c526c27ca/r-pkgs-callr-c2fb27d"
--library="C:/Program Files/R/R-3.3.3/library" --install-tests

  • installing source package 'callr' ...
    ** R
    ** tests
    ** preparing package for lazy loading
    ** help
    *** installing help indices
    ** building package indices
    ** testing if installed package can be loaded
    *** arch - i386
    *** arch - x64

  • DONE (callr)
    "C:/PROGRA1/R/R-331.3/bin/x64/R" --no-site-file --no-environ --no-save
    --no-restore --quiet CMD INSTALL
    "C:/Users/wlmr/AppData/Local/Temp/RtmpKEF1jE/devtools74c226713ab/r-pkgs-pkgbuild-5ed87aa"
    --library="C:/Program Files/R/R-3.3.3/library" --install-tests

  • installing source package 'pkgbuild' ...
    ** R
    ** tests
    ** preparing package for lazy loading
    ** help
    *** installing help indices
    ** building package indices
    ** testing if installed package can be loaded
    *** arch - i386
    *** arch - x64

  • DONE (pkgbuild)
    "C:/PROGRA1/R/R-331.3/bin/x64/R" --no-site-file --no-environ --no-save
    --no-restore --quiet CMD INSTALL
    "C:/Users/wlmr/AppData/Local/Temp/RtmpKEF1jE/devtools74c3fa0113b/r-pkgs-pkgload-3a96cf2"
    --library="C:/Program Files/R/R-3.3.3/library" --install-tests

  • installing source package 'pkgload' ...
    ** R
    ** tests
    ** preparing package for lazy loading
    ** help
    *** installing help indices
    ** building package indices
    ** testing if installed package can be loaded
    *** arch - i386
    *** arch - x64

  • DONE (pkgload)
    Skipping install of 'callr' from a github remote, the SHA1 (c2fb27d6) has not changed since last install.
    Use force = TRUE to force installation
    "C:/PROGRA1/R/R-331.3/bin/x64/R" --no-site-file --no-environ --no-save
    --no-restore --quiet CMD INSTALL
    "C:/Users/wlmr/AppData/Local/Temp/RtmpKEF1jE/devtools74c29365841/hadley-devtools-d8ab190"
    --library="C:/Program Files/R/R-3.3.3/library" --install-tests

  • installing source package 'devtools' ...
    ** R
    ** inst
    ** tests
    ** preparing package for lazy loading
    ** help
    *** installing help indices
    ** building package indices
    ** installing vignettes
    ** testing if installed package can be loaded
    *** arch - i386
    Error : package 'devtools' is not installed for 'arch = i386'
    Fehler: Laden fehlgeschlagen
    Ausführung angehalten
    *** arch - x64
    ERROR: loading failed for 'i386'

  • removing 'C:/Program Files/R/R-3.3.3/library/devtools'

  • restoring previous 'C:/Program Files/R/R-3.3.3/library/devtools'
    Warnung in file.copy(lp, dirname(pkgdir), recursive = TRUE, copy.date = TRUE)
    Problem C:\Program Files\R\R-3.3.3\library\00LOCK-hadley-devtools-d8ab190\devtools\libs\x64\devtools.dll nach C:\Program Files\R\R-3.3.3\library\devtools\libs\x64\devtools.dll zu kopieren: Permission denied
    Error: Command failed (1)

documenting data

I was looking up how to include data in a package, and I see that it should be documented, but there is no guidance on where to put the documentation.

Obviously the documentation can't go in the .rda file. Can it go anywhere? Is there a best practices place to put it?

loadNamespace vs requireNamespace

You write that loadNamespace is only used internally, and not recommended. However, it seems that it may be useful where you normally recommend requireNamespace. Looking at the source for requireNamespace it is a very thin wrapper to run loadNamespace in a tryCatch.

If the package writer just wants an error if the package user invokes a function with an absent requirement from Suggests, loadNamespace would seem like a reasonable choice.

Show how to link to documentation in other packages

One might write a package "bar" that depends on a previous package ("foo"), and wish to link to vignette "abc" in package "foo" from a vignette in the new package.

Or one might wish to link to a vignette in someone else's package (taking the risk that the link could break).

A cursory Google search didn't seem to turn up any examples of this ... ? In RStudio, the following naïve attempt:


---
title: "A Vignette in Package Bar"
----

Have a look at this [Other Vignette](`r system.file("doc", "abc.html", package="foo")`)

... failed; the URL for the link (as rendered in the Preview Pane) was http://127.0.0.1:28617/Library/Frameworks/R.framework/Versions/3.1/Resources/library/foo/doc/abc.html (which yields a "not found").

Chapter on CRAN policies: trademarks and package names?

It looks like there is a potentially dangerous CRAN-policy mistake that is not mentioned in the book and that new developers are likely to make: when the name of the new package contains trademarks

I may have made that mistake with my mixpanelR and it looks like a similar issue is experienced by @cscheid and github package as described in cscheid/rgithub#29

The aftermath of this mistake can be challenging since it requires renaming the package for CRAN submission.

I wonder if it is something that may be useful in the book when discussing CRAN policies?

Check pre-reqs for RStudio support for devtools::document()

When you say things like

Run devtools::document() (or press Cmd + Shift + D in RStudio) to convert roxygen comments to .Rd files.

taken from here: http://r-pkgs.had.co.nz/man.html#man-workflow … you might want to check this will work on a fresh, default RStudio installation.

FWIW I needed to check "Generate documentation with Roxygen" in Build Tools section of the Project options, then work through the configuration options to get this keyboard shortcut and the Build > Document menu item. But it's possible my situation has to do w/ previous usage or settings?

Makeconf path is incorrect on Windows

In the Makefiles section, it says that the path to Makeconf is file.path(R.home("etc"), "Makeconf"). On Windows, this gives the incorrect path, because it's missing R_ARCH:

> file.path(R.home("etc"), "Makeconf")
[1] "C:/PROGRA~1/R/R-33~1.3/etc/Makeconf"

It should be "C:/PROGRA~1/R/R-33~1.3/etc/x64/Makeconf" (or i386 if running 32-bit R).

This command will give the correct path:

> file.path(R.home("etc"), .Platform$r_arch, "Makeconf")
[1] "C:/PROGRA~1/R/R-33~1.3/etc/x64/Makeconf"

One drawback is that on Unixes, it will result an extra slash. It's only cosmetic, though:

> file.path(R.home("etc"), .Platform$r_arch, "Makeconf")
[1] "/Library/Frameworks/R.framework/Resources/etc//Makeconf"

expand documentation on how to document S3 generics, classes, methods

Being a little dense as I am, it took me a while to understand what I had to do to make sure my own S3 methods MyHappyFunction.array() were documented just like print.array() and friends.

Your S-O post helped me do it: http://stackoverflow.com/questions/7198758/roxygen2-how-to-properly-document-s3-methods

Perhaps other people are also dense, like me.

I'd be happy to add that with a couple of sentences in a PR; just wanted to check back first with you whether you'd be open to that.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.