Supplementing your R package with a Shiny app
2016-01-28 21:00
288 查看
http://deanattali.com/2015/04/21/r-package-shiny-app/
The R community is generally very fond of open-source-ness and the idea of releasing all code to the public. Writing packages has become such an easy experience now that Hadley’s
so powerful, and as a result there are new packages being released by useRs every single day.
A good package needs to have two things: useful functionality, and clear usage instructions. The former is a no-brainer, while the latter is what developers usually dread the most - the D-word
(Documentation. Yikes.). Proper documentation is essential so that others will know what your package can do and how to do it. And with the use of Shiny, we now have another great tool we can use to showcase a package’s capabilities.
In a nutshell, Shiny is a package that lets you run your R code
as an interactive webpage. What this means for package developers is that you can have an interactive webpage that lets users experiment with your package and see what it can do before having to read through the potentially lengthy function documentations/vignette.
As an example, I recently released a package for adding marginal plots to ggplot2. You be the judge: after that one-sentence description of some functionality, would you rather go straight to the README,
or see it in action first in a Shiny app online? I might be wrong, but I think it’s useful to interactively see what
the package can do.
Making a Shiny app doesn’t necessarily always make sense for every package, but there are certainly many times when it can be a great addition to a package’s “documentation”. I think that if a
new package has some functions that can be easily illustrated in a simple Shiny app, it’s worth it to take the extra 1-2 hours to develop it. This way, a user who finds your package and isn’t quite sure what to do with it
can try the Shiny app to see whether or not this is the functionality they were looking for. You can have several Shiny apps, each showing the usage of a particular function, or one app that is representative of a whole package. Whatever makes the most sense.
Of course, having a Shiny app is in no way a replacement to documentation, it’s just a useful add-on.
There are two ways to complement a package with a Shiny app that shows its main usage. These two methods are NOT mutually exclusive; I personally do both of them together:
You can host your Shiny app somewhere that is publicly available, such as shinyapps.io or
on your own Shiny Server. Then you can include
a link in the package’s README or vignette or function documentation that points to the Shiny app.
As an example, I host my own Shiny Server where I can host my Shiny
apps, and whenever I release a new package, I include a link in the README to a demo app.
The advantage of doing this is that people can play around with your package before even downloading it.
I recommend including the source code of the Shiny app in your package, and having a function such as
will launch the app. Here are the steps to do this (I’ve learned a lot from looking at
code - thanks RStudio):
First, add
a dependency in your
Then place your Shiny app folder under
add an R file called
should look like this
Your
be simple - it will just look for the Shiny app and launch it
Of course, don’t forget to document this function! Now users can try out an app showcasing your package by running
This method can easily support more than one Shiny app as well, simply place each app under
change the runExample code to something like this
Now running
launch the “myapp” app, and running
a message telling the user what examples are allowed.
The R community is generally very fond of open-source-ness and the idea of releasing all code to the public. Writing packages has become such an easy experience now that Hadley’s
devtoolsis
so powerful, and as a result there are new packages being released by useRs every single day.
A good package needs to have two things: useful functionality, and clear usage instructions. The former is a no-brainer, while the latter is what developers usually dread the most - the D-word
(Documentation. Yikes.). Proper documentation is essential so that others will know what your package can do and how to do it. And with the use of Shiny, we now have another great tool we can use to showcase a package’s capabilities.
Incorporating Shiny
In a nutshell, Shiny is a package that lets you run your R codeas an interactive webpage. What this means for package developers is that you can have an interactive webpage that lets users experiment with your package and see what it can do before having to read through the potentially lengthy function documentations/vignette.
As an example, I recently released a package for adding marginal plots to ggplot2. You be the judge: after that one-sentence description of some functionality, would you rather go straight to the README,
or see it in action first in a Shiny app online? I might be wrong, but I think it’s useful to interactively see what
the package can do.
Making a Shiny app doesn’t necessarily always make sense for every package, but there are certainly many times when it can be a great addition to a package’s “documentation”. I think that if a
new package has some functions that can be easily illustrated in a simple Shiny app, it’s worth it to take the extra 1-2 hours to develop it. This way, a user who finds your package and isn’t quite sure what to do with it
can try the Shiny app to see whether or not this is the functionality they were looking for. You can have several Shiny apps, each showing the usage of a particular function, or one app that is representative of a whole package. Whatever makes the most sense.
Of course, having a Shiny app is in no way a replacement to documentation, it’s just a useful add-on.
There are two ways to complement a package with a Shiny app that shows its main usage. These two methods are NOT mutually exclusive; I personally do both of them together:
1. Host the Shiny app online
You can host your Shiny app somewhere that is publicly available, such as shinyapps.io oron your own Shiny Server. Then you can include
a link in the package’s README or vignette or function documentation that points to the Shiny app.
As an example, I host my own Shiny Server where I can host my Shiny
apps, and whenever I release a new package, I include a link in the README to a demo app.
The advantage of doing this is that people can play around with your package before even downloading it.
2. Include the app in the package and add a function to launch it
I recommend including the source code of the Shiny app in your package, and having a function such as runExample()that
will launch the app. Here are the steps to do this (I’ve learned a lot from looking at
shiny::runExamplesource
code - thanks RStudio):
First, add
shinyas
a dependency in your
DESCRIPTIONfile.
Then place your Shiny app folder under
inst/shiny-examples/and
add an R file called
runExample.R. The package’s tree structure
should look like this
- mypacakge |- inst |- shiny-examples |- myapp |- ui.R |- server.R |- R |- runExample.R |- ... |- DESCRIPTION |- ...
Your
runExample.Rwill
be simple - it will just look for the Shiny app and launch it
#' @export runExample <- function() { appDir <- system.file("shiny-examples", "myapp", package = "mypackage") if (appDir == "") { stop("Could not find example directory. Try re-installing `mypackage`.", call. = FALSE) } shiny::runApp(appDir, display.mode = "normal") }
Of course, don’t forget to document this function! Now users can try out an app showcasing your package by running
mypackage::runExample().
This method can easily support more than one Shiny app as well, simply place each app under
inst/shiny-examples/and
change the runExample code to something like this
runExample <- function(example) { # locate all the shiny app examples that exist validExamples <- list.files(system.file("shiny-examples", package = "mypackage")) validExamplesMsg <- paste0( "Valid examples are: '", paste(validExamples, collapse = "', '"), "'") # if an invalid example is given, throw an error if (missing(example) || !nzchar(example) || !example %in% validExamples) { stop( 'Please run `runExample()` with a valid example app as an argument.\n', validExamplesMsg, call. = FALSE) } # find and launch the app appDir <- system.file("shiny-examples", example, package = "mypackage") shiny::runApp(appDir, display.mode = "normal") }
Now running
runExample("myapp")will
launch the “myapp” app, and running
runExample()will generate
a message telling the user what examples are allowed.
相关文章推荐
- android 实现漫天飞舞雪花以及下雨天的效果
- Dynamics CRM 2015/2016 Web API:注册 APP(调用CRM Online Web API)
- android 导航栏透明
- Android 基础 —— 模拟实现拨打电话功能
- android之浮动title
- Android中自定义一个事件监听器
- Android自定义View
- Android中Relativelayout各个属性
- Android 6.0 inflate过程分析
- 献给初学iOS的小盆友们——微博app项目开发之十四转发微博修正以及添加微博工具条
- Unity3d之剥离 alpha 通道
- Android 5.1编译
- iOS把两张图片合成一张图片
- iOS 使用动态库(dylib)和动态加载framework
- 【第一行代码】Android日志工具
- Android实现边录音边播放
- iOS CGContextRef画图小结
- iOS:手把手教你发布代码到CocoaPods(Trunk方式)
- iOS 画贝塞尔曲线代码
- [ios]如何手动symbolicate一个crash log文件