Package: bioimageio.spec
Specifications for BioImage.IOThis repository contains specifications defined by the BioImage.IO community. These specifications are used for defining fields in YAML files which we calledResource Description FilesorRDF. The RDFs can be downloaded or uploaded to thebioimage.io website, produced or consumed by BioImage.IO-compatible consumers(e.g. image analysis software or other website). Currently we defined two types of RDFs: a dedicated RDF specification for AI models (i.e.model RDF) and a general RDF specification. The model RDF is a RDF with additional fields that specifically designed for describing AI models.All the BioImage.IO-compatible RDF must fulfill the following rules:Must be a YAML file encoded as UTF-8; If yaml syntax version is not specified to be 1.1 in the first line by% YAML 1.1it must be equivalent in yaml 1.1 and yaml 1.2. For differences seehttps://yaml.readthedocs.io/en/latest/pyyaml.html#differences-with-pyyaml.The RDF file extension must be.yaml(not.yml)The RDF file can be saved in a folder (or virtual folder) or in a zip package, the following additional rules must apply:When stored in a local file system folder, github repo, zenodo deposition, blob storage virtual folder or similar kind, the RDF file name should match the pattern of*.rdf.yaml, for examplemy-model.rdf.yaml.When the RDF file and other files are zipped into a RDF package, it must be named asrdf.yaml.As a general guideline, please follow the model RDF spec to describe AI models and use the general RDF spec for other resource types includingdataset,application. You will find more details about these two specifications in the following sections. Please also note that the best way to check whether your RDF file is BioImage.IO-compliant is to run the BioImage.IO Validator against it.Resource Description File SpecificationA BioImage.IO-compatible Resource Description File (RDF) is a YAML file with a set of specifically defined fields.You can find detailed field definitions here:general RDF spec (latest)general RDF spec (0.2.x)The specifications are also available as json schemas:general RDF spec (0.2.x, json schema)Hereyou can find some examples for using RDF to describe applications, notebooks, datasets etc.Model Resource Description File SpecificationBesides the general RDF spec, theModel Resource Description File Specification(model RDF) defines a file format for representing pretrained AI models inYAML format. This format is used to describe models hosted on theBioImage.IOmodel repository site.You can find the latestmodel RDFhere:model RDF spec (latest)Here is a list of model RDF Examples:Model RDF Examples.Collection Resource Description File SpecificationTheCollection Resource Description File Specification(collection RDF) defines a file format for representing collections of resources for theBioImage.IOwebsite.You can find the latestcollection RDFhere:collection RDF spec (latest)Linking resource itemsYou can create links to connect resource items by adding another resource item id to thelinksfield. For example, if you want to associate an applicaiton with a model, you can set the links field of the models like the following:application:-id:HPA-Classificationsource:https://raw.githubusercontent.com/bioimage-io/tfjs-bioimage-io/master/apps/HPA-Classification.imjoy.htmlmodel:-id:HPAShuffleNetV2source:https://raw.githubusercontent.com/bioimage-io/tfjs-bioimage-io/master/models/HPAShuffleNetV2/HPAShuffleNetV2.model.yamllinks:-HPA-ClassificationHosting RDFsYou can host the resource description file on one of the public git repository website, including Zenodo Github, Gitlab, Bitbucket, or Gist.
In order to make it available inhttps://bioimage.io, you can submit the RDF package via the uploader.RecommendationsFor AI models, consider using the model-specific spec (i.e.model RDF) instead of the general RDF. Only fallback to the general RDF if writing model specific RDF is not possible for some reason.The RDF or package file name should not contain spaces or special characters, it should be concise, descriptive, in kebab case or camel case.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 file and try to avoid using subdirectories.Use thebioimage.io spec validatorto verify your YAML fileStore the yaml file in a version controlled Git repository (e.g. Github or Gitlab)Use or upgrade to the latest format versionbioimageio command-line interface (CLI)The BioImage.IO command line tool makes it easy to work with BioImage.IO RDFs.
A basic version of it, documented here, is provided by thebioimageio.spec package, which is extended by thebioimageio.corepackage.validateIt is recommended to use this validator to verify your models when you write it manually or develop tools for generating RDF files.Use thevalidatecommand to check for formatting errors like missing or invalid values:bioimageio validate <MY-MODEL-SOURCE><MY-MODEL-SOURCE>may be a local RDF yaml "<MY-MODEL>/rdf.yaml" or a DOI / URL to a zenodo record, or a URL to an rdf.yaml file.To see if your model is compatible to thelatest bioimage.io model formatuse the spec validator with the--update-formatflag:bioimageio validate --update-format `<MY-MODEL-SOURCE>`The output of thevalidatecommand will indicate missing or invalid fields in the model file. For example, if the fieldtimestampwas missing it would print the following:{'timestamp': ['Missing data for required field.']}or if the fieldtest_inputsdoes not contain a list, it would print:{'test_inputs': ['Not a valid list.']}.update-formatSimilar to thevalidatecommand with--update-formatflag theupdate-formatcommand attempts to convert an RDF
to the latest applicable format version, but saves the result in a file for further manual editing:bioimageio update-format <MY-MODEL-SOURCE> <OUTPUT-PATH>bioimageio.spec Python packageThe bioimageio.spec package allows to work with BioImage.IO RDFs within Python.
The commands on which the bioimageio CLI is based can be used as functions.
Additionally, IO functions are provided to work with BioImage.IO RDFs as 'raw nodes' Python objects, e.g. the raw representation of a model RDF 0.4 atbioimageio.spec.model.v0_4.raw_nodes.
Thebioimageio.corepackage extends this 'raw' representation for more convenience.installationbioimageio.spec can be installed with eitherpiporconda:# pip
pip install -U bioimageio.spec

# conda
conda install -c conda-forge bioimageio.specAs a dependency it is included inbioimageio.corelibrary, which extends bioimageio.spec with more powerful commands like 'predict'.Environment variablesNameDefaultDescriptionBIOIMAGEIO_USE_CACHE"true"Enables simple URL to file cache. possible, case-insensitive, positive values are: "true", "yes", "1". Any other value is interpreted as "false"BIOIMAGEIO_CACHE_PATHgenerated tmp folderFile path for simple URL to file cache; changes of URL source are not detected.BIOIMAGEIO_CACHE_WARNINGS_LIMIT"3"Maximum number of warnings generated for simple cache hits.Changelogbioimageio.spec 0.4.9small bugixesbetter type hintsimproved testsbioimageio.spec 0.4.8post1addaxesandepstoscale_mean_varbioimageio.spec 0.4.7post1add simple forward compatibility by treating future format versions as latest known (for the respective resource type)bioimageio.spec 0.4.6post3Make CLI output more readablefind redirected URLs when checking for URL availabilitybioimageio.spec 0.4.6post2Improve error message for non-existing RDF file path given as stringImprove documentation for model RDF'sdocumentationfieldbioimageio.spec 0.4.6post1fix enrich_partial_rdf_with_imjoy_plugin (seehttps://github.com/bioimage-io/spec-bioimage-io/pull/452)bioimageio.spec 0.4.5post16fix rdf_update of entries inresolve_collection_entries()bioimageio.spec 0.4.5post15pass root toenrich_partial_rdfarg ofresolve_collection_entries()bioimageio.spec 0.4.5post14keepResourceDescrption.root_pathas URI for remote resources. This fixes the collection RDF as the collection entries are resolved after the collection RDF has been loaded.bioimageio.spec 0.4.5post13new bioimageio.spec.partner module adding validate-partner-collection command if optional 'lxml' dependency is availablebioimageio.spec 0.4.5post12new env varBIOIMAGEIO_CACHE_WARNINGS_LIMIT(default: 3) to avoid spam from cache hit warningsmore robust conversion of ImportableSourceFile for absolute paths to relative paths (don't fail on non-path source file)bioimageio.spec 0.4.5post11resolve symlinks when transforming absolute to relative paths during serialization; see#438bioimageio.spec 0.4.5post10fix loading of collection RDF with id (id used to be ignored)bioimageio.spec 0.4.5post9support loading bioimageio resources by their animal nickname (currently only models have nicknames).bioimageio.spec 0.4.5post8any field previously expecting a local relative path is now also accepting an absolute pathload_raw_resource_description returns a raw resource description which has no relative paths (any relative paths are converted to absolute paths).bioimageio.spec 0.4.4post7add commandcommands.update_rdf()/update-rdf(cli)bioimageio.spec 0.4.4post2fix unresolved ImportableSourceFilebioimageio.spec 0.4.4post1fix collection RDF conversion for type fieldbioimageio.spec 0.4.3post1fix to shape validation for model RDF 0.4: output shape now needs to be bigger than halomoved objects from bioimageio.spec.shared.utils to bioimageio.spec.shared[.node_transformer]additional keys to validation summary: bioimageio_spec_version, statusbioimageio.spec 0.4.2post4fixes to general RDF:ignore value of fieldroot_pathif present in yaml. This field is used internally and always present in RDF nodes.bioimageio.spec 0.4.1.post5fixes to collection RDF:RDFs specified directly in collection RDF are validated correctly even if their source field does not point to an RDF.nesting of collection RDF allowedbioimageio.spec 0.4.1.post4fixed missing fieldiconin general RDF's raw nodefixes to collection RDF:RDFs specified directly in collection RDF are validated correctlyno nesting of collection RDF allowed for nowlinksis no longer an explicit collection entry field ("moved" to unknown)bioimageio.spec 0.4.1.post0new model spec 0.3.5 and 0.4.1bioimageio.spec 0.4.0.post3load_raw_resource_descriptionno longer acceptsupdate_to_current_formatkwarg (useupdate_to_formatinstead)bioimageio.spec 0.4.0.post2load_raw_resource_descriptionacceptsupdate_to_formatkwargRDF Format Versionsbioimageio.spec 0.4.9Non-breaking changesmake pre-/postprocessing kwargsmodeandaxesalways optional for model RDF 0.3 and 0.4model RDF 0.4.8Non-breaking changescitefield is now optionalRDF 0.2.2 and model RDF 0.4.7Breaking changes that are fully auto-convertiblename field may not include '/' or '' (conversion removes these)model RDF 0.4.6Non-breaking changesImplicit output shape can be expanded by insertingnullintoshape:scaleand indicating length of new dimension D in theoffsetfield. Keep in mind thatD=2*'offset'.model RDF 0.4.5Breaking changes that are fully auto-convertibleparentfield changed to hold a string that is a BioImage.IO ID, a URL or a local relative path (and not subfieldsuriandsha256)model RDF 0.4.4Non-breaking changesnew optional fieldtraining_datadataset RDF 0.2.2Non-breaking changesexplicitly define and document dataset RDF (for now, clone of general RDF with type="dataset")model RDF 0.4.3Non-breaking changesadd optional fielddownload_urladd optional fielddependenciesto all weight formats (not only pytorch_state_dict)add optionalpytorch_versionto the pytorch_state_dict and torchscript weight formatsmodel RDF 0.4.2Bug fixes:in apytorch_state_dictweight entryarchitectureis no longer optional.collection RDF 0.2.2Non-breaking changesmakeauthors,cite,documentationandtagsoptionalBreaking changes that are fully auto-convertibleSimplifies collection RDF 0.2.1 by merging resource type fields together to acollectionfield,
holindg a list of all resources in the specified collection.(general) RDF 0.2.2 / model RDF 0.3.6 / model RDF 0.4.2Non-breaking changesrdf_sourcenew optional fieldidnew optional fieldcollection RDF 0.2.1First official release, extends general RDF with fieldsapplication,model,dataset,notebookand (nested)collection, which hold lists linking to respective resources.(general) RDF 0.2.1Non-breaking changesadd optionalemailandgithub_userfields to entries inauthorsadd optionalmaintainersfield (entries like inauthorsbutgithub_useris required (andnameis not))model RDF 0.4.1Breaking changes that are fully auto-convertiblemoved fielddependenciestoweights:pytorch_state_dict:dependenciesNon-breaking changesdocumentationfield accepts URLs as wellmodel RDF 0.3.5Non-breaking changesdocumentationfield accepts URLs as wellmodel RDF 0.4.0Breaking changesmodel inputs and outputs may not use duplicated names.model fieldsha256is required ifpytorch_state_dictweights are defined.
and is now moved to thepytroch_state_dictentry asarchitecture_sha256.Breaking changes that are fully auto-convertiblemodel fields language and framework are removed.model fieldsourceis renamedarchitectureand is moved together withkwargsto thepytorch_state_dictweights entry (if it exists, otherwise they are removed).the weight formatpytorch_scriptwas renamed totorchscript.Other changesmodel inputs (like outputs) may be defined byscaleing andoffseting areference_tensoramaintainersfield was added to the model RDF.the entries in theauthorsfield may now additionally containemailorgithub_user.the summary returned by thevalidatecommand now also contains a list of warnings.anupdate_formatcommand was added to aid with updating older RDFs by applying auto-conversion.model RDF 0.3.4Non-breaking changesAdd optional parameterepstoscale_rangepostprocessing.model RDF 0.3.3Breaking changes that are fully auto-convertiblereference_inputfor implicit output tensor shape was renamed toreference_tensormodel RDF 0.3.2Breaking changesThe RDF file name in a package should berdf.yamlfor all the RDF (notmodel.yaml);Changeauthorsandpackaged_byfields from List[str] to List[Author] with Author consisting of a dictionary{name: '<Full name>', affiliation: '<Affiliation>', orcid: 'optional orcid id'};Add a mandatorytypefield to comply with the general RDF. Only valid value is 'model' for model RDF;Only allowlicenseidentifier from theSPDX license list;Other changesAdd optionalversionfield (default 0.1.0) to keep track of model changes;Allow the values in theattachmentslist to be any values besides URI;