ROImanager

ROImanager

ROImanager is a graphical interface dedicated to create, edit and save regions of interest (ROIs) associated to an image. In addition, it provides preset ROIs of the top projection of mouse cortical areas from the Mouse Allen Brain Atlas. The ROImanager app can be called from the Visualization tab, from the Add-ons tab in the DataViewer app or as standalone (see syntax below).

Syntax

ROImanager(): Opens only the main GUI.

ROImanager('C:/PATH/datFile.dat'): Opens the first frame of the imaging data from datFile.dat. The .dat file created by one of the analysis functions of umIT.

ROImanager(data): Opens the image contained in the variable data from the Matlab's workspace. data can be either a 2-D numeric matrix or a 3-D matrix encoding an RGB image. In the latter case, the app will automatically transform the data in a grayscale image using Matlab's built-in function rgb2gray.

ROImanager('C:/PATH/ROImasks_data.mat'): Opens the image and ROIs contained in the ROImasks_data.mat. The ROImasks_xxxxx.mat is created by ROImanager to store ROI information.

Sections

The interface

ROImanager_mainComp
Main components of ROImanager app

1. Menu Bar

  • File >>
    • New: Creates a new ROI table. Existing ROIs will be erased
    • Open ROImasks file: Opens dialog to load an ROImasks_xxxxx.mat file
    • Open Image: Opens dialog to load a new image. Images can be obtained from a .dat file, a variable stored in a .mat file or from an image file (.PNG, .JPEG or .TIF). RGB images will be automatically transformed to grayscale 2-D images
    • Save File: Saves the ROI data to the current ROImasks_xxxxx.mat file
    • Save as...: Opens dialog to save ROI data to a new ROImasks_xxxxx.mat file
    • Import from...

      Note
      The ROImanager app accepts ROIs only in the following formats:

      • 2D or 3D logical arrays
      • 2D label matrix

      For more information, read the section on importing ROIs.

      • .mat file: import ROIs stored in a .mat file.
      • workspace: import ROIs stored in variables from Matlab's workspace
    • Export table to CSV: export the content of the ROI table (4) to a .csv file
  • Create >>
    • Polygon: creates a new customizable polygonal ROI.
    • Point: creates a new point ROI. A point ROI consists of a single pixel from the image.
    • Mouse Allen Brain Atlas >>
    • From threshold...: launches a tool to create ROIs from threshold
    • Delete all ROIs: deletes existing ROIs and clears the ROI table
  • Selection >>

    Note
    ROIs are selected by checking the boxes in the Selection column of the ROI table.

    • Edit >>
      • Color: Change color of the selected ROI. Single selection only!
      • Shape >>

        Important
        Works only with polygonal ROIs!

        • Constrained Edit: Performs scaling, rotation and translation of selected ROIs. Can edit more than one ROI at once. In this case, the central point of rotation and scaling is the centroid of the ROI set.
        • Unconstrained Edit: Free edit of the shape and position of an ROI by changing/adding/deleting its vertices. Single selection only!
    • Delete: erases selected ROI(s) from the table. Multi-selection allowed
    • ROI math >>
      • split: splits a multi-region ROI
      • merge: merges several ROIs into one
      • intersect: intersects two or more ROIs
      • XOR: performs logical exclusive-OR operation
      • subtract: subtracts one ROI from another
  • Image >>
    • Set Origin >> Sets the axis origin (0,0) of the image
      • New: interactive selection of a new origin.
      • Import from file: Import the origin coordinates stored in a variable from a .mat file. The coordinates must be inside the image’s limits.
      • Align image to origin: Allows the rotation of the image around the origin. This option is disabled when ROImanager is used as Add-on in DataViewer app.
    • Set pixel size: Sets the pixel ratio in pixel per millimeter.
    • Set colormap: Sets image colormap and clipping values.
    • Mask >> Creates a logical mask to exclude non-pertinent regions of the image
      • Draw new: creates a new mask by drawing a polygon. Existing masks will be overwritten.
      • Import from file...: loads a logical mask from a variable inside a .mat file.
      • Show/Hide: toggles mask display over the image.
      • Delete: removes existing mask.
    • Image reference file... >>
      • Export: exports the image parameters as an ImageReferenceFrame.mat file which is used in the automatic and manual alignment functions of umIT
      • Import: imports the image parameters from a ImagingReferenceFrame.mat file
    • Reset parameters: reset all image parameters to default
    • Save Params to meta data file: saves the origin and pixel size values to the .mat file of the imaging data file (with extension .dat) currently opened

2. ROI display modes

There are 3 options to display the ROIs over the image:

  1. normal: ROIs are displayed with a semi-transparent face color with black contours.

    roimanager_overlayMode_normal

  2. contours only: ROIs are displayed as coloured contours and no face color.

    roimanager_overlayMode_contour

  3. highlight pixels: ROI shapes are shown as contours only while the pixels inside the ROIs are highlighted.

    roimanager_overlayMode_highlight

3. Image settings

Panel showing the current values of the image parameters:

  • orig(x,y): X,Y coordinates of the reference point
  • px/mm: pixel size (in pixel per millimeter)
  • cmap: colormap ('none' or colormap name)
  • logical msk: logical mask. ('none' or 'Set')

4. ROI table

A table containing the ROI name, type (Shape or point), date of creation, centroid coordinates as well as descriptive statistics of the ROIs and selected pixels.

ROImanager_Table
ROI table components and interactions

Important
The descriptive statistics of the ROIs (min/max, median, mean(+-STD)) refer to the ROI pixels from the frame used at the moment of the ROI creation. This information is not automatically updated when the frame is changed!

5. Image window

Figure containing the image (frame) used to plot the ROIs. This figure is absent when ROImanager is called as an Add-on from the DataViewer app.

Draw and edit polygonal ROIs

To draw a new polygonal ROI:

  1. Click on Create >> Polygon
  2. Enter the name of the new ROI
  3. Draw the polygon.
  4. Once the drawing is finished, one can edit the shape by adding/deleting vertices or translating the polygon across the image.
  5. Finally, double-click inside the ROI to save.


Steps to create a polygonal ROI

Now, to edit the ROI:

  1. Select the ROI by checking the correspondent box in the Selection column of the ROI table.
  2. Click on Selection >> Edit >> Constrained Edit/ Unconstrained Edit
  3. Edit the ROI shape.
  4. Double-click inside the ROI to save.

Example of constrained edit:


Example of constrained edit of a polygonal ROI

Example of uconstrained edit:


Example of unconstrained edit of a polygonal ROI

Create point ROIs

Point ROIs consist of a single pixel. This type of ROI does not allow any type of editing. Thus, if you want to change the location of the ROI, you can simply create a new point with the same name of the one that you want to change.

Here, you can select a pixel from the image interactively OR type the pixel's X,Y coordinates.

To create a point ROI:

  1. Click on Create >> Point
  2. Enter the name of the new ROI
  3. Choose pixel selection method and confirm:
    1. Interactively:
      • Select pixel from image and double-click to save
    2. Type coordinates
      • Type X and Y coordinates and click Ok


Example of interactive selection of point ROI


Example of selection of point ROI using X,Y coordinates

Mouse Brain Atlas preset ROIs

The preset ROIs were created from the top projection of the mouse cortical areas (see image below) obtained from the Mouse Allen Brain Atlas.

ROImanager_MouseAreas
ROI template from top view of the Allen Mouse Brain Atlas

Note
Note: The position of the Bregma is provided here as a rough estimate. The data from the Allen Mouse Brain Atlas does not provide any anatomical landmark coordinates from the mouse skull. For more info on this, see this discussion from the Allen Brain Map Community Forum.

Tip
For a more accurate result, it is advisable to set Bregma as the image origin and to set the image pixel size before drawing the ROIs from the Mouse Brain Atlas. Once these parameters are set, the ROI mask will be automatically place the atlas mask estimated Bregma over the origin point and resize it to fit the image's pixel ratio.

There are two modes for the Mouse Brain Atlas preset ROIs: Areas and Centroids. The Areas option draws the full surface of each cortical area while the Centroids option creates a circle around the region's centroid. Optional parameters for each mode can be set by clicking on Create >> Mouse Allen Brain Atlas >> (Areas/Centroids) >> Options....

Area options

One can choose to use the full surface of each ROI (default) or to shrink it by N pixels. This only affects the selected pixels inside the ROIs and not the shape themselves.

ROImanager_AreaOptions
Area Options

The shrinking algorithm removes pixels from the ROI border:

ROImanager_AreaShrinkEx
Example of shrinking of the Left primary visual cortex ROI by removing 15 pixels from the ROI border

Centroid options

One can choose the radius of the circles in pixels (default = 1 px) and in millimeters. The latter is only available if the image pixel size is already set.

ROImanager_CentroidOptions
Centroid options

Note
If the ROIs are larger than the cortical areas themselves, the circles will automatically intersect with the region's borders to avoid selecting pixels outside the selected ROIs.

ROI selection

Once the options are set (either for Areas or Centroids), click on Select (Areas/Centroids) button. A table containing the columns acronyms, names, functional modality and Selection will appear.

ROImanager_MouseAreasSelectionBox
Table of available ROIs from the Mouse Allen Brain Atlas

Tip
For checking/uncheking multiple chekboxes from the Selected column, first highlight the cells, then click outside the table and press Enter.

After checking the areas, close the window to confirm.

Fitting the mask

After areas selection, a mask is plotted over the image and can be fitted using a constrained edit method:


How to create ROIs from the Mouse Brain Atlas

Create ROIs using threshold

This option creates ROIs based on pixel values above or below a certain threshold. Go to Create >> From threshold... to launch the tool (ROImask Creator).

roimanager_roimask_creator_overview_annot
Main components of ROImask Creator tool

1. Control panel

  • Normalize: normalizes the threshold scale from 0 to 1
  • Excl. ROIs: excludes ROIs with a number less than N pixels
  • Remove small holes: performs morphological closing (dilation followed by erosion)
  • Smooth borders: performs morphological opening (erosion followed by dilation)

    Note
    When both Remove small holes and Smooth borders are selected, the app performs a morphological closing followed by an opening.

  • Threshold level >>
    • Edit field: type the threshold value and press Enter
    • Slider: alternatively, move the slider to set a threshold
  • Sel. direction panel >>
    • above thr.: chooses the pixels with values greater than the threshold
    • below thr.: chooses the pixels with values smaller than the threshold

2. Image window

Window containing the grayscaled image (left) and the binary mask (right). The ROIs created by the threshold are overlayed on both images and numbered on the binary mask.

Generating ROIs

Once all parameters are set in the control panel(1), simply click on the green button (Create ROIs) to generate the ROIs. The new ROIs will be added to the ROI table in ROImanager app with the notation : newROI_<NUMBER>

roimanager_roimask_creator_roi_preview
Example of ROI delimiting an area with pixel values above 0.03

roimanager_roimask_creator_resultROI
Resulting ROI added to the ROI table and shown in the DataViewer interface.

Tip
It is advisable to create a logical mask before loading the ROImasks Creator tool. The tool will use the mask to exclude unwanted regions of the image and thus, i will consider only the pixels inside the mask in the threshold calculation.

Draw a mask

Applies a logical mask to the image. The logical mask is used by the ROImanager app to exclude areas of the image during ROI creation (for details, see the rules for ROI fitting). In addition the logical mask is used by some of umIT's analysis functions as a variable in a Imaging reference frame file (for details see this section).

To draw a new mask:

  1. Go to Image >> Mask >> Draw new
  2. Select the number of regions to draw
  3. Draw each region (the same way as a polygonal ROI)


Steps to create/draw a logical mask using 2 regions.

Note
When drawing more than one region, the final mask will contain the union of all regions drawn (as the example above).

Note
A note on importing logical masks: the ROImanager app accepts masks stored in a variable as a logical 2D array (i.e. matrix) in a .mat file.

ROI math

The ROI math option allows one to perform the following operations on existing ROIs:

  • Split: splits a multi-region ROI on individual regions.
  • Merge: merges selected ROIs into one.
  • Intersect: creates a new ROI as the overlapping area from selected ROIs.
  • XOR (exclusive OR): creates a new ROI as the non-overlapping area(s) from selected ROIs.
  • Subtract: creates a new ROI from the subtraction of two existing ROIs.

In order to perform the desired operation, select the ROI(s) by checking the ROIs box in the Select column of the ROI table and go to Selection >> ROI math >> <OPERATION MENU>. A preview figure will be available to assess the result of the operation and confirm. At the end, you can edit the name(s) of the new ROI(s).

Important
Please, note that the original ROIs used in the operation will be replaced by the resulting ROI(s)!

Split

This operation works with only ONE multi-region ROI. A multi-region ROI consists of an ROI with two or more non-contiguous (isolated) areas:


Steps to split a multi-region ROI.

Merge

Here, one can merge two or more ROIs together into a single ROI:


Steps to merge ROIs.

Intersect

This operation retrieves the overlapping region(s) between the selected ROIs. This option accepts two or more ROIs as input.


Steps to intersect ROIs.

XOR (exclusive OR)

This operation retrieves the non-overlapping regions between two or more ROIs. In other words, it gives the inverse of the intersection of ROIs.

Tip
Although, more than two ROIs are accepted for this operation, it is advisable to perform it with two ROIs at a time.

Here is an example of XOR operation between two ROIs:


Steps to perform XOR operation between two ROIs.

Subtract

This operation subtracts one ROI from another. Here, only two ROIs are accepted!


Steps to subtract two ROIs.

Create an imaging reference frame file

An Imaging reference frame file stores a reference image - and some meta data - to be used by the analysis functions from umIT. For instance, one can use the reference frame to align different recordings (see this tutorial) or use one of the extra variables such as the logical mask to exclude pixels in some analysis such as the GSR function.

The main information saved in the Imaging reference frame file include:

  • a reference frame
  • the X,Y coordinates of a reference point (i.e. origin)
  • a logical mask
  • the image's pixel size
  • the colormap and color scale of the reference frame

In order to create the Imaging reference frame, one can simply go to Image >>Image reference file... >> Export and select the folder and name of the file (default: ImagingReferenceFrame.mat) to save the current frame as the reference frame. However, it is advisable to set all image parameters (origin, pixel size, colormap and logical mask) before creating the file. Here is a brief description on how to set the main image parameters:

Origin

To create a new reference point (i.e. origin), go to Image >> Set origin >> New. Here, you can select a point in the image to be the new origin (0,0) of the cartesian coordinates. In the example below, we will select an anatomical landmark from the mouse skull(Bregma) as the origin. To select a new origin, click and drag the green dot to the desired location and right-click to save. The image's axis will be shifted to match the new origin point.

Note
Once the new origin is set, the X,Y coordinates and Distance from Origin variables from the ROI table are updated to match the new coordinates.


How to set a new origin point.

Notice that the image in the example above is slightly rotated. To adjust the image's angle, go to Image >> Set origin >> Align image to origin. Click and drag the moving point to the area on the image that is supposed to be vertically aligned with the origin. In our example, we will use the Lambda landmark of the mouse skull to align the frame:


How to rotate the image around the origin.

One can also import the origin coordinates from a .mat file. To do so, go to Image >> Set origin >> Import from file.... Then you can open a .mat file and select the variable containing the X and Y coordinates. The variable must be a numerical array with dimensions 1X2.


How to import X,Y coordinates from .mat file as a new origin.

Pixel size

To set the image's pixel size, simply go to Image >> Set pixel size and type the image's pixel ratio in pixel per millimeter:

roimanager_set_pixel_size

Note
As for the origin, once the pixel size is set the units in the columns X,Y coordinates and Distance from Origin are changed to millimeter.

Tip
To erase the pixel size and reset the axis units and ROI coordinates back to pixels, just set the pixel ratio to zero.

Colormap

To change the colormap and the color scale, go to Image >> Set colormap:

roimanager_set_colormap

Important
If the ROImanager app was opened as Add-on from the DataViewer app, the button Set colormap from ROImanager is disabled. You can access the colormap settings from the DataViewer interface instead.

Logical mask

To learn how to create or import a logical mask, read this section.

Note
As stated in this section's introduction, a logical mask is useful to exclude unwanted pixels during an analysis function. For instance, the function GSR (removes global variance from the recording) uses the ImagingReferenceFrame file as input and loads the logical mask to include only the pixels inside the mask in the calculation of the global variance. Therefore, if your recordings contain non-pertinent areas, it is advisable to create and save a logical mask to delimit the region of interest.

Rules for ROI fitting

The ROImanager app will automatically detect if the ROIs are over an invalid region of the image. Invalid regions consist of:

  • Regions outside the image boundaries.
  • Areas of the image containing NaNs.
  • Areas outside the selected area using a logical mask.

If the ROI is completely inside an invalid region, it will be deleted. However, if the ROI is partially inside an invalid region, the app will redraw the ROI to exclude the invalid pixels.

Important
For partially invalid ROIs that are very small, there is a risk that the redrawing process yields an empty ROI. In this case, the ROI will be erased and you will be notified.

The example below illustrates the creation of invalid and partially invalid ROIs:


How the ROImanager app deals with invalid (step #2) and partially invalid (step #3) ROIs. Invalid ROIs are deleted while partially invalid ROIs are redrawn.

Import ROIs

One can create ROIs outside umIT and import them into ROImanager. You can import ROIs stored in a variable in a .mat file or directly from the workspace.

The ROIs must be stored in one of the following formats:

  • A 2D logical (Y by X true or false values) matrix
  • A 3D logical (Y by X by Z true of false values) array
  • A 2D labeled (Y by X positive integer values) matrix

Each data format will be imported in a different way:

  • 2D logical matrix: each region of contiguous pixels with TRUE values will be treated as an individual ROI
  • 3D logical array: each frame of the array (Y by X by frame) will be treated as a single ROI
  • 2D labeled matrix: each label will encodes one ROI

Thus, if you want to import multi-region ROIs using logical data types, create a 3D array with an ROI per frame. Alternatively, you can use a 2D labeled matrix to import the ROIs which will give the same results.

Important
In order to import the ROIs, the data arrays must have the same Y,X size of the current frame opened in the ROImanager app!

To import an ROI go to File >> Import ROIs from ... >> (.mat file / workspace) and select the variable containing the ROIs. If the ROIs are stored in a .mat file, a dialog box will open so you can select the file.


Example illustrating the ROI importation. Here, 2 ROIs (one single and one multi-region ROI) are imported from a 2D labeled matrix stored in a variable from Matlab's workspace.

Back to top

Copyright © LabeoTech 2023. This work is licensed under the GNU General Public License, Version 3.0.