Use cases and result interpretation for the Compartments pipeline operation.
What does the Compartments operation do?
In a nutshell, it establishes relationships between objects, assigning children and parent links, and permits the analysis of those relationships.
A Parent-Child relationship is a hierarchical structure where some objects belong to other objects and vice versa. The individual objects have their own characteristics (volume, surface area, intensity), but also features dependent on those relationships (ID of the parent, number of children). The Compartments operation is specifically concerned with establishing the relationships between parent segments and their children. Other types of parents exist, such as tracks or groups, but the compartments operation is specifically concerned with the overlap or proximity of different object types.
Example uses of the Compartments operation
Establishing parent/child relationships can be valuable in a variety of cases, such as:
- Counting foci in nuclei or vesicles inside cells
- Quantifying migration of objects to or from the inside of cells
- Measuring the numerical density of cells inside specific brain regions
In each of these cases, the number and size of the objects of interest are relevant based on their position relative to a parent.
Configuring the Compartments operation in a pipeline
The first thing that is needed before adding the compartments operation is a set of parent and children objects. Since many segmentation methods can result in unwanted objects it is also best to use any object filtering operation prior to adding the Comparmtnets operation to the pipeline.
The compartments operation can the be added to the pipeline like any other operation.
Once added to the pipeline we can configure the operation parameters.
Compartment operation inputs
Each Compartments operation can have one Parent object tag and multiple children object tags. If there are several potential parent objects in your pipeline, either multiple Compartments operations must be used (one for each parent type), or the parents must be given a common tag with the Combine Segment Outputs operation. The tag to be used for the parents can be selected from previous pipeline tags.
Parents can have multiple children tags. When added to the pipeline the operation starts with one parent and one child tag. To add another child object tag we can just click "+ Add input" and select from the available object tags. Note that the children cannot be either the parents or a subset thereof.
Configuring relationship parameters
Once the children have been selected we need to configure by what criteria children can be included. This is done by clicking the relation icon:
Then we can select under what conditions objects can be considered a child of any given parent:
If the Inside rule is selected, any potential child object that is fully within the boundaries of the parent will be included.
If the Intersecting rule is selected, a child that crosses the boundary of the parent can be included, depending on the amount of overlap between the parent and child candidate, as defined by the Min. Overlap slider.
If the Close rule is selected, potential children can also be included based on the proximity of these objects to potential parents. Note that children can only belong to one parent so if a child is within the max allowed distance of two parents it will be assigned to the closest one.
Compartments operation results
The result of the operation is a special type of segment grouping. Each parent object will have a number of children, and each child will be linked to the parent. From this we can do a variety of things.
First, the number of children is a feature of the parents. you can display the number of children a parent has as a feature in the Objects table:
Likewise, the ID of the parent or children can also be displayed as a feature of the respective object types. But most importantly, those features and the children's features can be used to inform other pipeline operations or custom features.
Custom features related to children
Of course, in many cases, the number of children is a very valuable metric in itself, but in many cases, more interesting insight can be had from more specific measurements. for example, if there are multiple potential children types it might be more interesting to get the number of children of each type separately or measure the numerical density of objects within each parent.
However, many of these features are not available within the standard feature set since they wouldn't make sense in many cases that don't involve compartmentalization. Instead, we must create new Custom Features. To do this, we open the Custom Features window directly from the Objects menu or from the feature selection window in the Objects table:
In the Custom Features Window we can then add a new Custom Feature:
Examples of useful Custom Features include:
- Numerical Density - This is a Compute feature reporting the Ratio of # Children to Volume
- Specific Children Count - An object count feature linked to a specific object tag
- Children Volume Statistics - A Group Statistics feature of the volume of children in a group.
.. and many combinations thereof (Volume ratio, tag specific numerical density, etc).
Object table layout
along with Custom Features, the objects table layout can also be changed to provide easier access to the features of parent and children.
The default layout for the Objects table is a single table showing all the objects with the selected tags. If the Compartments operation has just been run it may look something like this:
However, in this layout, the table doesn't give any clear indication of which objects are parents and which are children, or the relationship between them. Instead we can switch to the Master/Detail layout where parents can be displayed on the top, and the respective children shown in their own table at the bottom:
In the Master detail layout, each table behaves somewhat independently, meaning that different tags can be selected at the top and bottom, but the Detail table only shows the children of parents selected in the Master table.
Exporting compartmentalization results
Of course, the objects table is a powerful tool for visualizing and sorting the results of the Compartments operation. However, in many cases, it can be advantageous to export the results so that further analysis of the results can be done in different software like Excel. In that case, the results can be exported, either out of the Objects table using the Im/export button, or directly in the pipeline by adding the Export Objects Features operation.
The Export Object Features operation can be configured in a variety of ways, including the Master-Detail report as seen above.
As with the Master-Detail layout in the objects table, the features to be exported can be set independently for both the main table export and the details tables.
Conclusions
The Compartments operation, together with the objects tables and features, can provide powerful insights into object relationships in image analysis. Unfortunately, it is difficult to do this topic justice in a knowledge base article due to the vast array of potential uses and applications where these tools can be used. Hopefully, this article provides a valuable overview. Please contact support using the link at the top of the page if you require any additional help with your analysis.