reaction role (#684)

* - extended ReactionRoleType, added validation functions
- comments about stoichiometry convention

* - move stoichiometry convention to README.md

* update comments on `reaction_role`

* `compile_proto_wrappers.sh && format.sh`
- libprotoc 22.3
- Ubuntu clang-format version 14.0.0-1ubuntu1
- go version go1.20.5 linux/amd64
- Ubuntu clang-format version 14.0.0-1ubuntu1

* `compile_proto_wrappers.sh && format.sh`
- libprotoc 22.3
- Ubuntu clang-format version 14.0.0-1ubuntu1
- go version go1.20.5 linux/amd64
- Ubuntu clang-format version 14.0.0-1ubuntu1

---------

Co-authored-by: Steven Kearnes <skearnes@relaytx.com>

README.md

@@ -39,3 +39,20 @@ $ pip install -e .
 
 If you make changes to the protocol buffer definitions, [install](https://grpc.io/docs/protoc-installation/) `protoc`
 and run `./compile_proto_wrappers.sh` to rebuild the wrappers.
+
+## Conventions
+
+### 1. convention: compound stoichiometry
+
+##### Created: 2023.07.04
+
+##### Last updated: 2023.07.04
+
+##### Description: 
+1. The preferred field for compound stoichiometry is the map `Compound.features` or `ProductCompound.features`.
+2. The key should be "stoichiometric_coefficient" or "stoichiometric_ratio".
+3. The value should be a Data mesaage with its float_value representing the compound's stoichiometric coefficient or ratio.SInformation about also put stoichiometry ratio/coefficient here
+
+##### Related links: 
+[#683](https://github.com/open-reaction-database/ord-schema/issues/683) 
+[#684](https://github.com/open-reaction-database/ord-schema/pull/684)

js/ord-schema/proto/reaction_pb.js

@@ -4814,7 +4814,9 @@ proto.ord.ReactionRole.ReactionRoleType = {
   WORKUP: 5,
   INTERNAL_STANDARD: 6,
   AUTHENTIC_STANDARD: 7,
-  PRODUCT: 8
+  PRODUCT: 8,
+  BYPRODUCT: 9,
+  SIDE_PRODUCT: 10
 };
 
 

ord_schema/validations.py

@@ -783,9 +783,18 @@ def validate_reaction_workup(message: reaction_pb2.ReactionWorkup):
 
 def validate_reaction_outcome(message: reaction_pb2.ReactionOutcome):
     # pylint: disable=singleton-comparison
-    # Can only have one desired product
-    if sum(product.is_desired_product for product in message.products) > 1:
-        warnings.warn("Cannot have more than one desired product!", ValidationError)
+    # *Usually* there should be at most one PRODUCT & is_desired_product
+    ndp = sum(
+        product.is_desired_product
+        for product in message.products
+        if product.reaction_role == reaction_pb2.ReactionRole.ReactionRoleType.PRODUCT
+    )
+    if ndp > 1:
+        warnings.warn(
+            f"Usually at most one (reaction_role == PRODUCT & is_desired_product) product, but we have: {ndp}",
+            ValidationWarning,
+        )
+
     # Check key values for product analyses
     # NOTE(ccoley): Could use any(), but using expanded loops for clarity
     analysis_keys = list(message.analyses.keys())
@@ -820,6 +829,10 @@ def validate_product_compound(message: reaction_pb2.ProductCompound):
     except ValueError as error:
         warnings.warn(str(error), ValidationWarning)
 
+    if message.is_desired_product:
+        if message.reaction_role == reaction_pb2.ReactionRole.ReactionRoleType.SIDE_PRODUCT:
+            warnings.warn("a product cannot be (SIDE_PRODUCT & is_desired_product)", ValidationError)
+
 
 def validate_texture(message: reaction_pb2.ProductCompound.Texture):
     check_type_and_details(message)

proto/reaction.proto

@@ -287,6 +287,14 @@ message ReactionRole {
     // A product can be any species produced by the reaction, whether desired
     // or undesired.
     PRODUCT = 8;
+    // When there is one intended chemical equation:
+    // - Set `is_desired_product=True` to indicate a desired product.
+    // - Use BYPRODUCT to indicate a chemical species that is an expected result
+    // of the reaction but is not the product of interest.
+    // - Use SIDE_PRODUCT to indicate the product of a side reaction.
+    // - See https://doi.org/10.1021/op300317g for a discussion of these terms.
+    BYPRODUCT = 9;
+    SIDE_PRODUCT = 10;
   }
 }