From 55e28bf78bf7df23e3624bb297016845876d53e6 Mon Sep 17 00:00:00 2001 From: jluethi Date: Mon, 29 Aug 2022 14:37:45 +0200 Subject: [PATCH 1/4] 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/4] 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/4] 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.

From 7f7fa21d2e2b4b9631ce93e5136d7700d8fb192f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joel=20L=C3=BCthi?= 
Date: Tue, 4 Feb 2025 17:33:31 +0100
Subject: [PATCH 4/4] Update latest/index.bs

Improve syntax based on proposal from @imagejan

Co-authored-by: Jan Eglinger 
---
 latest/index.bs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/latest/index.bs b/latest/index.bs
index 61935db6..51533b97 100644
--- a/latest/index.bs
+++ b/latest/index.bs
@@ -193,11 +193,11 @@ 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: 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.
+Note: Fields of view of the microscope may be saved as individual images in each
+well to allow for maximal flexibility regarding translations between fields of view.
 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.
+per well is likely to improve performance.