bug(experiment): Comp types not handled correctly

Author: gegnew

cellengine/__init__.py

@@ -1,21 +1,41 @@
 # flake8: noqa
 __version__ = "0.1.0"
 
-from cellengine.utils.api_client.APIClient import APIClient
+try:
+    from typing import Literal
+except ImportError:
+    from typing_extensions import Literal
+
 from cellengine.resources.attachment import Attachment
 from cellengine.resources.compensation import Compensation
 from cellengine.resources.experiment import Experiment
 from cellengine.resources.fcs_file import FcsFile
 from cellengine.resources.gate import (
+    EllipseGate,
     Gate,
-    RectangleGate,
     PolygonGate,
-    EllipseGate,
-    SplitGate,
     QuadrantGate,
     RangeGate,
+    RectangleGate,
+    SplitGate,
 )
 from cellengine.resources.plot import Plot
 from cellengine.resources.population import Population
 from cellengine.resources.scaleset import ScaleSet
+from cellengine.utils.api_client.APIClient import APIClient
 from cellengine.utils.complex_population_builder import ComplexPopulationBuilder
+
+UNCOMPENSATED: int = 0
+"""Apply no compensation."""
+
+FILE_INTERNAL: int = -1
+"""
+Use the file's internal compensation matrix, if available. If not available, an
+error will be returned from API requests.
+"""
+
+PER_FILE: int = -2
+"""
+Use the compensation assigned to each individual FCS file. Not a valid value for
+`FcsFile.compensation`.
+"""

cellengine/resources/experiment.py

@@ -1,48 +1,46 @@
 from __future__ import annotations
-from datetime import datetime
-
-from marshmallow import fields
-from pandas.core.frame import DataFrame
-
-from cellengine.utils.dataclass_mixin import DataClassMixin, ReadOnly
 from dataclasses import dataclass, field
+from datetime import datetime
 import inspect
 from math import pi
-from custom_inherit import doc_inherit
-from typing import Any, Optional, Dict, Union, List
+from typing import Any, Dict, List, Optional, Union
 
+from custom_inherit import doc_inherit
 from dataclasses_json.cfg import config
+from marshmallow import fields
+from pandas.core.frame import DataFrame
 
 import cellengine as ce
-from cellengine.resources.population import Population
-from cellengine.resources.scaleset import ScaleSet
-from cellengine.resources.fcs_file import FcsFile
-from cellengine.resources.compensation import Compensation
+from cellengine.payloads.gate_utils import (
+    format_ellipse_gate,
+    format_polygon_gate,
+    format_quadrant_gate,
+    format_range_gate,
+    format_rectangle_gate,
+    format_split_gate,
+)
 from cellengine.resources.attachment import Attachment
+from cellengine.resources.compensation import Compensation
+from cellengine.resources.fcs_file import FcsFile
 from cellengine.resources.gate import (
+    EllipseGate,
     Gate,
-    RectangleGate,
     PolygonGate,
+    QuadrantGate,
     RangeGate,
+    RectangleGate,
     SplitGate,
-    EllipseGate,
-    QuadrantGate,
 )
+from cellengine.resources.population import Population
+from cellengine.resources.scaleset import ScaleSet
+from cellengine.utils.dataclass_mixin import DataClassMixin, ReadOnly
 from cellengine.utils.helpers import (
     CommentList,
     datetime_to_timestamp,
+    is_valid_id,
     timestamp_to_datetime,
 )
 
-from cellengine.payloads.gate_utils import (
-    format_rectangle_gate,
-    format_polygon_gate,
-    format_ellipse_gate,
-    format_range_gate,
-    format_split_gate,
-    format_quadrant_gate,
-)
-
 
 @dataclass
 class Experiment(DataClassMixin):
@@ -74,7 +72,7 @@ class Experiment(DataClassMixin):
         ),
         default=ReadOnly(),
     )  # type: ignore
-    _active_comp: Optional[Union[int, str, Compensation]] = field(
+    _active_comp: Optional[Union[int, str]] = field(
         default=None, metadata=config(field_name="activeCompensation")
     )
     data: Optional[Dict[Any, Any]] = field(default=None)
@@ -213,28 +211,43 @@ def undelete(self):
             del self.deleted
 
     @property
-    def active_compensation(self) -> Optional[Union[Compensation, int]]:
-        active_comp = self._active_comp
-        if type(active_comp) is str:
-            return ce.APIClient().get_compensation(self._id, active_comp)
-        elif type(active_comp) is int:
-            return active_comp
-        elif active_comp is None:
-            return None
-        raise ValueError(
-            f"Value '{active_comp}' is not a valid for activeCompensation."
-        )
+    def active_compensation(self) -> Optional[Union[str, int]]:
+        """The most recently used compensation.
+
+        Accepted values are:
+
+        - A Compensation object (value will be set to its `_id`)
+        - A Compensation ID
+        - A `cellengine` Compensation constant:
+          [`UNCOMPENSATED`][cellengine.UNCOMPENSATED],
+          [`FILE_INTERNAL`][cellengine.FILE_INTERNAL] or
+          [`PER_FILE`][cellengine.PER_FILE].
+
+        Example:
+        ```python
+        import cellengine
+        exp = cellengine.get_experiment(name='my experiment')
+        experiment.active_compensation = cellengine.UNCOMPENSATED
+        ```
+        """
+        return self._active_comp
 
     @active_compensation.setter
-    def active_compensation(self, compensation: Union[Compensation, int]):
-        if type(compensation) is Compensation:
+    def active_compensation(self, compensation: Union[Compensation, int, str]):
+        if isinstance(compensation, Compensation):
             self._active_comp = compensation._id
-        elif (
-            compensation == "UNCOMPENSATED"
-            or compensation == "FILE_INTERNAL"
-            or compensation == "PER_FILE"
-        ):
+        elif isinstance(compensation, str) and is_valid_id(compensation):
+            self._active_comp = compensation
+        elif isinstance(compensation, int) and compensation in [
+            ce.UNCOMPENSATED,
+            ce.PER_FILE,
+            ce.FILE_INTERNAL,
+        ]:
             self._active_comp = compensation
+        else:
+            raise ValueError(
+                f"Value '{compensation}' can not be set as the active compensation."
+            )
 
     @property
     def attachments(self) -> List[Attachment]:

docs/compensations.md

@@ -15,6 +15,14 @@ CellEngine object. Properties are the snake_case equivalent of those documented
 on the [CellEngine API](https://docs.cellengine.com/api/#compensations) unless
 otherwise noted.
 
+## Special Constants
+
+::: cellengine.UNCOMPENSATED
+
+::: cellengine.FILE_INTERNAL
+
+::: cellengine.PER_FILE
+
 ## Methods
 
 ::: cellengine.resources.compensation.Compensation

tests/unit/resources/test_experiment.py

@@ -1,8 +1,9 @@
 import json
 import pytest
 import responses
+from cellengine import FILE_INTERNAL, PER_FILE, UNCOMPENSATED
 
-from cellengine.utils import helpers
+from cellengine.utils import converter, helpers
 from cellengine.resources.experiment import Experiment
 from cellengine.resources.population import Population
 from cellengine.resources.fcs_file import FcsFile
@@ -20,7 +21,14 @@
 STATISTICS_ID = "5d64abe2ca9df61349ed8e79"
 
 
-def test_all_experiment_properties(client, ENDPOINT_BASE, experiment):
+@pytest.fixture(scope="function")
+def compensation(client, ENDPOINT_BASE, compensations):
+    comp = compensations[0]
+    comp.update({"experimentId": EXP_ID})
+    return converter.structure(comp, Compensation)
+
+
+def test_all_experiment_properties(ENDPOINT_BASE, experiment):
     assert experiment._id == "5d38a6f79fae87499999a74b"
     assert experiment.name == "pytest_experiment"
     assert experiment.comments == [{"insert": "\xa0\xa0\xa0First 12 of 96 files\n\n"}]
@@ -208,3 +216,29 @@ def test_should_clone_experiment(client, ENDPOINT_BASE, experiment, experiments)
     assert json.loads(responses.calls[0].request.body) == {
         "name": "my cloned experiment",
     }
+
+
+def test_sets_active_compensation_correctly(experiment, compensation):
+    experiment.active_compensation = 0
+    assert experiment.active_compensation == 0
+
+    experiment.active_compensation = -1
+    assert experiment.active_compensation == -1
+
+    experiment.active_compensation = -2
+    assert experiment.active_compensation == -2
+
+    experiment.active_compensation = UNCOMPENSATED
+    assert experiment.active_compensation == 0
+
+    experiment.active_compensation = FILE_INTERNAL
+    assert experiment.active_compensation == -1
+
+    experiment.active_compensation = PER_FILE
+    assert experiment.active_compensation == -2
+
+    experiment.active_compensation = compensation
+    assert experiment.active_compensation == compensation._id
+
+    experiment.active_compensation = compensation._id
+    assert experiment.active_compensation == compensation._id