ZEISS Microscopy Knowledge Base
Help
ZEISS Microscopy Knowledge Base
Search

Performing objects density (heat-map) and object distribution gradient plotting (profile)

This guide explains how to perform the Objects density distribution analysis per volume unit (heat-map).

The same workflow can be used to evaluate the Objects count' distribution gradient along a specific direction (gradient profile). The application uses a Python script to create the contiguous sub-regions (sampling volume) and a pipeline to count the objects and to compute its density per volume unit (single sub-region) or the distribution along the longest direction of the sub-regions structure.

The evaluated Objects can be any biological structures like Cells, Nuclei, Neurons, as well as any small structures like Vesicles, Protein clusters, Mitochondria, and etcetera. The sampling volume can describe and limiting any anatomical regions inside the sample.

The unique limits is related to the sampling volume shape, only regular 3D boxes are available.

Tilted multicolored segmented bar with small green dots and two green clusters below on black

Opening the working dataset

  1. Select the Open... item from the file menu.
    File menu showing Open... option highlighted with CTRL+O shortcut
  2. Select the dataset from the file browser.
    Note: The dataset is visualized according to the current rendering setting parameters. Refer to the arivis Pro Help for more details.

App window showing a 3D grid with three green volumes bearing red clusters, left control panels and a right color bar

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)​.

Drawing the reference ROI

  1. Switch the Viewing area from 4D to 2D view mode.
    Toolbar with five square buttons: filled blue rectangle, grid, 3D cube, info 'i', and display screen icon
  2. Select the Draw Objects tool.
    Row of gray toolbar icons including curved arrow, pointer arrow, yellow circle, hand, globe, and blue circular tool
  3. Select the Brush tool.
    Toolbar row with save, copy, undo, pointer, and drawing tool icons on gray background
  4. Draw the 2D ROI over any Z plane. Use the Erase Brush to correct the ROI if necessary.
    Black background with multiple red fluorescent round clusters and a large translucent blue elongated ROI outlined in light blue
  5. Press the green icon to confirm the ROI.
    Small toolbar showing document and editing icons with green check and red X buttons
    Red elongated rounded rectangle inside dashed white selection box over three red-blue speckled circles on black background
    The TAG Manual is now available in the data table.
    Tags: 1 panel showing checked Manual checkbox and a search field

Loading the Python script

  1. Open Python Script Editor. From the Extra menu, select the Script Editor item.
    Extras menu dropdown listing Preferences..., Plug-in Manager, Task Monitor, Run Script..., Script Editor
  2. Load the Free-Oriented Sub-volume Python Script.
    Script Editor - Script1 title bar showing menus File, Edit, View, Script
  3. Browse the folder on which the file has been saved.
    File menu with 'Open... Ctrl+O' highlighted, 'New Ctrl+N' above, 'Open Sample' and 'Close Ctrl+F4' below
Python script code screenshot showing comments 'coding: utf-8', 'ARIVIS AG', 'WRITTEN BY : Maurizio Abbate', imports and USER SETTINGS
Python script code overview

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.

Setting the script features

To define the contiguous sub-regions (sampling volume) features, few parameters of the script should be adjusted to match your analysis needs. These parameters are located in the code area labeled as USER SETTING.

USER_SETTINGS code: FIRST_PLANE=-1 LAST_PLANE=-1 NUM_BOX_LENGHT=14 NUM_BOX_WIDTH=2; 3D colored boxes with blue point cloud

  1. Set the Z planes range.
    FIRST_PLANE defines the lower Z plane of the sub-regions ROI.
    LAST_PLANE defines the higher Z plane of the sub-regions ROI.
    The values of -1 set the Z planes range equal to the whole volume depth (total number of Z Planes available).
    Code lines: FIRST_PLANE = -1 and LAST_PLANE = -1
  2. COMPUTE_MAIN_BOX = True enables the creation of an additional ROI having the same sizes of the total subregions ROI size.
    Code screenshot showing COMPUTE_MAIN_BOX = False
  3. NUM_BOX_LENGHT defines the number of sub-regions along the main axis (the longest one). NUM_BOX_WIDTH defines the number of sub-regions along the minor axis (the shortest one).
    Code screenshot showing NUM_BOX_LENGHT = 14 and NUM_BOX_WIDTH = 2
    Note: Set the number of sub-regions accordingly to the total size of the reference ROI. Don’t create boxes too small.

Examples:

NUM_BOX_LENGHT = 10
NUM_BOX_WIDTH = 1

3D view of stacked multicolored rectangular blocks with scattered blue dots on black background

NUM_BOX_LENGHT = 10
NUM_BOX_WIDTH = 2

3D view of segmented multicolored rectangular prism with scattered blue dots on black background

Running the Python script

Run the Free-Oriented Sub-volume Python Script pressing the Run Script button or pressing the F5 key.

Toolbar with Run Script button and Hide Output Pane, tabs labeled Skeketon_RevB.py and Free-Oriented Sub-...

Script menu showing Run Script F5 and Run File CTRL+F5 options

Note: Activate, if not already displayed, the Output Panel. The status of the script execution (errors including) will be visualized here.

Toolbar with Run Script button and Show Output Pane option

Script output panel displaying lines: starting script..., Script is running ........, time: 1.34400010109, script finished.

Building the analysis Pipeline

The pipeline have 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. The achieve the application note goals, only a couple of operators are mandatory. As described here below.

Pipeline diagram: optional left operators point to mandatory Input ROI, then Import Document Objects, then Store Objects

The Operators are grouped in several categories. Each category includes the functions that perform specific tasks, ordered by their usage. Here below a short summary.

Purpose

Application

Voxels Operator

The group includes the operators that interact directly with the voxels. Typically, spatial filters, Intensity normalization, intensity range equalization and so on.

Sample Noise removal, background subtraction, Intensity disomogenity correction, details enhancement, edges detection (e.g. membrane), morphological math.

Segmenter Generation

The group includes the threshold operators used to detect and create the segments. Automatic and manual method, machine learning approach, watershed and proprietary algorithms are available.

Structures identification. Nuclei, Neurons, small spots (Blob Finder), Cells, Vessels, Filaments (Watershed, Region Growing) or microstructures (Machine learning) can be detected using the appropriate method or a combination of them.

Segmenter Operators

The group includes the operators that interact directly with the segments. Feature filtering, morphology, Compartmentalization, distance measurements and more can be applied.

Objects colocalization, object classification by features, objects merging or splitting, objects grouping, objects parent/child relationship and even more.
  1. Change the Input ROI operator parameters.
    Input ROI panel: ROI 'Current time point', Channels '[all channels]', Scaling '100 %', checked 'Include Z'.
  2. Sets the processing and analysis target space.
    Dropdown showing options: Current View, Current Plane, Current Time Point, Current Image Set (selected), Custom
    Current View: The selected Z plane and the viewer area are processed.
    Current Plane: The selected Z plane is processed (XY).
    Current Time Point: The selected time point is processed (XYZ).
    Current Image Set: The complete dataset (XYZ and time) is processed.
    Custom: Allows to mix the previous methods.
    Note: Use the Custom option during the pipeline setting and testing. Set a sub volume (XY, Planes, Time Points, channels) of your dataset on which perform the trial. This will speed up the setting process.
  3. Expand the Input ROI dialog.
    Small downward chevron icon
    Input ROI dialog: ROI 'Custom', Bounds '0,0,512,512', Planes '1-13', Image set 'T099_Gfp+24hdox_mis.ims (default)'
    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.
  4. 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: It scale the dataset reducing the size.​ The measurements will not be modified by the scaling factor.​
    Input ROI panel: ROI 'Current time point', Channels '[all channels]', Scaling '100 %', checked 'Include Z'.
  5. Set the Import Document Objects operator and select the TAG filter.
    Import Document Objects panel with 'Tag filter:' input and checked 'Preserve tags on import'.
  6. Click on the Manual TAG.​
    Select tags dialog showing 'Available Tags' list with 'Manual', arrow buttons, empty 'Selected' panel and 'New Tag' field.
  7. Use the right arrow button to move the TAG on the right table​.
    Input ROI panel showing ROI: Current view, Channels: [all channels], Scaling: 100%
    Import Document Objects panel with Tag filter field set to 'Manual'.
  8. Add or remove optional operators inside the pipeline.
    Demo window showing 'Ready to run' and Input ROI panel with ROI: Current view; Channels: [all channels]; Scaling: 100%
    The Analysis Pipeline panel consists of two main areas. The Pipeline area and the analysis operations list area.​
    Panel titled 'Analysis Operations' with 'Voxel operations' list showing Deep Learning, Denoising and 'Segment generation'
    The Operators can be added to Pipeline in two ways:
  9. 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.
  10. 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. The Operator cannot be added during the Pipeline execution.
  11. To remove an Operator from the Pipeline, press the X button located in the right side of the operator title bar.
    Gray toolbar with four icons: square with diagonal, upward chevron, three horizontal lines, and an X.

Refer to the arivis Pro Help for more details.

Running the analysis Pipeline

The pipeline can be executed step by step (back and forth). This method allows to run and undo a single Operation. Either the arrow buttons or the Operation list can be used to go through the operators list.

Toolbar titled 'Detect Cells or Particles' showing arrows, dropdown, blue play and gray stop square

  1. Run the single operator.
    Gray curved arrow pointing up-right
  2. Optional: Undo the single operator.
    Gray curved arrow pointing up-left
    Note: Undo the last operator executed if you need to change the operator settings.
  3. Run the whole pipeline with no pauses.
    Blue right-pointing triangle
  4. Optional: Stop the pipeline execution.
    Gray centered square

This icon, located on the right side of the operator title bar, shows the operator status.

Task running:
Grey bar with icons: green square, blue square with white arrow, up caret, menu, cyan circular arrows

Task completed:
Grey bar icons: left arrow, blue square with white arrow, up caret, menu, green circle with white check

Viewing the results

  1. Results (segments and measurements) will be stored in the dataset only if the Store Objects operator has been correctly set. Tick the option as shown below before complete the pipeline execution.
    Store Objects dialog with checkboxes for Blob Finder, Import Document Objects, Segment Filter (checked), Compartments (checked)
  1. Open the data table if not already visible.
    Toolbar showing icons with menu labels Extras, Window, Help
  2. Measurements are now visible in the data table​.
    Data table listing Segment #014 to #020 with counts and sum volume stats (µm³)
    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. ​
    Diagonal multicolored segmented bar with blue and green speckles above two separate green clusters on black background
    Toolbar area showing Feature Columns..., Go to, Σ Summary and Im/Export... controls

Features can be added or removed from the data table using the Feature Column command.

ON THIS PAGE

PRODUCTS
ZENX Ray SoftwareEM SoftwareSolutions Lab
ABOUT ZEISS
AboutCareerNewsroomCompliance
Social Media
LinkedInFacebookYouTubeXInstagram
Impressum
Carl-Zeiss-Strasse 22
73447 Oberkochen
Germany
Legal