How to Host and Share RMarkdown Files
When I first learned how to use RMarkdown, I was in absolute awe. Moving from copy/pasting SPSS output into Word documents, to being able to automatically generate a rich analysis report full of text and visualizations at the press of a button was game-changing. RMarkdown files can also be rendered into a variety of formats which not only covers HTML, but also PDFs, Word documents, and others. While sharing an output file is easy and works great for an analysis that is conducted once, what if there are frequent updates that you want to share with clients/colleagues/others?
In the case that an analysis gets updated, it is not ideal to constantly be emailing various versions of the output file. This quickly becomes messy and unorganized. Plus, as the analyst you have to be spending time sending the output file. This can be especially troublesome if you’re looking to share the analysis with a large group.
One solution to this problem is to host your file on a server or website. You can choose to organize the files, or even overwrite the old analysis so that people viewing are always viewing the most up-to-date file.
Shinyapps.io
While there are many ways to host files online, our current favorite method at CompassRed is using shinyapps.io. This is a service that is offered by RStudio, and as the name suggests, mainly deals with hosting RShiny apps. RShiny is an incredibly flexible framework for building various types of web apps. Initially, we started using the service to host the apps that we have been developing. For example, check out this awesome dashboard that my colleague Ben Kates built for Delaware’s New Castle County. This dashboard displays the data collected by Biobot Analytics on the number of COVID-19 samples found in wastewater.
While there is a bit of a learning curve to start using RShiny, you can use shinyapps.io to host your existing RMarkdown files as well. The service also makes it easy to make updates to the hosted file right from your work station. Here’s how to do it!
- First, you need to create a new account on shinyapps.io. There’s a free tier, as well as paid tiers with the main difference being number of active hours and performance.
- Once your account is created and you are logged in, you will have to obtain a token in order for RStudio to be able to connect to your account and make publishing (RStudio’s language for deploying/hosting) seamless. Follow these two screenshots, and copy the code that is shown:
3. Once you have saved the above code, open up RStudio and install/load the following package: install.packages('rsconnect');library(rsconnect). Then run the code you copied, and your account should now be linked.
4. Once you’re ready to host your RMarkdown file, add the code runtime: shiny to the YAML. This essentially turns your markdown into a shiny app. Click the publish button (in the blue box above), and that will let you set the name of the app, as well as any files you want to include. Since your markdown will be rendered by shinyapps.io, you will want to include all the files that you need such as data, functions, etc.
That’s it! You should now see the name of your app in the shinyapps.io applications dashboard. You will have all of the information you need, and to access the analysis/app just follow the link that is given in the shinyapps.io dashboard. Typically, this follows for the format of :[accountname].shinyapps.io/[app_title].
As mentioned above, one really great benefit of hosting your RMarkdown file this way is being able to update the analysis very easily. Since you’re able to publish as frequently as you want, whenever there’s a new update to the analysis, you can re-publish and the hosted app will update accordingly.
Caveats
While shinyapps.io has a free tier which can allow you to start using this quickly, it is worth mentioning the limitations.
The free tier contains 25 “active hours” per month. When no one is accessing an app, it is considered “sleeping”, and does not use up any active hours. However, once someone goes to the app link, it becomes active and starts to use up the active hours. If people are going to be accessing the app continuously, the 25 hour allotment will run out by the next day and you will not be able to use the service until the following month. The free tier allows you to create up-to 5 separate apps, but the 25 hours is the limit across all apps. Essentially, the free tier allows you to learn how to use the service but it is recommended to move up to a paid tier in order to use the service on a larger scale. The pricing of the different tiers is as follows:
Another caveat is regarding access and authentication. As seen above, only the two most expensive plans have authentication for apps built-in. For any of the cheaper plans, you will have to use your own authentication method, otherwise all of your apps will be public.
Rpubs
Rpubs is a completely free alternative if you only want to host RMarkdown files. This requires you to knit (create an html file) first, and then publish the file on Rpubs.
The limitations with this method is that you lose out on potential features such as being able to add authentication since anything on Rpubs is completely public. There are also things you can do on shinyapps.io such as incorporating parameters and other UI elements. Finally, with shinyapps.io, you can incorporate RShiny apps right in an RMarkdown which is not something you can do with Rpubs since it just hosts the html file. Stay tuned for an overview of some of the above features in future posts!
