From 4cd3a9c2365664cadf61666df039e93a7e97aa0f Mon Sep 17 00:00:00 2001 From: Joe Cheng Date: Fri, 26 Feb 2016 15:12:26 -0800 Subject: [PATCH] Small tweaks --- index.Rmd | 13 ++++++------- layouts.Rmd | 15 ++++----------- shiny.Rmd | 18 +++++++++--------- snippets/textannotation.md | 18 +++++++++--------- using.Rmd | 31 +++++++++++++++---------------- 5 files changed, 43 insertions(+), 52 deletions(-) diff --git a/index.Rmd b/index.Rmd index 3980f7b7..c420b4cc 100644 --- a/index.Rmd +++ b/index.Rmd @@ -30,7 +30,7 @@ To author a flexdashboard you create an [R Markdown](http://rmarkdown.rstudio.co -If you are not using RStudio you can create a new `flexdashboard` R Markdown file from the command line as follows: +If you are not using RStudio, you can create a new `flexdashboard` R Markdown file from the R console: ```r rmarkdown::draft("dashboard.Rmd", template = "flex_dashboard", package = "flexdashboard") @@ -40,13 +40,13 @@ rmarkdown::draft("dashboard.Rmd", template = "flex_dashboard", package = "flexda You can use flexdashboard to publish groups of related data visualizations as a dashboard. A flexdashboard can either be static (a standard web page) or dynamic (a [Shiny](shiny.html) interactive document). -One of the most important characteristics of flexdashboard is the automatic scaling of charts to fit available browser width and (optionally) browser height. This makes flexdashboard ideal for publishing [htmlwidgets](http://www.htmlwidgets.org) since these widgets automatically re-size themselves to their containers. +One of the most important characteristics of flexdashboard is the automatic scaling of charts to fit available browser width and (optionally) browser height. This makes flexdashboard ideal for publishing [htmlwidgets](http://www.htmlwidgets.org) since these widgets automatically re-size themselves to their containers. -You can also use flexdashboard to publish base, lattice, and ggplot2 graphics. These charts are also automatically resized to fit their containers within dynamic (Shiny) dashboards, however in static dashboards a bit more work (described in [Figure Sizes and Scaling](using.html#figure-sizes-and-scaling)) is required to ensure that they are properly scaled. +You can also use flexdashboard to publish base, lattice, and ggplot2 graphics. These charts are also automatically resized to fit their containers within dynamic (Shiny) dashboards; in static dashboards, however, a bit more work is required to ensure that they are properly scaled (see [Figure Sizes and Scaling](using.html#figure-sizes-and-scaling)). ### Single Column Layout -Dashboards are divided into columns and rows, where by default columns are defined using level 2 markdown headers (`------------------`) and charts are defined using level 3 headers (`###`). Charts are stacked vertically within a column. For example, this layout defines a single column with three charts: +Dashboards are divided into columns and rows. By default, columns are defined using level 2 markdown headers (`------------------`) and charts are defined using level 3 headers (`###`). Charts are stacked vertically within a column. For example, this layout defines a single column with three charts:
@@ -92,13 +92,12 @@ To add a second column of charts we just add another column section:
-In this example we've moved **Chart 1** into it's own column which it will fill entirely. Since we only have 1 or 2 charts vertically stacked, we also specify the `fill_page: true` option to automatically scale the charts to the full height of the page. Finally, we want to provide additional emphasis to the chart appearing in the first column so we give the column a larger size via the `data-width` attribute. +In this example we've moved **Chart 1** into its own column which it will fill entirely. Since we only have one or two charts vertically stacked, we've also specified the `fill_page: true` option to automatically scale the charts to the full height of the page. Finally, we've given the column a larger size via the `data-width` attribute to provide additional emphasis to Chart 1. ## Learning More The [Using](using.html) page includes documentation on all of the features and options of flexdashboard, including layout orientations (row vs. column based), chart sizing, text annotations, theming, and creating dashboards with multiple pages. -The [Shiny](shiny.html) page describes how to create dashboards that enable viewers to change underlying parameters and see the results immediately. +The [Shiny](shiny.html) page describes how to create dashboards that automatically update themselves as the underlying data changes, or allow viewers to change parameters and see the results immediately. The [Layouts](layouts.html) page includes a variety of sample layouts which you can use as a starting point for your own dashboards. - diff --git a/layouts.Rmd b/layouts.Rmd index ae2a7036..eb00b16f 100644 --- a/layouts.Rmd +++ b/layouts.Rmd @@ -8,13 +8,13 @@ This page includes a variety of sample layouts which you can use as a starting p When creating a layout, it's important to decide up front whether you want your charts to fill the web page vertically (changing in height as the browser changes) or if you want the charts to maintain their original height (with the page scrolling as necessary to display all of the charts). -This behavior is controlled via the `fill_page` output option, which defaults to `false`. Filling the page is generally a good choice when you have only 1 or 2 charts vertically stacked, whereas scrolling is generally a better choice for 3 or more charts vertically stacked. The sample layouts below reflect these general guidelines. +This behavior is controlled via the `fill_page` output option, which defaults to `false`. Filling the page is generally a good choice when you have only one or two charts vertically stacked, whereas scrolling is generally a better choice for three or more charts vertically stacked. The sample layouts below reflect these general guidelines. ## Layouts ### Chart Stack (Fill) -This layout is a simple stack of two charts. Since there are only 2 charts the need to scroll is unlikely, so `fill_page: true` is specified so they grow to fill the page vertically. Note that one chart or the other could be made vertically taller by specifying the `data-height` attribute. +This layout is a simple stack of two charts. Since there are only two charts the need to scroll is unlikely, so `fill_page: true` is specified so they grow to fill the page vertically. Note that one chart or the other could be made vertically taller by specifying the `data-height` attribute.
@@ -34,7 +34,7 @@ This layout is a simple stack of two charts. Since there are only 2 charts the n ### Chart Stack (Scrolling) -This layout is a simple stack of 3 charts. To provide enough room to display all the charts a scrolling layout is used (`fill_page: false`). Note that because of its ability to scroll this layout could easily accommodate many more charts (although for large numbers of charts you might consider organizing them into [Multiple Pages]). +This layout is a simple stack of three charts. To provide enough room to display all the charts a scrolling layout is used (`fill_page: false`). Note that because of its ability to scroll this layout could easily accommodate many more charts (although for large numbers of charts you might consider organizing them into [Multiple Pages]).
@@ -141,14 +141,7 @@ This layout is a 2x2 grid of charts that uses `fill_page: true`. Note that depen ### Multiple Pages -This layout defines multiple pages using a level 1 markdown header (`==================`). Each page has it's own top-level navigation tab. Further, the second page uses a distinct orientation via the `data-orientation` attribute. +This layout defines multiple pages using a level 1 markdown header (`==================`). Each page has its own top-level navigation tab. Further, the second page uses a distinct orientation via the `data-orientation` attribute.
- - - - - - - diff --git a/shiny.Rmd b/shiny.Rmd index 23b69f12..c890cafb 100644 --- a/shiny.Rmd +++ b/shiny.Rmd @@ -1,6 +1,6 @@ --- title: "Using Shiny with flexdashboard" -output: +output: html_document: toc: true toc_depth: 2 @@ -8,7 +8,7 @@ output: ## Overview -By adding [Shiny](http://shiny.rstudio.com) to a flexdashboard, you can create dashboards that enable viewers to change underlying parameters and see the results immediately. This is done by adding `runtime: shiny` to a standard flexdashboard and then adding one or more input controls that dynamically drive the appearance of the charts within the dashboard. +By adding [Shiny](http://shiny.rstudio.com) to a flexdashboard, you can create dashboards that enable viewers to change underlying parameters and see the results immediately, or that update themselves incrementally as their underlying data changes (see [`reactiveFileReader`](http://shiny.rstudio.com/reference/shiny/latest/reactiveFileReader.html) and [`reactivePoll`](http://shiny.rstudio.com/reference/shiny/latest/reactivePoll.html)). This is done by adding `runtime: shiny` to a standard flexdashboard and then adding one or more input controls and/or reactive expressions that dynamically drive the appearance of the charts within the dashboard. Using Shiny with flexdashboard turns a static R Markdown report into an [Interative Document](http://rmarkdown.rstudio.com/authoring_shiny.html). It's important to note that interactive documents need to be [deployed](http://rmarkdown.rstudio.com/authoring_shiny.html#deployment) to a Shiny Server to be shared broadly (whereas static R Markdown documents are standalone web pages that can be attached to emails or served from any standard web server). @@ -18,11 +18,11 @@ The steps required to add Shiny components to a flexdashboard are as follows: 1. Add `runtime: shiny` to the options declared at the top of the document (YAML front matter). -2. Add the `{.sidebar}` attribute to the first column of the dashboard to make it a host for Shiny input controls (note this step isn't strictly required but nearly all Shiny based dashboards will want to do this). +2. Add the `{.sidebar}` attribute to the first column of the dashboard to make it a host for Shiny input controls (note this step isn't strictly required, but most Shiny based dashboards will want to do this). -3. Add Shiny inputs and output as appropriate. +3. Add Shiny inputs and output as appropriate. -A simple example of a Shiny based flexdashboard is provided below. +A simple example of a Shiny based flexdashboard is provided below. ## Simple Example @@ -39,11 +39,11 @@ Here's the source code for the example. Note that since we have only a single ch The first column ("Inputs") includes the `{.sidebar}` attribute and the Shiny input controls; the second column ("Outputs") includes the Shiny code required to render the chart based on the inputs. -## Input Sidebar +## Input Sidebar -The `{.sidebar}` attribute is a special designator indicating that a column should be laid out flush to the left with a fixed width of 250 pixels and a special background color. Sidebars are not required for flexdashboards using `runtime: shiny` however they are often useful for presenting inputs. +The `{.sidebar}` attribute is a special designator indicating that a column should be laid out flush to the left with a fixed width of 250 pixels and a special background color. Sidebars are not required for flexdashboards using `runtime: shiny`, but they are often useful for presenting inputs. -Sidebars always appear on the left no matter where they are defined within the flow of the document. You alter the default width of the sidebar using the `data-width` attribute. For example: +Sidebars always appear on the left no matter where they are defined within the flow of the document. You can alter the default width of the sidebar using the `data-width` attribute. For example:
@@ -61,7 +61,7 @@ The [shinydashboard](https://rstudio.github.io/shinydashboard/) package also pro 4. flexdashboard performs automatic scaling of charts to the size of the browser and as a result takes maximum advantage of available screen real estate when used with htmlwidgets (i.e. visualizations that automatically size themselves to their container). -3. flexdashboard can create standalone web dashboards (requiring no Shiny Server) if they are restricted to just presenting data rather than allowing the user to vary assumptions and parameters. +3. flexdashboard can create standalone web dashboards (requiring no Shiny Server) if they are restricted to just presenting static data rather than allowing the user to vary assumptions and parameters or observing changes in realtime. ## Learning More diff --git a/snippets/textannotation.md b/snippets/textannotation.md index e17f61e5..0653c1cf 100644 --- a/snippets/textannotation.md +++ b/snippets/textannotation.md @@ -1,13 +1,13 @@ --- title: "Text Annotations" -output: +output: flexdashboard::flex_dashboard: fill_page: true orientation: rows --- Monthly deaths from bronchitis, emphysema and asthma in the UK, 1974–1979. - + ```{r setup, include=FALSE} library(dygraphs) ``` @@ -16,14 +16,14 @@ Row {data-height=600} ------------------------------------- ### All Lung Deaths - + ```{r} dygraph(ldeaths) ``` - + Source: P. J. Diggle (1990) Time Series: A Biostatistical Introduction. Oxford, table A.3 - -Row {data-height: 400} + +Row {data-height=400} ------------------------------------- ### Male Deaths @@ -31,13 +31,13 @@ Row {data-height: 400} ```{r} dygraph(mdeaths) ``` - + Note: Includes only male deaths - + ### Female Deaths ```{r} dygraph(mdeaths) ``` - + Note: Includes only female deaths diff --git a/using.Rmd b/using.Rmd index f15af823..e0edbf5e 100644 --- a/using.Rmd +++ b/using.Rmd @@ -8,7 +8,7 @@ output: ## Layout Orientation -By default level 2 markdown headers (`------------------`) within dashboards define columns, with individual charts stacked vertically within each column. Here's the definition of simple dashboard with 3 charts stacked into a single column: +By default, level 2 markdown headers (`------------------`) within dashboards define columns, with individual charts stacked vertically within each column. Here's the definition of simple dashboard with three charts stacked into a single column:
@@ -27,7 +27,7 @@ By default level 2 markdown headers (`------------------`) within dashboards def
-However it's also possible to orient dashboards around rows rather than columns. You can do this by specifying the `orientation: rows` option. For example, this layout defines two rows, the first of which has a single chart and the second of which has two charts: +You can also choose to orient dashboards row-wise rather than column-wise, by specifying the `orientation: rows` option. For example, this layout defines two rows, the first of which has a single chart and the second of which has two charts:
@@ -55,7 +55,7 @@ However it's also possible to orient dashboards around rows rather than columns. ## Chart Sizing -To create an ideal layout for your dashboard it's important to understand how the size of individual charts is determined. This section describes the layout algorithm and the various ways you can tweak it's behavior. +To create an ideal layout for your dashboard, it's important to understand how the size of individual charts is determined. This section describes the layout algorithm and the various ways you can tweak its behavior. ### Chart Width @@ -73,7 +73,7 @@ The height of charts is determined in one of two ways depending on whether your The nature of the charts within your dashboard (desired emphasis, visualization types, etc.) will often dictate that you'll want to change the default sizing behavior. If no size attributes are specified then the relative size of each chart will be determined by it's knitr figure size (this is 5x4 inches or 480x384 pixels by default). -You can modify the default sizing behavior by applying the `data-width` and `data-height` attributes to rows, columns, or even individual charts. These attributes establish the relative size between charts laid out in the same dimension (horizontal or vertical). +You can modify the default sizing behavior by applying the `data-width` and `data-height` attributes to rows, columns, or even individual charts. These attributes establish the relative size between charts laid out in the same dimension (horizontal or vertical). ### Examples @@ -100,7 +100,7 @@ This example combines the `fill_page` option with custom size attributes that di
- + Note that we've specified a `data-height` attribute on both rows to establish their relative heights. This results in a layout that more clearly emphasizes the first chart. This example is a variation of the single-column layout demonstrated above with a `data-height` attribute applied to the first chart: @@ -130,11 +130,11 @@ Layout is done using the browser [flexbox](https://developer.mozilla.org/en-US/d The implication of this is that chart dimensions established via either knitr figure sizes or `data-width` and `data-height` attributes are used to establish relative sizes between charts within the same horizontal or vertical dimension as opposed to absolute sizes (this corresponds to the `flex-grow` and `flex-shrink` CSS properties). -## Figure Sizes and Scaling +## Figure Sizes and Scaling -Charts will always be automatically scaled to fit within their allocated flexbox region. For charts based on [htmlwidgets](http://www.htmlwidgets.org) this scaling will nearly always result in a chart that perfectly fits the bounds of it's container since htmlwidgets can dynamically re-size themselves. +Charts will always be automatically scaled to fit within their allocated flexbox region. Charts based on [htmlwidgets](http://www.htmlwidgets.org) can dynamically resize themselves, so their scaling will nearly always result in charts that perfectly fit the bounds of their containers. -It's also possible to use charts created using standard R graphics (base, lattice, ggplot2, etc.) with flexdashboard. Within dynamic (Shiny) dashboards these charts are also automatically sized to fit within their containers. +It's also possible to use charts created using standard R graphics (base, lattice, ggplot2, etc.) with flexdashboard. Within dynamic (Shiny) dashboards these charts are also automatically sized to fit within their containers (see the [section on `renderPlot`](shiny.html#TODO)). Within static dashboards standard R graphics are also scaled (with aspect ratios preserved so there is no stretching or distortion). However, since these charts are PNG images it's not possible for them to seamlessly fill the bounds of their container. When creating static dashboards containing standard R graphics it's therefore critical to define knitr `fig.width` and `fig.height` values as close as possible to what they'll actually be on the page. @@ -144,15 +144,15 @@ Here's an example of a row based layout that includes 3 charts from R base graph -We've specified an explicit `fig.height` and `fig.width` for each chart so that their rendered size fits their flex container as closely as possible. Note that the ideal values for these dimensions typically need to be determined by experimentation. Note also that we are using a scrolling layout (`fill_page: false`) which makes it easier to reason about the actual height which plots will be rendered at. +We've specified an explicit `fig.height` and `fig.width` for each chart so that their rendered size fits their flex container as closely as possible. Note that the ideal values for these dimensions typically need to be determined by experimentation. Note also that we are using a scrolling layout (`fill_page: false`) which makes it easier to reason about the actual height which plots will be rendered at. Even with the tweaks described above standard R graphics won't always fit perfectly into their containers, so in general htmlwidget based charts are preferred within static dashboards. Note that the [plotly](https://plot.ly/ggplot2/) package enables rendering of ggplot2 graphics as interactive htmlwidgets. ## Multiple Pages -If you have more than a handful of charts you'd like to include in a dashboard you may want to consider dividing the dashboard into multiple pages. To define a page just use a level 1 markdown header (`==================`). Each page you define will have it's own top-level navigation tab. +If you have more than a handful of charts you'd like to include in a dashboard, you may want to consider dividing the dashboard into multiple pages. To define a page just use a level 1 markdown header (`==================`). Each page you define will have its own top-level navigation tab. -For example, this code creates a dashboard with 2 pages, each containing 2 charts: +For example, this code creates a dashboard with two pages, each containing two charts:
@@ -164,7 +164,7 @@ Note that in this example both pages use the default "columns" orientation. It i ## Navigation Bar -By default the flexdashboard navigation bar includes only the dashboard title. For dashboards with [Multiple Pages] links to other available pages are also included. In addition you can add custom links to navigation bar using the `navbar` option. For example, the following adds "About" and "Source Code" links to the right side of the navigation bar: +By default, the flexdashboard navigation bar includes only the dashboard title. When a dashboard has [Multiple Pages], links to other available pages are also included. You can also add custom links to navigation bar using the `navbar` option. For example, the following adds "About" and "Source Code" links to the right side of the navigation bar: @@ -175,13 +175,13 @@ The `title` and `url` fields are required for navigation bar items. The `align` You can provide short text annotations for the various charts within a dashboard by including text immediately below the R code chunk where the chart is rendered. You can also include arbitrary content at the top of the dashboard before rows, columns, and charts are specified. -For example, the following dashboard includes some content at the top as well as a brief comment for it's first chart: +For example, the following dashboard includes some content at the top, as well as a brief comment for its first chart:
-This example also demonstrates the use of a "setup chunk" to load required R packages prior to executing the rest of the R chunks that make use of them as well as using a custom `data-height` attribute for the rows to make the first row disproportionately larger than the second row. - +This example also demonstrates the use of a "setup chunk" to load required R packages prior to executing the rest of the R chunks that make use of them, as well as using a custom `data-height` attribute for the rows to make the first row disproportionately larger than the second row. + ## Visual Themes A variety of themes are available to modify the appearance of flexdashboard. Supported themes include "default", "bootstrap", "cerulean", "journal", "flatly", "readable", "spacelab", "united", "cosmo", "lumen", "paper", "sandstone", "simplex", and "yeti". Note that the "cosmo" theme is used when "default" is specified. @@ -192,4 +192,3 @@ Use the `theme` option to specify an alternate theme:
-