ezomero package¶

Submodules¶

ezomero.json_api module¶

Create an OMERO connection using the JSON API

This function will create an OMERO connection by populating certain parameters for a request using the requests library by the procedure described in the notes below. Note that this function may ask for user input, so be cautious if using in the context of a script.

Parameters:

user (str, optional) – OMERO username.
password (str, optional) – OMERO password.
web_host (str, optional) – OMERO.web host.
verify (boolean, optional) – Whether to verify SSL certificates when making requests.
server_name (str, optional) – OMERO server name as configured in your OMERO.web installation. For a “default” OMERO.web installation, it will normally be ‘omero’.
config_path (str, optional) – Path to directory containing ‘.ezomero’ file that stores connection information. If left as None, defaults to the home directory as determined by Python’s pathlib.

Returns:

login_rsp (JSON object) – JSON containing the response to the POST request sent for log in.
session (requests Session object or None) – The effective requests session that will be used for further requests to the JSON API.
base_url (str or None) – Base URL for further requests, retrieved via JSON API request

Notes

The procedure for choosing parameters for initializing a JSON API session is as follows:

Any parameters given to create_json_connection will be used to initialize a JSON session
If a parameter is not given to this function, populate from variables in os.environ:
- OMERO_USER
- OMERO_PASS
- OMERO_WEB_HOST
If environment variables are not set, try to load from a config file. This file should be called ‘.ezomero’. By default, this function will look in the home directory, but config_path can be used to specify a directory in which to look for ‘.ezomero’.

The function ezomero.store_connection_params can be used to create the ‘.ezomero’ file.

Note that passwords can not be loaded from the ‘.ezomero’ file. This is to discourage storing credentials in a file as cleartext.
If any remaining parameters have not been set by the above steps, the user is prompted to enter a value for each unset parameter.

Note that, by default, this function will use the latest API version available, in case multiple versions are offered by the OMERO.web server.

ezomero.json_api.get_rendered_jpeg(session: Session, base_url: str, img_id: int, scale: float | int) → ndarray¶

Get a numpy array from a rendered JPEG at given scale factor of an image.

Parameters:

session (requests Session object) – requests session that has been initialized with login parameters.
base_url (str) – Base URL for further requests, retrieved via JSON API request
img_id (int) – ID of Image.
scale (float or int) – Scaling factor for the returned JPEG. 1 returns original size, 2 scales each dimension down by half, and so on.

Returns:

pixels – Array containing pixel values from rendered JPEG of the OMERO image.

Return type:

ndarray

Examples

# Get a JPEG of an entire image as a numpy array:

>>> jpeg_array = get_rendered_jpeg(session, base_url, 314, 1)

ezomero.rois module¶

Bases: ezShape

A dataclass used to create an OMERO Ellipse.

A dataclass used to represent an Ellipse shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation.

Parameters:

x (float) – The x axis position of the ellipse shape in pixels.
y (float) – The y axis position of the ellipse shape in pixels.
x_rad (float) – The x radius of the ellipse shape in pixels.
y_rad (float) – The y radius of the ellipse shape in pixels.
z (int, optional) – The z position of the shape in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the shape will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the shape will not be linked to any time frame. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

class ezomero.rois.Label(x: float, y: float, label: str, fontSize: int, z: int | None = None, c: int | None = None, t: int | None = None, fill_color: Tuple[int, int, int, int] | None = None, stroke_color: Tuple[int, int, int, int] | None = None, stroke_width: float | None = None)¶

Bases: ezShape

A dataclass used to create an OMERO Label.

A dataclass used to represent a Label shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation

Parameters:

x (float) – The x axis position of the label shape in pixels.
y (float) – The y axis position of the label shape in pixels.
label (str) – The text value of the Label.
fontSize (int) – The font size of the label, in pt.
z (int, optional) – The z position of the label in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Label will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the Label will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the Label will not be linked to any time frame. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

Bases: ezShape

A dataclass used to create an OMERO Line.

A dataclass used to represent a Line shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation.

Parameters:

x1 (float) – The x axis position of the start point of the line shape in pixels.
y1 (float) – The y axis position of the start point of the line shape in pixels.
x2 (float) – The x axis position of the end point of the line shape in pixels.
y2 (float) – The y axis position of the end point of the line shape in pixels.
z (int, optional) – The z position of the shape in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the shape will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the shape will not be linked to any time frame. Default is None.
markerStart (str, optional) – The marker for the start of the line. Default is None.
markerEnd (str, optional) – The marker for the end of the line. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

Bases: ezShape

A dataclass used to create an OMERO Point.

A dataclass used to represent a Point shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation

Parameters:

x (float) – The x axis position of the point shape in pixels.
y (float) – The y axis position of the point shape in pixels.
z (int, optional) – The z position of the point in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the Point will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the Point will not be linked to any time frame. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

Bases: ezShape

A dataclass used to create an OMERO polygon.

A dataclass used to represent a Polygon shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation.

Parameters:

points (list of tuples of 2 floats) – A list of 2 element tuples corresponding to the (x, y) coordinates of each vertex of the polygon.
z (int, optional) – The z position of the shape in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the shape will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the shape will not be linked to any time frame. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

Bases: ezShape

A dataclass used to create an OMERO polyline.

A dataclass used to represent a Polyline shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation.

Parameters:

points (list of tuples of 2 floats) – A list of 2 element tuples corresponding to the (x, y) coordinates of each vertex of the polyline.
z (int, optional) – The z position of the shape in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the shape will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the shape will not be linked to any time frame. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

Bases: ezShape

A dataclass used to create an OMERO rectangle.

A dataclass used to represent a Rectangle shape and create an OMERO equivalent. This dataclass is frozen and should not be modified after instantiation.

Parameters:

x (float) – The x axis position of the rectangle shape in pixels.
y (float) – The y axis position of the rectangle shape in pixels.
width (float) – The width (x axis) of the rectangle shape in pixels.
height (float) – The height (y axis) of the rectangle shape in pixels.
z (int, optional) – The z position of the shape in pixels. Note this is the z plane to which the shape is linked and not the sub-voxel resolution position of your shape. If None, the Point will not be linked to any z plane. Default is None.
c (int, optional) – The channel index to which the shape is linked. If None, the shape will not be linked to any channel. Default is None.
t (int, optional) – The time frame to which the shape is linked. If None, the shape will not be linked to any time frame. Default is None.
label (str, optional) – The label of the shape. Default is None.
fill_color (Tuple (4 integers), optional) – The color that will be used as the fill/background of this Shape. Format is RGBA, 0-255. If None, we default to (0, 0, 0, 0) (i.e. transparent) in ezomero.get_shape(). Default is None.
stroke_color (Tuple (4 integers), optional) – The color that will be used as the stroke/perimeter of this Shape. Format is RGBA, 0-255. If None, we default to (255, 255, 0, 255) (i.e. yellow, following OMERO.iViewer default) in ezomero.get_shape(). Default is None.
stroke_width (float, optional) – The line width used for the stroke/perimeter of this Shape. If None, we default to 1.0 in ezomero.get_shape(). Default is None.

class ezomero.rois.ezShape¶

Bases: object

Generic dataclass used to create an OMERO Shape.

A dataclass used to represent any shape and create an OMERO equivalent. This class has no fields; it’s just extended by all ROIs. This dataclass is frozen and should not be modified after instantiation

Module contents¶

Create an OMERO connection

This function will create an OMERO connection by populating certain parameters for omero.gateway.BlitzGateway initialization by the procedure described in the notes below. Note that this function may ask for user input, so be cautious if using in the context of a script.

Finally, don’t forget to close the connection conn.close() when it is no longer needed!

Parameters:

user (str, optional) – OMERO username.
password (str, optional) – OMERO password.
group (str, optional) – OMERO group.
host (str, optional) – OMERO.server host.
port (int, optional) – OMERO port.
secure (boolean, optional) – Whether to create a secure session.
config_path (str, optional) – Path to directory containing ‘.ezomero’ file that stores connection information. If left as None, defaults to the home directory as determined by Python’s pathlib.

Returns:

conn – OMERO connection, if successful. Otherwise an error is logged and returns None.

Return type:

omero.gateway.BlitzGateway object or None

Notes

The procedure for choosing parameters for omero.gateway.BlitzGateway initialization is as follows:

Any parameters given to ezomero.connect will be used to initialize omero.gateway.BlitzGateway
If a parameter is not given to ezomero.connect, populate from variables in os.environ:
- OMERO_USER
- OMERO_PASS
- OMERO_GROUP
- OMERO_HOST
- OMERO_PORT
- OMERO_SECURE
If environment variables are not set, try to load from a config file. This file should be called ‘.ezomero’. By default, this function will look in the home directory, but config_path can be used to specify a directory in which to look for ‘.ezomero’.

The function ezomero.store_connection_params can be used to create the ‘.ezomero’ file.

Note that passwords can not be loaded from the ‘.ezomero’ file. This is to discourage storing credentials in a file as cleartext.
If any remaining parameters have not been set by the above steps, the user is prompted to enter a value for each unset parameter.

Entry point that creates Importer and runs import.

Parameters:

conn (omero.gateway.BlitzGateway object.) – OMERO connection.
target (string) – Path to the import target to be imported into OMERO.
project (str or int, optional) – The name or ID of the Project data will be imported into.
dataset (str or int, optional) – The name or ID of the Dataset data will be imported into.
screen (str or int, optional) – The name or ID of the Screen data will be imported into.
ann (dict, optional) – Dictionary with key-value pairs to be added to imported images.
ns (str, optional) – Namespace for the added key-value pairs.
*args (str, optional) – You can also add any extra arguments you would like to pass to omero import to the end of the argument list in ezimport. For example, an in-place import can be done by adding transfer="ln_s" as an extra argument when calling ezimport`.
**kwargs (str, optional) – You can also add any extra arguments you would like to pass to omero import to the end of the argument list in ezimport. For example, an in-place import can be done by adding transfer="ln_s" as an extra argument when calling ezimport`.

Returns:

plate_ids or image_ids – The ids of the Images/Plates that were generated by importing the specified target.

Return type:

list of ints

Notes

This function is EXPERIMENTAL and has seen minimal testing. Use at your own risk! We do not recommend using this in production.

ezomero.filter_by_filename(conn: _BlitzGateway, im_ids: List[int], imported_filename: str, across_groups: bool | None = True) → List[int]¶

Filter list of image ids by originalFile name.

Sometimes we know the filename of an image that has been imported into OMERO but not necessarily the image ID. This is frequently the case when we want to annotate a recently imported image. This function will help to filter a list of image IDs to only those associated with a particular filename.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
im_ids (list of int) – List of OMERO image IDs.
imported_filename (str) – The full filename (with extension) of the file whose OMERO image we are looking for. NOT the path of the image.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

filtered_im_ids – Filtered list of images with originalFile name matching imported_filename.

Return type:

list of int

Notes

This function should be used as a filter on an image list that has been already narrowed down as much as possible. Note that many different images in OMERO may share the same filename (e.g., image.tif).

Examples

>>> im_ids = get_image_ids(conn, dataset=303)
>>> im_ids = filter_by_filename(conn, im_ids, "feb_2020.tif")]

ezomero.filter_by_kv(conn: _BlitzGateway, im_ids: List[int], key: str, value: str, across_groups: bool | None = True) → List[int]¶

Filter list of image ids by a key-value pair of a MapAnnotation.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
im_ids (list of int) – List of OMERO image IDs.
key (str) – Key to filter on.
value (str) – Value to filter on.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

filtered_im_ids

Return type:

list of int

ezomero.filter_by_tag_value(conn: _BlitzGateway, im_ids: List[int], tag_value: str, across_groups: bool | None = True) → List[int]¶

Filter list of image ids by textValue of a TagAnnotation.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
im_ids (list of int) – List of OMERO image IDs.
tag_value (str) – Value of tag to filter on.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

filtered_im_ids

Return type:

list of int

ezomero.get_comment_annotation(conn: _BlitzGateway, comment_id: int, across_groups: bool | None = True) → str¶

Get the value of a comment annotation object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
comment_id (int) – ID of comment annotation to get.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

comment – The value of the specified tag annotation object.

Return type:

str

Examples

>>> comment = get_tag(conn, 62)
>>> print(comment)
This is a comment

ezomero.get_comment_annotation_ids(conn: _BlitzGateway, object_type: str, object_id: int, ns: str | None = None, across_groups: bool | None = True) → List[int]¶

Get IDs of comment annotations associated with an object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObject
object_id (int) – ID of object of object_type.
ns (str, optional) – Namespace with which to filter results
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

comment_ids

Return type:

list of ints

Examples

# Return IDs of all comments linked to an image:

>>> comment_ids = get_comment_ids(conn, 'Image', 42)

# Return IDs of comments with namespace “test” linked to a Dataset:

>>> tag_ids = get_tag_ids(conn, 'Dataset', 16, ns='test')

ezomero.get_dataset_ids(conn: _BlitzGateway, project: int | None = None, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list of dataset ids based on project ID.

If no project or annotation is specified, function will return orphan datasets.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
project (int, optional) – ID of Project from which to return dataset IDs. This will return IDs of all datasets contained in the specified Project.
annotation (int, optional) – ID of Annotation from which to return dataset IDs. This will return IDs of all datasets linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

ds_ids – List of dataset IDs contained in the specified project.

Return type:

list of ints

Examples

# Return orphaned datasets:

>>> orphans = get_dataset_ids(conn)

# Return IDs of all datasets from Project with ID 224:

>>> ds_ids = get_dataset_ids(conn, project=224)

ezomero.get_file_annotation(conn: _BlitzGateway, file_ann_id: int, folder_path: str | None = None, across_groups: bool | None = True) → str¶

Get the value of a file annotation object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
file_ann_id (int) – ID of file annotation to get.
folder_path (str) – Path where file annotation will be saved. Defaults to local script directory.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

file_path – The path to the created file.

Return type:

str

Examples

>>> attch_path = get_file_annotation(conn,
...                                  62,
...                                  folder_path='/home/user/Downloads')
>>> print(attch_path)
'/home/user/Downloads/attachment.txt'

ezomero.get_file_annotation_ids(conn: _BlitzGateway, object_type: str, object_id: int, ns: str | None = None, across_groups: bool | None = True) → List[int]¶

Get IDs of file annotations associated with an object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObject
object_id (int) – ID of object of object_type.
ns (str, optional) – Namespace with which to filter results
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

file_ann_ids

Return type:

list of ints

Examples

# Return IDs of all file annotations linked to an image:

>>> file_ann_ids = get_file_annotation_ids(conn, 'Image', 42)

# Return IDs of file annotations with namespace “test” linked to a Dataset:

>>> file_ann_ids = get_file_annotation_ids(conn, 'Dataset', 16, ns='test')

ezomero.get_group_id(conn: _BlitzGateway, group_name: str) → int | None¶

Get ID of a group based on group name.

Must be an exact match. Case sensitive.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
group_name (str) – Name of the group for which an ID is to be returned.

Returns:

group_id – ID of the OMERO group. Returns None if group cannot be found.

Return type:

int

Examples

>>> get_group_id(conn, "Research IT")
304

Get omero image object along with pixels as a numpy array.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image_id (int) – Id of the image to get.
no_pixels (bool, optional) – If true, no pixel data is returned, only the OMERO image object. Default is False.
start_coords (list or tuple of int, optional) – Starting coordinates for each axis for the pixel region to be returned if no_pixels is False (assumes XYZCT ordering). If None, the zero coordinate is used for each axis. Default is None.
axis_lengths (list or tuple of int, optional) – Lengths for each axis for the pixel region to be returned if no_pixels is False. If None, the lengths will be set such that the entire possible range of pixels is returned. Default is None.
xyzct (bool, optional) – Option to return array with dimensional ordering XYZCT. If False, the skimage preferred ordering will be used (TZYXC). Default is False.
pad (bool, optional) – If axis_lengths values would result in out-of-bounds indices, pad pixel array with zeros. Otherwise, such an operation will raise an exception. Ignored if no_pixels is True.
pyramid_level (int, optional) – If image has multiple pyramid levels and this argument is set, pixels are returned at the chosen resolution level, and all other arguments apply to that level as well. We follow the usual convention of 0 as full-resolution.
dim_order (str, optional) – String containing the letters ‘x’, ‘y’, ‘z’, ‘c’ and ‘t’ in some order, specifying the order of dimensions to be returned by the function. If specified, ignores the value of the ‘xyzct’ variable.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

image (omero.gateway.ImageWrapper object) – OMERO image object.
pixels (ndarray) – Array containing pixel values from OMERO image. Can be a subregion of the image if start_coords and axis_lengths are specified.

Notes

Regardless of whether xyzct is True or dim_order is set, the numpy array is created as TZYXC, for performance reasons. If xyzct is True or dim_order is set, the returned pixels array is actually a view of the original TZYXC array.

Examples

# Get an entire image as a numpy array:

>>> im_object, im_array = get_image(conn, 314)

# Get a subregion of an image as a numpy array:

>>> im_o, im_a = get_image(conn, 314, start_coords=(40, 50, 4, 0, 0),
...                        axis_lengths=(256, 256, 12, 10, 10))

# Get only the OMERO image object, no pixels:

>>> im_object, _ = get_image(conn, 314, no_pixels=True)
>>> im_object.getId()
314

Return a list of image ids based on image container

If no container is specified, function will return orphans.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
project (int, optional) – ID of Project from which to return image IDs. This will return IDs of all images contained in all child Datasets of the specified Project.
dataset (int, optional) – ID of Dataset from which to return image IDs.
plate (int, optional) – ID of Plate from which to return image IDs. This will return IDs of all images contained in all Wells belonging to the specified Plate.
well (int, optional) – ID of Well from which to return image IDs.
plate_acquisition (int, optional) – ID of Plate acquisition from which to return image IDs.
annotation (int, optional) – ID of Annotation from which to return image IDs. This will return IDs of all images linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

im_ids – List of image IDs contained in the specified container.

Return type:

list of ints

Notes

User and group information comes from the conn object. Be sure to use ezomero.set_group to specify group prior to passing the conn object to this function.

Only one of Project, Dataset, Plate, Well, Plate acquisition or Annotation can be specified. If none of those are specified, orphaned images are returned.

Examples

# Return orphaned images:

>>> orphans = get_image_ids(conn)

# Return IDs of all images from Dataset with ID 448:

>>> ds_ims = get_image_ids(conn, dataset=448)

# Return IDs of all images annotated with Tag ID 876:

>>> tag_ims = get_image_ids(conn, annotation=876)

ezomero.get_map_annotation(conn: _BlitzGateway, map_ann_id: int, across_groups: bool | None = True) → dict¶

Get the value of a map annotation object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
map_ann_id (int) – ID of map annotation to get.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

kv_dict – The value of the specified map annotation object, as a Python dict. If kv-pairs with the same key exist, the corresponding dict value will be a list.

Return type:

dict

Examples

>>> ma_dict = get_map_annotation(conn, 62)
>>> print(ma_dict)
{'testkey': 'testvalue', 'testkey2': ['testvalue2'. 'testvalue3']}

ezomero.get_map_annotation_ids(conn: _BlitzGateway, object_type: str, object_id: int, ns: str | None = None, across_groups: bool | None = True) → List[int]¶

Get IDs of map annotations associated with an object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObject
object_id (int) – ID of object of object_type.
ns (str, optional) – Namespace with which to filter results
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

map_ann_ids

Return type:

list of ints

Examples

# Return IDs of all map annotations belonging to an image:

>>> map_ann_ids = get_map_annotation_ids(conn, 'Image', 42)

# Return IDs of map annotations with namespace “test” linked to a Dataset:

>>> map_ann_ids = get_map_annotation_ids(conn, 'Dataset', 16, ns='test')

ezomero.get_original_filepaths(conn: _BlitzGateway, image_id: int, fpath: Literal['fpath', 'repo'] | None = 'repo', across_groups: bool | None = True) → List[str]¶

Get paths to original files for specified image.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image_id (int) – ID of image for which filepath info is to be returned.
fpath ({'repo', 'client'}, optional) – Specify whether you want to return path to file in the managed repository (‘repo’) or the path from which the image was imported (‘client’). The latter is useful for images that were imported by the “in place” method. Defaults to ‘repo’.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Notes

The ManagedRepository (‘repo’) paths are relative, whereas the client paths are absolute.

The client path may not be accessible if the image was not imported using “in place” imports (e.g., transfer=ln_s).

Returns:: original_filepaths
Return type:: list of str

Examples

# Return (relative) path of file in ManagedRepository:

>>> get_original_filepaths(conn, 745)
['djme_2/2020-06/16/13-38-36.468/PJN17_083_07.ndpi']

# Return client path (location of file when it was imported):

>>> get_original_filepaths(conn, 2201, fpath='client')
['/client/omero/smith_lab/stack2/PJN17_083_07.ndpi']

ezomero.get_plate_acquisition_ids(conn: _BlitzGateway, screen: int | None = None, plate: int | None = None, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list of plate acquisition ids based on a container

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
screen (int, optional) – ID of Screen from which to return plate acquisition IDs. This will return IDs of all plate acquisitions contained in the specified Screen.
plate (int, optional) – ID of Plate from which to return plate acquisition IDs. This will return IDs of all plate acquisitions belonging to the specified Plate.
annotation (int, optional) – ID of Annotation from which to return run IDs. This will return IDs of all runs linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

plate_acquisition_ids – List of plate acquisitions IDs contained in the specified container.

Return type:

list of ints

Examples

# Return IDs of all plate acquisitions from Screen with ID 224:

>>> plate_acquisition_ids = get_plate_acquisition_ids(conn, screen=224)

ezomero.get_plate_ids(conn: _BlitzGateway, screen: int | None = None, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list of plate ids based on screen ID.

If no screen is specified, function will return orphan plates.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
screen (int, optional) – ID of Screen from which to return plate IDs. This will return IDs of all plates contained in the specified Screen.
annotation (int, optional) – ID of Annotation from which to return plate IDs. This will return IDs of all plates linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

pl_ids – List of plates IDs contained in the specified screen.

Return type:

list of ints

Examples

# Return orphaned plates:

>>> orphans = get_plate_ids(conn)

# Return IDs of all plates from Screen with ID 224:

>>> pl_ids = get_plate_ids(conn, screen=224)

ezomero.get_project_ids(conn: _BlitzGateway, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list with IDs for all available Projects.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
annotation (int, optional) – ID of Annotation from which to return project IDs. This will return IDs of all projects linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

proj_ids – List of project IDs accessible by current user.

Return type:

list of ints

Examples

# Return IDs of all projects accessible by current user:

>>> proj_ids = get_project_ids(conn)

# Return IDs of all projects annotated with tag id 576:

>>> proj_ids = get_project_ids(conn, annotation=576)

ezomero.get_pyramid_levels(conn: _BlitzGateway, image_id: int, across_groups: bool | None = True) → List[Tuple[int, ...]]¶

Get number of pyramid levels associated with an Image

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image_id (int) – ID of Image.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

levels – Pyramidal levels available for this image, with number of pixels for X and Y axes.

Return type:

list of tuples

Examples

# Return pyramid levels associated to an image:

>>> lvls = get_pyramid_levels(conn, 42)
[(2048, 1600), (1024, 800), (512, 400), (256, 200)]

ezomero.get_roi_ids(conn: _BlitzGateway, image_id: int, across_groups: bool | None = True) → List[int]¶

Get IDs of ROIs associated with an Image

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image_id (int) – ID of Image.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

roi_ids

Return type:

list of ints

Examples

# Return IDs of all ROIs linked to an image:

>>> roi_ids = get_roi_ids(conn, 42)

ezomero.get_screen_ids(conn: _BlitzGateway, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list with IDs for all available Screens.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
annotation (int, optional) – ID of Annotation from which to return screen IDs. This will return IDs of all screens linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

scrn_ids – List of screen IDs accessible by current user.

Return type:

list of ints

Examples

# Return IDs of all screens accessible by current user:

>>> scrn_ids = get_screen_ids(conn)

# Return IDs of all screens annotated with tag id 913:

>>> proj_ids = get_screen_ids(conn, annotation=913)

ezomero.get_shape(conn: _BlitzGateway, shape_id: int, across_groups: bool | None = True) → ezShape¶

Get an ezomero shape object from an OMERO Shape id

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
shape_id (int) – ID of shape to get.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

shape – An object of one of ezomero shape classes

Return type:

obj

Notes

fill_color for the Shape defaults to (0, 0, 0, 0) in case the original Shape doesn’t have one. stroke_color for the Shape defaults to (255, 255, 0, 255) in case the original Shape doesn’t have one. stroke_width for the Shape defaults to 1 in case the original Shape doesn’t have one.

Examples

>>> shape = get_shape(conn, 634443)

ezomero.get_shape_ids(conn: _BlitzGateway, roi_id: int, across_groups: bool | None = True) → List[int] | None¶

Get IDs of shapes associated with an ROI

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
roi_id (int) – ID of ROI.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

shape_ids

Return type:

list of ints

Examples

# Return IDs of all shapes linked to an ROI:

>>> shape_ids = get_shape_ids(conn, 4222)

ezomero.get_table(conn: _BlitzGateway, file_ann_id: int, across_groups: bool | None = True) → Any¶

Get a table from its FileAnnotation object.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
file_ann_id (int) – ID of FileAnnotation table to get.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

table – Object containing the actual table. It can be either a list of row-lists or a pandas Dataframe in case the optional pandas dependency was installed.

Return type:

object

Examples

>>> table = get_table(conn, 62)
>>> print(table[0])
['ID', 'X', 'Y']

ezomero.get_tag(conn: _BlitzGateway, tag_id: int, across_groups: bool | None = True) → str¶

Get the value of a tag annotation object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
tag_id (int) – ID of tag annotation to get.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

tag – The value of the specified tag annotation object.

Return type:

str

Examples

>>> tag = get_tag(conn, 62)
>>> print(tag)
This_is_a_tag

ezomero.get_tag_ids(conn: _BlitzGateway, object_type: str, object_id: int, ns: str | None = None, across_groups: bool | None = True) → List[int]¶

Get IDs of tag annotations associated with an object

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObject
object_id (int) – ID of object of object_type.
ns (str, optional) – Namespace with which to filter results
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

tag_ids

Return type:

list of ints

Examples

# Return IDs of all tags linked to an image:

>>> tag_ids = get_tag_ids(conn, 'Image', 42)

# Return IDs of tags with namespace “test” linked to a Dataset:

>>> tag_ids = get_tag_ids(conn, 'Dataset', 16, ns='test')

ezomero.get_user_id(conn: _BlitzGateway, user_name: str) → int | None¶

Get ID of a user based on user name.

Must be an exact match. Case sensitive.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
user_name (str) – Name of the user for which an ID is to be returned.

Returns:

user_id – ID of the OMERO user. Returns None if group cannot be found.

Return type:

int

Examples

>>> get_user_id(conn, "jaxl")
35

ezomero.get_well_id(conn: _BlitzGateway, plate_id: int, row: int, column: int, across_groups: bool | None = True) → int | None¶

Get ID of well based on plate ID, row, and column

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
plate_id (int) – ID of plate for which the well ID is needed
row (int) – Row of well (zero-based indexing)
column (int) – Column of well (zero-based indexing)

Returns:

well_id – ID of well being queried.

Return type:

int

ezomero.get_well_ids(conn: _BlitzGateway, screen: int | None = None, plate: int | None = None, annotation: int | None = None, across_groups: bool | None = True) → List[int]¶

Return a list of well ids based on a container

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
screen (int, optional) – ID of Screen from which to return well IDs. This will return IDs of all wells contained in the specified Screen.
plate (int, optional) – ID of Plate from which to return well IDs. This will return IDs of all wells belonging to the specified Plate.
annotation (int, optional) – ID of Annotation from which to return well IDs. This will return IDs of all wells linked to the specified annotation.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

wl_ids – List of wells IDs contained in the specified container.

Return type:

list of ints

Examples

# Return IDs of all wells from Screen with ID 224:

>>> wl_ids = get_well_ids(conn, screen=224)

ezomero.link_datasets_to_project(conn: _BlitzGateway, dataset_ids: List[int], project_id: int)¶

Link datasets to the specified project.

Nothing is returned by this function.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
dataset_ids (list of int) – List of OMERO Dataset Ids.
project_id (int) – Id of Project to which Datasets will be linked.

ezomero.link_images_to_dataset(conn: _BlitzGateway, image_ids: List[int], dataset_id: int)¶

Link images to the specified dataset.

Nothing is returned by this function.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
im_ids (list of int) – List of OMERO image IDs.
dataset_id (int) – Id of dataset to which images will be linked.

ezomero.link_plates_to_screen(conn: _BlitzGateway, plate_ids: List[int], screen_id: int)¶

Link plates to the specified screen.

Nothing is returned by this function.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
plate_ids (list of int) – List of OMERO Plate Ids.
screen_id (int) – Id of Screen to which Plate will be linked.

ezomero.post_comment_annotation(conn: _BlitzGateway, object_type: str, object_id: int, comment: str, ns: str | None = None, across_groups: bool | None = True) → int | None¶

Create new MapAnnotation and link to an object.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObjects
object_id (int) – ID of object to which the new CommentAnnotation will be linked.
comment (str) – string that will be passed as the CommentAnnotation value
ns (str, optional) – Namespace for the CommentAnnotation
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

comment_ann_id – IDs of newly created CommentAnnotation

Return type:

int

Examples

>>> ns = 'jax.org/jax/example/namespace'
>>> d = {'species': 'human',
...      'occupation': 'time traveler'
...      'first name': 'Kyle',
...      'surname': 'Reese'}
>>> post_map_annotation(conn, "Image", 56, d, ns)
234

ezomero.post_dataset(conn: _BlitzGateway, dataset_name: str, project_id: int | None = None, description: str | None = None, across_groups: bool | None = True) → int | None¶

Create a new dataset.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
dataset_name (str) – Name of the Dataset being created.
project_id (int, optional) – Id of Project in which to create the Dataset. If no Project is specified, the Dataset will be orphaned.
description (str, optional) – Description for the new Dataset.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

dataset_id – Id of the dataset that has been created.

Return type:

int

Examples

# Create a new orphaned Dataset:

>>> did = post_dataset(conn, "New Dataset")
>>> did
234

# Create a new Dataset in Project:120:

>>> did = post_dataset(conn, "Child of 120", project_id=120)
>>> did

Create new FileAnnotation and link to images.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
file_path (string) – local path to file to be added as FileAnnotation
ns (str) – Namespace for the FileAnnotation
object_type (str, optional) – OMERO object type, passed to BlitzGateway.getObject
object_id (int, optional) – ID of object to which the new FileAnnotation will be linked.
mimetype (str, optional) – String of the form ‘type/subtype’, usable for a MIME content-type header.
description (str, optional) – File description to be added to FileAnnotation
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Notes

All keys and values are converted to strings before saving in OMERO.

Returns:: file_ann_id – IDs of newly created FileAnnotation
Return type:: int

Examples

>>> ns = 'jax.org/jax/example/namespace'
>>> path = '/home/user/Downloads/file_ann.txt'
>>> post_file_annotation(conn, path, ns, "Image", 56)
234

Create a new OMERO image from numpy array.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image (numpy.ndarray) – The numpy array from which a new OMERO image will be created. Note that array.ndim must equal 5. The function assumes this ndarray uses XYZCT ordering.
image_name (str) – Name of the new image to be created.
description (str, optional) – Description for the new image.
dataset_id (int, optional) – Id of the Dataset in which to create the image. If no Dataset is specified, an orphaned image will be created.
source_image_id (int, optional) – If specified, copy this image with metadata, then add pixel data from image parameter.
channel_list (list of ints) – Copies metadata from these channels in source image (if specified).
dim_order (str, optional) – String containing the letters ‘x’, ‘y’, ‘z’, ‘c’ and ‘t’ in some order, specifying the order of dimensions the image array was supplied on.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Returns:

image_id – Id of the new image that has been created.

Return type:

int

Examples

>>> test_image = np.zeros((200, 200, 20, 3, 1), dtype=np.uint8)
>>> im_id = post_image(conn, test_image, "test", dataset_id=105)
>>> print(im_id)
234

ezomero.post_map_annotation(conn: _BlitzGateway, object_type: str, object_id: int, kv_dict: dict, ns: str, across_groups: bool | None = True) → int | None¶

Create new MapAnnotation and link to an object.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObjects
object_id (int) – ID of object to which the new MapAnnotation will be linked.
kv_dict (dict) – key-value pairs that will be included in the MapAnnotation
ns (str) – Namespace for the MapAnnotation
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Notes

All keys and values are converted to strings before saving in OMERO. Passing a list of values will result in multiple instances of the key, one for each value.

Returns:: map_ann_id – IDs of newly created MapAnnotation
Return type:: int

Examples

>>> ns = 'jax.org/jax/example/namespace'
>>> d = {'species': 'human',
...      'occupation': ['time traveler', 'soldier'].
...      'first name': 'Kyle',
...      'surname': 'Reese'}
>>> post_map_annotation(conn, "Image", 56, d, ns)
234

ezomero.post_project(conn: _BlitzGateway, project_name: str, description: str | None = None) → int¶

Create a new project.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
project_name (str) – Name of the new object to be created.
description (str, optional) – Description for the new Project.

Returns:

project_id – Id of the new Project.

Return type:

int

Notes

Project will be created in the Group specified in the connection. Group can be changed using conn.SERVICE_OPTS.setOmeroGroup.

Examples

>>> project_id = post_project(conn, "My New Project")
>>> print(project_id)
238

Create new ROI from a list of shapes and link to an image.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
image_id (int) – IDs of the image to which the new ROI will be linked.
shapes (list of shapes) – List of shape objects associated with the new ROI.
name (str, optional) – Name for the new ROI.
description (str, optional) – Description of the new ROI.

Returns:

ROI_id – ID of newly created ROI

Return type:

int

Examples

>>> shapes = list()
>>> point = Point(x=30.6, y=80.4)
>>> shapes.append(point)
>>> rectangle = Rectangle(x=50.0,
                          y=51.3,
                          width=90,
                          height=40,
                          z=3,
                          label='The place',
                          fill_color=(255, 10, 10, 150),
                          stroke_color=(255, 0, 0, 0),
                          stroke_width=2)
>>> shapes.append(rectangle)
>>> post_roi(conn, 23, shapes, name='My Cell',
             description='Very important')
234

ezomero.post_screen(conn: _BlitzGateway, screen_name: str, description: str | None = None) → int¶

Create a new screen.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
screen_name (str) – Name of the new object to be created.
description (str, optional) – Description for the new Screen.

Returns:

screen_id – Id of the new Screen.

Return type:

int

Notes

Screen will be created in the Group specified in the connection. Group can be changed using conn.SERVICE_OPTS.setOmeroGroup.

Examples

>>> screen_id = post_screen(conn, "My New Screen")
>>> print(screen_id)
238

ezomero.post_table(conn: _BlitzGateway, table: Any, object_type: str, object_id: int, title: str | None = '', headers: bool = True) → int | None¶

Create new table and link it to an OMERO object.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
object_type (str) – OMERO object type, passed to BlitzGateway.getObjects
object_id (int) – ID of object to which the new Table will be linked.
table (object) – Object containing the actual table. It can be either a list of row-lists or a pandas Dataframe in case the optional pandas dependency was installed. Note that each column should be of a single type; mixed-type columns will be ignored. Types supported: int, string, float, boolean.
title (str, optional) – Title for the table. If none is specified, a Table:ID name is picked, with a random UUID. Note that table names need to be unique!
headers (bool, optional) – Whether the first line of the table object should be interpreted as column headers or not. Defaults to True and is ignored for pandas Dataframes.

Returns:

TableFile_id – ID of newly created FileAnnotation containing the new Table.

Return type:

int

Notes

Currently not working with across_groups - the OriginalFile seems to ignore setting groups dynamically and always does it on the original connection group, causing issues.

Examples

>>> columns = ['ID', 'X', 'Y']
>>> table = [columns, [1, 10, 20], [2, 30, 40]]
>>> post_table(conn, table, "Image", 99, title='My Table', headers=True)
234

ezomero.print_datasets(conn: _BlitzGateway, project: int | None = None)¶

Print all available Datasets for a given Project.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
project (int or None, optional) – ID of Project for which to list datasets. If project is None, orphans are listed.

ezomero.print_groups(conn: _BlitzGateway)¶

Print all Groups with IDs and membership info.

Parameters:: conn (omero.gateway.BlitzGateway object) – OMERO connection.

ezomero.print_map_annotation(conn: _BlitzGateway, map_ann_id: int)¶

Print some information and value of a map annotation.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
map_ann_id (int) – Id of the MapAnnotation to be displayed.

ezomero.print_projects(conn: _BlitzGateway)¶

Print all available Projects.

Parameters:: conn (omero.gateway.BlitzGateway object) – OMERO connection.

ezomero.put_description(conn: _BlitzGateway, obj_type: str, obj_id: int, desc: str, across_groups: bool = True) → None¶

Update an existing object description with a new value (string)

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
obj_type (str) – The OMERO object type to have its description changed. Valid object types are ‘Image’, ‘Dataset’, ‘Project’, ‘FileAnnotation’, ‘CommentAnnotation’, ‘MapAnnotation’, ‘TagAnnotation’, ‘Plate’, ‘Screen’ and ‘Roi’.
obj_id (int) – ID of the object whose description will be replaced.
desc (str) – New description for the object.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Return type:

Returns None.

Examples

# Change an image description:

>>> new_desc = "This is a new description"
>>> put_description(conn, 'Image', 15, new_desc)

# Change a TagAnnotation description:

>>> put_description(conn, 'TagAnnotation', 16, 'new tag description')

ezomero.put_map_annotation(conn: _BlitzGateway, map_ann_id: int, kv_dict: dict, ns: str | None = None, across_groups: bool = True) → None¶

Update an existing map annotation with new values (kv pairs)

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
map_ann_id (int) – ID of map annotation whose values (kv pairs) will be replaced.
kv_dict (dict) – New values (kv pairs) for the MapAnnotation.
ns (str) – New namespace for the MapAnnotation. If left as None, the old namespace will be used.
across_groups (bool, optional) – Defines cross-group behavior of function - set to False to disable it.

Notes

All keys and values are converted to strings before saving in OMERO.

Return type:: Returns None.

Examples

# Change only the values of an existing map annotation:

>>> new_values = {'key1': 'value1', 'key2': ['value2', 'value3']}
>>> put_map_annotation(conn, 15, new_values)

# Change both the values and namespace of an existing map annotation:

>>> put_map_annotation(conn, 16, new_values, 'test_v2')

ezomero.set_group(conn: _BlitzGateway, group_id: int) → bool¶

Safely switch OMERO group.

This function will change the user’s current group to that specified by group_id, but only if the user is a member of that group. This is a “safer” way to do this than conn.SERVICE_OPTS.setOmeroGroup, which will allow switching to a group that a user does not have permissions, which can lead to server-side errors.

Parameters:

conn (omero.gateway.BlitzGateway object) – OMERO connection.
group_id (int) – The id of the group to switch to.

Returns:

change_status – Returns True if group is changed, otherwise returns False.

Return type:

bool

Save OMERO connection parameters in a file.

This function creates a config file (‘.ezomero’) in which certain OMERO parameters are stored, to make it easier to create omero.gateway.BlitzGateway objects.

Parameters:

user (str, optional) – OMERO username.
group (str, optional) – OMERO group.
host (str, optional) – OMERO.server host.
port (int, optional) – OMERO port.
secure (boolean, optional) – Whether to create a secure session.
web_host (boolean/str, optional) – Whether to save a web host address got JSON connections as well. If False, will skip it; it True, will prompt user for it; if it is a str, will save that value to OMERO_WEB_HOST.
config_path (str, optional) – Path to directory that will contain the ‘.ezomero’ file. If left as None, defaults to the home directory as determined by Python’s pathlib.

ezomero package¶

Submodules¶

ezomero.json_api module¶

ezomero.rois module¶

Module contents¶

ezomero

Navigation

Related Topics