Merge pull request #45 from ARKlab/feature/19532-unitofmeasure

ref(unitofmeasure): added unitofmeasure functionality

Author: AndreaCuneo

README.md

@@ -442,6 +442,154 @@ To construct a GME Public Offer Extraction the following must be provided.
      
 </table>
 
+### Unit of Measure Conversion Functionality
+
+### Overview
+
+The unit of measure conversion functionality allows users to request a conversion of units for Market Data that was registered using a different unit. This feature is supported only for Actual and Versioned Time Series.
+Supported units are defined in the CommonUnitOfMeasure object and conform to ISO/IEC 80000 (i.e., `kW`, `MW`, `kWh`, `MWh`, `m`, `km`, `day`, `min`, `h`, `s`, `mo`, `yr`).
+
+Note: Duration-based units are interpreted with the following fixed assumptions:
+`1 day = 24 hours`
+`1 mo = 30 days`
+`1 yr = 365 days`
+
+Additional supported units include **currency codes** in 3-letter format as per ISO 4217:2015 (e.g., `EUR`, `USD`, `JPY`). These are not part of CommonUnitOfMeasure and must be specified as regular strings.
+Units of measure can also be **composite**, using the {a}/{b} syntax, where both {a} and {b} are either units from CommonUnitOfMeasure or ISO 4217 currency codes.
+
+### Conversion Logic
+
+Unit conversion is based on the assumption that each unit of measure can be decomposed into a **"BaseDimension"**, which represents a polynomial of base SI units (`m`, `s`, `kg`, etc.) and currencies (`EUR`, `USD`, etc.).
+A unit of measure is represented as a value in BaseDimension UnitOdMeasure.
+Example:
+10 `Wh` = 10 `kg·m²·s⁻³`
+Conversion is allowed when the BaseDimensions **match exactly**, i.e., the same set of base units raised to the same exponents.
+In Artesian, units that differ **only** in the **time dimension** are also potentially convertible, as the time dimension can be inferred from the data’s time interval.
+
+### Example: Power to Energy Conversion
+
+Converting `W` to `Wh`:
+• `W` → BaseDimension: `k·m²·s⁻³`
+• `Wh` → BaseDimension: `kg·m²·s⁻²`
+• `1 h = 3600 s`
+**Conversion Steps:**
+10 W = 10 kg·m²/s³
+1 h = 3600 s
+10 kg·m²/s³ × 3600 s = 36000 kg·m²/s² = 10 Wh
+
+### MarketData Registration with UnitOfMeasure
+
+The UnitOfMeasure is defined during registration:
+
+```Python
+mkd = MarketData.MarketDataEntityInput(
+      providerName = "TestProviderName",
+      marketDataName = "TestMarketDataName",
+      originalGranularity=Granularity.Day,
+      type=MarketData.MarketDataType.ActualTimeSerie,
+      originalTimezone="CET",
+      aggregationRule=AggregationRule.SumAndDivide,
+    UnitOfMeasure = CommonUnitOfMeasure.kW
+  )
+
+registered = mkservice.readMarketDataRegistryByName(mkdid.provider, mkdid.name)
+if (registered is None):
+  registered = mkservice.registerMarketData(mkd)
+```
+
+### UnitOfMeasure Conversion and Aggregation Rule Override
+
+In the QueryService, there are two supported methods related to unit of measure handling during extraction:
+
+1. UnitOfMeasure Conversion
+2. Aggregation Rule Override
+
+### UnitOfMeasure Conversion
+
+To convert a UnitOfMeasure during data extraction, use the `.inUnitOfMeasure()` method. This function converts the data from the unit defined at MarketData registration to the target unit you specify in the query.
+
+```Python
+qs = QueryService(cfg)
+data = qs.createActual() \
+    .forMarketData([100011484]) \
+    .inAbsoluteDateRange("2024-01-01","2024-01-02") \
+    .inTimeZone("UTC") \
+    .inGranularity(Granularity.Day) \
+    .inUnitOfMeasure(CommonUnitOfMeasure.MW) \
+    .execute()
+```
+
+By default, the aggregation rule used during extraction is the one defined at registration. However, you can override it if needed. The conversion is always applied before aggregation.
+
+### Aggregation Rule Override
+
+AggregationRule can be overrided using the `.withAggregationRule()` method in QueryService.
+
+```Python
+qs = QueryService(cfg)
+data = qs.createActual() \
+    .forMarketData([100011484]) \
+    .inAbsoluteDateRange("2024-01-01","2024-01-02") \
+    .inTimeZone("UTC") \
+    .inGranularity(Granularity.Day) \
+    .withAggregationRule(AggregationRule.AverageAndReplicate) \
+    .execute()
+```
+
+Sometimes, especially when converting from a **consumption unit** (e.g., `MWh`) to a **power unit** (e.g., `MW`), the registered aggregation rule (e.g., `SumAndDivide`) may not make sense for the new unit.
+
+If you **don’t override the aggregation rule**, the conversion may produce **invalid or misleading results**.
+
+### Example: Convert power (`MW`) to energy (`MWh`):
+
+```Python
+data = qs.createActual() \
+    .forMarketData([100011484]) \
+    .inAbsoluteDateRange("2024-01-01","2024-01-02") \
+    .inTimeZone("UTC") \
+    .inGranularity(Granularity.Day) \
+    .inUnitOfMeasure(CommonUnitOfMeasure.MWh) \
+    .withAggregationRule(AggregationRule.AverageAndReplicate) \
+    .execute()
+```
+
+### Composite Unit Example: `MWh/day`
+
+```Python
+data = qs.createActual() \
+    .forMarketData([100011484]) \
+    .inAbsoluteDateRange("2024-01-01","2024-01-02") \
+    .inTimeZone("UTC") \
+    .inGranularity(Granularity.Day) \
+    .inUnitOfMeasure(CommonUnitOfMeasure.MWh / CommonUnitOfMeasure.day) \
+    .withAggregationRule(AggregationRule.AverageAndReplicate) \
+    .execute()
+```
+
+### CheckConversion: Validate Unit Compatibility
+
+Use the `CheckConversion` method to verify whether a list of input units can be converted into a specifified target unit:
+
+```Python
+from Artesian import ArtesianConfig, MarketData
+from Artesian.MarketData import CommonUnitOfMeasure
+
+cfg = ArtesianConfg()
+
+mkservice = MarketData.MarketDataService(cfg)
+
+inputUnitsOfMeasure = [CommonUnitOfMeasure.kW, CommonUnitOfMeasure.kWh, "EUR/MWh"]
+targetUnitOfMeasure = CommonUnitOfMeasure.MW
+
+checkConversionResult = mkservice.checkConversion(inputUnitsOfMeasure , targetUnitOfMeasure)
+```
+
+**Returned Object: CheckConversionResult**
+
+1. TargetUnitOfMeasure: "`kW`"
+2. ConvertibleInputUnitsOfMeasure: [ "`MW`", "`kW/s`" ]
+3. NotConvertibleInputUnitsOfMeasure: [ "`s`" ]
+
 ### Extraction Options
 
 Extraction options for GME Public Offer queries.
@@ -518,6 +666,18 @@ Extraction options for GME Public Offer queries.
  .withPagination(1,10)
 ```
 
+#### UnitOfMeasure (for Actual and Versioned Time Series)
+
+```Python
+ .inUnitOfMeasure(CommonUnitOfMeasure.kWh)
+```
+
+#### AggregationRule (for Actual and Versioned Time Series)
+
+```Python
+ .withAggregationRule(AggregationRule.SumAndDivide)
+```
+
 ## Write Data in Artesian
 
 Using the MarketDataService is possible to register MarketData and write curves into it using the UpsertData method.

src/Artesian/MarketData/CommonUnitOfMeasure.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CommonUnitOfMeasure:
+    kW = "kW"
+    MW = "MW"
+    kWh = "kWh"
+    MWh = "MWh"
+    m = "m"
+    km = "km"
+    day = "day"
+    min = "min"
+    h = "h"
+    s = "s"
+    mo = "mo"
+    yr = "yr"

src/Artesian/MarketData/MarketDataService.py

@@ -11,6 +11,7 @@
 from ._Dto.ArtesianSearchResults import ArtesianSearchResults
 from ._Dto.MarketDataEntityInput import MarketDataEntityInput
 from ._Dto.MarketDataEntityOutput import MarketDataEntityOutput
+from ._Dto.CheckConversionResult import CheckConversionResult
 from ._Dto.UpsertData import UpsertData
 import asyncio
 
@@ -396,6 +397,61 @@ def registerMarketData(
             self.registerMarketDataAsync(entity)
         )
 
+    async def checkConversionAsync(
+        self: MarketDataService,
+        inputUnitsOfMeasure: List[str],
+        targetUnitOfMeasure: str
+    ) -> CheckConversionResult:
+        """
+        Check UnitOfMeasure conversion.
+
+        Args:
+            inputUnitsOfMeasure: the list of the input UnitOfMeasure to be check for
+                                conversion
+            targetUnitOfMeasure: The target UnitOfMeasure
+
+        Returns:
+            CheckConversionResult Entity (Async).
+        """
+        url = "/uom/checkconversion"
+        params = {"inputUnitsOfMeasure": inputUnitsOfMeasure,
+                  "targetUnitOfMeasure": targetUnitOfMeasure}
+        with self.__client as c:
+            res = await asyncio.gather(
+                *[
+                    self.__executor.exec(
+                        c.exec,
+                        "GET",
+                        url,
+                        None,
+                        retcls=CheckConversionResult,
+                        params=params,
+                    )
+                ]
+            )
+            return cast(CheckConversionResult, res[0])
+
+    def checkConversion(
+        self: MarketDataService,
+        inputUnitsOfMeasure: List[str],
+        targetUnitOfMeasure: str
+    ) -> CheckConversionResult:
+        """
+        Check UnitOfMeasure conversion.
+
+        Args:
+            inputUnitsOfMeasure: the list of the input UnitOfMeasure to be check for
+                                conversion
+            targetUnitOfMeasure: The target UnitOfMeasure
+
+        Returns:
+            CheckConversionResult Entity.
+        """
+
+        return _get_event_loop().run_until_complete(
+            self.checkConversionAsync(inputUnitsOfMeasure, targetUnitOfMeasure)
+        )
+
     async def updateDerivedConfigurationAsync(
         self: MarketDataService,
         marketDataId: int,

src/Artesian/MarketData/_Dto/CheckConversionResult.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class CheckConversionResult:
+    """
+    Class for the CheckConversionResult.
+
+    Attributes:
+        targetUnitOfMeasure: the target UnitOfMeasure
+        convertibleInputUnitsOfMeasure: the list of convertible input UnitOfMeasure
+        notConvertibleInputUnitsOfMeasure: the list of not convertible input
+                                          UnitOfMeasure
+    """
+
+    targetUnitOfMeasure: str
+    convertibleInputUnitsOfMeasure: List[str]
+    notConvertibleInputUnitsOfMeasure: List[str]

src/Artesian/MarketData/_Dto/MarketDataEntityInput.py

@@ -2,6 +2,7 @@
 from typing import Dict, List, Optional
 
 from .DerivedCfg import DerivedCfg
+from .UnitOfMeasure import UnitOfMeasure
 from .._Enum.DerivedAlgorithm import DerivedAlgorithm
 from .._Enum import MarketDataType
 from .._Enum import AggregationRule
@@ -34,6 +35,7 @@ class MarketDataEntityInput:
     originalGranularity: Granularity
     type: MarketDataType
     originalTimezone: str
+    unitOfMeasure: Optional[UnitOfMeasure] = None
     derivedCfg: Optional[DerivedCfg] = None
     aggregationRule: AggregationRule = AggregationRule.Undefined
     tags: Optional[Dict[str, List[str]]] = None

src/Artesian/MarketData/_Dto/UnitOfMeasure.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class UnitOfMeasure:
+    """
+    Class for the UnitOfMeasure.
+
+    Attributes:
+        value: the value of the unit of measure for the values of timeseries
+               (actual and versioned)
+
+    """
+
+    value: str

src/Artesian/MarketData/_Dto/__init__.py

@@ -1,5 +1,7 @@
 from .MarketDataEntityInput import MarketDataEntityInput
 from .MarketDataEntityOutput import MarketDataEntityOutput
+from .CheckConversionResult import CheckConversionResult
+from .UnitOfMeasure import UnitOfMeasure
 from .CurveRangeEntity import CurveRangeEntity
 from .PagedResult import PagedResultCurveRangeEntity
 from .ArtesianSearchResults import ArtesianSearchResults
@@ -31,4 +33,6 @@
     ArtesianMetadataFacet.__name__,
     ArtesianMetadataFacetCount.__name__,
     DerivedCfg.__name__,
+    CheckConversionResult.__name__,
+    UnitOfMeasure.__name__,
 ]  # type: ignore

src/Artesian/MarketData/__init__.py

@@ -4,6 +4,7 @@
 from ..Granularity import Granularity
 from ._Enum.MarketDataType import MarketDataType
 from ._Enum.ArtesianMetadataFacetType import ArtesianMetadataFacetType
+from .CommonUnitOfMeasure import CommonUnitOfMeasure
 
 from ._Dto import (
     AuctionBids,
@@ -21,6 +22,8 @@
     ArtesianMetadataFacet,
     ArtesianMetadataFacetCount,
     DerivedCfg,
+    CheckConversionResult,
+    UnitOfMeasure,
 )
 
 __all__ = [
@@ -44,5 +47,8 @@
     ArtesianMetadataFacetCount.__name__,
     ArtesianMetadataFacetType.__name__,
     DerivedCfg.__name__,
+    CheckConversionResult.__name__,
     DerivedAlgorithm.__name__,
+    CommonUnitOfMeasure.__name__,
+    UnitOfMeasure.__name__,
 ]  # type: ignore