Skip to content

Contributing to the Rcpp Gallery

Jump to bottom
Dirk Eddelbuettel edited this page Sep 5, 2021 · 20 revisions

Contributions to the Rcpp Gallery are very welcome. To contribute an article you create a source file containing C++ and R code along with appropriate context and explanation. Source files can either be plain C++ files (with some special Doxygen comments) or an R Markdown file that includes C++ and R code blocks.

C++ with Doxygen

You can author articles by simply creating a C++ source file with Doxygen comments. These source files are processed using Rcpp::sourceCpp so can easily export their functions to R and then include R code chunks to demonstrate their use.

To start with, you add an opening comment to the source file containing a pre-defined set of Doxygen fields. For example:

/**
 * @title Modifying a Data Frame
 * @author Dirk Eddelbuettel
 * @license GPL (>= 2)
 * @tags dataframe
 * @summary Demonstrates modifying a data frame passed to a function and 
 *   returning the modified version.
 */

Note that the @license GPL (>= 2) field is required for all submissions and that the @summary field requires indenting if you want to continue it on additional lines.

The remainder of the file contains a mix of the following:

  • Freestanding C++ code that will be compiled using sourceCpp and which follows Rcpp Gallery conventions:
    1. Rcpp namespace should be globally available ("using namespace Rcpp;"); and
    2. Other namespaces (e.g. R, std, arma, etc.) should be explicitly qualified.
  • Additional Doxygen-style comment blocks (e.g. starting with /**) that will be converted to HTML in published articles.
  • R code chunks that will be sourced and run by sourceCpp

Here's an example of including an embedded R code chunk:

/*** R
df <- data.frame(a = c(1, 2, 3),
                 b = c("x", "y", "z"))
modifyDataFrame(df)
*/

Here's an example of C++ source file created using these conventions: 2012-14-14-modifying-a-data-frame.cpp.

Invoking make compiles this source file and converts it into this article on the website: http://gallery.rcpp.org/articles/modifying-a-data-frame/

R Markdown

R Markdown articles can include a mixture of C++ and R code as well as textual content formatted using markdown. R Markdown articles need to include title, author, tags, and summary fields in a --- delimited block at the top of the file:

---
title: Modifying a Data Frame
author: Dirk Eddelbuettel
license: GPL (>= 2)
tags: dataframe
summary: Demonstrates modifying a data frame passed to a function and
   returning the modified version
---

Note that the license: GPL (>= 2) field is required for all submissions and that the summary field requires indenting if you want to continue it on additional lines.

Within R Markdown documents you can specify that the code inside a chunk is C++ code by specifying the engine='Rcpp' option, for example:

```{r, engine='Rcpp'}

Here is an example of a source file authored using this format: 2012-12-18-simulating-vector-autoregressive-process.Rmd

Invoking make compiles the Rmd file and converts it into this article on the website: http://gallery.rcpp.org/articles/simulating-vector-autoregressive-process/

Formatting

Features

Mathematical expressions can be included in R Markdown files and will now be rendered by MathJax. To use this functionality, the mathjax: true field is required, as below.

---
title: Modifying a Data Frame
author: Dirk Eddelbuettel
license: GPL (>= 2)
tags: dataframe
mathjax: true
summary: Demonstrates modifying a data frame passed to a function and
returning the modified version

---

Next, you need to format your mathematical expressions in a way that is expected. For inline math using LaTeX markup like

The equation $$ \hat{\beta} = {X'X}^{-1}X'y $$ makes a good tattoo.

or

The equation
$$ \hat{\beta} = {X'X}^{-1}X'y $$
makes a good tattoo.

For display math, you would use

The equation

$$ \hat{\beta} = {X'X}^{-1}X'y $$

makes a good tattoo.

There are some issues with tables and the | character, though. These can be avoided by using \vert and not |.

Conventions

Contributors will usually use headings of different levels in their posts and in markdown this might look like the following:

# my top level heading
some text

## a subsection
more text

# another top level heading
still yet, more text

However, so the generated HTML file is styled correctly, the convention is to have top level headings at ##, not #. The correct version of the above snippet is as follows:

## my top level heading
some text

### a subsection
more text

## another top level heading
still yet, more text

Submitting an Article

You can submit an article for inclusion in the Rcpp Gallery in one of two ways:

  1. Fork the Rcpp Gallery website and submit a pull request with your new or updated articles. But before doing a pull request, it is often advisable to first discuss the proposed change, here a new article, and establish consensus. See this recommendation in the Rcpp repo which also mentions it for its context.

  2. Post your article on the web (e.g. using a Gist) and then submit an issue requesting that we include the article.

If you are submitting a pull request and/or want to preview what your article will look like once it's published, you'll likely want to clone the Rcpp Gallery repository and setup a local development configuration. Details on doing this are covered in the Local-Development-Configuration article.

Clone this wiki locally