Masking

rakaia supports the import and overlay of mask arrays that represent segmented objects over canvas images. These masks are often outputs of processing pipelines for mutiplexed imaging technologies and can represent structures such as cells and tissues, or more complex annotations.

Mask import/formatting

The data import collapsible sidebar for rakaia has a drag and drop input components where masks can be uploaded:

Masks can be uploaded individually or in bulk. Individual uploads will prompt a modal popup where the specific mask name can be set. For bulk uploads, the basename of the file will set the internal mask name that is shown in the dropdown menu. Users should ensure that for bulk uploads, each mask has a unique filename that corresponds to an ROI name (see below in Mask matching heuristics)

Mask formatting

Masks should be imported as single-channel greyscale tiffs where each tiff represents a mask for a specific ROI. The naming convention of masks can be user-derived, and partial and exact name match of mask tiffs will allow for rakaia to auto-identify the mask associated with an ROI. See more under Mask matching heuristics.

The mask itself should be a 2D array of integer values starting at 1, where each integer represents a unique object in the mask (i.e. a cell). Conventionally, each array value that has the same integer value corresponds to a pixel that represents that object (e.g. All of the array values with 1 represent a cell with ID 1). Areas of the mask without an object should have values of 0.

Mask overlay & blending

Masks can be selected and overlaid on top of a canvas under the Advanced Canvas Options collapsible sidebar under the Mask configuration space:

When a mask is selected, rakaia will verify the dimensions of the mask against the current ROI. If the dimensions to not align, the mask is not applied and the user will receive an alert message detailing the incompatibility.

Selecting a mask from the dropdown menu and then toggling Apply mask will project the mask on top of the blended canvas with the adjustable opacity relative to the underlying blend:

By default, the object boundary of each segment in the image will also be projected on top of the blend. This allows the user to adjust the opacity of the interior of each segmented object while retaining the boundaries of the objects. This option can be turned off as is necessary.

Mask matching heuristics

Users often import multiple ROIs into one session, and rakaia provides controls to efficiently switch between ROIs while retaining the current blend parameters. In situations where mutiple masks are imported, rakaia will attempt to match the current ROI name to a mask name with exact or partial matching. For example, the following names will automatch:

• ROI name: acquisition_1
• Example corresponding mask filenames: acquisition_1.tiff or acquisition_1_mask.tiff, among others

If any part of the ROI name matches to a string portion of one of the mask names, the mask will be auto-selected into the mask dropdown selection on ROI selection. This allows users to rapidly switch through multiple ROIs with matching segmentation masks provided that the naming scheme above is observed. Note that the same dimension matching procedure will occur as outlined above, and incompatible masks will not be overlaid.

The mask naming convention for the steinbock pipeline is also compatible.

Cluster projection

rakaia supports the visualization of grouped annotated objects, such as cell-type assignments or numerical clustering assignments for objects contained inside a mask. Annotations may be imported and applied from CSV under Advanced canvas options -> Quantification/Clustering -> with the drag and drop component named Import cluster annotations in CSV format. The CSV should have the following structure:

• A column linking object mask IDs to labelled categories. rakaia accepts either object_id or cell_id as the identifying column. This column should hold the integers for every mack object to be annotated.
• One or more dditional columns for annotation. Each column will be an annotation category, such as a cluster ID (leiden, UMAP, etc.) or a cell type. These annotation columns will populate a dropdown menu so multiple annotation categories per ROI can be toggled.

An example CSV format is shown below:

object_id   cluster     cell_type
1           0           immune
2           0           immune
3           1           epithelial

In this instance, users may toggle the cluster and cell_type categories to project different annotations for the objects 1 through 3 inside of an imported mask.

Cluster annotations can be applied by toggling Apply clustering once a category is set under Select cluster category. The subtype dropdown menu combined with the color picker can be used to select the colour for the particular cluster. Any cluster/grouping can have its colour changed and reflected in the mask projection.

By default, the cluster annotation will be shown inside each object of the mask (when applied), as shown on the left, or it can be toggled to circles to add a small circle at the centroid of every mask object:

It is important to note that the clustering will be projected on top of any underlying channels in the blend, so coloured channels may interfere with the full visibility of the clusters. If the user wishes to visualize just the clusters and no underlying channels, a single channel can be selected and both bounds set to 0, so the channel is functionally invisible. The mask can then be applied and the canvas will show only the mask and its desired opacity level, in addition to the cluster labels if applied. Selecting the channel and making it "blank" is necessary for this step as the mask cannot be applied to the canvas if the blend is blank.

Note: Cluster projections require that Toggle legend be turned on in the Advanced canvas options

Visit the Quantification secion for more information on how to rtansfer quantifification or annotation categories to the cluster projection inputs.