In hyginn/rptPlus: R Package Template - Enhanced

nocite: @pmid24204232, @Borges1977

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

# knitr knits in a new session with an empty global workspace after setting its
# working directory to ./vignettes. To make your package functions available in
# the vignette, you have to load the library. The following two lines should
# accomplish this without manual intervention:
pkgName <- trimws(gsub("^Package:", "", readLines("../DESCRIPTION")[1]))
library(pkgName, character.only = TRUE)

 

There are many links and references in this document. If you find anything here ambiguous, inaccurate, outdated, incomplete, or broken, please [file an issue](https://github.com/hyginn/rpt/issues)!

 

About this Vignette

This sample Vignette explains how to customize this template for your own R package, and it contains hints on how to create meaningful contents. Thus the Vignette is a template for your own development - both in how it integrates with the rest of the package framework, and what you can do with it. Edit it to your needs. But do make sure your package has a Vignette! Obviously, the code and data assets contain comment headers throughout, and these are used by roxygen2 to compile package documentation and man pages. However, documenting what the functions do does not necessarily explain how to use a package.

The .Rmd format in which this Vignette is written is a very clever way to enable "literate programming": the source combines markdown formatted text with executable R code, and the results of the code are integrated into the resulting document. This magic is made possible by the fabulous knitr package, originally written by Yihui Xie and integrated into the RStudio IDE.

knitr can render the Rmarkdown contents of this Vignette to a variety of different formats, including html and pdf. Which format is targeted is defined in the metadata block at the top of the Vignette. Specifically, the format used here is "BiocStyle::html_document", which is a requirement for Bioconductor packages. An alternative format that is often used in CRAN and other packages is "html_vignette"; this format aims to produce a vignette that is as small as possible.

 

Develop your Vignette

In RStudio, open the ./vignettes folder and rename rptPlus.Rmd to `<your-package-name>.Rmd. Then open the file to edit it. Whenever you make changes, click on the Knit icon at the top of the editing pane, this will save the file, "knit" the output to an html file, and open the file in the viewer. You can also copy the path of the resulting file from the R Markdown tab in the console pane and open it in your normal browser.

Customize the metadata

Edit the following information in the metadata block:

Your Vignette Title

In the header block, change your Vignette title and the Vignette index entry:

-   title: "The rptPlus Sample Vignette"
+   title: "<your-Vignette-title>"

vignette: >
  %\VignetteIndexEntry{The rptPlus Sample Vignette}
  %\VignetteIndexEntry{<your-Vignette-title>}
[...]

Author and Affiliation

The author name and affiliation in the document header are also generated from metadata. You can list several authors with their shared and unique affiliations and provide a linked email address to the corresponding author. For details, see here.

author:
-   - name: Boris Steipe
+   - name: <your-name>
     affiliation: 
-     - http://orcid.org/0000-0002-1134-6758
+     - http://orcid.org/<your-ORCID-ID>
-     - name: University of Toronto
+     - name: <your-affiliation>
-     email: [e-mail]
+     email: <corresponding-author's-email>

Abstract and Running Headers

An abstract will be processed from the metadata block.

abstract: >
-    The rptPlus Sample Vignette demonstrates[...]
+    <your-Vignette-summary>

Contents

Text

Text in this Vignette is written in R Markdown format. This is reasonably lightweight and intuitive, for details refer to the many documents linked in Section \@ref(further-reading) (Further reading) and study the examples in this document.

A good Vignette is all about workflow. It addresses the divine and elusive why of documentation. To paraphrase Henri Poincaré: a useful package is made from functions as a house is with stones. But a collection of functions is no more useful in itself than a heap of stones makes a house.[^1] Connecting workflow upstream and downstream is the essence of good software, it is the task of the Vignette to make your implicit ideas explicit.

[^1]: "Science is built up with facts, as a house is with stones. But a collection of facts is no more a science than a heap of stones is a house." Henri Poincaré.

Links

Easily accessible cross-references are the lifeblood of academic publishing. Use references liberally to make access to material for in-depth exploration easy.

• cross references within the document can be made to figures, tables, equations and section headers (see here). But since a markdown document is also an HTML document, you can flexibly create "anchors" anywhere in the document with <a name="<some-id>"><some-text></a> and link to them either with markdown syntax: [<linked-text>](#<some-id>) or with HTML syntax: <a href="#<some-id>"><linked-text></a>. For example this link as well as this link both lead to an anchor at the top of the "Further reading" section (however with differing behaviour regarding where the top of the browser window is positioned).

• external links can also be made in markdown and HTML, the markdown syntax is [<linked-text>](<URL>). For example this link leads to my "Gist" for link-checking code in R.

• BiocStyle provides macros for linking to other R packages in BioConductor, CRAN, on GitHub and elsewhere:

Table: (#tab:tMacros) BiocStyle link macros

For ... | type ... | to get: ------------ | ----------------------------------------- | ------------------------------ Bioconductor:|r "r "Biocpkg("BiocStyle") | `r Biocpkg("BiocStyle")` CRAN: | r "r "`CRANpkg("knitr")` |r CRANpkg("knitr") GitHub: |r "r "Githubpkg("hyginn/rptPlus") `|r Githubpkg("hyginn/rptPlus")`

The above example also shows how to caption a table and place an anchor for a link (for the link itself, see below).

Math

R markdown supports the rendering of equations with LaTeX markup. Here is an example:

The golden ratio $\phi$ is

$$ \frac{\left(1 + \sqrt{5}\right)}{2} $$

A "golden spiral" [^2] is a logarithmic spiral whose radius diminishes by $\frac{1}{\phi}$ every quarter turn. It is thus inscribed into a "golden rectangle". The golden spiral with initial radius 1 is defined by the polar equation

\begin{equation} r = \phi^{-\theta\frac{2}{\pi}} (#eq:phiPolar) \end{equation}

[^2]: cf. "Golden spiral" on Wikipedia.

Figures

The block of R code below is executed when the document is knit, and the resulting plot is shown. The code first sets up N angles theta and then computes the radius according to \@ref(eq:phiPolar) . Polar coordinates are then converted to cartesian coordinates and scaled to the canonical golden rectangle. We plot an empty frame, draw the rectangle, draw segments for the enclosed golden sections, and finally draw the line of the spiral.

phi <- ((1 + sqrt(5)) / 2)^(1:-8)           # ten decreasing powers of phi
tStart <- -0.233
tEnd <- 8 * pi
N <- 800
theta <- seq(tStart, tEnd, length.out = N)
r = phi[1]^-(theta * (2  / pi))
x <- r * cos(theta)
y <- r * sin(theta)

x <- ((x + abs(min(x))) * phi[1]) / (max(x) - min(x))  # scale to [0, phi]
y <-  (y + abs(min(y)))           / (max(y) - min(y))  # scale to [0, 1]

oPar <- par(mar = rep(0.25, 4))             # set thin margins
plot(x, y,                                  # plot empty frame ...
     type = "n",
     xlim = c(0, phi[1]),
     ylim = c(0, 1),
     xlab = "", ylab = "", 
     axes = FALSE,
     asp = 1)                               # with fixed aspect ratio

rect(0, 0, phi[1], 1, border = "#CCCCCC")   # draw enclosing rectangle


C <- "#C9C9EE"                              # draw enclosed golden sections
segments(phi[1]-phi[2],            0,phi[1]-phi[2],       phi[2],col=C,lwd=0.4)
segments(            0,phi[2]-phi[3],phi[1]-phi[2],phi[2]-phi[3],col=C,lwd=0.4)
segments(phi[2]-phi[3],            0,phi[2]-phi[3],phi[2]-phi[3],col=C,lwd=0.4)
segments(phi[2]-phi[3],phi[3]-phi[4],phi[1]-phi[2],phi[3]-phi[4],col=C,lwd=0.4)
segments(phi[4]+phi[7],phi[3]-phi[4],phi[4]+phi[7],phi[2]-phi[3],col=C,lwd=0.4)
segments(phi[2]-phi[3],phi[5]+phi[8],phi[4]+phi[7],phi[5]+phi[8],col=C,lwd=0.4)
segments(phi[4]+phi[8],phi[3]-phi[4],phi[4]+phi[8],phi[5]+phi[8],col=C,lwd=0.4)
segments(phi[4]+phi[8],phi[5]+phi[9],phi[4]+phi[7],phi[5]+phi[9],col=C,lwd=0.4)

lines(x, y, col = "#CC0000")               # draw spiral

par <- oPar                                # reset graphics state

Tables

Printing tables is straightforward using the defaults in knitr::kable(). But getting the data from your package can be tricky: the package needs to be built and installed first and loaded in the setup chunk of the Vignette. Then you can simply refer to exported data in the package namespace. However the usual system.file() will still fail. Not to worry: the correct path is simply ../inst/extdata/<fileName> since knitr knits in ./vignettes as its working directory. However, this code is specific to the vignette, not something you can tell your users to do.

Example 1. The standard genetic code is provided as sample data with rptPlus:

x <- matrix(paste0(names(rptGC), ": ", rptGC), ncol=4)
nuc <- c("A", "G", "C", "T")
colnames(x) <- paste0(nuc, "..", sep ="")
rownames(x) <- paste0(".", rep(nuc, each = 4), nuc, sep ="")

knitr::kable(x,
             caption = "The standard genetic code.",
             align = "c")

Example 2. Printing the values in ./inst/extdata/test_lseq.dat

x <- readLines("../inst/extdata/test_lseq.dat")
knitr::kable(x, caption = "Five log-spaced numbers in [1, 10]")

Tables automatically receive anchors that you can link to, for example the link to Table 1 is link\@ref(tab:tMacros) and it appears thus: Table \@ref(tab:tMacros).

Bibliographies and Citations

There are two ways to manage bibliographies: the common way is to supply an external bibliography file in the ./vignettes folder, but one can also keep short bibliographies inline, in the YAML formatted metadata block (cf. here). I recommend the external bibliography, it is more explicit and if your package contains more than one vignette it guarantees that the references are consistent. The bibliography.bib file included here contains three different "entry types" so you have templates to work with. Valid BibTeX entry types and their required and optional fields are listed here. Automatically converting pubmed IDs to BibTeX formatted references can be done with TeXMed.

To cite a work in your text, type [@<reference-id-in-bibFile>]. For example [@steipe-rptPlus] will render as [@steipe-rptPlus]. References will be compiled after the # References section of your document.

More details on formatting citations are posted at RStudio.

Further reading

• Get started with Rstudio Markdown
• A collection of Rmarkdown Articles
• The RStudio R markdown cheat sheet
• The RStudio R markdown reference guide
• Detailed "chunk" options
• The Bioconductor LaTEX style reference

Session Info

This release of the rptPlus package was produced in the following context of supporting packages:

sessionInfo()

References

hyginn/rptPlus documentation built on May 30, 2019, 2:11 p.m.