From 8b24328b21885110fc43f2f8269143a9a5229ec1 Mon Sep 17 00:00:00 2001 From: Melissa Linkert Date: Sun, 13 Dec 2020 19:15:44 -0600 Subject: [PATCH 1/5] Clarify plate and well specifications for sparse plates --- latest/index.bs | 127 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 120 insertions(+), 7 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 7c2a5c7d..1659ce0b 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -366,7 +366,8 @@ custom attributes of the plate group under the `plate` key.
A list of JSON objects defining the columns of the plate. Each column object defines the properties of the column at the index of the object in the list. If not empty, it MUST contain a `name` key specifying the - column name.
+ column name. Each column in the physical plate MUST be defined, even + if no wells in the column are defined.
field_count
An integer defining the maximum number of fields per view across all wells.
@@ -376,7 +377,8 @@ custom attributes of the plate group under the `plate` key.
A list of JSON objects defining the rows of the plate. Each row object defines the properties of the row at the index of the object in the list. If not empty, it MUST contain a `name` key specifying the row - name.
+ name. Each row in the physical plate MUST be defined, even if no wells + in the row are defined.
version
A string defining the version of the specification.
wells
@@ -384,8 +386,8 @@ custom attributes of the plate group under the `plate` key. MUST contain a `path` key identifying the path to the well subgroup. -For example the following JSON object defines a plate with two acquisition and -6 wells (2 rows and 3 columns), containing up 2 fields of view per acquistion. +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. ```json "plate": { @@ -448,11 +450,102 @@ For example the following JSON object defines a plate with two acquisition and } ``` +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. + +```json +"plate": { + "acquisitions": [ + { + "id": 1, + "maximumfieldcount": 1, + "name": "single acquisition", + "starttime": 1343731272000 + }, + ], + "columns": [ + { + "name": "1" + }, + { + "name": "2" + }, + { + "name": "3" + }, + { + "name": "4" + }, + { + "name": "5" + }, + { + "name": "6" + }, + { + "name": "7" + }, + { + "name": "8" + }, + { + "name": "9" + }, + { + "name": "10" + }, + { + "name": "11" + }, + { + "name": "12" + } + ], + "field_count": 1, + "name": "sparse test", + "rows": [ + { + "name": "A" + }, + { + "name": "B" + }, + { + "name": "C" + }, + { + "name": "D" + }, + { + "name": "E" + }, + { + "name": "F" + }, + { + "name": "G" + }, + { + "name": "H" + } + ], + "version": "0.1", + "wells": [ + { + "path": "C/5" + }, + { + "path": "D/7" + } + ] + } +``` + "well" metadata {#well-md} -------------------------- For high-content screening datasets, the metadata about all fields of views -under a given well can be found under the "well" key in the attributes of the +under a given well can be found under the "well" key in the attributes of the well group.
@@ -460,7 +553,7 @@ well group.
A list of JSON objects defining the fields of views for a given well. Each object MUST contain a `path` key identifying the path to the field of view. If multiple acquisitions were performed in the plate, it - SHOULD contain an `acquisition` key identifying the id of the + MUST contain an `acquisition` key identifying the id of the acquisition which must match one of acquisition JSON objects defined in the plate metadata.
version
@@ -468,7 +561,7 @@ well group.
For example the following JSON object defines a well with four fields of -views. The first two fields of view were part of the first acquisition while +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. ```json @@ -495,6 +588,26 @@ the last two fields of view were part of the second acquisition. } ``` +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. + +```json +"well": { + "images": [ + { + "acquisition": 0, + "path": "0" + }, + { + "acquisition": 3, + "path": "1" + } + ], + "version": "0.1" +} +``` + Implementations {#implementations} ================================== From 0c286908a4fbaceb2c622b21e5a52cc041eea7c0 Mon Sep 17 00:00:00 2001 From: Melissa Linkert Date: Wed, 17 Mar 2021 12:48:50 -0500 Subject: [PATCH 2/5] Add "row_index" and "column_index" to "wells" spec --- latest/index.bs | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 1659ce0b..afc4f102 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -383,7 +383,10 @@ custom attributes of the plate group under the `plate` key.
A string defining the version of the specification.
wells
A list of JSON objects defining the wells of the plate. Each well object - MUST contain a `path` key identifying the path to the well subgroup.
+ MUST contain a `path` key identifying the path to the well subgroup. + Each well object MUST contain both a `row_index` key identifying the index into + the `rows` list and a `column_index` key indentifying the index into + the `columns` list. `row_index` and `column_index` MUST be 0-based. For example the following JSON object defines a plate with two acquisitions and @@ -429,22 +432,34 @@ For example the following JSON object defines a plate with two acquisitions and "version": "0.1", "wells": [ { - "path": "2020-10-10/A/1" + "path": "2020-10-10/A/1", + "row_index": 0, + "column_index": 0 }, { "path": "2020-10-10/A/2" + "row_index": 0, + "column_index": 1 }, { "path": "2020-10-10/A/3" + "row_index": 0, + "column_index": 2 }, { "path": "2020-10-10/B/1" + "row_index": 1, + "column_index": 0 }, { "path": "2020-10-10/B/2" + "row_index": 1, + "column_index": 1 }, { "path": "2020-10-10/B/3" + "row_index": 1, + "column_index": 2 } ] } @@ -533,9 +548,13 @@ The following JSON object defines a sparse plate with one acquisition and "wells": [ { "path": "C/5" + "row_index": 2, + "column_index": 4 }, { "path": "D/7" + "row_index": 3, + "column_index": 6 } ] } From 5a1ddc7d57d3c7f96e1d84efdb7a86e701666de6 Mon Sep 17 00:00:00 2001 From: Melissa Linkert Date: Thu, 2 Dec 2021 13:29:35 -0600 Subject: [PATCH 3/5] Stricter requirements for row/column names, well groups, and well paths --- latest/index.bs | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index afc4f102..8a912595 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -156,7 +156,7 @@ High-content screening {#hcs-layout} ------------------------------------ The following specification defines the hierarchy for a high-content screening -dataset. Three groups must be defined above the images: +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 @@ -166,6 +166,9 @@ dataset. Three groups must be defined above the images: collection of wells organized in rows and columns. It MUST implement the [plate specification](#plate-md) +A well row group MUST NOT be present if there are no images in the well row. +A well group MUST NOT be present if there are no images in the well. + ``` . # Root folder, potentially in S3, @@ -365,9 +368,9 @@ custom attributes of the plate group under the `plate` key.
columns
A list of JSON objects defining the columns of the plate. Each column object defines the properties of the column at the index of the object - in the list. If not empty, it MUST contain a `name` key specifying the - column name. Each column in the physical plate MUST be defined, even - if no wells in the column are defined.
+ in the list. Each column in the physical plate MUST be defined, even + if no wells in the column are defined. Each defined column MUST contain + a `name` key specifying the column name.
field_count
An integer defining the maximum number of fields per view across all wells.
@@ -376,14 +379,17 @@ custom attributes of the plate group under the `plate` key.
rows
A list of JSON objects defining the rows of the plate. Each row object defines the properties of the row at the index of the object in the - list. If not empty, it MUST contain a `name` key specifying the row - name. Each row in the physical plate MUST be defined, even if no wells - in the row are defined.
+ list. Each row in the physical plate MUST be defined, even if no wells + in the row are defined. Each defined row MUST contain a `name` key + specifying the row name.
version
A string defining the version of the specification.
wells
A list of JSON objects defining the wells of the plate. Each well object MUST contain a `path` key identifying the path to the well subgroup. + The `path` MUST consist of a `name` in the `rows` list, a file separator (`/`), + and a `name` from the `columns` list, in that order. The `path` MUST NOT contain + additional leading or trailing directories. Each well object MUST contain both a `row_index` key identifying the index into the `rows` list and a `column_index` key indentifying the index into the `columns` list. `row_index` and `column_index` MUST be 0-based.
@@ -432,32 +438,32 @@ For example the following JSON object defines a plate with two acquisitions and "version": "0.1", "wells": [ { - "path": "2020-10-10/A/1", + "path": "A/1", "row_index": 0, "column_index": 0 }, { - "path": "2020-10-10/A/2" + "path": "A/2" "row_index": 0, "column_index": 1 }, { - "path": "2020-10-10/A/3" + "path": "A/3" "row_index": 0, "column_index": 2 }, { - "path": "2020-10-10/B/1" + "path": "B/1" "row_index": 1, "column_index": 0 }, { - "path": "2020-10-10/B/2" + "path": "B/2" "row_index": 1, "column_index": 1 }, { - "path": "2020-10-10/B/3" + "path": "B/3" "row_index": 1, "column_index": 2 } From 7c2536a57ea0e3503cfc28f534e776fe7ff722e7 Mon Sep 17 00:00:00 2001 From: Melissa Linkert Date: Fri, 3 Dec 2021 12:42:13 -0600 Subject: [PATCH 4/5] Change row_index and column_index to rowIndex and columnIndex --- latest/index.bs | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index 785a4d05..e0b6a5f7 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -440,9 +440,9 @@ custom attributes of the plate group under the `plate` key. The `path` MUST consist of a `name` in the `rows` list, a file separator (`/`), and a `name` from the `columns` list, in that order. The `path` MUST NOT contain additional leading or trailing directories. - Each well object MUST contain both a `row_index` key identifying the index into - the `rows` list and a `column_index` key indentifying the index into - the `columns` list. `row_index` and `column_index` MUST be 0-based. + Each well object MUST contain both a `rowIndex` key identifying the index into + the `rows` list and a `columnIndex` key indentifying the index into + the `columns` list. `rowIndex` and `columnIndex` MUST be 0-based. For example the following JSON object defines a plate with two acquisitions and @@ -489,33 +489,33 @@ For example the following JSON object defines a plate with two acquisitions and "wells": [ { "path": "A/1", - "row_index": 0, - "column_index": 0 + "rowIndex": 0, + "columnIndex": 0 }, { "path": "A/2" - "row_index": 0, - "column_index": 1 + "rowIndex": 0, + "columnIndex": 1 }, { "path": "A/3" - "row_index": 0, - "column_index": 2 + "rowIndex": 0, + "columnIndex": 2 }, { "path": "B/1" - "row_index": 1, - "column_index": 0 + "rowIndex": 1, + "columnIndex": 0 }, { "path": "B/2" - "row_index": 1, - "column_index": 1 + "rowIndex": 1, + "columnIndex": 1 }, { "path": "B/3" - "row_index": 1, - "column_index": 2 + "rowIndex": 1, + "columnIndex": 2 } ] } @@ -604,13 +604,13 @@ The following JSON object defines a sparse plate with one acquisition and "wells": [ { "path": "C/5" - "row_index": 2, - "column_index": 4 + "rowIndex": 2, + "columnIndex": 4 }, { "path": "D/7" - "row_index": 3, - "column_index": 6 + "rowIndex": 3, + "columnIndex": 6 } ] } From 3c31c14269bb362bcc4444adfc789c873b4cae0e Mon Sep 17 00:00:00 2001 From: Melissa Linkert Date: Thu, 9 Dec 2021 11:46:11 -0600 Subject: [PATCH 5/5] Relax row/well group requirement and clarify naming expectations --- latest/index.bs | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/latest/index.bs b/latest/index.bs index e0b6a5f7..eaf6d6fc 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -171,8 +171,8 @@ dataset. Three groups MUST be defined above the images: collection of wells organized in rows and columns. It MUST implement the [plate specification](#plate-md) -A well row group MUST NOT be present if there are no images in the well row. -A well group MUST NOT be present if there are no images in the well. +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. 
@@ -420,7 +420,11 @@ custom attributes of the plate group under the `plate` key.
       object defines the properties of the column at the index of the object
       in the list. Each column in the physical plate MUST be defined, even
       if no wells in the column are defined. Each defined column MUST contain
-      a `name` key specifying the column name.
+      a `name` key specifying the column name. The `name` MUST contain only
+      alphanumeric characters, MUST be case-sensitive, and MUST NOT be a
+      duplicate of any 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`).
   
field_count

   
An integer defining the maximum number of fields per view across all
       wells.

@@ -431,7 +435,11 @@ custom attributes of the plate group under the `plate` key.
       defines the properties of the row at the index of the object in the
       list. Each row in the physical plate MUST be defined, even if no wells
       in the row are defined. Each defined row MUST contain a `name` key
-      specifying the row name.
+      specifying the row name. The `name` MUST contain only alphanumeric
+      characters, MUST be case-sensitive, and MUST NOT be a duplicate
+      of any other `name` in the `rows` list. Care SHOULD be taken to avoid
+      collisions on case-insensitive filesystems (e.g. avoid using both `Aa`
+      and `aA`).
   
version

   
A string defining the version of the specification.

   
wells

@@ -442,7 +450,9 @@ custom attributes of the plate group under the `plate` key.
       additional leading or trailing directories.
       Each well object MUST contain both a `rowIndex` key identifying the index into
       the `rows` list and a `columnIndex` key indentifying the index into
-      the `columns` list. `rowIndex` and `columnIndex` MUST be 0-based.
+      the `columns` list. `rowIndex` and `columnIndex` MUST be 0-based.
+      The `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