bioimage.io规范

此存储库包含由bioimage.io社区定义的标准格式规范，用于bioimage.io网站上的内容（即模型、数据集和应用）。内容中的每个项目都始终使用名为rdf.yaml或bioimageio.yaml的YAML 1.2文件进行描述。此rdf.yaml \ bioimageio.yaml以及其中引用的文件可以从bioimage.io网站下载或上传，并由bioimage.io兼容的消费者（例如，ilastik之类的图像分析软件）生成或消费。

这些是bioimage.io兼容资源必须满足的规则和格式。

注意，Python包PyYAML不支持YAML 1.2。因此，我们使用并推荐ruyaml。有关差异，请参阅https://ruamelyaml.readthedocs.io/en/latest/pyyaml。

请注意，检查您的rdf.yaml文件是否遵守bioimage.io规范的最佳方法是调用bioimageio.core Python包中的bioimageio.core.validate。该bioimageio.core Python包还提供了带有validate命令的bioimageio命令行界面（CLI）。

bioimageio validate path/to/your/rdf.yaml

格式版本概述

所有bioimage.io描述格式都定义为Pydantic模型。

JSON 架构

简化描述可用作 JSON 架构

这些主要用于语法高亮和表单生成。

示例

我们提供了一些示例，说明如何使用 rdf.yaml 文件来描述模型、应用程序、笔记本和数据集，以及一个示例笔记本，用于以编程方式访问模型、应用程序、笔记本和数据集的描述。

💁 建议

• 由于存储服务（如 Zenodo）的限制，它不支持子文件夹，建议将其他文件放置在与 rdf.yaml 文件相同级别的目录中，并尽量不使用子目录。
• 使用bioimageio.core Python 包验证您的 rdf.yaml 文件。
• bioimageio.spec 不断演进。请尝试使用并升级到最新格式版本！

⌨ bioimageio 命令行界面 (CLI)

bioimageio CLI 已完全迁移到 bioimageio.core。

🖥 安装

bioimageio.spec 可以使用 conda 或 pip 进行安装。我们建议安装 bioimageio.core 以获取 BioImage.IO 社区中可用的 Python 程序性功能。

conda install -c conda-forge bioimageio.core

或

pip install -U bioimageio.core

仍然，对于更轻的包或仅测试，您也可以单独安装 bioimageio.spec 包。

conda install -c conda-forge bioimageio.spec

或

pip install -U bioimageio.spec

🏞 环境变量

TODO：链接到开发文档中的设置

🤝 如何贡献

♥ 贡献者

由 contrib.rocks 制作。

🛈 版本控制方案

为了使 bioimageio.spec Python 包的版本与（模型）描述格式版本保持同步，bioimageio.spec 的版本格式为 MAJOR.MINOR.PATCH.LIB，其中 MAJOR.MINOR.PATCH 对应于最新实现的模型描述格式版本，LIB 可用于不影响格式版本的库更改。 此更改是在 bioimageio.spec 0.5.3.1 中引入的。

Δ 更新日志

bioimageio.spec Python 包

bioimageio.spec 0.5.3.2

• 错误修复 "当根目录更改时重置已知文件" (#619)

bioimageio.spec 0.5.3.1

注意：版本控制方案已更改，因为我们的先前 post 发布包含超出 post 发布应包含的内容的改变（仅更改文档字符串等）。这源于希望保持库版本与（模型）格式版本同步，以避免混淆。为了保持这种关系，但避免过度的 post 发布，现在将库版本号添加为第四部分 MAJOR.MINOR.PATCH.LIB_VERSION。

• 添加 load_model_description 和 load_dataset_description
• 添加 ensure_description_is_model 和 ensure_description_is_dataset
• 将 ValidationContext 中的 perform_io_checks 和 known_files 暴露给 load_description 和 load_description_and_validate_format_only

bioimageio.spec 0.5.3post4

• 修复 pydantic 的 pinning

bioimageio.spec 0.5.3post3

• 更新解析 bioimage.io 资源 ID

bioimageio.spec 0.5.3post2

• 修复从 bioimage.io 集合解析非最新 RDF 版本时的 SHA-256 值

bioimageio.spec 0.5.3post1

• 在加载 0.5.x 模型时提高补丁版本
• 改进验证错误格式化
• 首先使用 head 请求验证 URL，如果被禁止，随后使用流式传输的 get 请求，如果这也被禁止，则使用常规 get 请求。
• RelativePath.absolute() 现在是一个方法（而不是属性），类似于 pathlib.Path

bioimageio.spec 0.5.3

• 删除集合描述
• 更新 SPDX 许可列表
• 更新通用描述到 0.3.1
• 更新模型描述为0.5.3
• 将超时参数添加到所有requests.get调用中

bioimageio.spec 0.5.2post5

• 在验证总结中添加更多信息
• 在FileSource联合体中降级Path对象

bioimageio.spec 0.5.2post4

• 解决备份DOI
• 修复解析作为字符串提供的相对文件路径
• 允许绕过已知文件的下载和哈希处理

bioimageio.spec 0.5.2post3

• 在验证URL时避免完整下载

bioimageio.spec 0.5.2post2

• 解析版本（未）特定的集合ID，例如load_description('affable-shark')，load_description('affable-shark/1')

bioimageio.spec 0.5.2post1

• 修复具有权重格式优先级的模型打包问题

bioimageio.spec 0.5.2

• 新补丁版本模型0.5.2

bioimageio.spec 0.5.1

• 新补丁版本模型0.5.1

bioimageio.spec 0.5.0post2

• 如果CI环境变量是一个字符串则不失败

bioimageio.spec 0.5.0post1

• 修复_internal.io_utils.identify_bioimageio_yaml_file()

bioimageio.spec 0.5.0

• 新描述格式：通用 0.3、应用 0.3、集合 0.3、数据集 0.3、笔记本 0.3和模型 0.5。
• 各种API更改，最重要的函数
  • bioimageio.spec.load_description（替换load_raw_resource_description，接口更改）
  • bioimageio.spec.validate_format（新功能）
  • bioimageio.spec.dump_description（替换serialize_raw_resource_description_to_dict，接口更改）
  • bioimageio.spec.update_format（接口更改）
• 从Marshmallow切换到Pydantic
  • 扩展验证
  • 一个联合体，更精确的JSON模式

bioimageio.spec 0.4.9

• 小的错误修复
• 更好的类型提示
• 改进的测试

bioimageio.spec 0.4.8post1

• 将axes和eps添加到scale_mean_var

bioimageio.spec 0.4.7post1

• 通过将未来的格式版本视为各自资源类型的最新已知版本来添加简单的向前兼容性

bioimageio.spec 0.4.6post3

• 使CLI输出更易于阅读

• 在检查URL可用性时找到重定向的URL

bioimageio.spec 0.4.6post2

• 改进了给定字符串的RDF文件路径不存在的错误信息

• 改进了模型描述中documentation字段的文档

bioimageio.spec 0.4.6post1

• 修复enrich_partial_rdf_with_imjoy_plugin（见https://github.com/bioimage-io/spec-bioimage-io/pull/452）

bioimageio.spec 0.4.5post16

• 修复resolve_collection_entries()中的条目rdf_update

bioimageio.spec 0.4.5post15

• 将根传递给resolve_collection_entries()中的enrich_partial_rdf参数

bioimageio.spec 0.4.5post14

• 将ResourceDescrption.root_path作为远程资源的URI。这解决了集合描述，因为集合条目是在加载集合描述之后解决的。

bioimageio.spec 0.4.5post13

• 添加新的bioimageio.spec.partner模块，如果可选的'lxml'依赖项可用，则添加validate-partner-collection命令

bioimageio.spec 0.4.5post12

• 新环境变量BIOIMAGEIO_CACHE_WARNINGS_LIMIT（默认：3）以避免缓存命中警告的垃圾邮件

• 对从绝对路径到相对路径的转换进行更健壮的转换（在非路径源文件上不会失败）

bioimageio.spec 0.4.5post11

• 在序列化过程中将绝对路径转换为相对路径时解决符号链接；请参阅#438

bioimageio.spec 0.4.5post10

• 修复带有id的集合描述的加载（id之前被忽略）

bioimageio.spec 0.4.5post9

• 支持通过动物的昵称加载bioimageio资源（目前只有模型有昵称）。

bioimageio.spec 0.4.5post8

• 任何之前期望本地相对路径的字段现在也接受绝对路径

• load_raw_resource_description返回一个没有相对路径的原始资源描述（任何相对路径都转换为绝对路径）。

bioimageio.spec 0.4.4post7

• 添加命令commands.update_rdf()/update-rdf(cli)

bioimageio.spec 0.4.4post2

• 修复未解决的导入源文件问题

bioimageio.spec 0.4.4post1

• 修复集合描述类型字段的转换问题

bioimageio.spec 0.4.3post1

• 修复模型描述0.4的形状验证问题：输出形状现在需要大于晕环

• 将对象从bioimageio.spec.shared.utils移动到bioimageio.spec.shared[.node_transformer]

• 验证摘要中添加了额外的键：bioimageio_spec_version, status

bioimageio.spec 0.4.2post4

• 修复通用描述中的问题
  • 如果yaml中存在，忽略root_path字段的值。此字段用于内部，并且总是存在于RDF节点中。

bioimageio.spec 0.4.1.post5

• 修复集合描述中的问题
  • 即使源字段没有指向RDF，直接在集合描述中指定的RDF也会被正确验证
  • 允许集合描述嵌套

bioimageio.spec 0.4.1.post4

• 修复通用描述原始节点中缺失的icon字段

• 修复集合描述中的问题

  • 直接在集合描述中指定的RDF被正确验证
  • 目前不允许集合描述嵌套
  • links不再是一个显式的集合条目字段（"已移动到未知"）

bioimageio.spec 0.4.1.post0

• 新的模型规范0.3.5和0.4.1

bioimageio.spec 0.4.0.post3

• load_raw_resource_description不再接受update_to_current_format关键字参数（请使用update_to_format代替）

bioimageio.spec 0.4.0.post2

• load_raw_resource_description接受update_to_format关键字参数

资源描述格式版本

通用0.3.1和模型0.5.3

• 非破坏性更改
  • 为了使用version，删除了version_number

模型0.5.2

• 非破坏性更改
  • 为索引、时间和空间输入轴添加了concatenable标志

模型0.5.1

• 非破坏性更改
  • 为outputs.i.size添加了DataDependentSize，以指定在运行推理之前不知道的输出形状。
  • 添加了可选的inputs.i.optional字段，以指示一个张量可能是None
  • 通过默认添加'ensure_dtype'操作，使preprocessing和postprocessing中的数据类型假设变得明确。
  • 允许在'binarize'处理步骤中指定多个阈值（沿axis）

通用0.3.0 / 应用程序0.3.0 / 集合0.3.0 / 数据集0.3.0 / 笔记本0.3.0

• 完全自动可转换的破坏性更改
  • 删除了download_url
  • 删除了非文件附件
  • attachments.files移动到attachments.i.source
• 非破坏性更改
  • 添加了可选的parent字段

模型0.5.0

所有通用0.3.0更改（除模型外已具有parent字段）加上

• 部分自动可转换的破坏性更改
  • inputs.i.axes现在定义得更详细（同样适用于outputs.i.axes）
  • inputs.i.shape按轴移动到inputs.i.axes.size（同样适用于outputs.i.shape）
  • 将新的预-/后处理'fixed_zero_mean_unit_variance'与'zero_mean_unit_variance'分开，其中mode=fixed不再有效。（对于标量值，这是自动可转换的。）
• 完全自动可转换的破坏性更改
  • weights.pytorch_state_dict.architecture中的更改
    • 将weights.pytorch_state_dict.architecture.source_file重命名为...architecture.source
  • weights.pytorch_state_dict.dependencies中的更改
    • 仅允许使用conda环境，并通过weights.pytorch_state_dict.dependencies.source指定
    • 新的可选字段weights.pytorch_state_dict.dependencies.sha256
  • weights.tensorflow_model_bundle.dependencies中的更改
    • 与weights.pytorch_state_dict.dependencies中的更改相同
  • 将test_inputs移动到inputs.i.test_tensor
  • 将test_outputs移动到outputs.i.test_tensor
  • 将sample_inputs移动到inputs.i.sample_tensor
  • 将sample_outputs移动到outputs.i.sample_tensor
  • 将inputs.i.name重命名为inputs.i.id
  • 将 outputs.i.name 重命名为 outputs.i.id
  • 将 inputs.i.preprocessing.name 重命名为 inputs.i.preprocessing.id
  • 将 outputs.i.postprocessing.name 重命名为 outputs.i.postprocessing.id
• 非破坏性更改
  • 新增预/后处理：id='ensure_dtype'，具有关键字参数 dtype

通用版本 0.2.4 和模型版本 0.4.10

• 完全自动可转换的破坏性更改
  • 如果可用，则用 config.bioimageio.nickname 中的值覆盖 id
• 非破坏性更改
  • version_number 是一个新可选字段，表示 RDF 是具有给定 id 的第 n 个版本
  • id_emoji 是一个新可选字段（如果可用，则从 config.bioimageio.nickname_icon 设置）
  • uploader 是一个新可选字段，具有 email 和可选的 name 子字段

模型版本 0.4.9

• 非破坏性更改
  • 对于模型描述 0.3 和 0.4，将预/后处理关键字参数 mode 和 axes 总是设置为可选

模型版本 0.4.8

• 非破坏性更改
  • cite 字段现在是可选的

通用版本 0.2.2 和模型版本 0.4.7

• 完全自动可转换的破坏性更改
  • 名称字段可能不包含 '/' 或 ''（转换时会移除这些字符）

模型版本 0.4.6

• 非破坏性更改
  • 可以通过在 shape:scale 中插入 null 来扩展隐式输出形状，并在 offset 字段中指示新维度 D 的长度。请注意，D=2*'offset'。

模型版本 0.4.5

• 完全自动可转换的破坏性更改
  • parent 字段已更改，用于存储一个字符串，该字符串是 bioimage.io ID、URL 或本地相对路径（而不是子字段 uri 和 sha256）

模型版本 0.4.4

• 非破坏性更改
  • 新增可选字段 training_data

数据集版本 0.2.2

• 非破坏性更改
  • 明确定义并记录数据集描述（目前，克隆通用描述，类型为 "dataset"）

模型版本 0.4.3

• 非破坏性更改
  • 添加可选字段 download_url
  • 将可选字段 dependencies 添加到所有权重格式（不仅限于 pytorch_state_dict）
  • 将可选的 pytorch_version 添加到 pytorch_state_dict 和 torchscript 权重格式中

模型版本 0.4.2

• 错误修复
  • 在 pytorch_state_dict 权重条目中，architecture 现在不再是可选的。

集合版本 0.2.2

• 非破坏性更改

  • 将 authors、cite、documentation 和 tags 设置为可选

• 完全自动可转换的破坏性更改

  • 通过将资源类型字段合并到 collection 字段中简化集合描述 0.2.1，该字段包含指定集合中所有资源的列表。

通用版本 0.2.2 / 模型版本 0.3.6 / 模型版本 0.4.2

• 非破坏性更改
  • 新增可选字段 rdf_source
  • 新增可选字段 id

集合版本 0.2.1

• 首次正式发布，扩展了通用描述，添加了 application、model、dataset、notebook 和（嵌套）collection 字段，这些字段包含链接到相应资源的列表。

通用版本 0.2.1

• 非破坏性更改
  • 在 authors 中的条目中添加可选的 email 和 github_user 字段
  • 添加可选的 maintainers 字段（类似于 authors 中的条目，但需要 github_user（且不需要 name））

模型版本 0.4.1

• 完全自动可转换的破坏性更改

  • 将字段 dependencies 移动到 weights:pytorch_state_dict:dependencies

• 非破坏性更改

  • documentation 字段现在也接受 URL

模型版本 0.3.5

• 非破坏性更改
  • documentation 字段现在也接受 URL

模型版本 0.4.0

• 重大变更

  • 模型输入和输出不得使用重复的名称。
  • 如果定义了 pytorch_state_dict 权重，则模型字段 sha256 是必需的，并且现在已移动到 pytroch_state_dict 条目中作为 architecture_sha256。

• 完全自动可转换的破坏性更改

  • 删除了模型字段语言和框架。
  • 将模型字段 source 重命名为 architecture，并将其与 kwargs 一起移动到 pytorch_state_dict 权重条目中（如果存在，否则它们将被删除）。
  • 将权重格式 pytorch_script 重命名为 torchscript。

• 其他更改

  • 模型输入（如输出）可以通过对 reference_tensor 进行 scale 和 offset 来定义。
  • 在模型描述中添加了 maintainers 字段。
  • 在 authors 字段中的条目现在可以额外包含 email 或 github_user。
  • validate 命令返回的摘要现在还包含警告列表。
  • 添加了 update_format 命令，以帮助通过应用自动转换来更新较旧的 RDF。

模型版本 0.3.4

• 非破坏性更改
  • 将可选参数 eps 添加到 scale_range 后处理。

模型版本 0.3.3

• 完全自动可转换的破坏性更改
  • 将隐式输出张量的 reference_input 重命名为 reference_tensor

模型版本 0.3.2

• 重大变更

  • 包中的 RDF 文件名应为 rdf.yaml（对于所有 RDF，不是 model.yaml）；
  • 将 authors 和 packaged_by 字段从 List[str] 更改为 List[Author]，其中 Author 由一个字典组成 {name: '<Full name>', affiliation: '<Affiliation>', orcid: 'optional orcid id'};
  • 添加强制性的 type 字段以符合通用描述。仅有效的值是 'model' 用于模型描述；
  • 仅允许来自 SPDX 许可列表 的 license 标识符；

• 非破坏性更改

  • 添加可选的 version 字段（默认 0.1.0）以跟踪模型更改；
  • 允许 attachments 列表中的值可以是除了 URI 之外的任何值；