kickstarter / Kumquat
Programming Languages
Kumquat
Kumquat is a reporting tool for rendering RMarkdown files inside Rails.
RMarkdown, or .Rmd
files are Markdown files with code chunks of R in them.
You can use Kumquat to integerate R output into Rails, which is useful for using libaries like ggplot2
in email reporting tools.
Example
For example, consider a typical render
call to a partial:
render '_a_knitr_report'
This partial is _a_knitr_report.Rmd
, a regular RMarkdown file stored in your app:
A Test Report for Kumquat
========================================================
This is some code for Knitr, including [a link](https://www.kickstarter.com).
A list:
* One
* Another thing
* Last thing!
### More stuff.
Lorem Ipsum.
```{r, fig.width=10, fig.height=8, echo=FALSE, message=FALSE}
library(ggplot2)
qplot(data = data.frame( x = runif(100), y = runif(100) ), x = x, y = y)
```
Which yields the following output:
Kumquat can be integrated anywhere inside Rails views where partials are called.
How it Works
Kumquat requires R to be installed on the machines running your application. The main action is then in Knit2HTML
which shells out to Rscript
and runs the necessary knitr
package methods to compile HTML.
When you install Kumquat a template handler is registered to handle Rmd files.
Also, Email
A mail interceptor, KumquatReportInterceptor
is also registered to attach images inline to Rmd reports marked with an X-KUMQUAT
signature which you can add to a mail object accordingly:
mail :to => @admin.email,
:reply_to => "[email protected]",
:subject => "Test Kumquat Report",
'X-KUMQUAT' => true do |format|
format.text { render layout: nil }
format.html { render layout: nil }
end
Setup & Development
Kumquat requires R to be installed, and the knitr packages to render RMarkdown files. The rest of the R dependencies are up to you, but need to be specified in the KNITR_LIBRARIES
constant in the Knit2HTML
class.
Chef Recipe
If you're curious about installing R using Chef, check out a suggested recipe on the wiki
Database Support
If you need to connect R to a database and provide credentials from your application, you can do so in an application initializer like so:
Kumquat.database_config(Configs[:redshift].merge({ database_connector: "RPostgres::Postgres()" }))
We are using Hadley Wickham's RPostgres library which can be installed in R accordingly:
install.packages("devtools")
devtools::install_github("RcppCore/Rcpp")
devtools::install_github("rstats-db/DBI")
devtools::install_github("rstats-db/RPostgres")
library(DBI)
Sending emails from a local development environment
If you'd like to deliver emails in your local environment, make sure your config.action_mailer.delivery_method
is configured properly, and you have a way to send email locally (on OS X, run the command sudo postfix start
).
Logging
You can view kumquat and email logs for debugging tail -f log/kumquat.log