Quick start

Installation

To use SuperDSM, first install it using conda:

conda install -c bioconda superdsm

Usage

Batch processing

To run SuperDSM from command line, use:

python -m 'superdsm.batch' --help

To export (intermediate) results, use:

python -m 'superdsm.export' --help

For details, see Batch system.

Interactive

To use SuperDSM interactively, i.e. programatically as opposed to batch processing, the first step is to initialize Ray. This is the multiprocessing framework used by SuperDSM. Initialization is simple, just remember to adapt the number of CPUs to be used:

import ray
ray.init(num_cpus=16, log_to_driver=False, logging_level='error')

After this initialization routine, SuperDSM is ready to use:

import superdsm.automation
pipeline = superdsm.pipeline.create_default_pipeline()
cfg = superdsm.config.Config()
data, _, _ = superdsm.automation.process_image(pipeline, cfg, img)

In this example, the default set of hyperparameters will be used. The parameters can be changed using the cfg object (see the Config class API). The available hyperparameters are described in the documentation of the respective stages employed in the pipeline created by the create_default_pipeline() function.

The variable img must be a two-dimensional numpy.ndarray object which represents the raw image intensities. Images can be loaded from file using imread().

The pipeline data object data is a dictionary containing all the intermediate results which might be necessary for further computations. This can also be used to obtain a graphical representation of the segmentation results:

import superdsm.render
seg = superdsm.render.render_result_over_image(data)

The seg object returned by the render_result_over_image() function is an RGB image (represented by a numpy.ndarray object) which can be visualized directly (e.g., using matplotlib) or saved for later use (e.g., using imwrite()). Use rasterize_labels() to obtain segmentation masks from the pipeline data object.

References

If you use SuperDSM, please cite:

  • L. Kostrykin and K. Rohr, “Robust Graph Pruning for Efficient Segmentation and Cluster Splitting of Cell Nuclei using Deformable Shape Models,” accepted for presentation at IEEE International Symposium on Biomedical Imaging (ISBI), Athens, Greece, May 27–30, 2024.

  • L. Kostrykin and K. Rohr, “Superadditivity and Convex Optimization for Globally Optimal Cell Segmentation Using Deformable Shape Models,” in IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI), vol. 45(3), pp. 3831–3847, 2023. [doi]