ome2024-ngff-challenge

2024年生成1 PB OME-Zarr数据的挑战项目规划和材料库

挑战概述

挑战的高级目标是根据规范的开发版本生成 OME-Zarr 数据，以推动实施工作并建立社区成员可以预期的转换成本基线。

挑战中生成的数据将具有

• 所有 v2 数组转换为 v3，可选地分片数据
• 所有 .zattrs 元数据迁移到 zarr.json["attributes"]["ome"]
• 一个包含最小元数据（标本和成像方式）的顶层 ro-crate-metadata.json 文件

您可以使用 minio 客户端 查看示例数据集的内容

$ mc config host add uk1anon https://uk1s3.embassy.ebi.ac.uk "" ""
Added `uk1anon` successfully.
$ mc ls -r uk1anon/idr/share/ome2024-ngff-challenge/0.0.5/6001240.zarr/
[2024-08-01 14:24:35 CEST]  24MiB STANDARD 0/c/0/0/0/0
[2024-08-01 14:24:28 CEST]   598B STANDARD 0/zarr.json
[2024-08-01 14:24:32 CEST] 6.0MiB STANDARD 1/c/0/0/0/0
[2024-08-01 14:24:28 CEST]   598B STANDARD 1/zarr.json
[2024-08-01 14:24:29 CEST] 1.6MiB STANDARD 2/c/0/0/0/0
[2024-08-01 14:24:28 CEST]   592B STANDARD 2/zarr.json
[2024-08-01 14:24:28 CEST] 1.2KiB STANDARD ro-crate-metadata.json
[2024-08-01 14:24:28 CEST] 2.7KiB STANDARD zarr.json

数据集（来自 idr0062）可以使用在 https://deploy-preview-36--ome-ngff-validator.netlify.app/?source=https://uk1s3.embassy.ebi.ac.uk/idr/share/ome2024-ngff-challenge/0.0.5/6001240.zarr 可用的 OME-NGFF 验证器的开发版本进行检查

其他样本

• 4496763.zarr 形状 4,25,2048,2048，大小 589.81 MB，来自 idr0047。
• 9822152.zarr 形状 1,1,1,93184,144384，大小 21.57 GB，来自 idr0083。
• 9846151.zarr 形状 1,3,1402,5192,2947，大小 66.04 GB，来自 idr0048。
• Week9_090907.zarr 胶板来自 idr0035。
• l4_sample/color 来自 WebKnossos。
• 来自 idr0090 的胶板：190129.zarr 大小 1.0 TB，190206.zarr 大小 485 GB，190211.zarr 大小 704 GB。
• 76-45.zarr 胶板来自 idr0010

$ ome2024-ngff-challenge --input-bucket=idr --input-endpoint=https://uk1s3.embassy.ebi.ac.uk --input-anon zarr/v0.4/idr0047A/4496763.zarr params_4496763.json --output-write-details

# params_4496763.json
[{"shape": [4, 25, 2048, 2048], "chunks": [1, 1, 2048, 2048], "shards": [4, 1, 2048, 2048]}, {"shape": [4, 25, 1024, 1024], "chunks": [1, 1, 1024, 1024], "shards": [4, 1, 1024, 1024]}, {"shape": [4, 25, 512, 512], "chunks": [1, 1, 512, 512], "shards": [4, 1, 512, 512]}, {"shape": [4, 25, 256, 256], "chunks": [1, 1, 256, 256], "shards": [4, 1, 256, 256]}, {"shape": [4, 25, 128, 128], "chunks": [1, 1, 128, 128], "shards": [4, 1, 128, 128]}, {"shape": [4, 25, 64, 64], "chunks": [1, 1, 64, 64], "shards": [4, 1, 64, 64]}]

ome2024-ngff-challenge --input-bucket=idr --input-endpoint=https://uk1s3.embassy.ebi.ac.uk --input-anon zarr/v0.4/idr0047A/4496763.zarr 4496763.zarr --output-read-details params_4496763.json

$ ome2024-ngff-challenge --input-bucket=idr --input-endpoint=https://uk1s3.embassy.ebi.ac.uk --input-anon zarr/v0.4/idr0083A/9822152.zarr 9822152.zarr --output-shards=1,1,1,4096,4096 --output-chunks=1,1,1,1024,1024 --log debug

$ ome2024-ngff-challenge 9846151.zarr/0 will/9846151_2D_chunks_3.zarr --output-shards=1,1,1,4096,4096 --output-chunks=1,1,1,1024,1024 --log debug

$ ome2024-ngff-challenge --input-bucket=bia-integrator-data --input-endpoint=https://uk1s3.embassy.ebi.ac.uk --input-anon S-BIAD847/0762bf96-4f01-454d-9b13-5c8438ea384f/0762bf96-4f01-454d-9b13-5c8438ea384f.zarr /data/will/idr0035/Week9_090907.zarr --output-shards=1,3,1,1024,2048 --output-chunks=1,1,1,1024,1024 --log debug

CLI 命令

resave：转换您的数据

ome2024-ngff-challenge 工具可用于转换基于 Zarr v2 的 OME-Zarr 0.4 数据集。输入数据将 不会以任何方式修改，并在选择的位置创建数据的完整副本。

入门

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr

是工具的最基本调用。如果您不选择许可证，应用程序将失败

No license set. Choose one of the Creative Commons license (e.g., `--cc-by`) or skip RO-Crate creation (`--rocrate-skip`)

许可证

有几个许可证选项可供选择。我们建议以下其中之一

• --cc-by：必须提及创作者
• --cc0：将您的数据添加到公共领域

或者，您可以选择自己的许可证，例如

--rocrate-license=https://creativecommons.org/licenses/by-nc/4.0/

以限制您数据的使用。此外，您还可以禁用所有元数据的收集。

注意：您需要稍后添加元数据才能使数据集被视为有效。

元数据

为了挑战而收集了四个额外的元数据字段

• 生物体和模态：推荐
• 名称和描述：建议

可以通过带 --rocrate- 前缀的属性来设置这些，因为它们将存储在顶层 Zarr 数据集的标准 RO-Crate JSON 文件（./ro-crate-metadata.json）中。

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --rocrate-organism=NCBI:txid9606      # Human
ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --rocrate-modality=obo:FBbi_00000369  # SPIM
ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --rocrate-name="short name of dataset"
ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --rocrate-description="and a longer description"

有关包括几个其他 NCBI 和 FBbi 术语的示例，请参阅

ome2024-ngff-challenge resave --help

重新运行脚本

如果您想以不同的参数重新运行脚本，可以设置 --output-overwrite 以忽略以前的转换

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --output-overwrite

并行写入

默认情况下，将同时处理16个数据块以限制内存使用。根据您的本地资源，您可以增加此数量。

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --output-threads=128

远程读取/写入

如果您想避免下载和/或上传Zarr数据集，您可以在命令行上设置S3参数，这样输入和/或输出数据集将被视为S3桶内的前缀。

ome2024-ngff-challenge resave --cc-by \
        --input-bucket=BUCKET \
        --input-endpoint=HOST \
        --input-anon \
        input.zarr \
        output.zarr

一个您可以尝试的小例子

ome2024-ngff-challenge resave --cc-by \
        --input-bucket=idr \
        --input-endpoint=https://uk1s3.embassy.ebi.ac.uk \
        --input-anon \
        zarr/v0.4/idr0062A/6001240.zarr \
        /tmp/6001240.zarr

通过脚本读取/写入

另一个读写选项是让resave.py生成一个可以稍后执行的脚本。如果您传递了--output-script，则不会立即生成数组，而会创建一个名为convert.sh的文件，稍后可以执行。

例如，运行

ome2024-ngff-challenge resave --cc-by dev2/input.zarr /tmp/scripts.zarr --output-script

将生成一个包含一个zarr.json文件和3个convert.sh脚本的数据集

/tmp/scripts.zarr/0/convert.sh
/tmp/scripts.zarr/1/convert.sh
/tmp/scripts.zarr/2/convert.sh

每个脚本都包含一个形式的语句

zarrs_reencode --chunk-shape 1,1,275,271 --shard-shape 2,236,275,271 --dimension-names c,z,y,x --validate dev2/input.zarr /tmp/scripts.zarr

运行此脚本将需要安装带有zarrs_tools的

cargo install zarrs_tools
export PATH=$PATH:$HOME/.cargo/bin

优化块和分片

Zarr v3支持分片，它是包含多个块的文件。分片的形状在所有维度上必须是块大小的倍数。目前还没有一个适用于所有数据的确定分片和块大小的启发式方法。resave默认选择分片形状为图像数组的完整形状。

为了限制分片的大小，如果分片超过1亿像素，则必须指定分片形状。您可以使用--output-shards指定分片形状，该形状将用于所有金字塔分辨率。如果块形状因较低分辨率而更改（以匹配较小的图像形状），则可能会出现问题。在这种情况下，您还应该指定用于所有分辨率的块形状。

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --output-chunks=1,1,1,256,256 --output-shards=1,1,1,2048,2048

或者，您可以使用JSON文件来审查并手动优化每个分辨率的分片和块参数

ome2024-ngff-challenge resave --cc-by input.zarr parameters.json --output-write-details

这将写入一个如下形式的JSON文件

[{"shape": [...], "chunks": [...], "shards": [...]}, ...

其中字典的顺序与“multiscales”中“datasets”字段的顺序相匹配。可以使用output-read-details标志读取对文件的编辑

ome2024-ngff-challenge resave --cc-by input.zarr output.zarr --output-read-details=parameters.json

注意：对形状的更改将被忽略。

更多信息

有关更多参数和示例，请参阅ome2024-ngff-challenge resave -h。

lookup：查找本体术语（WIP）

ome2024-ngff-challenge工具还可以用于查找EBI OLS中的术语，以设置元数据字段，如--rocrate-modality和--rocrate-organism。

ome2024-ngff-challenge lookup "homo sapiens"
ONTOLOGY  	TERM                	LABEL                         	DESCRIPTION
ncbitaxon 	NCBITaxon_9606      	Homo sapiens
vto       	VTO_0011993         	Homo sapiens
snomed    	SNOMED_337915000    	Homo sapiens
...

相关工作

以下额外的PR是使用此存储库中脚本创建的数据所需的

• https://github.com/ome/ome-ngff-validator/pull/36
• https://github.com/ome/ome-zarr-py/pull/383
• https://github.com/hms-dbmi/vizarr/pull/172
• https://github.com/LDeakin/zarrs_tools/issues/8

稍有不相关但当前很重要

• https://github.com/google/neuroglancer/issues/606
• https://github.com/ome/napari-ome-zarr/pull/112
• https://github.com/zarr-developers/zarr-python/issues/2029