This guide explains how to create a density distribution map, also called ”Heat-Map”. The script generates contiguous boxes in X,Y and Z directions that can be used as ROIs for further analysis (Compartmentalization, gradient distribution, etc.)
Creating Heat-Map – density distribution
Opening the working dataset
- Select Open... from the file menu.
- Select the dataset from the file browser.
The dataset is a multi dimensional, discrete, representation of your real sample volume. It can be structured as a Z series of planes (Optical sectioning) of multiple channels (dyes) in a temporal sequence of time points (located in several spatial positions).
Usually, the dataset shows a single experimental situation (a complete experiment can be composed by several datasets). The datasets are available as graphic files saved in plenty of file formats (standard formats as well as proprietary formats).
Note: The dataset is visualized according to the current rendering setting parameters. Refer to the arivis Pro Help for more details.
Loading the Python script
- Open Python Script Editor. From the Extra menu, select Script Editor.
- Load the Divide_Scope Python Script.
Note: The script name can change according to the new version released. The latest script is: DivideScope RevE (3_4).py. - Browse the folder on which the file has been saved.
Python script code usage rights:The user has the permission to use, modify and distribute this code, as long as this copyright notice remains part of the code itself: Copyright(c) 2021 arivis AG, Germany. All Rights Reserved.
Set the Script features
In order to define the contigues sub-regions (sampling volume) features, some parameters of the script should be adjusted to match your analysis needs. These parameters are located in the code area labeled as USER SETTING.
SIZE_BOX_X : Set the X sub-volume size.
SIZE_BOX_Y : Set the Y sub-volume size.
SIZE_BOX_Z : Set the Z sub-volume size.
All the values are expressed in metric units (µm).
If one of the box dimensions is bigger than the correspondent volume size, the script will not be executed and an error message is issued.
Only the parameters located in the USER SETTING area can be modified. Don’t change any other number, definition or text in the code outside this dedicated area.
Running the Python script
Run the DivideScope RevE (3_4) Python Script by pressing the Run Script button or pressing the F5 key.
Note: Activate the Output Panel, if not already displayed. The status of the script execution (errors including) will be visualized here.
This is the script result, a 3D matrix of sub-volumes:
The sub-volumes segments are shown in the objects table using the TAG Script.
Analysis options overview
Once the script is executed and the sub-volumes have been created, several density distribution analyses can be performed on the sample. The simplest one is to get the single/multiple channel(s) intensity features inside the boxes. More sophisticated approaches can include a compartment analysis.
The COMPARTMENTALIZATION concept is strictly related to the studies of the interactions and of the relationship between the structure compartments.
Complex hierarchies between the structures can be established and evaluated using this operator. Objects inside a parent structure can be selected. Their position inside the main structure, as well as their distribution (clustering), and other features, can be evaluated. A child object can be a parent for other objects. The number of the available nested levels are, theoretically, unlimited.
In the example above, The COMPARTMENTALIZATION is extended on 3 levels. The result is a hierarchical link between the Cell (Reference) and its nucleus (subject) . The nucleus is, in turn, related to the vesicles it contains. Finally, the vesicles count per cell is obtained.
The COMPARTMENTALIZATION analysis is not limited to the biological samples, even if this is the most common situation. Any structure located inside of a defined surrounding volume can be evaluated.
It is not mandatory that the parent object is a defined structure (e.g. Cell or Nucleus). It can be an anatomical region or, generally speaking, a sub-region of interest of the sample volume. These regions can be drawn both manually or using the interactive method.
The COMPARTMENTALIZATION approach is the base on which more complex and sophisticated evaluations can be performed.
On the next pages the compartment concept will be detailed.
Refer to the Application Note #8 for detailed information about «How to Draw objects interactively».
Simple Compartments (2 levels)
The Simple Compartments' schema is organized on two levels of hierarchy, the Reference (Parent) and the Subject (Child). The child objects belonging to the parent spaces are labelled TAG as compartmentalized.
These Reference structure can also be drawn both manually or using the interactive method. Refer to the Application Note #8 for detailed information about «How to Draw objects interactively».
Compartments setup:
The left most item is a reference. The items below the left most item is the subject. It must be shifted one position on right compared to the reference.
The commands on top of the dialog are used to set the hierarchy.
Multiple Compartments (multiple levels)
The Multiple Compartments’ schema uses 3 levels or more of hierarchy. Starting from the first child on the top, each level is checked with the previous one. The child objects belonging to its parent spaces are labelled TAG as compartmentalized.
Compartments setup:
The left most item is a reference. The items below the left most item is the subject. It must be shifted one position to right compared to the reference.
The 3rd level is set by shifting the TAG one position to right compared to the subject on top of it.
The commands on top of the dialog are used to set the hierarchy.
Single Compartments (multiple subjects)
The Simple Compartments' schema (multiple subjects) is organized on two levels of hierarchy, but the child level can have more entries. The child objects of each entry, belonging to the parent spaces, are labelled TAG as compartmentalized.
Compartments setup:
The left most item is a reference. The items below the left most item is the subject. It must be shifted one position to the right compared to the reference.
The 2nd subject is set to the same level of the
The Compartments results are shown in the data table. The TAG Compartments is used to label the classified objects.
The commands on top of the dialog are used to set the hierarchy.
Compartments example
Simple Compartments (2 levels)
Multiple Compartments (multiple levels).
Single Compartments (multiple subjects).
Heat-Map Compartments application
Objects density distribution (heat-map)
The purpose of the density distribution Heat-Map, is to evaluate, through a colored map (heat-map), the objects population concentration per volume’ unit inside the whole sample.
These boxes are used as Parent (compartment reference) to establish the compartmentalization of the counted objects (child) in the sampled volume. The different colors show the density (or concentration) in the specific sub space. Usually, the cold colors (e.g. blue hues) show a low concentration, while the hot colors (e.g. red hues) show high concentration values.
Using different scripts a special boxes layout can be created. Here below are quick examples of the Gradient profile and the Spiral distribution map:
Object gradient profile
The Object gradient profile task computes the concentration’ gradient of the child objects along a specific direction.
Regular sized boxes are created to cover the selected part of the volume' sample with contiguous subspaces.
These boxes are used as Parent to establish the compartmentalization of the counted objects (child) in the sampled volume. The boxes can be created following a linear progression, or covering a more complex path (e.g. spiral path).
Building the analysis pipeline
The pipeline has to be created according to the user analysis requirements as well as the sample typology.
The sample labeling, the imaging technique (Fluorescence, EM, Tomography, bright-field ...) and the image characteristics are important to drive the pipeline setup.
The knowledge of the biological structures under evaluation, it’s behavior and the expected features' trend are also important as well. All the above information should be used to build a target driven pipeline.
To achieve the application note goals, only a couple of operators are mandatory, as described below:
- Change the ROI operator parameters inside the Input ROI dialog.
-
- A dropdown menu will open.
- Inside the dropdown menu, set the processing and analysis target space.
Following options are available:
Current View: The selected Z plane and the viewer area will be processed.
Current Plane: The selected Z plane will be processed (XY).
Current Image Set: The complete dataset (XYZ and time) will be processed.
Current Time Point: The selected time point will be processed (XYZ).
Custom: Allows to mix the previous methods and expands the Input ROI dialog.
NOTE: Use the Custom option during setting and testing of the pipeline. Set a sub volume (XY, Planes, Time Points, channels) of your dataset on which to perform the trial. This will speed up the setting process. - Use the Custom option during setting and testing of the pipeline. Setting a sub volume of your dataset on which to perform the trial, will speed up the setting process. You have the following setting options:
Bounds: Sets the analysis area edges. The whole XY bounds, the viewing area or a custom space can be applied.
Planes: Sets the analysis planes range. A single plane, a range of planes or the whole stack can be selected.
Time Points: Sets the analysis time points range. A single TP, a range of TPs or the whole movie can be selected.
Channels: Sets the processing and analysis target channels. Selecting a single channel, all the operators in the pipeline will be forced to use it.
Scaling: Scales the dataset by reducing the size. The measurements will not be modified by the scaling factor. - Set the Import Document Objects operator, by selecting the Tag filter inside the Import Document Objects dialog .
- The select tags dialog opens.
- Select the Manual TAG and use the right arrow button to move the TAG to the right table.
- Add or remove optional operators inside the pipeline.
- The Analysis Pipeline panel consists of two main areas. The Pipeline area and the Analysis Operations area.
- Add the Operators to the pipeline in two possible ways:
1. Double-click on the Operator you wish to add to the current pipeline. The Operator will be inserted at the end of the group of operations to which it belongs. Voxel operations are positioned before the Segment generation meanwhile Store operations are put always at the end of the pipeline.
2. Drag and drop the Operator you wish to add to the current pipeline. The Operator will be automatically inserted in any place within the group of operations to which it belongs. NOTE: The Operator cannot be added during the pipeline execution. - To remove an Operator from the pipeline, press the X button located in the right side of the operator title bar.
Please refer to arivis Pro Help for more details.
Viewing the results
Results (segments and measurements) will be stored in the dataset only if the Store Objects operator has been correctly set. Tick appropriately the option as shown below before complete the pipeline execution.
- Open the data table if not already visible.
- Measurements are now visible in the data table.
Note: The spots count in the single sub-region is shown in the data table. The empty sub-regions are not listed. To get the total spots count the group statistic feature must be used.
Features can be added or removed from the data table using the Feature Column command.