Commit 0c9d12b0 authored by Jean-Karim Heriche's avatar Jean-Karim Heriche

First full featured version with documentation.

parent 371f84b7
# History files
# Session Data files
# Example code in package build process
# Output files from R CMD build
# Output files from R CMD check
# RStudio files
# produced vignettes
# OAuth2 token, see
# knitr and R markdown default cache directories
# Temporary files created by R markdown
# Shiny token, see
# Image Data Explorer
## Image Data Explorer
A R Shiny app for the exploration of image-derived data with the ability to visualize images associated with data points.
### Introduction
Most bioimaging projects derive data from images and regions of interest (ROIs, e.g. segmented objects) on those images. It is desirable, and sometimes necessary, to explore these image-derived data while visualizing the image(s) and ROIs associated with each data point. To address this need, we developed the Image Data Explorer (IDE). The IDE is implemented as a Shiny app (i.e. a web app written in R using the Shiny package).
### Data structure requirements
#### Images
Each image file must contain an image of at most 3 dimensions with the third dimension representing either depth (z coordinate) or time. Images are expected to be organised under one common root directory. For example, if the images are organized like this:
  ▽ screen\_images
      ▽ plate1\_replicate1
          ▽ well001
          ▷ well002
      ▷ plate1\_replicate2
then the image root directory is screen\_images. The IDE can in principle read all image formats supported by BioFromats but has so far only been tested with TIFF, PNG and JPEG.
#### Data points
Image-derived data are expected to be in table format with data points in rows and stored in a tab- or comma-separated plain text file. The table must have column headers with unique column names. To link data points to images, the table should include one column with the path to image files relative to the image root directory and each cell of this column must reference only one file. Using the example above, the image root directory is screen\_images and therefore the table column for data points associated with image W001-P001-Z000-T0000-s1234-Cy3.tif should contain the relative path plate1_replicate1/well001/W001-P001-Z000-T0000-s1234-Cy3.tif. There can be multiple columns with links to images but only two can be used simultaneously in the IDE.
The IDE references ROIs by the coordinates of the ROI centre therefore there should be a column for each of the relevant coordinates: x, y and either z or t. Coordinates (x,y) must be in pixels relative to the top left corner of the image (which is pretty much the standard for image analysis software).
### Using the IDE
#### Requirements
The IDE needs a computer with an [R environment version >=3.5.0]( The IDE requires some R packages and will try to install them if it can't detect them on the system. In case of problems, it may be better to install the required packages manually.
The IDE requires the following packages from CRAN:
DT, shiny, shinyFiles, shinycssloaders, shinydashboard, ggplot2, plotly, RANN.
From within an R console, install with:
> install.packages("DT", "shiny", "shinyFiles", "shinycssloaders", "shinydashboard", "ggplot2", "plotly", "RANN")
and from Bioconductor:
From within an R console, install with:
> install.packages("BiocManager")
> BiocManager::install("RBioFormats")
The IDE also needs a patched version of EBImage. From within R, install with:
> library(devtools)
> install_github("jkh1/EBImage")
Note that this may overwrite a preexisting EBImage installation.
#### Installation
Download the code from the project's repository and run it from a terminal:
> git clone
> Rscript image-data-explorer/image_data_explorer.R
The app is then accessible from a web browser at
Alternatively, open the file image_data_explorer.R with [RStudio]( and click the 'Run App' button.
#### Data input
The IDE opens with the 'Input data' section comprising 4 boxes:
* Input data file
This is where the tabular data is selected and uploaded to the app server. Before uploading a file, make sure that the correct column separator and quote type are selected.
* Plot variables
This allows to select two columns whose values will be shown in a scatterplot.
* Images
If images are associated with the data file, select the image root directory then one or two columns containing the paths to the images relative to the selected root directory. If a column name contains the pattern 'image.*path', this column will be preselected in the image 1field.
* ROIs
If the data table rows correspond to ROIs of associated images, select here the columns containing the coordinates of the ROIs centres.
If the rows correspond to time points only (i.e. with no ROI definition), select only a column for frame coordinates and leave X and Y coordinates empty. If a column name contains the pattern 'coordinate_X|Y|Z|time', it will be preselected in the matching ROI coordinate field (e.g. a column named cell_coordinate_x will be preselected as column for coordinate X).
#### Data exploration
Once the data input section has been completed, data exploration is reached by clicking 'Explore' in the sidebar.
This section is formed of three parts:
* A plot area on the top left of the screen. This shows a scatterplot of the variables selected in the data input section.
Clicking on a data point in the graph selects it in the data table below and opens the corresponding image(s). If the point is associated with x,y coordinates then a red dot is added to the image(s) at the position given by these coordinates.
* An image viewer area next to the plot area. This is where images selected under image 1 in the data input section will appear.
Clicking on the image selects the corresponding row in the data table and highlights the corresponding point in the plot. If rows correspond to ROIs then the click position is indicated by a red dot and the data point corresponding to the closest ROI in the image is selected in both the data table and the plot.
* A data table area at the bottom of the screen. The data table shows the content of the uploaded data file. A tab allows switching to a second image viewer where images selected under image 2 in the data input section will appear. This second image viewer behaves like the one described above. The data table viewer uses pagination to show the data with a default of 10 rows per page which can be changed using the 'Show xx rows' button in the top left corner above the table. Clicking on a table row selects it and highlights the corresponding point in the plot. Multiple selection is possible which is why no image is shown when selecting table rows. The table is searchable globally using the 'Search' box in the top right corner above the table or by column using the boxes atop each column. Searches filter the rows to be displayed in the table. To select all the rows and highlight them in the plot, click the button labeled 'Show filtered rows in plot' above the table. To deselect all selected rows, click the 'Clear selection' button.
This diff is collapsed.
server <- function (input, output) {
data <- reactive({
if (is.null(input$datafile)) return(NULL)
## After the user selects and uploads a data file,
## the content of the data file will be shown.
header = input$header,
sep = input$sep,
quote = input$quote)
settings <- reactive({
if (is.null(input$settings_file)) return(NULL)
## After the user selects and uploads a data file,
## the content of the data file will be shown.
output$content <- renderDT(data(), server = TRUE)
output$Paths <- renderUI({
checkboxGroupInput(inputId = "ImagePaths",
label = "Select Image columns",
choices = names(data()),
selected = getSettings(settings()) )
output$downloadData <- downloadHandler(
filename = function() {
# This function should write data to a file given to it by
# the argument 'file'.
content = function(file) {
save_settings(input$ImagePaths, file)
output$selected_paths = renderPrint({
s = input$ImagePaths
if (length(s)) {
cat('These variables were selected:\n\n')
cat(s, sep = ', ')
ui <- navbarPage("",
## Input: Select a file
fileInput("datafile", "Select data file (in CSV format)",
multiple = FALSE,
accept = c("text/csv",
## Horizontal line
## Input: Checkbox if file has header
checkboxInput("header", "File has header", TRUE),
## Input: Select separator
radioButtons("sep", "Separator",
choices = c(Comma = ",",
Semicolon = ";",
Tab = "\t"),
selected = "\t"),
## Input: Select quotes
radioButtons("quote", "Quote",
choices = c(None = "",
"Double Quote" = '"',
"Single Quote" = "'"),
selected = '"'),
fluidRow(title = 'settings',
fileInput("image", "Select an image file:",
multiple = FALSE,
accept = c('.png','.jpg','.tif','.jpeg')),
downloadButton('downloadData', 'Download'),
fileInput("settings_file", "Select settings json file:",
multiple = FALSE,
accept = c('.json'))
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment