Table Of Contents

Search

Enter search terms or a module, class or function name.

ROI Buddy GUI

Introduction

The ROI Buddy GUI can be used for viewing, creating, editing, and tagging the regions of interest (ROIs) associated with multiple SIMA imaging datasets simultaneously. In addition it can be used for registering ROIs from different imaging sessions of the same field-of-view, allowing for the longitudinal tracking of cells in serial imaging experiments.

_images/overview.jpg

Typical Workflow

  • Load multiple SIMA imaging datasets corresponding to different recordings of the same field of view.
  • For each dataset, select the channel you wish to edit and align.
  • Create or load pre-drawn ROIs for each dataset, editing the ROIs as necessary in Edit Mode.
  • Tag cells in one dataset based on some criteria, e.g. morphology.
  • Enter Align mode, bringing all the ROIs into alignment.
  • Choose “Register ROIs” to assign a common id property to overlapping ROIs.
  • Use the merge and unmerge tools to manually fix any incorrect groupings.
  • Once registration is satisfactory, choose “Propagate Tags” to assign the morphology tags to all matched ROIs across imaging sessions.
  • Save ROIs.

Installation

The ROI Buddy GUI has the following dependencies which should be installed prior to installation of ROI Buddy:

In addition, transforming or registering ROIs across sessions requires an optional SIMA dependency:

Once these dependencies are installed, the ROI Buddy can be installed from the Python Package Index using pip.:

$ pip install roibuddy --user

Alternatively, the ROI Buddy GUI can be built from source. Source code for released versions can be downloaded from the Python Package Index, and code under development can be downloaded from the project’s GitHub page.

Once installed, ROI Buddy can be run either by:

$ roibuddy

or:

$ python -m roibuddy

If these commands do not work, check the output of the installation command to determine the directory where the executable was placed, and either add this directory to your path or run the executable directly from that location.

As an alternative, you can also run ROI Buddy from a Docker container, see docker setup.

Windows

After installing SIMA, we recommend installing pre-compiled wheels from (http://www.lfd.uci.edu/~gohlke/pythonlibs/) in this order:

before installing ROI Buddy from the Python Package Index.

Mac OS X

We recommend using MacPorts for installing the dependencies. After installing SIMA using MacPorts as described here, run the following command in Terminal to install an additional dependency:

$ sudo port install py27-pyqwt

Then download and install guidata and guiqwt before installing ROI Buddy from the Python Package Index.

Docker

Docker images are pre-built installations that you can run immediately on your local machine. To run ROI Buddy from a Docker container, first follow the Docker Engine installation instructions for your operating system. You will also need an X Windows server installed on your machine. On linux, this is most likely already installed, newer versions of OS X can install XQuartz, and on Windows we recommend either Xming or MobaXterm.

From a docker terminal run the latest ROI Buddy image (it will automatically be downloaded), with:

$ docker run -it --rm --net=host --env="DISPLAY" -v $HOME/.Xauthority:/root/.Xauthority:rw
    -v /PATH/TO/DATA:/data --name roibuddy losonczylab/roibuddy

If you have issues launching the ROI Buddy image, make sure your DISPLAY environment variable is set correctly to reach the X server that you are running.

User Interface

File Menu

File Menu Option Action
Add T-Series Adds a .sima directory to the list of imaging datasets
Auto add t-series Recursively walk the selected directory and add directories ending in .sima. Optionally a tag argument can be specified, in which case tag must be contained in the .sima directory name
Save current ROIs Save the active ROIList associated with the active imaging dataset
Save all ROIs For each loaded imaging dataset, save the active ROIList with the same name
Edit Label Edit the label property associated with the selected ROI objects. If two polygons in the active ROI List share the same label they are assumed to be disjoint regions comprising a single ROI object.
Add Tags Add comma-delimited strings to the ROI tags property. This feature is useful for tagging ROIs on morphology, genetic identity, etc. and filtering based on this criteria in subsequent analysis
Remove Tags Clear the tags associated with the selected ROIs
Edit Tags Manually edit the list of comma-delimited tag strings associated with the selected ROIs
Merge
  • Edit Mode: If the selected polygons are contiguous, merge them into a single polygon defined by the convex hull containing the selected polygons. If regions are discontiguous, assign them a common label property, indicating that these disjoint structures comprise a single ROI upon saving.
 
  • Align Mode: Select exactly two polygons from different imaging datasets. The selected regions will be assigned the same id property, indicating that they are the same structure imaged during different sessions. The id assigned corresponds to that of the ROI belonging to the largest cluster.
Unmerge Unmerge the selected ROI from any groupings. In both Edit and Align modes, the id property is cleared. In Edit mode, the label property is set to a unique value.
Quit Quit ROI Buddy application

Control Panel

_images/main_panel.jpg

Toggling modes

Edit Mode Toggling to edit mode allows for editing, creation, and deletion of ROIs. In addition, this is the mode in which ROI tagging and labeling takes place.
Align Mode Toggling to align mode allows for the transformation of ROI Lists from separate imaging sessions into a common space, allowing for simultaneous visualization of independently drawn sets. In this view, ROI objects can be deleted (as in the case of singleton ROIs that were perhaps a false positive), and ROIs can be registered across days.

Initializing SIMA imaging dataset and ROI List objects

Remove / Add Add or remove SIMA datasets from the dataset list.
ROI Set A dropdown allowing for selection of the ROI List currently being modified. These ROI Lists correspond to the keys of imagingDataset.ROIs(). By default, the most recently modified ROI List is displayed upon initialization.
New / Delete Set Create or delete ROI Lists for the active SIMA imaging dataset. These lists are stored in the associated imagingDatset.ROIs dictionary.

Registering ROI objects across multiple imaging sessions

If multiple datasets have been loaded from the same field of view, it is possible to align the ROIs and commonly identify them so that they can be tracked across sessions. The currently selected dataset will act as a template to which all other datasets will be aligned. Each dataset is automatically aligned to the template dataset by calculating an affine transformation between time averaged images that produces maximal similarity. A clustering algorithm based on the Jaccard Index is used to match cells between datasets, which can be manually adjusted by merging/unmerging ROIs from the automatic clusters. Once registered, ROIs that are matched across days are assigned the same id property which is denoted visibly by giving them all the same color.

Register ROIs Begin automatic registration using the currently active dataset as the registration template. If datasets do not match, an error dialog will identify the datasets that could be aligned.
Propagate Tags In align mode, the propagate tags button distributes tags across ROI objects from different imaging datasets sharing the same id property. The user can select which tags to propagate. Thus, regions need only be tagged in one dataset, and these tags can be added to other recordings of the same region.

Warning

In align mode, it is necessary that all imaging datasets loaded must be roughly of the same field of view. Alignment is based upon an affine transformation with 6 degrees of freedom. If a transform between time averaged images cannot be calculated, an error message will be displayed printing the directories of the incompatible sets.

Toggling the visibility of ROIs

Show ROIs / All Toggle the visibility of ROI polygons. In align mode, Show All results in the transformation of all ROIs into a common space, allowing for visual inspection of alignment across imaging sessions.

Keyboard shortcuts

m (edit mode):merge separate ROIs into a single ROI object
m (align mode):merge selected ROIs into the same cluster, assigning them the same ID attribute
u (align mode):unmerge ROI from its cluster and assign it a unique ID attribute
f (edit mode):select freeform tool
s (edit mode):select pointer-selection tool
d:delete
r:randomize ROI colors