- 6.1 Resources -
- 6.2 Project exercise +
- 6.2 Package exercise
- 6.3 Quick start
- 6.4 Basic stuff
-
diff --git a/docs/packages.html b/docs/packages.html
index 92e7bac..133cb72 100644
--- a/docs/packages.html
+++ b/docs/packages.html
@@ -249,7 +249,7 @@
- 6 Packages
- 6.1 Resources -
- 6.2 Project exercise +
- 6.2 Package exercise
- 6.3 Quick start
- 6.4 Basic stuff
-
@@ -324,16 +324,16 @@
6.1 ResourcesHow to decide when to trust an R package?
-6.2 Project exercise
+++6.2 Package exercise
Just to experiment with making an R package, we’ll try to make a small package that implements some of the features of package {dplyr} that we learned in chapter 4. We can call this package {minidplyr}.
-
-
After having read the following two sections (6.3 and 6.4), create a first function that helps you
selectvariables of a data frame by using a character vector of variable names or an integer vector of variable positions. Which accessor could you use? Document this function and use it. Bonus (for later): can you use base R functionsubsetto use variables names without quoting them?
-Check your package with
Ctrl/Cmd + Shift + Eand fix all problems. At this point, there should be no ERROR or WARNING, unless you did not document the previous function properly. However, you should still update the DESCRIPTION file with proper information. Do it, fix any problem, and run checks again. You could submit this package to CRAN in its present form; congratulations on your new R package!
+After having read the following two sections (6.3 and 6.4), create a first function that helps you
selectvariables of a data frame by using a character vector of variable names or an integer vector of variable positions. Which accessor could you use? Document this function and use it.
+Check your package with
Ctrl/Cmd + Shift + Eand fix all problems. At this point, there should be no ERROR or WARNING, unless you did not document the previous function properly. However, you should still update the DESCRIPTION file with proper information. Do it, fix any problem, and run checks again. You could almost submit this package to CRAN in its current form; congratulations on your new R package!Commit everything and push to GitHub. Try to install the package from someone else using
remotes::install_github("<github-username>/minidplyr").Learn how to make unit tests in section 6.5.1 and do that for your new function
select2. Which silly cases you should test? Here, you can useusethis::use_package("dplyr", type = "Suggests")to add package {dplyr} to the suggested packages (because you will use this package in tests only). You can see the unit tests I came up with for this function.Make a function
filter2that enables to filter rows of a data frame. Add some documentation and tests for this function as well.
-Learn about continuous checking of your package in section 6.5.2. Follow the instructions, commit and push your changes. Go check your new badges on GitHub!
+Learn about continuous checking of your package in section 6.5.2. Follow the instructions to set it up. Check your package locally, then commit and push your changes. Go check your new badges on GitHub!
Learn how to make a website out of your package in section 6.5.3 and build one for this package (or another of your packages).
Implement more functions if you find this project interesting. For example, make a function
mutate2with the help of base R functiontransform(orwithin). Try to make the previous functions more general by taking many arguments at once (in...). Make sure to keep your existing code as internal functions in order to break your code in manageable parts.
6.3 Quick start
Create a new RStudio project (not a package). Here, I advise you to create a new project on GitHub (with a README) and then clone it as an RStudio project. It is a good practice to put all your (public) stuff on GitHub (as we learned in section 2.3).
Run the following lines of R code.
-usethis::use_description(list(License = "GPL-3")) +usethis::use_namespace() +dir.create("R") +usethis::use_package_doc() +usethis::use_roxygen_md()Restart RStudio and change the following options. You should see a new “Build” panel next to the “Git” panel.
Then use
Ctrl/Cmd + Shift + Bto build and reload your package.6.4.2 R code
old <- options(stringsAsFactors = FALSE) -on.exit(options(old), add = TRUE)@@ -379,9 +379,9 @@6.4.3 Documentationthis chapter. Note that you can now use the Markdown syntax in the documentation. For example, instead of having to use
\code{foo}, you can directly use`foo`in the roxygen comments.To use (and export) functions already implemented in other packages, for example the pipe from package {magrittr}, you can use
- +usethis::use_package("magrittr")and put the following code somewhere in an R file of your package.Fun: [How to] Include a dancing banana in your R package documentation.
@@ -402,9 +402,9 @@6.5.1 Testing6.5.2 Continuous checking
I would rarely trust a package that doesn’t use these continuous integration services. It’s good practice to check your package regularly and on different Operating Systems (OS). Learn more about the different checks there.
-An easy way to regularly check your package on GitHub is to use GitHub Actions. Indeed, each time you push to your GitHub repository, checks are run on different OS. To use this service, you can run
+usethis::use_github_action_check_standard().An easy way to regularly check your package on GitHub is to use GitHub Actions. Indeed, each time you push to your GitHub repository, checks are run on different OS. To use this service, you can run
usethis::use_github_action("check-standard").To get the coverage of your tests, use Codecov by running
-usethis::use_coverage()andusethis::use_github_action("test-coverage").Finally, to prevent typos in your package and especially for non-native English speakers, it can be useful to check the spelling in your package. If you think that the word “programmation” exists and that “prefered” has only one ‘r’ at the end (I did!), you should definitely use package {spelling}. Just run
+spelling::spell_check_setup(); this will check spelling in your package at the end of checks. If it reports words you want to ignore, just put these words in a text fileinst/WORDLIST(with one word by line).Finally, to prevent typos in your package and especially for non-native English speakers, it can be useful to check the spelling in your package. If you think that the word “programmation” exists and that “prefered” has only one ‘r’ at the end (I did!), you should definitely use package {spelling}. Just run
spelling::spell_check_setup(); this will check spelling in your package at the end of checks. If it reports words you want to ignore, just put these words in a text fileinst/WORDLIST(with one word per line).6.5.3 Pkgdown
@@ -413,7 +413,7 @@6.5.3 Pkgdown -
Push the new files. This will render everything that you have in this folder as a website (after 0-2 minutes).
Push the new files. This will render everything that you have in this folder as a website (after 0-2 minutes). You will find your package’s website at
https://<github-username>.github.io/minidplyr/.To get more information and especially to configure the website, see the documentation, as a {pkgdown} website, of course. For an example, see the website of my package {bigstatsr} and the corresponding YAML file.
@@ -424,19 +424,19 @@6.5.3 Pkgdown6.6 More
6.6.1 Rcpp
-We learned about Rcpp in section 5.4. To use Rcpp code in your package, just use
+usethis::use_rcpp()and put the 2 roxygen tags e.g. in the fileR/<package>-package.R. Then, create .cpp files with RStudio and save them thesrc/directory.We learned about Rcpp in section 5.4. To use Rcpp code in your package, just run
usethis::use_rcpp(). Then, create .cpp files with RStudio and save them thesrc/directory.Note that the
// [[Rcpp::export]]makes the C++ function available to R, it doesn’t export the function as part of your package (though you could access it with<package>:::<rcpp-fun>()). If you want your package to explicitly provides an Rcpp function (as an R function), you also need roxygen comments (beginning with//'instead of#', including//' @export) on top of your Rcpp function.If you need some C++ code from another package (e.g. from package {RcppArmadillo}), normally you would use
- -In an R package, you don’t need the first line but instead you need to add the package to the
+ +LinkingTofield of the DESCRIPTION file (e.g. withusethis::use_package("RcppArmadillo", "LinkingTo")).In an R package, you don’t need the first line
// [[Rcpp::depends(RcppArmadillo)]], but instead you need to add the package to theLinkingTofield of the DESCRIPTION file (e.g. withusethis::use_package("RcppArmadillo", "LinkingTo")).@@ -521,20 +521,6 @@6.6.2 Ignore files
There are two types of ignore:
Files ignored by Git, specified in the .gitignore file. For example, you don’t want to track changes for some large data files or some binaries often changing. You can ignore files by using
usethis::use_git_ignore().
-Files ignored during the build of your package, specified in the .Rbuildignore file. For example, in my packages, I generally have two directories called
tmp-testsandtmp-savewhere I just put some random code that I used once during development. Checks will tell you if your package contains non-standard files or directories. Moreover, I generally ignore vignettes; they are still built as part of the {pkgdown} website. +Files ignored during the build of your package, specified in the .Rbuildignore file. For example, in my packages, I generally have directories called
tmp-testsandtmp-datawhere I put code and data that I used during development, but that should not be part of the final package. Checks will tell you if your package contains non-standard files or directories. Moreover, I generally ignore vignettes; they are still built as part of the {pkgdown} website. There is also a {usethis} function for this:usethis::use_build_ignore().
6.7 Release on CRAN
- 6 Packages