Skip to content

Commit 449fbca

Browse files
joshmoorejoshmoore
authored
Merge pull request #112 from joshmoore/bf2raw
bioformats2raw.layout
2 parents 12c916b + 106c301 commit 449fbca

17 files changed

Lines changed: 336 additions & 7 deletions

File tree

‎0.4/examples/bf2raw/.config.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"schema": "schemas/bf2raw.schema"
3+
}

‎0.4/examples/bf2raw/image.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"bioformats2raw.layout" : 3
3+
}

‎0.4/examples/bf2raw/plate.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"bioformats2raw.layout" : 3,
3+
"plate" : {
4+
"columns" : [ {
5+
"name" : "1"
6+
} ],
7+
"name" : "Plate Name 0",
8+
"wells" : [ {
9+
"path" : "A/1",
10+
"rowIndex" : 0,
11+
"columnIndex" : 0
12+
} ],
13+
"field_count" : 1,
14+
"rows" : [ {
15+
"name" : "A"
16+
} ],
17+
"acquisitions" : [ {
18+
"id" : 0
19+
} ],
20+
"version" : "0.4"
21+
}
22+
}

‎0.4/examples/ome/.config.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"schema": "schemas/ome.schema"
3+
}

‎0.4/examples/ome/series-2.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"series" : [ "0", "1" ]
3+
}

‎0.4/index.bs‎

Lines changed: 95 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,14 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
9999
“RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in
100100
[RFC 2119](https://tools.ietf.org/html/rfc2119).
101101

102+
<p>
103+
<dfn>Transitional</dfn> metadata is added to the specification with the
104+
intention of removing it in the future. Implementations may be expected (MUST) or
105+
encouraged (SHOULD) to support the reading of the data, but writing will usually
106+
be optional (MAY). Examples of transitional metadata include custom additions by
107+
implementations that are later submitted as a formal specification. (See [[#bf2raw]])
108+
</p>
109+
102110
Some of the JSON examples in this document include commments. However, these are only for
103111
clarity purposes and comments MUST NOT be included in JSON objects.
104112

@@ -240,6 +248,85 @@ keys as specified below for discovering certain types of data, especially images
240248

241249
If part of [[#multiscale-md]], the length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data.
242250

251+
"bioformats2raw.layout" (transitional) {#bf2raw}
252+
------------------------------------------------
253+
254+
[=Transitional=] "bioformats2raw.layout" metadata identifies a group which implicitly describes a series of images.
255+
The need for the collection stems from the common "multi-image file" scenario in microscopy. Parsers like Bio-Formats
256+
define a strict, stable ordering of the images in a single container that can be used to refer to them by other tools.
257+
258+
In order to capture that information within an OME-NGFF dataset, `bioformats2raw` internally introduced a wrapping layer.
259+
The bioformats2raw layout has been added to v0.4 as a transitional specification to specify filesets that already exist
260+
in the wild. An upcoming NGFF specification will replace this layout with explicit metadata.
261+
262+
<h4 id="bf2raw-layout" class="no-toc">Layout</h4>
263+
264+
Typical Zarr layout produced by running `bioformats2raw` on a fileset that contains more than one image (series > 1):
265+
266+
<pre>
267+
series.ome.zarr # One converted fileset from bioformats2raw
268+
├── .zgroup
269+
├── .zattrs # Contains "bioformats2raw.layout" metadata
270+
├── OME # Special group for containing OME metadata
271+
│ ├── .zgroup
272+
│ ├── .zattrs # Contains "series" metadata
273+
│ └── METADATA.ome.xml # OME-XML file stored within the Zarr fileset
274+
├── 0 # First image in the collection
275+
├── 1 # Second image in the collection
276+
└── ...
277+
</pre>
278+
279+
<h4 id="bf2raw-attributes" class="no-toc">Attributes</h4>
280+
281+
The top-level `.zattrs` file must contain the `bioformats2raw.layout` key:
282+
<pre class=include-code>
283+
path: examples/bf2raw/image.json
284+
highlight: json
285+
</pre>
286+
287+
If the top-level group represents a plate, the `bioformats2raw.layout` metadata will be present but
288+
the "plate" key MUST also be present, takes precedence and parsing of such datasets should follow [[#plate-md]]. It is not
289+
possible to mix collections of images with plates at present.
290+
291+
<pre class=include-code>
292+
path: examples/bf2raw/plate.json
293+
highlight: json
294+
</pre>
295+
296+
The `.zattrs` file within the OME group may contain the "series" key:
297+
298+
<pre class=include-code>
299+
path: examples/ome/series-2.json
300+
highlight: json
301+
</pre>
302+
303+
<h4 id="bf2raw-details" class="no-toc">Details</h4>
304+
305+
Conforming groups:
306+
307+
- MUST have the value "3" for the "bioformats2raw.layout" key in their `.zattrs` metadata at the top of the hierarchy;
308+
- SHOULD have OME metadata representing the entire collection of images in a file named "OME/METADATA.ome.xml" which:
309+
- MUST adhere to the OME-XML specification but
310+
- MUST use `<MetadataOnly/>` elements as opposed to `<BinData/>`, `<BinaryOnly/>` or `<TiffData/>`;
311+
- MAY make use of the [minimum specification](https://docs.openmicroscopy.org/ome-model/6.2.2/specifications/minimum.html).
312+
313+
Additionally, the logic for finding the Zarr group for each image follows the following logic:
314+
315+
- If "plate" metadata is present, images MUST be located at the defined location.
316+
- Matching "series" metadata (as described next) SHOULD be provided for tools that are unaware of the "plate" specification.
317+
- If the "OME" Zarr group exists, it:
318+
- MAY contain a "series" attribute. If so:
319+
- "series" MUST be a list of string objects, each of which is a path to an image group.
320+
- The order of the paths MUST match the order of the "Image" elements in "OME/METADATA.ome.xml" if provided.
321+
- If the "series" attribute does not exist and no "plate" is present:
322+
- separate "multiscales" images MUST be stored in consecutively numbered groups starting from 0 (i.e. "0/", "1/", "2/", "3/", ...).
323+
- Every "multiscales" group MUST represent exactly one OME-XML "Image" in the same order as either the series index or the group numbers.
324+
325+
Conforming readers:
326+
- SHOULD make users aware of the presence of more than one image (i.e. SHOULD NOT default to only opening the first image);
327+
- MAY use the "series" attribute in the "OME" group to determine a list of valid groups to display;
328+
- MAY choose to show all images within the collection or offer the user a choice of images, as with <dfn export="true"><abbr title="High-content screening">HCS</abbr></dfn> plates;
329+
- MAY ignore other groups or arrays under the root of the hierarchy.
243330

244331
"coordinateTransformations" metadata {#trafo-md}
245332
-------------------------------------
@@ -315,10 +402,10 @@ if not datasets:
315402
datasets = [x["path"] for x in multiscales[0]["datasets"]]
316403
```
317404

318-
"omero" metadata {#omero-md}
319-
----------------------------
405+
"omero" metadata (transitional) {#omero-md}
406+
-------------------------------------------
320407

321-
Information specific to the channels of an image and how to render it
408+
[=Transitional=] information specific to the channels of an image and how to render it
322409
can be found under the "omero" key in the group-level metadata:
323410

324411
```json
@@ -581,6 +668,11 @@ Version History {#history}
581668
<td>Description</td>
582669
</tr>
583670
</thead>
671+
<tr>
672+
<td>0.4.1</td>
673+
<td>2022-09-26</td>
674+
<td>transitional metadata for image collections ("bioformats2raw.layout")</td>
675+
</tr>
584676
<tr>
585677
<td>0.4.0</td>
586678
<td>2022-02-08</td>

‎0.4/schemas/bf2raw.schema‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://ngff.openmicroscopy.org/latest/schemas/bf2raw.schema",
4+
"title": "NGFF container produced by bioformats2raw",
5+
"description": "JSON from OME-NGFF .zattrs",
6+
"type": "object",
7+
"properties": {
8+
"bioformats2raw.layout": {
9+
"description": "The top-level identifier metadata added by bioformats2raw",
10+
"type": "number",
11+
"enum": [3]
12+
}
13+
}
14+
}

‎0.4/schemas/ome.schema‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://ngff.openmicroscopy.org/latest/schemas/ome.schema",
4+
"title": "NGFF group produced by bioformats2raw to contain OME metadata",
5+
"description": "JSON from OME-NGFF OME/.zattrs linked to an OME-XML file",
6+
"type": "object",
7+
"properties": {
8+
"series": {
9+
"description": "An array of the same length and the same order as the images defined in the OME-XML",
10+
"type": "array",
11+
"items": {
12+
"type": "string"
13+
},
14+
"minContains": 1
15+
}
16+
}
17+
}

‎latest/examples/bf2raw/.config.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"schema": "schemas/bf2raw.schema"
3+
}

‎latest/examples/bf2raw/image.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"bioformats2raw.layout" : 3
3+
}

0 commit comments

Comments
 (0)