neurotorchmz.utils.synapse_detection

Contents

neurotorchmz.utils.synapse_detection#

Classes for describing ROIs, synapses and detection algorithms

Classes

CircularSynapseROI()

Implements a circular ROI of a given radius

DetectionResult()

Class to store the result of synapse detections

HysteresisTh()

IDetectionAlgorithm()

Abstract base class for a detection algorithm implementation

ISynapse()

This abstract class defines the concept of a synapse.

ISynapseROI()

This abstract class defines a synapse ROI describing a specific shape in an image or image frame

LocalMax()

Implementation of the LocalMax algorithm for ROI detection.

MultiframeSynapse()

Implements a synapse which can hold multiple rois (one for each frame)

PolygonalSynapseROI()

Implements a polygonal synapse ROI

ROIList()

Implements a list of ROIS, but allows to access them via their UUID as in a dict.

SimpleCustering()

SingleframeSynapse([roi])

Implements a synapse class which can hold exactly one ROI

SynapseClusteringAlgorithm()

A synapse clustering algorithm merges a list of ROIs detected from a defined list of frames to a new list of synapses.

Thresholding()

Implementation of the thresholding detection algorithm.

Exceptions

DetectionError

Error thrown by calling detect() on a IDetectionAlgorithm object indicating something went wrong in the detection process.
class neurotorchmz.utils.synapse_detection.CircularSynapseROI#

Bases: ISynapseROI

Implements a circular ROI of a given radius

CLASS_DESC = 'Circular ROI'#

Every subclass defines a description string

_radius: float | None#

Radius of the ROI

get_coordinates(shape: tuple) → tuple[ndarray | list, ndarray | list]#

Return coordinates of points inside the ROI and inside the given shape. They are returned as a tuple with the first parameter beeing the y coordinates and the second the x coordinates.

Example output: ([Y0, Y1, Y2, …], [X0, X1, X2, …])

Returns tuple[np.array, np.array]:

The coordinates inside the ROI in the format [yy, xx]

property radius: float | None#
set_radius(radius: int | float | None) → Self#

Set the radius of the ROI

exception neurotorchmz.utils.synapse_detection.DetectionError#

Bases: Exception

Error thrown by calling detect() on a IDetectionAlgorithm object indicating something went wrong in the detection process.

class neurotorchmz.utils.synapse_detection.DetectionResult#

Bases: object

Class to store the result of synapse detections

_callbacks: list[Callable[[list[ISynapse], list[ISynapse], list[ISynapse]], None]]#
_synapses: dict[str, ISynapse]#
_synapses_callbacks: dict[str, Callable[[], None]]#
append(synapse: ISynapse, /) → None#
as_dict() → dict[str, ISynapse]#
clear() → None#
clear_where(fn: Callable[[ISynapse], bool]) → None#
export_traces(path: Path, imgObj: ImageObject, include_index=False) → bool#

Exports the detection result traces as csv file given an ImageObject

Parameters:

  • path (Path) – The path to export to

  • imgObj (ImageObject) – The ImageObject used to extract the traces

  • include_index (bool) – If True, the traces are exported with an index column

Return bool:

True if the data was exported, False otherwise

extend(synapses: Iterable[ISynapse], /) → None#
notify(added: list[ISynapse] = [], removed: list[ISynapse] = [], modified: list[ISynapse] = []) → None#

Notify all registered callbacks

register_callback(callback: Callable[[list[ISynapse], list[ISynapse], list[ISynapse]], None]) → None#

Register a callback on this results object. The callback must accept three lists of ISynapse (added, removed and modified) and will be called whenever the result changes

remove(synapse: ISynapse) → None#
remove_callback(callback: Callable[[list[ISynapse], list[ISynapse], list[ISynapse]], None]) → None#

Remove a callback

to_list() → list[ISynapse]#
to_pandas(imgObj: ImageObject) → DataFrame | None#

Returns a pandas dataframe of the traces given the ImageObject. Returns None if the ImageObject has no valid image

class neurotorchmz.utils.synapse_detection.HysteresisTh#

Bases: IDetectionAlgorithm

detect(img: ndarray, lowerThreshold: int | float, upperThreshold: int | float, minArea: int | float, **kwargs) → list[ISynapseROI]#

Find ROIs in a given image. For details see the documentation

Parameters:

  • img (np.ndarray) – The image as 2D numpy array

  • lowerThreshold (int|float) – lower threshold for detection

  • upperThreshold (int|float) – upper threshold for detection

  • minArea (int|float) – Consider only ROIs with a pixel area greater than the given value

reset()#

Abstract funtion which must be overwritten by a subclass to reset internal variables and states

class neurotorchmz.utils.synapse_detection.IDetectionAlgorithm#

Bases: object

Abstract base class for a detection algorithm implementation

detect(img: ndarray, **kwargs) → list[ISynapseROI]#

Given an input image as 2D np.ndarray and algorithm dependend arbitary arguments, return a list of ISynapseROI.

Parameters:

img (np.ndarray) – The input image as 2D array

reset()#

Abstract funtion which must be overwritten by a subclass to reset internal variables and states

class neurotorchmz.utils.synapse_detection.ISynapse#

Bases: object

This abstract class defines the concept of a synapse. Currently there are two types of synapses: Singleframe and Multiframe.

_callbacks: list[Callable[[], None]]#
_format(append_str: str) → str#
_name: str | None#
_staged: bool#
get_roi_description() → str#

Abstract function for displaying information about the rois. Needs to be implemented by each subclass

property location: tuple[float, float] | None#

Returns the location of the synapse (Y, X) or None

property location_string: str#

Returns the location of the synapse in the format ‘X, Y’ or ‘’ if the location is not set

property location_x: float | None#
property location_y: float | None#
property name: str | None#

Returns the name of the synapse or None

notify() → None#

Notify all callbacks that some properties have changed

register_callback(callback: Callable[[], None]) → None#

Register a callback. The callback is called when properties of the ISynapse object have been modified

remove_callback(callback: Callable[[], None]) → None#

Removes a callback

set_name(name: str | None) → Self#
property staged: bool#

A synapse can be staged meaning it will not be replaced when rerunning the detection

property uuid: str#

Returns the unique and nopt mutable UUID of the synapse object

class neurotorchmz.utils.synapse_detection.ISynapseROI#

Bases: object

This abstract class defines a synapse ROI describing a specific shape in an image or image frame

Convention: The order of coordiantes is Y, X to be compatible with the shape of the image (t, row, col). But for any kind of displaying convert them to X, Y to not cofuse the user

CLASS_DESC = 'ISynapseROI'#

Every subclass defines a description string

_callbacks: list[Callable[[], None]]#
_frame: int | None#
_location: tuple[float, float] | None#
_region_props: RegionProperties | None#
_signal_strength: float | None#
property frame: int | None#

The associate frame for this ROI or None if the object just defines a shape

get_coordinates(shape: tuple) → tuple[ndarray | list, ndarray | list]#

Return coordinates of points inside the ROI and inside the given shape. They are returned as a tuple with the first parameter beeing the y coordinates and the second the x coordinates.

Example output: ([Y0, Y1, Y2, …], [X0, X1, X2, …])

Returns tuple[np.array, np.array]:

The coordinates inside the ROI in the format [yy, xx]

static get_distance(loc1: tuple[float, float] | None, loc2: tuple[float, float] | None) → float#

Returns the distance between two locations (as used in a ISynapseROI) or None if one of the locations is None

static get_distance_between_rois(roi1: ISynapseROI, roi2: ISynapseROI) → float#

Returns the distance between the locations of the ROIs or np.inf if at least one has no location

get_signal_from_image(img: ndarray) → ndarray#

Given an 3D ImageObject (t, y, x), flatten x and y to the pixels given by get_coordinates providing a shape (t, num_image_mask_pixel)

property location: tuple[float, float] | None#

Returns the location of the ROI (Y, X) or None

property location_string: str#

Returns the location of the synapse in the format ‘X, Y’ or ‘’ if the location is not set

property location_x: float | None#
property location_y: float | None#
notify() → None#

Notify all callbacks that some properties have changed

property region_props: RegionProperties | None#

Stores skimage RegionProperties for the ROI

register_callback(callback: Callable[[], None]) → None#

Register a callback. The callback is called when properties of the ISynapseROI object have been modified

remove_callback(callback: Callable[[], None]) → None#

Removes a callback

set_frame(frame: int | None) → Self#

Set the frame of the synapse or removes it by providing None

set_location(*, location: tuple[int | float, int | float] | None = None, y: int | float | None = None, x: int | float | None = None) → Self#

Set the location of the synapse by either providing a tuple or Y and X explicitly

Parameters:

  • location (tuple[int|float, int|float]) – Location tuple (Y, X)

  • y (int|float)

  • x (int|float)

set_region_props(region_props: RegionProperties | None) → Self#

Set skimage.RegionProperties for this synapse

set_signal_strength(signal_strength: float | None) → Self#
property signal_strength: float | None#

Optional parameter to determine the current signal strength of the ROI

property uuid: str#

Returns the unique and nopt mutable UUID of the synapse object

class neurotorchmz.utils.synapse_detection.LocalMax#

Bases: IDetectionAlgorithm

Implementation of the LocalMax algorithm for ROI detection. For details see the documentation

detect(img: ndarray, lowerThreshold: int | float, upperThreshold: int | float, expandSize: int, minArea: int, minDistance: int, radius: int | float | None, **kwargs) → list[ISynapseROI]#

Detect ROIs in the given 2D image. For details see the documentation

Find ROIs in a given image. For details see the documentation

Parameters:

  • img (np.ndarray) – The image as 2D numpy array

  • lowerThreshold (int|float) – The lower threshold

  • upperThreshold (int|float) – The upper threshold

  • expandSize (int) – Pixel to expand the peak search into

  • minArea (int) – Minimum area of a ROI

  • minDistance (int) – Mimum distance between two ROIs

  • radius (int|float|None) – Returns circular ROIs if radius >= 0 and polygonal ROIs if radius is None. Raises exception otherwise

reset()#

Abstract funtion which must be overwritten by a subclass to reset internal variables and states

class neurotorchmz.utils.synapse_detection.MultiframeSynapse#

Bases: ISynapse

Implements a synapse which can hold multiple rois (one for each frame)

_location: tuple[float, float] | None#
extend_rois(rois: list[ISynapseROI]) → Self#

Add a range of rois to the synapse

get_roi_description() → str#

In the future return information about the rois. Currently, only the text ‘Multiframe Synapse’ is returned

property location: tuple[float, float] | None#

Returns the location of the synapse (Y, X) or None

set_location(*, location: tuple[float, float] | None = None, y: float | None = None, x: float | None = None) → Self#

Set the location of the synapse by either providing a tuple or Y and X explicitly which is for example used for sorting them. There is no need to provide an exact center

Parameters:

  • location (tuple[int|float, int|float]) – Location tuple (Y, X)

  • y (int|float)

  • x (int|float)

set_rois(rois: list[ISynapseROI]) → Self#

Add a range of rois to the synapse

class neurotorchmz.utils.synapse_detection.PolygonalSynapseROI#

Bases: ISynapseROI

Implements a polygonal synapse ROI

CLASS_DESC = 'Polyonal ROI'#

Every subclass defines a description string

_coords: list[tuple[int, int]] | None#
_polygon: ndarray | None#
property coords: list[tuple[int, int]] | None#

List of points inside the polygon in the format [(Y, X), (Y, X), ..]

get_coordinates(shape: tuple) → tuple[ndarray | list, ndarray | list]#

Return coordinates of points inside the ROI and inside the given shape. They are returned as a tuple with the first parameter beeing the y coordinates and the second the x coordinates.

Example output: ([Y0, Y1, Y2, …], [X0, X1, X2, …])

Returns tuple[np.array, np.array]:

The coordinates inside the ROI in the format [yy, xx]

property polygon: ndarray | None#

List of polygon points in the format [(Y, X), (Y, X), ..]

set_polygon(polygon: ndarray, coords: list[tuple[int, int]] | None = None, region_props: RegionProperties | None = None)#

Set the polygon by providing the coordinate tuples and either a) the pixel coords or b) a RegionProperties object (from which the coords are derived)

Parameters:

  • polygon (np.ndarray[(int, 2), Any]) – The contour of the polygon in the format [(Y, X), (Y, X), ..]

  • coords (list[tuple[int, int]]) – The pixel coordinates of the polygon in the format [(Y, X), (Y, X), ..]. Either it or a RegionProperties object must be given

  • region_props (RegionPropertiers) – A region_props object. Either it or the coords must be given

class neurotorchmz.utils.synapse_detection.ROIList#

Bases: object

Implements a list of ROIS, but allows to access them via their UUID as in a dict. Also, a callback system is implemented

_callbacks: list[Callable[[list[ISynapseROI], list[ISynapseROI], list[ISynapseROI]], None]]#
_rois: dict[str, ISynapseROI]#
_rois_callbacks: dict[str, Callable[[], None]]#
append(synapse: ISynapseROI, /) → None#
as_dict() → dict[str, ISynapseROI]#
clear() → None#
clear_where(fn: Callable[[ISynapseROI], bool]) → None#
extend(rois: Iterable[ISynapseROI], /) → None#
notify(added: list[ISynapseROI] = [], removed: list[ISynapseROI] = [], modified: list[ISynapseROI] = []) → None#

Notify all registered callbacks

register_callback(callback: Callable[[list[ISynapseROI], list[ISynapseROI], list[ISynapseROI]], None]) → None#

Register a callback on this results object. The callback must accept three lists of ISynapseROI (added, removed and modified) and will be called whenever the result changes

remove(roi: ISynapseROI) → None#
remove_callback(callback: Callable[[list[ISynapseROI], list[ISynapseROI], list[ISynapseROI]], None]) → None#

Remove a callback

to_list() → list[ISynapseROI]#
class neurotorchmz.utils.synapse_detection.SimpleCustering#

Bases: SynapseClusteringAlgorithm

static cluster(rois: list[ISynapseROI]) → list[ISynapse]#
class neurotorchmz.utils.synapse_detection.SingleframeSynapse(roi: ISynapseROI | None = None)#

Bases: ISynapse

Implements a synapse class which can hold exactly one ROI

get_roi_description() → str#

Displays information about the roi by calling str(roi)

property location: tuple[float, float] | None#

Returns the location of the synapse (Y, X) or None

set_roi(roi: ISynapseROI | None = None) → Self#

Set the ROI or remove it by passing None or no argument

class neurotorchmz.utils.synapse_detection.SynapseClusteringAlgorithm#

Bases: object

A synapse clustering algorithm merges a list of ROIs detected from a defined list of frames to a new list of synapses.

static cluster(rois: list[ISynapseROI]) → list[ISynapse]#
class neurotorchmz.utils.synapse_detection.Thresholding#

Bases: IDetectionAlgorithm

Implementation of the thresholding detection algorithm. For details see the documentation

detect(img: ndarray, threshold: int | float, radius: int | float | None, minArea: int | float | None, **kwargs) → list[ISynapseROI]#

Find ROIs in a given image. For details see the documentation

Parameters:

  • img (np.ndarray) – The image as 2D numpy array

  • threshold (int|float) – Detection is performed on a thresholded image

  • radius (int|float|None) – Returns circular ROIs if radius >= 0 and polygonal ROIs if radius is None. Raises exception otherwise

  • minArea (int|float) – Consider only ROIs with a pixel area greater than the provided value

reset()#

Abstract funtion which must be overwritten by a subclass to reset internal variables and states

Contents