1 Introduction to TissueMiner

# This is a comment: the code below will print "Welcome to TissueMiner"
print("Welcome to TissueMiner")
## [1] "Welcome to TissueMiner"

1.1 Prepare the movie data

1.1.1 First, organize your movie images as follows

  • Create a movie_repository folder where you store the data from all your movies
    • Inside this folder, create one movie folder per movie
      • inside each movie folder, create a Segmentation folder to store movie images
        • the movie should be stored as a series of tif or png files, one per timepoint, with the name of each file composed of a sample name + underscore + frame number

The data organization is summarized as follow:

<movie_repository>/<movie_directory>/Segmentation/<movie_directory_name>_%03d.png

where %03d represents a frame number padded with 3 digits. The number of digits can be modified, see FAQ.

Here, is an example: movieSegmentation/demo/Segmentation/demo_000.png

alt tag

alt tag

  • The image type should be 8-bit or RGB.
  • The image format should be png or tiff

1.1.2 Segment and track cells using TissueAnalyzer

Tissue Analyzer (copyright Aigouy 2016) ships with its own licence (see license_TA.txt bundled in the software). Tissue Analyzer should not be modified or reverse engineered. Tissue Analyzer should always be distributed bundled with TissueMiner and not alone.

You can install the latest version of Tissue Analyzer (formerly known as Packing Analyzer) within FIJI (http://fiji.sc/Fiji). To do so:

  • get a fresh FIJI installation (including JDK8)
  • launch FIJI
  • open the “Help” menu
  • click on “Update…”
  • click on “Manage update sites”
  • click on “Add” and enter “http://sites.imagej.net/TA/” in the URL field (and anything you like in the “Name” field)
  • click “Close” and FIJI should offer you to install TA.

Once the installation is complete, restart FIJI, open the “Plugins” menu and click on “Tissue Analyzer”

For a quick start guide, click here

1.1.3 Optionally, define regions of interest (ROI’s) and orient the tissue along the x or y axis

To this purpose, we provide two FIJI programs draw_n_get_ROIcoord.ijm and orient_tissue.ijm.

1.1.3.1 Define ROI’s:

  • launch FIJI
  • go to the fiji_macros folder located in your TissueMiner installation folder
  • drag-and-drop the draw_n_get_ROIcoord.ijm file into FIJI
  • a script editor opens automatically
  • click RUN and define your ROI’s

By default, TissueMiner always creates two ROI’s:

  • “raw”: corresponds to all segmented and tracked cells
  • “whole_tissue”: corresponds to cell lineages that remain in the field of view

1.1.3.2 Orient the tissue

  • launch FIJI
  • go to the fiji_macros folder located in your TissueMiner installation folder
  • drap-and-drop the orient_tissue.ijm file into FIJI
  • a script editor opens automatically
  • click RUN and define the tissue axis to be aligned on x or y.

Both programs automatically save a text file (UserFrameRoi.txt and transformation.txt, respectively). If these files are present, TissueMiner will take them into account for further precessing steps.

1.2 TissueMiner “snakemake” automated workflow

The snakemake automated workflow performs computationally intensive tasks. It constitutes an important part of TissueMiner as it creates the relational database, which stores information about cell geometry, cell topology and cell history for a given movie. This workflow also browses cell lineages to assign cells to regions of interest (ROI’s), and it calculates cellular contributions to tissue deformation in each ROI. Finally, it can also create videos of patterned cell behaviors.

Running time estimate on a single core (2,7 GHz Intel Core i5; 2Gb of RAM) for the provided samples:

dataset size (Gb) cell junction number cell contour number cell lineage number ROI number run time
demo 0.1 ~200000 ~68000 ~1200 3 2min48sec
WT_3 2.1 ~1450000 ~487000 ~8600 6 17min00sec
WT_1 2.5 ~1610000 ~540000 ~9400 6 18min03sec

Running times on multicore computers would significantly be reduced.

1.2.1 What are the data generated by the “snakemake” automated workflow ?

  • Here is a list of important files that are generated by the automated workflow
    • The database: (<movie_name>.sqlite)
    • An extra table (cellshapes.RData) to represent cell contours by using anticlockwisely ordered cell vertices
    • An extra table (./roi_bt/lgRoiSmoothed.RData) to store cells in user-defined regions of interest
    • An extra table (./topochanges/t1DataFilt.RData) to store cell neighbor changes
    • An extra table (./shear_contrib/triangles.RData) to store triangles
    • Extra tables (./shear_contrib/<ROI_name>/avgDeformTensorsWide.RData) to store the calculated pure shear deformation of triangles and tissue for each region of interest

1.2.2 Select specific rules to run part of the “snakemake” automated workflow

  • A graph represents the order and the relations between rules (tasks) to be run. You can see such a graph in Figure 7 of the resource paper.
  • Command to run the complete workflow including video creation: sm all
  • Command to see all non-processed rules: sm -n
  • Command to build the database only: sm make_db
  • Command to generate the necessary data for exploiting the TissueMiner API: sm shear_calculate topo_countt1 polygon_class tri_categorize
  • Using docker, all of these commands must be used right after the docker command that we store in the tm alias for simplicity. Example:
    • alias tm='docker run --rm -ti -v $(dirname $PWD):/movies -w /movies/$(basename $PWD) etournay/tissue_miner'
    • tm sm shear_calculate topo_countt1 polygon_class tri_categorize

1.2.3 Strengths

  • The snakemake automated workflow (sm command) builds the database and generates additional data about cell lineages, cell topology, cell geometry, and cell contributions to tissue deformation.
  • You can run the workflow step by step by mean of “rules” that we defined in the snakemake configuration file. Based on this configuration file, the snakemake engine checks if all necessary inputs are present before running a given step. If inputs are missing the snakemake engine runs the missing steps automatically.

1.2.4 Limitation

  • Data manipulation and visualization strategies shouldn’t be modified within this workflow to avoid breaking the workflow.

1.2.5 To overcome this limitation: a TissueMiner API

  • This present User Manual guides the user through the Application programming interface (API) that we developed in TissueMiner to customize data visualization.

1.3 TissueMiner API installation and configuration

1.3.1 Requirements

On Ubuntu and even on MacOSX, the dockerized TissueMiner isn’t necessary for running the API because the dependencies can be installed directly on the computer.

On Ubuntu (docker is NOT necessary): you may install Rstudio or another integrated environment for R programming. The TissueMiner API has already been installed and configured during the installation procedure of TissueMiner.


On MacOS (docker is NOT necessary): we provide a TissueMiner API installer/updater that includes an Rstudio installation if not yet present. Run this in a simple Terminal:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew update
brew install git
export TM_HOME="${HOME}/tissue_miner"
git clone https://github.com/mpicbg-scicomp/tissue_miner.git ${TM_HOME}
${TM_HOME}/installation/osx/install_tm_api.sh

On any systems with the Docker toolbox: you can use the Rstudio server from the provided docker image that includes all necessary R packages.

  • open a Docker QuickStart Terminal and start the RStudio server: edit the following command with the appropriate path (run it only once please !)
# First, define the path to the movie repository. 
# Ex: replace /media/fileserver/movie_repository by the path to your movie repository

docker run -d -p 8787:8787 -e USER=rstudio -e PASSWORD=rstudio \
-v /media/fileserver/movie_repository:/home/rstudio/movie_repository \
etournay/tissue_miner
  • get the URL to reach the Rstudio server (run it each time you need to get the URL, or better bookmark the web page in your web browser)
echo "http://$(docker-machine ip default):8787"
  • copy and paste the resulting URL onto a web browser: login: rstudio, password: rstudio

  • now, you can enjoy R programming in the RStudio server !

  • to stop the Rstudio server, open the Docker QuickStart Terminal and follow these steps sequentially:

docker ps

output example:

# In this example, I stop the RStudio server by running 
docker stop 171906d9e728 # where the last argument is the CONTAINER ID that is just displayed above

  • mount other folders into the dockerized TissueMiner using the -v option (make sure that the dockerized Rstudio server isn’t already running by using docker ps). Example:
# First, define the path to the movie repository (ex: /media/fileserver/movie_repository)
# Second, define the path to your own R scripts (ex: $HOME/my_R_scripts)
# Third, you may also define the path to your entire home folder (ex: $HOME)

docker run -d -p 8787:8787 -e USER=rstudio -e PASSWORD=rstudio \
-v /media/fileserver/movie_repository:/home/rstudio/movie_repository \
-v $HOME/my_R_scripts:/home/rstudio/scripts \
-v $HOME:/home/rstudio/home_share \
etournay/tissue_miner

1.3.2 TissueMiner configuration

— We provide two configuration files to set up the global TissueMiner environment: default_config.R and flywing_tm_config.R:

  • define graphics theme
  • define a common color scheme for known quantities. Ex: color of shear curves
  • define time offsets for comparing multiple movies in time, using the algnModel variable
  • define a time offset to display the developmental time. Ex: 54000 seconds for 16 hAPF
  • define default parameters. Ex: movie grid size, default ROI name, …

— Configure Rstudio when used without Docker:

  • set up the path to the TissueMiner API scripts ( Ubuntu, Linux and MacOS)
echo "TM_HOME=~/tissue_miner" >> ~/.Renviron
  • set up the path to the configuration file to run examples of the present User Manual
echo "TM_CONFIG=~/tissue_miner/config/flywing_tm_config.R" >> ~/.Renviron
echo "TM_CONFIG=~/tissue_miner/config/default_config.R" >> ~/.Renviron
  • or you may create your own configuration file
# Here provide the path to your configuration file
echo "TM_CONFIG=path_to_my_config_file" >> ~/.Renviron
  • edit your .Renviron file: in Rstudio, click on the “Files” panel (right side), then click the “Home” panel and finally click the .Renviron file that you can now edit in Rstudio.

— Configure the dockerized RStudio:

  • in this context, the .Renviron file cannot be modified permanently: we use an alternative method described below.
  • the TM_HOME variable is already set up to take into account the dockerized TissueMiner scripts.
  • the TM_CONFIG variable is set up by default to use the default_config.R of the dockerized TissueMiner.
  • you can transiently overwrite these variables by using a dedicated R command Sys.setenv() that you should always add at the begining of your scripts. Examples:
# Example 1: home_share is the mount point to access your data (see above)
Sys.setenv(TM_CONFIG="/home/rstudio/data/tm_config/my_favorite_config.R")

# Example 2: assuming that the user has cloned the TM git repository in his home folder 
Sys.setenv(TM_HOME="/home/rstudio/data/tissue_miner/")

1.3.3 Header of all your scripts: load the TissueMiner API in R (Rstudio)

  • We assume you already have downloaded the example data
  • Please modify the paths (first code block below) according to the data location
  • Always execute the two blocks below before running any analysis: this will load all the necessary functions in the memory of the computer.

Please, do not forget to edit the path below to set up your data location in the movieDbBaseDir variable !

# Define path to all processed movies: MUST BE EDITED BY THE USER
movieDbBaseDir="/home/rstudio/data/example_data"

# Define path a particular time-lapse called "demo"
movieDir <- file.path(movieDbBaseDir, c("demo"))

# Define a working directory where to save the analysis
outDataBaseDir=file.path(movieDir, "output_analysis")

# Set up path to the TissueMiner code
# This command requires that the global environment TM_HOME is defined in the .bash_profile
scriptsDir=Sys.getenv("TM_HOME")

# Load TissueMiner libraries
source(file.path(scriptsDir, "commons/TMCommons.R"))
source(file.path(scriptsDir, "commons/BaseQueryFunctions.R"))
source(file.path(scriptsDir, "commons/TimeFunctions.R"))

# Overwrite any default configuration for running the examples of the User Manual
source(file.path(scriptsDir, "config/flywing_tm_config.R"))

# Set up working directory
mcdir(outDataBaseDir)

  • TissueMiner extends the existing grammars in R for visualizing and quantifying cell dynamics in 2D-living tissues:
Functions Description Project
print_head head the current table with the row number TissueMiner
dt.merge fast merging of two dataframes, possibility to suffix column names TissueMiner
openMovieDb open a connection to a movie database TissueMiner
multi_db_query aggregate data into one dataframe TissueMiner
coarseGrid assign grid elements to cell positions TissueMiner
smooth_tissue average quantities in time using a moving window TissueMiner
align_movie_start align movies at earliest common developmental time TissueMiner
chunk_time_into_intervals undersample time for local time averaging TissueMiner
synchronize_frames find closest frame to user-defined time intervals TissueMiner
mqf_* functions set of multi-query functions to quantify cell dynamics TissueMiner

The mqf functions constitute an important part of the TissueMiner API. They will be discribed thereafter.


1.4 How to query a relational database ?

1.4.1 Open a connection to the database

  • We use openMovieDb provided with the TissueMiner API
# Connection to the DB stored in the "db" variable
db <- openMovieDb(movieDir)
# Close the connection
dbDisconnect(db)

Please, keep the connection open to run the tutorial !


1.4.2 Example: overlay cells and vertices on the image

We can now overlay cells and vertices on the movie image. To do so, we built a dedicated render_frame() function that loads the specified frame of the time-lapse. This function takes the cell contour table and a desired frame as input variables. The render_frame() function alone returns the first layers of the graph that consists of a raster image of the wing and additional specifications such as the Y-axis flipping - scale_y_continuous(trans = “reverse”) - and the iso-scaling of the X and Y axes - coord_equal(). Additional options are appended using the + sign.

# Load the definitions of cell contours (calculated with the automated workflow `tm sm make_db`)
cellshapes <- locload(file.path(movieDir, "cellshapes.RData")) %>% print_head()
## Source: local data frame [6 x 5]
## 
##   frame cell_id x_pos y_pos bond_order
##   (int)   (int) (dbl) (dbl)      (dbl)
## 1     0   10001   193   195          1
## 2     0   10001   189   199          2
## 3     0   10001   206   212          3
## 4     0   10001   229   206          4
## 5     0   10001   219   192          5
## 6     0   10001   217   190          6
## [1] 219714
# Plot cells and vertices on the original image
cellshapes %>%
  
  # add overlay image (! connection to DB required !):
  render_frame(50) +
  
  # add a geometrical layer to represent cells as polygons
  geom_polygon(aes(x_pos, y_pos, group=cell_id), color="green",fill=NA, size=0.2) +
  
  # add a geometrical layer to represent vertices as points
  geom_point(aes(x_pos, y_pos),color="red", size=0.4) +
  
  # add a title to the graph
  ggtitle("Cells and vertices overlaid on the image")