| Name | useq-schema JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | Schema for multi-dimensional microscopy experiments |
| upload_time | 2025-02-11 01:05:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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/ci.yml)
[](https://pymmcore-plus.github.io/useq-schema/)
[](https://codecov.io/gh/pymmcore-plus/useq-schema)
*An open, implementation-agnostic schema for describing multi-dimensional
microscopy experiments.*
**Documentation: <https://pymmcore-plus.github.io/useq-schema/>**
## Rationale
The `useq-schema` library defines a structured schema to represent a sequence of
microscope acquisition events. By adopting this schema, various microscopy
software tools can facilitate interoperability, allowing end users to
potentially switch between different control backends with ease. *The goal is to
encourage a shared standard, making it straightforward for developers to adopt
useq-schema and enhance compatibility across tools.*
> [!IMPORTANT]
>
> **Hey developers! :wave: Not convinced? Don't leave yet!**
>
> We are particularly interested in feedback from developers of microscopy-control
> software.
>
> If you are considering supporting `useq-schema` in your software, but don't
> see all the fields in `MDAEvent` that you would need to support your complex use case,
> please [open an issue](https://github.com/pymmcore-plus/useq-schema/issues/new) or pull
> request to discuss additional features.
>
> :carrot: The carrot for you?
>
> Anyone who is already using `useq-schema` to describe a sequence of events
> in some other software (that supports it) can easily try out your solution, with
> (hopefully) minimal changes to their code.
## `useq.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).
```python
from useq import MDAEvent
event = MDAEvent(
channel="DAPI",
exposure=100,
x_pos=100.0,
y_pos=100.0,
z_pos=30.0,
min_start_time=10.0,
... # multiple other fields
)
```
Downstream libraries that aim to support useq-schema should support driving
hardware based on an `Iterable[MDAEvent]`. See [`useq.MDAEvent`
documentation](https://pymmcore-plus.github.io/useq-schema/schema/event/) for
more details.
<details>
<summary>Similar objects in existing software packages</summary>
- 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` provides a `to_pycromanager()` method that converts an `MDAEvent` into a
single pycro-manager event dict)
- *your object here?...*
</details>
## `useq.MDASequence`
`useq.MDASequence` is a declarative representation of an multi-dimensional
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.
See [`useq.MDASequence` documentation](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)
for more details.
<details>
<summary>Similar objects in existing software packages</summary>
- 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` provides a `to_pycromanager()`method that
converts an `MDASequence` to a list of pycro-manager events)
- *your object here?...*
</details>
### Example 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',
)
```
The `MDASequence` object is iterable, yielding `MDAEvent` objects in the order
specified by the `axis_order` attribute.
```python
>>> 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,
)]
```
Both `MDAEvent` and `MDASequence` objects are pydantic models, so they can be
easily serialized to and from json or yaml.
```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
```
## Installation
```bash
pip install useq-schema
```
or, with conda:
```bash
conda install -c conda-forge useq-schema
```
## Executing useq-schema experiments with pymmcore-plus
[pymmcore-plus](https://github.com/pymmcore-plus/pymmcore-plus) implements an
acquisition engine that can execute an iterable of `MDAEvents` 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)
```
This can be considered a "reference implementation" of an engine that supports useq-schema.
See [pymmcore-plus documentation](https://pymmcore-plus.github.io/pymmcore-plus/examples/mda/) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "useq-schema",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "microscopy, schema",
"author": null,
"author_email": "Talley Lambert <talley.lambert@gmail.com>, Federico Gasparoli <federico.gasparoli@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/14/a2/53b27075b47b542ee429b2523ac06467ff65b11ff9847731e283f09bee36/useq_schema-0.7.0.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/ci.yml)\n[](https://pymmcore-plus.github.io/useq-schema/)\n[](https://codecov.io/gh/pymmcore-plus/useq-schema)\n\n*An open, implementation-agnostic schema for describing multi-dimensional\nmicroscopy experiments.*\n\n**Documentation: <https://pymmcore-plus.github.io/useq-schema/>**\n\n## Rationale\n\nThe `useq-schema` library defines a structured schema to represent a sequence of\nmicroscope acquisition events. By adopting this schema, various microscopy\nsoftware tools can facilitate interoperability, allowing end users to\npotentially switch between different control backends with ease. *The goal is to\nencourage a shared standard, making it straightforward for developers to adopt\nuseq-schema and enhance compatibility across tools.*\n\n> [!IMPORTANT]\n>\n> **Hey developers! :wave: Not convinced? Don't leave yet!** \n>\n> We are particularly interested in feedback from developers of microscopy-control\n> software.\n> \n> If you are considering supporting `useq-schema` in your software, but don't\n> see all the fields in `MDAEvent` that you would need to support your complex use case,\n> please [open an issue](https://github.com/pymmcore-plus/useq-schema/issues/new) or pull\n> request to discuss additional features.\n>\n> :carrot: The carrot for you?\n> \n> Anyone who is already using `useq-schema` to describe a sequence of events\n> in some other software (that supports it) can easily try out your solution, with\n> (hopefully) minimal changes to their code.\n\n## `useq.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).\n\n```python\nfrom useq import MDAEvent\n\nevent = MDAEvent(\n channel=\"DAPI\",\n exposure=100,\n x_pos=100.0,\n y_pos=100.0,\n z_pos=30.0,\n min_start_time=10.0,\n ... # multiple other fields\n)\n```\n\nDownstream libraries that aim to support useq-schema should support driving\nhardware based on an `Iterable[MDAEvent]`. See [`useq.MDAEvent`\ndocumentation](https://pymmcore-plus.github.io/useq-schema/schema/event/) for\nmore details.\n\n<details>\n\n<summary>Similar objects in existing software packages</summary>\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` provides a `to_pycromanager()` method that converts an `MDAEvent` into a\n single pycro-manager event dict)\n- *your object here?...*\n\n</details>\n\n## `useq.MDASequence`\n\n`useq.MDASequence` is a declarative representation of an multi-dimensional\nexperiment. It represents a sequence of events: as might be generated by the\nmultidimensional acquisition GUI in most microscope software. It is composed of\n[\"plans\" for each 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\nSee [`useq.MDASequence` documentation](https://pymmcore-plus.github.io/useq-schema/schema/sequence/)\nfor more details.\n\n<details>\n\n<summary>Similar objects in existing software packages</summary>\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` provides a `to_pycromanager()`method that\n converts an `MDASequence` to a list of pycro-manager events)\n- *your object here?...*\n\n</details>\n\n### Example 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)\n```\n\nThe `MDASequence` object is iterable, yielding `MDAEvent` objects in the order\nspecified by the `axis_order` attribute.\n\n```python\n>>> events = list(mda_seq)\n\n>>> print(len(events))\n720 \n\n>>> print(events[:3])\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\nBoth `MDAEvent` and `MDASequence` objects are pydantic models, so they can be\neasily serialized to and from json or yaml.\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\n## Installation\n\n```bash\npip install useq-schema\n```\n\nor, with conda:\n\n```bash\nconda install -c conda-forge useq-schema\n```\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 iterable of `MDAEvents` 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\nThis can be considered a \"reference implementation\" of an engine that supports useq-schema. \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.7.0",
"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": null,
"digests": {
"blake2b_256": "0c73019569b86019ea58264e3eaab18c9ca5d4eaf9821c36a415d92457a54ca4",
"md5": "8bc48a7eb1c44de5e4d7c52bd57e6f52",
"sha256": "63c294d2e78ef9f81f8b885367d147809c08123118ea684b53893f78985365ab"
},
"downloads": -1,
"filename": "useq_schema-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8bc48a7eb1c44de5e4d7c52bd57e6f52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 54896,
"upload_time": "2025-02-11T01:05:50",
"upload_time_iso_8601": "2025-02-11T01:05:50.079127Z",
"url": "https://files.pythonhosted.org/packages/0c/73/019569b86019ea58264e3eaab18c9ca5d4eaf9821c36a415d92457a54ca4/useq_schema-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "14a253b27075b47b542ee429b2523ac06467ff65b11ff9847731e283f09bee36",
"md5": "b2c38beeef4d06197dbcb652da3b65d7",
"sha256": "3b786e3a54be8f65c70f1012a37cdc61e58085b745f1a4f33699447976b601f2"
},
"downloads": -1,
"filename": "useq_schema-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "b2c38beeef4d06197dbcb652da3b65d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 67734,
"upload_time": "2025-02-11T01:05:52",
"upload_time_iso_8601": "2025-02-11T01:05:52.379948Z",
"url": "https://files.pythonhosted.org/packages/14/a2/53b27075b47b542ee429b2523ac06467ff65b11ff9847731e283f09bee36/useq_schema-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-11 01:05:52",
"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"
}
