ome_types

OME

Bases: OMEMixin, OMEType

The OME element is a container for all information objects accessible by OME.

These information objects include descriptions of the imaging experiments and the people who perform them, descriptions of the microscope, the resulting images and how they were acquired, the analyses performed on those images, and the analysis results themselves. An OME file may contain any or all of this information. With the creation of the Metadata Only Companion OME-XML and Binary Only OME-TIFF files the top level OME node has changed slightly. It can EITHER: Contain all the previously expected elements OR: Contain a single BinaryOnly element that points at its Metadata Only Companion OME-XML file.

Attributes:

Name	Type	Description
rights	None | Rights	(The OME Rights).
projects	list[Project]	(The OME Projects).
datasets	list[Dataset]	(The OME Datasets).
folders	list[Folder]	(The OME Folders).
experiments	list[Experiment]	(The OME Experiments).
plates	list[Plate]	(The OME Plates).
screens	list[Screen]	(The OME Screens).
experimenters	list[Experimenter]	(The OME Experimenters).
experimenter_groups	list[ExperimenterGroup]	(The OME ExperimenterGroups).
instruments	list[Instrument]	(The OME Instruments).
images	list[Image]	(The OME Images).
structured_annotations	None | StructuredAnnotations	(The OME StructuredAnnotations).
rois	list[ROI]	(The OME ROIs).
binary_only	None | BinaryOnly	Pointer to an external metadata file. If this element is present, then no other metadata may be present in this file, i.e. this file is a place- holder.
uuid	None | str	This unique identifier is used to keep track of multi part files. It allows the links between files to survive renaming. While OPTIONAL in the general case this is REQUIRED in a MetadataOnly Companion to a collection of BinaryOnly files.
creator	None | str	This is the name of the creating application of the OME-XML and preferably its full version. e.g "CompanyName, SoftwareName, V2.6.3456" This is optional but we hope it will be set by applications writing out OME-XML from scratch.

BinaryOnly

Bases: OMEType

Attributes:

Name	Type	Description
metadata_file	str	Filename of the OME-XML metadata file for this binary data. If the file cannot be found, a search can be performed based on the UUID.
uuid	str	The unique identifier of another OME-XML block whose metadata describes the binary data in this file. This UUID is considered authoritative regardless of mismatches in the filename.

from_tiff(path: Path | str | BinaryIO, *, validate: bool | None = None, parser_kwargs: ParserKwargs | None = None) -> OME

Generate an OME object from a TIFF file.

Parameters:

Name	Type	Description	Default
path	Path | str | BinaryIO	Path to a TIFF file or a file-like object.	required
validate	bool | None	Whether to validate the XML document against the OME schema before parsing. If None, validation will be skipped if lxml is not available, and will be performed otherwise.	None
parser_kwargs	ParserKwargs | None	Passed to the XmlParser constructor. If None, a default parser will be used.	None

from_xml(source: XMLSource, *, validate: bool | None = None, parser: Any = None, parser_kwargs: ParserKwargs | None = None, transformations: Iterable[TransformationCallable] = (), warn_on_schema_update: bool = False) -> OME

Generate an OME object from an XML document.

NOTE: Technically, this can return any ome-types instance, (not just OME) but it's by far the most common type that will come out of this function, and the type annotation will be more useful to most users. For those who pass in an xml document that isn't just a root tag, they can cast the result to the correct type themselves.

Parameters:

Name	Type	Description	Default
source	(Path | str | bytes | BytesIO)	Path to an XML file, string or bytes containing XML, or a file-like object. If the source is not OME-2016-06 XML, it will be transformed to that namespace if possible.	required
validate	bool | None	Whether to validate the XML document against the OME schema. If None, validation will be skipped if lxml is not available, and will be performed otherwise.	None
parser	Any	Ignored, but kept for backwards compatibility.	None
parser_kwargs	ParserKwargs | None	Passed to the XmlParser constructor. If None, a default parser will be used.	None
transformations	Iterable[TransformationCallable]	A sequence of functions that take an ElementTree and return an ElementTree. These will be applied sequentially to the XML document before parsing. Can be used to apply custom transformations or fixes to the XML document before parsing.	()
warn_on_schema_update	bool	Whether to warn if a transformation was applied to bring the document to OME-2016-06.	False

Returns:

Type	Description
OME	The OME object parsed from the XML document. (See NOTE above.)

to_dict(source: OME | XMLSource) -> dict[str, Any]

Return a dictionary representation of an OME or XML document.

Parameters:

Name	Type	Description	Default
source	OME | Path | str | bytes | BytesIO	An OME object, or a path to an XML file, or a string or bytes containing XML.	required

Returns:

Type	Description
dict[str, Any]	A dictionary representation of the OME object or XML document.

to_xml(obj: OMEType, *, exclude_defaults: bool = False, exclude_unset: bool = True, indent: int = 2, include_namespace: bool | None = None, include_schema_location: bool = True, canonicalize: bool = False, validate: bool = False) -> str

Generate an XML document from an OME object.

Parameters:

Name	Type	Description	Default
obj	OMEType	Instance of an ome-types model class.	required
exclude_defaults	bool	Whether to exclude attributes that are set to their default value, by default False.	False
exclude_unset	bool	Whether to exclude attributes that are not explicitly set, by default True.	True
indent	int	Number of spaces to indent the XML document, by default 2.	2
include_namespace	bool | None	Whether to include the OME namespace in the root element. If None, will be set to the value of canonicalize, by default None.	None
include_schema_location	bool	Whether to include the schema location in the root element, by default True.	True
canonicalize	bool	Whether to canonicalize the XML output, by default False.	False
validate	bool	Whether to validate the XML document against the OME schema, after rendering. (In most cases, this will be redundant and unnecessary.)	False

Returns:

Type	Description
str	The XML document as a string.

validate_xml(xml: XMLSource, schema: Path | str | None = None, *, warn_on_schema_update: bool = True) -> AnyElementTree

Validate XML against an XML Schema.

By default, will validate against the OME 2016-06 schema.