.. _rshiny-apps:

Using R Shiny
=============

Faculty supports building `R Shiny <https://shiny.rstudio.com/>`_
applications. R Shiny offers a flexible interface for building
interactive dashboards entirely in R (you don't need to write any
JavaScript). The Shiny `gallery <https://shiny.rstudio.com/gallery/>`_ has
some great examples of dashboards, and the `shiny-examples repository on github
<https://github.com/rstudio/shiny-examples>`_ for many more that can be used as
starting point for your own app.

.. contents:: Contents
    :local:

Developing the application
--------------------------

When you are just starting out, you probably want to develop the
application without exposing it to other people in your project.

The easiest way of doing this is in Rstudio, and will be familiar to you if you
have built shiny apps with Rstudio in the past. To
start, simply create an Rstudio server.

Now we need to write the code for our application. We will use one of the
applications in the R Shiny gallery as an example: `k-means clustering of
the Iris dataset <https://shiny.rstudio.com/gallery/kmeans-example.html>`_.

Let's start by creating a directory ``/project/iris-kmeans`` in the project
workspace, which you can either do using the Rstudio file browser

.. image:: images/rstudio_file_browser.png

or by opening the terminal and running the command::

    $ mkdir -p /project/iris-kmeans

Next create a file called ``app.R`` in ``/project/iris-kmeans``, with the
following contents:

.. code-block:: R

    library(shiny)

    ui <- pageWithSidebar(
      headerPanel('Iris k-means clustering'),
      sidebarPanel(
        selectInput('xcol', 'X Variable', names(iris)),
        selectInput('ycol', 'Y Variable', names(iris),
                    selected=names(iris)[[2]]),
        numericInput('clusters', 'Cluster count', 3,
                     min = 1, max = 9)
      ),
      mainPanel(
        plotOutput('plot1')
      )
    )

    server <- function(input, output, session) {

      # Combine the selected variables into a new data frame
      selectedData <- reactive({
        iris[, c(input$xcol, input$ycol)]
      })

      clusters <- reactive({
        kmeans(selectedData(), input$clusters)
      })

      output$plot1 <- renderPlot({
        palette(c("#E41A1C", "#377EB8", "#4DAF4A", "#984EA3",
          "#FF7F00", "#FFFF33", "#A65628", "#F781BF", "#999999"))

        par(mar = c(5.1, 4.1, 0, 1))
        plot(selectedData(),
             col = clusters()$cluster,
             pch = 20, cex = 3)
        points(clusters()$centers, pch = 4, cex = 4, lwd = 4)
      })

    }

    shinyApp(ui = ui, server = server)

Note that is important that the file be called ``app.R`` for ``shiny-server``
to recognise it.

This code defines an application that will compute k-means clusters of the Iris
data, allowing the user which features to use for the clustering and how many
clusters to use.

To preview your app, simply click on "Run App" in the top right of your code
pane in Rstudio.

.. image:: images/rshiny_run_app_button.png

By clicking on the dropdown arrow to the right of "Run App", you can choose to
preview your app in the Rstudio viewer pane, to open the app in a pop-up
window, or to open the app in your browser. On Faculty the last two are
broadly the same, though if you elect to view in a pop-up window you may need
to configure your browser to allow pop-ups from Faculty.

Deploying the application
-------------------------

You have now developed a great dashboard, and you want to let other
members of your project access it. Faculty supports hosting R Shiny
applications. Head to the `Apps` tab in Faculty, click `New`,
followed by `R Shiny`. You will be prompted to enter a name for your
app.

.. image:: images/rshiny_app_modal.png

Choose a name and click `Create App`. You will then be taken to the `App settings` page.

You will need to make the following changes to the application settings:

 - Change the `APP DIRECTORY` to `/project/iris-kmeans`.

.. thumbnail:: images/rshiny_app_settings.png

Save your application by clicking the `Save` button, then click `Start app`
to actually start your server. After a few seconds, you will
see the status of your app change to `Running`. At this point, a URL
will appear. Select that URL and place it in your browser search bar.
You will be taken to the application! Behind the scenes, Faculty verifies
that you are an observer in the project that the app belongs to.

Sharing your application
------------------------

To share the application with a team member who is an observer in
the project, just give them the URL of the application!

To invite people to your project, go to the Collaborators page, enter their Faculty
username or the email that they used to sign up to Faculty, and assign
them observer status.

.. thumbnail:: images/team_page_with_observer.png