diff --git a/README.md b/README.md index 0b03675bb..4ccc1fd5f 100644 --- a/README.md +++ b/README.md @@ -25,54 +25,7 @@ You can find detailed field definitions here: The specifications are also available as json schemas: - [general RDF spec 0.2.x (json schema)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/rdf_spec_0_2.json) - -### Describing applications -The RDF can be used to describe applications. To do so set the `type` field to `application`.\ -For regular software package with a downloadable file, you can set `download_url` to the downloadable file, for example, you can upload the executable files as Github release, deposit it on Zenodo, or even generate a sharable url from Dropbox/Google Drive.\ -For web application, set `source` to the url of the web application. Users can then click and redirect to your web application. However, simple integration will not support features such as opening dataset or models with your application. - -It is recommended to build BioEngine Apps such that users can directly try and use them in BioImage.IO. See [here](https://github.com/bioimage-io/bioimage.io/blob/main/docs/bioengine_apps/build-bioengine-apps.md) for more details.\ -Below is an example for [Kaibu](https://kaibu.org), which is a BioEngine/ImJoy compatible web application: -```yaml -id: kaibu -name: Kaibu -description: Kaibu--a web application for visualizing and annotating multi-dimensional images -covers: - # use the `raw` url if you store the image on github - - https://raw.githubusercontent.com/imjoy-team/kaibu/master/public/static/img/kaibu-screenshot-1.png - -# source url to kaibu.org -source: https://kaibu.org -# add custom badge -badge: - - icon: https://imjoy.io/static/badge/launch-imjoy-badge.svg - label: Launch ImJoy - url: https://imjoy.io/#/app?plugin=https://kaibu.org/#/app -``` -For more application examples, see the [manifest for ImJoy](https://github.com/imjoy-team/bioimage-io-models/blob/master/manifest.bioimage.io.yaml). - -### Describing datasets, notebooks and other types -The RDF allows for the description of datasets (type=`dataset`), notebooks (type=`notebook`) and other potential resources, you can use set `source` and/or `download_url` to point to the resource, or use `attachments` to specify a list of associated files. - -For examples, see entries `dataset`/`notebook` in the [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic/blob/master/manifest.bioimage.io.yaml) collection. - - -### Describing models with the unspecific RDF(not recommended, use the Model RDF instead) -In general, it is discouraged to use the general RDF to describe AI models and we recommend to follow the [model RDF spec](#model-resource-description-file-specification) instead. However, in some cases, it is not possible to provide detailed fields defined in the [model RDF spec](#model-resource-description-file-specification), the general RDF can be used for discribing AI models. -To do that, you need to first set the `type` field to `model`.\ -A basic integration would be simply provide a `download_url` to a zip file (for example, with the model weights, source code or executable binary file) hosted on Github releases, Dropbox, Google Drive etc. For example: -```yaml -download_url: https://zenodo.org/record/3446812/files/unet2d_weights.torch?download=1 -``` - -If the model is available as a github repo, then provide the `git_repo` field: -```yaml -git_repo: https://github.com/my/model... -``` - -Here an example of a general RDF describing a model (not recommended): -https://github.com/CellProfiling/HPA-model-zoo/blob/2f668d87defddc6c7cd156259a8be4146b665e72/manifest.bioimage.io.yaml#L33-L59 - +[Here](https://github.com/bioimage-io/spec-bioimage-io/blob/main/example_specs/rdf-examples.md) you can find some examples for using RDF to describe applications, notebooks, datasets etc. ## [Model Resource Description File Specification](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/model_spec_latest.md) @@ -169,6 +122,8 @@ or if the field `test_inputs` does not contain a list, it would print: ### RDF Format Versions #### collection RDF 0.2.2 +- Non-breaking changes + - make `authors`, `cite`, `documentation` and `tags` optional - Breaking changes that are fully auto-convertible - Simplifies collection RDF 0.2.1 by merging resource type fields together to a `collection` field, holindg a list of all resources in the specified collection. diff --git a/bioimageio/spec/VERSION b/bioimageio/spec/VERSION index 059b4440a..d56125d2b 100644 --- a/bioimageio/spec/VERSION +++ b/bioimageio/spec/VERSION @@ -1,3 +1,3 @@ { - "version": "0.4.2post2" + "version": "0.4.2post3" } diff --git a/bioimageio/spec/collection/v0_2/raw_nodes.py b/bioimageio/spec/collection/v0_2/raw_nodes.py index c285b8fae..46e84e4b2 100644 --- a/bioimageio/spec/collection/v0_2/raw_nodes.py +++ b/bioimageio/spec/collection/v0_2/raw_nodes.py @@ -54,18 +54,18 @@ def __init__( version: Union[_Missing, distutils.version.StrictVersion] = missing, # RDF attachments: Union[_Missing, Dict[str, Any]] = missing, - authors: List[Author], + authors: Union[_Missing, List[Author]] = missing, badges: Union[_Missing, List[Badge]] = missing, - cite: List[CiteEntry], + cite: Union[_Missing, List[CiteEntry]] = missing, config: Union[_Missing, dict] = missing, covers: Union[_Missing, List[Union[URI, Path]]] = missing, description: str, - documentation: Path, + documentation: Union[_Missing, Path] = missing, git_repo: Union[_Missing, str] = missing, license: Union[_Missing, str] = missing, links: Union[_Missing, List[str]] = missing, maintainers: Union[_Missing, List[Maintainer]] = missing, - tags: List[str], + tags: Union[_Missing, List[str]] = missing, # collection RDF collection: List[CollectionEntry], unknown: Dict[str, Any] = missing, diff --git a/bioimageio/spec/rdf/v0_2/raw_nodes.py b/bioimageio/spec/rdf/v0_2/raw_nodes.py index 600c8fc2d..32f1955d7 100644 --- a/bioimageio/spec/rdf/v0_2/raw_nodes.py +++ b/bioimageio/spec/rdf/v0_2/raw_nodes.py @@ -81,13 +81,13 @@ class Badge(RawNode): @dataclass class RDF(ResourceDescription): attachments: Union[_Missing, Attachments] = missing - authors: List[Author] = missing + authors: Union[_Missing, List[Author]] = missing badges: Union[_Missing, List[Badge]] = missing - cite: List[CiteEntry] = missing + cite: Union[_Missing, List[CiteEntry]] = missing config: Union[_Missing, dict] = missing covers: Union[_Missing, List[Union[URI, Path]]] = missing description: str = missing - documentation: Path = missing + documentation: Union[_Missing, Path] = missing format_version: FormatVersion = missing git_repo: Union[_Missing, str] = missing id: Union[_Missing, str] = missing @@ -96,7 +96,7 @@ class RDF(ResourceDescription): links: Union[_Missing, List[str]] = missing maintainers: Union[_Missing, List[Maintainer]] = missing rdf_source: Union[_Missing, URI] = missing - tags: List[str] = missing + tags: Union[_Missing, List[str]] = missing # manual __init__ to allow for unknown kwargs def __init__( @@ -109,13 +109,13 @@ def __init__( version: Union[_Missing, distutils.version.StrictVersion] = missing, # RDF attachments: Union[_Missing, Dict[str, Any]] = missing, - authors: List[Author], + authors: Union[_Missing, List[Author]] = missing, badges: Union[_Missing, List[Badge]] = missing, - cite: List[CiteEntry], + cite: Union[_Missing, List[CiteEntry]] = missing, config: Union[_Missing, dict] = missing, covers: Union[_Missing, List[Union[URI, Path]]] = missing, description: str, - documentation: Path, + documentation: Union[_Missing, Path] = missing, git_repo: Union[_Missing, str] = missing, id: Union[_Missing, str] = missing, icon: Union[_Missing, str] = missing, @@ -123,7 +123,7 @@ def __init__( links: Union[_Missing, List[str]] = missing, maintainers: Union[_Missing, List[Maintainer]] = missing, rdf_source: Union[_Missing, URI] = missing, - tags: List[str], + tags: Union[_Missing, List[str]] = missing, **unknown_kwargs, ): self.attachments = attachments diff --git a/bioimageio/spec/rdf/v0_2/schema.py b/bioimageio/spec/rdf/v0_2/schema.py index f745dbcd2..b4ae51ef4 100644 --- a/bioimageio/spec/rdf/v0_2/schema.py +++ b/bioimageio/spec/rdf/v0_2/schema.py @@ -88,14 +88,14 @@ class Meta: authors_bioimageio_description = ( "A list of authors. The authors are the creators of the specifications and the primary points of contact." ) - authors = fields.List(fields.Nested(Author()), bioimageio_description=authors_bioimageio_description, required=True) + authors = fields.List(fields.Nested(Author()), bioimageio_description=authors_bioimageio_description) badges = fields.List(fields.Nested(Badge()), bioimageio_description="a list of badges") cite_bioimageio_description = """A list of citation entries. Each entry contains a mandatory `text` field and either one or both of `doi` and `url`. E.g. the citation for the model architecture and/or the training data used.""" - cite = fields.List(fields.Nested(CiteEntry()), required=True, bioimageio_description=cite_bioimageio_description) + cite = fields.List(fields.Nested(CiteEntry()), bioimageio_description=cite_bioimageio_description) config_bioimageio_description = ( "A custom configuration field that can contain any keys not present in the RDF spec. " @@ -139,7 +139,6 @@ class Meta: ) ), ], - required=True, bioimageio_description="URL or relative path to markdown file with additional documentation. " "For markdown files the recommended documentation file name is `README.md`.", ) @@ -223,7 +222,7 @@ def warn_about_long_name(self, value: str): bioimageio_description="url or local relative path to the source of the resource", ) - tags = fields.List(fields.String(), required=True, bioimageio_description="A list of tags.") + tags = fields.List(fields.String(), bioimageio_description="A list of tags.") type = fields.String(required=True) diff --git a/example_specs/collections/unet2d_nuclei_broad_coll/rdf.yaml b/example_specs/collections/unet2d_nuclei_broad_coll/rdf.yaml index e9fd2ee4f..db8a8ab90 100644 --- a/example_specs/collections/unet2d_nuclei_broad_coll/rdf.yaml +++ b/example_specs/collections/unet2d_nuclei_broad_coll/rdf.yaml @@ -23,7 +23,7 @@ cite: url: https://www.kaggle.com/c/data-science-bowl-2018 git_repo: https://github.com/bioimage-io/spec-bioimage-io/tree/main/example_specs/models/unet2d_nuclei_broad -tags: [unet2d, pytorch, nucleus, segmentation, dsb2018] +# tags: [unet2d, pytorch, nucleus, segmentation, dsb2018] # tags is optional for collection license: MIT documentation: README.md diff --git a/example_specs/rdf-examples.md b/example_specs/rdf-examples.md new file mode 100644 index 000000000..0465aed54 --- /dev/null +++ b/example_specs/rdf-examples.md @@ -0,0 +1,83 @@ +# Examples for describing the + +### Describing applications +The RDF can be used to describe applications. To do so set the `type` field to `application`.\ +For regular software package with a downloadable file, you can set `download_url` to the downloadable file, for example, you can upload the executable files as Github release, deposit it on Zenodo, or even generate a sharable url from Dropbox/Google Drive.\ +For web application, set `source` to the url of the web application. Users can then click and redirect to your web application. However, simple integration will not support features such as opening dataset or models with your application. + +It is recommended to build BioEngine Apps such that users can directly try and use them in BioImage.IO. See [here](https://github.com/bioimage-io/bioimage.io/blob/main/docs/bioengine_apps/build-bioengine-apps.md) for more details.\ +Below is an example for [Kaibu](https://kaibu.org), which is a BioEngine/ImJoy compatible web application: +```yaml +id: kaibu +name: Kaibu +description: Kaibu--a web application for visualizing and annotating multi-dimensional images +covers: + # use the `raw` url if you store the image on github + - https://raw.githubusercontent.com/imjoy-team/kaibu/master/public/static/img/kaibu-screenshot-1.png + +# source url to kaibu.org +source: https://kaibu.org +# add custom badge +badges: + - icon: https://imjoy.io/static/badge/launch-imjoy-badge.svg + label: Launch ImJoy + url: https://imjoy.io/#/app?plugin=https://kaibu.org/#/app +``` +For more application examples, see the [manifest for ImJoy](https://github.com/imjoy-team/bioimage-io-models/blob/master/manifest.bioimage.io.yaml). + +### Describing notebooks and scripts + +Jupyter notebooks, Google Colab or other types of executable notebooks or scripts are considered as applications, therefore, you should use `type=application` and add additional tags. For example: +``` + - type: application + id: Notebook_fnet_3D_ZeroCostDL4Mic + name: Label-free Prediction - fnet - (3D) ZeroCostDL4Mic + description: Paired image-to-image translation of 3D images. Label-free Prediction (fnet) is a neural network used to infer the features of cellular structures from brightfield or EM images without coloured labels. The network is trained using paired training images from the same field of view, imaged in a label-free (e.g. brightfield) and labelled condition (e.g. fluorescent protein). When trained, this allows the user to identify certain structures from brightfield images alone. The performance of fnet may depend significantly on the structure at hand. Note - visit the ZeroCostDL4Mic wiki to check the original publications this network is based on and make sure you cite these. + cite: + - text: "von Chamier, L., Laine, R.F., Jukkala, J. et al. Democratising deep learning for microscopy with ZeroCostDL4Mic. Nat Commun 12, 2276 (2021). https://doi.org/10.1038/s41467-021-22518-0" + doi: https://doi.org/10.1038/s41467-021-22518-0 + + - text: "Ounkomol, C., Seshamani, S., Maleckar, M.M. et al. Label-free prediction of three-dimensional fluorescence images from transmitted-light microscopy. Nat Methods 15, 917–920 (2018). https://doi.org/10.1038/s41592-018-0111-2" + doi: https://doi.org/10.1038/s41592-018-0111-2 + + authors: + - Lucas von Chamier and the ZeroCostDL4Mic Team + covers: + - https://raw.githubusercontent.com/HenriquesLab/ZeroCostDL4Mic/master/BioimageModelZoo/Images/fnet_notebook.png + + badges: + - label: Open in Colab + icon: https://colab.research.google.com/assets/colab-badge.svg + url: https://colab.research.google.com/github/HenriquesLab/ZeroCostDL4Mic/blob/master/Colab_notebooks/fnet_3D_ZeroCostDL4Mic.ipynb + documentation: https://raw.githubusercontent.com/HenriquesLab/ZeroCostDL4Mic/master/BioimageModelZoo/README.md + tags: [colab, notebook, fnet, labelling, ZeroCostDL4Mic, 3D] + download_url: https://raw.githubusercontent.com/HenriquesLab/ZeroCostDL4Mic/master/Colab_notebooks/fnet_3D_ZeroCostDL4Mic.ipynb + git_repo: https://github.com/HenriquesLab/ZeroCostDL4Mic + links: + - Notebook Preview + - Dataset_fnet_3D_ZeroCostDL4Mic +``` + + +### Describing datasets and other types +The RDF allows for the description of datasets (type=`dataset`) and other potential resources, you can use set `source` and/or `download_url` to point to the resource, or use `attachments` to specify a list of associated files. + +For examples, see entries `dataset`/`notebook` in the [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic/blob/master/manifest.bioimage.io.yaml) collection. + + +### Describing models with the unspecific RDF(not recommended, use the Model RDF instead) +In general, it is discouraged to use the general RDF to describe AI models and we recommend to follow the [model RDF spec](#model-resource-description-file-specification) instead. However, in some cases, it is not possible to provide detailed fields defined in the [model RDF spec](#model-resource-description-file-specification), the general RDF can be used for discribing AI models. +To do that, you need to first set the `type` field to `model`.\ +A basic integration would be simply provide a `download_url` to a zip file (for example, with the model weights, source code or executable binary file) hosted on Github releases, Dropbox, Google Drive etc. For example: +```yaml +download_url: https://zenodo.org/record/3446812/files/unet2d_weights.torch?download=1 +``` + +If the model is available as a github repo, then provide the `git_repo` field: +```yaml +git_repo: https://github.com/my/model... +``` + +Here an example of a general RDF describing a model (not recommended): +https://github.com/CellProfiling/HPA-model-zoo/blob/2f668d87defddc6c7cd156259a8be4146b665e72/manifest.bioimage.io.yaml#L33-L59 +