Merge pull request #812 from CitrineInformatics/feature/pla-11071-local-attribute

PLA-11071: Add LocalAttribute to variable definition set

Author: kroenlein

docs/source/data_extraction.rst

@@ -233,6 +233,7 @@ There are several ways to define variables that take their values from Attribute
   * :class:`~citrine.gemtables.variables.AttributeInOutput`: for when attributes occur both in a process output and one or more of its inputs
   * :class:`~citrine.gemtables.variables.IngredientQuantityByProcessAndName`: for the specific case of the volume fraction, mass fraction, number fraction, or absolute quantity of an ingredient
   * :class:`~citrine.gemtables.variables.IngredientQuantityInOutput`: for the quantity of an ingredient between the terminal material and a given set of processes (useful for ingredients used in multiple processes)
+  * :class:`~citrine.gemtables.variables.LocalAttribute`: for retrieving the attribute from the terminal material or its attached process or measurements (useful for attributes found on multiple materials)
   * :class:`~citrine.gemtables.variables.LocalIngredientQuantity`: for the quantity of an ingredient used in the process creating the terminal material (useful for ingredients used in multiple processes)
 
 * Identifiers

src/citrine/__version__.py

@@ -1 +1 @@
-__version__ = '1.57.0'
+__version__ = '1.58.0'

src/citrine/gemtables/variables.py

@@ -1,6 +1,6 @@
 """Variable definitions for GEM Tables."""
 from abc import abstractmethod
-from typing import Type, Optional, List, Union
+from typing import Type, Optional, List, Union, Tuple
 from uuid import UUID
 
 from deprecation import deprecated
@@ -78,9 +78,9 @@ def get_type(cls, data) -> Type[Serializable]:
             raise ValueError("Can only get types from dicts with a 'type' key")
         types: List[Type[Serializable]] = [
             TerminalMaterialInfo, AttributeByTemplate, AttributeByTemplateAfterProcessTemplate,
-            AttributeByTemplateAndObjectTemplate, IngredientIdentifierByProcessTemplateAndName,
-            IngredientLabelByProcessAndName, IngredientLabelsSetByProcessAndName,
-            IngredientQuantityByProcessAndName,
+            AttributeByTemplateAndObjectTemplate, LocalAttribute,
+            IngredientIdentifierByProcessTemplateAndName, IngredientLabelByProcessAndName,
+            IngredientLabelsSetByProcessAndName, IngredientQuantityByProcessAndName,
             TerminalMaterialIdentifier, AttributeInOutput,
             IngredientIdentifierInOutput, IngredientLabelsSetInOutput, IngredientQuantityInOutput,
             LocalIngredientIdentifier, LocalIngredientLabelsSet, LocalIngredientQuantity,
@@ -143,7 +143,7 @@ class AttributeByTemplate(Serializable['AttributeByTemplate'], Variable):
         sequence of column headers
     template: Union[UUID, str, LinkByUID, AttributeTemplate]
         attribute template that identifies the attribute to assign to the variable
-    attribute_constraints: list[list[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
+    attribute_constraints: List[Tuple[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
         Optional
         constraints on object attributes in the target object that must be satisfied. Constraints
         are expressed as Bounds.  Attributes are expressed with links. The attribute that the
@@ -166,7 +166,7 @@ class AttributeByTemplate(Serializable['AttributeByTemplate'], Variable):
     typ = properties.String('type', default="attribute_by_template", deserializable=False)
 
     attribute_type = Union[UUID, str, LinkByUID, AttributeTemplate]
-    constraint_type = Union[attribute_type, BaseBounds]
+    constraint_type = Tuple[attribute_type, BaseBounds]
 
     def _attrs(self) -> List[str]:
         return ["name", "headers", "template", "attribute_constraints", "type_selector", "typ"]
@@ -176,7 +176,7 @@ def __init__(self,
                  *,
                  headers: List[str],
                  template: attribute_type,
-                 attribute_constraints: Optional[List[List[constraint_type]]] = None,
+                 attribute_constraints: Optional[List[constraint_type]] = None,
                  type_selector: DataObjectTypeSelector = DataObjectTypeSelector.PREFER_RUN):
         self.name = name
         self.headers = headers
@@ -200,7 +200,7 @@ class AttributeByTemplateAfterProcessTemplate(
         attribute template that identifies the attribute to assign to the variable
     process_template: Union[UUID, str, LinkByUID, ProcessTemplate]
         process template that identifies the originating process
-    attribute_constraints: list[list[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
+    attribute_constraints: List[Tuple[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
         Optional
         constraints on object attributes in the target object that must be satisfied. Constraints
         are expressed as Bounds.  Attributes are expressed with links. The attribute that the
@@ -225,7 +225,7 @@ class AttributeByTemplateAfterProcessTemplate(
 
     attribute_type = Union[UUID, str, LinkByUID, AttributeTemplate]
     process_type = Union[UUID, str, LinkByUID, ProcessTemplate]
-    constraint_type = Union[attribute_type, BaseBounds]
+    constraint_type = Tuple[attribute_type, BaseBounds]
 
     def _attrs(self) -> List[str]:
         return ["name", "headers", "attribute_template", "process_template",
@@ -237,7 +237,7 @@ def __init__(self,
                  headers: List[str],
                  attribute_template: attribute_type,
                  process_template: process_type,
-                 attribute_constraints: Optional[List[List[constraint_type]]] = None,
+                 attribute_constraints: Optional[List[constraint_type]] = None,
                  type_selector: DataObjectTypeSelector = DataObjectTypeSelector.PREFER_RUN):
         self.name = name
         self.headers = headers
@@ -267,7 +267,7 @@ class AttributeByTemplateAndObjectTemplate(
         attribute template that identifies the attribute to assign to the variable
     object_template: Union[UUID, str, LinkByUID, BaseTemplate]
         template that identifies the associated object
-    attribute_constraints: list[list[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
+    attribute_constraints: List[Tuple[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
         Optional
         constraints on object attributes in the target object that must be satisfied. Constraints
         are expressed as Bounds.  Attributes are expressed with links. The attribute that the
@@ -292,7 +292,7 @@ class AttributeByTemplateAndObjectTemplate(
 
     attribute_type = Union[UUID, str, LinkByUID, AttributeTemplate]
     object_type = Union[UUID, str, LinkByUID, BaseTemplate]
-    constraint_type = Union[attribute_type, BaseBounds]
+    constraint_type = Tuple[attribute_type, BaseBounds]
 
     def _attrs(self) -> List[str]:
         return ["name", "headers", "attribute_template", "object_template",
@@ -304,7 +304,7 @@ def __init__(self,
                  headers: List[str],
                  attribute_template: attribute_type,
                  object_template: object_type,
-                 attribute_constraints: Optional[List[List[constraint_type]]] = None,
+                 attribute_constraints: Optional[List[constraint_type]] = None,
                  type_selector: DataObjectTypeSelector = DataObjectTypeSelector.PREFER_RUN):
         self.name = name
         self.headers = headers
@@ -315,6 +315,60 @@ def __init__(self,
         self.type_selector = type_selector
 
 
+class LocalAttribute(Serializable['LocalAttribute'], Variable):
+    """[ALPHA] Attribute marked by an attribute template for the root of a material history tree.
+
+    Parameters
+    ----------
+    name: str
+        a short human-readable name to use when referencing the variable
+    headers: list[str]
+        sequence of column headers
+    template: Union[UUID, str, LinkByUID, AttributeTemplate]
+        attribute template that identifies the attribute to assign to the variable
+    attribute_constraints: List[Tuple[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
+        Optional
+        constraints on object attributes in the target object that must be satisfied. Constraints
+        are expressed as Bounds.  Attributes are expressed with links. The attribute that the
+        variable is being set to may be the target of a constraint as well.
+    type_selector: DataObjectTypeSelector
+        strategy for selecting data object types to consider when matching, defaults to PREFER_RUN
+
+    """
+
+    name = properties.String('name')
+    headers = properties.List(properties.String, 'headers')
+    template = properties.Object(LinkByUID, 'template')
+    attribute_constraints = properties.Optional(
+        properties.List(
+            properties.SpecifiedMixedList(
+                [properties.Object(LinkByUID), properties.Object(BaseBounds)]
+            )
+        ), 'attribute_constraints')
+    type_selector = properties.Enumeration(DataObjectTypeSelector, "type_selector")
+    typ = properties.String('type', default="local_attribute", deserializable=False)
+
+    attribute_type = Union[UUID, str, LinkByUID, AttributeTemplate]
+    constraint_type = Tuple[attribute_type, BaseBounds]
+
+    def _attrs(self) -> List[str]:
+        return ["name", "headers", "template", "attribute_constraints", "type_selector", "typ"]
+
+    def __init__(self,
+                 name: str,
+                 *,
+                 headers: List[str],
+                 template: attribute_type,
+                 attribute_constraints: Optional[List[constraint_type]] = None,
+                 type_selector: DataObjectTypeSelector = DataObjectTypeSelector.PREFER_RUN):
+        self.name = name
+        self.headers = headers
+        self.template = _make_link_by_uid(template)
+        self.attribute_constraints = None if attribute_constraints is None \
+            else [(_make_link_by_uid(x[0]), x[1]) for x in attribute_constraints]
+        self.type_selector = type_selector
+
+
 class IngredientIdentifierByProcessTemplateAndName(
         Serializable['IngredientIdentifierByProcessAndName'], Variable):
     """[ALPHA] Ingredient identifier associated with a process template and a name.
@@ -614,7 +668,7 @@ class AttributeInOutput(Serializable['AttributeInOutput'], Variable):
     process_templates: list[LinkByUID]
         process templates that should not be traversed through when searching for a matching
         attribute.  The attribute may be present in these processes but not their ingredients.
-    attribute_constraints: list[list[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
+    attribute_constraints: List[Tuple[Union[UUID, str, LinkByUID, AttributeTemplate], Bounds]]
         Optional
         constraints on object attributes in the target object that must be satisfied. Constraints
         are expressed as Bounds.  Attributes are expressed with links. The attribute that the
@@ -639,7 +693,7 @@ class AttributeInOutput(Serializable['AttributeInOutput'], Variable):
 
     attribute_type = Union[UUID, str, LinkByUID, AttributeTemplate]
     process_type = Union[UUID, str, LinkByUID, ProcessTemplate]
-    constraint_type = Union[attribute_type, BaseBounds]
+    constraint_type = Tuple[attribute_type, BaseBounds]
 
     def _attrs(self) -> List[str]:
         return ["name", "headers", "attribute_template", "process_templates",
@@ -651,7 +705,7 @@ def __init__(self,
                  headers: List[str],
                  attribute_template: attribute_type,
                  process_templates: List[process_type],
-                 attribute_constraints: Optional[List[List[constraint_type]]] = None,
+                 attribute_constraints: Optional[List[constraint_type]] = None,
                  type_selector: DataObjectTypeSelector = DataObjectTypeSelector.PREFER_RUN):
         self.name = name
         self.headers = headers

tests/gemtable/test_variables.py

@@ -13,6 +13,7 @@
     AttributeByTemplateAfterProcessTemplate(name="density", headers=["density"], attribute_template=LinkByUID(scope="template", id="density"), process_template=LinkByUID(scope="template", id="process")),
     AttributeByTemplateAndObjectTemplate(name="density", headers=["density"], attribute_template=LinkByUID(scope="template", id="density"), object_template=LinkByUID(scope="template", id="object")),
     AttributeInOutput(name="density", headers=["density"], attribute_template=LinkByUID(scope="template", id="density"), process_templates=[LinkByUID(scope="template", id="object")]),
+    LocalAttribute(name="density", headers=["density"], template=LinkByUID(scope="templates", id="density"), attribute_constraints=[[LinkByUID(scope="templates", id="density"), RealBounds(0, 100, "g/cm**3")]]),
     IngredientIdentifierByProcessTemplateAndName(name="ingredient id", headers=["density"], process_template=LinkByUID(scope="template", id="process"), ingredient_name="ingredient", scope="scope"),
     IngredientIdentifierInOutput(name="ingredient id", headers=["ingredient id"], ingredient_name="ingredient", process_templates=[LinkByUID(scope="template", id="object")], scope="scope"),
     LocalIngredientIdentifier(name="ingredient id", headers=["ingredient id"], ingredient_name="ingredient", scope="scope"),