From 8f306b06121e19609715ea18265643efda9fc1cc Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 7 Jul 2021 19:50:17 +0100 Subject: [PATCH 1/5] Bump spec version number to v1.1.0~develop --- optimade.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index 472d61dbd..9c0f49457 100644 --- a/optimade.rst +++ b/optimade.rst @@ -1,6 +1,6 @@ -================================= -OPTIMADE API specification v1.1.0 -================================= +========================================= +OPTIMADE API specification v1.1.0~develop +========================================= .. comment From 27ccec78bd971ebe58a03355612665021412d221 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Tue, 28 Dec 2021 13:31:01 +0100 Subject: [PATCH 2/5] Added section to describe a group property which could also be used to store biomolecular data. --- optimade.rst | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/optimade.rst b/optimade.rst index e4a72765d..6d1033eb1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2465,6 +2465,114 @@ Relationships with calculations MAY be used to indicate provenance where a struc Appendices ========== +Domain Specific Fields +---------------------- + +The fields below are all optional and are only used within specific research fields. + +group_type +~~~~~~~~~~ + +- **Description**: For each type of chemical group/molecule in the system there is a dictionary that describes this group/molecule. + Databases are allowed to add more properties as long as the properties are prefixed with the database specific prefix. + +- **Type**: list of dictionaries with the properties: + - :property:`name`: string (REQUIRED) + - :property:`molecular_formula`: string (OPTIONAL) + - :property:`mass`: float (OPTIONAL) + - :property:`subgroups`: list of strings (OPTIONAL) +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations. When the :property:`groups` property is present the :property:`group_type property` MUST, however, be present as well. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, only a subset of the filter features MAY be supported. + - **name**: REQUIRED; gives the name of the group_type; + - The **name** value MUST be unique in the :property:`group_types` list. + - Strings of 3 characters or less MUST match the strings belonging to this group as defined by wwPDB at ``_. + - **molecular_formula**: OPTIONAL; The molecular formula of the molecule/group described in this group type. + - Element symbols MUST have proper capitalization (e.g., :val:`"Si"`, not :VAL:`"SI"` for "silicon"). + - Elements MUST be placed in alphabetical order, followed by an integer describing the number atoms of this element in the group. + - No spaces or separators are allowed. + - **mass**: OPTIONAL; The mass of the molecule or group in a.m.u. + - **sub_groups**: OPTIONAL; A list of strings containing the :property:`group_types` contained within this group. + +.. code:: jsonc + { + "group_type":[ + { + "name" : "PME", + "molecular_formula": "C14H18N2O5", + "mass" : 294.307, + "subgroups":[ + "PHE", + "ASP", + ] + },{ + "name" : "PHE", + "molecular_formula": "C9H9NO", + "mass" : 163.176, + },{ + "name": "ASP", + "molecular_formula": "C4H6NO3", + "mass" : 116.096, + } + ] + } + +groups +~~~~~~ + +- **Description**: A particular group of atoms and other subgroups. + Databases are allowed to add more properties as long as the properties are prefixed with the database specific prefix. +- **Type**: list of dictionaries with the properties: + - :property:`group_id`: string (REQUIRED) + - :property:`type`: string (REQUIRED) + - :property:`parts`: list of strings and integers (REQUIRED) + - :property:`residue_sequence_number`: integer (OPTIONAL) + - :property:`insertion_code`: string (OPTIONAL) +- **Requirements/Conventions**: + - **Query**: Support for queries on this property is OPTIONAL. + If supported, only a subset of the filter features MAY be supported. + - **Support**: OPTIONAL support in implementations. When the :property:`group_type property` property is present the :property:`groups` property MUST be present as well. + - **group_id**: REQUIRED; A string that is unique for each group. + - **type**: REQUIRED; The :property:`group_type` of this group. + - **parts**: REQUIRED; A list containing :property:`group_id` strings of groups that are part of this group and integers referring to the index of `cartesian_site_positions`_, that belong to this group and are not in one of the sub groups. + Circular references are not allowed, i.e. a group is not allowed to refer back to itself even if it is via another group. + - **residue_sequence_number**: An integers describing the position of the group/residue in a chain/group. + This matches the residue sequence number field in the of the PDB file format. + There is therefore no guarantee that these numbers are ordered or unique. + - **insertion_code**: If two groups/residues have the same residue_sequence_number the insertion_code is used to distinguish them. + Two groups that both belong to the same super group MUST have distinct combinations of the :property:`residue_sequence_number` and :property:`insertion_code`. + This matches the icode field in the of the PDB file format. + +- **Examples**: +.. code:: jsonc + { + "groups":[ + { + "group_id":"PME1", + "type": "PME", + "contains": [ + "PHE1", + "ASP1", + 1,2,3,4, + ], + },{ + "group_id":"PHE1", + "type": "PME", + "contains": [5,6,7.8.9.10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25], + "residue_sequence_number": 1 + "insertion_code": null + },{ + "group_id":"ASP1" + "type": "ASP" + "contains": [26,27,28,29,30,31,32,33,34,35,36,37,38,39] + "residue_sequence_number": 2 + "insertion_code": "A" + } + ] + } + + The Filter Language EBNF Grammar -------------------------------- From cdd2404b2faf8c967be591733355dbafa333bf1a Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 29 Dec 2021 12:40:38 +0100 Subject: [PATCH 3/5] Split parts property "parts" into sub_groups and sites so we no longer mixes types. --- optimade.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 6d1033eb1..bb1f5f471 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2485,7 +2485,7 @@ group_type - **Support**: OPTIONAL support in implementations. When the :property:`groups` property is present the :property:`group_type property` MUST, however, be present as well. - **Query**: Support for queries on this property is OPTIONAL. If supported, only a subset of the filter features MAY be supported. - - **name**: REQUIRED; gives the name of the group_type; + - **name**: REQUIRED; The name of the group_type; - The **name** value MUST be unique in the :property:`group_types` list. - Strings of 3 characters or less MUST match the strings belonging to this group as defined by wwPDB at ``_. - **molecular_formula**: OPTIONAL; The molecular formula of the molecule/group described in this group type. @@ -2526,7 +2526,8 @@ groups - **Type**: list of dictionaries with the properties: - :property:`group_id`: string (REQUIRED) - :property:`type`: string (REQUIRED) - - :property:`parts`: list of strings and integers (REQUIRED) + - :property:`sub_groups`: list of strings (REQUIRED) + - :property:`sites`: list of integers (REQUIRED) - :property:`residue_sequence_number`: integer (OPTIONAL) - :property:`insertion_code`: string (OPTIONAL) - **Requirements/Conventions**: @@ -2535,8 +2536,9 @@ groups - **Support**: OPTIONAL support in implementations. When the :property:`group_type property` property is present the :property:`groups` property MUST be present as well. - **group_id**: REQUIRED; A string that is unique for each group. - **type**: REQUIRED; The :property:`group_type` of this group. - - **parts**: REQUIRED; A list containing :property:`group_id` strings of groups that are part of this group and integers referring to the index of `cartesian_site_positions`_, that belong to this group and are not in one of the sub groups. - Circular references are not allowed, i.e. a group is not allowed to refer back to itself even if it is via another group. + - **sub_groups**: REQUIRED; A list containing :property:`group_id` strings of groups that are part of this group. Circular references are not allowed, i.e. a group is not allowed to refer back to itself even if it is via another group. + - **sites**; REQUIRED; A list of integers referring to the index of `cartesian_site_positions`_, that belong to this group and are not in one of the sub groups. + - **residue_sequence_number**: An integers describing the position of the group/residue in a chain/group. This matches the residue sequence number field in the of the PDB file format. There is therefore no guarantee that these numbers are ordered or unique. @@ -2545,6 +2547,7 @@ groups This matches the icode field in the of the PDB file format. - **Examples**: + .. code:: jsonc { "groups":[ From 9113e0b61c2ed986c9433b17f4314b10effd664b Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 29 Dec 2021 13:34:54 +0100 Subject: [PATCH 4/5] Added that the index of the first site is zero. --- optimade.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/optimade.rst b/optimade.rst index bb1f5f471..ef8c2c821 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2538,7 +2538,7 @@ groups - **type**: REQUIRED; The :property:`group_type` of this group. - **sub_groups**: REQUIRED; A list containing :property:`group_id` strings of groups that are part of this group. Circular references are not allowed, i.e. a group is not allowed to refer back to itself even if it is via another group. - **sites**; REQUIRED; A list of integers referring to the index of `cartesian_site_positions`_, that belong to this group and are not in one of the sub groups. - + - - **residue_sequence_number**: An integers describing the position of the group/residue in a chain/group. This matches the residue sequence number field in the of the PDB file format. There is therefore no guarantee that these numbers are ordered or unique. @@ -2557,19 +2557,19 @@ groups "contains": [ "PHE1", "ASP1", - 1,2,3,4, + 0,1,2,3, ], },{ "group_id":"PHE1", "type": "PME", - "contains": [5,6,7.8.9.10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25], + "contains": [4,5,6,7.8.9.10,11,12,13,14,15,16,17,18,19,20,21,22,23,24], "residue_sequence_number": 1 "insertion_code": null },{ "group_id":"ASP1" "type": "ASP" - "contains": [26,27,28,29,30,31,32,33,34,35,36,37,38,39] - "residue_sequence_number": 2 + "contains": [26,27,28,29,30,31,32,33,34,35,36,37,38] + "residue_sequ,ence_number": 2 "insertion_code": "A" } ] From f51cd9f9572ee2ec3308a78862a1880611ede098 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Wed, 29 Dec 2021 13:49:13 +0100 Subject: [PATCH 5/5] Made correction to example of the groups property. --- optimade.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/optimade.rst b/optimade.rst index ef8c2c821..121f118b2 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2538,7 +2538,7 @@ groups - **type**: REQUIRED; The :property:`group_type` of this group. - **sub_groups**: REQUIRED; A list containing :property:`group_id` strings of groups that are part of this group. Circular references are not allowed, i.e. a group is not allowed to refer back to itself even if it is via another group. - **sites**; REQUIRED; A list of integers referring to the index of `cartesian_site_positions`_, that belong to this group and are not in one of the sub groups. - - + The index of the first site is 0. - **residue_sequence_number**: An integers describing the position of the group/residue in a chain/group. This matches the residue sequence number field in the of the PDB file format. There is therefore no guarantee that these numbers are ordered or unique. @@ -2552,24 +2552,26 @@ groups { "groups":[ { - "group_id":"PME1", + "group_id": "PME1", "type": "PME", - "contains": [ + "sub_groups": [ "PHE1", "ASP1", - 0,1,2,3, ], + "sites":[0,1,2,3] },{ - "group_id":"PHE1", + "group_id": "PHE1", "type": "PME", - "contains": [4,5,6,7.8.9.10,11,12,13,14,15,16,17,18,19,20,21,22,23,24], - "residue_sequence_number": 1 + "sites": [4,5,6,7.8.9.10,11,12,13,14,15,16,17,18,19,20,21,22,23,24], + "sub_groups": [], + "residue_sequence_number": 1, "insertion_code": null },{ - "group_id":"ASP1" - "type": "ASP" - "contains": [26,27,28,29,30,31,32,33,34,35,36,37,38] - "residue_sequ,ence_number": 2 + "group_id": "ASP1", + "type": "ASP", + "sub_groups": [], + "sites": [26,27,28,29,30,31,32,33,34,35,36,37,38], + "residue_sequ,ence_number": 2, "insertion_code": "A" } ]