scPortrait – image-based single cell analysis at scale in Python

scPortrait is a scalable toolkit to analyse single-cell image datasets. This Python implementation efficiently segments individual cells, generates single-cell datasets and provides tools for the efficient deep learning classification of their phenotypes for downstream applications.

Installation

Check out the installation instructions here. You can validate your installation by running one of the example notebooks here.

Getting Started

You can check out our worfklow overview or our in-depth tutorial to get started with scPortrait. For more detailed information on the package, checkout the more detailed guides here. You can find a collection of example projects which run on datasets provided within scPortrait to help you get started with here. If you encounter issues feel free to open up a git issue.

Citing our Work

scPortrait was developed by Sophia Mädler and Niklas Schmacke in the labs of Matthias Mann, Veit Hornung and Fabian Theis in 2024 and is actively being developed. If you are interested in contributing please reach out to the developers.

If you use our code please cite the following manuscript:

scPortrait integrates single-cell images into multimodal modeling. Sophia Clara Mädler, Niklas Arndt Schmacke, Alessandro Palma, Altana Namsaraeva, Ali Oğuz Can, Varvara Varlamova, Lukas Heumos, Mahima Arunkumar, Georg Wallmann, Veit Hornung, Fabian J. Theis, Matthias Mann bioRxiv 2025.09.22.677590; doi: https://doi.org/10.1101/2025.09.22.677590

Contributing

We are excited for people to adapt and extend scPortrait to their needs. If you are interested in contributing to scPortrait, please reach out to the developers or open a pull request on our GitHub repository.

Documentation

Ecosystem

• Installation
• Workflow
  • Stitching
  • Segmentation
  • Extraction
  • Featurization
  • Selection
• Tutorials
  • Basic scPortrait Project
  • Segmentation Workflows
  • Fine-tuning the single-cell image extraction
  • Deep Learning in scPortrait
  • Parsing Workflow
  • Stitching Workflow
  • Additional Notebooks

Code Examples

• Code Snippets
• Plotting
• Segmentation

Module API

• pipeline
  • project
  • Project
    • Project.config
    • Project.nuc_seg_name
    • Project.cyto_seg_name
    • Project.sdata_path
    • Project.filehander
    • Project.DEFAULT_IMAGE_DTYPE
    • Project.DEFAULT_SEGMENTATION_DTYPE
    • Project.DEFAULT_SINGLE_CELL_IMAGE_DTYPE
    • Project.sdata
    • Project.update_featurization_f()
    • Project.print_project_status()
    • Project.view_sdata()
    • Project.plot_input_image()
    • Project.plot_he_image()
    • Project.plot_segmentation_masks()
    • Project.plot_single_cell_images()
    • Project.load_input_from_array()
    • Project.load_input_from_tif_files()
    • Project.load_input_from_omezarr()
    • Project.load_input_from_dask()
    • Project.load_input_from_sdata()
    • Project.complete_segmentation()
    • Project.extract()
    • Project.select()
  • segmentation
    • Segmentation
    • ShardedSegmentation
  • segmentation workflows
    • WGASegmentation
    • ShardedWGASegmentation
    • DAPISegmentation
    • ShardedDAPISegmentation
    • DAPISegmentationCellpose
    • ShardedDAPISegmentationCellpose
    • CytosolSegmentationCellpose
    • ShardedCytosolSegmentationCellpose
    • CytosolOnlySegmentationCellpose
    • ShardedCytosolOnlySegmentationCellpose
    • CytosolSegmentationDownsamplingCellpose
    • ShardedCytosolSegmentationDownsamplingCellpose
    • CytosolOnlySegmentationDownsamplingCellpose
    • ShardedCytosolOnlySegmentationDownsamplingCellpose
  • extraction
    • HDF5CellExtraction
  • Featurization
    • MLClusterClassifier
    • EnsembleClassifier
    • CellFeaturizer
    • ConvNeXtFeaturizer
  • selection
    • LMDSelection
• processing
  • images
    • downsample_img_padding()
    • percentile_normalization()
    • EDF()
    • maximum_intensity_projection()
  • masks
    • MatchNucleusCytosolIds
    • SizeFilter
• plotting
  • add_scalebar()
  • cell_grid()
  • cell_grid_multi_channel()
  • cell_grid_single_channel()
  • plot_segmentation_mask()
  • plot_image()
  • plot_labels()
  • generate_composite()
• io
  • read_h5sc()
• tools
  • parse
  • PhenixParser
    • PhenixParser.generate_metadata()
    • PhenixParser.check_for_missing_files()
    • PhenixParser.replace_missing_images()
    • PhenixParser.parse()
    • PhenixParser.sort_wells()
    • PhenixParser.sort_timepoints()
  • CombinedPhenixParser
    • CombinedPhenixParser.get_datasets_to_combine()
  • stitch
  • Stitcher
    • Stitcher.get_stitching_information()
    • Stitcher.save_positions()
    • Stitcher.generate_thumbnail()
    • Stitcher.plot_qc()
    • Stitcher.stitch()
    • Stitcher.write_tif()
    • Stitcher.write_ome_zarr()
    • Stitcher.write_thumbnail()
    • Stitcher.write_spatialdata()
  • ParallelStitcher
    • ParallelStitcher.write_tif_parallel()
  • ml
    • datasets
    • metrics
    • models
    • plmodels
    • pretrained_models
    • transforms
    • utils
  • h5sc
  • get_image_with_cellid()
  • get_image_index()
  • sdata
  • write_image()
  • write_labels()
  • add_element_sdata()
  • rename_image_element()
  • processing (pp)
    • percentile_normalize_image()
    • get_bounding_box_sdata()