action-transfer.Rmd

# Uploads and downloads {#action-transfer}

```{r, include = FALSE}
source("common.R")
```

Transferring files to and from the user is a common feature of apps. It's most commonly used to upload data for analysis, or download the results either as a dataset or as a report. This chapter shows the UI and server components you'll need to files in and out of your app. 

```{r setup}
library(shiny)
```

## Upload

### UI

The UI needed to support file uploads is simple. Like most other UI components, you just need to supply the `id` and `label` arguments: `fileInput(id, label)`. The `width`, `buttonLabel` and `placeholder` arguments allow you to tweak the appearance in other ways. I won't discuss them further here, but you can read more about them in `?fileInput`.

```{r}
ui <- fluidPage(
  fileInput("file", "Upload a file")
)
```

### Server

Most of the complication arises on the server side because unlike other inputs which return short vectors, `input$file` returns a data frame with four columns:

* `name`: the original file name on the uploader's computer.

* `size`: the file size in bytes. By default, you can only upload files up to
   5 MB is file. You can increase this limit to (e.g.) 10 MB with
   `options(shiny.maxRequestSize = 10 * 1024^2)`

* `type`: the "mime type" of the file. This is a formal specification of the 
  file type, which is usually derived from the extension. It is rarely needed.

* `datapath`: the path to where the path has been uploaded to the server.
  The file is always saved to a temporary directory and given a temporary 
  number. Treat this path as ephemeral: if the user uploads more files, it 
  will go away.

I think the easiest way to get to understand this data structure is to make a simple app. Run the following code and upload a few files to get a sense of what data Shiny is providing. 

```{r}
ui <- fluidPage(
  fileInput("upload", NULL, buttonLabel = "Upload...", multiple = TRUE),
  tableOutput("files")
)
server <- function(input, output, session) {
  output$files <- renderTable(input$upload)
}
```

Note my use of the `label` and `buttonLabel` arguments to mildly customise the appearance, and use of `multiple = TRUE` to allow the user to upload multiple files. 
### Uploading data

If the user is uploading a dataset, there are three details that you need to be aware of:

* `input$file` is initialised to  `NULL` on page load, and so you'll need
  `req(input$file)` to make sure your reactive code waits until the first file 
  is uploaded.
  
* The `accept` argument allows you to limit the possible inputs. The easiest 
  way is to supply a character vector of file extensions, like 
  `accept = ".csv"`. (You can also use mime types, see `?fileInput` for more
  details.)
  
* The `accept` argument is only a suggestion to the browser, and is not always
  enforced, so you should also use `validate()` to check the 
  extension[^extensions] in your server function.

[^extensions]: Note that the browser defintion of an extension is different to the definiton used by the browser - the browser uses `.csv` where `file_ext()` returns `.csv`.

Putting all these ideas together gives us the following app where you can upload a `.csv` file and see the first few rows:

```{r}
ui <- fluidPage(
  fileInput("file", NULL, accept = ".csv"),
  tableOutput("head")
)

server <- function(input, output, session) {
  data <- reactive({
    req(input$file)
    ext <- tools::file_ext(input$file$filename)
    validate(need(ext == "csv", "Please upload a CSV file"))
    
    vroom::vroom(input$file$datapath, delim = ",")
  })
  
  output$head <- renderTable({
    head(data(), 5)
  })
}
```

Note that since `multiple = FALSE` (the default), `input$file` is a single row data frame, and `input$file$filename` is a length-1 character vector. 

## Download

### UI

Again, the UI is straightforward: use either `downloadButton(id)` or `downloadLink(id)` to give the user something to click to download a file. They do have o ther arguments, but you'll hardly ever need them; see `?downloadButton` for the details.

```{r}
ui <- fluidPage(
  downloadButton("download1"),
  downloadLink("download2")
)
```

Classes: <http://bootstrapdocs.com/v3.3.6/docs/css/#buttons>

### Server

The server side of downloads is different to the other ouputs as you don't use a render function. Instead, you use `downloadHandler()`, which takes two arguments:

*   `filename` is a function with no arguments that returns a single string 
    giving the name of the file. This is the string that will appear in
    the download dialog box. If the file name is constant (i.e. it doesn't
    depend on anything else in the app), you can skip the function and just set 
    it to a string.

*   `content` is a function with a single argument, `file`, which is the path
    where your should place the file to be downloaded. The return argument of 
    this function is ignored; it's called purely for its side-effect of creating 
    a file at the given path.

For example, if you wanted to provide a `.csv` file, your server function might contain a snippet like this:

```{r, eval = FALSE}
output$download <- downloadHandler(
  filename = function() {
    paste0(input$dataset, ".csv")
  },
  content = function(file) {
    write.csv(data(), file)
  }
)
```

### Downloading data

The following app shows off the basics by creating an app that lets you download any dataset in the datasets package as a tsv[^tsv-csv] file.

```{r}
ui <- fluidPage(
  selectInput("dataset", "Pick a dataset", ls("package:datasets")),
  tableOutput("preview"),
  downloadButton("download", "Download .tsv")
)

server <- function(input, output, session) {
  data <- reactive({
    get(input$dataset, "package:datasets")
  })
  
  output$preview <- renderTable({
    head(data())
  })
    
  output$download <- downloadHandler(
    filename = function() {
      paste0(input$dataset, ".tsv")
    },
    content = function(file) {
      vroom::vroom_write(data(), file)
    }
  )
}
```

[^tsv-csv]: `.tsv` file is to be preferred over a `.csv` because many European countries use commas to separate the whole and fractional parts of a number (e.g. `1,23` not `1.23`). This means they can't use commas to separate fields and instead use semi-colons. It's best to just side-step this issue together, and instead just use tab separatea files.

### Downloading reports

Another common use of downloads is to prepare a report that summarises the result of interactive exploration in the Shiny app. One powerful way to generate such a report is with a parameterised RMarkdown document,  <https://bookdown.org/yihui/rmarkdown/parameterized-reports.html>. A parameterised RMarkdown file has a `params` field in the YAML metadata:

```yaml
title: My Document
output: html_document
params:
  year: 2018
  region: Europe
  printcode: TRUE
  data: file.csv
```

Inside the document you can refer to those values with `params$year`, `params$region` etc. 

What makes this technique powerful is you can also set the parameters using code, by calling `rmarkdown::render()` with the `params` argument. This makes it possible to generate a range of RMarkdown reports from a single app.

Here's a simple example taken from <https://shiny.rstudio.com/articles/generating-reports.html>, which describes this technique in more detail.

```{r}
ui <- fluidPage(
  sliderInput("n", "Number of points", 1, 100, 50),
  downloadButton("report", "Generate report")
)

server <- function(input, output, session) {
  output$report <- downloadHandler(
    filename = "report.html",
    content = function(file) {
      params <- list(n = input$n)

      rmarkdown::render("report.Rmd", 
        output_file = file,
        params = params,
        envir = new.env(parent = globalenv())
      )
    }
  )
}
```

If you want to produce other output formats, just change the output format in the `.Rmd`, and make sure to update the extension.

There are a few other tricks worth knowing about:

*   If the report takes some time to generate, use one of the techniques from
    Chapter \@ref(action-feedback) to let the user know that your app is 
    working.

*   Often, when deploying the app, you can't write to the working directory,
    which RMarkdown will attempt to do. You can work around this by copying
    the report to a temporary directory:

    ```{r}
    report_path <- tempfile(fileext = ".Rmd")
    file.copy("report.Rmd", report_path, overwrite = TRUE)
    ```

    Then replaaing `"report.Rmd"` in the call to `rmarkdown::render()` with
    `report_path`.

*   By default, RMarkdown will render the report in the current process, which
    means that it will inherit many settings from the Shiny app (like loaded 
    packages, options, etc). For greater robustness, I recommend running in
    fresh R session by using the callr package. 
    
    ```{r, eval = FALSE}
    render_report <- function(input, output, params) {
      rmarkdown::render(input,
        output_file = output,
        params = params,
        envir = new.env(parent = globalenv())
      )
    }
    
    server <- function(input, output) {
      output$report <- downloadHandler(
        filename = "report.html",
        content = function(file) {
          params <- list(n = input$slider)
          callr::r(
            render_report,
            list(input = report_path, output = file, params = params)
          )
        }
      )
    }
    ```

You can see all these pieces put together in `rmarkdown-report/`.

Later, in Chapter XYZ, we'll come back to generating a complete report of all the code that your app has executed. 

## Case study

We'll put all the pieces together in a small case study where we upload a file (with user supplied separator), preview it, perform some optional transformations using the [janitor package](http://sfirke.github.io/janitor), by Sam Firke, and then let the user download it as a `.tsv`. 

To make it easier to understand how to use the app, I've used `sidebarLayout()` to divide the app into three main steps:

1. Uploading and parsing the file.
2. Cleaning the file.
3. Downloading the file.

```{r}
ui <- fluidPage(
  sidebarLayout(
    sidebarPanel(
      fileInput("file", "Data", buttonLabel = "Upload..."),
      textInput("delim", "Delimiter (leave blank to guess)", ""),
      numericInput("skip", "Rows to skip", 0, min = 0)
    ),
    mainPanel(
      h2("Raw data"),
      tableOutput("preview1")
    )
  ),
  sidebarLayout(
    sidebarPanel(
      checkboxInput("snake", "Rename columns to snake case?"),
      checkboxInput("constant", "Remove constant columns?"),
      checkboxInput("empty", "Remove empty cols?")
    ),
    mainPanel(
      h2("Cleaner data"),
      tableOutput("preview2")
    )
  ),
  fluidRow(
    column(width = 4, downloadButton("download", class = "btn-block"))
  )
)
```

And this same organisation makes it easier to understand the app:

```{r}
server <- function(input, output, session) {
  raw <- reactive({
    req(input$file)
    delim <- if (input$delim == "") NULL else input$delim
    vroom::vroom(input$file$datapath, delim = delim, skip = input$skip)
  })
  output$preview1 <- renderTable(raw())
  
  tidied <- reactive({
    out <- raw()
    if (input$snake) {
      names(out) <- janitor::make_clean_names(names(out))
    }
    if (input$empty) {
      out <- janitor::remove_empty(out, "cols")
    }
    if (input$constant) {
      out <- janitor::remove_constant(out)
    }
    
    out
  })
  output$preview2 <- renderTable(tidied())
  
  output$download <- downloadHandler(
    filename = function() {
      paste0(tools::file_path_sans_ext(input$file$name), ".tsv")
    },
    content = function(file) {
      vroom::vroom_write(tidied(), file)
    }
  )
}
```

### Exercises