| Name | useq-schema JSON |
| Version |
0.4.6
JSON |
| download |
| home_page | |
| Summary | Schema for multi-dimensional microscopy experiments |
| upload_time | 2023-08-16 16:55:26 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | BSD 3-Clause License |
| keywords |
microscopy
schema
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# useq-schema
[](https://github.com/pymmcore-plus/useq-schema/raw/main/LICENSE)
[](https://pypi.org/project/useq-schema)
[](https://pypi.org/project/useq-schema)
[](https://anaconda.org/conda-forge/useq-schema)
[](https://github.com/pymmcore-plus/useq-schema/actions/workflows/test_and_deploy.yml)
[](https://pymmcore-plus.github.io/useq-schema/)
[](https://codecov.io/gh/pymmcore-plus/useq-schema)
*An implementation agnostic schema for describing a sequence of events during a
multi-dimensional imaging acquisition.*
**Documentation: <https://pymmcore-plus.github.io/useq-schema/>**
The goal of this repo is to provide a specification (and some python utilities)
for generating event objects that can be consumed by microscope acquisition
engines. The *hope* is that this will encourage interoperability between
various efforts to drive automated image acquisition.
The schema *tries* to remain agnostic to the specific acquisition engine, though
it was designed around the needs of Micro-Manager. One hope is to solicit
feedback from interested parties regarding limitations and/or potential
extensions to the schema. Similarly, while the "ideal" schema will support
arbitrary dimensions (i.e. more than the conventional position, time, channel,
z, ...), it also hard to avoid hard-coding some assumptions about dimensionality
in certain places.
Any and all feedback is welcome! Please get in touch if you have any thoughts.
## `MDAEvent`
The primary "event" object is `useq.MDAEvent`. This represents a single event
that a microscope should perform, including preparation of the hardware, and
execution of the event (such as an image acquisition). This is the simpler,
but more important of the two objects. Downstream libraries that aim to support
useq schema should support driving hardware based on an `Iterable[MDAEvent]`.
- For [micro-manager](https://github.com/micro-manager/micro-manager), this
object is most similar (though not *that* similar) to the events generated by
[`generate-acq-sequence`](https://github.com/micro-manager/micro-manager/blob/2b0f51a2f916112d39c6135ad35a112065f8d58d/acqEngine/src/main/clj/org/micromanager/sequence_generator.clj#L410)
in the clojure acquisition engine.
- For [pycro-manager](https://github.com/micro-manager/pycro-manager), this
object is similar to an individual [acquisition event
`dict`](https://pycro-manager.readthedocs.io/en/latest/apis.html#acquisition-event-specification)
generated by
[`multi_d_acquisition_events`](https://github.com/micro-manager/pycro-manager/blob/63cf209a8907fd23932ee9f8016cb6a2b61b45aa/pycromanager/acquire.py#L605),
(and, `useq.MDAEvent` provides a `to_pycromanager()` method that returns a
single pycro-manager event dict)
- *your object here?...*
See [`useq.MDAEvent` documentation](https://pymmcore-plus.github.io/useq-schema/schema/event/)
for more details.
> **Note:** `useq-schema` uses [`pydantic`](https://pydantic-docs.helpmanual.io/) to
> define models, so you can retrieve the [json schema](https://json-schema.org/)
> for the `MDAEvent` object with `MDAEvent.schema_json()`
## `MDASequence`
`useq.MDASequence` is a declarative representation of an entire experiment. It
represents a sequence of events (as might be generated by the multidimensional
acquisition GUI in most microscope software). It is composed of ["plans" for
each axis in the
experiment](https://pymmcore-plus.github.io/useq-schema/schema/axes/) (such as a
Time Plan, a Z Plan, a list of channels and positions, etc.). A
`useq.MDASequence` object is itself iterable, and yields `MDAEvent` objects.
- For [micro-manager](https://github.com/micro-manager/micro-manager), this
object is most similar to
[`org.micromanager.acquisition.SequenceSettings`](https://github.com/micro-manager/micro-manager/blob/2b0f51a2f916112d39c6135ad35a112065f8d58d/mmstudio/src/main/java/org/micromanager/acquisition/SequenceSettings.java#L39),
(generated by clicking the "Acquire!" button in the Multi-D Acquisition GUI)
- For [pycro-manager](https://github.com/micro-manager/pycro-manager), this
object is similar to the
[`multi_d_acquisition_events`](https://github.com/micro-manager/pycro-manager/blob/63cf209a8907fd23932ee9f8016cb6a2b61b45aa/pycromanager/acquire.py#L605)
convenience function, (and `useq.MDASequence` provides a `to_pycromanager()`
method that returns a list of pycro-manager events)
- *your object here?...*
See [`useq.MDASequence` documentation](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)
for more details.
### example `MDASequence` usage:
```python
from useq import MDASequence
mda_seq = MDASequence(
stage_positions=[(100, 100, 30), (200, 150, 35)],
channels=["DAPI", "FITC"],
time_plan={'interval': 1, 'loops': 20},
z_plan={"range": 4, "step": 0.5},
axis_order='tpcz',
)
events = list(mda_seq)
print(len(events)) # 720
print(events[:3])
# [MDAEvent(
# channel=Channel(config='DAPI'),
# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 0}),
# min_start_time=0.0,
# x_pos=100.0,
# y_pos=100.0,
# z_pos=28.0,
# ),
# MDAEvent(
# channel=Channel(config='DAPI'),
# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 1}),
# min_start_time=0.0,
# x_pos=100.0,
# y_pos=100.0,
# z_pos=28.5,
# ),
# MDAEvent(
# channel=Channel(config='DAPI'),
# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 2}),
# min_start_time=0.0,
# x_pos=100.0,
# y_pos=100.0,
# z_pos=29.0,
# )]
```
serialize to yaml or json
```py
print(mda_seq.yaml())
```
```yaml
axis_order: tpcz
channels:
- config: DAPI
- config: FITC
stage_positions:
- x: 100.0
y: 100.0
z: 30.0
- x: 200.0
y: 150.0
z: 35.0
time_plan:
interval: 0:00:01
loops: 20
z_plan:
range: 4.0
step: 0.5
```
## Executing useq-schema experiments with pymmcore-plus
[pymmcore-plus](https://github.com/pymmcore-plus/pymmcore-plus) implements an
acquisition engine that can execute an `MDASequence` using
micro-manager in a pure python environment (no Java required).
```python
from pymmcore_plus import CMMCorePlus
core = CMMCorePlus()
core.loadSystemConfiguration() # loads demo by default
core.mda.run(mda_seq) # run the experiment
# or, construct a sequence of MDAEvents anyway you like
events = [MDAEvent(...), MDAEvent(...), ...]
core.mda.run(events)
```
See [pymmcore-plus documentation](https://pymmcore-plus.github.io/pymmcore-plus/examples/mda/) for details
Raw data
{
"_id": null,
"home_page": "",
"name": "useq-schema",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "microscopy,schema",
"author": "",
"author_email": "Talley Lambert <talley.lambert@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/88/aa/af2808fcc8af6d804920fed9701bd92f98eeb1dca91b5f980696ba6e0330/useq_schema-0.4.6.tar.gz",
"platform": null,
"description": "# useq-schema\n\n[](https://github.com/pymmcore-plus/useq-schema/raw/main/LICENSE)\n[](https://pypi.org/project/useq-schema)\n[](https://pypi.org/project/useq-schema)\n[](https://anaconda.org/conda-forge/useq-schema)\n[](https://github.com/pymmcore-plus/useq-schema/actions/workflows/test_and_deploy.yml)\n[](https://pymmcore-plus.github.io/useq-schema/)\n[](https://codecov.io/gh/pymmcore-plus/useq-schema)\n\n*An implementation agnostic schema for describing a sequence of events during a\nmulti-dimensional imaging acquisition.*\n\n**Documentation: <https://pymmcore-plus.github.io/useq-schema/>**\n\nThe goal of this repo is to provide a specification (and some python utilities)\nfor generating event objects that can be consumed by microscope acquisition\nengines. The *hope* is that this will encourage interoperability between\nvarious efforts to drive automated image acquisition.\n\nThe schema *tries* to remain agnostic to the specific acquisition engine, though\nit was designed around the needs of Micro-Manager. One hope is to solicit\nfeedback from interested parties regarding limitations and/or potential\nextensions to the schema. Similarly, while the \"ideal\" schema will support\narbitrary dimensions (i.e. more than the conventional position, time, channel,\nz, ...), it also hard to avoid hard-coding some assumptions about dimensionality\nin certain places. \n\nAny and all feedback is welcome! Please get in touch if you have any thoughts.\n\n## `MDAEvent`\n\nThe primary \"event\" object is `useq.MDAEvent`. This represents a single event\nthat a microscope should perform, including preparation of the hardware, and\nexecution of the event (such as an image acquisition). This is the simpler,\nbut more important of the two objects. Downstream libraries that aim to support\nuseq schema should support driving hardware based on an `Iterable[MDAEvent]`.\n\n- For [micro-manager](https://github.com/micro-manager/micro-manager), this\n object is most similar (though not *that* similar) to the events generated by\n [`generate-acq-sequence`](https://github.com/micro-manager/micro-manager/blob/2b0f51a2f916112d39c6135ad35a112065f8d58d/acqEngine/src/main/clj/org/micromanager/sequence_generator.clj#L410)\n in the clojure acquisition engine.\n- For [pycro-manager](https://github.com/micro-manager/pycro-manager), this\n object is similar to an individual [acquisition event\n `dict`](https://pycro-manager.readthedocs.io/en/latest/apis.html#acquisition-event-specification)\n generated by\n [`multi_d_acquisition_events`](https://github.com/micro-manager/pycro-manager/blob/63cf209a8907fd23932ee9f8016cb6a2b61b45aa/pycromanager/acquire.py#L605),\n (and, `useq.MDAEvent` provides a `to_pycromanager()` method that returns a\n single pycro-manager event dict)\n- *your object here?...*\n\nSee [`useq.MDAEvent` documentation](https://pymmcore-plus.github.io/useq-schema/schema/event/)\nfor more details.\n\n> **Note:** `useq-schema` uses [`pydantic`](https://pydantic-docs.helpmanual.io/) to\n> define models, so you can retrieve the [json schema](https://json-schema.org/)\n> for the `MDAEvent` object with `MDAEvent.schema_json()`\n\n## `MDASequence`\n\n`useq.MDASequence` is a declarative representation of an entire experiment. It\nrepresents a sequence of events (as might be generated by the multidimensional\nacquisition GUI in most microscope software). It is composed of [\"plans\" for\neach axis in the\nexperiment](https://pymmcore-plus.github.io/useq-schema/schema/axes/) (such as a\nTime Plan, a Z Plan, a list of channels and positions, etc.). A\n`useq.MDASequence` object is itself iterable, and yields `MDAEvent` objects.\n\n- For [micro-manager](https://github.com/micro-manager/micro-manager), this\n object is most similar to\n [`org.micromanager.acquisition.SequenceSettings`](https://github.com/micro-manager/micro-manager/blob/2b0f51a2f916112d39c6135ad35a112065f8d58d/mmstudio/src/main/java/org/micromanager/acquisition/SequenceSettings.java#L39),\n (generated by clicking the \"Acquire!\" button in the Multi-D Acquisition GUI)\n- For [pycro-manager](https://github.com/micro-manager/pycro-manager), this\n object is similar to the\n [`multi_d_acquisition_events`](https://github.com/micro-manager/pycro-manager/blob/63cf209a8907fd23932ee9f8016cb6a2b61b45aa/pycromanager/acquire.py#L605)\n convenience function, (and `useq.MDASequence` provides a `to_pycromanager()`\n method that returns a list of pycro-manager events)\n- *your object here?...*\n\nSee [`useq.MDASequence` documentation](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)\nfor more details.\n\n### example `MDASequence` usage:\n\n```python\nfrom useq import MDASequence\n\nmda_seq = MDASequence(\n stage_positions=[(100, 100, 30), (200, 150, 35)],\n channels=[\"DAPI\", \"FITC\"],\n time_plan={'interval': 1, 'loops': 20},\n z_plan={\"range\": 4, \"step\": 0.5},\n axis_order='tpcz',\n)\nevents = list(mda_seq)\n\nprint(len(events)) # 720\n\nprint(events[:3])\n\n# [MDAEvent(\n# channel=Channel(config='DAPI'),\n# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 0}),\n# min_start_time=0.0,\n# x_pos=100.0,\n# y_pos=100.0,\n# z_pos=28.0,\n# ),\n# MDAEvent(\n# channel=Channel(config='DAPI'),\n# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 1}),\n# min_start_time=0.0,\n# x_pos=100.0,\n# y_pos=100.0,\n# z_pos=28.5,\n# ),\n# MDAEvent(\n# channel=Channel(config='DAPI'),\n# index=mappingproxy({'t': 0, 'p': 0, 'c': 0, 'z': 2}),\n# min_start_time=0.0,\n# x_pos=100.0,\n# y_pos=100.0,\n# z_pos=29.0,\n# )]\n```\n\nserialize to yaml or json\n\n```py\nprint(mda_seq.yaml())\n```\n\n```yaml\naxis_order: tpcz\nchannels:\n- config: DAPI\n- config: FITC\nstage_positions:\n- x: 100.0\n y: 100.0\n z: 30.0\n- x: 200.0\n y: 150.0\n z: 35.0\ntime_plan:\n interval: 0:00:01\n loops: 20\nz_plan:\n range: 4.0\n step: 0.5\n```\n## Executing useq-schema experiments with pymmcore-plus\n\n[pymmcore-plus](https://github.com/pymmcore-plus/pymmcore-plus) implements an\nacquisition engine that can execute an `MDASequence` using\nmicro-manager in a pure python environment (no Java required).\n\n```python\nfrom pymmcore_plus import CMMCorePlus\n\ncore = CMMCorePlus()\ncore.loadSystemConfiguration() # loads demo by default\n\ncore.mda.run(mda_seq) # run the experiment\n\n# or, construct a sequence of MDAEvents anyway you like\nevents = [MDAEvent(...), MDAEvent(...), ...]\ncore.mda.run(events)\n```\n\nSee [pymmcore-plus documentation](https://pymmcore-plus.github.io/pymmcore-plus/examples/mda/) for details\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Schema for multi-dimensional microscopy experiments",
"version": "0.4.6",
"project_urls": {
"Source": "https://github.com/pymmcore-plus/useq-schema",
"Tracker": "https://github.com/pymmcore-plus/useq-schema/issues"
},
"split_keywords": [
"microscopy",
"schema"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27c3dd9876df8d9be064a17ace5991b3046ceae7b1e8dae8206a8238cbdb1c98",
"md5": "f508e780f9295bd078becae9be2723fd",
"sha256": "0a81dfe80ba53728a71350a5c08f634b5057ecfb1ec9ea458e890670e3789e85"
},
"downloads": -1,
"filename": "useq_schema-0.4.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f508e780f9295bd078becae9be2723fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33030,
"upload_time": "2023-08-16T16:55:25",
"upload_time_iso_8601": "2023-08-16T16:55:25.666450Z",
"url": "https://files.pythonhosted.org/packages/27/c3/dd9876df8d9be064a17ace5991b3046ceae7b1e8dae8206a8238cbdb1c98/useq_schema-0.4.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "88aaaf2808fcc8af6d804920fed9701bd92f98eeb1dca91b5f980696ba6e0330",
"md5": "6ef6dcb662e606e95eb93306fc1825f1",
"sha256": "c82b3eae900ff509374a642525850fc774ad120a6df17febfa33605eb73b5919"
},
"downloads": -1,
"filename": "useq_schema-0.4.6.tar.gz",
"has_sig": false,
"md5_digest": "6ef6dcb662e606e95eb93306fc1825f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45853,
"upload_time": "2023-08-16T16:55:26",
"upload_time_iso_8601": "2023-08-16T16:55:26.877352Z",
"url": "https://files.pythonhosted.org/packages/88/aa/af2808fcc8af6d804920fed9701bd92f98eeb1dca91b5f980696ba6e0330/useq_schema-0.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 16:55:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pymmcore-plus",
"github_project": "useq-schema",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "useq-schema"
}
