The PyJAMAS API

The PyJAMAS API can be invoked by creating a PyJAMAS object:

from pyjamas.pjscore import PyJAMAS
pjs = PyJAMAS()

The pjs object contains attributes that hold important data about the image and annotations. Here are a few of them:

  • pjs.slices: (numpy.ndarray) the image data as an array of dimensions C x H x W where C is the number of channels or timepoints, H is the height, and W is the width.

  • pjs.height: (int) the height of the image (number of rows in the numpy array).

  • pjs.width: (int) the width of the image (number of columns in the numpy array).

  • pjs.n_frames: (int) the number of frames in the image (number of channels in the numpy array).

  • pjs.curslice: (int) the index of the current frame of the image.

  • pjs.polylines: (list) a list of length pjs.n_frames, where each element is a list of the polylines on that frame.

  • pjs.polyline_ids: (list) a list of length pjs.n_frames, where each element is a list of the polyline ids on that frame. pjs.polylines and pjs.polyline_ids are in the same order so that the id at pjs.polyline_ids[t][i] corresponds to the polyline at pjs.polylines[t][i]

  • pjs.fiducials: (list) a list of length pjs.n_frames, where each element is a list of the fiducial coordinates on that frame.

  • pjs.brush_size: (int) the size of the width of polyline outlines. This parameter is also used in many functions to determine the margin around polylines to consider a part of the object.

  • pjs.batch_classifier: a class that implements fit and predict methods for machine learning applications. pjs.batch_classifier contains functions for applying the tool to many frames, while pjs.batch_classifier.classifier contains the actual classifier object.

The pjs object also contains a set of attributes that provide access to the PyJAMAS API. The attributes are instances of different submodules in the pyjamas.rcallbacks package. The attributes are:

The methods included in each attribute are described below.

pjs.io

class pyjamas.rcallbacks.rcbio.RCBIO(ui)
cbExportAllPolylineAnnotations(folder_name=None, message='Export files to folder ...')

Exports each polyline in the image containing a fiducial into a single PyJAMAS annotation file - including polylines containing the same fiducial in other slices.

Parameters:

  • folder_name (Optional[str]) – folder where annotation files will be stored.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the export process completed normally, False otherwise.

cbExportCurrentAnnotationsBinaryImage(filename=None, polyline=None, firstSlice=None, lastSlice=None, message='Save annotations ...')

Save current slice annotations as a binary image displaying one mask per object.

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on the current image name (pjs.filename). If not provided, a dialog will open.

  • polyline (Optional[ndarray]) – ndarray with two columns containing the x, y coordinates of the ROI; if None or empty array, use the entire image as ROI.

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1); a dialog will open if this parameter is None.

  • lastSlice (Optional[int]) – slice number for the last slice to use; a dialog will open if this parameter is None.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

cbExportMovie(filename=None, message='Export movie with annotations ...')

Save an avi file displaying the movie currently open and its annotations. The number of frames per second is determined by pjs.fps.

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on the current image name (pjs.filename). If not provided, a dialog will open.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the display was properly saved, False otherwise.

cbExportPolylineAnnotations(folder_name=None)

Set PyJAMAS’ annotation mode such that when a fiducial is clicked on, its containing polyline -over time- is stored in a new PyJAMAS annotation file (pickled).

Parameters:

folder_name (Optional[str]) – folder where annotation files will be stored.

Return type:

bool

Returns:

True if the annotation mode was changed, False otherwise.

cbExportROIAndMasks(polyline=None, margin_size=0)

Save the image within an ROI, plus a second image containing a binary mask of any polylines within the ROI.

Parameters:

  • polyline (Optional[ndarray]) – ndarray with two columns containing the x, y coordinates of the ROI; if using a tracked polyline, ndarray with one element corresponding to the polyline index; if not provided, the function will prompt the user to select a polyline.

  • margin_size (int) – margin size in pixels for cropping around the polyline

Return type:

bool

Returns:

True if the image is cropped, False otherwise.

cbExportSIESTAAnnotations(filename=None, message='Export SIESTA annotations ...')

Export annotations in Matlab format. These annotations can be read by both Matlab and Python. See https://www.mathworks.com/help/matlab/matlab_external/handling-data-returned-from-python.html for details.

Something important here is to send float arrays to Matlab, otherwise there are errors when Matlab tries to conduct certain operations on the arrays.

Parameters:

  • filename (Optional[str]) – name of the file used to store the annotations.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the annotations are exported, False otherwise.

cbImportMasks(filename=None, message='Load mask file ...')

Load a mask image from file using rimutils.read_stack and convert the mask regions to polyline annotations.

Parameters:

  • filename (Optional[str]) – file to open.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the mask image was loaded with no problems, False otherwise.

cbImportSIESTAAnnotations(filenames=None, image_file=None, replace=True, message='Load annotations ...')

Read Matlab-based annotations into PyJAMAS..

Parameters:

  • filenames (Optional[List[str]]) – path to the files that will contain the Matlab-based annotations.

  • image_file (Optional[str]) – path to an image that can be loaded with the Matlab-based annotations. ‘’ to use an empty image.

  • replace (bool) – True if loaded annotations should replace existing ones, False if this is an additive load.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the annotation file was properly loaded, False otherwise.

cbLoadAnnotations(filenames=None, image_file=None, replace=True, message='Load annotations ...')

Loads PyJAMAS annotation files.

Parameters:

  • filenames (Optional[List[str]]) – paths to the files containing the annotations.

  • image_file (Optional[str]) – path to an image to be loaded with the annotation file. None if no image is to be loaded. ‘’ to create an empty image.

  • replace (bool) – True if loaded annotations should replace existing ones, False if this is an additive load.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the annotation file was loaded, False otherwise.

cbLoadArray(image)

Load a numpy matrix as an image.

Parameters:

image (ndarray) – the array to open.

Return type:

bool

Returns:

True if the image was loaded with no problems, False otherwise.

cbLoadClassifier(filename=None, message='Load classifier ...')

Load a classifier from disk.

Parameters:

  • filename (Optional[str]) – name of the file containing a pickled classifier to be loaded.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the classifier was loaded, False otherwise.

cbLoadConfig(filename=None, message='Load config file ...')

Load a configuration file using tomlkit.

Parameters:

  • filename (Optional[str]) – file to open.

  • message (Optional[str]) – string to display as the dialog box title.

Returns:

True if the config file was loaded with no problems, False otherwise.

cbLoadTimeSeries(filename=None, channel_method=None, index=-1, message='Load image ...')

Load an image from file using rimutils.read_stack.

Parameters:

  • filename (Optional[str]) – file to open.

  • channel_method (Optional[ChannelMethod]) – for a multi-channel sequence, determines whether to open a channel or a slice.

  • index (int) – index of the channel or slice to open (with origin at 0).

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the image was loaded with no problems, False otherwise.

cbSaveAnnotations(filename=None, polylines=None, polyline_ids=None, fiducials=None, pickle_protocol=3, message='Save annotations ...')

Save annotations on the current image in pjs format (pickled). These annotations CAN BE opened by PyJAMAS.

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on the current image name (pjs.filename). If not provided, a dialog will open.

  • polylines (Optional[List]) – list of polylines to save (one slice per time point, one QtGui.QPolygonF per polyline).

  • polyline_ids (Optional[List]) – list of polylines ids to save (one slice per time point, one integer per polyline).

  • fiducials (Optional[List]) – list of fiducials to save (one slice per time point, one row with [x, y] coordinates per fiducial (int)).

  • pickle_protocol (int) – integer indicating the pickle protocol to use for saving (defaults to RCBIO.DEFAULT_PICKLE_PROTOCOL).

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the annotations were saved, False otherwise.

cbSaveClassifier(filename=None, theclassifier=None, message='Save classifier ...')

Save current classifier (pickled).

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on the current image name (pjs.filename). If not provided, a dialog will open.

  • theclassifier (Optional[rimclassifier]) – True if the classifier saved, False otherwise.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the classifier was saved, False otherwise.

cbSaveConfig(filename=None, message='Save config file ...')

Save the current pjs.config as a .toml file.

Parameters:

  • filename (Optional[str]) – filepath to save to.

  • message (Optional[str]) – string to display as the dialog box title.

Returns:

True if the config file was saved with no problems, False otherwise.

cbSaveDisplay(filename=None, message='Save display ...')

Save the PyJAMAS display, including annotations, as a colour image.

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on the current image name (pjs.filename). If not provided, a dialog will open.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the display was properly saved, False otherwise.

cbSaveROI(filename=None, x_range=False, y_range=False, z_range=False, message='Save time series ...')

Save a subregion of the image currently open (pjs.slices).

Parameters:

  • filename (Optional[str]) – ‘’ for automated naming based on coordinates. If None, a dialog will open. Make sure to provide an extension (defaults to PyJAMAS.image_extensions[0]).

  • x_range (Tuple[int, int]) – tuple containing the min and max X values to save. If False, take the coordinates of the first polyline defined on the image. If no polygons, use the entire image width.

  • y_range (Tuple[int, int]) – tuple containing the min and max Y values to save. If False, take the coordinates of the first polyline defined on the image. If no polygons, use the entire image height.

  • z_range (Tuple[int, int]) – tuple containing the min and max Z values to save. If False, use just the current Z.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the image was properly saved, False otherwise.

cbSaveTimeSeries(filename=None, message='Save time series ...')

Save the current image (pjs.slices) as a grayscale, multi-page TIFF.

Parameters:

  • filename (Optional[str]) – path to the destination file.

  • message (str) – string to display as the dialog box title.

Return type:

bool

Returns:

True if the image was saved with no problems, False otherwise.

update_key_bindings()

Updates values for key bindings using the values from self.pjs.config

update_options()

Updates values for options using the values from self.pjs.config

pjs.options

class pyjamas.rcallbacks.rcboptions.RCBOptions(ui)
cbChangeDisplayTheme()

Toggles display between light theme and dark theme.

Return type:

bool

Returns:

True.

cbChangeFootprint(footprint)

Change the footprint for dilations and erosions :return: True.

cbChangeKeyBindings(key_bindings=None)

Configure which keyboard shortcuts are used for which PyJAMAS functions.

Parameters:

key_bindings (Optional[dict]) – dict of dicts of format {‘menu1_title’: {‘action1_text’: ‘action1_shortcut’}}

Returns:

True if key bindings were changed, False otherwise.

cbCloseAllPolylines()

Toggles closing all polylines loaded from file ON/OFF.

Returns:

True.

cbCropTracked()

Toggles cropping with tracked polylines on or off.

Return type:

bool

Returns:

True.

cbDisplayFiducialIDs()

Toggle fiducial ids on/off.

Return type:

bool

Returns:

True.

cbFramesPerSec(fps=None)

Set the number of frames per second to use when playing through the slices.

Parameters:

fps (Optional[int]) – number of frames per second; if the value is None, a dialog appears.

Return type:

bool

Returns:

True if the number of frames per second was changed, False otherwise.

cbSetBrushSize(sz=None)

Set the size of the brush used to paint polygons.

Parameters:

sz (int) – brush size; if the value is None a dialog appears.

Return type:

bool

Returns:

True if the brush size was changed, False otherwise.

cbSetCWD(folder_name='')

Set the current working directory.

Parameters:

folder_name (str) – absolute path to the current working directory; if the string is empty (‘’) or None, a dialog appears.

Return type:

bool

Returns:

True if the directory was set (the selected directory must exist), False otherwise.

cbSetImageProcessingCropSize(crop_size=None)

Set the size of the image crop that will be used for expensive computational operations (e.g. balloons).

Parameters:

crop_size (Optional[int]) – size of the cropped image.

Return type:

bool

Returns:

True if crop size was changed, False otherwise.

cbSetLiveWireSmoothGaussian(sigma=None)

Set the standard deviation of the Gaussian used to smoothen images for LiveWire segmentation. A weight of 0.0 is no smoothing.

Parameters:

sigma (Optional[float]) – standard deviation of the Gaussian used for image smoothing.

Return type:

bool

Returns:

True if sigma was changed, False otherwise.

cbSetLivewireShortestPathFunction(shortest_path_fn=None)

Set the function used to calculate the shortest path between two pixels using LiveWire segmentation.

Parameters:

shortest_path_fn (Optional[str]) – name of the function to calculate the shortest path between two pixels (see rimage.rimcore.rimage.livewire_shortest_path_fns for examples).

Returns:

True if function was changed, False otherwise.

cbSetMarginSize(margin_size=None)

Set the size of margins used for cropping.

Parameters:

margin_size (Optional[int]) – size of margins in pixels.

Return type:

bool

Returns:

True if margin size was changed, False otherwise.

cbToggleHighlightOnHover()

quit()

Toggle highlighting objects on hover on/off. :return: True.

cbUndo()

Undo the most recent action: individual fiducials added or deleted; polylines added, deleted or moved; or multiple fiducials or polylines added or deleted simultaneously (e.g. after finding seeds, segmenting cells, or deleting all annotations). Also, image projections, inversion, smoothing, gradient, registration, crop or kymograph.

Return type:

bool

Returns:

True if undo finished correctly, False if there was an error.

pjs.image

class pyjamas.rcallbacks.rcbimage.RCBImage(ui)
cbAdjustContrast(min_percentile=None, max_percentile=None)

Stretch the displayed pixel values between a certain minimum and maximum percentiles.

Parameters:

  • min_percentile (Optional[int]) – lower percentile of existing image intensities to map to black; a dialog appears if this is None.

  • max_percentile (Optional[int]) – higher percentile of existing image intensities to map to white; a dialog appears if this is None.

Return type:

bool

Returns:

True if the contrast was adjusted, False otherwise.

cbCentroidSeeds(firstSlice=None, lastSlice=None, wait_for_thread=False)

Add one fiducial at the centroid of each polyline.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if centroid fiducials are added, False if the process is cancelled.

cbCrop(polyline=None, margin_size=0, new_window=False)

Crop image.

Parameters:

  • polyline (Optional[ndarray]) – ndarray with two columns, containing the x, y polyline of the region to crop; if cropping with a tracked polyline, ndarray with one element corresponding to the polyline index; if not provided, the function will prompt the user to select a polyline.

  • margin_size (int) – margin size in pixels for cropping around the polyline

  • new_window (bool) – set to False.

Return type:

bool

Returns:

True if the image is cropped, False otherwise.

cbDisplayInfo()

Displays information related to the image currently open in PyJAMAS.

Return type:

bool

Returns:

True.

cbExpandNPropagateSeeds(firstSlice=None, lastSlice=None, sigma=None, xcorrWindowSize=None, wait_for_thread=False)

Expand fiducials using the watershed algorithm, and propagate the fiducials to the next slice, calculating the displacement to apply based on the local cross-correlation. Fiducials closer to the object edge than pjs.CENTER_SEEDS_CLOSER_TO_THE_EDGE, are moved to the object centroid before propagation.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • sigma (Optional[float]) – standard deviation of the Gaussian filter applied to smoothen the image.

  • xcorrWindowSize (Optional[int]) – width in pixels of the window size used to calculate the local cross-correlation.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if expand and propagate runs, False if the process is cancelled.

cbExpandSeeds(firstSlice=None, lastSlice=None, sigma=None, wait_for_thread=False)

Expand fiducials using the watershed algorithm.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • sigma (Optional[float]) – standard deviation of the Gaussian filter applied to smoothen the image.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if seed expansion runs, False if the process is cancelled.

cbFindPuncta(firstSlice=None, lastSlice=None, mean_filter_width=None, difference_threshold=None, max_size_merge=None, wait_for_thread=False)

Find bright intensity puncta using the difference between the image and an average-filtered version. Small adjacent puncta are merged.

An interactive dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • mean_filter_width (Optional[int]) – width of the square mean filter that will be subtracted from the original image for puncta detection.

  • difference_threshold (Optional[float]) – intensity threshold of puncta after subtracting an average filtered version of the image.

  • max_size_merge (Optional[int]) – maximum size of mergeable puncta.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if puncta detection runs, False if the process is cancelled.

cbFindSeeds(firstSlice=None, lastSlice=None, sigma=None, window_size=None, bindilation=None, mindist=None, preview=None, wait_for_thread=False)

Find seeds for watershed-based object segmentation. Uses a combination of Gaussian blurring and local thresholding to find object boundaries, and a distance transform to find pixels inside objects.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • sigma (Optional[float]) – standard deviation of the Gaussian filter applied to smoothen the image.

  • window_size (Optional[int]) – width in pixels of the window size used to calculate the local threshold (useful when segmenting objects with bright boundaries and dark interiors - e.g. cells expressing fluorescent membrane markers).

  • bindilation (Optional[int]) – positive values conduct binary closings after local thresholding to remove discontinuities in bright features, negative values conduct binary openings (useful when segmenting bright objects separated by a dark background - e.g. fluorescent cell nuclei).

  • mindist (Optional[float]) – minimum distance transform value to consider a pixel significantly far from edges and part of the local maxima; if negative, a local threshold of the distance transform is used to calculate its local maxima.

  • preview (Optional[bool]) – True to open a window with a preview of parameter values, False otherwise.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if seed detection runs, False if the process is cancelled.

cbFlipImage(direction=2)

Flip image and image annotations left/right or up/down.

Parameters:

direction (int) – one of pjs.image.LEFT_RIGHT or pjs.image.UP_DOWN.

Return type:

bool

Returns:

True.

cbGaussianImage(sigma=0.0)

Gaussian smoothing.

Parameters:

sigma (float) – standard deviation of the Gaussian kernel.

Return type:

bool

Returns:

True if the image was smoothened, False if the value of sigma is incorrect.

cbGoTo(slice_index)

Jump to a specific slice.

Parameters:

slice_index (int) – index (minimum value is zero) of the slice to jump to; negative values start start pointing from the last slice (-1 being the last one).

Return type:

bool

Returns:

True if the jump occurred, False if the index is out of range.

cbGradientImage()

Magnitude of the image gradient.

Return type:

bool

Returns:

True.

cbInvertImage()

Invert image.

Return type:

bool

Returns:

True.

cbKymograph(polyline=None, margin_size=0, new_window=False)

Kymograph of an image region.

Parameters:

  • polyline (Optional[ndarray]) – ndarray with two columns containing the x, y coordinates of the region to crop; if not provided, the function will prompt the user to select a polyline.

  • margin_size (int) – margin size in pixels for cropping around the polyline

  • new_window (bool) – set to False.

Return type:

bool

Returns:

True if the kymograph is created, False otherwise.

cbNextFrame()

Advance to the next slice (or move to the first slice if currently on the last one).

Return type:

bool

Returns:

True.

cbOrthogonalViews()

Display the XZ and YZ planes of a stack at a given point in the 3D image. The XZ and YZ viewers will update automatically as the lines in the main window are moved.

Returns:

True if the viewers were successfully opened or closed.

cbPlay()

Play/stop playing through the image slices.

Return type:

bool

Returns:

True.

cbPrevFrame()

Move to the previous slice (or to the last one if currently on the first one).

Return type:

bool

Returns:

True.

cbProjectImage(slice_list=None, projection_type=projection_types.MAX)

Intensity projection of the open image.

Parameters:

slice_list (Optional[List[int]]) – list of slice indexes to project (e.g. 0, 1, 4-8, 15); if None, a dialog is opened; if empty, all slices are used.

Return type:

bool

Returns:

True if the maximum intensity projection was created, False if not.

cbPropagateBalloons(firstSlice=None, lastSlice=None, xcorrWindowSize=None, wait_for_thread=False)

Transfer polylines to subsequent slices. The displacement across slices is quantified based on the local cross-correlation and applied to the seeds. Then re-expand using a balloon (with no balloon force).

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • xcorrWindowSize (Optional[int]) – width in pixels of the window size used to calculate the local cross-correlation.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if balloon propagation runs, False if the process is cancelled.

cbPropagateSeeds(firstSlice=None, lastSlice=None, xcorrWindowSize=None, wait_for_thread=False)

Transfer fiducials to subsequent slices. The displacement across slices is quantified based on the local cross-correlation and applied to the seeds.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • xcorrWindowSize (Optional[int]) – width in pixels of the window size used to calculate the local cross-correlation.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if seed propagation runs, False if the process is cancelled.

cbRegisterImage()

Register imaage slices containing fiducial annotations that label corresponding image features.

Return type:

bool

Returns:

True.

cbRescaleImage(scale_factor=(1.0, 1.0))

Rescale image (and annotations) along the X, Y axes.

Parameters:

scale_factor (Tuple[float, float]) – scale factors for rows and columns.

Return type:

bool

Returns:

True if the image was rescaled, False if the scale factor tuple is not properly formatted.

cbRotateImage(direction=90)

Rotate image and image annotations by 90 degrees.

Parameters:

direction (int) – one of pjs.image.CW (clockwise) or pjs.image.CCW (counterclockwise).

Return type:

bool

Returns:

True.

cbSegmentDetectedObjects(firstSlice=None, lastSlice=None, sigma=None, wait_for_thread=False)

Segment individual objects included within polylines. Places a seed in the centre of each polyline and a second one in the dimmest corner, and runs a watershed-based segmentation.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • sigma (Optional[float]) – standard deviation of the Gaussian filter applied to smoothen the image.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the segmentation runs, False if the process is cancelled.

cbSubstack(first_slice=0, last_slice=-1, new_window=False)

Create a substack.

Parameters:

  • first_slice (int) – first slice to include in the substack (indexing from 1).

  • last_slice (int) – last slice (inclusive!!) to include in the substack (indexing from 1).

  • new_window (bool) – set to False.

Return type:

bool

Returns:

True if the substrack is created, False otherwise.

cbTimeSlider()

Jump to the slice indicated by the value of the time slider on the display window.

Return type:

bool

Returns:

True.

cbZoom(zoom_index=-1)

Zoom in/out of the open image.

Parameters:

zoom_index (int) – index into a tuple of possible zoom factors (PyJAMAS.zoom_factors).

Returns:

make_substack(first_slice=0, last_slice=-1, new_window=False)

From first_slice to last_slice-1, indexing from 0.

pjs.classifiers

class pyjamas.rcallbacks.rcbclassifiers.RCBClassifiers(ui)
cbApplyClassifier(firstSlice=None, lastSlice=None, wait_for_thread=False)

Apply the current classifier to detect objects in the open image.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1); a dialog will open if this parameter is None.

  • lastSlice (Optional[int]) – slice number for the last slice to use; a dialog will open if this parameter is None.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier is applied, False if the process is cancelled.

cbCreateLR(parameters=None, wait_for_thread=False)

Create a logistic regression classifier.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters to create a logistic regression classifier; a dialog opens if this parameter is set to None; keys are:

    positive_training_folder:

    path to the folder containing positive training images, formatted as a string

    negative_training_folder:

    path to the folder containing negative training images, formatted as a string

    hard_negative_training_folder:

    path to the folder containing hard negative training images, formatted as a string

    histogram_of_gradients:

    use the distribution of gradient orientations as image features, True or False

    train_image_size:

    the number of rows and columns in the positive and negative training images, formatted as a tuple of two integers

    step_sz:

    number of pixel rows and columns to skip when scanning test images for target structures, formatted as a tuple of two integers

    misclass_penalty_C:

    penalty for misclassification of training samples, formatted as a float

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier was successfully created, False otherwise.

cbCreateQuickieNet(parameters=None, wait_for_thread=False)

Create a convolutional neural network with ReSCUNet architecture but training on entire images, not individual objects. Much faster (and probably more inaccurate) than ReSCUNet.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters to create a ReSCUNet; a dialog opens if this parameter is set to None; keys are:

    positive_training_folder:

    path to the folder containing positive training images, formatted as a string

    train_image_size:

    the number of rows and columns in the network input (train images will be scaled to this size) formatted as a tuple of two integers, both of the integers must be divisible by 16.

    step_sz:

    number of pixel rows and columns to divide test images into, each subimage will be scaled to the network input size and processed, formatted as a tuple of two integers

    epochs:

    maximum number of iterations over the training data, as an int

    learning_rate:

    step size when updating the weights, as a float

    mini_batch_size:

    size of mini batches, as an int

    erosion_width:

    width of the erosion kernel to apply to the labeled image produced by the UNet, to separate touching objects, as an int

    concatenation_depth:

    number of encoder blocks before previous segmentation mask and current image frame input streams are combined in the network

    generate_notebook:

    whether a Jupyter notebook to create and train the UNet (e.g. in Google Colab) should be generated, as a bool (if True, the UNet will NOT be created)

    notebook_path:

    where to store the Jupyter notebook if it must be created

    save_folder:

    where to store resized images and weight maps, if empty the resized images and weight maps will not be saved

    resize_images_flag:

    whether or not to resize images, resized images and weight_maps will be loaded from positive_training_folder if False

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier was successfully created, False otherwise.

cbCreateReSCUNet(parameters=None, wait_for_thread=False)

Create a convolutional neural network with ReSCUNet architecture.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters to create a ReSCUNet; a dialog opens if this parameter is set to None; keys are:

    positive_training_folder:

    path to the folder containing positive training images, formatted as a string

    train_image_size:

    the number of rows and columns in the network input (train images will be scaled to this size) formatted as a tuple of two integers, both of the integers must be divisible by 16.

    step_sz:

    number of pixel rows and columns to divide test images into, each subimage will be scaled to the network input size and processed, formatted as a tuple of two integers

    epochs:

    maximum number of iterations over the training data, as an int

    learning_rate:

    step size when updating the weights, as a float

    mini_batch_size:

    size of mini batches, as an int

    erosion_width:

    width of the erosion kernel to apply to the labeled image produced by the UNet, to separate touching objects, as an int

    concatenation_depth:

    number of encoder blocks before previous segmentation mask and current image frame input streams are combined in the network

    generate_notebook:

    whether a Jupyter notebook to create and train the UNet (e.g. in Google Colab) should be generated, as a bool (if True, the UNet will NOT be created)

    notebook_path:

    where to store the Jupyter notebook if it must be created

    save_folder:

    where to store resized images and weight maps, if empty the resized images and weight maps will not be saved

    resize_images_flag:

    whether or not to resize images, resized images and weight_maps will be loaded from positive_training_folder if False

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier was successfully created, False otherwise.

cbCreateSVM(parameters=None, wait_for_thread=False)

Create a support vector machine classifier.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters to create a logistic regression classifier; a dialog opens if this parameter is set to None; keys are:

    positive_training_folder:

    path to the folder containing positive training images, formatted as a string

    negative_training_folder:

    path to the folder containing negative training images, formatted as a string

    hard_negative_training_folder:

    path to the folder containing hard negative training images, formatted as a string

    histogram_of_gradients:

    use the distribution of gradient orientations as image features, True or False

    train_image_size:

    the number of rows and columns in the positive and negative training images, formatted as a tuple of two integers

    step_sz:

    number of pixel rows and columns to skip when scanning test images for target structures, formatted as a tuple of two integers

    misclass_penalty_C:

    penalty for misclassification of training samples, formatted as a float

    kernel_type:

    type of kernel (‘linear’ or ‘rbf’)

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier was successfully created, False otherwise.

cbCreateUNet(parameters=None, wait_for_thread=False)

Create a convolutional neural network with UNet architecture.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters to create a UNet; a dialog opens if this parameter is set to None; keys are:

    positive_training_folder:

    path to the folder containing positive training images, formatted as a string

    train_image_size:

    the number of rows and columns in the network input (train images will be scaled to this size) formatted as a tuple of two integers, both of the integers must be divisible by 16.

    step_sz:

    number of pixel rows and columns to divide test images into, each subimage will be scaled to the network input size and processed, formatted as a tuple of two integers

    epochs:

    maximum number of iterations over the training data, as an int

    learning_rate:

    step size when updating the weights, as a float

    mini_batch_size:

    size of mini batches, as an int

    erosion_width:

    width of the erosion kernel to apply to the labeled image produced by the UNet, to separate touching objects, as an int

    generate_notebook:

    whether a Jupyter notebook to create and train the UNet (e.g. in Google Colab) should be generated, as a bool (if True, the UNet will NOT be created)

    notebook_path:

    where to store the Jupyter notebook if it must be created

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the classifier was successfully created, False otherwise.

cbNonMaxSuppression(parameters=None, firstSlice=None, lastSlice=None)

Apply non-maximum suppression to remove redundant objects from an image.

Parameters:

  • parameters (Optional[dict]) –

    dictionary containing the parameters for non-maximum suppression; a dialog will open if this parameter is None; keys are:

    prob_threshold:

    lower threshold for the probability that a detected object represents an instance of the positive training set (returned by the classifier), as a float

    iou_threshold:

    maximum value for the intersection-over-union ratio for the area of two detected objects, as a float; 0.0 prevents any overlaps between objects, 1.0 allows full overlap

    max_num_objects:

    maximum number of objects present in the image, as an integer; objects will be discarded from lowest to highest probability of the object representing an instance of the positive training set

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1); a dialog will open if this parameter is None.

  • lastSlice (Optional[int]) – slice number for the last slice to use; a dialog will open if this parameter is None.

Return type:

bool

Returns:

True if non-maximum suppression is applied, False if the process is cancelled.

cbSetNeuralNetStepSize(step_sz=None)

Set the step size for tiling over an input image when applying a convolutional neural network. If step_sz >= train_image_size no tiling occurs.

Parameters:

step_sz (tuple) – the step size (int, int) for tiling in the vertical and horizontal directions.

Return type:

bool

Returns:

True if option is succesfully set, False otherwise.

pjs.annotations

class pyjamas.rcallbacks.rcbannotations.RCBAnnotations(ui)
cbCopyPolyline()

Set annotation mode to copy the polyline clicked on (stored in pjs._copied_poly_).

Return type:

bool

Returns:

True.

cbDeleteAllAnn()

Delete annotations from all image slices.

Return type:

bool

Returns:

True.

cbDeleteAllFiducials()

Delete all fiducials from all slices.

Return type:

bool

Returns:

True

cbDeleteFiducialsInsidePoly()

Set annotation mode to remove fiducials inside the polyline clicked on.

Return type:

bool

Returns:

True.

cbDeleteFiducialsOutsidePoly()

Set annotation mode to remove fiducials outside the polyline clicked on.

Return type:

bool

Returns:

True.

cbDeleteSliceAnn(index=None)

Delete annotations from a specific slice.

Parameters:

index (Optional[int]) – index of the slice in which annotations will be deleted (>=0). Defaults to the current slice (pjs.curslice).

Return type:

bool

Returns:

True.

cbDeleteSliceFiducials(index=None)

Delete fiducials from a specific slice.

Parameters:

index (Optional[int]) – index of the slice in which fiducials will be deleted (>=0). Defaults to the current slice (pjs.curslice).

Return type:

bool

Returns:

True

cbDeleteSlicePoly(index=None)

Delete polylines from a specific slice.

Parameters:

index (Optional[int]) – index of the slice in which polylines will be deleted (>=0). Defaults to the current slice (pjs.curslice).

Return type:

bool

Returns:

True.

cbDilateErodePolyline()

Set annotation mode to dilate or erode the polyline clicked on.

Return type:

bool

Returns:

True.

cbFiducials()

Set annotation mode to add/remove fiducials.

Return type:

bool

Returns:

True.

cbHideAnn()

Toggle annotations off/on the screen.

Return type:

bool

Returns:

True.

cbInflateBalloon()

Set annotation mode to add/remove polylines using active contours for semi-automated object delineation.

Return type:

bool

Returns:

True.

cbLiveWire()

Set annotation mode to add/remove polylines using the LiveWire algorithm for semi-automated object delineation. The LiveWire is implemented using an A* algorithm, with a Euclidean distance heuristic.

Return type:

bool

Returns:

True.

cbMovePolyline()

Set annotation mode to move the polyline clicked on.

Return type:

bool

Returns:

True.

cbNoAnn()

Reset annotation mode: no action upon mouse click.

Return type:

bool

Returns:

True.

cbPastePolyline(paste_shifted=False)

Paste the polyline previously copied (stored in pjs._copied_poly_).

Return type:

object

Returns:

True if polyline was copied, False otherwise.

cbPolylines()

Set annotation mode to add/remove polylines.

Return type:

bool

Returns:

True.

cbRectangles()

Set annotation mode to add/remove rectangles (a specific type of polyline).

Return type:

bool

Returns:

True.

cbTrackFiducials(firstSlice=None, lastSlice=None, wait_for_thread=False)

Match fiducials across slices in a stack based on minimum distance. Requires a constant number of fiducials. Runs in a different thread.

Parameters:

  • firstSlice (Optional[int]) – start slice (>=1).

  • lastSlice (Optional[int]) – final slice.

  • wait_for_thread (bool) – True if PyJAMAS should wait for the function to finish before returning control to the user, False otherwise.

Return type:

bool

Returns:

True if tracking finished correctly, False otherwise.

pjs.measurements

class pyjamas.rcallbacks.rcbmeasure.RCBMeasure(ui)
cbMeasurePoly(firstSlice=None, lastSlice=None, measurements=None, filename=None)

Measure polylines.

A dialog will be opened if any parameters are set to None.

Parameters:

  • firstSlice (Optional[int]) – slice number for the first slice to use (minimum is 1).

  • lastSlice (Optional[int]) – slice number for the last slice to use.

  • measurements (Optional[dict]) –

    dictionary with the following keys:

    area:

    True|False

    perimeter:

    True|False

    pixels:

    True|False

    image:

    True|False

    sample:

    True|False

  • filename (Optional[str]) – path and file name where the measurement results will be saved; results are saved in .csv format. If filename==’’, no results are saved.

Return type:

dict

Returns:

dictionary with measurement results.

pjs.batch

class pyjamas.rcallbacks.rcbbatchprocess.RCBBatchProcess(ui)
cbBatchFlatFieldCorrection(parameters=None)

Flat field correction of all images within a given folder or folder tree.

Parameters:

parameters (Optional[dict]) –

dictionary with parameters, a dialog will open if the value is none.

input_folder:

absolute path to the folder containing all images to be resized.

darkfield_file:

path to the file containing the image to correct for darkfield, ‘’ or None of no darkfield correction.

flatfield_file:

path to the file containing the image to correct for flatfield, ‘’ or None of no flatfield correction.

crop_dims:

tuple with (row, col) dimensions to crop the images before applying any corrections, None for no cropping.

bg_mode:

background subtraction, None if no background subtraction, ‘mode’ if the background is the volume mode.

input_substr:

substring to refine input files corrected, ‘’ to correct all images.

file_suffix:

suffix to add to the file name of the corrected images.

Return type:

bool

Returns:

True if correction complete, False otherwise.

cbBatchProjectConcat(input_folder_name=None, slice_str=None, output_file_name=None, projection_type=projection_types.MAX, wait_for_thread=False)

Project all the 3D images in a folder and concatenate all the maximum intensity projections into a new 3D image.

A dialog will be opened if any parameters are set to None.

Parameters:

  • input_folder_name (Optional[str]) – path to the folder that contains the images to project and concatenate.

  • slice_str (Optional[str]) – slice indexes to use for projection (e.g. ‘0, 2-4, 12’).

  • output_file_name (Optional[str]) – path and file name to save the image resulting from projecting and concatenating the images in input_folder_name.

  • projection_type (projection_types) – determines the type of projection to use (max, sum, etc.); value is one of rcbbatchprocess.projection_types.

  • wait_for_thread (bool) – True if PyJAMAS must wait for the thread running this operation to complete, False otherwise.

Return type:

bool

Returns:

True if the projected and concatenated image is saved, False otherwise.

cbBatchResize(parameters=None)

Resizes all images within a given folder or folder tree to a specified size and saves them to a new folder.

Parameters:

parameters (Optional[dict]) –

dictionary with parameters, a dialog will open if the value is none.

input_folder: absolute path to the folder containing all images to be resized. save_folder: absolute path to the folder that resized images will be saved to. im_size: tuple containing the new image size in (rows, cols), eq. (height, width). recurr: When set to true, the folder tree will be searched recursively for images to be resized.

Return type:

bool

Returns:

True if resizing complete, False otherwise.

cbMeasureBatch(parameters=None)

Measures image data sets and produces plots and CSV files that combine all the data. A Python script to reproduce the analysis, and a Jupyter notebook to reproduce the analysis and generate the plots can also be generated.

Parameters:

parameters (Optional[dict]) –

dictionary containing measurement parameters; a dialog will open if the value is set to None; dictionary keys are:

folders:

paths to the folders containing each of the data sets to compared, formatted as a list of strings; each folder will contain subfolders, each with different images and annotation files

names:

labels for the datasets to be compared, formatted as a list of strings

t_res:

time resolution in seconds, formatted as a float

index_time_zero:

the slice index in timeseries corresponding to time zero, formatted as an integer

xy_res:

spatial resolution in microns, formatted as float

brush_sz:

size of the brush used to quantify intensity under polyline annotations, formatted as an integer

intensity_flag:

determines whether pixel values (and not only morphological features) are measured, set to True or False

image_extension:

extension of the images to be loaded for intensity analysis, formatted a string

normalize_intensity_flag:
determines the procedure to normalize pixel values in time sequences, set to one of pjs.batch.normalization_modes:

RAW_INTENSITIES – no normalization PHOTOBLEACHING – divide by the image mean (the photobleaching normalization factor is 1 for first image in the sequence) BACKGROUND_PHOTOBLEACHING_MEAN_IMAGE - subtract the image mode and divide by the image mean (the photobleaching normalization factor is 1 for first image in the sequence) PHOTOBLEACHING_MEAN_SAMPLE - detect the sample and divide by the sample mean (the photobleaching normalization factor is 1 for first image in the sequence) BACKGROUND_PHOTOBLEACHING_MEAN_SAMPLE - detect the sample, subtract the sample mode and divide by the sample mean (the photobleaching normalization factor is 1 for first image in the sequence) BACKGROUND_PHOTOBLEACHING_MEAN_FILE - use a file with either a single slice or as many slices as the original image, and named as the original image with PyJAMAS.backgroundimage_extension (the photobleaching normalization factor is 1 for first image in the sequence).

analysis_filename_appendix:

suffix to be added to the name of the csv file used to save the analysis results, formatted as a string

analysis_extension:

extension of the csv file used to save analysis results, formatted as a string

err_style_value:

determines how error is displayed in plots averaging multiple data sets, set to either ‘band’ or ‘bar’

plot_style_value:

determines how distributions are displayed, set to ‘strip, ‘box’ or ‘violin’

analyze_flag:

determines whether annotations are measured, or if previously stored measurement values are used for plotting (faster), set to True or False

save_results:

determines whether overall results are saved (in a csv file) and a Jupyter notebook to reproduce analysis and plot produced, set to True or False

results_folder:

path to the folder where overall quantification results, notebook, and plots will be saved, formatted as a string

script_filename_appendix:

appendix to be added to the name of a file containing a Jupyter notebook that can be used to reproduce the analysis results and plots, formatted as a string

Return type:

bool

Returns:

True if the measurements complete, False otherwise.

pjs.plugins

class pyjamas.rcallbacks.rcbplugins.RCBPlugins(ui)
cbInstallPlugin(filename=None)

Install plugin: Copy plugin to the plugins folder (pjs.plugin_path) and load it into the plugins menu.

Parameters:

filename (Optional[str]) – path and file name of the plugin to be installed; a dialog opens if the file name is empty or None.

Returns:

True if the plugin was installed, False if the install was cancelled.

cbLoadPlugins()

Load plugins into the plugins menu. Searches for plugins under pjs.plugin_path.

Return type:

True

Returns:

True.

cbUninstallPlugin(plugin_name=None)

Uninstall plugin: delete the folder for a given plugin from the PyJAMAS plugins directory.

Parameters:

plugin_name (str) – name of the plugin to be deleted.

Returns:

True if the plugin was uninstalled, False if the operation was cancelled.

pjs.about

class pyjamas.rcallbacks.rcbabout.RCBAbout(ui)
cbAbout()

Displays the PyJAMAS license file (contained in LICENSE).

Return type:

bool

Returns:

True.