I’m using knitr::rmarkdown (but knitr::knitr does the same) as my VignetteEngine. I then build my package vignette using devtools::build_vignettes().
This works, but only creates HTML and R output files in inst/doc. What I want is a Markdown output file, since only that can be displayed directly within the Github project pages (for HTML files, Github shows the source and for Rmd files it shows a rendered output but — obviously — without executing the R blocks).
I’ve tried finding out how to specify the output for custom VignetteEngines and I think that it should be possible (after all, other packages use this to build PDF vignettes, at a minimum) but I cannot find a way of doing this via devtools::build_vignettes. Is there no way around building the vignette manually (i.e. via knitr::knit or similar mechanisms that ignore the VignetteBuilder directives)?
I can’t find relevant information in the documentation/source either.
The only output formats for vignettes are HTML and PDF (and LaTeX, but it is converted to PDF, not displayed). Markdown isn't supported.
You can have arbitrary documentation files in your package (by convention you put them in inst/doc), but they aren't considered to be vignettes, so they won't be automatically built, functions like browseVignettes() will ignore them, etc.
To convert an Rmd file to md, just run knitr::knit on it.
Related
I wish to use libraries across multiple .Rmd files in an r notebook without having to reload the library each time.
An example: I have loaded the library kableExtra in the index.Rmd file but when I call it in another .Rmd file such as ExSum.Rmd I would get this error:
Error in Kable....: could not find funciton "kable" Calls:...
If I load the kableExtra library again this problem goes away. Is there a workaround?
R Markdown files are intended to be standalone, so you shouldn't do this. There are two workarounds that come close:
If you process your .Rmd files within the R console by running code like rmarkdown::render("file.Rmd") then any packages attached in the session will be available to the code in the .Rmd file.
You can put all the setup code (e.g. library(kableExtra)) into a file (called setup.R, for example), and source it into each document in the first code chunk using source('setup.R'). Every file will run the same setup, but you only need to type it once.
The second is the better approach.
I'm using Rmarkdown/Bookdown to write a paper/PDF document, which is an amazing tool #Yihui, thanks! Now I'm trying to include a table I have already put in LaTeX into the document by reading in this external .tex file. However, when knitting in RStudio with a \include{some-file.tex} or input{some-file.tex} in the body of the .Rmd outside of a chunk a LaTeX Error: Can be used only in preamble. is produced and the process stopped. I haven't found a way how to directly input through knit or otherwise into a chunk as well.
I found this question here: Rmarkdown v2, embed Latex document, although while the question is similar, there is no answer which would reflect how to input/include .tex-files into an .Rmd.
Why would I want this? Sometimes LaTeX tables offer more layout options than building directly in R, like for tables only with text rather than R-computed numbers. Also, when running models on a cluster, exporting results directly into .tex ready for compilation saves a lot of computation compared to have to open all these heavy .RData files just for getting the results into a PDF. Similarly, having sometimes multiple types of reports with different audiences, having the full R code in one main .Rmd file and integrating only the necessary results in other files reduces complexity by not having to redo all steps in each file newly. This way, I can keep one report with the full picture and do not have to check if I included every little change in various documents simultaneously.
So finally the question is how to get prepared .tex-Files into a .Rmd-document?
Thanks for your answers!
I have a .Rnw document in which I include childs. The childs produce tables via the 'latex' command of the Hmisc library in R.
When I make changes in the child documents, these changes do not anymore change the pdf document. My first guess was to use the chunk option 'eval=TRUE', but this does not change anything. Then, I saw, that the tables are actually saved to a .tex file with same name as the .Rnw document. I deleted this file and after compilation with knitr I got an error:
Error: Latexmk: Could not find file documentname.tex.
I assume, this is not the way to do it. Now I am out of ideas what to do. I appreciate some help on my problem.
Best
Simon
Allright, when trying to construct a simple example, I actually found out, that neither the packages I included nor the nesting of child documents interfere with the compilation via knitr. The reason was a simple error in the low-level .Rnw document, where a Hmisc latex table had a label, that missed a closing speech mark.
This causes then the output pdf not to change - I assume, that in this case the already constructed .tex file is included instead of letting knitr recompile the .Rnw documents and this hasn't changed since the last compilation?
What I wonder about is the different format of the landscape ctable in the document. Using a simple knitr document just with \documentclass{article} produces well placed tables. In my document using a template for the JFE, I get a table that extends over the whole page and even in footnotesize it is far away from the great appearance in the simple document. There is only a margin of less than half a cm on the right and the left. Page size is the same: both US letter... Can I probably control that via knitr or only via resizebox?
I wonder whether I can use knitr markdown to just create a report on the fly with objects stemming from my current workspace. Reproducibility is not the issue here. I also read this very fine thread here.
But still I get an error message complaining that the particular object could not be found.
1) Suppose I open a fresh markdown document and save it.
2) write a chunk that refers to some lm object in my workspace. call summary(mylmobject)
3) knitr it.
Unfortunately the report is generated but the regression output cannot be shown because the object could not be found. Note, it works in general if i just save the object to .Rdata and then load it directly from the markdown file.
Is there a way to use objects in R markdown that are in the current workspace?
This would be really nice to show non R people some output while still working.
RStudio opens a new R session to knit() your R Markdown file, so the objects in your current working space will not be available to that session (they are two separate sessions). Two solutions:
file a feature request to RStudio, asking them to support knitting in the current R session instead of forcibly starting a new session;
knit manually by yourself: library(knitr); knit('your_file.Rmd') (or knit2html() if you want HTML output in one step, or rmarkdown::render() if you are using R Markdown v2)
Might be easier to save you data from your other session using:
save.image("C:/Users/Desktop/example_candelete.RData")
and then load it into your MD file:
load("C:/Users/Desktop/example_candelete.RData")
The Markdownreports package is exactly designed for parsing a markdown document on the fly.
As Julien Colomb commented, I've found the best thing to do in this situation is to save the large objects and then load them explicitly while I'm tailoring the markdown. This is a must if your data is coming through an ODBC and you don't want to run the entire queries repeatedly as you tinker with fonts and themes.
If I load data(mtcars) it comes with a very neat codebook that I can call using ?mtcars.
I'm interested to document my data in the same way and, furthermore, save that neat codebook as a pdf.
Is it possible to save the 'content' of ?mtcars and how is it created?
Thanks, Eric
P.S. I did read this thread.
update 2012-05-14 00:39:59 PDT
I am looking for a solution using only R; unfortunately I cannot rely on other software (e.g. Tex)
update 2012-05-14 09:49:05 PDT
Thank you very much everyone for the many answers.
Reading these answers I realized that I should have made my priorities much clearer. Therefore, here is a list of my priorities in regard to this question.
R, I am looking for a solution that is based exclusively on R.
Reproducibility, that the codebook can be part of a automated script.
Readability, the text should be easy to read.
Searchability, a file that can be open with any standard software and searched (this is why I thought pdf would be a good solution, but this is overruled by 1 through 3).
I am currently labeling my variables using label() from the Hmisc package and might end up writing a .txt codebook using Label() from the same package.
(I'm not completely sure what you're after, but):
Like other package documentation, the file for mtcars is an .Rd file. You can convert it into other formats (ASCII) than pdf, but the usual way of producing a pdf does use pdflatex.
However, most information in such an .Rd file is written more or less by hand (unless you use yet another R package like roxygen/roxygen2 help you to generate parts of it automatically.
For user-data, usually Noweb is much more convenient.
.Rnw -Sweave-> -> .tex -pdflatex-> pdf is certainly the most usual way with such files.
However, you can use it e.g. with Openoffice (if that is installed) or use it with plain ASCII files instead of TeX.
Have a look at package knitr which may be easier with pure-ASCII files. (I'm not an expert, just switching over from Sweave)
If html is an option, both Sweave and knitr can work with that.
I don't know how to get the pdf of individual data sets but you can build the pdf of the entire datasets package from the LaTeX version using:
path <- find.package('datasets')
system(paste(shQuote(file.path(R.home("bin"), "R")),"CMD",
"Rd2pdf",shQuote(path)))
I'm not sure on this but it only makes sense you'd have to have some sort of LaTeX program like MikTex. Also I'm not sure how this will work on different OS as mine is windows and this works for me.
PS this is only a partial answer to your question as you want to do this for your data, but if nothing else it may get the ball rolling.
The help page that is displayed when entering ?mtcars is generated from an .Rd file, which is a LaTeX-like file that is used for all of R's help pages. Although .Rd files are LaTeX-like, you don't actually need to know LaTeX to read or write them. The actual mtcars.Rd file is available here: http://commondatastorage.googleapis.com/jthetzel-public/mtcars.Rd , which can be viewed with any text editor.
.Rd files included in the ./man directory of a package are converted to .html files when installing the package. They are converted by functions in the "tools" package.. If you would like functionality like ?mtcars for your datasets, you would need to create a package for them. That might sound complicated if you have never created a package before, but it is easy enough to learn and will make you a better R programmer. There are a number of examples of dataset-only packages on CRAN, for example msProstate: http://cran.r-project.org/web/packages/msProstate/index.html . Consider downloading the package source to see how it is organized.
For more information on creating your own packages, writing .Rd files, and building packages:
http://cran.r-project.org/doc/manuals/R-exts.html, especially "1.1.5 Data in packages".
Edit
And if you want to convert the .Rd file in your package to a .pdf, you can do so when building your package, but you will need a LaTeX compiler. If you are on Windows, see here: http://cran.r-project.org/bin/windows/Rtools/ .
You can't create a PDF with just R; you need to use other software that creates PDFs.
You could use a combination of utils::promptData, tools::Rd2HTML, and a simple custom function to open the created HTML file in the users' browser.
It would probably be easier to just make a package containing your data sets. Look at the "datasets" package for an example.
It looks like that if you want to generate a pdf, an external tool like LaTeX is always needed. I would recommend using a simple ASCII text format to generate such a file. In principle the .Rd files are also ASCII text, but I do not find them particularly readable.
Instead, I would recommend using a plain text ASCII format such as Markdown (which is e.g. used on StackOverflow) to write the text file. Such a file is already much more readable than an .Rd formatted file, and as a bonus it can quite easily be processed into a PDF should you choose to do so later on. The knitr package I think is capable of generating PDF files from Markdown sources. In addition, knitr allows you to mix in R code in the Markdown text. This code can be evaluated and the results (even figures) added to the resulting PDF.
In practice you can use sprintf to generate character vectors that you can pipe to a file in order to dynamically generate the markdown text. Just write the template one time, and mark the places for the text you want to add later like this:
base_text = "
First header
============
This document was generated on %s, by %s.
"
text_forfile = sprintf(text, some_date, some_name)
Just dump the text in text_forfile to a .md file and your done, no external tools needed. See this post on SO for how dump text to a file.