feat: Luminex xPONENT - migrate to BENCHLING/2024/09 schema (#1007)

Co-authored-by: Nathan Stender <nathan.stender@benchling.com>

Author: slopez-b

SUPPORTED_INSTRUMENT_SOFTWARE.adoc

@@ -32,7 +32,7 @@ The parsers follow maturation levels of: Recommended, Candidate Release, Working
 .2+|Liquid Handler|Beckman Coulter Biomek|Recommended|BENCHLING/2024/11
 |Beckman Echo Plate Reformat|Recommended|BENCHLING/2024/11
 .2+|Multi Analyte Profiling|Bio-Rad Bio-Plex Manager|Recommended|BENCHLING/2024/01
-|Luminex xPONENT|Recommended|BENCHLING/2024/01
+|Luminex xPONENT|Recommended|BENCHLING/2024/09
 .14+|Plate Reader|Agilent Gen5|Recommended|REC/2024/06
 |Agilent Gen5 Image|Recommended|BENCHLING/2023/09
 |BMG Labtech SMART Control|Recommended|REC/2024/06
@@ -63,4 +63,4 @@ The parsers follow maturation levels of: Recommended, Candidate Release, Working
 .3+|qPCR|AppBio QuantStudio RT-PCR|Recommended|REC/2024/09
 |AppBio QuantStudio Design & Analysis|Recommended|REC/2024/09
 |Bio-Rad CFX Maestro|Recommended|REC/2024/09
-|===
+|===

src/allotropy/allotrope/models/shared/definitions/definitions.py

@@ -84,6 +84,11 @@ class TStatisticDatumRole(Enum):
     frequency_of_grandparent_role = "frequency of grandparent role"
     frequency_of_total_role = "frequency of total role"
     sum_of_squares_role = "sum of squares role"
+    mode_value_role = "mode value role"
+    trimmed_mode_value_role = "trimmed mode value role"
+    trimmed_count_role = "trimmed count role"
+    trimmed_standard_deviation_role = "trimmed standard deviation role"
+    trimmed_arithmetic_mean_role = "trimmed arithmetic mean role"
 
 
 class InvalidJsonFloat(Enum):

src/allotropy/allotrope/schema_mappers/adm/multi_analyte_profiling/benchling/_2024/_09/multi_analyte_profiling.py

@@ -3,8 +3,12 @@
 from allotropy.allotrope.models.adm.multi_analyte_profiling.benchling._2024._09.multi_analyte_profiling import (
     AnalyteAggregateDocument,
     AnalyteDocumentItem,
+    CalculatedDataAggregateDocument,
+    CalculatedDataDocumentItem,
     CalibrationAggregateDocument,
     CalibrationDocumentItem,
+    DataSourceAggregateDocument,
+    DataSourceDocumentItem,
     DataSystemDocument,
     DeviceControlAggregateDocument,
     DeviceControlDocumentItem,
@@ -17,6 +21,11 @@
     MultiAnalyteProfilingAggregateDocument,
     MultiAnalyteProfilingDocumentItem,
     SampleDocument,
+    StatisticDimensionAggregateDocument,
+    StatisticDimensionDocumentItem,
+    StatisticsAggregateDocument,
+    StatisticsDocumentItem,
+    TQuantityValueModel,
 )
 from allotropy.allotrope.models.shared.components.plate_reader import SampleRoleType
 from allotropy.allotrope.models.shared.definitions.custom import (
@@ -28,19 +37,37 @@
 from allotropy.allotrope.models.shared.definitions.definitions import (
     TStatisticDatumRole,
 )
+from allotropy.allotrope.models.shared.definitions.units import Unitless
 from allotropy.allotrope.schema_mappers.schema_mapper import SchemaMapper
 from allotropy.constants import ASM_CONVERTER_VERSION
+from allotropy.parsers.utils.calculated_data_documents.definition import (
+    CalculatedDocument,
+)
 from allotropy.parsers.utils.values import quantity_or_none
 
 
+@dataclass(frozen=True)
+class StatisticDimension:
+    value: float
+    unit: str
+    statistic_datum_role: TStatisticDatumRole
+
+
+@dataclass(frozen=True)
+class StatisticsDocument:
+    statistical_feature: str
+    statistic_dimensions: list[StatisticDimension]
+
+
 @dataclass(frozen=True)
 class Analyte:
     identifier: str
     name: str
-    value: float
     assay_bead_identifier: str
     assay_bead_count: float
-    statistic_datum_role: TStatisticDatumRole | None
+    statistics: list[StatisticsDocument] | None = None
+    statistic_datum_role: TStatisticDatumRole | None = None
+    fluorescence: float | None = None
 
 
 @dataclass(frozen=True)
@@ -115,6 +142,7 @@ class Metadata:
 class Data:
     metadata: Metadata
     measurement_groups: list[MeasurementGroup]
+    calculated_data: list[CalculatedDocument] | None = None
 
 
 class Mapper(SchemaMapper[Data, Model]):
@@ -146,6 +174,9 @@ def map_model(self, data: Data) -> Model:
                     self._get_technique_document(measurement_group, data.metadata)
                     for measurement_group in data.measurement_groups
                 ],
+                calculated_data_aggregate_document=self._get_calculated_data_aggregate_document(
+                    data.calculated_data
+                ),
             ),
             field_asm_manifest=self.MANIFEST,
         )
@@ -208,9 +239,33 @@ def _get_measurement_document(
                         ),
                         fluorescence=quantity_or_none(
                             TQuantityValueRelativeFluorescenceUnit,
-                            analyte.value,
+                            analyte.fluorescence,
                             has_statistic_datum_role=analyte.statistic_datum_role,
                         ),
+                        statistics_aggregate_document=(
+                            StatisticsAggregateDocument(
+                                statistics_document=[
+                                    StatisticsDocumentItem(
+                                        statistical_feature=statistic.statistical_feature,
+                                        statistic_dimension_aggregate_document=StatisticDimensionAggregateDocument(
+                                            statistic_dimension_document=[
+                                                StatisticDimensionDocumentItem(
+                                                    statistical_value=TQuantityValueModel(
+                                                        value=dimension.value,
+                                                        unit=dimension.unit,
+                                                        has_statistic_datum_role=dimension.statistic_datum_role,
+                                                    ),
+                                                )
+                                                for dimension in statistic.statistic_dimensions
+                                            ]
+                                        ),
+                                    )
+                                    for statistic in analyte.statistics
+                                ]
+                            )
+                            if analyte.statistics
+                            else None
+                        ),
                     )
                     for analyte in measurement.analytes
                 ]
@@ -261,3 +316,33 @@ def _get_error_aggregate_document(
                 for error in errors
             ]
         )
+
+    def _get_calculated_data_aggregate_document(
+        self, calculated_data_items: list[CalculatedDocument] | None
+    ) -> CalculatedDataAggregateDocument | None:
+        if not calculated_data_items:
+            return None
+
+        return CalculatedDataAggregateDocument(
+            calculated_data_document=[
+                CalculatedDataDocumentItem(
+                    calculated_data_identifier=calculated_data_item.uuid,
+                    calculated_data_name=calculated_data_item.name,
+                    calculation_description=calculated_data_item.description,
+                    calculated_result=TQuantityValueModel(
+                        value=calculated_data_item.value,
+                        unit=calculated_data_item.unit or Unitless.unit,
+                    ),
+                    data_source_aggregate_document=DataSourceAggregateDocument(
+                        data_source_document=[
+                            DataSourceDocumentItem(
+                                data_source_identifier=item.reference.uuid,
+                                data_source_feature=item.feature,
+                            )
+                            for item in calculated_data_item.data_sources
+                        ]
+                    ),
+                )
+                for calculated_data_item in calculated_data_items
+            ]
+        )

src/allotropy/allotrope/schemas/adm/multi-analyte-profiling/BENCHLING/2024/09/CHANGE_NOTES.md

@@ -15,6 +15,6 @@ Changes:
   * Reasoning: These should be included in REC/2024/12 core schema
   * Proposal: Add "method version" to measurement aggregate document
 
-* Add "coefficient of variation role", "trimmed mode role", "trimmed count role", "trimmed standard deviation role", "trimmed arithmetic mean role" to tStatisiticDatumRole class
+* Add "coefficient of variation role", "trimmed mode value role", "trimmed count role", "trimmed standard deviation role", "trimmed arithmetic mean role" to tStatisiticDatumRole class
   * Reasoning: Support of additional statistical terms that are exported from multi-analyte-profilers
-  * Proposal: Add "coefficient of variation role", "trimmed mode role", "trimmed count role", "trimmed standard deviation role", "trimmed arithmetic mean role" to tStatisiticDatumRole
+  * Proposal: Add "coefficient of variation role", "trimmed mode value role", "trimmed count role", "trimmed standard deviation role", "trimmed arithmetic mean role" to tStatisiticDatumRole

src/allotropy/allotrope/schemas/adm/multi-analyte-profiling/BENCHLING/2024/09/multi-analyte-profiling.schema.json

@@ -2081,7 +2081,7 @@
             "variance role",
             "mode value role",
             "maximum value role",
-            "trimmed mode role",
+            "trimmed mode value role",
             "trimmed count role",
             "trimmed standard deviation role",
             "trimmed arithmetic mean role",

src/allotropy/parsers/luminex_xponent/constants.py

@@ -1,3 +1,9 @@
+from dataclasses import dataclass
+
+from allotropy.allotrope.models.shared.definitions.definitions import (
+    TStatisticDatumRole,
+)
+
 DEFAULT_SOFTWARE_NAME = "xPONENT"
 DEFAULT_CONTAINER_TYPE = "well plate"
 DEFAULT_DEVICE_TYPE = "multi analyte profiling analyzer"
@@ -8,4 +14,58 @@
 MINIMUM_CALIBRATION_LINE_COLS = 2
 EXPECTED_CALIBRATION_RESULT_LEN = 2
 EXPECTED_HEADER_COLUMNS = 7
-REQUIRED_SECTIONS = ["Median", "Count", "Units", "Dilution Factor"]
+REQUIRED_SECTIONS = ["Count", "Units", "Dilution Factor"]
+
+
+@dataclass(frozen=True)
+class StatisticSectionConfig:
+    role: TStatisticDatumRole
+    unit: str
+
+
+STATISTIC_SECTIONS_CONF = {
+    "Median": StatisticSectionConfig(
+        role=TStatisticDatumRole.median_role,
+        unit="RFU",
+    ),
+    "Mean": StatisticSectionConfig(
+        role=TStatisticDatumRole.arithmetic_mean_role,
+        unit="RFU",
+    ),
+    "%CV": StatisticSectionConfig(
+        role=TStatisticDatumRole.coefficient_of_variation_role,
+        unit="(unitless)",
+    ),
+    "Standard Deviation": StatisticSectionConfig(
+        role=TStatisticDatumRole.standard_deviation_role,
+        unit="(unitless)",
+    ),
+    "Peak": StatisticSectionConfig(
+        role=TStatisticDatumRole.mode_value_role,
+        unit="RFU",
+    ),
+    "Trimmed Peak": StatisticSectionConfig(
+        role=TStatisticDatumRole.trimmed_mode_value_role,
+        unit="RFU",
+    ),
+    "Trimmed Count": StatisticSectionConfig(
+        role=TStatisticDatumRole.trimmed_count_role,
+        unit="RFU",
+    ),
+    "Trimmed Standard Deviation": StatisticSectionConfig(
+        role=TStatisticDatumRole.trimmed_standard_deviation_role,
+        unit="(unitless)",
+    ),
+    "Trimmed Mean": StatisticSectionConfig(
+        role=TStatisticDatumRole.trimmed_arithmetic_mean_role,
+        unit="RFU",
+    ),
+}
+
+CALCULATED_DATA_SECTIONS: dict[str, str] = {
+    "Net MFI": "RFU",
+    "Avg Net MFI": "RFU",
+    "Test Result": "(unitless)",
+    "% Recovery": "(unitless)",
+    "%CV of Replicates": "(unitless)",
+}

src/allotropy/parsers/luminex_xponent/luminex_xponent_parser.py

@@ -1,7 +1,7 @@
-from allotropy.allotrope.models.adm.multi_analyte_profiling.benchling._2024._01.multi_analyte_profiling import (
+from allotropy.allotrope.models.adm.multi_analyte_profiling.benchling._2024._09.multi_analyte_profiling import (
     Model,
 )
-from allotropy.allotrope.schema_mappers.adm.multi_analyte_profiling.benchling._2024._01.multi_analyte_profiling import (
+from allotropy.allotrope.schema_mappers.adm.multi_analyte_profiling.benchling._2024._09.multi_analyte_profiling import (
     Data as MapperData,
     Mapper,
 )
@@ -31,5 +31,5 @@ def create_data(self, named_file_contents: NamedFileContents) -> MapperData:
             create_metadata(
                 data.header, data.calibrations, named_file_contents.original_file_path
             ),
-            create_measurement_groups(data.measurement_list.measurements, data.header),
+            *create_measurement_groups(data.measurement_list.measurements, data.header),
         )