Publishing WP blog posts directly from RStudio!

Recently I have been working quite a bit in RStudio, not only to write R code but also to create really useful interactive reports. It already was my favourite IDE, but since they introduced the notebook functionality, it has become an amazing multi-purpose research tool! I thought it would be really nice to be able to publish some of the reports I write using RMarkdown on my WordPress blog for future reference, but I didn’t know how to do it. Fortunately, after digging just a little bit into the wonderful web, I found a few tutorials that guided me through the process. The most thorough of them may be this blog post by 3.14a. In addition to that, William K Morri’s blog, and knitr creator Yihiu Xie’s webpage were extremely useful to make it work properly.

In this post I report the steps I followed for my own future reference (and anyone that might find it useful, of course). But I also use it to test that the process has worked as expected, as I have written it in RStudio and uploaded it to WordPress using the very same steps I report.

So this is basically a blog post about this blog post. A recursive post.

Installation and Configuration

I first review the necessary steps that will later allow me to upload posts to omy own WordPress account. They are mainly based in the tutorial I mentioned above, and, as you will see, quite easy to follow. But when I was trying to make it work some issues arised, so I think it is a good idea to report them here just in case.

Installing and Loading R Packages

Uploading and publishing in WordPress blog posts written in RMarkdown requires to have R‘s package RWordPress installed. Unfortunately, the source recommended in 3.14a’s tutorial (and in many other places) doesn’t work properly for me. More precisely, the link seems to be broken.

Fortunately, Yihui Xie’s webpage includes another tutorial with a working source for the package. As it is hosted in a Github Repo, we can use the install_github function from the devtools package to install it directly from the source.

library(devtools)
if (!require('RWordPress')) {
  devtools::install_github(
    c("duncantl/XMLRPC", "duncantl/RWordPress"))
}

We also need the knitr package, but it comes pre-installed with RStudio, so I don’t need to get it on purpose. We can now load both packages. (You might see a warning message being showed. It’s normal; I simply ignored it.)

library(RWordPress)
library(knitr)

Setting Options

In order to upload the posts written in RStudio to our blog, I need to configure some options:

options(WordPressLogin=c(your_username="your_password"),
        WordPressURL="https://your.blog.com/xmlrpc.php")

But be careful! At first I was trying to use an http URL (as it appeared by default in the tutorial), and getting an error for it. After changing it to https, it worked perfectly. So, in my case, the correct URL would be https://rhapsodyinmu.wordpress.com/xmlrpc.php.

In addition to that, it is also important to specify the way we want the images (e.g., plots) to be uploaded, so that they appear in WordPress. If we do nothing, we will not see anything. Trust me, I tried.

The code below allows knitr to upload any image (generated inside a code chunk, I think) to Imgur automatically, and include in the source code of our post the necessary HTML tag to retrieve it from the hosting service and show it. It works like a charm, as I will demonstrate later!

opts_knit$set(upload.fun = imgur_upload, base.url = NULL) 

Writing a Post

As we mentioned before, I will use RMarkdown to write the blog posts. It’s really easy to learn. I can’t recommend enough to take a look at the tutorial in here. Follow the lessons and you’ll realise how intuitive it becomes to write a dynamic report (or a blog post in our case) that looks amazing.

Unfortunately, WordPress (by default) doesn’t accept all RMarkdown possibilities, so our post will not look as pretty as it does in RStudio’s preview. If you are lucky enough to self-host your WordPress.org site, you can install some Add-Ons that will even enhance its appearance, such as Crayon Syntax Highlighter or WP QuickLaTeX. On the other hand, if you, like me, host your site in WordPress.com, you will need to resign yourself to a slightly less awesome appearance. Not being able to use those Add-Ons may motivate me to migrate the blog to a WordPress.org self-hosting site. I’ll think about it.

R Code

Apart from allowing us to write formatted text with non-distracting “tags” that can be converted to HTML easily, we can use an RMarkdown file to include and execute R code. I here check that both the code chunks and the computed outputs look nice when uploaded to WordPress.

As I mentioned before, if you are lucky enough to be self-hosting your site, the Crayon Syntax Highlighter Add-On will make your code chunks look quite impressive. If not, then I strongly recommend you to use the shortcode = c(T, T) parameter in your call to the knit2wp function when uploading the post. I include an example of it on the next section.

Let’s start with a simple code chunk with no output…

library(ggplot2)
library(dplyr)

Looks fine. What about a simple operation with output?

sum(c(1:10))
## [1] 55

What about a table?

mtcars %>% select(mpg, wt, cyl) %>% summary()
##       mpg              wt             cyl       
##  Min.   :10.40   Min.   :1.513   Min.   :4.000  
##  1st Qu.:15.43   1st Qu.:2.581   1st Qu.:4.000  
##  Median :19.20   Median :3.325   Median :6.000  
##  Mean   :20.09   Mean   :3.217   Mean   :6.188  
##  3rd Qu.:22.80   3rd Qu.:3.610   3rd Qu.:8.000  
##  Max.   :33.90   Max.   :5.424   Max.   :8.000

If you want, you can use the function kable from the knitr package to make your tables look much better.

kable(
  mtcars %>% select(mpg, wt, cyl) %>% summary()
  )
mpg wt cyl
Min. :10.40 Min. :1.513 Min. :4.000
1st Qu.:15.43 1st Qu.:2.581 1st Qu.:4.000
Median :19.20 Median :3.325 Median :6.000
Mean :20.09 Mean :3.217 Mean :6.188
3rd Qu.:22.80 3rd Qu.:3.610 3rd Qu.:8.000
Max. :33.90 Max. :5.424 Max. :8.000

Finally, let’s try a figure. As we have previously set the option to upload figures to Imgur automatically, we just need to specify a name for the code chunk, and the image will be referenced using that name. For instance, in the header of the code chuck that generates the figure below I have written:

{r ggplot_mtcars, fig.width=7, fig.height=4, plot.align=center},

so that the resulting figure will be labelled plot of chunk ggplot_mtcars and have the specified dimensions (useful to avoid huge figures occupying the whole screen).

ggplot(mtcars, aes(wt, mpg, color = cyl)) + geom_point()

plot of chunk ggplot_mtcars

Python Code

We can also include code in programming languages other than R, such as Python, and we will still be able to see the output:

def test_function(parameter):
  return parameter + 1

print(test_function(2))

## 3

We can even import libraries, such as numpy, and use them:

import numpy as np

a = np.arange(15).reshape(3, 5)
print(a)
## [[ 0  1  2  3  4]
##  [ 5  6  7  8  9]
##  [10 11 12 13 14]]

However, state is not kept across cells, which obviously reduces its usefulness:

print(a)
## Traceback (most recent call last):
##   File "<string>", line 1, in <module>
## NameError: name 'a' is not defined

I have also tried to generate a matplotlib figure, but, after taking a really long time to render, it appeared in a floating window instead of within the report. A pity.

Latex Equations

Another functionality I suspect I will be using quite often in these reports/posts is writing \LaTeX equations.
Apparently, if we could use the WP QuickLaTeX WordPress.org Add-On, we would be able to include \LaTeX code between dollar signs – $...$, or $$...$$ for stand-alone equations – and see exactly the same output both in RStudio and WordPress.
Unfortunately, not having a self-hosted site forces us to add latex just after the opening dollar sign (and between backticks), which is not understood by RStudio (or rmarkdown, I guess). This means that the output looks quite ugly in the preview.

For example, we can get a pretty inline equation in WordPress (y_{i} = \mu + \epsilon_{i}), but in RStudio we still see the unrendered code. Exactly the same happens with standalone equations:

\bar{y} = \frac{\sum_{i = 0}^{N}{y_i}}{N}

(Note: I surrounded it with HTML tags to center-align it.)

This feels very hacky and really disturbs the workflow. This drawback may force me to consider getting some hosting space…

I Have Written a Post. Now What?

After writing the post in RStudio, we should upload it to WordPress. Yihui Xie, creator of knitr comes again to our help.

Upload (as a Draft!)

I strongly recommend uploading the post forcing it not to be published. In other words, first upload it as a draft, and only publish it (from WordPress) if we are happy with the result. The knit2wp function included in knitr allows us to do so if we indicate publish = F in its call. See below a template for uploading a post as a draft:

id <- knit2wp('yourfile.Rmd', title = 'Your post title',
              shortcode = c(T, T), action = 'newPost',
              publish = F)

We assign the output to a variable (id) to be able to keep track of the ID of the uploaded post in WordPress in case we need to edit it in the future.

Notice that I used the parameter shortcode = c(T, T), as I cannot use an external code highlighter. In case you can, it looks much better if you leave shortcode as false (shortcode = F), allowing the external highlighter to take care of how code chunks look like.

We can also add more information in our call, such as including categories (e.g., categories = c('R', 'Stats')) or keywords (e.g., mt_keywords = c('knitr', 'wordpress'))). However, I tried to include categories and WordPress completely ignored me. I guess the problem was that all the categories I intended to use were new in WordPress, so I can only use the option with pre-existing ones.

Edit a Previously Uploaded Post

You can edit the post as many times as you want, until you are convinced with the result and ready to publish. If you keep track of the id and use knit2wp with action = 'editPost' and postid = id, you can avoid uploading new drafts every time and updating the original one instead.

knit2wp('yourfile.Rmd', postid = id,
        title = 'Your post title',
        shortcode = c(T, T), action = 'editPost', publish = F
        )

Publish

Once you are happy with the result, you can finally publish the post either by using another call to knit2wp with publish = T, or by using the WordPress assistant.

Conclusion

Apart from how annoying will be to write \LaTeX equations, I am really satisfied with this workflow. I hope it will allow me to publish more often (I keep saying that and… it has been almost one month since the first and only post here…).

I’ll be back soon!!! (For real)

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s