I am working on an R package and I am using the package Roxygen2 to write the help manuals for my R functions. What I would like to know is if it is possible to use latex for math equations in the manual pages?
For example, if I had a function called add2 that did the following:
add2 = function(x,y){
z = x+y
return(z)
}
And using Roxygen2 documentation I had the following:
##' #include add2.R
{}
##' Compute the sum of x_1 and x_2
##'
##' Computes the sum of x_1 and x_2
##'
##' #param x_1 number of guys
##' #param x_2 number of girls
##' #return The sum of the two values x_1 and x_2
##'
##' #example examples/adding.R
##' #export
##' #author Name
And this works for me, but this displays x1 and x2 as x_1 and x_2 in the help manual whereas I would like for it to look like latex math and actually have the subscripts on x, i.e., $x_1$ and $x_2$ in latex.
Is there any way to do this or does R not accomodate this?
Sort of. Use something like \eqn{x_1} if you want use the (unprocessed) version of the LaTeX markup in plain-text output (alternately you could say something like \eqn{x_1}{x1}). The "sort of" part is that I'm not sure offhand for which particular output formats the LaTeX processing will be done -- for example, I'm guessing that the HTML-formatted version of output you would see in (e.g.) an RStudio documentation pane would not respect this markup. (The LaTeX markup definitely will be used in the PDF versions of the manual, which I almost never look at ...)
I'm going to go ahead and quote from the Mathematics section of Writing R Extensions ...
Mathematical formulae should be set beautifully for printed documentation yet we still want something useful for text and HTML online help. To this end, the two commands \eqn{latex}{ascii} and \deqn{latex}{ascii} are used. Whereas \eqn is used for “inline” formulae (corresponding to TeX’s $…$), \deqn gives “displayed equations” (as in LaTeX’s displaymath environment, or TeX’s $$…$$). Both arguments are treated as ‘verbatim’ text.
Both commands can also be used as \eqn{latexascii} (only one argument) which then is used for both latex and ascii. No whitespace is allowed between command and the first argument, nor between the first and second arguments.
The following example is from Poisson.Rd:
\deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{%
p(x) = \lambda^x exp(-\lambda)/x!}
for \eqn{x = 0, 1, 2, \ldots}.
As of 2020-05-08, the mathjaxr package, by Wolfgang Viechtbauer, is on CRAN. It
Provides 'MathJax' and macros to enable its use within Rd files for rendering equations in the HTML help files.
From the README file:
[After installing the package, editing the package DESCRIPTION file appropriately, and adding \loadmathjax{} to the Rd file ... a]n inline equation can then be added with the \mjeqn{latex}{ascii} macro, with the LaTeX commands for the equation given between the first set of curly brackets (which will be rendered in the HTML and PDF help pages) and the plain-text version of the equation given between the second set of curly brackets (which will be shown in the plain text help). With the \mjdeqn{latex}{ascii} macro, one can add ‘displayed equations’ (as in LaTeX’s displaymath environment).
Quoting O'Reilly's "R Packages" by Hadley Wickham:
You can use standard LaTeX math (with no extensions). Choose between either inline or block display:
\eqn{a + b}: Inline equation
\deqn{a + b}: Display (block) equation
So, using \eqn and \deqn is the recommended and official way.
Related
.Call seems rather poorly documented; ?.Call gives an explanation of the PACKAGE argument:
PACKAGE: if supplied, confine the search for a character string .NAME to the DLL given by this argument (plus the conventional extension, ‘.so’, ‘.dll’, ...).
This argument follows ... and so its name cannot be abbreviated.
This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols, and also speeds up the search (see ‘Note’).
And in the Note:
If one of these functions is to be used frequently, do specify PACKAGE (to confine the search to a single DLL) or pass .NAME as one of the native symbol objects. Searching for symbols can take a long time, especially when many namespaces are loaded.
You may see PACKAGE = "base" for symbols linked into R. Do not use this in your own code: such symbols are not part of the API and may be changed without warning.
PACKAGE = "" used to be accepted (but was undocumented): it is now an error.
But there are no usage examples.
It's unclear how the PACKAGE argument works. For example, in answering this question, I thought the following should have worked, but it doesn't:
.Call(C_BinCount, x, breaks, TRUE, TRUE, PACKAGE = "graphics")
Instead this works:
.Call(graphics:::C_BinCount, x, breaks, TRUE, TRUE)
Is this simply because C_BinCount is unexported? I.e., if the internal code of hist.default had added PACKAGE = "graphics", this would have worked?
This seems simple but is really rare to find usage of this argument; none of the sources I found give more than passing mention (1, 2, 3, 4, 5)... Examples of this actually working would be appreciated (even if it's just citing code found in an existing package)
(for self-containment purposes, if you don't want to copy-paste code from the other question, here are x and breaks):
x = runif(100000000, 2.5, 2.6)
nB <- 99
delt <- 3/nB
fuzz <- 1e-7 * c(-delt, rep.int(delt, nB))
breaks <- seq(0, 3, by = delt) + fuzz
C_BinCount is an object of class "NativeSymbolInfo", rather than a character string naming a C-level function, hence PACKAGE (which "confine(s) the search for a character string .NAME") is not relevant. C_BinCount is made a symbol by its mention in useDynLib() in the graphics package NAMESPACE.
As an R symbol, C_BinCount's resolution is subject to the same rules as other symbols -- it's not exported from the NAMESPACE, so only accessible via graphics:::C_BinCount. And also, for that reason, off-limits for robust code development. Since the C entry point is imported as a symbol, it is not available as a character string, so .Call("C_BinCount", ...) will not work.
Using a NativeSymbolInfo object tells R where the C code is located, so there is no need to do so again via PACKAGE; the choice to use the symbol rather than character string is made by the package developer, and I think would generally be considered good practice. Many packages developed before the invention of NativeSymbolInfo use the PACKAGE argument, if I grep the Bioconductor source tree there are 4379 lines with .Call.*PACKAGE, e.g., here.
Additional information, including examples, is in Writing R Extensions section 1.5.4.
I'm using \deqn{}{} with roxygen2 to document equations for a function in a package. The LaTeX (the 1st argument to deqn) renders fine because white space is ignored in LaTeX equations, but I have a problem with the ASCII (the 2nd argument to deqn) representation.
The problem is that my formatting is destroyed (it appears roxygen puts the entire deqn command on a "single line" and then wraps that line at ~60 columns or so). Is there a way to force roxygen2 to preserve the white space formatting in my roxygen commands/comments in the .R file?
I have the following code in a file, example.R:
#'Example
#'
#'deqn ASCII example
#'
#'\deqn{ \sigma = \sqrt{ \frac{Z}{n} \sum
#' \left[ \textstyle\frac{1}{2}\displaystyle
#' \left( \log \frac{H_i}{L_i} \right)^2 - (2\log 2-1)
#' \left( \log \frac{C_i}{O_i} \right)^2 \right] }
#'}{sqrt(N/n * runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 -
#' (2*log(2)-1) * log(OHLC[,4]/OHLC[,1])^2, n))}
#'
#'#param x An example parameter
#'#return A example result
#'#author Joshua Ulrich
#'#keywords ts
#'#export
"example" <-
function(x) {
}
And I use the following R code to generate the example.Rd file:
library(roxygen2)
setwd("dir/containing/example.R/")
dir.create("man",FALSE)
roclet <- rd_roclet()
roc_proc(roclet, "example.R", ".")
roc_out(roclet, "example.R", ".")
You can generate the text representation of the example.Rd file using this command at the command line:
R CMD Rd2txt dir/containing/example.R/man/example.Rd
The Details section of the output from the above command looks like:
sqrt(N/n *
runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 - (2*log(2)-1) *
log(OHLC[,4]/OHLC[,1])^2, n))
whereas I would like it to look like:
sqrt(N/n * runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 -
(2*log(2)-1) * log(OHLC[,4]/OHLC[,1])^2, n))
According to Hadley Wickham, line wrapping will be removed in future versions of roxygen. So the solution for roxygen2 is to roxygenize the file (or package), then manually update the text equation in the affected .Rd file(s).
This answer doesn't address your ASCII issue, but it currently is my go-to way when rendering latex equations in HTML, so I hope this helps you.
Take a look at the mathjaxr package (CRAN, GitHub). You can install it either with install.packages("mathjaxr") or remotes::install_github("wviechtb/mathjaxr").
It introduces a macro \loadmathjax that loads the necessary JavaScript from MathJax to render latex equations. Then use the macro \mjeqn{latex}{ascii} or \mjdeqn{latex}{ascii} instead of \eqn or \deqn and you're good to go.
In your specific example, we'd have the following:
#' Example
#'
#' Example mathjax function
#'
#' \loadmathjax
#' \mjdeqn{ \sigma = \sqrt{ \frac{Z}{n} \sum
#' \textstyle\frac{1}{2}\displaystyle
#' \left\[ \left( \log \frac{H_i}{L_i} \right)^2 - (2\log 2-1) \left( \log \frac{C_i}{O_i} \right)^2 \right] }
#' }{ASCII representation}
example <- function(a, b, c) {}
(notice the open square bracket is escaped)
If you use RStudio, you may run into some trouble with the \loadmathjax macro. To preview the content quickly, do the following:
Generate documentation (Ctrl + Shift + D or devtools::document(roclets = c('rd', 'collate', 'namespace')))
Call preview_rd("example.Rd") to preview the documentation
When you're done, you can inspect the final result with these steps:
Generate documentation (Ctrl + Shift + D or devtools::document(roclets = c('rd', 'collate', 'namespace'))
Install the package (Ctrl + Shift + L or devtools::install())
Restart the R session with .rs.restartR()
Preview documentation with ?example
Either way should produce the following result:
I'm writing a geocoding function right now that relies on having a Bing Maps Key. Obviously I'd rather not publish mine, and the examples fail without one.
How do I include an example for users to run manually, but not have it executed during R CMD check?
Use \dontrun{}
#'#examples
#'\dontrun{
#'geocode("3817 Spruce St, Philadelphia, PA 19104")
#'geocode("Philadelphia, PA")
#'dat <- data.frame(value=runif(3),address=c("3817 Spruce St, Philadelphia, PA 19104","Philadelphia, PA","Neverneverland"))
#'geocode(dat)
#'}
You can use \donttest{} to your example. The snippet will be provided in your documentation, but won't get tested with the R CMD Check.
For more info --> ?example
#' #example
\donttest{
2^2
}
This 2^2 won't get run when you run devtools::check()
EDIT
Per the latest release notes or NEWS for R 4.0.0, examples within \donttest{} will now be tested by default. This can, however, be overridden by setting environment variable _R_CHECK_DONTTEST_EXAMPLES_ to FALSE.
R CMD check --as-cran now runs \donttest examples (which are run by example()) instead of instructing the tester to do so. This can be temporarily circumvented during development by setting environment variable R_CHECK_DONTTEST_EXAMPLES to a false value.
According to this GitHub issues discussion (credited here), Hadley Wickham noted that
Generally, now if you don't want to run tests on CRAN \dontrun{} is more likely to work, but using \dontrun{} may cause initial submission to fail.
There are other ways as well that will let you continue to use donttest{}, refer the aforementioned discussions for the workarounds.
For those who are using #example path/to/example.R instead of the #examples tag you can use the \dontrun environment directly in the example.R file. For example
# example.R
\dontrun{
# this is a long running example
for(i in seq(1, 1e5)) { lm(mpg ~ wt, data = mtcars) }
}
# some other shorter example
2 + 2
Ari, I also use roxygen2 (version 4.1.0). The following is the end of my roxygen2 mark-up in my function (gctemplate) definition till the beginning of the real part.
#' #examples
#' ## List all G-causalities in a VAR system of 5 variables that will be searched in the pattern of 1
#' ## causer (like-independent) variable and 2 like-dependents conditional on 5-(1+2)=2 of the remaining
#' ## variable(s) in the system. Variables are assigned to numbers 1 to nvars.
#' ## "1 2 5 3 4" in the resulting line of gctemplate is to indicate the
#' ## (conditonal, partial, etc.) G-causality from variable 1 to variables 2 and 5
#' ## conditonal on variables 3 and 4.
#' # gctemplate(5,1,2)
#' ## The number of all G-causalities to be searched in the above pattern.
#' #dim(gctemplate(5,1,2))[[1]]
#' #importFrom combinat combn
#' #export
gctemplate <- function(nvars, ncausers, ndependents){
...
I know GSee's dontrun method.
In my technique, the numerical example and the text explaining the numerical example are both comments. I use indentation to make difference between these two; Notice there are 1 sharp and 2 sharps respectively after "#'". I always use the above "#' ## / #' #" technique in my packages. The user is left to copy-paste operation whenever s/he wanna test the function. This technique is - according to me - more parallel with the classical comment bombardment of the software coding philosophy.
\dontrun{}
Is the correct function. See here:
For the purpose of illustration, it’s often useful to include code that causes an error. \dontrun{} allows you to include code in the example that is not run. (You used to be able to use \donttest{} for a similar purpose, but it’s no longer recommended because it actually is tested.)
Source: https://r-pkgs.org/man.html?q=donttest#man-functions
I would like to be able to edit the Fortran code that is referred to in the fGarch package.
More specifically I would like to edit the available conditional distributions that can be used by fGarch::garchFit, i.e. including the stable distribution and the generalised hyperbolic distribution.
So having looked into the garchFit() function, I have delved (deepish) into the code, and .aparchLLH.internal() is referred to from the garchFit() function and there is a line in there that refers to Fortran written code.
The specific line that I am referring to is the following bit of code:
fit <- .Fortran("garchllh", N = as.integer(N), Y = as.double(.series$x),
Z = as.double(.series$z), H = as.double(.series$h),
NF = as.integer(NF), X = as.double(params), DPARM = as.double(DPARM),
MDIST = as.integer(MDIST), MYPAR = as.integer(MYPAR),
F = as.double(0), PACKAGE = "fGarch")
I believe that the Fortran function garchllh is what I would like to edit, but do not know how to go about editing it so that I can introduce new distributions into the garchFit() function.
N.B. Just as a note, I do not have much experience in Fortran code, but would like to have a look at it to see if it can be edited and altered to fit for my purpose, so any help on the Fortran editing of code section would be much appreciated...
As mentioned in comments, you need to download the source -- a good place would be to start with install.packages("fGarch",type="source") and see that everything compiles properly. Then, look at the package source -- seems like you would need to do a pretty straightforward adjustment to dist.f, and probably add more changes to various places where MDIST is set -- start with grep MDIST *.R in the R directory of the extracted source. After you're done and tested, you could also talk to the package maintainers -- perhaps they would include your additions in the next version :)
This is not just a coding style question. If you know python (and I think also Ruby has something like this), you can have a docstring in a function, such that you can readily get that string by issuing a "help" command. e.g.:
def something(t=None):
'''Do something, perhaps to t
t : a thing
You may not want to do this
'''
if t is not None:
return t ** 2
else:
return 'Or maybe not'
Then help(something) returns the following:
Help on function something in module __main__:
something(t=None)
Do something, perhaps to t
t : a thing
You may not want to do this
The way things work in R, you can get the full text of the defined code snippet, so you could see comments (including those at the beginning of the function), but that can be a lot of scrolling and visual filtering. Is there any better way?
I recently wrote a package to do just this task. The docstring package allows one to write their documentation as roxygen style comments within the function they are documenting. For example one could do
square <- function(x){
#' Square a number
return(x^2)
}
and then to view the documentation either call the docstring function
docstring(square)
or use the built in ? support and do
?square
The comments can either be a single chunk like shown above or fully roxygen style to take advantage of some of the keywords provided
square <- function(x){
#' Square a number
#'
#' Calculates the square of the input
#'
#' #param x the input to be squared
return(x^2)
}
This is on CRAN now: https://cran.r-project.org/package=docstring so you can just install using
install.packages("docstring")
or if you want the latest development version you can install from github:
library(devtools)
install_github("dasonk/docstring")
You can add any attributes you like to R objects, including function. So something like
describe <- function(obj) attr(obj, "help")
foo <- function(t=NULL) ifelse(!is.null(t), t^2, "Or maybe not")
attr(foo, "help") <- "Here is the help message"
produces more or less the desired output
> foo(2)
[1] 4
> foo()
[1] "Or maybe not"
> describe(foo)
[1] "Here is the help message"
Sort-of -- look at the roxygen2 package on CRAN (vignette here). You write a declarative header, and among other things a help page is created for you when you 'roxygen-ize' your sources.
It may not be the easiest package to use, see here on SO for questions pertaining to it as well as its mailing list. But it probably is the closest match.
RStudio helps you to create documentation quite easily.
See their documentation for more information.
The new reference class system has something very similar to docstrings for documenting methods of a class. Here is an example:
Something <- setRefClass("Something",
methods=list(
something=function(t=NULL) {
"Do something, perhaps to t
t : a thing
You may not want to do this
"
if(!is.null(t))
t^2
else
"Or maybe not"
}
))
a <- Something$new()
a$something(2)
a$something()
Something$help("something") ## to see help page
I had another idea as I'm finally wrapping my head around the fact that "R is a (very poor) LISP". Specifically, you can get access to the source code (usually) using the deparse command. So, this function would be a start towards defining your own custom source-code parsing help function:
docstr <- function(my.fun) {
# Comments are not retained
# So, we can put extra stuff here we don't want
# our docstr users to see
'This is a docstring that will be printed with extra whitespace and quotes'
orig.code.ish <- deparse(my.fun)
print(orig.code.ish[3])
}
docstr(docstr)
The above illustrates that deparse really does deparse, and is different from what you'd print at the REPL prompt if you typed docstr: quotes are changed to (default) double-quotes, opening curly brace gets moved to the second line, and blank lines (including comments) are removed. This actually helps a lot if you want to design a robust function. Would be trivial to look for e.g., opening and closing quotes down through the first line that doesn't start with a quote.
Another way to do it would be to get the list of call objects that make up the body list with body(docstr). The string would be in body(docstr)[[2]]. I have to admit that I'm a bit out of my depth here, as I don't fully understand the return value of body, and don't know where to find documentation! In particular, note that body(docstr)[2] returns an object of type and mode 'call'.
This latter approach seems much more LISPy. I'd love to hear other's thoughts on the general idea, or have pointers to actual language reference materials for this!