Machine Learning Segmentation

▲ QiTissue
Download
What's New?
▲ Hardware Requirement Specifications
▲ Videos
▲ Getting Started
▲ Documentation
FAQ

Machine Learning Segmentation

ML Segmentation - Cellpose and Stardist

QiTissue provides built-in a small selection of carefully crafted segmentation routines that are optimized for a fairly wide variety of image types. These can be further optimized using adjustable parameters. These segmentation routines are based on classical image processing formalisms and algorithms such as mathematical morphology. To give access to a wider selection of segmentation approaches, this section describes an experimental plugin (QI-ML-Segmentation) for Machine Learning (aka deep-learning or artificial intelligence - AI) segmentation. It integrates the well-known Cellpose (https://www.cellpose.org/) and Stardist (https://github.com/stardist/stardist) algorithms as Python-callable routines that work with QiTissue's infrastructure. In addition, for DeepCell (https://deepcell.org/) with its Mesmer deep-learning model there is limited experimental support (see: below ) until its designers support current versions of Python (3.11) and TensorFlow (2.15+). QI-ML-Segmentation only implements the inference or prediction step of the algorithms but can use both pretrained models from the originators and user-provided models. Qi LLC does not provide support for the functioning of the algorithms. Please contact the respective originators of the algorithms for support. The https://image.sc forum is an excellent site to connect with developers and other users.

INSTALLATION

The QI-ML-Segmentation package is provided as a small set of Python scripts which can be downloaded from QI-ML-Segmentation Package, unzipped (on Windows right-click on the .zip file and select Extract All...; on Mac simply double-click on the .zip file), and the resulting ml_segmentation folder (containing the required Python scripts) can be dropped into Documents/QiScripts (a folder that should already exist).

Inside QiTissue, each of the algorithms must be installed (once) into QiTissue's Python environment. Simply select the "install_<name>" script from the Python->ml_segmentation menu for each of the algorithms you plan to use. This will download and install the entire algorithm package which will take a while. The user interface will appear frozen during the installation. This is expected and depending on the speed or the computer and the network may take a few minutes.

INSTRUCTIONS

The QI-ML-Segmentation package has 2 run-routines: 1) run_cellpose which provides a dialog box with options to execute the Cellpose algorithm, and 2) run_stardist, which provides a dialog box with options to execute the Stardist algorithm.

Both routines allow the selection of a pretrained model or a user-provided model, selecting the nuclear and, optionally, a cytoplasm channel (if the algorithm/model supports it), a selection of ROI(s) (if any are defined) to run the algorithm on, and selection of the cytoplasm definition method from QiTissue to use. In addition, each algorithm has a few adjustable parameters whose meaning can be found in the respective documentation. When "Run" is clicked, the package extracts the image data from QiTissue, executes the algorithm in its Python environment, and retrieves the generated masks into QiTissue where cytoplasm determination and feature extraction take place. These steps may take a while, depending on the computer's performance, during which time QiTissue appears frozen but this is expected and requires a bit of patience.

There is experimental support for GPU use to significantly speed up the process but this is highly dependent on the computer's platform, availability of a supported GPU, amount of GPU memory, and this has only had very limited testing. Currently only Apple Silicon-based computers (with M1, M2, M3, or M4 processor) have been tested.

ML Segmentation - Deepcell (experimental)

Deepcell support is highly experimental and is for advanced users only. The below assumes that you have QiTissue and the QI-ML-Segmentation package installed following the instructions above. And it assumes you have executed the installation script for at least one of the packages Cellpose or Stardist. The installation part is one-time only.

Installation

Windows 10/11:

  1. Download and install Python 3.10 from: https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe

  2. Open a CMD terminal (NOTE: replace <name> with your account name):
    cd C:\User\<name>\Qi

  3. Create a Python virtualenv for Deepcell:
    "C:\Users\<name>\AppData\Local\Programs\Python\Python310\python.exe" -c "from virtualenv import cli_run; cli_run(['qi_deepcell_venv'])"

  4. Activate the new virtualenv:

    qi_deepcell_venv\scripts\activate.bat

  5. Install the qi_deepcell package and all dependencies (this will take a bit of time):

    pip install qi_deepcell==0.6.2 --extra-index-url https://gitlab.com/api/v4/groups/qimagingsys/-/packages/pypi/simple

  6. Close the CMD terminal window.

Linux: It is assumed that the Linux AppImage has been unpacked using the –appimage-extract option and that the resulting squashfs directory has been renamed to “QiTissue” in the user’s home directory.

  1. Open a Terminal window. Type "python3 -V" to check the version of the system’s Python version. Versions 3.8, 3.9, and 3.10 are compatible. Otherwise install Python 3.10.

  2. In the Terminal, cd to the Qi directory:
    cd Qi

  3. Set up and create a Python virtualenv for Deepcell:
    pip3 install virtualenv
    python3 -c "from virtualenv import cli_run; cli_run(['qi_deepcell_venv'])"

  4. Activate the new virtualenv:
    source qi_deepcell_venv/bin/activate

  5. Install the qi_deepcell package and all dependencies (this will take a bit of time):
    pip install qi_deepcell==0.6.2 --extra-index-url https://gitlab.com/api/v4/groups/qimagingsys/-/packages/pypi/simple

  6. Deactivate the virtual environment and cd to the home directory:
    deactivate
    cd

Macintosh: M1/M2/M3: Currently no compatible Deepcell package exists for Macs with Apple Silicon (M processor). When that changes, we will provide installation and usage instructions.
Macintosh: Mac/x86: For Macs with Intel-based processor (arm64 or x86), follow the step-by-step Linux instructions above. Any MacOS version Catalina or newer will likely do.

Configuration

After the regular installation of the QI-ML-Segmentation package and the steps above, you need to get a DEEPCELL_ACCESS_TOKEN from the Deepcell Project. Please visit: https://deepcell.readthedocs.io/en/master/API-key.html and obtain your TOKEN from: https://users.deepcell.org/login/

Make your TOKEN available to the QI-ML-Segmentation package by editing the file _deepcell_token.py in your Documents/QiScripts/ml_segmentation folder. Replace the phrase YOUR_OWN_TOKEN_HERE with the TOKEN string. Make sure to leave the quotes. Note that the TOKEN is only valid for 90 days. Remember to obtain a new TOKEN and update the _deepcell_token.py file before it expires.

Usage

As described above for Cellpose and Stardist, use the run_deepcell routine to execute the Deepcell algorithm.