Skip to content

spec ¤

bioimageio.spec --- BioImage.IO specifications in Python.

This package provides Pydantic data models for BioImage.IO resource descriptions and tools to work with such descriptions.

The BioImage.IO resource description format is resource type specific (e.g. models, datasets) and versioned. bioimageio.spec defines and validates these specifications and is backwards compatible with previous format versions. It also provides download/upload to/from the BioImage.IO Model Zoo at https://bioimage.io.

Note

For additional tools to work with BioImage.IO resources in Python, consider using the bioimageio.core package.

Modules:

Name Description
application

application resource description format
common

Common nodes and field types of bioimage.io specifications.
conda_env

Representation of conda environment.yaml files for bioimageio specifications.
dataset

dataset resource description format
generic

generic resource description format
model

model resource description format
notebook

notebook resource description format
partner_utils

bioimageio.spec extensions for bioimage.io community partners
summary

Utilities for summarizing and formatting BioImage.IO validation results.
utils

Utility functions for bioimage.io specifications (mostly IO).

Functions:

Name Description
build_description

build a bioimage.io resource description from an RDF's content.
dump_description

Converts a resource to a dictionary containing only simple types that can directly be serialzed to YAML.
get_conda_env

get the recommended Conda environment for a given weights entry description
get_resource_package_content

Get the content of a bioimage.io resource package.
load_dataset_description

same as load_description, but addtionally ensures that the loaded
load_description

load a bioimage.io resource description
load_description_and_validate_format_only

same as load_description, but only return the validation summary.
load_model_description

same as load_description, but addtionally ensures that the loaded
save_bioimageio_package

Package a bioimageio resource as a zip file.
save_bioimageio_package_as_folder

Write the content of a bioimage.io resource package to a folder.
save_bioimageio_package_to_stream

Package a bioimageio resource into a stream.
save_bioimageio_yaml_only

write the metadata of a resource description (rd) to file
update_format

Update a resource description.
update_hashes

Update hash values of the files referenced in source.
upload

Upload a new resource description (version) to the hypha server to be shared at bioimage.io.
validate_format

Validate a dictionary holding a bioimageio description.

Attributes:

Name Type Description
AnyApplicationDescr
AnyDatasetDescr
AnyGenericDescr
AnyModelDescr
AnyNotebookDescr
ApplicationDescr
BioimageioCondaEnv
DatasetDescr
GenericDescr
InvalidDescr
LatestResourceDescr

A resource description following the latest specification format
ModelDescr
NotebookDescr
PRETTY_VALIDATION_ERRORS_IN_IPYNB_ENABLED

Whether pretty validation errors in IPython notebooks were successfully enabled during import.
ResourceDescr

Any of the implemented resource descriptions
SpecificResourceDescr

Any of the implemented, non-generic resource descriptions
ValidationContext
ValidationSummary
__version__
get_validation_context
settings

parsed environment variables for bioimageio.spec

AnyApplicationDescr module-attribute ¤

AnyApplicationDescr = application.AnyApplicationDescr

AnyDatasetDescr module-attribute ¤

AnyDatasetDescr = dataset.AnyDatasetDescr

AnyGenericDescr module-attribute ¤

AnyGenericDescr = generic.AnyGenericDescr

AnyModelDescr module-attribute ¤

AnyModelDescr = model.AnyModelDescr
Referenced by:

AnyNotebookDescr module-attribute ¤

AnyNotebookDescr = notebook.AnyNotebookDescr

ApplicationDescr module-attribute ¤

ApplicationDescr = application.ApplicationDescr

BioimageioCondaEnv module-attribute ¤

BioimageioCondaEnv = conda_env.BioimageioCondaEnv

DatasetDescr module-attribute ¤

DatasetDescr = dataset.DatasetDescr

GenericDescr module-attribute ¤

GenericDescr = generic.GenericDescr
Referenced by:

InvalidDescr module-attribute ¤

InvalidDescr = common_nodes.InvalidDescr
Referenced by:

LatestResourceDescr module-attribute ¤

LatestResourceDescr = Union[
    Annotated[
        Union[
            ApplicationDescr,
            DatasetDescr,
            ModelDescr,
            NotebookDescr,
        ],
        Discriminator("type"),
    ],
    GenericDescr,
]

A resource description following the latest specification format

Referenced by: Returned by:

ModelDescr module-attribute ¤

ModelDescr = model.ModelDescr
Referenced by:

NotebookDescr module-attribute ¤

NotebookDescr = notebook.NotebookDescr

PRETTY_VALIDATION_ERRORS_IN_IPYNB_ENABLED module-attribute ¤

PRETTY_VALIDATION_ERRORS_IN_IPYNB_ENABLED = _enabled

Whether pretty validation errors in IPython notebooks were successfully enabled during import.

ResourceDescr module-attribute ¤

ResourceDescr = Union[
    SpecificResourceDescr, AnyGenericDescr
]

Any of the implemented resource descriptions

Referenced by: Returned by: Used by:

SpecificResourceDescr module-attribute ¤

SpecificResourceDescr = Annotated[
    Union[
        AnyApplicationDescr,
        AnyDatasetDescr,
        AnyModelDescr,
        AnyNotebookDescr,
    ],
    Discriminator("type"),
]

Any of the implemented, non-generic resource descriptions

Used by:

ValidationContext module-attribute ¤

ValidationContext = validation_context.ValidationContext

ValidationSummary module-attribute ¤

ValidationSummary = summary.ValidationSummary

__version__ module-attribute ¤

__version__ = _version.VERSION

get_validation_context module-attribute ¤

get_validation_context = (
    validation_context.get_validation_context
)

settings module-attribute ¤

settings = Settings()

parsed environment variables for bioimageio.spec

Referenced by:

build_description ¤

build_description(
    content: BioimageioYamlContentView,
    /,
    *,
    context: Optional[ValidationContext] = None,
    format_version: Literal["latest"],
) -> Union[LatestResourceDescr, InvalidDescr]

build_description(
    content: BioimageioYamlContentView,
    /,
    *,
    context: Optional[ValidationContext] = None,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
) -> Union[ResourceDescr, InvalidDescr]

build_description(
    content: BioimageioYamlContentView,
    /,
    *,
    context: Optional[ValidationContext] = None,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
) -> Union[ResourceDescr, InvalidDescr]

build a bioimage.io resource description from an RDF's content.

Use load_description if you want to build a resource description from an rdf.yaml or bioimage.io zip-package.

Parameters:

Name Type Description Default

content ¤

 BioimageioYamlContentView

loaded rdf.yaml file (loaded with YAML, not bioimageio.spec)

 required

context ¤

 Optional[ValidationContext]

validation context to use during validation

 None

format_version ¤

 Union[FormatVersionPlaceholder, str]

(optional) use this argument to load the resource and convert its metadata to a higher format_version. Note: - Use "latest" to convert to the latest available format version. - Use "discover" to use the format version specified in the RDF. - Only considers major.minor format version, ignores patch version. - Conversion to lower format versions is not supported.

 DISCOVER

Returns:

Type Description
Union[ResourceDescr, InvalidDescr]

An object holding all metadata of the bioimage.io resource
Source code in src/bioimageio/spec/_description.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
def build_description(
    content: BioimageioYamlContentView,
    /,
    *,
    context: Optional[ValidationContext] = None,
    format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
) -> Union[ResourceDescr, InvalidDescr]:
    """build a bioimage.io resource description from an RDF's content.

    Use `load_description` if you want to build a resource description from an rdf.yaml
    or bioimage.io zip-package.

    Args:
        content: loaded rdf.yaml file (loaded with YAML, not bioimageio.spec)
        context: validation context to use during validation
        format_version:
            (optional) use this argument to load the resource and
            convert its metadata to a higher format_version.
            Note:
            - Use "latest" to convert to the latest available format version.
            - Use "discover" to use the format version specified in the RDF.
            - Only considers major.minor format version, ignores patch version.
            - Conversion to lower format versions is not supported.

    Returns:
        An object holding all metadata of the bioimage.io resource

    """

    return build_description_impl(
        content,
        context=context,
        format_version=format_version,
        get_rd_class=_get_rd_class,
    )

dump_description ¤

dump_description(
    rd: Union[ResourceDescr, InvalidDescr],
    /,
    *,
    exclude_unset: bool = True,
    exclude_defaults: bool = False,
) -> BioimageioYamlContent

Converts a resource to a dictionary containing only simple types that can directly be serialzed to YAML.

Parameters:

Name Type Description Default

rd ¤

 Union[ResourceDescr, InvalidDescr]

bioimageio resource description

 required

exclude_unset ¤

 bool

Exclude fields that have not explicitly be set.

 True

exclude_defaults ¤

 bool

Exclude fields that have the default value (even if set explicitly).

 False
Source code in src/bioimageio/spec/_description.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def dump_description(
    rd: Union[ResourceDescr, InvalidDescr],
    /,
    *,
    exclude_unset: bool = True,
    exclude_defaults: bool = False,
) -> BioimageioYamlContent:
    """Converts a resource to a dictionary containing only simple types that can directly be serialzed to YAML.

    Args:
        rd: bioimageio resource description
        exclude_unset: Exclude fields that have not explicitly be set.
        exclude_defaults: Exclude fields that have the default value (even if set explicitly).
    """
    return rd.model_dump(
        mode="json", exclude_unset=exclude_unset, exclude_defaults=exclude_defaults
    )

get_conda_env ¤

get_conda_env(
    *,
    entry: SupportedWeightsEntry,
    env_name: Optional[Union[Literal["DROP"], str]] = None,
) -> BioimageioCondaEnv

get the recommended Conda environment for a given weights entry description

Source code in src/bioimageio/spec/_get_conda_env.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def get_conda_env(
    *,
    entry: SupportedWeightsEntry,
    env_name: Optional[Union[Literal["DROP"], str]] = None,
) -> BioimageioCondaEnv:
    """get the recommended Conda environment for a given weights entry description"""
    if isinstance(entry, (v0_4.OnnxWeightsDescr, v0_5.OnnxWeightsDescr)):
        conda_env = _get_default_onnx_env(opset_version=entry.opset_version)
    elif isinstance(
        entry,
        (
            v0_4.PytorchStateDictWeightsDescr,
            v0_5.PytorchStateDictWeightsDescr,
            v0_4.TorchscriptWeightsDescr,
            v0_5.TorchscriptWeightsDescr,
        ),
    ):
        if (
            isinstance(entry, v0_5.TorchscriptWeightsDescr)
            or entry.dependencies is None
        ):
            conda_env = _get_default_pytorch_env(pytorch_version=entry.pytorch_version)
        else:
            conda_env = _get_env_from_deps(entry.dependencies)

    elif isinstance(
        entry,
        (
            v0_4.TensorflowSavedModelBundleWeightsDescr,
            v0_5.TensorflowSavedModelBundleWeightsDescr,
        ),
    ):
        if entry.dependencies is None:
            conda_env = _get_default_tf_env(tensorflow_version=entry.tensorflow_version)
        else:
            conda_env = _get_env_from_deps(entry.dependencies)
    elif isinstance(
        entry,
        (v0_4.KerasHdf5WeightsDescr, v0_5.KerasHdf5WeightsDescr),
    ):
        conda_env = _get_default_tf_env(tensorflow_version=entry.tensorflow_version)
    else:
        assert_never(entry)

    if env_name == "DROP":
        conda_env.name = None
    elif env_name is not None:
        conda_env.name = env_name

    return conda_env

get_resource_package_content ¤

get_resource_package_content(
    rd: ResourceDescr,
    /,
    *,
    bioimageio_yaml_file_name: FileName = BIOIMAGEIO_YAML,
    weights_priority_order: Optional[
        Sequence[WeightsFormat]
    ] = None,
) -> Dict[
    FileName,
    Union[
        HttpUrl,
        AbsoluteFilePath,
        BioimageioYamlContent,
        ZipPath,
    ],
]

Get the content of a bioimage.io resource package.

Source code in src/bioimageio/spec/_package.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def get_resource_package_content(
    rd: ResourceDescr,
    /,
    *,
    bioimageio_yaml_file_name: FileName = BIOIMAGEIO_YAML,
    weights_priority_order: Optional[Sequence[WeightsFormat]] = None,  # model only
) -> Dict[FileName, Union[HttpUrl, AbsoluteFilePath, BioimageioYamlContent, ZipPath]]:
    """Get the content of a bioimage.io resource package."""
    ret: Dict[
        FileName, Union[HttpUrl, AbsoluteFilePath, BioimageioYamlContent, ZipPath]
    ] = {}
    for k, v in get_package_content(
        rd,
        bioimageio_yaml_file_name=bioimageio_yaml_file_name,
        weights_priority_order=weights_priority_order,
    ).items():
        if isinstance(v, FileDescr):
            if isinstance(v.source, (Path, RelativeFilePath)):
                ret[k] = v.source.absolute()
            else:
                ret[k] = v.source

        else:
            ret[k] = v

    return ret

load_dataset_description ¤

load_dataset_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Literal["latest"],
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> DatasetDescr

load_dataset_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> AnyDatasetDescr

load_dataset_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> AnyDatasetDescr

same as load_description, but addtionally ensures that the loaded description is valid and of type 'dataset'.

Referenced by:
Source code in src/bioimageio/spec/_io.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
def load_dataset_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[Dict[str, Optional[Sha256]]] = None,
    sha256: Optional[Sha256] = None,
) -> AnyDatasetDescr:
    """same as `load_description`, but addtionally ensures that the loaded
    description is valid and of type 'dataset'.
    """
    rd = load_description(
        source,
        format_version=format_version,
        perform_io_checks=perform_io_checks,
        known_files=known_files,
        sha256=sha256,
    )
    return ensure_description_is_dataset(rd)

load_description ¤

load_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Literal["latest"],
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> Union[LatestResourceDescr, InvalidDescr]

load_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> Union[ResourceDescr, InvalidDescr]

load_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> Union[ResourceDescr, InvalidDescr]

load a bioimage.io resource description

Parameters:

Name Type Description Default

source ¤

 Union[PermissiveFileSource, ZipFile]

Path or URL to an rdf.yaml or a bioimage.io package (zip-file with rdf.yaml in it).

 required

format_version ¤

 Union[FormatVersionPlaceholder, str]

(optional) Use this argument to load the resource and convert its metadata to a higher format_version. Note: - Use "latest" to convert to the latest available format version. - Use "discover" to use the format version specified in the RDF. - Only considers major.minor format version, ignores patch version. - Conversion to lower format versions is not supported.

 DISCOVER

perform_io_checks ¤

 Optional[bool]

Wether or not to perform validation that requires file io, e.g. downloading a remote files. The existence of local absolute file paths is still being checked.

 None

known_files ¤

 Optional[Dict[str, Optional[Sha256]]]

Allows to bypass download and hashing of referenced files (even if perform_io_checks is True). Checked files will be added to this dictionary with their SHA-256 value.

 None

sha256 ¤

 Optional[Sha256]

Optional SHA-256 value of source

 None

Returns:

Type Description
Union[ResourceDescr, InvalidDescr]

An object holding all metadata of the bioimage.io resource
Referenced by:
Source code in src/bioimageio/spec/_io.py 
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def load_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[Dict[str, Optional[Sha256]]] = None,
    sha256: Optional[Sha256] = None,
) -> Union[ResourceDescr, InvalidDescr]:
    """load a bioimage.io resource description

    Args:
        source:
            Path or URL to an rdf.yaml or a bioimage.io package
            (zip-file with rdf.yaml in it).
        format_version:
            (optional) Use this argument to load the resource and
            convert its metadata to a higher format_version.
            Note:
            - Use "latest" to convert to the latest available format version.
            - Use "discover" to use the format version specified in the RDF.
            - Only considers major.minor format version, ignores patch version.
            - Conversion to lower format versions is not supported.
        perform_io_checks:
            Wether or not to perform validation that requires file io,
            e.g. downloading a remote files. The existence of local
            absolute file paths is still being checked.
        known_files:
            Allows to bypass download and hashing of referenced files
            (even if perform_io_checks is True).
            Checked files will be added to this dictionary
            with their SHA-256 value.
        sha256:
            Optional SHA-256 value of **source**

    Returns:
        An object holding all metadata of the bioimage.io resource

    """
    if isinstance(source, ResourceDescrBase):
        name = getattr(source, "name", f"{str(source)[:10]}...")
        logger.warning("returning already loaded description '{}' as is", name)
        return source  # pyright: ignore[reportReturnType]

    opened = open_bioimageio_yaml(source, sha256=sha256)

    context = get_validation_context().replace(
        root=opened.original_root,
        file_name=opened.original_file_name,
        original_source_name=opened.original_source_name,
        perform_io_checks=perform_io_checks,
        known_files=known_files,
    )

    return build_description(
        opened.content,
        context=context,
        format_version=format_version,
    )

load_description_and_validate_format_only ¤

load_description_and_validate_format_only(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> ValidationSummary

same as load_description, but only return the validation summary.

Returns:

Type Description
ValidationSummary

Validation summary of the bioimage.io resource found at source.
Source code in src/bioimageio/spec/_io.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
def load_description_and_validate_format_only(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[Dict[str, Optional[Sha256]]] = None,
    sha256: Optional[Sha256] = None,
) -> ValidationSummary:
    """same as `load_description`, but only return the validation summary.

    Returns:
        Validation summary of the bioimage.io resource found at `source`.

    """
    rd = load_description(
        source,
        format_version=format_version,
        perform_io_checks=perform_io_checks,
        known_files=known_files,
        sha256=sha256,
    )
    assert rd.validation_summary is not None
    return rd.validation_summary

load_model_description ¤

load_model_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Literal["latest"],
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> ModelDescr

load_model_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> AnyModelDescr

load_model_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[
        FormatVersionPlaceholder, str
    ] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[
        Dict[str, Optional[Sha256]]
    ] = None,
    sha256: Optional[Sha256] = None,
) -> AnyModelDescr

same as load_description, but addtionally ensures that the loaded description is valid and of type 'model'.

Raises:

Type Description
ValueError

for invalid or non-model resources
Referenced by:
Source code in src/bioimageio/spec/_io.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def load_model_description(
    source: Union[PermissiveFileSource, ZipFile],
    /,
    *,
    format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
    perform_io_checks: Optional[bool] = None,
    known_files: Optional[Dict[str, Optional[Sha256]]] = None,
    sha256: Optional[Sha256] = None,
) -> AnyModelDescr:
    """same as `load_description`, but addtionally ensures that the loaded
    description is valid and of type 'model'.

    Raises:
        ValueError: for invalid or non-model resources
    """
    rd = load_description(
        source,
        format_version=format_version,
        perform_io_checks=perform_io_checks,
        known_files=known_files,
        sha256=sha256,
    )
    return ensure_description_is_model(rd)

save_bioimageio_package ¤

save_bioimageio_package(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    compression: int = ZIP_DEFLATED,
    compression_level: int = 1,
    output_path: Union[NewPath, FilePath, None] = None,
    weights_priority_order: Optional[
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
    allow_invalid: bool = False,
) -> FilePath

Package a bioimageio resource as a zip file.

Parameters:

Name Type Description Default

source ¤

 Union[BioimageioYamlSource, ResourceDescr]

bioimageio resource description

 required

compression ¤

 int

The numeric constant of compression method.

 ZIP_DEFLATED

compression_level ¤

 int

Compression level to use when writing files to the archive. See https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile

 1

output_path ¤

 Union[NewPath, FilePath, None]

file path to write package to

 None

weights_priority_order ¤

 Optional[Sequence[Literal['keras_hdf5', 'onnx', 'pytorch_state_dict', 'tensorflow_js', 'tensorflow_saved_model_bundle', 'torchscript']]]

If given only the first weights format present in the model is included. If none of the prioritized weights formats is found all are included.

 None

Returns:

Type Description
FilePath

path to zipped bioimageio package
Referenced by:
Source code in src/bioimageio/spec/_package.py 
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
def save_bioimageio_package(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    compression: int = ZIP_DEFLATED,
    compression_level: int = 1,
    output_path: Union[NewPath, FilePath, None] = None,
    weights_priority_order: Optional[  # model only
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
    allow_invalid: bool = False,
) -> FilePath:
    """Package a bioimageio resource as a zip file.

    Args:
        source: bioimageio resource description
        compression: The numeric constant of compression method.
        compression_level: Compression level to use when writing files to the archive.
                           See https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile
        output_path: file path to write package to
        weights_priority_order: If given only the first weights format present in the model is included.
                                If none of the prioritized weights formats is found all are included.

    Returns:
        path to zipped bioimageio package
    """
    package_content = _prepare_resource_package(
        source,
        weights_priority_order=weights_priority_order,
    )
    if output_path is None:
        output_path = Path(
            NamedTemporaryFile(suffix=".bioimageio.zip", delete=False).name
        )
    else:
        output_path = Path(output_path)

    write_zip(
        output_path,
        package_content,
        compression=compression,
        compression_level=compression_level,
    )
    with get_validation_context().replace(warning_level=ERROR):
        if isinstance((exported := load_description(output_path)), InvalidDescr):
            exported.validation_summary.display()
            msg = f"Exported package at '{output_path}' is invalid."
            if allow_invalid:
                logger.error(msg)
            else:
                raise ValueError(msg)

    return output_path

save_bioimageio_package_as_folder ¤

save_bioimageio_package_as_folder(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    output_path: Union[NewPath, DirectoryPath, None] = None,
    weights_priority_order: Optional[
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
) -> DirectoryPath

Write the content of a bioimage.io resource package to a folder.

Parameters:

Name Type Description Default

source ¤

 Union[BioimageioYamlSource, ResourceDescr]

bioimageio resource description

 required

output_path ¤

 Union[NewPath, DirectoryPath, None]

file path to write package to

 None

weights_priority_order ¤

 Optional[Sequence[Literal['keras_hdf5', 'onnx', 'pytorch_state_dict', 'tensorflow_js', 'tensorflow_saved_model_bundle', 'torchscript']]]

If given only the first weights format present in the model is included. If none of the prioritized weights formats is found all are included.

 None

Returns:

Type Description
DirectoryPath

directory path to bioimageio package folder
Referenced by:
Source code in src/bioimageio/spec/_package.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
def save_bioimageio_package_as_folder(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    output_path: Union[NewPath, DirectoryPath, None] = None,
    weights_priority_order: Optional[  # model only
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
) -> DirectoryPath:
    """Write the content of a bioimage.io resource package to a folder.

    Args:
        source: bioimageio resource description
        output_path: file path to write package to
        weights_priority_order: If given only the first weights format present in the model is included.
                                If none of the prioritized weights formats is found all are included.

    Returns:
        directory path to bioimageio package folder
    """
    package_content = _prepare_resource_package(
        source,
        weights_priority_order=weights_priority_order,
    )
    if output_path is None:
        output_path = Path(mkdtemp())
    else:
        output_path = Path(output_path)

    output_path.mkdir(exist_ok=True, parents=True)
    for name, src in package_content.items():
        if not name:
            raise ValueError("got empty file name in package content")

        if isinstance(src, collections.abc.Mapping):
            write_yaml(src, output_path / name)
        elif (
            isinstance(src.original_root, Path)
            and src.original_root / src.original_file_name
            == (output_path / name).resolve()
        ):
            logger.debug(
                f"Not copying {src.original_root / src.original_file_name} to itself."
            )
        else:
            if isinstance(src.original_root, Path):
                logger.debug(
                    f"Copying from path {src.original_root / src.original_file_name} to {output_path / name}."
                )
            else:
                logger.debug(
                    f"Copying {src.original_root}/{src.original_file_name} to {output_path / name}."
                )
            with (output_path / name).open("wb") as dest:
                _ = shutil.copyfileobj(src, dest)

    return output_path

save_bioimageio_package_to_stream ¤

save_bioimageio_package_to_stream(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    compression: int = ZIP_DEFLATED,
    compression_level: int = 1,
    output_stream: Union[IO[bytes], None] = None,
    weights_priority_order: Optional[
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
) -> IO[bytes]

Package a bioimageio resource into a stream.

Parameters:

Name Type Description Default

source ¤

 Union[BioimageioYamlSource, ResourceDescr]

bioimageio resource description

 required

compression ¤

 int

The numeric constant of compression method.

 ZIP_DEFLATED

compression_level ¤

 int

Compression level to use when writing files to the archive. See https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile

 1

output_stream ¤

 Union[IO[bytes], None]

stream to write package to

 None

weights_priority_order ¤

 Optional[Sequence[Literal['keras_hdf5', 'onnx', 'pytorch_state_dict', 'tensorflow_js', 'tensorflow_saved_model_bundle', 'torchscript']]]

If given only the first weights format present in the model is included. If none of the prioritized weights formats is found all are included.

 None

Note: this function bypasses safety checks and does not load/validate the model after writing.

Returns:

Type Description
IO[bytes]

stream of zipped bioimageio package
Referenced by:
Source code in src/bioimageio/spec/_package.py 
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
def save_bioimageio_package_to_stream(
    source: Union[BioimageioYamlSource, ResourceDescr],
    /,
    *,
    compression: int = ZIP_DEFLATED,
    compression_level: int = 1,
    output_stream: Union[IO[bytes], None] = None,
    weights_priority_order: Optional[  # model only
        Sequence[
            Literal[
                "keras_hdf5",
                "onnx",
                "pytorch_state_dict",
                "tensorflow_js",
                "tensorflow_saved_model_bundle",
                "torchscript",
            ]
        ]
    ] = None,
) -> IO[bytes]:
    """Package a bioimageio resource into a stream.

    Args:
        source: bioimageio resource description
        compression: The numeric constant of compression method.
        compression_level: Compression level to use when writing files to the archive.
                           See https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile
        output_stream: stream to write package to
        weights_priority_order: If given only the first weights format present in the model is included.
                                If none of the prioritized weights formats is found all are included.

    Note: this function bypasses safety checks and does not load/validate the model after writing.

    Returns:
        stream of zipped bioimageio package
    """
    if output_stream is None:
        output_stream = BytesIO()

    package_content = _prepare_resource_package(
        source,
        weights_priority_order=weights_priority_order,
    )

    write_zip(
        output_stream,
        package_content,
        compression=compression,
        compression_level=compression_level,
    )

    return output_stream

save_bioimageio_yaml_only ¤

save_bioimageio_yaml_only(
    rd: Union[
        ResourceDescr, BioimageioYamlContent, InvalidDescr
    ],
    /,
    file: Union[NewPath, FilePath, TextIO],
    *,
    exclude_unset: bool = True,
    exclude_defaults: bool = False,
)

write the metadata of a resource description (rd) to file without writing any of the referenced files in it.

Parameters:

Name Type Description Default

rd ¤

 Union[ResourceDescr, BioimageioYamlContent, InvalidDescr]

bioimageio resource description

 required

file ¤

 Union[NewPath, FilePath, TextIO]

file or stream to save to

 required

exclude_unset ¤

 bool

Exclude fields that have not explicitly be set.

 True

exclude_defaults ¤

 bool

Exclude fields that have the default value (even if set explicitly).

 False

Note: To save a resource description with its associated files as a package, use save_bioimageio_package or save_bioimageio_package_as_folder.

Referenced by:
Source code in src/bioimageio/spec/_io.py 
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def save_bioimageio_yaml_only(
    rd: Union[ResourceDescr, BioimageioYamlContent, InvalidDescr],
    /,
    file: Union[NewPath, FilePath, TextIO],
    *,
    exclude_unset: bool = True,
    exclude_defaults: bool = False,
):
    """write the metadata of a resource description (`rd`) to `file`
    without writing any of the referenced files in it.

    Args:
        rd: bioimageio resource description
        file: file or stream to save to
        exclude_unset: Exclude fields that have not explicitly be set.
        exclude_defaults: Exclude fields that have the default value (even if set explicitly).

    Note: To save a resource description with its associated files as a package,
    use `save_bioimageio_package` or `save_bioimageio_package_as_folder`.
    """
    if isinstance(rd, ResourceDescrBase):
        content = dump_description(
            rd, exclude_unset=exclude_unset, exclude_defaults=exclude_defaults
        )
    else:
        content = rd

    write_yaml(cast(YamlValue, content), file)

update_format ¤

update_format(
    source: Union[
        ResourceDescr,
        PermissiveFileSource,
        ZipFile,
        BioimageioYamlContent,
        InvalidDescr,
    ],
    /,
    *,
    output: Union[Path, TextIO, None] = None,
    exclude_defaults: bool = True,
    perform_io_checks: Optional[bool] = None,
) -> Union[LatestResourceDescr, InvalidDescr]

Update a resource description.

Notes: - Invalid source descriptions may fail to update. - The updated description might be invalid (even if the source was valid).

Source code in src/bioimageio/spec/_io.py 
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
def update_format(
    source: Union[
        ResourceDescr,
        PermissiveFileSource,
        ZipFile,
        BioimageioYamlContent,
        InvalidDescr,
    ],
    /,
    *,
    output: Union[Path, TextIO, None] = None,
    exclude_defaults: bool = True,
    perform_io_checks: Optional[bool] = None,
) -> Union[LatestResourceDescr, InvalidDescr]:
    """Update a resource description.

    Notes:
    - Invalid **source** descriptions may fail to update.
    - The updated description might be invalid (even if the **source** was valid).
    """

    if isinstance(source, ResourceDescrBase):
        root = source.root
        source = dump_description(source)
    else:
        root = None

    if isinstance(source, collections.abc.Mapping):
        descr = build_description(
            source,
            context=get_validation_context().replace(
                root=root, perform_io_checks=perform_io_checks
            ),
            format_version=LATEST,
        )

    else:
        descr = load_description(
            source,
            perform_io_checks=perform_io_checks,
            format_version=LATEST,
        )

    if output is not None:
        save_bioimageio_yaml_only(descr, file=output, exclude_defaults=exclude_defaults)

    return descr

update_hashes ¤

update_hashes(
    source: Union[
        PermissiveFileSource,
        ZipFile,
        ResourceDescr,
        BioimageioYamlContent,
    ],
) -> Union[ResourceDescr, InvalidDescr]

Update hash values of the files referenced in source.

Source code in src/bioimageio/spec/_io.py 
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
def update_hashes(
    source: Union[PermissiveFileSource, ZipFile, ResourceDescr, BioimageioYamlContent],
    /,
) -> Union[ResourceDescr, InvalidDescr]:
    """Update hash values of the files referenced in **source**."""
    if isinstance(source, ResourceDescrBase):
        root = source.root
        source = dump_description(source)
    else:
        root = None

    context = get_validation_context().replace(
        update_hashes=True, root=root, perform_io_checks=True
    )
    with context:
        if isinstance(source, collections.abc.Mapping):
            return build_description(source)
        else:
            return load_description(source, perform_io_checks=True)

upload ¤

upload(
    source: Union[
        PermissiveFileSource,
        ZipFile,
        ResourceDescr,
        BioimageioYamlContent,
    ],
) -> HttpUrl

Upload a new resource description (version) to the hypha server to be shared at bioimage.io. To edit an existing resource version, please login to https://bioimage.io and use the web interface.

Warning

This upload function is in alpha stage and might change in the future.

Parameters:

Name Type Description Default

source ¤

 Union[PermissiveFileSource, ZipFile, ResourceDescr, BioimageioYamlContent]

The resource description to upload.

 required

Returns:

Type Description
HttpUrl

A URL to the uploaded resource description. Note: It might take some time until the resource is processed and available for download from the returned URL.
Source code in src/bioimageio/spec/_upload.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
def upload(
    source: Union[PermissiveFileSource, ZipFile, ResourceDescr, BioimageioYamlContent],
    /,
) -> HttpUrl:
    """Upload a new resource description (version) to the hypha server to be shared at bioimage.io.
    To edit an existing resource **version**, please login to https://bioimage.io and use the web interface.

    WARNING: This upload function is in alpha stage and might change in the future.

    Args:
        source: The resource description to upload.

    Returns:
        A URL to the uploaded resource description.
        Note: It might take some time until the resource is processed and available for download from the returned URL.
    """

    if settings.hypha_upload_token is None:
        raise ValueError(
            """
Upload token is not set. Please set BIOIMAGEIO_HYPHA_UPLOAD_TOKEN in your environment variables.
By setting this token you agree to our terms of service at https://bioimage.io/#/toc.

How to obtain a token:
    1. Login to https://bioimage.io
    2. Generate a new token at https://bioimage.io/#/api?tab=hypha-rpc
"""
        )

    if isinstance(source, ResourceDescrBase):
        # If source is already a ResourceDescr, we can use it directly
        descr = source
    elif isinstance(source, dict):
        descr = build_description(source)
    else:
        descr = load_description(source)

    if isinstance(descr, InvalidDescr):
        raise ValueError("Uploading invalid resource descriptions is not allowed.")

    if descr.type != "model":
        raise NotImplementedError(
            f"For now, only model resources can be uploaded (got type={descr.type})."
        )

    if descr.id is not None:
        raise ValueError(
            "You cannot upload a resource with an id. Please remove the id from the description and make sure to upload a new non-existing resource. To edit an existing resource, please use the web interface at https://bioimage.io."
        )

    content = get_resource_package_content(descr)

    metadata = content[BIOIMAGEIO_YAML]
    assert isinstance(metadata, dict)
    manifest = dict(metadata)

    # only admins can upload a resource with a version
    artifact_version = "stage"  # if descr.version is None else str(descr.version)

    # Create new model
    r = httpx.post(
        settings.hypha_upload,
        json={
            "parent_id": "bioimage-io/bioimage.io",
            "alias": (
                descr.id or "{animal_adjective}-{animal}"
            ),  # TODO: adapt for non-model uploads,
            "type": descr.type,
            "manifest": manifest,
            "version": artifact_version,
        },
        headers=(
            headers := {
                "Authorization": f"Bearer {settings.hypha_upload_token}",
                "Content-Type": "application/json",
            }
        ),
    )

    response = r.json()
    artifact_id = response.get("id")
    if artifact_id is None:
        try:
            logger.error("Response detail: {}", "".join(response["detail"]))
        except Exception:
            logger.error("Response: {}", response)

        raise RuntimeError(f"Upload did not return resource id: {response}")
    else:
        logger.info("Uploaded resource description {}", artifact_id)

    for file_name, file_source in content.items():
        # Get upload URL for a file
        response = httpx.post(
            settings.hypha_upload.replace("/create", "/put_file"),
            json={
                "artifact_id": artifact_id,
                "file_path": file_name,
            },
            headers=headers,
            follow_redirects=True,
        )
        upload_url = response.raise_for_status().json()

        # Upload file to the provided URL
        if isinstance(file_source, collections.abc.Mapping):
            buf = io.BytesIO()
            write_yaml(file_source, buf)
            files = {file_name: buf}
        else:
            files = {file_name: get_reader(file_source)}

        response = httpx.put(
            upload_url,
            files=files,  # pyright: ignore[reportArgumentType]
            # TODO: follow up on https://github.com/encode/httpx/discussions/3611
            headers={"Content-Type": ""},  # Important for S3 uploads
            follow_redirects=True,
        )
        logger.info("Uploaded '{}' successfully", file_name)

    # Update model status
    manifest["status"] = "request-review"
    response = httpx.post(
        settings.hypha_upload.replace("/create", "/edit"),
        json={
            "artifact_id": artifact_id,
            "version": artifact_version,
            "manifest": manifest,
        },
        headers=headers,
        follow_redirects=True,
    )
    logger.info(
        "Updated status of {}/{} to 'request-review'", artifact_id, artifact_version
    )
    logger.warning(
        "Upload successfull. Please note that the uploaded resource might not be available for download immediately."
    )
    with get_validation_context().replace(perform_io_checks=False):
        return HttpUrl(
            f"https://hypha.aicell.io/bioimage-io/artifacts/{artifact_id}/files/rdf.yaml?version={artifact_version}"
        )

validate_format ¤

validate_format(
    data: BioimageioYamlContent,
    /,
    *,
    format_version: Union[
        Literal["discover", "latest"], str
    ] = DISCOVER,
    context: Optional[ValidationContext] = None,
) -> ValidationSummary

Validate a dictionary holding a bioimageio description. See bioimagieo.spec.load_description_and_validate_format_only to validate a file source.

Parameters:

Name Type Description Default

data ¤

 BioimageioYamlContent

Dictionary holding the raw bioimageio.yaml content.

 required

format_version ¤

 Union[Literal['discover', 'latest'], str]

Format version to (update to and) use for validation. Note: - Use "latest" to convert to the latest available format version. - Use "discover" to use the format version specified in the RDF. - Only considers major.minor format version, ignores patch version. - Conversion to lower format versions is not supported.

 DISCOVER

context ¤

 Optional[ValidationContext]

Validation context, see bioimagieo.spec.ValidationContext

 None
Note

Use bioimagieo.spec.load_description_and_validate_format_only to validate a file source instead of loading the YAML content and creating the appropriate ValidationContext.

Alternatively you can use bioimagieo.spec.load_description and access the validation_summary attribute of the returned object.

Source code in src/bioimageio/spec/_description.py 
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
def validate_format(
    data: BioimageioYamlContent,
    /,
    *,
    format_version: Union[Literal["discover", "latest"], str] = DISCOVER,
    context: Optional[ValidationContext] = None,
) -> ValidationSummary:
    """Validate a dictionary holding a bioimageio description.
    See `bioimagieo.spec.load_description_and_validate_format_only`
    to validate a file source.

    Args:
        data: Dictionary holding the raw bioimageio.yaml content.
        format_version:
            Format version to (update to and) use for validation.
            Note:
            - Use "latest" to convert to the latest available format version.
            - Use "discover" to use the format version specified in the RDF.
            - Only considers major.minor format version, ignores patch version.
            - Conversion to lower format versions is not supported.
        context: Validation context, see `bioimagieo.spec.ValidationContext`

    Note:
        Use `bioimagieo.spec.load_description_and_validate_format_only` to validate a
        file source instead of loading the YAML content and creating the appropriate
        `ValidationContext`.

        Alternatively you can use `bioimagieo.spec.load_description` and access the
        `validation_summary` attribute of the returned object.
    """
    with context or get_validation_context():
        rd = build_description(data, format_version=format_version)

    assert rd.validation_summary is not None
    return rd.validation_summary