{"id":15576802,"url":"https://github.com/tlambert03/ome-types","last_synced_at":"2025-04-04T17:06:43.875Z","repository":{"id":39617382,"uuid":"218640637","full_name":"tlambert03/ome-types","owner":"tlambert03","description":"native Python dataclasses for the OME data model","archived":false,"fork":false,"pushed_at":"2024-10-15T19:24:02.000Z","size":812,"stargazers_count":50,"open_issues_count":9,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-17T05:13:57.736Z","etag":null,"topics":["metadata","microscopy","ome"],"latest_commit_sha":null,"homepage":"https://ome-types.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tlambert03.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-30T22:50:05.000Z","updated_at":"2024-09-23T21:16:43.000Z","dependencies_parsed_at":"2023-12-16T23:48:50.985Z","dependency_job_id":"a1f0c2fc-6c7d-4898-8929-31712f6b95c6","html_url":"https://github.com/tlambert03/ome-types","commit_stats":{"total_commits":169,"total_committers":8,"mean_commits":21.125,"dds":"0.30177514792899407","last_synced_commit":"422db221fad08144a59f6396a65b1567465134b8"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2Fome-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2Fome-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2Fome-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2Fome-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tlambert03","download_url":"https://codeload.github.com/tlambert03/ome-types/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217176,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metadata","microscopy","ome"],"created_at":"2024-10-02T18:58:23.291Z","updated_at":"2025-04-04T17:06:43.857Z","avatar_url":"https://github.com/tlambert03.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ome-types\n\n[![License](https://img.shields.io/github/license/tlambert03/ome-types)](LICENSE)\n[![Version](https://img.shields.io/pypi/v/ome-types.svg)](https://pypi.python.org/pypi/ome-types)\n[![CondaVersion](https://img.shields.io/conda/v/conda-forge/ome-types)](https://anaconda.org/conda-forge/ome-types)\n[![Python\nVersion](https://img.shields.io/pypi/pyversions/ome-types.svg)](https://python.org)\n[![Tests](https://github.com/tlambert03/ome-types/workflows/tests/badge.svg)](https://github.com/tlambert03/ome-types/actions)\n[![Docs](https://readthedocs.org/projects/ome-types/badge/?version=latest)](https://ome-types.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gh/tlambert03/ome-types/branch/main/graph/badge.svg?token=GocY9y8A32)](https://codecov.io/gh/tlambert03/ome-types)\n[![Benchmarks](https://img.shields.io/badge/⏱-codspeed-%23FF7B53)](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\u003e Note: The generated python code can be seen in the [`built`\n\u003e branch](https://github.com/tlambert03/ome-types/tree/built).\n\u003e (Read the [code generation](#code-generation) section for details).\n\n### 📖 \u0026nbsp;\u0026nbsp;[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 =\u003e 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      =\u003e if you want to use object.\u003cfield\u003e_quantity properties\n# xmlschema =\u003e 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=[\u003c1 Images\u003e],\n    plates=[\u003c1 Plates\u003e],\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=[\u003c1 Wells\u003e],\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=[\u003c1 Bin_Data\u003e],\n        channels=[\u003c3 Channels\u003e],\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=[\u003c1 Objectives\u003e],\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\u003cOME ...\u003e\n    \u003cPlate ColumnNamingConvention=\"letter\" Columns=\"12\" ID=\"Plate:1\" ...\u003e\n        ...\n    \u003c/Plate\u003e\n    \u003cInstrument ID=\"Instrument:1\"\u003e\n        \u003cMicroscope Manufacturer=\"OME Instruments\" Model=\"Lab Mk4\" SerialNumber=\"L4-5678\" /\u003e\n        \u003cObjective Manufacturer=\"OME Objectives\" Model=\"40xAir\" ID=\"Objective:1\"\n        NominalMagnification=\"40.0\" /\u003e\n    \u003c/Instrument\u003e\n    \u003cImage ID=\"Image:0\" Name=\"Series 1\"\u003e\n        \u003cAcquisitionDate\u003e2008-02-06T13:43:19\u003c/AcquisitionDate\u003e\n        \u003cDescription\u003eThis is the new description.\u003c/Description\u003e\n        \u003cInstrumentRef ID=\"Instrument:1\" /\u003e\n        \u003cPixels ... PhysicalSizeX=\"350.0\" PhysicalSizeXUnit=\"nm\" ...\u003e\n            \u003cChannel AcquisitionMode=\"SpinningDiskConfocal\" ...\u003e\n             ...\n        \u003c/Pixels\u003e\n    \u003c/Image\u003e\n\u003c/OME\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2Fome-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlambert03%2Fome-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2Fome-types/lists"}