- First of all, you have to install R, see this page.
- We recommend RStudio as a GUI for R RStudio it is convenient, useful and easy to use.
- When you installed Tango, if R was already installed before, the RTango install script has been executed so you don't need anything more to install.
- If you installed R after installing Tango, then you'll have to run the script again, for that just run ImageJ or Fiji with Tango, and then in the Tango menu choose "Install RTango". That's it.
- If You want to install RTango without Tango, you can, you just have to download the script and run it.
First RTango session
Create a new RTango session
library('rtango') # This will load rtango package into the R session session = tangoSession$new() session$initFields() # This will create a new RTango session
Connect your R session to Tango databaseFirst of all, RTango is a R client for MongoDB Tango database so you need to find the Tango server. Two different cases here :
- If you did install Tango and ImageJ on the same computer you're using, you have to use :
session$addConnection() # This will connect your R Session to Tango database
- If you installed Tango and ImageJ on another computer on the same network, you have to find its hostname (DNS hostname) or its IP address.
- If your computer is called "tango" on the network, use :
session$addConnection(host='tango') # This will connect your R session to Tango database
- If your computer has the IP address 192.168.1.2, use :
session$addConnection(host='192.168.1.2') # This will connect your R session to Tango database
R should display on the screen all the projects it will find in the database.
 "tango_Johnny_SeriousStuff" "tango_jean_GM06_Immuno" "tango_jean_ImmunoFishGM06990" "tango_jean_GM12878_FISH3D"  "tango_jean_GM06990_ImmunoFISH" "tango_jean_CycleGM06_2" "tango_Franz_FL120828-FISH3D" "tango_jean_GM12878_global_org"  "tango_jean_CycleGM06" "tango_jean_FL121108_GMFISH" "tango_jean_ImmunoMES" "tango_jean_MEF_HS"  "tango_jean_JO121127_MOPFIXGM06990" "tango_Franz_Test1"
Note that the names all have a suffix, thus have this form tango_username_projectName. This is the complete name of the project that rTango uses.
Following code gives informations about experiments in the "firstProject" :
session$listExperiments(projectName="tango_johnny_firstProject")  "firstExperiment" # if you use a remote mongoDB server session$listExperiments(projectName="tango_johnny_firstProject",connectionName="192.168.1.2")  "firstExperiment"
Add an experiment to your sessionIf you followed the Getting Started guide, you already have one project and one experiment in your database, so let's retrieve data by doing this (don't forget to change project name, username and experiment name if chose different ones):
session$addExperiment( projectName='tango_johnny_firstProject', experimentName='firstExperiment' )
Don't forget to mention the host in case you chose another computer for Tango and ImageJ for example:
session$addExperiment( host='192.168.1.2', projectName='tango_johnny_firstProject', experimentName='firstExperiment' )
Now we shall focus on the experiment. Execute the command below after replacing all the names:
exp = session$workspaces$default$localhost$tango_johnny_firstProject$firstExperiment
$worspaces doesn't have to be changed, ever.
$default is the name of the default workspace of your session.
$localhost is the name of the computer where you put the database, and probably also Tango and ImageJ.
$tango_johnny_firstProject is the name of the project, you may have to change it.
$firstExperiment is the name of your experiment in tango interface.
Once it's done you should see an object of type experiment in RStudio data browser.
Data ExtractionMeasurement are stored in the database, and can be retrieved directly from R as dataframe objects.
Each measurement is associated to a name (that can be edited in TANGO) and one or several structures.
Name and associated structures of a measurement can be seen in the interface of TANGO, either in the edit experiment tab or in the data browsing tab. See the tutorial for more informations.
There are two main commands to extract data from the database, they can extract several measurements of the same kind at once.
Extract Object DataThese data corresponds to measurement performed on a single object of a segmented structure (1 value per object), such as the volume of an object. Thus they can be indexed by the index of the object when the parameter addIdx=TRUE
This code will extract the volume_unit and the compacity of all objects found in the structure of index 0(it is always the nucleus in Tango), and build the following dataframe :
Extract Structure DataThese data corresponds to measurement performed between several structures.
A specific case is measurement between two objects of two structures (such as distance). In this case only, dataframe can be indexed by the index of the each of objects (2 indexes) when the parameter addIdx is set to true; Make sure you extract only this kind of measurements at once when addIdx is set to TRUE.
The other kind of measurement can be arrays of undefined length, so one have to make sure they all have the same length, or extract only one per dataframe.
This code will retrieve distBB (border to border distance) and distCC (center to center distance) measurements between objects of structure CenpA and objects of structure C23.
On this snapshot, we can see that :
- The distance between the 1st object border in CenpA structure and the 2nd object border in C23 structure is 4.33274838
- The distance between the 3rd object center in CenpA structure and the 2nd object center in C23 structure is 3.7281815
Play with SelectionsWhen analysing data with R, it can be useful to visualize (or process) the underlying images.
To make a link between data in R and images, we introduced Selections, that can be generated from R and used in TANGO, or edited in TANGO and used in R.
Selection can represent a subset of the nuclei of an experiment, or the objects contained in nuclei.
Selections from R to TANGOLet's start by creating a subset of our objects:
Try this command :
dataframe3=subset(dataframe2,subset=distBB<0.1) # defines a sub-population of objects by a criterion selection1=exp$extractSelection(dataframe3) # creates a selection selection1$save() #records it so that it can be seen in tango.
Now look at dataframe3. The R subset function has filtered rows so only those where distBB is less than 0.1 will remain.
By default, the save command will generate a selection named "currentSelection" in TANGO and override it if existing.
A name can be specified, and if override is set to false, it will create a unique name.
Now look at the results in Tango, in the data tab, by clicking on the >Selections> button.
Only nuclei contained in the selected Fields are displayed in the list.
Selections from TANGO to RA selection created or edited in TANGO can be retrieved in R:
selections = exp$selections #returns a list of all the selections, indexes by their name curSel = selections[["currentSelection"]] #takes only one selection nuc.list = curSel$getFilter() #extracts the list of selected nuclei # this list can be used to created a subset of a data.frame for instance (providing the data.frame "df" has a column names "nucleus.id"): df.subset = df[df$nucleus.id%in%nuc.list, ]
Install AcinonyxRefer to this page.
See also the Acinonyx documentation here.
Generate an interactive plotIn this simple example, we will generate an histogram of eroded volume fraction of centromeres, as generated in the tutorial
#Extracting data from database: df1 = exp$extractObjectData(1, keys=c("volume_unit", "CenpA_average", "CenpA_integratedDensity", "evf"), addIdx=TRUE) #generate interactive histogram of evf library("Acinonyx") ihist(df1$evf)
Acinonyx uses a java virtual machine, so when displaying many plots you might get the error: java.lang.OutOfMemoryError: Java heap space
In this case:
The -Xmx flag to increase the heap size (and -Xms to increase the stack size)
The solution is to supply this -Xmx parameter before the Java Virtual Machine is initialized. From the R shell, invoke this:
options( java.parameters = "-Xmx4g" )
Select a subset of the population and record the selection
# get the index of the interactively selected objects. Each one corresponds to a line in the dataframe df1 and to a single centromere sel = iset.selected() # convert to a tango selection: df1.subset=df1[sel,] # generated a dataframe with only the selected lines sel1 = exp$extractSelection(df1.subset) # converts the dataframe into a selection sel1$save() #saves the selection under the name "currentSelection" and override it if existing.
A selection names "currentSelection" will appear in the selection list, containing only the selected centromeres.
R contains flow-cytometry packages, that provides many functions for processing and visualizing flow-cytometry data.
Many of those functionalities are relevant for image-cytometry analysis. Thus we developed a small package in order to ensure compatibility with those tools.
In this section we provide an example using iFLow, a GUI based visualization for flow cytometry.
Install iFlow :
source("http://bioconductor.org/biocLite.R") > biocLite("iFlow")
Install rtango.flow package
- download rtango.flow package and save it.
- install the package in R
> install.packages('/path/to/your/download/rtango.flow_1.0.tar.gz', repos = NULL)
Don't forget to replace /path/to/your/download with the real path to the file you just download.
Import data to iFlowflowCore and iFLow use a different format of data, thus dataframes generated by rtango have to be converted:
library(rtango.flow) workFlow = tangoWorkFlow$new(dataframes=list(A=dataframe1,B=dataframe2,C=dataframe3)) iFlow()
When the iFlow interface shows up, choose the File Menu and "Load" and select "tangoFlowSet".
Please read the docs for making filters on the data coming from tango.
Export selection to TANGOiFlow allows one to create gates in order to select a sub-population of the data.
Our package allows one to retrieve the sub-populations and visualize the corresponding images in TANGO.
Now look back in tango interface, you should see selections there.