Lecturer: Michael Lydeamore
Department of Econometrics and Business Statistics
Aim
Why
Documentation is vital
random_number()
functiondata-raw/smartmeter.R
:
People have become very used to the pipe syntax, and so actually the above function is better written as:
#' @examples
#'
#' smartmeter |> last_n_days(n = 7)
last_n_days <- function(.data, n) {
smartmeter |>
dplyr::filter(date >= (max(date) - n))
}
Tip
Your case may not be as straightforward as this: do not feel like you can never include a data object inside a function. It is still useful!
The base pipe (|>
) is fine for 99% of cases - I recommend just using that.
If you need the magrittr
pipe (%>%
) then you can use
The process to include a Shiny app is a bit more complicated than data or a function.
Put your app code in inst/[appname]/app.R
In your function to launch your app:
Files in inst/
are installed with your package but are considered “internal”.
The system.file
tells R where to look for your shiny app code.
Warning
Don’t include an example for running a shiny app! It will cause R to hang.
Instead, include your example inside an if
statement:
roxygen2
#'
above a function to write documentation for that functionroxygen2
uses @
tags to structure documentation, e.g.
@description
is the description@param
describes the arguments of the function@export
signals that it is an exported function@return
describes the return objectdevtools::document()
converts the Rd tags to appropriate sections of .Rd
files written in the man/
foldersolarash
packageR/cleaning.R
#' Cleans Solar Data from the Jemema Electricity Portal
#'
#' @param .data A data frame containing raw solar data extracted from the Jemema Electricity Portal.
#' @return A cleaned data frame with columns: date, datetime, energy_kwh, and other relevant columns.
#'
#' @importFrom tidyr pivot_longer
#' @importFrom dplyr mutate
clean_solar_data <- function(.data) {
...
}
usethis::use_data_raw()
to store R code to process raw data,usethis::use_data()
to save a binary file in data/
directory,praises
.data.R
or name-of-data.R
R/data.R
#' Example Smart Meter Data from the Jemena Electricity Portal
#'
#' A dataset containing example smart meter data extracted from the Jemena Electricity Portal.
#' @format A data frame with 17520 rows and 4 variables:
#' \describe{
#' \item{date}{Date of the reading (YYYY-MM-DD)}
#' \item{datetime}{Date and time of the reading (POSIXct)}
#' \item{energy_kwh}{Energy consumption in kilowatt-hours (kWh)}
#' \item{con_gen}{Whether the reading is consumption or generation}
#' \item{estimated}{Whether the reading is estimated or actual. In this dataset, all readings are actual.}
#' }
#'
#' @source \url{https://jemena.com.au/}
"smartmeter"
R/solardash-package.R
It is possible!
Add to your DESCRIPTION file:
VignetteBuilder:
quarto
and change your YAML header to:
vignette: >
%\VignetteIndexEntry{Vignette's Title}
%\VignetteEngine{quarto::html}
%\VignetteEncoding{UTF-8}
Warning
This is still new and there may be some issues with some package checkers. Our experience is that CRAN has accepted packages even when they’ve failed tests because of the Quarto engine
I believe it is where things are heading, so it is worth trying out, even if it costs you some pain now.
Depends
: Specify the version of R that the package will work with or package that it is dependent on (e.g. for ggplot2 extension packages, it depends on ggplot2).Imports
: External packages that are imported to use in your package. Most external packages are in this category.Suggests
: Packages that are not strictly needed but are nice to have, i.e. you use them in examples or vignettes.usethis::use_package()
or for existing repo, run from the terminal:
solardash
packagehttps://github.com/MikeLydeamore/solardash
.README
file with installation instructions – this is displayed in the GitHub repo.README.Rmd
file withpkgdown
pkgdown
pkgdown::build_site()
_pkgdown.yml
file
pkgdown
siteFirst, modify _pkgdown.yml
file
And then the world is your customising oyster:
Choose from bootswatch themes. Strangely theme
here means syntax highlighting theme, not theme theme. Computer scientists.
By default maths is rendered with mathml
which is pretty good but not perfect. You can switch with
available::available("pkgname") # check if package name is available (if planning to publish publicly)
usethis::create_package("pkgname")
usethis::use_git() # set up version control
usethis::use_github() # optional
usethis::use_r("myfile")
# write some functions in a script
usethis::use_data_raw() # if adding data
devtools::load_all() # try it out in the console
usethis::use_package("import-pkgname") # add package to import (or depends or suggests)
usethis::use_package_doc() # add package documentation
usethis::use_pipe() # if you want to add %>% from `magrittr`
usethis::use_vignette("vignette-name") # add vignette
devtools::build() # build vignettes
devtools::install() # to install package
devtools::check() # to build and check a package
usethis::use_readme_rmd() # to add a README Rmd file
styler::style_pkg() # optional (commit first, then review changes carefully)
usethis::use_pkgdown_github_pages() # for setting up pkgdown website on github
# `usethis::use_pkgdown()` if not using github pages
CRAN has quite the set of policies to follow. Some are “optional” but most are mandatory.
This will create a GitHub issue with a checklist of things to do before submitting to CRAN.
Some key points:
devtools::check()
must give 0 0 0
. Realistically it will give one note (new submission), but try to avoid all others.devtools::run_examples()
must run without errorcheckhelper::find_missing_tags()
: All functions must have @noRd
or @export
tagurlchecker::url_check()
rhub::rhub_check()
usethis::use_cran_comments()
: Add a cran-comments.md
file with responses to common questionsOne of the most common warnings is
no visible binding for global variable
This is a result of using the non-standard evaluation in dplyr
and ggplot2
(and other places). Unfortunately the fix is very unsatisfying.
All declared Imports should be used
We have packages that are only used in our shiny app but nowhere else.
We handle these like we would examples or tests: Suggests
.
But, what would happen now if we tried to launch the shiny app without these suggested packages installed?
The cli
package is a modern way to handle messages, warnings, and errors.
Documentation: https://cli.r-lib.org/
The cli
package is a modern way to handle messages, warnings, and errors.
Documentation: https://cli.r-lib.org/
run_solar_dashboard <- function() {
required_packages <- c("DT", "ggplot2", "readr")
for (pkg in required_packages) {
if (!requireNamespace(pkg, quietly = TRUE)) {
cli::cli_abort(c(
"Package {.pkg {pkg}} must be installed to run the dashboard.",
"i" = "You can install it with {.code install.packages('{pkg}')}"
))
}
}
...
}
usethis::use_mit_license("Your Name")
LICENSE
and DESCRIPTION
should matchBugReports
and URL
with devtools::use_github_links()
Don’t be afraid to submit your package to CRAN!
They are helpful and although they may reject your package, they will give you feedback on what to fix.
Summary
usethis
, devtools
, roxygen2
, and pkgdown
.ETC5523 Week 10