Domain-specific objects

class pydetecdiv.domain.Project.Project(dbname: str = None, dbms: str = None)

Bases: object

Project class to keep track of the database connection and providing basic methods to retrieve objects. Actually hides repository from other domain classes. This class handles actual records and domain-specific objects while the repository deals with records and data-access objects. Data exchange between Repository and Project objects is achieved through the use of dict representing standardized records.

property path: str

Property returning the path of the project

Returns:

property uuid: str

Property returning the uuid associated to this project

Returns:

property author: str

Property returning the author associated to this project

Returns:

property date: datetime

Property returning the date of this project

Returns:

property raw_dataset: Dataset

Property returning the raw dataset object associated to this project

Returns:

commit() → None

Commit operations performed on objects (creation and update) to save them into the repository.

cancel() → None

Cancel operations performed on objects since last commit

import_images(image_files: list[str], destination: str = None, **kwargs) → Popen

Import images specified in a list of files into a destination

Parameters:

• image_files – list of image files to import

• destination – destination directory to import files into

• kwargs – extra keyword arguments

Returns:

the list of imported files. This list can be used to roll the copy back if needed

import_images_from_metadata(metadata_files: str, destination: str = None, author: str = '', date: datetime | str = 'now', in_place: bool = True, img_format: str = 'imagetiff', **kwargs) → None

Import images specified in a list of files into a destination

Parameters:

• metadata_files – list of metadata files to load and get information from for image import

• destination – destination directory to import image files into

• kwargs – extra keyword arguments

annotate(dataset: Dataset, source: str | Callable, columns: list[str], regex: str) → DataFrame

Annotate data in a dataset using a regular expression applied to columns specified by source (column name or callable returning a str built from column names)

Parameters:

• dataset (Dataset object) – the dataset DSO whose data should be annotated

• source (str or callable) – source column(s) used to determine the annotations

• columns (tuple of str) – annotation columns to add to the dataframe representing Data objects

• regex (str) – the regular expression defining columns

Returns:

a table representing annotated Data objects

Return type:

pandas DataFrame

create_fov_from_raw_data(df: DataFrame, multi: bool) → None

Create domain-specific objects from raw data using a regular expression applied to a database field or a combination thereof specified by source. DSOs to create are specified by the values in keys.

id_mapping(class_name: str) → dict[str, int]

Return name to id mapping for objects of a given class

Parameters:

class_name – the class name

Returns:

the name to id mapping

save_record(class_name: str, record: dict[str, Any]) → int

Creates and saves an object of class named class_name from its record without requiring the creation of a DSO. This method can be useful for creating associated objects with mutual dependency.

Parameters:

• class_name (str) – the class name of the object to create

• record (dict) – the record representing the object to create

Returns:

the id of the created object

Return type:

int

save(dso: DSO) → int

Save an object to the repository if it is new or has been modified

Parameters:

dso – the domain-specific object to save

Returns:

the id of the saved object if it was created

delete(dso: DSO) → None

Delete a domain-specific object

Parameters:

dso (object (DomainSpecificObject)) – the object to delete

get_object(class_name: str, id_: int = None, uuid: str = None, use_pool: bool = True) → DSO

Get an object referenced by its id

Parameters:

• class_name (class inheriting DomainSpecificObject) – the class of the requested object

• id (int) – the id reference of the object

• uuid – the uuid of the requested object

• use_pool – True if object should be obtained from the pool unless it has not been created yet

Returns:

the desired object

get_named_object(class_name, name=None) → DSO

Return a named object by its name

Parameters:

• class_name – class name of the requested object

• name – the name of the requested object

Returns:

the object

get_objects(class_name: str, id_list: list[int] = None) → list[DSO]

Get a list of all domain objects of a given class in the current project retrieved from the repository

Parameters:

• class_name (str) – the class name of the domain-specific objects to be returned

• id_list (list of int) – the list of ids for the objects to be retrieved

Returns:

a list of all the objects of that class in the project with all their associated metadata

Return type:

list of the requested domain-specific objects

get_records(class_name: str, id_list: list[int] = None) → list[dict[str, Any]]

get list of dictionary records of DSOs of the specified class with id in list :param class_name: the name of the class :param id_list: the list of ids

get_dataframe(class_name: str, id_list: list[int] = None) → DataFrame

get a pandas DataFrame with records of DSOs of the specified class with id in list :param class_name: the name of the class :param id_list: the list of ids

count_objects(class_name: str) → int

Count all objects of a given class in the current project

Parameters:

class_name (str) – the class name of the domain-specific objects to count

Returns:

the number of objects of the requested class

Return type:

int

has_links(class_name: str, to: DSO = None) → bool

Checks whether there are links to a given object from objects of a given class.

Parameters:

• class_name (str) – the name of the class from which the existence of links is tested

• to (DomainSpecificObject object) – the object which is tested for existence of links from class_name class

Returns:

True if links exist, False otherwise

Return type:

bool

count_links(class_name: str, to: DSO = None) → int

Counts the number of objects of a given class having a link to an object

Parameters:

• class_name (str) – the name of the class whose links to the specified object are counted

• to (DomainSpecificObject object) – the object to which links are counted

Returns:

the number of objects of class class_name that are linked to the specified object

Return type:

int

get_linked_objects(class_name: str, to: DSO = None) → list[otherDSO]

A method returning the list of all objects of class defined by class_name that are linked to an object specified by argument to= Note that for ROIs linked to a FOV, this method also returns the initial ROI (full-FOV) even if other ROIs have been created. If initial ROIs are not desired, then the FOV.roi_list property should be used instead.

Parameters:

• class_name (str) – the class name of the objects to retrieve

• to (DomainSpecificObject) – the object the retrieve objects should be linked to

Returns:

the list of objects linked to linked_to object

Return type:

list of objects

link_objects(dso1: DSO, dso2: otherDSO) → None

Create a direct link between two objects. This method only works for objects that have a direct logical connection defined in an association table. It does not work to create transitive links with intermediate objects

Parameters:

• dso1 (object) – first domain-specific object to link

• dso2 (object) – second domain-specific object to link

unlink_objects(dso1: DSO, dso2: otherDSO) → None

Delete a direct link between two objects. This method only works for objects that have a direct logical connection defined in an association table. It does not work to delete transitive links with intermediate objects

Parameters:

• dso1 (object) – first domain-specific object to unlink

• dso2 (object) – second domain-specific object to unlink

build_dso(class_name: str, rec: dict[str, Any], use_pool: bool = True) → DSO | None

factory method to build a dso of class class_name from record rec or return the pooled object if it was already created. Note that if the object was already in the pool, values in the record are not used to update the object. To make any change to the object’s attribute, the object’s class methods and setter should be used instead as they ensure that values are checked for validity and new attributes are saved to the persistence back-end

Parameters:

• class_name – the class name of the dso to build

• rec – the record representing the object to build (if id_ is not in the record, the object is a new creation

Returns:

the requested object

property info: str

Returns ready-to-print information about project

Returns:

project information

Return type:

str

class pydetecdiv.domain.Experiment.Experiment(uuid: str, author: str, date: datetime, raw_dataset: int, **kwargs)

Bases: NamedDSO

A business-logic class defining valid operations and attributes of an experiment

property raw_dataset: Dataset

property returning the raw dataset object for this experiment

Returns:

raw dataset

record(no_id: bool = False) → dict

Returns a record dictionary of the current Experiment object

Parameters:

no_id – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

class pydetecdiv.domain.Run.Run(tool_name: str = None, tool_version: str = None, is_plugin: bool = False, command: str = None, parameters: dict[str, object] = None, key_val: dict[str, Any] = None, **kwargs)

Bases: DomainSpecificObject

A business-logic class defining valid operations and attributes of data

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Data

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict

execute(tool: CommandLineTool, testing: bool = False)

Execute the job after having installed requirements if necessary

test()

Run the testing

class pydetecdiv.domain.Dataset.Dataset(url: str = '', type_: str = None, run: int = None, pattern: str = None, key_val: dict = None, **kwargs)

Bases: NamedDSO

A business-logic class defining valid operations and attributes of data

property url: str

URL property of the data file, relative to the workspace directory or absolute path if file are stored in place

Returns:

relative or absolute path of the data file

Return type:

str

property data_list: list[Data]

returns the list of data files in dataset

Returns:

list of Data objects

Return type:

list of Data objects

record(no_id: int = False) → dict[str, Any]

Returns a record dictionary of the current Dataset

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict

class pydetecdiv.domain.Data.Data(dataset: int | Dataset, author: str, date: str | datetime, url: str, format_: str, source_dir: str, meta_data: dict, key_val: dict, image_resource: int | ImageResource, c: int = None, t: int = None, z: int = None, xdim: int = -1, ydim: int = -1, uuid: str = None, **kwargs)

Bases: NamedDSO

A business-logic class defining valid operations and attributes of data

property image_resource: ImageResource

property returning the Image resource object this Data file is part of

Returns:

the parent Image resource object

Return type:

ImageResource

property dataset: Dataset

Property returning the Dataset object this data belongs to

Returns:

the Dataset this Data belongs to

Return type:

Dataset object

property url: str

URL property of the data file, relative to the workspace directory or absolute path if file are stored in place

Returns:

relative or absolute path of the data file

Return type:

str

property fov: list[FOV]

Returns the list of FOV objects associated to the current data

Returns:

the list of associated FOVs

Return type:

list of FOV objects

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Data

Parameters:

no_id – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

class pydetecdiv.domain.FOV.FOV(comments: str = None, key_val: dict = None, **kwargs)

Bases: NamedDSO, BoxedDSO

A business-logic class defining valid operations and attributes of Fields of view (FOV)

delete() → None

Delete the current FOV, first deleting all linked ROIs that would be consequently left orphaned

record(no_id: bool = False) → dict

Returns a record dictionary of the current FOV

Parameters:

no_id (bool) – if True, does not return id_ (useful for transferring from one project to another)

Returns:

record dictionary

Return type:

dict

property info: str

Returns ready-to-print information about FOV

Returns:

FOV information

Return type:

str

property timestamp: float | None

the last time this FOV was modified (ROI was added, drift correction was computed…) :return: the timestamp

property comments: str

comments property of FOV

Returns:

the comments

Return type:

str

property data: list[Data]

Property returning the Data objects associated to this FOV

Returns:

the data associated to this FOV

Return type:

list of Data objects

property roi_list: list[ROI]

Returns the list of ROI objects whose parent if the current FOV

Returns:

the list of associated ROIs

Return type:

list of ROI objects

property initial_roi: ROI

Return the initial ROI, created at the creation of this FOV and representing the full FOV

Returns:

the initial ROI

Return type:

ROI object

image_resource(dataset: str = 'data') → ImageResource

Return the image resource (single multipage file or a series of files) corresponding to the FOV in a specific

dataset

Parameters:

dataset (str) – the dataset name

Returns:

the image resource

Return type:

ImageResource

property size: tuple[int, int]

The size (dimension) of the object obtained from its associated box

Returns:

the dimension of the boxed object

Return type:

a tuple of two int

property bottom_right: tuple[int, int]

The bottom-right corner of the Box in the coordinate system

Returns:

the coordinates of the bottom-right corner

Return type:

a tuple of two int

property top_left: tuple[int, int]

The top-left corner of the Box in the coordinate system

Returns:

the coordinates of the top-left corner

Return type:

a tuple of two int

class pydetecdiv.domain.ROI.ROI(fov: int | FOV = None, key_val: dict[str, Any] = None, **kwargs)

Bases: NamedDSO, BoxedDSO

A business-logic class defining valid operations and attributes of Regions of interest (ROI)

delete() → None

Deletes this ROI if and only if it is not the full-FOV one which should serve to keep track of original data.

property fov: FOV

property returning the FOV object this ROI is a region of

Returns:

the parent FOV object

Return type:

FOV

property bottom_right: tuple[int, int]

The bottom-right corner of the ROI in the FOV

Returns:

the coordinates of the bottom-right corner

Return type:

a tuple of two int

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current ROI

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

class pydetecdiv.domain.ImageResource.ImageResource(dataset: int | Dataset, fov: int | FOV, multi: bool, xdim: int = -1, ydim: int = -1, zdim: int = -1, cdim: int = -1, tdim: int = -1, xyscale: float = 1, tscale: float = 1, zscale: float = 1, xyunit: float = 1e-06, zunit: float = 1e-06, tunit: float = 0.001, key_val: dict = None, **kwargs)

Bases: DomainSpecificObject

A business-logic class defining valid operations and attributes of Image resources

property dataset: Dataset

the dataset corresponding to this image resource

property fov: FOV

the FOV corresponding to this image resource

property data_list: list[Data]

Property returning the Data objects associated to this FOV

Returns:

the data associated to this FOV

Return type:

list of Data objects

property shape: tuple[int, int, int, int, int]

The image resource shape (should habitually be 5D with the following dimensions TCZYX)

property dims: Dimensions

The image resource dimensions with their size

property xdim: int

The image resource X dimension size determined from file

property ydim: int

The image resource Y dimension size determined from file

property tdim: int

The image resource Y dimension size determined from file

property cdim: int

The image resource Y dimension size determined from file

property zdim: int

The image resource Y dimension size determined from file

set_image_shape_from_file() → tuple[int, int]

The image shape determined from first file

property sizeT: int

The number of frames

property sizeC: int

the number of channels :return:

property sizeZ: int

the number of layers :return:

property sizeY: int

the height of the images

property sizeX: int

the width of the images

image_resource_data() → ImageResourceData

Creates a ImageResourceData object with the appropriate sub-class according to the multi parameter :return: the ImageResourceData object :rtype: ImageResourceData (SingleFileImageResource or MultiFileImageResource)

property image_files_5d: ndarray[str] | None

property returning the list of file paths as a 3D array. Each file contains a XY 2D image, and there is one file for each T, C,Z combination of coordinates :return: 3D array of file paths :rtype: array of str

property image_files: list[str]

property returning the list of all files associated with this image resource :return: list of image files :rtype: list of str (file paths)

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Image resource

Parameters:

no_id (bool) – if True, does not return id_ (useful for transferring from one project to another)

Returns:

record dictionary

Return type:

dict

class pydetecdiv.domain.Entity.Entity(roi: int | ROI, category: str = 'cell', exit_frame: int = 9223372036854775807, key_val: dict = None, **kwargs)

Bases: NamedDSO

A class defining an entity that can be segmented, tracked, etc in a time-lapse microscopy video

property roi: ROI

property returning the ROI object this entity belongs to

Returns:

the parent ROI object

property exit_frame: int

Return the exit frame index for this entity

bounding_box(frame: int)

return a the Bounding boxes for this Entity at the requested frame :param frame: the frame or None

bounding_boxes(frame: int = None) → list[Bounding_Box]

return a list of Bounding boxes for this Entity if frame is None, otherwise return the bounding box at the requested frame :param frame: the frame or None

points(frame: int = None) → list[Point]

return a list of points for this Entity :param frame: the frame or None

masks(frame: int = None) → list[Mask]

return a list of masks for this Entity if frame is None, otherwise, returns the mask at the given frame :param frame: the frame or None

mask(frame: int) → Mask

The mask at given frame :param frame: the frame index

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Entity

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict

class pydetecdiv.domain.BoundingBox.BoundingBox(box: QGraphicsRectItem = None, frame: int = None, entity: Entity = None, key_val: dict = None, x: float = 0, y: float = 0, width: int = 0, height: int = 0, **kwargs)

Bases: NamedDSO

A class defining a bounding box with its properties and available methods

property object: Entity

property returning the Entity object this bounding box corresponds to. (this is a legacy method expected to be removed not to be used)

property entity: Entity

property returning the Entity object this bounding box corresponds to

Returns:

the Entity object

property x: float | None

the x coordinate of the bounding box (top-left corner)

property y: float | None

the y coordinate of the bounding box (top-left corner)

property width: int | None

the width of the bounding box

property height: int | None

the height of the bounding box

property coords: list[float]

the coordinates of the bounding box (top-left corner / bottom-right corner)

change_box(box: QGraphicsRectItem) → None

changes the specified bounding box :param box: the new graphics item for the bounding box

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Entity

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict

class pydetecdiv.domain.Point.Point(point: QGraphicsEllipseItem = None, label: int = 1, frame: int = None, entity: Entity = None, x: float = 0, y: float = 0, key_val: dict = None, **kwargs)

Bases: NamedDSO

A class defining a point with its properties and available methods

property object

property returning the Entity object this point corresponds to. (this is a legacy method expected to be removed not to be used)

property entity: Entity

property returning the ROI object this entity belongs to

Returns:

the parent ROI object

change_point(point: QGraphicsEllipseItem) → None

changes the specified bounding box :param box: the new graphics item for the bounding box

property x: float | None

the x coordinate of the point

property y: float | None

the y coordinate of the point

property coords: list[float]

the coordinates of the point

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Entity

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict

class pydetecdiv.domain.Mask.Mask(mask_item: QGraphicsPolygonItem = None, frame: int = None, entity: Entity = None, bin_mask=None, key_val: dict = None, **kwargs)

Bases: NamedDSO

A class defining masks as predicted by SegmentAnything2 from the prompts

property graphics_item: QGraphicsItem

Determines and return the graphics item representing the current mask in the Segmentation Tool scene :return: the graphics item

property bin_mask: ndarray | None

The binary mask, i.e. the masks raw data :return: the bianry mask

property object: Entity

return the corresponding entity (this is a legacy method expected to be removed not to be used)

property entity: Entity

property returning the Entity object this mask corresponds to

Returns:

the Entity object

property contour: ndarray | None

The mask contour as determined according to the specified method

property normalised_contour: ndarray | None

The mask contour as determined according to the specified method and relative to ROI size

property ellipse_contour: ndarray | None

The mask contour as an ellipse approximation

static bitmap2contour(out_mask: ndarray, contour_method: int = 2) → ndarray | None

Returns the contour approximation of the mask using according to the specified method stored in self.contour_method

change_mask(mask: ndarray) → None

changes the specified mask array :param mask: the new array for the mask

set_graphics_item(contour_method: int = 2) → None

Sets the approximation method of contour from the binary mask accordingly and sets the brush :param contour_method: the contour approximation method to use

to_shape() → QGraphicsPolygonItem

Returns a polygon approximation of the original binary mask

property ellipse_item: QGraphicsEllipseItem

return a graphics item to display the mask as an ellipse

setBrush(brush: QBrush = None) → None

Set the brush for all representation of the mask (polygon or ellipse) :param brush: the brush to use with this mask

record(no_id: bool = False) → dict[str, Any]

Returns a record dictionary of the current Entity

Parameters:

no_id (bool) – if True, the id_ is not passed included in the record to allow transfer from one project to another

Returns:

record dictionary

Return type:

dict