From 4ee4fa18872a90d2fea6cfefbf444b331b5f2f83 Mon Sep 17 00:00:00 2001 From: Sebastien Besson Date: Thu, 26 May 2022 21:40:24 +0100 Subject: [PATCH 1/5] Clarify types and requirements levels for the plate/well specification This commit rewrites the section and ensures that: - each key has a requirement level specified as MUST/SHOULD/MAY - the type for the value of each key is explicitly defined --- 0.4/index.bs | 123 ++++++++++++++++++++++++--------------------------- 1 file changed, 59 insertions(+), 64 deletions(-) diff --git a/0.4/index.bs b/0.4/index.bs index d4f4b88e..64725fba 100644 --- a/0.4/index.bs +++ b/0.4/index.bs @@ -437,59 +437,56 @@ above). ---------------------------- For high-content screening datasets, the plate layout can be found under the -custom attributes of the plate group under the `plate` key. - -
-
acquisitions
-
An optional list of JSON objects defining the acquisitions for a given - plate. Each acquisition object MUST contain an `id` key providing an - unique identifier within the context of the plate to which fields of - view can refer to. It SHOULD contain a `name` key identifying the name - of the acquisition. It SHOULD contain a `maximumfieldcount` key - indicating the maximum number of fields of view for the acquisition. It - MAY contain a `description` key providing a description for the - acquisition. It MAY contain a `startime` and/or `endtime` key specifying - the start and/or end timestamp of the acquisition using an epoch - string.
-
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. 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. 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.
-
name
-
A string defining the name of the plate.
-
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. 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. 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
-
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 `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 `rowIndex`, `columnIndex`, and `path` MUST all refer to the same - row/column pair.
-
+custom attributes of the plate group under the `plate` key in the group-level metadata. + +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 +within the context of the plate to which fields of view 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 an integer indicating the maximum number of fields of view 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 `startime` and/or `endtime` key whose values MUST be integer epoch timestamps specifying +the start and/or end timestamp of the acquisition. + +The `plate` dictionary MUST contain a `columns` key whose value MUST be a list of JSON objects +defining the columns of the plate. Each column object 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 column object MUST +contain a `name` key whole value is a string 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`). + +The `plate` dictionary SHOULD contain a `field_count` key whose value MUST be an integer +defining the maximum number of fields per view across all wells. + +The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the +name of the plate. + +The `plate` dictionary MUST contain a `rows` key whose value MUST be a list of JSON objects +defining the rows of the plate. Each row object object 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 whose value MUST be a string defining 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`). + +The `plate` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the +version of the plate specificaton. + +The `plate` dictionary MUST contain a `wells` key whose value MUST be a list of JSON objects +defining the wells of the plate. Each well object MUST contain a `path` key whose value MUST +be a string specifying 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 `rowIndex` key whose value MUST be an integer identifying +the index into the `rows` list and a `columnIndex` key whose value MUST be an integer indentifying +the index into 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 6 wells (2 rows and 3 columns), containing up to 2 fields of view per acquisition. @@ -514,17 +511,15 @@ 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 well group. -
-
images
-
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 - 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
-
A string defining the version of the specification.
-
+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. If multiple +acquisitions were performed in the plate, it MUST contain an `acquisition` key whose value +MUST be an integer identifying the acquisition which MUST match one of acquisition JSON +objects defined in the plate metadata (see #plate-md). + +The `well` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the +version of the well specificaton. 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 From bbc46783e7ee3ae144654b86e7cce382aba2d7f6 Mon Sep 17 00:00:00 2001 From: Sebastien Besson Date: Fri, 27 May 2022 12:27:57 +0100 Subject: [PATCH 2/5] Improve wording as per Melissa's suggestions --- 0.4/index.bs | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/0.4/index.bs b/0.4/index.bs index 64725fba..6a48de90 100644 --- a/0.4/index.bs +++ b/0.4/index.bs @@ -442,32 +442,33 @@ 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 -within the context of the plate to which fields of view can refer to (see #well-md). +greater than of equal to 0 within the context of the plate to which fields of view 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 an integer indicating the maximum number of fields of view for the +key whose value MUST be a positive integer indicating the maximum number of fields of view 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 `startime` and/or `endtime` key whose values MUST be integer epoch timestamps specifying +a `starttime` and/or `endtime` key whose values MUST be integer epoch timestamps specifying the start and/or end timestamp of the acquisition. The `plate` dictionary MUST contain a `columns` key whose value MUST be a list of JSON objects -defining the columns of the plate. Each column object object defines the properties of +defining the columns of the plate. Each column 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 column object MUST -contain a `name` key whole value is a string specifying the column name. The `name` MUST +contain a `name` key whose value is a string 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`). -The `plate` dictionary SHOULD contain a `field_count` key whose value MUST be an integer +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. The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the name of the plate. The `plate` dictionary MUST contain a `rows` key whose value MUST be a list of JSON objects -defining the rows of the plate. Each row object object defines the properties of +defining the rows of the plate. Each row object 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 whose value MUST be a string defining the row name. The `name` MUST @@ -513,10 +514,11 @@ 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. If multiple -acquisitions were performed in the plate, it MUST contain an `acquisition` key whose value -MUST be an integer identifying the acquisition which MUST match one of acquisition JSON -objects defined in the plate metadata (see #plate-md). +`path` key whose value MUST be a string specifying the path to the field of view. 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 +which MUST match one of the acquisition JSON objects defined in the plate metadata (see #plate-md). The `well` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the version of the well specificaton. From cbefa91a7fe569a89cad7b8b797a1dcab2108cc5 Mon Sep 17 00:00:00 2001 From: Sebastien Besson Date: Fri, 27 May 2022 12:28:20 +0100 Subject: [PATCH 3/5] Add acquisition description to the plate schema --- 0.4/schemas/plate.schema | 4 ++++ latest/schemas/plate.schema | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/0.4/schemas/plate.schema b/0.4/schemas/plate.schema index d23d7e52..df7cfad0 100644 --- a/0.4/schemas/plate.schema +++ b/0.4/schemas/plate.schema @@ -28,6 +28,10 @@ "description": "The name of the acquisition", "type": "string" }, + "description": { + "description": "The description of the acquisition", + "type": "string" + }, "starttime": { "description": "The start timestamp of the acquisition, expressed as epoch time i.e. the number seconds since the Epoch", "type": "integer", diff --git a/latest/schemas/plate.schema b/latest/schemas/plate.schema index 417f156d..099f5bb4 100644 --- a/latest/schemas/plate.schema +++ b/latest/schemas/plate.schema @@ -28,6 +28,10 @@ "description": "The name of the acquisition", "type": "string" }, + "description": { + "description": "The description of the acquisition", + "type": "string" + }, "starttime": { "description": "The start timestamp of the acquisition, expressed as epoch time i.e. the number seconds since the Epoch", "type": "integer", From d950f3af5d37fecedecda1754fde828c2bf6ba50 Mon Sep 17 00:00:00 2001 From: Sebastien Besson Date: Fri, 27 May 2022 12:29:58 +0100 Subject: [PATCH 4/5] Port plate/well updates to latest specification --- 0.4/index.bs | 2 +- latest/index.bs | 125 +++++++++++++++++++++++------------------------- 2 files changed, 62 insertions(+), 65 deletions(-) diff --git a/0.4/index.bs b/0.4/index.bs index 6a48de90..09cca654 100644 --- a/0.4/index.bs +++ b/0.4/index.bs @@ -521,7 +521,7 @@ it MUST contain an `acquisition` key whose value MUST be an integer identifying which MUST match one of the acquisition JSON objects defined in the plate metadata (see #plate-md). The `well` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the -version of the well specificaton. +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 diff --git a/latest/index.bs b/latest/index.bs index 26bb77aa..58b8832f 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -439,59 +439,57 @@ above). ---------------------------- For high-content screening datasets, the plate layout can be found under the -custom attributes of the plate group under the `plate` key. - -
-
acquisitions
-
An optional list of JSON objects defining the acquisitions for a given - plate. Each acquisition object MUST contain an `id` key providing an - unique identifier within the context of the plate to which fields of - view can refer to. It SHOULD contain a `name` key identifying the name - of the acquisition. It SHOULD contain a `maximumfieldcount` key - indicating the maximum number of fields of view for the acquisition. It - MAY contain a `description` key providing a description for the - acquisition. It MAY contain a `startime` and/or `endtime` key specifying - the start and/or end timestamp of the acquisition using an epoch - string.
-
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. 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. 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.
-
name
-
A string defining the name of the plate.
-
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. 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. 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
-
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 `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 `rowIndex`, `columnIndex`, and `path` MUST all refer to the same - row/column pair.
-
+custom attributes of the plate group under the `plate` key in the group-level metadata. + +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 of equal to 0 within the context of the plate to which fields of view 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 +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 +the start and/or end timestamp of the acquisition. + +The `plate` dictionary MUST contain a `columns` key whose value MUST be 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. Each column in the physical plate +MUST be defined, even if no wells in the column are defined. Each column object MUST +contain a `name` key whose value is a string 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`). + +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. + +The `plate` dictionary SHOULD contain a `name` key whose value MUST be a string defining the +name of the plate. + +The `plate` dictionary MUST contain a `rows` key whose value MUST be 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. 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 whose value MUST be a string defining 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`). + +The `plate` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the +version of the plate specificaton. + +The `plate` dictionary MUST contain a `wells` key whose value MUST be a list of JSON objects +defining the wells of the plate. Each well object MUST contain a `path` key whose value MUST +be a string specifying 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 `rowIndex` key whose value MUST be an integer identifying +the index into the `rows` list and a `columnIndex` key whose value MUST be an integer indentifying +the index into 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 6 wells (2 rows and 3 columns), containing up to 2 fields of view per acquisition. @@ -516,17 +514,16 @@ 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 well group. -
-
images
-
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 - 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
-
A string defining the version of the specification.
-
+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` +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 +which MUST match one of the acquisition JSON objects defined in the plate metadata (see #plate-md). + +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 From c889ffa77ea07eeff220104404719c3721feb824 Mon Sep 17 00:00:00 2001 From: Sebastien Besson Date: Fri, 27 May 2022 16:49:33 +0100 Subject: [PATCH 5/5] Correct a few remaining typos --- 0.4/index.bs | 2 +- latest/index.bs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/0.4/index.bs b/0.4/index.bs index 09cca654..a0c3f83d 100644 --- a/0.4/index.bs +++ b/0.4/index.bs @@ -442,7 +442,7 @@ 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 of 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 fields of view 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` diff --git a/latest/index.bs b/latest/index.bs index 58b8832f..e2fc6bcf 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -444,7 +444,7 @@ 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 of 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 fields of view 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` @@ -479,7 +479,7 @@ 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`). The `plate` dictionary SHOULD contain a `version` key whose value MUST be a string specifying the -version of the plate specificaton. +version of the plate specification. The `plate` dictionary MUST contain a `wells` key whose value MUST be a list of JSON objects defining the wells of the plate. Each well object MUST contain a `path` key whose value MUST