# ome-types
[](LICENSE)
[](https://pypi.python.org/pypi/ome-types)
[](https://anaconda.org/conda-forge/ome-types)
[](https://python.org)
[](https://github.com/tlambert03/ome-types/actions)
[](https://ome-types.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/tlambert03/ome-types)
[](https://codspeed.io/tlambert03/ome-types)
## A pure-python implementation of the OME data model
`ome_types` provides a set of python dataclasses and utility functions for
parsing the [OME-XML
format](https://docs.openmicroscopy.org/ome-model/latest/ome-xml/) into
fully-typed python objects for interactive or programmatic access in python. It
can also take these python objects and output them into valid OME-XML.
`ome_types` is a **pure python** library and does not require a Java virtual
machine.
> Note: The generated python code can be seen in the [`built`
> branch](https://github.com/tlambert03/ome-types/tree/built).
> (Read the [code generation](#code-generation) section for details).
### 📖 [documentation](https://ome-types.readthedocs.io/)
## Installation
### from pip
```shell
pip install ome-types
```
With all optional dependencies:
```shell
# lxml => if you ...
# - want to use lxml as the XML parser
# - want to validate XML against the ome.xsd schema
# - want to use XML documents older than the 2016-06 schema
# pint => if you want to use object.<field>_quantity properties
# xmlschema => if you want to validate XML but DON'T want lxml
pip install ome-types[lxml,pint]
```
### from conda
```shell
conda install -c conda-forge ome-types
```
### from github (bleeding edge dev version)
```shell
pip install git+https://github.com/tlambert03/ome-types.git
```
## Usage
### convert an XML string or filepath into an instance of `ome_types.model.OME`
(The XML string/file will be validated against the [ome.xsd
schema](https://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome.html))
```python
from ome_types import from_xml
ome = from_xml('tests/data/hcs.ome.xml')
```
### extract OME metadata from an OME-TIFF
```python
from ome_types import from_tiff
ome2 = from_tiff('tests/data/ome.tiff')
```
### manipulate the metadata via python objects
Both `from_xml` and `from_tiff` return an instance of `ome_types.model.OME`. All
classes in `ome_types.model` follow the naming conventions of the [OME data
model](https://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome.html),
but use `snake_case` attribute names instead of `CamelCase`, to be consistent
with the python ecosystem.
```python
In [2]: ome = from_xml('tests/data/hcs.ome.xml')
In [3]: ome
Out[3]:
OME(
images=[<1 Images>],
plates=[<1 Plates>],
)
In [4]: ome.plates[0]
Out[4]:
Plate(
id='Plate:1',
name='Control Plate',
column_naming_convention='letter',
columns=12,
row_naming_convention='number',
rows=8,
wells=[<1 Wells>],
)
In [5]: ome.images[0]
Out[5]:
Image(
id='Image:0',
name='Series 1',
pixels=Pixels(
id='Pixels:0',
dimension_order='XYCZT',
size_c=3,
size_t=16,
size_x=1024,
size_y=1024,
size_z=1,
type='uint16',
bin_data=[<1 Bin_Data>],
channels=[<3 Channels>],
physical_size_x=0.207,
physical_size_y=0.207,
time_increment=120.1302,
),
acquisition_date=datetime.fromisoformat('2008-02-06T13:43:19'),
description='An example OME compliant file, based on Olympus.oib',
)
```
#### Objects can be removed, or changed
```python
In [6]: from ome_types.model.simple_types import UnitsLength
In [7]: from ome_types.model.channel import AcquisitionMode
In [8]: ome.images[0].description = "This is the new description."
In [9]: ome.images[0].pixels.physical_size_x = 350.0
In [10]: ome.images[0].pixels.physical_size_x_unit = UnitsLength.NANOMETER
In [11]: for c in ome.images[0].pixels.channels:
c.acquisition_mode = AcquisitionMode.SPINNING_DISK_CONFOCAL
```
#### Elements can be added by constructing new OME model objects
```python
In [12]: from ome_types.model import Instrument, Microscope, Objective, InstrumentRef
In [13]: microscope_mk4 = Microscope(
manufacturer='OME Instruments',
model='Lab Mk4',
serial_number='L4-5678',
)
In [14]: objective_40x = Objective(
manufacturer='OME Objectives',
model='40xAir',
nominal_magnification=40.0,
)
In [15]: instrument = Instrument(
microscope=microscope_mk4,
objectives=[objective_40x],
)
In [16]: ome.instruments.append(instrument)
In [17]: ome.images[0].instrument_ref = InstrumentRef(id=instrument.id)
In [18]: ome.instruments
Out[18]:
[Instrument(
id='Instrument:1',
microscope=Microscope(
manufacturer='OME Instruments',
model='Lab Mk4',
serial_number='L4-5678',
),
objectives=[<1 Objectives>],
)]
```
### export to an OME-XML string
Finally, you can generate the OME-XML representation of the OME model object,
for writing to a standalone `.ome.xml` file or inserting into the header of an
OME-TIFF file:
```python
In [19]: from ome_types import to_xml
In [20]: print(to_xml(ome))
<OME ...>
<Plate ColumnNamingConvention="letter" Columns="12" ID="Plate:1" ...>
...
</Plate>
<Instrument ID="Instrument:1">
<Microscope Manufacturer="OME Instruments" Model="Lab Mk4" SerialNumber="L4-5678" />
<Objective Manufacturer="OME Objectives" Model="40xAir" ID="Objective:1"
NominalMagnification="40.0" />
</Instrument>
<Image ID="Image:0" Name="Series 1">
<AcquisitionDate>2008-02-06T13:43:19</AcquisitionDate>
<Description>This is the new description.</Description>
<InstrumentRef ID="Instrument:1" />
<Pixels ... PhysicalSizeX="350.0" PhysicalSizeXUnit="nm" ...>
<Channel AcquisitionMode="SpinningDiskConfocal" ...>
...
</Pixels>
</Image>
</OME>
```
## Code generation
The bulk of this library (namely, modules inside `ome_types._autogenerated`) is
generated at install time, and is therefore not checked into source (or visible
in the main branch of this repo).
You can see the code generated by the main branch in the [built
branch](https://github.com/tlambert03/ome-types/tree/built)
The package at `src/ome_autogen` converts the [ome.xsd
schema](https://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd) into valid
python code. To run the code generation script in a development environment,
clone this repository and run:
```sh
python -m src.ome_autogen
```
The documentation and types for the full model can be in the [API Reference](https://ome-types.readthedocs.io/en/latest/API/ome_types/)
## Contributing
To clone and install this repository locally:
```shell
git clone https://github.com/tlambert03/ome-types.git
cd ome-types
pip install -e .[test,dev]
```
We use `pre-commit` to run various code-quality checks during continuous
integration. If you'd like to make sure that your code will pass these checks
before you commit your code, you should install `pre-commit` after cloning this
repository:
```shell
pre-commit install
```
### regenerating the models
If you modify anything in `src/ome_autogen`, you may need to
regenerate the model with:
```shell
python -m src.ome_autogen
```
### Running tests
To run tests:
```
pytest
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ome-types",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "microscopy, ome, ome-model, schema, types",
"author": null,
"author_email": "Talley Lambert <talley.lambert@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/69/190f9cabbcbbfbd49acc867c3b5191fd7634928270ea2fa3a8da79febc12/ome_types-0.5.1.post1.tar.gz",
"platform": null,
"description": "# ome-types\n\n[](LICENSE)\n[](https://pypi.python.org/pypi/ome-types)\n[](https://anaconda.org/conda-forge/ome-types)\n[](https://python.org)\n[](https://github.com/tlambert03/ome-types/actions)\n[](https://ome-types.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/tlambert03/ome-types)\n[](https://codspeed.io/tlambert03/ome-types)\n\n## A pure-python implementation of the OME data model\n\n`ome_types` provides a set of python dataclasses and utility functions for\nparsing the [OME-XML\nformat](https://docs.openmicroscopy.org/ome-model/latest/ome-xml/) into\nfully-typed python objects for interactive or programmatic access in python. It\ncan also take these python objects and output them into valid OME-XML.\n`ome_types` is a **pure python** library and does not require a Java virtual\nmachine.\n\n> Note: The generated python code can be seen in the [`built`\n> branch](https://github.com/tlambert03/ome-types/tree/built).\n> (Read the [code generation](#code-generation) section for details).\n\n### \ud83d\udcd6 [documentation](https://ome-types.readthedocs.io/)\n\n## Installation\n\n### from pip\n\n```shell\npip install ome-types\n```\n\nWith all optional dependencies:\n\n```shell\n# lxml => if you ...\n# - want to use lxml as the XML parser\n# - want to validate XML against the ome.xsd schema\n# - want to use XML documents older than the 2016-06 schema\n# pint => if you want to use object.<field>_quantity properties\n# xmlschema => if you want to validate XML but DON'T want lxml\n\npip install ome-types[lxml,pint]\n```\n\n### from conda\n\n```shell\nconda install -c conda-forge ome-types\n```\n\n### from github (bleeding edge dev version)\n\n```shell\npip install git+https://github.com/tlambert03/ome-types.git\n```\n\n## Usage\n\n### convert an XML string or filepath into an instance of `ome_types.model.OME`\n\n(The XML string/file will be validated against the [ome.xsd\nschema](https://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome.html))\n\n```python\nfrom ome_types import from_xml\n\nome = from_xml('tests/data/hcs.ome.xml')\n```\n\n### extract OME metadata from an OME-TIFF\n\n```python\nfrom ome_types import from_tiff\n\nome2 = from_tiff('tests/data/ome.tiff')\n```\n\n### manipulate the metadata via python objects\n\nBoth `from_xml` and `from_tiff` return an instance of `ome_types.model.OME`. All\nclasses in `ome_types.model` follow the naming conventions of the [OME data\nmodel](https://www.openmicroscopy.org/Schemas/Documentation/Generated/OME-2016-06/ome.html),\nbut use `snake_case` attribute names instead of `CamelCase`, to be consistent\nwith the python ecosystem.\n\n```python\nIn [2]: ome = from_xml('tests/data/hcs.ome.xml')\n\nIn [3]: ome\nOut[3]:\nOME(\n images=[<1 Images>],\n plates=[<1 Plates>],\n)\n\nIn [4]: ome.plates[0]\nOut[4]:\nPlate(\n id='Plate:1',\n name='Control Plate',\n column_naming_convention='letter',\n columns=12,\n row_naming_convention='number',\n rows=8,\n wells=[<1 Wells>],\n)\n\n\nIn [5]: ome.images[0]\nOut[5]:\nImage(\n id='Image:0',\n name='Series 1',\n pixels=Pixels(\n id='Pixels:0',\n dimension_order='XYCZT',\n size_c=3,\n size_t=16,\n size_x=1024,\n size_y=1024,\n size_z=1,\n type='uint16',\n bin_data=[<1 Bin_Data>],\n channels=[<3 Channels>],\n physical_size_x=0.207,\n physical_size_y=0.207,\n time_increment=120.1302,\n ),\n acquisition_date=datetime.fromisoformat('2008-02-06T13:43:19'),\n description='An example OME compliant file, based on Olympus.oib',\n)\n```\n\n#### Objects can be removed, or changed\n\n```python\nIn [6]: from ome_types.model.simple_types import UnitsLength\n\nIn [7]: from ome_types.model.channel import AcquisitionMode\n\nIn [8]: ome.images[0].description = \"This is the new description.\"\n\nIn [9]: ome.images[0].pixels.physical_size_x = 350.0\n\nIn [10]: ome.images[0].pixels.physical_size_x_unit = UnitsLength.NANOMETER\n\nIn [11]: for c in ome.images[0].pixels.channels:\n c.acquisition_mode = AcquisitionMode.SPINNING_DISK_CONFOCAL\n```\n\n#### Elements can be added by constructing new OME model objects\n\n```python\nIn [12]: from ome_types.model import Instrument, Microscope, Objective, InstrumentRef\n\nIn [13]: microscope_mk4 = Microscope(\n manufacturer='OME Instruments',\n model='Lab Mk4',\n serial_number='L4-5678',\n )\n\nIn [14]: objective_40x = Objective(\n manufacturer='OME Objectives',\n model='40xAir',\n nominal_magnification=40.0,\n )\n\nIn [15]: instrument = Instrument(\n microscope=microscope_mk4,\n objectives=[objective_40x],\n )\n\nIn [16]: ome.instruments.append(instrument)\n\nIn [17]: ome.images[0].instrument_ref = InstrumentRef(id=instrument.id)\n\nIn [18]: ome.instruments\nOut[18]:\n[Instrument(\n id='Instrument:1',\n microscope=Microscope(\n manufacturer='OME Instruments',\n model='Lab Mk4',\n serial_number='L4-5678',\n ),\n objectives=[<1 Objectives>],\n )]\n```\n\n### export to an OME-XML string\n\nFinally, you can generate the OME-XML representation of the OME model object,\nfor writing to a standalone `.ome.xml` file or inserting into the header of an\nOME-TIFF file:\n\n```python\nIn [19]: from ome_types import to_xml\n\nIn [20]: print(to_xml(ome))\n<OME ...>\n <Plate ColumnNamingConvention=\"letter\" Columns=\"12\" ID=\"Plate:1\" ...>\n ...\n </Plate>\n <Instrument ID=\"Instrument:1\">\n <Microscope Manufacturer=\"OME Instruments\" Model=\"Lab Mk4\" SerialNumber=\"L4-5678\" />\n <Objective Manufacturer=\"OME Objectives\" Model=\"40xAir\" ID=\"Objective:1\"\n NominalMagnification=\"40.0\" />\n </Instrument>\n <Image ID=\"Image:0\" Name=\"Series 1\">\n <AcquisitionDate>2008-02-06T13:43:19</AcquisitionDate>\n <Description>This is the new description.</Description>\n <InstrumentRef ID=\"Instrument:1\" />\n <Pixels ... PhysicalSizeX=\"350.0\" PhysicalSizeXUnit=\"nm\" ...>\n <Channel AcquisitionMode=\"SpinningDiskConfocal\" ...>\n ...\n </Pixels>\n </Image>\n</OME>\n```\n\n## Code generation\n\nThe bulk of this library (namely, modules inside `ome_types._autogenerated`) is\ngenerated at install time, and is therefore not checked into source (or visible\nin the main branch of this repo).\n\nYou can see the code generated by the main branch in the [built\nbranch](https://github.com/tlambert03/ome-types/tree/built)\n\nThe package at `src/ome_autogen` converts the [ome.xsd\nschema](https://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd) into valid\npython code. To run the code generation script in a development environment,\nclone this repository and run:\n\n```sh\npython -m src.ome_autogen\n```\n\nThe documentation and types for the full model can be in the [API Reference](https://ome-types.readthedocs.io/en/latest/API/ome_types/)\n\n## Contributing\n\nTo clone and install this repository locally:\n\n```shell\ngit clone https://github.com/tlambert03/ome-types.git\ncd ome-types\npip install -e .[test,dev]\n```\n\nWe use `pre-commit` to run various code-quality checks during continuous\nintegration. If you'd like to make sure that your code will pass these checks\nbefore you commit your code, you should install `pre-commit` after cloning this\nrepository:\n\n```shell\npre-commit install\n```\n\n### regenerating the models\n\nIf you modify anything in `src/ome_autogen`, you may need to\nregenerate the model with:\n\n```shell\npython -m src.ome_autogen\n```\n\n### Running tests\n\nTo run tests:\n\n```\npytest\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python dataclasses for the OME data model",
"version": "0.5.1.post1",
"project_urls": {
"Documentation": "https://ome-types.readthedocs.io/en/latest/",
"Source": "https://github.com/tlambert03/ome-types",
"Tracker": "https://github.com/tlambert03/ome-types/issues"
},
"split_keywords": [
"microscopy",
" ome",
" ome-model",
" schema",
" types"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd59e9a6a76a4baa323632273cd4d98e6ccf4f83f9f29d4076f7eb18f780651d",
"md5": "599258a4246c9b47329076c3d38d2ebb",
"sha256": "49fc57a81cf179b354e2a62e0d15936522e9f35afbe536fdad92139d8285b8ef"
},
"downloads": -1,
"filename": "ome_types-0.5.1.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "599258a4246c9b47329076c3d38d2ebb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 248163,
"upload_time": "2024-04-01T16:48:07",
"upload_time_iso_8601": "2024-04-01T16:48:07.340466Z",
"url": "https://files.pythonhosted.org/packages/fd/59/e9a6a76a4baa323632273cd4d98e6ccf4f83f9f29d4076f7eb18f780651d/ome_types-0.5.1.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a69190f9cabbcbbfbd49acc867c3b5191fd7634928270ea2fa3a8da79febc12",
"md5": "95ff60822a181c6ca2e2cd806081b906",
"sha256": "cadda5e36ad4d33dad2034fd43f32113a736fe47c67fd9e06bbb8d3858d1dc58"
},
"downloads": -1,
"filename": "ome_types-0.5.1.post1.tar.gz",
"has_sig": false,
"md5_digest": "95ff60822a181c6ca2e2cd806081b906",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 121825,
"upload_time": "2024-04-01T16:48:08",
"upload_time_iso_8601": "2024-04-01T16:48:08.971286Z",
"url": "https://files.pythonhosted.org/packages/4a/69/190f9cabbcbbfbd49acc867c3b5191fd7634928270ea2fa3a8da79febc12/ome_types-0.5.1.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-01 16:48:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tlambert03",
"github_project": "ome-types",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ome-types"
}
JSON
