Getting connected

Introduction

Welcome to the Tango Getting Started Tutorial.
This tutorial is a complete example of an Image analysis procedure, in which we provide sample image and adapted processing chains.
If you have any problem, please contact us

Installation

Install TANGO

1. Go to the download page
2. Make sure your computer meets the requirements
3. Follow the instruction to install TANGO and configure MongoDB
4. Increase the default memory to about 2000Mb (in ImageJ: menu Edit/Options/Memory & Threads), depending on the image size you wish to analyse (at least 2 times the size)

Connect to the Database

1. If mongoDB is running on your computer, leave the Host field to the default value (localhost), otherwise write the DNS or the IP adress of the server that runs the database.

• Click the "Connect" button

• Then you can add a user in the database by clicking on the "Add user" button and then type your username in the prompt, or select an existing user.

Documentation

TANGO has an integrated documentation. To access it, click on "Help!" on the "Connect" tab. A window will open, click on "Update". The documentation will be retrieved from the web. The helper displays 3 types of information:

1. When mousing over a button of the interface, the corresponding documentation will be displayed.
2. When mousing over the title of a plug-in, information on the plug-in (how it works, acknowledgements...).
3. When mousing over a the name of a parameter of a plug-in, information on the parameter (to help tuning it).

Using TANGO

First Experiment

In TANGO, an experiment is a set of images containing data that will be processed and analyzed the same way.
First of all we have to define the so-called experiment.

1. Click on the "Edit Experiment" tab.
2. Create a new project by clicking New (No white space , no special char ).
3. Then let's create our first new experiment by clicking the "New" button just below, and again, you know...

Channel Images

• The first Step is defining the input data. In TANGO, input images are called Channel Images. A Channel Image corresponds to an image stack acquired with a particular wavelength (thus corresponds to a particular labelled cellular structure).
• All acquisition fields of a given experiment must have the same number of channel images in the same order.
• The input data of the experiment we just created has 3 channels images, so that we have to click 3 times on the "add" button
• For each Channel Image click on the "edit button. Here we will only edit the "keyword" field, that we be useful to identify the Channel Images (depending on the import method, it can have other means, see the internal documentation ("helper") for further details)

We won't add any pre-filters but you can choose filters and adjust parameters very easily. Those filters are applied on the whole images prior to the cropping step, they are useful for chromatic shift correction for instance (unsing Translate 3D)
See the developer manual to add your own filters to the list.

Structures

• Structures correspond to a biological compartment of interest (contained in the nucleus).
• One Structure is associated to one Channel Image. Structures can be different from channel images, because for instance two different processes applied on a same channel image can extract different structures (in mouse cells, DAPI staining can be used to extract nuclei and the bright spots (chromocenter) contained in the nuclei, so there will be two structures (Nucleus & Chromocenters) associated to the same channel image (DAPI)).
• In this example, there are 3 Structures. To define them, click on the structure tab and click 3 times on the "add" button.
• For each Structure, click on the "edit" button, and define
  • the name of the structure
  • the associated Channel Image
  • optionally, the display colour and 3D display settings

IMPORTANT! Don't forget to click on "Save Changes" when you're done editing channels and structures.

Import Images

• Download the Sample images provided with this tutorial. Unzip the "tangoSampleImage.zvi" file.
• Select the scale option: if "use global scale" is not selected, the scale contained in the metadata of each image will be used. Otherwise, it is possible to enter manually the scale of the image, but it has to be the same for every image of the experiment.
• Select the import file method: choose "BIOFORMAT-LOCI" in this case. For further information see the internal documentation on import (helper).
• Click on the "Import Images" button and select the downloaded "tangoSampleImage.zvi" file. It is possible to select several file, or a folder containing files (it will be recursively scanned for files in sub-folders)

Import process can take a long time because images are copied into the database.

Processing Chains

We term Processing Chain a set of elementary operations applied to a grayscale image to segment the structures it contains.
Defining a Processing Chain can be a complex task that requires a certain knowledge in image processing.
For this tutorial, we will import preset processing chains, as templates.

• Download the sample processing chains and save the file to yous disk. Unzip it.
• WARNING: since the version 0.87, use these Processing Chains. If you had already imported the old processing chains, either create a new user of delete previous processing chain templates in TANGO (Processing Chains tab / Template sub-tab).
• Select the "connect" tab, click on "Import Processing Chains", and select the unzipped folder "processingChain"

• Select the "edit processing chain tab"
• For each structure that need to be segmented, select the corresponding template processing chain, and click on the "copy from template" button.

• Click on the "Save" button

Processing and Data browsing

The interface of TANGO provide access to the different hierachical level of studied objects: fields that contain nuclei that contain structures that can contain objects.
Those objects are represented in lists.

• To select an object, simply click on the element of the list.
• To add an object to the selection, ctrl + click
• To select an interval: shfit + click
• To unselect an object: ctrl + clik on a selected object

Field Browsing

Select the "Data" tab.
The first list on the left contains all the acquisition Fields.
It is possible to display the images they contain, by clicking on "Overlay" or "Input Image" in the "View" section.

Nucleus Processing

To automatically process nuclei, Run the following steps:

• nuclei processing (to segment nuclei).
• cropping of image for each segmented nucleus.
• structures processing (to segment structures) for each nucleus.

To do so:

• Select the fields to be processed
• Select the 3 actions (checkboxes)
• Click on the "Run" button

In case nuclei are close together and can't be automatically separated, a semi-automatic procedure is possible, that will be soon described here.

Nucleus Browsing

Once the process is done, it is possible to browse the cells detected in the acquisition field, by clicking on the ">Cells>" button. It will display a second panel, with two lists:

• the top list contains all the nuclei contained in the selected fields (indicated as "1" on the screenshot).
• the bottom list contains all the structures contained in the first selected nucleus (indicated as "2" on the screenshot)

There is a tag system that allows you to create categories of cells. Simply select the cells you want to tag, and choose a tag in the "tag" choice. This will display the cells in the list with the colour of the tag.
If the tag "-1" is set, the corresponding cells will be ignored from all process and quantification steps.
Tags can be retrieved along with quantifications.

Usually thumbnails allow to rapidly find badly segmented nuclei (nuclei touching edges, merged nuclei...) we advise to assign tag "-1" or delete them prior to processing or quantification.

There are 3 different ways to visualize nuclei and structures :

• Overlay: by clicking on the overlay button (using the image5D plug-in, see internal documentation for settings). Two images will open: one for the raw channel image and one for the labelled image.
• Grayscale image stack: will open the selected structures of the selected cell as regular stacks, one for the raw channel image and one for the labelled image.
• 3D: 3D representation of segmented structures (using the 3D-Viewer plug-in, see internal documentation for settings).

To use them, select a nucleus and click on the button corresponding to the desired representation

This screenshot shows the different views, from left to right: 3D, overlay, grayscale stack, upper: raw lower: segmented images.

Object Browsing

For segmented structures, it is possible to browse the detected objects:
Click on the ">Objects>" button: a list will appear on the right, containing the objects of the selected structure(s) of the selected cell.
A good way to assess the quality of segmentation is to display the ROIs (region of interest = contour of the object) of the objects on the raw image. To do so, simply select an opened image and click on the objects you want to display (the button "ROI" has to be toggled on). ROI display will update automatically when the Z-position is changed. Cool .

Here are the action performed on the snapshot:

• Select one nucleus and one structure (nucleoli)
• Open the corresponding image by clicking on the "Open Structures" button
• Select the raw image, and click on the nucleolus n° 4: its contour will be displayed on the selected image

Quantitative Image Analysis

We term Measurements numerical information describing features from signals (such as shape descriptors or fluorescence quantification) or spatial relations between several signals (such as co-localization of two signals or distances between segmented objects).
They can be carried-out on grayscale or segmented signals.
TANGO includes a lot of different measurements. For details, see the Quantification Modules Page
The interface allows to choose the measurements and on which Structure(s) they have to be performed.
It is possible to see them on the interface and to extract them to text files.

Setting-up the Measurements:

To set up Measurements select the "experiment" tab, and the "Measurement" sub-tab.

In this example we will perform a few representative Measurements:

• Distance between centromeres and nucleoli:
  • Click on the "add" button
  • Select "Distances"
  • Click on the corresponding "edit" button
  • Select "centromeres" as first structure and "nucleoli" as second structure. On the right of the "remove" button, the index of the selected structures are displayed.
  • Select "Euclidean distance", "Center-Border", "negative" if inclusion
  • This Measurements will generate an array of distances, corresponding to distance between center of all centromeres and border of all nucleoli. Its length will be number of centromeres * number of nucleoli
  • It is possible to edit the names associated to the array (dist by default).

• Shape descriptors for each centromeres:
  • Select centromeres as the structure
  • This measurement estimate various shape descriptors, listed in the bottom panel. Each of them have a default name, that can be edited.

• Fluorescence quantification of centromere signal within each centromere:
  • This measurement estimate various statistical descriptors of fluoresence signal
  • Select centromeres as Structure object : fluorescence estimation will be done within each object of the selected structure (within each centromere in this case)
  • Select centromeres as Structure signal : the signal of the raw channel image associated to the selected structure will be used for quantifcation.
  • Output values are listed in the bottom panel. Each of them have a default name, that can be edited, and a prefix can be added in front of each of them. It is useful to distinguish output values, when this measurement is applied several times to the same objects but with different signals.

• Eroded Volume Fraction for each centromere:
  • Select centromere as Structure

• Don't forget to save the experiment.

Running the Measurements

Quantifications are run in the data tab: at the field or at the cell level.

• Check "Measurement check box".
• Check "Override meas." to erase all existing quantifications (if not, only new measurements will be performed, this saves time).
• select the cells/fields on which you want to perform quantifications and click on the "run" button.

Browsing Measurements

Measurements can be displayed in the interface. From the object browsing list, click on the ">Measurements>" button. A text field will appear on the left.
Three types of measurements can be displayed (the type is written above the text field)

• When selecting a single object: quantification on the objects are displayed (like shape descriptors).
• When selecting two objects: quantifications between the two objects are displayed (like distances).
• When selecting no objects but one or several structures: quantification on structures are displayed.

Retrieving Measurements

Quantifications can be retrieved in two ways :

• Extraction to spreadsheet file using the "Export Measurement" button of the data tab.
• Directly from the statistical processing software "R" using the package rTango.