From 55e28bf78bf7df23e3624bb297016845876d53e6 Mon Sep 17 00:00:00 2001 From: jluethi Date: Mon, 29 Aug 2022 14:37:45 +0200 Subject: [PATCH 1/3] Change field of view to image in well content --- latest/index.bs | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 3ed6d7d7..caaf8f7a 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -184,8 +184,7 @@ The following specification defines the hierarchy for a high-content screening dataset. Three groups MUST be defined above the images: - the group above the images defines the well and MUST implement the - [well specification](#well-md). All images contained in a well are fields - of view of the same well + [well specification](#well-md). A well is a collection of 1 to m images. - the group above the well defines a row of wells - the group above the well row defines an entire plate i.e. a two-dimensional collection of wells organized in rows and columns. It MUST implement the @@ -208,7 +207,7 @@ A well group SHOULD NOT be present if there are no images in the well. │ │ ├── .zgroup │ │ ├── .zattrs # Implements "well" specification │ │ │ - │ │ ├── 0 # First field of view of well A1 + │ │ ├── 0 # First image of well A1 │ │ │ │ │ │ │ ├── .zgroup │ │ │ ├── .zattrs # Implements "multiscales", "omero" @@ -216,7 +215,7 @@ A well group SHOULD NOT be present if there are no images in the well. │ │ │ │ ... # Resolution levels │ │ │ ├── n │ │ │ └── labels # Labels (optional) - │ │ ├── ... # Fields of view + │ │ ├── ... # Images belonging to well A1 │ │ └── m │ ├── ... # Columns │ └── 12 @@ -418,11 +417,11 @@ custom attributes of the plate group under the `plate` key in the group-level me The `plate` dictionary MAY contain an `acquisitions` key whose value MUST be a list of JSON objects defining the acquisitions for a given plate to which wells can refer to. Each acquisition object MUST contain an `id` key whose value MUST be an unique integer identifier -greater than or equal to 0 within the context of the plate to which fields of view can refer +greater than or equal to 0 within the context of the plate to which images can refer to (see #well-md). Each acquisition object SHOULD contain a `name` key whose value MUST be a string identifying the name of the acquisition. Each acquisition object SHOULD contain a `maximumfieldcount` -key whose value MUST be a positive integer indicating the maximum number of fields of view for the +key whose value MUST be a positive integer indicating the maximum number of images per well for the acquisition. Each acquisition object MAY contain a `description` key whose value MUST be a string specifying a description for the acquisition. Each acquisition object MAY contain a `starttime` and/or `endtime` key whose values MUST be integer epoch timestamps specifying @@ -438,7 +437,7 @@ other `name` in the `columns` list. Care SHOULD be taken to avoid collisions on case-insensitive filesystems (e.g. avoid using both `Aa` and `aA`). The `plate` dictionary SHOULD contain a `field_count` key whose value MUST be a positive integer -defining the maximum number of fields per view across all wells. +defining the maximum number of images per well across all wells. The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the name of the plate. @@ -466,7 +465,7 @@ the index into the `columns` list. `rowIndex` and `columnIndex` MUST be 0-based. `rowIndex`, `columnIndex`, and `path` MUST all refer to the same row/column pair. For example the following JSON object defines a plate with two acquisitions and -6 wells (2 rows and 3 columns), containing up to 2 fields of view per acquisition. +6 wells (2 rows and 3 columns), containing up to 2 images per acquisition. 
 path: examples/plate_strict/plate_6wells.json
@@ -474,7 +473,7 @@ highlight: json
The following JSON object defines a sparse plate with one acquisition and -2 wells in a 96 well plate, containing one field of view per acquisition. +2 wells in a 96 well plate, containing one image per acquisition. 
 path: examples/plate_strict/plate_2wells.json
@@ -484,13 +483,13 @@ highlight: json
 "well" metadata {#well-md}
 --------------------------
 
-For high-content screening datasets, the metadata about all fields of views
+For high-content screening datasets, the metadata about all images
 under a given well can be found under the "well" key in the attributes of the
 well group.
 
 The `well` dictionary MUST contain an `images` key whose value MUST be a list of JSON objects
-specifying all fields of views for a given well. Each image object MUST contain a
-`path` key whose value MUST be a string specifying the path to the field of view. The `path`
+specifying all images for a given well. Each image object MUST contain a
+`path` key whose value MUST be a string specifying the path to the image. The `path`
 MUST contain only alphanumeric characters, MUST be case-sensitive, and MUST NOT be a duplicate
 of any other `path` in the `images` list. If multiple acquisitions were performed in the plate,
 it MUST contain an `acquisition` key whose value MUST be an integer identifying the acquisition
@@ -499,18 +498,18 @@ which MUST match one of the acquisition JSON objects defined in the plate metada
 The `well` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the
 version of the well specification.
 
-For example the following JSON object defines a well with four fields of
-view. The first two fields of view were part of the first acquisition while
-the last two fields of view were part of the second acquisition.
+For example the following JSON object defines a well with four images.
+The first two images were part of the first acquisition while
+the last two images were part of the second acquisition.
 
 
 path: examples/well_strict/well_4fields.json
 highlight: json
 

 
-The following JSON object defines a well with two fields of view in a plate with
-four acquisitions. The first field is part of the first acquisition, and the second
-field is part of the last acquisition.
+The following JSON object defines a well with two images in a plate with
+four acquisitions. The first image is part of the first acquisition, and the second
+image is part of the last acquisition.
 
 
 path: examples/well_strict/well_2fields.json

From 20261ace44a4be387f02225fbef93ef8281b1aa5 Mon Sep 17 00:00:00 2001
From: jluethi 
Date: Mon, 29 Aug 2022 14:38:23 +0200
Subject: [PATCH 2/3] Add note about trade-offs for single- vs multi-image
 wells

---
 latest/index.bs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/latest/index.bs b/latest/index.bs
index caaf8f7a..c26282c3 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -193,6 +193,15 @@ dataset. Three groups MUST be defined above the images:
 A well row group SHOULD NOT be present if there are no images in the well row.
 A well group SHOULD NOT be present if there are no images in the well.
 
+Note: Trade-offs on how data is structured per well:
+Field of views of the microscope MAY be saved as individual images in each
+well to allow for maximal flexibility regarding translations between field of views.
+Having wells with many individual images does not scale for visualisation of
+large plates. Visualisation tools would then need to read all the tiny pyramid
+files for each field of view to create overviews and this IO performance becomes
+a big limiting factor. In that case, all the field of views SHOULD be saved as
+a single, combined image. In that way, the pyramid chunks can be kept at a
+reasonable size for low-resolution representations of a well.
 
 
 .                             # Root folder, potentially in S3,

From 03e281267d74cbb4cec71bcdeca70ed2e04d7ded Mon Sep 17 00:00:00 2001
From: jluethi 
Date: Mon, 29 Aug 2022 19:01:19 +0200
Subject: [PATCH 3/3] Improve wordingwith feedback from @will-moore

---
 latest/index.bs | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index c26282c3..61935db6 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -193,15 +193,12 @@ dataset. Three groups MUST be defined above the images:
 A well row group SHOULD NOT be present if there are no images in the well row.
 A well group SHOULD NOT be present if there are no images in the well.
 
-Note: Trade-offs on how data is structured per well:
-Field of views of the microscope MAY be saved as individual images in each
+Note: Field of views of the microscope may be saved as individual images in each
 well to allow for maximal flexibility regarding translations between field of views.
-Having wells with many individual images does not scale for visualisation of
-large plates. Visualisation tools would then need to read all the tiny pyramid
-files for each field of view to create overviews and this IO performance becomes
-a big limiting factor. In that case, all the field of views SHOULD be saved as
-a single, combined image. In that way, the pyramid chunks can be kept at a
-reasonable size for low-resolution representations of a well.
+However, having wells with many individual images does not scale well for visualisation of
+large plates. In that case, combining the fields and saving as a single image
+per Well is likely to improve performance.
+
 
 
 .                             # Root folder, potentially in S3,
@@ -446,7 +443,7 @@ other `name` in the `columns` list. Care SHOULD be taken to avoid collisions on
 case-insensitive filesystems (e.g. avoid using both `Aa` and `aA`).
 
 The `plate` dictionary SHOULD contain a `field_count` key whose value MUST be a positive integer
-defining the maximum number of images per well across all wells.
+defining the maximum number of images per well across all wells and all acquisitions.
 
 The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the
 name of the plate.