Specifications for bioimage.io

This repository contains the specifications of the standard format defined by the bioimage.io community for the content (i.e., models, datasets and applications) in the bioimage.io website. Each item in the content is always described using a YAML 1.2 file named rdf.yaml or bioimageio.yaml. This rdf.yaml \ bioimageio.yaml--- along with the files referenced in it --- can be downloaded from or uploaded to the bioimage.io website and may be produced or consumed by bioimage.io-compatible consumers (e.g., image analysis software like ilastik).

These are the rules and format that bioimage.io-compatible resources must fulfill.

Note that the Python package PyYAML does not support YAML 1.2 . We therefore use and recommend ruyaml. For differences see https://ruamelyaml.readthedocs.io/en/latest/pyyaml.

Please also note that the best way to check whether your rdf.yaml file is bioimage.io-compliant is to call bioimageio.core.validate from the bioimageio.core Python package. The bioimageio.core Python package also provides the bioimageio command line interface (CLI) with the validate command:

bioimageio validate path/to/your/rdf.yaml

Format version overview

All bioimage.io description formats are defined as Pydantic models.

Type	Format Version	Documentation1	Developer Documentation2
model	0.5 0.4	model 0.5 model 0.4	ModelDescr_v0_5 ModelDescr_v0_4
dataset	0.3 0.2	dataset 0.3 dataset 0.2	DatasetDescr_v0_3 DatasetDescr_v0_2
notebook	0.3 0.2	notebook 0.3 notebook 0.2	NotebookDescr_v0_3 NotebookDescr_v0_2
application	0.3 0.2	application 0.3 application 0.2	ApplicationDescr_v0_3 ApplicationDescr_v0_2
generic	0.3 0.2	-	GenericDescr_v0_3 GenericDescr_v0_2

JSON Schema

Simplified descriptions are available as JSON Schema (generated with Pydantic):

bioimageio.spec version	JSON Schema	documentation1
latest	bioimageio_schema_latest.json	latest documentation
0.5	bioimageio_schema_v0-5.json	0.5 documentation

Note: bioimageio_schema_v0-5.json and bioimageio_schema_latest.json are identical, but bioimageio_schema_latest.json will eventually refer to the future bioimageio_schema_v0-6.json.

Flattened, interactive docs

A flattened view of the types used by the spec that also shows values constraints.

rendered

You can also generate these docs locally by running PYTHONPATH=./scripts python -m interactive_docs

Examples

We provide some examples for using rdf.yaml files to describe models, applications, notebooks and datasets, and an example notebook to programmatically access the models, applications, notebooks and datasets descriptions.

💁 Recommendations

• Due to the limitations of storage services such as Zenodo, which does not support subfolders, it is recommended to place other files in the same directory level of the rdf.yaml file and try to avoid using subdirectories.
• Use the bioimageio.core Python package to validate your rdf.yaml file.
• bioimageio.spec keeps evolving. Try to use and upgrade to the most current format version!

⌨ bioimageio command-line interface (CLI)

The bioimageio CLI has moved entirely to bioimageio.core.

🖥 Installation

bioimageio.spec can be installed with either conda or pip. We recommend installing bioimageio.core instead to get access to the Python programmatic features available in the BioImage.IO community:

conda install -c conda-forge bioimageio.core

or

pip install -U bioimageio.core

Still, for a lighter package or just testing, you can install the bioimageio.spec package solely:

conda install -c conda-forge bioimageio.spec

or

pip install -U bioimageio.spec

🏞 Environment variables

TODO: link to settings in dev docs

🤝 How to contribute

♥ Contributors

Made with contrib.rocks.

🛈 Versioining scheme

To keep the bioimageio.spec Python package version in sync with the (model) description format version, bioimageio.spec is versioned as MAJOR.MINRO.PATCH.LIB, where MAJOR.MINRO.PATCH correspond to the latest model description format version implemented and LIB may be bumpbed for library changes that do not affect the format version. This change was introduced with bioimageio.spec 0.5.3.1.

Δ Changelog

The changelog of the bioimageio.spec Python package and the changes to the resource description format it implements can be found here.

Footnotes

1. JSON Schema based documentation generated with json-schema-for-humans. ↩ ↩²

2. Part of the bioimageio.spec package documentation generated with pdoc. ↩