Cellpose API Guide
Cellpose class
- class cellpose.models.Cellpose(gpu=False, model_type='cyto3', device=None)[source]
Main model which combines SizeModel and CellposeModel.
- Parameters
gpu (bool, optional) – Whether or not to use GPU, will check if GPU available. Defaults to False.
model_type (str, optional) – Model type. “cyto”=cytoplasm model; “nuclei”=nucleus model; “cyto2”=cytoplasm model with additional user images; “cyto3”=super-generalist model; Defaults to “cyto3”.
device (torch device, optional) – Device used for model running / training. Overrides gpu input. Recommended if you want to use a specific GPU (e.g. torch.device(“cuda:1”)). Defaults to None.
- device
Device used for model running / training.
- Type
torch device
- gpu
Flag indicating if GPU is used.
- Type
bool
- diam_mean
Mean diameter for cytoplasm model.
- Type
float
- cp
CellposeModel instance.
- Type
- pretrained_size
Pretrained size model path.
- Type
str
- eval(x, batch_size=8, channels=[0, 0], channel_axis=None, invert=False, normalize=True, diameter=30.0, do_3D=False, **kwargs)[source]
Run cellpose size model and mask model and get masks.
- Parameters
x (list or array) – List or array of images. Can be list of 2D/3D images, or array of 2D/3D images, or 4D image array.
batch_size (int, optional) – Number of 224x224 patches to run simultaneously on the GPU. Can make smaller or bigger depending on GPU memory usage. Defaults to 8.
channels (list, optional) – List of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to [0,0].
channel_axis (int, optional) – If None, channels dimension is attempted to be automatically determined. Defaults to None.
invert (bool, optional) – Invert image pixel intensity before running network (if True, image is also normalized). Defaults to False.
normalize (bool, optional) – If True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (see CellposeModel for details). Defaults to True.
diameter (float, optional) – If set to None, then diameter is automatically estimated if size model is loaded. Defaults to 30..
do_3D (bool, optional) – Set to True to run 3D segmentation on 4D image input. Defaults to False.
- Returns
- tuple containing
masks (list of 2D arrays or single 3D array): Labelled image, where 0=no masks; 1,2,…=mask labels.
- flows (list of lists 2D arrays or list of 3D arrays):
flows[k][0] = XY flow in HSV 0-255
flows[k][1] = XY flows at each pixel
flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics)
flows[k][3] = final pixel locations after Euler integration
styles (list of 1D arrays of length 256 or single 1D array): Style vector summarizing each image, also used to estimate size of objects in image.
diams (list of diameters or float): List of diameters or float (if do_3D=True).
CellposeModel
- class cellpose.models.CellposeModel(gpu=False, pretrained_model=False, model_type=None, diam_mean=30.0, device=None, nchan=2)[source]
Class representing a Cellpose model.
- diam_mean
Mean “diameter” value for the model.
- Type
float
- builtin
Whether the model is a built-in model or not.
- Type
bool
- device
Device used for model running / training.
- Type
torch device
- mkldnn
MKLDNN flag for the model.
- Type
None or bool
- nchan
Number of channels used as input to the network.
- Type
int
- nclasses
Number of classes in the model.
- Type
int
- nbase
List of base values for the model.
- Type
list
- pretrained_model
Full path to pretrained cellpose model(s).
- Type
str or list of strings
- diam_labels
Diameter labels of the model.
- Type
numpy array
- net_type
Type of the network.
- Type
str
- __init__(self, gpu=False, pretrained_model=False, model_type=None, diam_mean=30., device=None, nchan=2)[source]
Initialize the CellposeModel.
- eval(self, x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile=True, tile_overlap=0.1, bsize=224, interp=True, compute_masks=True, progress=None)[source]
Segment list of images x, or 4D array - Z x nchan x Y x X.
- eval(x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile=True, tile_overlap=0.1, bsize=224, interp=True, compute_masks=True, progress=None)[source]
segment list of images x, or 4D array - Z x nchan x Y x X
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
resample (bool, optional) – run dynamics at original image size (will be slower but create more accurate boundaries). Defaults to True.
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – invert image pixel intensity before running network. Defaults to False.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float, optional) – diameter for each image, if diameter is None, set to diam_mean or diam_train if available. Defaults to None.
flow_threshold (float, optional) – flow error threshold (all cells with errors below threshold are kept) (not used for 3D). Defaults to 0.4.
cellprob_threshold (float, optional) – all pixels with value above threshold kept for masks, decrease to find more and larger masks. Defaults to 0.0.
do_3D (bool, optional) – set to True to run 3D segmentation on 3D/4D image input. Defaults to False.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
stitch_threshold (float, optional) – if stitch_threshold>0.0 and not do_3D, masks are stitched in 3D to return volume segmentation. Defaults to 0.0.
min_size (int, optional) – all ROIs below this size, in pixels, will be discarded. Defaults to 15.
niter (int, optional) – number of iterations for dynamics computation. if None, it is set proportional to the diameter. Defaults to None.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – block size for tiles, recommended to keep at 224, like in training. Defaults to 224.
interp (bool, optional) – interpolate during 2D dynamics (not available in 3D) . Defaults to True.
compute_masks (bool, optional) – Whether or not to compute dynamics and return masks. This is set to False when retrieving the styles for the size model. Defaults to True.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.
- Returns
masks (list, np.ndarray): labelled image(s), where 0=no masks; 1,2,…=mask labels
flows (list): list of lists: flows[k][0] = XY flow in HSV 0-255; flows[k][1] = XY(Z) flows at each pixel; flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics); flows[k][3] = final pixel locations after Euler integration
styles (list, np.ndarray): style vector summarizing each image of size 256.
- Return type
A tuple containing
CellposeDenoiseModel
- class cellpose.denoise.CellposeDenoiseModel(gpu=False, pretrained_model=False, model_type=None, restore_type='denoise_cyto3', chan2_restore=False, device=None)[source]
model to run Cellpose and Image restoration
- eval(x, batch_size=8, channels=None, channel_axis=None, z_axis=None, normalize=True, rescale=None, diameter=None, tile=True, tile_overlap=0.1, augment=False, resample=True, invert=False, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, interp=True)[source]
Restore array or list of images using the image restoration model, and then segment.
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float, optional) – diameter for each image, if diameter is None, set to diam_mean or diam_train if available. Defaults to None.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
augment (bool, optional) – augment tiles by flipping and averaging for segmentation. Defaults to False.
resample (bool, optional) – run dynamics at original image size (will be slower but create more accurate boundaries). Defaults to True.
invert (bool, optional) – invert image pixel intensity before running network. Defaults to False.
flow_threshold (float, optional) – flow error threshold (all cells with errors below threshold are kept) (not used for 3D). Defaults to 0.4.
cellprob_threshold (float, optional) – all pixels with value above threshold kept for masks, decrease to find more and larger masks. Defaults to 0.0.
do_3D (bool, optional) – set to True to run 3D segmentation on 3D/4D image input. Defaults to False.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
stitch_threshold (float, optional) – if stitch_threshold>0.0 and not do_3D, masks are stitched in 3D to return volume segmentation. Defaults to 0.0.
min_size (int, optional) – all ROIs below this size, in pixels, will be discarded. Defaults to 15.
niter (int, optional) – number of iterations for dynamics computation. if None, it is set proportional to the diameter. Defaults to None.
interp (bool, optional) – interpolate during 2D dynamics (not available in 3D) . Defaults to True.
- Returns
labelled image(s), where 0=no masks; 1,2,…=mask labels flows (list): list of lists: flows[k][0] = XY flow in HSV 0-255; flows[k][1] = XY(Z) flows at each pixel; flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics); flows[k][3] = final pixel locations after Euler integration styles (list, np.ndarray): style vector summarizing each image of size 256. imgs (list of 2D/3D arrays): Restored images
- Return type
masks (list, np.ndarray)
DenoiseModel
- class cellpose.denoise.DenoiseModel(gpu=False, pretrained_model=False, nchan=1, model_type=None, chan2=False, diam_mean=30.0, device=None)[source]
DenoiseModel class for denoising images using Cellpose denoising model.
- Parameters
gpu (bool, optional) – Whether to use GPU for computation. Defaults to False.
pretrained_model (bool or str or Path, optional) – Pretrained model to use for denoising. Can be a string or path. Defaults to False.
nchan (int, optional) – Number of channels in the input images, all Cellpose 3 models were trained with nchan=1. Defaults to 1.
model_type (str, optional) – Type of pretrained model to use (“denoise_cyto3”, “deblur_cyto3”, “upsample_cyto3”, …). Defaults to None.
chan2 (bool, optional) – Whether to use a separate model for the second channel. Defaults to False.
diam_mean (float, optional) – Mean diameter of the objects in the images. Defaults to 30.0.
device (torch.device, optional) – Device to use for computation. Defaults to None.
- nchan
Number of channels in the input images.
- Type
int
- diam_mean
Mean diameter of the objects in the images.
- Type
float
- pretrained_model
Pretrained model path to use for denoising.
- Type
bool or str or Path
- net_type
Type of the denoising network.
- Type
str
- eval(x, batch_size=8, channels=None, channel_axis=None, z_axis=None,
normalize=True, rescale=None, diameter=None, tile=True, tile_overlap=0.1)
Denoise array or list of images using the denoising model.
- _eval(net, x, normalize=True, rescale=None, diameter=None, tile=True,
tile_overlap=0.1)
Run denoising model on a single channel.
- eval(x, batch_size=8, channels=None, channel_axis=None, z_axis=None, normalize=True, rescale=None, diameter=None, tile=True, tile_overlap=0.1)[source]
Restore array or list of images using the image restoration model.
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float, optional) – diameter for each image, if diameter is None, set to diam_mean or diam_train if available. Defaults to None.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
- Returns
Restored images
- Return type
imgs (list of 2D/3D arrays)
SizeModel
- class cellpose.models.SizeModel(cp_model, device=None, pretrained_size=None, **kwargs)[source]
Linear regression model for determining the size of objects in image used to rescale before input to cp_model. Uses styles from cp_model.
- pretrained_size
Path to pretrained size model.
- Type
str
- cp
Model from which to get styles.
- Type
UnetModel or CellposeModel
- device
Device used for model running / training (torch.device(“cuda”) or torch.device(“cpu”)), overrides gpu input, recommended if you want to use a specific GPU (e.g. torch.device(“cuda:1”)).
- Type
torch device
- diam_mean
Mean diameter of objects.
- Type
float
- eval(self, x, channels=None, channel_axis=None, normalize=True, invert=False,
augment=False, tile=True, batch_size=8, progress=None, interp=True):
Use images x to produce style or use style input to predict size of objects in image.
- Raises
ValueError – If no pretrained cellpose model is specified, cannot compute size.
- eval(x, channels=None, channel_axis=None, normalize=True, invert=False, augment=False, tile=True, batch_size=8, progress=None)[source]
Use images x to produce style or use style input to predict size of objects in image.
Object size estimation is done in two steps: 1. Use a linear regression model to predict size from style in image. 2. Resize image to predicted size and run CellposeModel to get output masks.
Take the median object size of the predicted masks as the final predicted size.
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – Invert image pixel intensity before running network (if True, image is also normalized). Defaults to False.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.
- Returns
diam (np.ndarray): Final estimated diameters from images x or styles style after running both steps.
diam_style (np.ndarray): Estimated diameters from style alone.
- Return type
A tuple containing
Training
- cellpose.train.train_seg(net, train_data=None, train_labels=None, train_files=None, train_labels_files=None, train_probs=None, test_data=None, test_labels=None, test_files=None, test_labels_files=None, test_probs=None, load_files=True, batch_size=8, learning_rate=0.005, n_epochs=2000, weight_decay=1e-05, momentum=0.9, SGD=False, channels=None, channel_axis=None, normalize=True, compute_flows=False, save_path=None, save_every=100, nimg_per_epoch=None, nimg_test_per_epoch=None, rescale=True, min_train_masks=5, model_name=None)[source]
Train the network with images for segmentation.
- Parameters
net (object) – The network model to train.
train_data (List[np.ndarray], optional) – List of arrays (2D or 3D) - images for training. Defaults to None.
train_labels (List[np.ndarray], optional) – List of arrays (2D or 3D) - labels for train_data, where 0=no masks; 1,2,…=mask labels. Defaults to None.
train_files (List[str], optional) – List of strings - file names for images in train_data (to save flows for future runs). Defaults to None.
train_labels_files (List[str], optional) – List of strings - file names for labels in train_labels. Defaults to None.
train_probs (List[float], optional) – List of floats - probabilities for each image to be selected during training. Defaults to None.
test_data (List[np.ndarray], optional) – List of arrays (2D or 3D) - images for testing. Defaults to None.
test_labels (List[np.ndarray], optional) – List of arrays (2D or 3D) - labels for test_data, where 0=no masks; 1,2,…=mask labels. Defaults to None.
test_files (List[str], optional) – List of strings - file names for images in test_data (to save flows for future runs). Defaults to None.
test_labels_files (List[str], optional) – List of strings - file names for labels in test_labels. Defaults to None.
test_probs (List[float], optional) – List of floats - probabilities for each image to be selected during testing. Defaults to None.
load_files (bool, optional) – Boolean - whether to load images and labels from files. Defaults to True.
batch_size (int, optional) – Integer - number of patches to run simultaneously on the GPU. Defaults to 8.
learning_rate (float or List[float], optional) – Float or list/np.ndarray - learning rate for training. Defaults to 0.005.
n_epochs (int, optional) – Integer - number of times to go through the whole training set during training. Defaults to 2000.
weight_decay (float, optional) – Float - weight decay for the optimizer. Defaults to 1e-5.
momentum (float, optional) – Float - momentum for the optimizer. Defaults to 0.9.
SGD (bool, optional) – Boolean - whether to use SGD as optimization instead of RAdam. Defaults to False.
channels (List[int], optional) – List of ints - channels to use for training. Defaults to None.
channel_axis (int, optional) – Integer - axis of the channel dimension in the input data. Defaults to None.
normalize (bool or dict, optional) – Boolean or dictionary - whether to normalize the data. Defaults to True.
compute_flows (bool, optional) – Boolean - whether to compute flows during training. Defaults to False.
save_path (str, optional) – String - where to save the trained model. Defaults to None.
save_every (int, optional) – Integer - save the network every [save_every] epochs. Defaults to 100.
nimg_per_epoch (int, optional) – Integer - minimum number of images to train on per epoch. Defaults to None.
nimg_test_per_epoch (int, optional) – Integer - minimum number of images to test on per epoch. Defaults to None.
rescale (bool, optional) – Boolean - whether or not to rescale images during training. Defaults to True.
min_train_masks (int, optional) – Integer - minimum number of masks an image must have to use in the training set. Defaults to 5.
model_name (str, optional) – String - name of the network. Defaults to None.
- Returns
path to saved model weights
- Return type
Path
- cellpose.train.train_size(net, pretrained_model, train_data=None, train_labels=None, train_files=None, train_labels_files=None, train_probs=None, test_data=None, test_labels=None, test_files=None, test_labels_files=None, test_probs=None, load_files=True, min_train_masks=5, channels=None, channel_axis=None, normalize=True, nimg_per_epoch=None, nimg_test_per_epoch=None, batch_size=128, l2_regularization=1.0, n_epochs=10)[source]
Train the size model.
- Parameters
net (object) – The neural network model.
pretrained_model (str) – The path to the pretrained model.
train_data (numpy.ndarray, optional) – The training data. Defaults to None.
train_labels (numpy.ndarray, optional) – The training labels. Defaults to None.
train_files (list, optional) – The training file paths. Defaults to None.
train_labels_files (list, optional) – The training label file paths. Defaults to None.
train_probs (numpy.ndarray, optional) – The training probabilities. Defaults to None.
test_data (numpy.ndarray, optional) – The test data. Defaults to None.
test_labels (numpy.ndarray, optional) – The test labels. Defaults to None.
test_files (list, optional) – The test file paths. Defaults to None.
test_labels_files (list, optional) – The test label file paths. Defaults to None.
test_probs (numpy.ndarray, optional) – The test probabilities. Defaults to None.
load_files (bool, optional) – Whether to load files. Defaults to True.
min_train_masks (int, optional) – The minimum number of training masks. Defaults to 5.
channels (list, optional) – The channels. Defaults to None.
channel_axis (int, optional) – The channel axis. Defaults to None.
normalize (bool or dict, optional) – Whether to normalize the data. Defaults to True.
nimg_per_epoch (int, optional) – The number of images per epoch. Defaults to None.
nimg_test_per_epoch (int, optional) – The number of test images per epoch. Defaults to None.
batch_size (int, optional) – The batch size. Defaults to 128.
l2_regularization (float, optional) – The L2 regularization factor. Defaults to 1.0.
n_epochs (int, optional) – The number of epochs. Defaults to 10.
- Returns
The trained size model parameters.
- Return type
dict
Metrics
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.metrics.aggregated_jaccard_index(masks_true, masks_pred)[source]
AJI = intersection of all matched masks / union of all masks
- Parameters
masks_true (list of np.ndarrays (int) or np.ndarray (int)) – where 0=NO masks; 1,2… are mask labels
masks_pred (list of np.ndarrays (int) or np.ndarray (int)) – np.ndarray (int) where 0=NO masks; 1,2… are mask labels
- Returns
aggregated jaccard index for each set of masks
- Return type
aji (float)
- cellpose.metrics.average_precision(masks_true, masks_pred, threshold=[0.5, 0.75, 0.9])[source]
Average precision estimation: AP = TP / (TP + FP + FN)
This function is based heavily on the fast stardist matching functions (https://github.com/mpicbg-csbd/stardist/blob/master/stardist/matching.py)
- Parameters
masks_true (list of np.ndarrays (int) or np.ndarray (int)) – where 0=NO masks; 1,2… are mask labels
masks_pred (list of np.ndarrays (int) or np.ndarray (int)) – np.ndarray (int) where 0=NO masks; 1,2… are mask labels
- Returns
average precision at thresholds tp (array [len(masks_true) x len(threshold)]):
number of true positives at thresholds
- fp (array [len(masks_true) x len(threshold)]):
number of false positives at thresholds
- fn (array [len(masks_true) x len(threshold)]):
number of false negatives at thresholds
- Return type
ap (array [len(masks_true) x len(threshold)])
- cellpose.metrics.boundary_scores(masks_true, masks_pred, scales)[source]
Calculate boundary precision, recall, and F-score.
- Parameters
masks_true (list) – List of true masks.
masks_pred (list) – List of predicted masks.
scales (list) – List of scales.
- Returns
A tuple containing precision, recall, and F-score arrays.
- Return type
tuple
- cellpose.metrics.flow_error(maski, dP_net, device=None)[source]
Error in flows from predicted masks vs flows predicted by network run on image.
This function serves to benchmark the quality of masks. It works as follows: 1. The predicted masks are used to create a flow diagram. 2. The mask-flows are compared to the flows that the network predicted.
If there is a discrepancy between the flows, it suggests that the mask is incorrect. Masks with flow_errors greater than 0.4 are discarded by default. This setting can be changed in Cellpose.eval or CellposeModel.eval.
- Parameters
maski (np.ndarray, int) – Masks produced from running dynamics on dP_net, where 0=NO masks; 1,2… are mask labels.
dP_net (np.ndarray, float) – ND flows where dP_net.shape[1:] = maski.shape.
- Returns
Mean squared error between predicted flows and flows from masks. dP_masks (np.ndarray, float): ND flows produced from the predicted masks.
- Return type
flow_errors (np.ndarray, float)
Flows to masks
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.dynamics.compute_masks(dP, cellprob, p=None, niter=200, cellprob_threshold=0.0, flow_threshold=0.4, interp=True, do_3D=False, min_size=15, device=None)[source]
Compute masks using dynamics from dP and cellprob.
- Parameters
dP (numpy.ndarray) – The dynamics flow field array.
cellprob (numpy.ndarray) – The cell probability array.
p (numpy.ndarray, optional) – The pixels on which to run dynamics. Defaults to None
niter (int, optional) – The number of iterations for mask computation. Defaults to 200.
cellprob_threshold (float, optional) – The threshold for cell probability. Defaults to 0.0.
flow_threshold (float, optional) – The threshold for quality control metrics. Defaults to 0.4.
interp (bool, optional) – Whether to interpolate during dynamics computation. Defaults to True.
do_3D (bool, optional) – Whether to perform mask computation in 3D. Defaults to False.
min_size (int, optional) – The minimum size of the masks. Defaults to 15.
device (str, optional) – The torch device to use for computation. Defaults to None.
- Returns
A tuple containing the computed masks and the final pixel locations.
- Return type
tuple
- cellpose.dynamics.follow_flows(dP, mask=None, niter=200, interp=True, device=None)[source]
Run dynamics to recover masks in 2D or 3D.
Pixels are represented as a meshgrid. Only pixels with non-zero cell-probability are used (as defined by inds).
- Parameters
dP (np.ndarray) – Flows [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
mask (np.ndarray, optional) – Pixel mask to seed masks. Useful when flows have low magnitudes.
niter (int, optional) – Number of iterations of dynamics to run. Default is 200.
interp (bool, optional) – Interpolate during 2D dynamics (not available in 3D). Default is True.
use_gpu (bool, optional) – Use GPU to run interpolated dynamics (faster than CPU). Default is False.
- Returns
p (np.ndarray): Final locations of each pixel after dynamics; [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
inds (np.ndarray): Indices of pixels used for dynamics; [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
- Return type
tuple containing
- cellpose.dynamics.get_centers(masks, slices)
Get the centers of the masks and their extents.
- Parameters
masks (ndarray) – The labeled masks.
slices (ndarray) – The slices of the masks.
- Returns
- tuple containing
centers (ndarray): The centers of the masks.
ext (ndarray): The extents of the masks.
- cellpose.dynamics.get_masks(p, iscell=None, rpad=20)[source]
Create masks using pixel convergence after running dynamics.
Makes a histogram of final pixel locations p, initializes masks at peaks of histogram and extends the masks from the peaks so that they include all pixels with more than 2 final pixels p. Discards masks with flow errors greater than the threshold.
- Parameters
p (float32, 3D or 4D array) – Final locations of each pixel after dynamics, size [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
iscell (bool, 2D or 3D array) – If iscell is not None, set pixels that are iscell False to stay in their original location.
rpad (int, optional) – Histogram edge padding. Default is 20.
- Returns
- Masks with inconsistent flow masks removed,
0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].
- Return type
M0 (int, 2D or 3D array)
- cellpose.dynamics.labels_to_flows(labels, files=None, device=None, redo_flows=False, niter=None)[source]
Converts labels (list of masks or flows) to flows for training model.
- Parameters
labels (list of ND-arrays) – The labels to convert. labels[k] can be 2D or 3D. If [3 x Ly x Lx], it is assumed that flows were precomputed. Otherwise, labels[k][0] or labels[k] (if 2D) is used to create flows and cell probabilities.
files (list of str, optional) – The files to save the flows to. If provided, flows are saved to files to be reused. Defaults to None.
device (str, optional) – The device to use for computation. Defaults to None.
redo_flows (bool, optional) – Whether to recompute the flows. Defaults to False.
niter (int, optional) – The number of iterations for computing flows. Defaults to None.
- Returns
The flows for training the model. flows[k][0] is labels[k], flows[k][1] is cell distance transform, flows[k][2] is Y flow, flows[k][3] is X flow, and flows[k][4] is heat distribution.
- Return type
list of [4 x Ly x Lx] arrays
- cellpose.dynamics.map_coordinates(I, yc, xc, Y)
Bilinear interpolation of image “I” in-place with y-coordinates yc and x-coordinates xc to Y.
- Parameters
I (numpy.ndarray) – Input image of shape (C, Ly, Lx).
yc (numpy.ndarray) – New y-coordinates.
xc (numpy.ndarray) – New x-coordinates.
Y (numpy.ndarray) – Output array of shape (C, ni).
- Returns
None
- cellpose.dynamics.masks_to_flows(masks, device=None, niter=None)[source]
Convert masks to flows using diffusion from center pixel.
Center of masks where diffusion starts is defined to be the closest pixel to the mean of all pixels that is inside the mask. Result of diffusion is converted into flows by computing the gradients of the diffusion density map.
- Parameters
masks (int, 2D or 3D array) – Labelled masks 0=NO masks; 1,2,…=mask labels
- Returns
- Flows in Y = mu[-2], flows in X = mu[-1].
If masks are 3D, flows in Z = mu[0].
- Return type
mu (float, 3D or 4D array)
- cellpose.dynamics.masks_to_flows_cpu(masks, device=None, niter=None)[source]
Convert masks to flows using diffusion from center pixel.
Center of masks where diffusion starts is defined to be the closest pixel to the mean of all pixels that is inside the mask. Result of diffusion is converted into flows by computing the gradients of the diffusion density map.
- Parameters
masks (int, 2D or 3D array) – Labelled masks 0=NO masks; 1,2,…=mask labels
- Returns
- tuple containing
- mu (float, 3D or 4D array): Flows in Y = mu[-2], flows in X = mu[-1].
If masks are 3D, flows in Z = mu[0].
meds (float, 2D or 3D array): cell centers
- cellpose.dynamics.masks_to_flows_gpu(masks, device=None, niter=None)[source]
Convert masks to flows using diffusion from center pixel.
Center of masks where diffusion starts is defined using COM.
- Parameters
masks (int, 2D or 3D array) – Labelled masks. 0=NO masks; 1,2,…=mask labels.
- Returns
- tuple containing
- mu (float, 3D or 4D array): Flows in Y = mu[-2], flows in X = mu[-1].
If masks are 3D, flows in Z = mu[0].
meds_p (float, 2D or 3D array): cell centers
- cellpose.dynamics.masks_to_flows_gpu_3d(masks, device=None)[source]
Convert masks to flows using diffusion from center pixel.
- Parameters
masks (int, 2D or 3D array) – Labelled masks. 0=NO masks; 1,2,…=mask labels.
- Returns
- tuple containing
mu (float, 3D or 4D array): Flows in Y = mu[-2], flows in X = mu[-1]. If masks are 3D, flows in Z = mu[0].
mu_c (float, 2D or 3D array): zeros
- cellpose.dynamics.remove_bad_flow_masks(masks, flows, threshold=0.4, device=None)[source]
Remove masks which have inconsistent flows.
Uses metrics.flow_error to compute flows from predicted masks and compare flows to predicted flows from the network. Discards masks with flow errors greater than the threshold.
- Parameters
masks (int, 2D or 3D array) – Labelled masks, 0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].
flows (float, 3D or 4D array) – Flows [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
threshold (float, optional) – Masks with flow error greater than threshold are discarded. Default is 0.4.
- Returns
- Masks with inconsistent flow masks removed,
0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].
- Return type
masks (int, 2D or 3D array)
- cellpose.dynamics.resize_and_compute_masks(dP, cellprob, p=None, niter=200, cellprob_threshold=0.0, flow_threshold=0.4, interp=True, do_3D=False, min_size=15, resize=None, device=None)[source]
Compute masks using dynamics from dP and cellprob, and resizes masks if resize is not None.
- Parameters
dP (numpy.ndarray) – The dynamics flow field array.
cellprob (numpy.ndarray) – The cell probability array.
p (numpy.ndarray, optional) – The pixels on which to run dynamics. Defaults to None
niter (int, optional) – The number of iterations for mask computation. Defaults to 200.
cellprob_threshold (float, optional) – The threshold for cell probability. Defaults to 0.0.
flow_threshold (float, optional) – The threshold for quality control metrics. Defaults to 0.4.
interp (bool, optional) – Whether to interpolate during dynamics computation. Defaults to True.
do_3D (bool, optional) – Whether to perform mask computation in 3D. Defaults to False.
min_size (int, optional) – The minimum size of the masks. Defaults to 15.
resize (tuple, optional) – The desired size for resizing the masks. Defaults to None.
device (str, optional) – The torch device to use for computation. Defaults to None.
- Returns
A tuple containing the computed masks and the final pixel locations.
- Return type
tuple
- cellpose.dynamics.steps2D(p, dP, inds, niter)
Run dynamics of pixels to recover masks in 2D.
Euler integration of dynamics dP for niter steps.
- Parameters
p (np.ndarray) – Pixel locations [axis x Ly x Lx] (start at initial meshgrid).
dP (np.ndarray) – Flows [axis x Ly x Lx].
inds (np.ndarray) – Non-zero pixels to run dynamics on [npixels x 2].
niter (int) – Number of iterations of dynamics to run.
- Returns
Final locations of each pixel after dynamics.
- Return type
np.ndarray
- cellpose.dynamics.steps2D_interp(p, dP, niter, device=None)[source]
Run dynamics of pixels to recover masks in 2D, with interpolation between pixel values.
Euler integration of dynamics dP for niter steps.
- Parameters
p (numpy.ndarray) – Array of shape (n_points, 2) representing the initial pixel locations.
dP (numpy.ndarray) – Array of shape (2, Ly, Lx) representing the flow field.
niter (int) – Number of iterations to perform.
device (torch.device, optional) – Device to use for computation. Defaults to None.
- Returns
Array of shape (n_points, 2) representing the final pixel locations.
- Return type
numpy.ndarray
- Raises
None –
- cellpose.dynamics.steps3D(p, dP, inds, niter)
Run dynamics of pixels to recover masks in 3D.
Euler integration of dynamics dP for niter steps.
- Parameters
p (np.ndarray) – Pixel locations [axis x Lz x Ly x Lx] (start at initial meshgrid).
dP (np.ndarray) – Flows [axis x Lz x Ly x Lx].
inds (np.ndarray) – Non-zero pixels to run dynamics on [npixels x 3].
niter (int) – Number of iterations of dynamics to run.
- Returns
Final locations of each pixel after dynamics.
- Return type
np.ndarray
Image transforms
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.transforms.average_tiles(y, ysub, xsub, Ly, Lx)[source]
Average the results of the network over tiles.
- Parameters
y (float) – Output of cellpose network for each tile. Shape: [ntiles x nclasses x bsize x bsize]
ysub (list) – List of arrays with start and end of tiles in Y of length ntiles
xsub (list) – List of arrays with start and end of tiles in X of length ntiles
Ly (int) – Size of pre-tiled image in Y (may be larger than original image if image size is less than bsize)
Lx (int) – Size of pre-tiled image in X (may be larger than original image if image size is less than bsize)
- Returns
Network output averaged over tiles. Shape: [nclasses x Ly x Lx]
- Return type
yf (float32)
- cellpose.transforms.convert_image(x, channels, channel_axis=None, z_axis=None, do_3D=False, nchan=2)[source]
Converts the image to have the z-axis first, channels last, and normalized intensities.
- Parameters
x (numpy.ndarray or torch.Tensor) – The input image.
channels (list or None) – The list of channels to use (ones-based, 0=gray). If None, all channels are kept.
channel_axis (int or None) – The axis of the channels in the input image. If None, the axis is determined automatically.
z_axis (int or None) – The axis of the z-dimension in the input image. If None, the axis is determined automatically.
do_3D (bool) – Whether to process the image in 3D mode. Defaults to False.
nchan (int) – The number of channels to keep if the input image has more than nchan channels.
- Returns
The converted image.
- Return type
numpy.ndarray
- Raises
ValueError – If the input image has less than two channels and channels are not specified.
ValueError – If the input image is 2D and do_3D is True.
ValueError – If the input image is 4D and do_3D is False.
- cellpose.transforms.gaussian_kernel(sigma, Ly, Lx, device=torch.device)[source]
Generates a 2D Gaussian kernel.
- Parameters
sigma (float) – Standard deviation of the Gaussian distribution.
Ly (int) – Number of pixels in the y-axis.
Lx (int) – Number of pixels in the x-axis.
device (torch.device, optional) – Device to store the kernel tensor. Defaults to torch.device(“cpu”).
- Returns
2D Gaussian kernel tensor.
- Return type
torch.Tensor
- cellpose.transforms.make_tiles(imgi, bsize=224, augment=False, tile_overlap=0.1)[source]
Make tiles of image to run at test-time.
- Parameters
imgi (np.ndarray) – Array of shape (nchan, Ly, Lx) representing the input image.
bsize (int, optional) – Size of tiles. Defaults to 224.
augment (bool, optional) – Whether to flip tiles and set tile_overlap=2. Defaults to False.
tile_overlap (float, optional) – Fraction of overlap of tiles. Defaults to 0.1.
- Returns
- tuple containing
IMG (np.ndarray): Array of shape (ntiles, nchan, bsize, bsize) representing the tiles.
ysub (list): List of arrays with start and end of tiles in Y of length ntiles.
xsub (list): List of arrays with start and end of tiles in X of length ntiles.
Ly (int): Height of the input image.
Lx (int): Width of the input image.
- cellpose.transforms.move_axis(img, m_axis=-1, first=True)[source]
move axis m_axis to first or last position
- cellpose.transforms.move_min_dim(img, force=False)[source]
Move the minimum dimension last as channels if it is less than 10 or force is True.
- Parameters
img (ndarray) – The input image.
force (bool, optional) – If True, the minimum dimension will always be moved. Defaults to False.
- Returns
The image with the minimum dimension moved to the last axis as channels.
- Return type
ndarray
- cellpose.transforms.normalize99(Y, lower=1, upper=99, copy=True)[source]
Normalize the image so that 0.0 corresponds to the 1st percentile and 1.0 corresponds to the 99th percentile.
- Parameters
Y (ndarray) – The input image.
lower (int, optional) – The lower percentile. Defaults to 1.
upper (int, optional) – The upper percentile. Defaults to 99.
copy (bool, optional) – Whether to create a copy of the input image. Defaults to True.
- Returns
The normalized image.
- Return type
ndarray
- cellpose.transforms.normalize99_tile(img, blocksize=100, lower=1.0, upper=99.0, tile_overlap=0.1, norm3D=False, smooth3D=1, is3D=False)[source]
Compute normalization like normalize99 function but in tiles.
- Parameters
img (numpy.ndarray) – Array of shape (Lz x) Ly x Lx (x nchan) containing the image.
blocksize (float, optional) – Size of tiles. Defaults to 100.
lower (float, optional) – Lower percentile for normalization. Defaults to 1.0.
upper (float, optional) – Upper percentile for normalization. Defaults to 99.0.
tile_overlap (float, optional) – Fraction of overlap of tiles. Defaults to 0.1.
norm3D (bool, optional) – Use same tiled normalization for each z-plane. Defaults to False.
smooth3D (int, optional) – Smoothing factor for 3D normalization. Defaults to 1.
is3D (bool, optional) – Set to True if image is a 3D stack. Defaults to False.
- Returns
Normalized image array of shape (Lz x) Ly x Lx (x nchan).
- Return type
numpy.ndarray
- cellpose.transforms.normalize_img(img, normalize=True, norm3D=False, invert=False, lowhigh=None, percentile=None, sharpen_radius=0, smooth_radius=0, tile_norm_blocksize=0, tile_norm_smooth3D=1, axis=-1)[source]
Normalize each channel of the image.
- Parameters
img (ndarray) – The input image. It should have at least 3 dimensions. If it is 4-dimensional, it assumes the first non-channel axis is the Z dimension.
normalize (bool, optional) – Whether to perform normalization. Defaults to True.
norm3D (bool, optional) – Whether to normalize in 3D. Defaults to False.
invert (bool, optional) – Whether to invert the image. Useful if cells are dark instead of bright. Defaults to False.
lowhigh (tuple, optional) – The lower and upper bounds for normalization. If provided, it should be a tuple of two values. Defaults to None.
percentile (tuple, optional) – The lower and upper percentiles for normalization. If provided, it should be a tuple of two values. Each value should be between 0 and 100. Defaults to None.
sharpen_radius (int, optional) – The radius for sharpening the image. Defaults to 0.
smooth_radius (int, optional) – The radius for smoothing the image. Defaults to 0.
tile_norm_blocksize (int, optional) – The block size for tile-based normalization. Defaults to 0.
tile_norm_smooth3D (int, optional) – The smoothness factor for tile-based normalization in 3D. Defaults to 1.
axis (int, optional) – The channel axis to loop over for normalization. Defaults to -1.
- Returns
The normalized image of the same size.
- Return type
ndarray
- Raises
ValueError – If the image has less than 3 dimensions.
ValueError – If the provided lowhigh or percentile values are invalid.
ValueError – If the image is inverted without normalization.
- cellpose.transforms.pad_image_ND(img0, div=16, extra=1, min_size=None)[source]
Pad image for test-time so that its dimensions are a multiple of 16 (2D or 3D).
- Parameters
img0 (ndarray) – Image of size [nchan (x Lz) x Ly x Lx].
div (int, optional) – Divisor for padding. Defaults to 16.
extra (int, optional) – Extra padding. Defaults to 1.
min_size (tuple, optional) – Minimum size of the image. Defaults to None.
- Returns
- tuple containing
I (ndarray): Padded image.
ysub (ndarray): Y range of pixels in the padded image corresponding to img0.
xsub (ndarray): X range of pixels in the padded image corresponding to img0.
- cellpose.transforms.random_rotate_and_resize(X, Y=None, scale_range=1.0, xy=(224, 224), do_3D=False, do_flip=True, rotate=True, rescale=None, unet=False, random_per_image=True)[source]
Augmentation by random rotation and resizing.
- Parameters
X (list of ND-arrays, float) – List of image arrays of size [nchan x Ly x Lx] or [Ly x Lx].
Y (list of ND-arrays, float, optional) – List of image labels of size [nlabels x Ly x Lx] or [Ly x Lx]. The 1st channel of Y is always nearest-neighbor interpolated (assumed to be masks or 0-1 representation). If Y.shape[0]==3 and not unet, then the labels are assumed to be [cell probability, Y flow, X flow]. If unet, second channel is dist_to_bound. Defaults to None.
scale_range (float, optional) – Range of resizing of images for augmentation. Images are resized by (1-scale_range/2) + scale_range * np.random.rand(). Defaults to 1.0.
xy (tuple, int, optional) – Size of transformed images to return. Defaults to (224,224).
do_flip (bool, optional) – Whether or not to flip images horizontally. Defaults to True.
rotate (bool, optional) – Whether or not to rotate images. Defaults to True.
rescale (array, float, optional) – How much to resize images by before performing augmentations. Defaults to None.
unet (bool, optional) – Whether or not to use unet. Defaults to False.
random_per_image (bool, optional) – Different random rotate and resize per image. Defaults to True.
- Returns
- tuple containing
imgi (ND-array, float): Transformed images in array [nimg x nchan x xy[0] x xy[1]].
lbl (ND-array, float): Transformed labels in array [nimg x nchan x xy[0] x xy[1]].
scale (array, float): Amount each image was resized by.
- cellpose.transforms.reshape(data, channels=[0, 0], chan_first=False)[source]
Reshape data using channels.
- Parameters
data (numpy.ndarray) – The input data. It should have shape (Z x ) Ly x Lx x nchan if data.ndim==8 and data.shape[0]<8, it is assumed to be nchan x Ly x Lx.
channels (list of int, optional) – The channels to use for reshaping. The first element of the list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). The second element of the list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to train on grayscale images, input [0,0]. To train on images with cells in green and nuclei in blue, input [2,3]. Defaults to [0, 0].
chan_first (bool, optional) – Whether to return the reshaped data with channel as the first dimension. Defaults to False.
- Returns
The reshaped data with shape (Z x ) Ly x Lx x nchan (if chan_first==False).
- Return type
numpy.ndarray
- cellpose.transforms.resize_image(img0, Ly=None, Lx=None, rsz=None, interpolation=cv2.INTER_LINEAR, no_channels=False)[source]
Resize image for computing flows / unresize for computing dynamics.
- Parameters
img0 (ndarray) – Image of size [Y x X x nchan] or [Lz x Y x X x nchan] or [Lz x Y x X].
Ly (int, optional) – Desired height of the resized image. Defaults to None.
Lx (int, optional) – Desired width of the resized image. Defaults to None.
rsz (float, optional) – Resize coefficient(s) for the image. If Ly is None, rsz is used. Defaults to None.
interpolation (int, optional) – OpenCV interpolation method. Defaults to cv2.INTER_LINEAR.
no_channels (bool, optional) – Flag indicating whether to treat the third dimension as a channel. Defaults to False.
- Returns
Resized image of size [Ly x Lx x nchan] or [Lz x Ly x Lx x nchan].
- Return type
ndarray
- Raises
ValueError – If Ly is None and rsz is None.
- cellpose.transforms.smooth_sharpen_img(img, smooth_radius=6, sharpen_radius=12, device=torch.device, is3D=False)[source]
Sharpen blurry images with surround subtraction and/or smooth noisy images.
- Parameters
img (float32) – Array that’s (Lz x) Ly x Lx (x nchan).
smooth_radius (float, optional) – Size of gaussian smoothing filter, recommended to be 1/10-1/4 of cell diameter (if also sharpening, should be 2-3x smaller than sharpen_radius). Defaults to 6.
sharpen_radius (float, optional) – Size of gaussian surround filter, recommended to be 1/8-1/2 of cell diameter (if also smoothing, should be 2-3x larger than smooth_radius). Defaults to 12.
device (torch.device, optional) – Device on which to perform sharpening. Will be faster on GPU but need to ensure GPU has RAM for image. Defaults to torch.device(“cpu”).
is3D (bool, optional) – If image is 3D stack (only necessary to set if img.ndim==3). Defaults to False.
- Returns
Array that’s (Lz x) Ly x Lx (x nchan).
- Return type
img_sharpen (float32)
- cellpose.transforms.unaugment_tiles(y)[source]
Reverse test-time augmentations for averaging (includes flipping of flowsY and flowsX).
- Parameters
y (float32) – Array of shape (ntiles_y, ntiles_x, chan, Ly, Lx) where chan = (flowsY, flowsX, cell prob).
- Returns
Array of shape (ntiles_y, ntiles_x, chan, Ly, Lx).
- Return type
float32
- cellpose.transforms.update_axis(m_axis, to_squeeze, ndim)[source]
Squeeze the axis value based on the given parameters.
- Parameters
m_axis (int) – The current axis value.
to_squeeze (numpy.ndarray) – An array of indices to squeeze.
ndim (int) – The number of dimensions.
- Returns
The updated axis value.
- Return type
int or None
Plot functions
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.plot.disk(med, r, Ly, Lx)[source]
Returns the pixels of a disk with a given radius and center.
- Parameters
med (tuple) – The center coordinates of the disk.
r (float) – The radius of the disk.
Ly (int) – The height of the image.
Lx (int) – The width of the image.
- Returns
A tuple containing the y and x coordinates of the pixels within the disk.
- Return type
tuple
- cellpose.plot.dx_to_circ(dP, transparency=False, mask=None)[source]
Converts the optic flow representation to a circular color representation.
- Parameters
dP (ndarray) – Flow field components [dy, dx].
transparency (bool, optional) – Controls the opacity based on the magnitude of flow. Defaults to False.
mask (ndarray, optional) – Multiplies each RGB component to suppress noise.
- Returns
The circular color representation of the optic flow.
- Return type
ndarray
- cellpose.plot.image_to_rgb(img0, channels=[0, 0])[source]
Converts image from 2 x Ly x Lx or Ly x Lx x 2 to RGB Ly x Lx x 3.
- Parameters
img0 (ndarray) – Input image of shape 2 x Ly x Lx or Ly x Lx x 2.
- Returns
RGB image of shape Ly x Lx x 3.
- Return type
ndarray
- cellpose.plot.interesting_patch(mask, bsize=130)[source]
Get patch of size bsize x bsize with most masks.
- Parameters
mask (ndarray) – Input mask.
bsize (int) – Size of the patch.
- Returns
Patch coordinates (y, x).
- Return type
tuple
- cellpose.plot.mask_overlay(img, masks, colors=None)[source]
Overlay masks on image (set image to grayscale).
- Parameters
img (int or float, 2D or 3D array) – Image of size [Ly x Lx (x nchan)].
masks (int, 2D array) – Masks where 0=NO masks; 1,2,…=mask labels.
colors (int, 2D array, optional) – Size [nmasks x 3], each entry is a color in 0-255 range.
- Returns
Array of masks overlaid on grayscale image.
- Return type
RGB (uint8, 3D array)
- cellpose.plot.mask_rgb(masks, colors=None)[source]
Masks in random RGB colors.
- Parameters
masks (int, 2D array) – Masks where 0=NO masks; 1,2,…=mask labels.
colors (int, 2D array, optional) – Size [nmasks x 3], each entry is a color in 0-255 range.
- Returns
Array of masks overlaid on grayscale image.
- Return type
RGB (uint8, 3D array)
- cellpose.plot.outline_view(img0, maski, color=[1, 0, 0], mode='inner')[source]
Generates a red outline overlay onto the image.
- Parameters
img0 (numpy.ndarray) – The input image.
maski (numpy.ndarray) – The mask representing the region of interest.
color (list, optional) – The color of the outline overlay. Defaults to [1, 0, 0] (red).
mode (str, optional) – The mode for generating the outline. Defaults to “inner”.
- Returns
The image with the red outline overlay.
- Return type
numpy.ndarray
- cellpose.plot.show_segmentation(fig, img, maski, flowi, channels=[0, 0], file_name=None)[source]
Plot segmentation results (like on website).
Can save each panel of figure with file_name option. Use channels option if img input is not an RGB image with 3 channels.
- Parameters
fig (matplotlib.pyplot.figure) – Figure in which to make plot.
img (ndarray) – 2D or 3D array. Image input into cellpose.
maski (int, ndarray) – For image k, masks[k] output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flowi (int, ndarray) – For image k, flows[k][0] output from Cellpose.eval (RGB of flows).
channels (list of int, optional) – Channels used to run Cellpose, no need to use if image is RGB. Defaults to [0, 0].
file_name (str, optional) – File name of image. If file_name is not None, figure panels are saved. Defaults to None.
seg_norm (bool, optional) – Improve cell visibility under labels. Defaults to False.
I/O functions
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.io.add_model(filename)[source]
add model to .cellpose models folder to use with GUI or CLI
- cellpose.io.get_image_files(folder, mask_filter, imf=None, look_one_level_down=False)[source]
Finds all images in a folder and its subfolders (if specified) with the given file extensions.
- Parameters
folder (str) – The path to the folder to search for images.
mask_filter (str) – The filter for mask files.
imf (str, optional) – The additional filter for image files. Defaults to None.
look_one_level_down (bool, optional) – Whether to search for images in subfolders. Defaults to False.
- Returns
A list of image file paths.
- Return type
list
- Raises
ValueError – If no files are found in the specified folder.
ValueError – If no images are found in the specified folder with the supported file extensions.
ValueError – If no images are found in the specified folder without the mask or flow file endings.
- cellpose.io.get_label_files(image_names, mask_filter, imf=None)[source]
Get the label files corresponding to the given image names and mask filter.
- Parameters
image_names (list) – List of image names.
mask_filter (str) – Mask filter to be applied.
imf (str, optional) – Image file extension. Defaults to None.
- Returns
A tuple containing the label file names and flow file names (if present).
- Return type
tuple
- cellpose.io.imread(filename)[source]
Read in an image file with tif or image file type supported by cv2.
- Parameters
filename (str) – The path to the image file.
- Returns
The image data as a NumPy array.
- Return type
numpy.ndarray
- Raises
None –
Raises an error if the image file format is not supported.
Examples
>>> img = imread("image.tif")
- cellpose.io.imsave(filename, arr)[source]
Saves an image array to a file.
- Parameters
filename (str) – The name of the file to save the image to.
arr (numpy.ndarray) – The image array to be saved.
- Returns
None
- cellpose.io.load_images_labels(tdir, mask_filter='_masks', image_filter=None, look_one_level_down=False)[source]
Loads images and corresponding labels from a directory.
- Parameters
tdir (str) – The directory path.
mask_filter (str, optional) – The filter for mask files. Defaults to “_masks”.
image_filter (str, optional) – The filter for image files. Defaults to None.
look_one_level_down (bool, optional) – Whether to look for files one level down. Defaults to False.
- Returns
A tuple containing a list of images, a list of labels, and a list of image names.
- Return type
tuple
- cellpose.io.load_train_test_data(train_dir, test_dir=None, image_filter=None, mask_filter='_masks', look_one_level_down=False)[source]
Loads training and testing data for a Cellpose model.
- Parameters
train_dir (str) – The directory path containing the training data.
test_dir (str, optional) – The directory path containing the testing data. Defaults to None.
image_filter (str, optional) – The filter for selecting image files. Defaults to None.
mask_filter (str, optional) – The filter for selecting mask files. Defaults to “_masks”.
look_one_level_down (bool, optional) – Whether to look for data in subdirectories of train_dir and test_dir. Defaults to False.
- Returns
A list of training images. labels (list): A list of labels corresponding to the training images. image_names (list): A list of names of the training images. test_images (list, optional): A list of testing images. None if test_dir is not provided. test_labels (list, optional): A list of labels corresponding to the testing images. None if test_dir is not provided. test_image_names (list, optional): A list of names of the testing images. None if test_dir is not provided.
- Return type
images (list)
- cellpose.io.masks_flows_to_seg(images, masks, flows, file_names, diams=30.0, channels=None, imgs_restore=None, restore_type=None, ratio=1.0)[source]
Save output of model eval to be loaded in GUI.
Can be list output (run on multiple images) or single output (run on single image).
Saved to file_names[k]+”_seg.npy”.
- Parameters
images (list) – Images input into cellpose.
masks (list) – Masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flows (list) – Flows output from Cellpose.eval.
file_names (list, str) – Names of files of images.
diams (float array) – Diameters used to run Cellpose. Defaults to 30.
channels (list, int, optional) – Channels used to run Cellpose. Defaults to None.
- Returns
None
- cellpose.io.remove_model(filename, delete=False)[source]
remove model from .cellpose custom model list
- cellpose.io.save_masks(images, masks, flows, file_names, png=True, tif=False, channels=[0, 0], suffix='', save_flows=False, save_outlines=False, dir_above=False, in_folders=False, savedir=None, save_txt=False, save_mpl=False)[source]
Save masks + nicely plotted segmentation image to png and/or tiff.
Can save masks, flows to different directories, if in_folders is True.
If png, masks[k] for images[k] are saved to file_names[k]+”_cp_masks.png”.
If tif, masks[k] for images[k] are saved to file_names[k]+”_cp_masks.tif”.
If png and matplotlib installed, full segmentation figure is saved to file_names[k]+”_cp.png”.
Only tif option works for 3D data, and only tif option works for empty masks.
- Parameters
images (list) – Images input into cellpose.
masks (list) – Masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flows (list) – Flows output from Cellpose.eval.
file_names (list, str) – Names of files of images.
png (bool, optional) – Save masks to PNG. Defaults to True.
tif (bool, optional) – Save masks to TIF. Defaults to False.
channels (list, int, optional) – Channels used to run Cellpose. Defaults to [0,0].
suffix (str, optional) – Add name to saved masks. Defaults to “”.
save_flows (bool, optional) – Save flows output from Cellpose.eval. Defaults to False.
save_outlines (bool, optional) – Save outlines of masks. Defaults to False.
dir_above (bool, optional) – Save masks/flows in directory above. Defaults to False.
in_folders (bool, optional) – Save masks/flows in separate folders. Defaults to False.
savedir (str, optional) – Absolute path where images will be saved. If None, saves to image directory. Defaults to None.
save_txt (bool, optional) – Save masks as list of outlines for ImageJ. Defaults to False.
save_mpl (bool, optional) – If True, saves a matplotlib figure of the original image/segmentation/flows. Does not work for 3D. This takes a long time for large images. Defaults to False.
- Returns
None
- cellpose.io.save_rois(masks, file_name)[source]
save masks to .roi files in .zip archive for ImageJ/Fiji
- Parameters
masks (np.ndarray) – masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels
file_name (str) – name to save the .zip file to
- Returns
None
Utils functions
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- class cellpose.utils.TqdmToLogger(logger, level=None)[source]
Output stream for TQDM which will output to logger module instead of the StdOut.
- cellpose.utils.circleMask(d0)[source]
Creates an array with indices which are the radius of that x,y point.
- Parameters
d0 (tuple) – Patch of (-d0, d0+1) over which radius is computed.
- Returns
- A tuple containing:
rs (ndarray): Array of radii with shape (2*d0[0]+1, 2*d0[1]+1).
dx (ndarray): Indices of the patch along the x-axis.
dy (ndarray): Indices of the patch along the y-axis.
- Return type
tuple
- cellpose.utils.diameters(masks)[source]
Calculate the diameters of the objects in the given masks.
Parameters: masks (ndarray): masks (0=no cells, 1=first cell, 2=second cell,…)
Returns: tuple: A tuple containing the median diameter and an array of diameters for each object.
Examples: >>> masks = np.array([[0, 1, 1], [1, 0, 0], [1, 1, 0]]) >>> diameters(masks) (1.0, array([1.41421356, 1.0, 1.0]))
- cellpose.utils.dilate_masks(masks, n_iter=5)[source]
Dilate masks by n_iter pixels.
- Parameters
masks (ndarray) – Array of masks.
n_iter (int, optional) – Number of pixels to dilate the masks. Defaults to 5.
- Returns
Dilated masks.
- Return type
ndarray
- cellpose.utils.distance_to_boundary(masks)[source]
Get the distance to the boundary of mask pixels.
- Parameters
masks (int, 2D or 3D array) – The masks array. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.
- Returns
The distance to the boundary. Size [Ly x Lx] or [Lz x Ly x Lx].
- Return type
dist_to_bound (2D or 3D array)
- Raises
ValueError – If the masks array is not 2D or 3D.
- cellpose.utils.download_url_to_file(url, dst, progress=True)[source]
- Download object at the given URL to a local path.
Thanks to torch, slightly modified
- Parameters
url (string) – URL of the object to download
dst (string) – Full path where object will be saved, e.g. /tmp/temporary_file
progress (bool, optional) – whether or not to display a progress bar to stderr Default: True
- cellpose.utils.fill_holes_and_remove_small_masks(masks, min_size=15)[source]
Fills holes in masks (2D/3D) and discards masks smaller than min_size.
This function fills holes in each mask using scipy.ndimage.morphology.binary_fill_holes. It also removes masks that are smaller than the specified min_size.
Parameters: masks (ndarray): Int, 2D or 3D array of labelled masks.
0 represents no mask, while positive integers represent mask labels. The size can be [Ly x Lx] or [Lz x Ly x Lx].
- min_size (int, optional): Minimum number of pixels per mask.
Masks smaller than min_size will be removed. Set to -1 to turn off this functionality. Default is 15.
Returns: ndarray: Int, 2D or 3D array of masks with holes filled and small masks removed.
0 represents no mask, while positive integers represent mask labels. The size is [Ly x Lx] or [Lz x Ly x Lx].
- cellpose.utils.get_mask_compactness(masks)[source]
Calculate the compactness of masks.
- Parameters
masks (ndarray) – Binary masks representing objects.
- Returns
Array of compactness values for each mask.
- Return type
ndarray
- cellpose.utils.get_mask_perimeters(masks)[source]
Calculate the perimeters of the given masks.
- Parameters
masks (numpy.ndarray) – Binary masks representing objects.
- Returns
Array containing the perimeters of each mask.
- Return type
numpy.ndarray
- cellpose.utils.get_mask_stats(masks_true)[source]
Calculate various statistics for the given binary masks.
- Parameters
masks_true (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
- Returns
Convexity values for each mask. solidity (ndarray): Solidity values for each mask. compactness (ndarray): Compactness values for each mask.
- Return type
convexity (ndarray)
- cellpose.utils.get_masks_unet(output, cell_threshold=0, boundary_threshold=0)[source]
Create masks using cell probability and cell boundary.
- Parameters
output (ndarray) – The output array containing cell probability and cell boundary.
cell_threshold (float, optional) – The threshold value for cell probability. Defaults to 0.
boundary_threshold (float, optional) – The threshold value for cell boundary. Defaults to 0.
- Returns
The masks representing the segmented cells.
- Return type
ndarray
- cellpose.utils.get_outline_multi(args)[source]
Get the outline of a specific mask in a multi-mask image.
- Parameters
args (tuple) – A tuple containing the masks and the mask number.
- Returns
The outline of the specified mask as an array of coordinates.
- Return type
numpy.ndarray
- cellpose.utils.get_perimeter(points)[source]
Calculate the perimeter of a set of points.
- Parameters
points (ndarray) – An array of points with shape (npoints, ndim).
- Returns
The perimeter of the points.
- Return type
float
- cellpose.utils.masks_to_edges(masks, threshold=1.0)[source]
Get edges of masks as a 0-1 array.
- Parameters
masks (int, 2D or 3D array) – Size [Ly x Lx] or [Lz x Ly x Lx], where 0=NO masks and 1,2,…=mask labels.
threshold (float, optional) – Threshold value for distance to boundary. Defaults to 1.0.
- Returns
Size [Ly x Lx] or [Lz x Ly x Lx], where True pixels are edge pixels.
- Return type
edges (2D or 3D array)
- cellpose.utils.masks_to_outlines(masks)[source]
Get outlines of masks as a 0-1 array.
- Parameters
masks (int, 2D or 3D array) – Size [Ly x Lx] or [Lz x Ly x Lx], where 0=NO masks and 1,2,…=mask labels.
- Returns
Size [Ly x Lx] or [Lz x Ly x Lx], where True pixels are outlines.
- Return type
outlines (2D or 3D array)
- cellpose.utils.outlines_list(masks, multiprocessing_threshold=1000, multiprocessing=None)[source]
Get outlines of masks as a list to loop over for plotting.
- Parameters
masks (ndarray) – Array of masks.
multiprocessing_threshold (int, optional) – Threshold for enabling multiprocessing. Defaults to 1000.
multiprocessing (bool, optional) – Flag to enable multiprocessing. Defaults to None.
- Returns
List of outlines.
- Return type
list
- Raises
None –
Notes
This function is a wrapper for outlines_list_single and outlines_list_multi.
Multiprocessing is disabled for Windows.
- cellpose.utils.outlines_list_multi(masks, num_processes=None)[source]
Get outlines of masks as a list to loop over for plotting.
- Parameters
masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
- Returns
List of outlines as pixel coordinates.
- Return type
list
- cellpose.utils.outlines_list_single(masks)[source]
Get outlines of masks as a list to loop over for plotting.
- Parameters
masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
- Returns
List of outlines as pixel coordinates.
- Return type
list
- cellpose.utils.radius_distribution(masks, bins)[source]
Calculate the radius distribution of masks.
- Parameters
masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
bins (int) – Number of bins for the histogram.
- Returns
- A tuple containing:
nb (ndarray): Normalized histogram of radii.
md (float): Median radius.
radii (ndarray): Array of radii.
- Return type
tuple
- cellpose.utils.remove_edge_masks(masks, change_index=True)[source]
Removes masks with pixels on the edge of the image.
- Parameters
masks (int, 2D or 3D array) – The masks to be processed. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.
change_index (bool, optional) – If True, after removing masks, changes the indexing so that there are no missing label numbers. Defaults to True.
- Returns
The processed masks. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.
- Return type
outlines (2D or 3D array)
- cellpose.utils.size_distribution(masks)[source]
Calculates the size distribution of masks.
- Parameters
masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
- Returns
The ratio of the 25th percentile of mask sizes to the 75th percentile of mask sizes.
- Return type
float
- cellpose.utils.stitch3D(masks, stitch_threshold=0.25)[source]
Stitch 2D masks into a 3D volume using a stitch_threshold on IOU.
- Parameters
masks (list or ndarray) – List of 2D masks.
stitch_threshold (float, optional) – Threshold value for stitching. Defaults to 0.25.
- Returns
List of stitched 3D masks.
- Return type
list
Network classes
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- class cellpose.resnet_torch.CPnet(*args: Any, **kwargs: Any)[source]
CPnet is the Cellpose neural network model used for cell segmentation and image restoration.
- Parameters
nbase (list) – List of integers representing the number of channels in each layer of the downsample path.
nout (int) – Number of output channels.
sz (int) – Size of the input image.
mkldnn (bool, optional) – Whether to use MKL-DNN acceleration. Defaults to False.
conv_3D (bool, optional) – Whether to use 3D convolution. Defaults to False.
max_pool (bool, optional) – Whether to use max pooling. Defaults to True.
diam_mean (float, optional) – Mean diameter of the cells. Defaults to 30.0.
- nbase
List of integers representing the number of channels in each layer of the downsample path.
- Type
list
- nout
Number of output channels.
- Type
int
- sz
Size of the input image.
- Type
int
- residual_on
Whether to use residual connections.
- Type
bool
- style_on
Whether to use style transfer.
- Type
bool
- concatenation
Whether to use concatenation.
- Type
bool
- conv_3D
Whether to use 3D convolution.
- Type
bool
- mkldnn
Whether to use MKL-DNN acceleration.
- Type
bool
- downsample
Downsample blocks of the network.
- Type
nn.Module
- upsample
Upsample blocks of the network.
- Type
nn.Module
- make_style
Style module, avgpool’s over all spatial positions.
- Type
nn.Module
- output
Output module - batchconv layer.
- Type
nn.Module
- diam_mean
Parameter representing the mean diameter to which the cells are rescaled to during training.
- Type
nn.Parameter
- diam_labels
Parameter representing the mean diameter of the cells in the training set (before rescaling).
- Type
nn.Parameter
- property device
Get the device of the model.
- Returns
The device of the model.
- Return type
torch.device
- forward(data)[source]
Forward pass of the CPnet model.
- Parameters
data (torch.Tensor) – Input data.
- Returns
A tuple containing the output tensor, style tensor, and downsampled tensors.
- Return type
tuple
Core functions
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- cellpose.core.assign_device(use_torch=True, gpu=False, device=0)[source]
Assigns the device (CPU or GPU or mps) to be used for computation.
- Parameters
use_torch (bool, optional) – Whether to use torch for GPU detection. Defaults to True.
gpu (bool, optional) – Whether to use GPU for computation. Defaults to False.
device (int or str, optional) – The device index or name to be used. Defaults to 0.
- Returns
The assigned device. bool: True if GPU is used, False otherwise.
- Return type
torch.device
- cellpose.core.check_mkl(use_torch=True)[source]
Checks if MKL-DNN is enabled and working.
- Parameters
use_torch (bool, optional) – Whether to use torch. Defaults to True.
- Returns
True if MKL-DNN is enabled, False otherwise.
- Return type
bool
- cellpose.core.run_3D(net, imgs, batch_size=8, rsz=1.0, anisotropy=None, augment=False, tile=True, tile_overlap=0.1, bsize=224, progress=None)[source]
Run network on image z-stack.
(faster if augment is False)
- Parameters
imgs (np.ndarray) – The input image stack of size [Lz x Ly x Lx x nchan].
batch_size (int, optional) – Number of tiles to run in a batch. Defaults to 8.
rsz (float, optional) – Resize coefficient(s) for image. Defaults to 1.0.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
augment (bool, optional) – Tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – Tiles image to ensure GPU/CPU memory usage limited (recommended); cannot be turned off for 3D segmentation. Defaults to True.
tile_overlap (float, optional) – Fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – Size of tiles to use in pixels [bsize x bsize]. Defaults to 224.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.
- Returns
- output of network, if tiled it is averaged in tile overlaps. Size of [Ly x Lx x 3] or [Lz x Ly x Lx x 3].
y[…,0] is Y flow; y[…,1] is X flow; y[…,2] is cell probability.
style (np.ndarray): 1D array of size 256 summarizing the style of the image, if tiled it is averaged over tiles.
- Return type
y (np.ndarray)
- cellpose.core.run_net(net, imgs, batch_size=8, augment=False, tile=True, tile_overlap=0.1, bsize=224)[source]
Run network on image or stack of images.
(faster if augment is False)
- Parameters
imgs (np.ndarray) – The input image or stack of images of size [Ly x Lx x nchan] or [Lz x Ly x Lx x nchan].
batch_size (int, optional) – Number of tiles to run in a batch. Defaults to 8.
rsz (float, optional) – Resize coefficient(s) for image. Defaults to 1.0.
augment (bool, optional) – Tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – Tiles image to ensure GPU/CPU memory usage limited (recommended); cannot be turned off for 3D segmentation. Defaults to True.
tile_overlap (float, optional) – Fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – Size of tiles to use in pixels [bsize x bsize]. Defaults to 224.
- Returns
- output of network, if tiled it is averaged in tile overlaps. Size of [Ly x Lx x 3] or [Lz x Ly x Lx x 3].
y[…,0] is Y flow; y[…,1] is X flow; y[…,2] is cell probability.
style (np.ndarray): 1D array of size 256 summarizing the style of the image, if tiled it is averaged over tiles.
- Return type
y (np.ndarray)
- cellpose.core.use_gpu(gpu_number=0, use_torch=True)[source]
Check if GPU is available for use.
- Parameters
gpu_number (int) – The index of the GPU to be used. Default is 0.
use_torch (bool) – Whether to use PyTorch for GPU check. Default is True.
- Returns
True if GPU is available, False otherwise.
- Return type
bool
- Raises
ValueError – If use_torch is False, as cellpose only runs with PyTorch now.
All models functions
Copyright © 2023 Howard Hughes Medical Institute, Authored by Carsen Stringer and Marius Pachitariu.
- class cellpose.models.Cellpose(gpu=False, model_type='cyto3', device=None)[source]
Main model which combines SizeModel and CellposeModel.
- Parameters
gpu (bool, optional) – Whether or not to use GPU, will check if GPU available. Defaults to False.
model_type (str, optional) – Model type. “cyto”=cytoplasm model; “nuclei”=nucleus model; “cyto2”=cytoplasm model with additional user images; “cyto3”=super-generalist model; Defaults to “cyto3”.
device (torch device, optional) – Device used for model running / training. Overrides gpu input. Recommended if you want to use a specific GPU (e.g. torch.device(“cuda:1”)). Defaults to None.
- device
Device used for model running / training.
- Type
torch device
- gpu
Flag indicating if GPU is used.
- Type
bool
- diam_mean
Mean diameter for cytoplasm model.
- Type
float
- cp
CellposeModel instance.
- Type
- pretrained_size
Pretrained size model path.
- Type
str
- eval(x, batch_size=8, channels=[0, 0], channel_axis=None, invert=False, normalize=True, diameter=30.0, do_3D=False, **kwargs)[source]
Run cellpose size model and mask model and get masks.
- Parameters
x (list or array) – List or array of images. Can be list of 2D/3D images, or array of 2D/3D images, or 4D image array.
batch_size (int, optional) – Number of 224x224 patches to run simultaneously on the GPU. Can make smaller or bigger depending on GPU memory usage. Defaults to 8.
channels (list, optional) – List of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to [0,0].
channel_axis (int, optional) – If None, channels dimension is attempted to be automatically determined. Defaults to None.
invert (bool, optional) – Invert image pixel intensity before running network (if True, image is also normalized). Defaults to False.
normalize (bool, optional) – If True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (see CellposeModel for details). Defaults to True.
diameter (float, optional) – If set to None, then diameter is automatically estimated if size model is loaded. Defaults to 30..
do_3D (bool, optional) – Set to True to run 3D segmentation on 4D image input. Defaults to False.
- Returns
- tuple containing
masks (list of 2D arrays or single 3D array): Labelled image, where 0=no masks; 1,2,…=mask labels.
- flows (list of lists 2D arrays or list of 3D arrays):
flows[k][0] = XY flow in HSV 0-255
flows[k][1] = XY flows at each pixel
flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics)
flows[k][3] = final pixel locations after Euler integration
styles (list of 1D arrays of length 256 or single 1D array): Style vector summarizing each image, also used to estimate size of objects in image.
diams (list of diameters or float): List of diameters or float (if do_3D=True).
- class cellpose.models.CellposeModel(gpu=False, pretrained_model=False, model_type=None, diam_mean=30.0, device=None, nchan=2)[source]
Class representing a Cellpose model.
- diam_mean
Mean “diameter” value for the model.
- Type
float
- builtin
Whether the model is a built-in model or not.
- Type
bool
- device
Device used for model running / training.
- Type
torch device
- mkldnn
MKLDNN flag for the model.
- Type
None or bool
- nchan
Number of channels used as input to the network.
- Type
int
- nclasses
Number of classes in the model.
- Type
int
- nbase
List of base values for the model.
- Type
list
- pretrained_model
Full path to pretrained cellpose model(s).
- Type
str or list of strings
- diam_labels
Diameter labels of the model.
- Type
numpy array
- net_type
Type of the network.
- Type
str
- __init__(self, gpu=False, pretrained_model=False, model_type=None, diam_mean=30., device=None, nchan=2)[source]
Initialize the CellposeModel.
- eval(self, x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile=True, tile_overlap=0.1, bsize=224, interp=True, compute_masks=True, progress=None)[source]
Segment list of images x, or 4D array - Z x nchan x Y x X.
- eval(x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile=True, tile_overlap=0.1, bsize=224, interp=True, compute_masks=True, progress=None)[source]
segment list of images x, or 4D array - Z x nchan x Y x X
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
resample (bool, optional) – run dynamics at original image size (will be slower but create more accurate boundaries). Defaults to True.
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – invert image pixel intensity before running network. Defaults to False.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float, optional) – diameter for each image, if diameter is None, set to diam_mean or diam_train if available. Defaults to None.
flow_threshold (float, optional) – flow error threshold (all cells with errors below threshold are kept) (not used for 3D). Defaults to 0.4.
cellprob_threshold (float, optional) – all pixels with value above threshold kept for masks, decrease to find more and larger masks. Defaults to 0.0.
do_3D (bool, optional) – set to True to run 3D segmentation on 3D/4D image input. Defaults to False.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
stitch_threshold (float, optional) – if stitch_threshold>0.0 and not do_3D, masks are stitched in 3D to return volume segmentation. Defaults to 0.0.
min_size (int, optional) – all ROIs below this size, in pixels, will be discarded. Defaults to 15.
niter (int, optional) – number of iterations for dynamics computation. if None, it is set proportional to the diameter. Defaults to None.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – block size for tiles, recommended to keep at 224, like in training. Defaults to 224.
interp (bool, optional) – interpolate during 2D dynamics (not available in 3D) . Defaults to True.
compute_masks (bool, optional) – Whether or not to compute dynamics and return masks. This is set to False when retrieving the styles for the size model. Defaults to True.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.
- Returns
masks (list, np.ndarray): labelled image(s), where 0=no masks; 1,2,…=mask labels
flows (list): list of lists: flows[k][0] = XY flow in HSV 0-255; flows[k][1] = XY(Z) flows at each pixel; flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics); flows[k][3] = final pixel locations after Euler integration
styles (list, np.ndarray): style vector summarizing each image of size 256.
- Return type
A tuple containing
- class cellpose.models.SizeModel(cp_model, device=None, pretrained_size=None, **kwargs)[source]
Linear regression model for determining the size of objects in image used to rescale before input to cp_model. Uses styles from cp_model.
- pretrained_size
Path to pretrained size model.
- Type
str
- cp
Model from which to get styles.
- Type
UnetModel or CellposeModel
- device
Device used for model running / training (torch.device(“cuda”) or torch.device(“cpu”)), overrides gpu input, recommended if you want to use a specific GPU (e.g. torch.device(“cuda:1”)).
- Type
torch device
- diam_mean
Mean diameter of objects.
- Type
float
- eval(self, x, channels=None, channel_axis=None, normalize=True, invert=False,
augment=False, tile=True, batch_size=8, progress=None, interp=True):
Use images x to produce style or use style input to predict size of objects in image.
- Raises
ValueError – If no pretrained cellpose model is specified, cannot compute size.
- eval(x, channels=None, channel_axis=None, normalize=True, invert=False, augment=False, tile=True, batch_size=8, progress=None)[source]
Use images x to produce style or use style input to predict size of objects in image.
Object size estimation is done in two steps: 1. Use a linear regression model to predict size from style in image. 2. Resize image to predicted size and run CellposeModel to get output masks.
Take the median object size of the predicted masks as the final predicted size.
- Parameters
x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images
channels (list, optional) – list of channels, either of length 2 or of length number of images by 2. First element of list is the channel to segment (0=grayscale, 1=red, 2=green, 3=blue). Second element of list is the optional nuclear channel (0=none, 1=red, 2=green, 3=blue). For instance, to segment grayscale images, input [0,0]. To segment images with cells in green and nuclei in blue, input [2,3]. To segment one grayscale image and one image with cells in green and nuclei in blue, input [[0,0], [2,3]]. Defaults to None.
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
”normalize”=True ; run normalization (if False, all following parameters ignored)
”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
”tile_norm”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
”norm3D”=False ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – Invert image pixel intensity before running network (if True, image is also normalized). Defaults to False.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile (bool, optional) – tiles image to ensure GPU/CPU memory usage limited (recommended). Defaults to True.
batch_size (int, optional) – number of 224x224 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 8.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.
- Returns
diam (np.ndarray): Final estimated diameters from images x or styles style after running both steps.
diam_style (np.ndarray): Estimated diameters from style alone.
- Return type
A tuple containing