fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/timevectors/ConstantTimeVector.py

@@ -0,0 +1,131 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import ConstantTimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class ConstantTimeVector(TimeVector):
+    """ConstantTimeVector class for TimeVectors that are constant over time. Subclass of TimeVector."""
+
+    def __init__(
+        self,
+        scalar: float,
+        unit: str | None = None,
+        is_max_level: bool | None = None,
+        is_zero_one_profile: bool | None = None,
+        reference_period: ReferencePeriod | None = None,
+    ) -> None:
+        """
+        Initialize the ConstantTimeVector class.
+
+        Args:
+            scalar (float): Constant float value of the TimeVector.
+            unit (str | None): Unit of the value in the vector.
+            is_max_level (bool | None): Whether the vector represents the maximum level, average level given a
+                                        reference period, or not a level at all.
+            is_zero_one_profile (bool | None): Whether the vector represents a profile with values between 0 and 1, a
+                                               profile with values averaging to 1 over a given reference period, or is
+                                               not a profile.
+            reference_period (ReferencePeriod | None, optional): Given reference period if the vector represents average
+                                                                 level or mean one profile. Defaults to None.
+
+        Raises:
+            ValueError: When both is_max_level and is_zero_one_profile is not None. This would mean the TimeVector
+                        represents both a level and a profile, which is not allowed.
+
+        """
+        self._scalar = float(scalar)
+        self._unit = unit
+        self._is_max_level = is_max_level
+        self._is_zero_one_profile = is_zero_one_profile
+        self._reference_period = reference_period
+
+        self._check_type(scalar, (float, np.float32))  # TODO: Accept np.float32 elsewhere aswell
+        self._check_type(unit, (str, type(None)))
+        self._check_type(is_max_level, (bool, type(None)))
+        self._check_type(is_zero_one_profile, (bool, type(None)))
+        self._check_type(reference_period, (ReferencePeriod, type(None)))
+
+        self._check_is_level_or_profile()
+
+    def __repr__(self) -> str:
+        """Return the string representation of the ConstantTimeVector."""
+        ref_period = None
+        if self._reference_period is not None:
+            start_year = self._reference_period.get_start_year()
+            num_years = self._reference_period.get_num_years()
+            ref_period = f"{start_year}-{start_year + num_years - 1}"
+        unit = f", unit={self._unit}" if self._unit is not None else ""
+        ref_period = f", reference_period={ref_period}" if ref_period is not None else ""
+        is_max_level = f", is_max_level={self._is_max_level}"
+        return f"ConstantTimeVector({self._scalar}{unit}{ref_period}{is_max_level})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality between two ConstantTimeVector objects."""
+        if not isinstance(other, ConstantTimeVector):
+            return False
+        return (
+            self._scalar == other._scalar
+            and self._unit == other._unit
+            and self._is_max_level == other._is_max_level
+            and self._is_zero_one_profile == other._is_zero_one_profile
+            and self._reference_period == other._reference_period
+        )
+
+    def __hash__(self) -> int:
+        """Compute the hash of the ConstantTimeVector."""
+        return hash((self._scalar, self._unit, self._is_max_level, self._is_zero_one_profile, self._reference_period))
+
+    def get_expr_str(self) -> str:
+        """Simpler representation of self to show in Expr."""
+        if self._unit:
+            return f"{self._scalar} {self._unit}"
+
+        return f"{self._scalar}"
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the values of the TimeVector."""
+        dtype = np.float32 if is_float32 else np.float64
+        out = np.zeros(1, dtype=dtype)
+        out[0] = self._scalar
+        return out
+
+    def get_timeindex(self) -> ConstantTimeIndex:
+        """Get the TimeIndex of the TimeVector."""
+        return ConstantTimeIndex()
+
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        return True
+
+    def is_max_level(self) -> bool | None:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._is_max_level
+
+    def is_zero_one_profile(self) -> bool | None:
+        """Check if TimeVector is a profile with values between zero and one."""
+        return self._is_zero_one_profile
+
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        return self._unit
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        if self._reference_period is not None:
+            return self._reference_period
+        if self.is_zero_one_profile() is False:
+            timeindex = self.get_timeindex()
+            return timeindex.get_reference_period()
+        return None
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the Fingerprint of the TimeVector."""
+        return self.get_fingerprint_default()
+
+    def get_loader(self) -> None:
+        """Interface method Not applicable for this type. Return None."""
+        return

framcore/timevectors/LinearTransformTimeVector.py

@@ -0,0 +1,131 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.loaders import TimeVectorLoader
+from framcore.timeindexes import ConstantTimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class LinearTransformTimeVector(TimeVector):
+    """LinearTransformTimeVector represents a TimeVector as scale * timevector + shift. Immutable."""
+
+    def __init__(
+        self,
+        timevector: TimeVector,
+        scale: float,
+        shift: float,
+        unit: str | None,
+        is_max_level: bool | None = None,
+        is_zero_one_profile: bool | None = None,
+        reference_period: ReferencePeriod | None = None,
+    ) -> None:
+        """
+        Initialize LinearTransformTimeVector with a TimeVector, scale and shift.
+
+        May also override unit, is_max_level,  is_zero_one_profile and reference_period of the original timevector.
+
+        Args:
+            timevector (TimeVector): TimeVector.
+            scale (float): Scale factor.
+            shift (float): Shift value.
+            unit (str | None): Unit of the values in the transformed vector.
+            is_max_level (bool | None, optional): Whether the transformed vector represents the maximum level,
+                                                  average level given a reference period, or not a level at all.
+                                                  Defaults to None.
+            is_zero_one_profile (bool | None, optional): Whether the transformed vector represents a profile with values
+                                                        between 0 and 1, a profile with values averaging to 1 over a given
+                                                        reference period, or is not a profile. Defaults to None.
+            reference_period (ReferencePeriod | None, optional): Given reference period if the transformed vector
+                                                                 represents average level or mean one profile. Defaults to None.
+
+        """
+        self._check_type(timevector, TimeVector)
+        self._check_type(scale, float)
+        self._check_type(shift, float)
+        self._check_type(unit, (str, type(None)))
+        self._check_type(is_max_level, (bool, type(None)))
+        self._check_type(is_zero_one_profile, (bool, type(None)))
+        self._check_type(reference_period, (ReferencePeriod, type(None)))
+        self._timevector = timevector
+        self._scale = scale
+        self._shift = shift
+        self._unit = unit
+        self._is_max_level = is_max_level
+        self._is_zero_one_profile = is_zero_one_profile
+        self._reference_period = reference_period
+
+        self._check_is_level_or_profile()
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the values of the TimeVector."""
+        vector = self._timevector.get_vector(is_float32)
+        if self._scale == 1.0 and self._shift == 0.0:
+            return vector
+        out = vector.copy()
+        if self._scale != 1.0:
+            np.multiply(out, self._scale, out=out)
+        if self._shift != 0.0:
+            np.add(out, self._shift, out=out)
+        return out
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the Fingerprint of the TimeVector."""
+        return self.get_fingerprint_default()
+
+    def get_timeindex(self) -> ConstantTimeIndex:
+        """Get the TimeIndex of the TimeVector."""
+        return self._timevector.get_timeindex()
+
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        return self._timevector.is_constant()
+
+    def is_max_level(self) -> bool | None:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._is_max_level
+
+    def is_zero_one_profile(self) -> bool | None:
+        """Check if TimeVector is a profile with values between zero and one."""
+        return self._is_zero_one_profile
+
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        return self._unit
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        return self._reference_period
+
+    def get_loader(self) -> TimeVectorLoader | None:
+        """Call get_loader on underlying time vector."""
+        return self._timevector.get_loader()
+
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if self and other are equal."""
+        if not isinstance(other, type(self)):
+            return False
+        return (
+            self._timevector == other._timevector
+            and self._scale == other._scale
+            and self._shift == other._shift
+            and self._unit == other._unit
+            and self._is_max_level == other._is_max_level
+            and self._is_zero_one_profile == other._is_zero_one_profile
+            and self._reference_period == other._reference_period
+        )
+
+    def __hash__(self) -> int:
+        """Compute the hash of the LinearTransformTimeVector."""
+        return hash(
+            (
+                self._timevector,
+                self._scale,
+                self._shift,
+                self._unit,
+                self._is_max_level,
+                self._is_zero_one_profile,
+                self._reference_period,
+            ),
+        )

framcore/timevectors/ListTimeVector.py

@@ -0,0 +1,127 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class ListTimeVector(TimeVector):
+    """TimeVector with a numpy array of values paired with a timeindex."""
+
+    def __init__(
+        self,
+        timeindex: TimeIndex,
+        vector: NDArray,
+        unit: str | None,
+        is_max_level: bool | None,
+        is_zero_one_profile: bool | None,
+        reference_period: ReferencePeriod | None = None,
+    ) -> None:
+        """
+        Initialize the ListTimeVector class.
+
+        Args:
+            timeindex (TimeIndex): Index of timestamps for the vector.
+            vector (NDArray): Array of vector values.
+            unit (str | None): Unit of the values in the vector.
+            is_max_level (bool | None): Whether the vector represents the maximum level, average level given a
+                                        reference period, or not a level at all.
+            is_zero_one_profile (bool | None): Whether the vector represents aprofile with values between 0 and 1, a
+                                               profile with values averaging to 1 over a given reference period, or is
+                                               not a profile.
+            reference_period (ReferencePeriod | None, optional): Given reference period if the vector represents average
+                                                                 level or mean one profile. Defaults to None.
+
+        Raises:
+            ValueError: When both is_max_level and is_zero_one_profile is not None. This would mean the TimeVector
+                        represents both a level and a profile, which is not allowed.
+            ValueError: When the shape of the vector does not match the number of periods in the timeindex.
+
+        """
+        if vector.shape != (timeindex.get_num_periods(),):
+            msg = f"Vector shape {vector.shape} does not match number of periods {timeindex.get_num_periods()} of timeindex ({timeindex})."
+            raise ValueError(msg)
+
+        self._timeindex = timeindex
+        self._vector = vector
+        self._unit = unit
+        self._reference_period = reference_period
+        self._is_max_level = is_max_level
+        self._is_zero_one_profile = is_zero_one_profile
+
+        self._check_type(timeindex, TimeIndex)
+        self._check_type(vector, np.ndarray)
+        self._check_type(unit, (str, type(None)))
+        self._check_type(is_max_level, (bool, type(None)))
+        self._check_type(is_zero_one_profile, (bool, type(None)))
+        self._check_type(reference_period, (ReferencePeriod, type(None)))
+
+        self._check_is_level_or_profile()
+
+    def __eq__(self, other: object) -> None:
+        """Check equality between two ListTimeVector objects."""
+        if not isinstance(other, ListTimeVector):
+            return NotImplemented
+        return (
+            (self._timeindex == other._timeindex)
+            and np.array_equal(self._vector, other._vector)
+            and (self._unit == other._unit)
+            and (self._is_max_level == other._is_max_level)
+            and (self._is_zero_one_profile == other._is_zero_one_profile)
+            and (self._reference_period == other._reference_period)
+        )
+
+    def __hash__(self) -> int:
+        """Return hash of ListTimeVector object."""
+        return hash((self._timeindex, self._vector.tobytes(), self._unit, self._is_max_level, self._is_zero_one_profile, self._reference_period))
+
+    def __repr__(self) -> str:
+        """Return the string representation of the ListTimeVector."""
+        return f"ListTimeVector(timeindex={self._timeindex}, vector={self._vector}, unit={self._unit}, reference_period={self._reference_period})"
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the vector of the TimeVector as a numpy array."""
+        if is_float32:
+            return self._vector.astype(dtype=np.float32)
+        return self._vector
+
+    def get_timeindex(self) -> TimeIndex:
+        """Get the TimeIndex of the TimeVector."""
+        return self._timeindex
+
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        return False
+
+    def is_max_level(self) -> bool:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._is_max_level
+
+    def is_zero_one_profile(self) -> bool:
+        """Check if TimeVector is a profile with vector between zero and one."""
+        return self._is_zero_one_profile
+
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        return self._unit
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        return self._reference_period
+
+    def get_fingerprint(self) -> Fingerprint:
+        """
+        Get the fingerprint of the ListTimeVector.
+
+        Returns:
+            Fingerprint: The fingerprint of the ListTimeVector, excluding the reference period.
+
+        """
+        excludes = {"_reference_period"}
+        return self.get_fingerprint_default(excludes=excludes)
+
+    def get_loader(self) -> None:
+        """Interface method Not applicable for this type. Return None."""
+        return

framcore/timevectors/LoadedTimeVector.py

@@ -0,0 +1,97 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.loaders import TimeVectorLoader
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class LoadedTimeVector(TimeVector):
+    """TimeVector which gets its data from a data source via a TimeVectorLoader. Subclass of TimeVector."""
+
+    def __init__(self, vector_id: str, loader: TimeVectorLoader) -> None:
+        """
+        Store vector id and loader in instance variables, get unit from loader.
+
+        Args:
+            vector_id (str): Unique name of this vector.
+            loader (TimeVectorLoader): Object connected to a data source where vector_id is associated with a time
+                                       vector. The Loader object must also implement the TimeVectorLoader API.
+
+        Raises:
+            ValueError: When metadata in the TimeVectorLoader for both is_max_level and is_zero_one_profile for the
+                        given vector_id is not None. This would mean the TimeVector represents both a level and a
+                        profile, which is not allowed.
+
+        """
+        self._vector_id = vector_id
+        self._loader = loader
+        self._check_type(self._vector_id, str)
+        self._check_type(self._loader, TimeVectorLoader)
+        self._is_max_level = self._loader.is_max_level(self._vector_id)
+        self._is_zero_one_profile = self._loader.is_zero_one_profile(self._vector_id)
+        self._unit = self._loader.get_unit(self._vector_id)
+        self._reference_period = self._loader.get_reference_period(self._vector_id)
+
+        self._check_is_level_or_profile()
+
+    def __repr__(self) -> str:
+        """Overwrite string representation of LoadedTimeVector objects."""
+        return f"{type(self).__name__}(vector_id={self._vector_id},loader={self._loader},unit={self._unit})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality between two LoadedTimeVector objects."""
+        if not isinstance(other, LoadedTimeVector):
+            return NotImplemented
+        return (self._vector_id == other._vector_id) and (self._loader == other._loader)
+
+    def __hash__(self) -> int:
+        """Return hash of LoadedTimeVector object."""
+        return hash((self._vector_id, self._loader))
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the vector of the TimeVector as a numpy array."""
+        vector = self._loader.get_values(self._vector_id)
+        if is_float32:
+            return vector.astype(np.float32)
+        return vector
+
+    def get_timeindex(self) -> TimeIndex:
+        """
+        Get this time vectors index.
+
+        Returns:
+            TimeIndex: Object describing the index.
+
+        """
+        return self._loader.get_index(self._vector_id)
+
+    def is_constant(self) -> bool:
+        """Signify if this TimeVector is constant."""
+        return False
+
+    def get_unit(self) -> str:
+        """Get the unit of this TimeVector."""
+        return self._unit
+
+    def get_loader(self) -> TimeVectorLoader:
+        """Get the Loader this TimeVector retrieves its data from."""
+        return self._loader
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period which the data of this TimeVector is from."""
+        return self._reference_period
+
+    def is_max_level(self) -> bool | None:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._loader.is_max_level(self._vector_id)
+
+    def is_zero_one_profile(self) -> bool | None:
+        """Check if TimeVector is a profile with values between zero and one."""
+        return self._loader.is_zero_one_profile(self._vector_id)
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the Fingerprint of this TimeVector."""
+        return self._loader.get_fingerprint(self._vector_id)

framcore/timevectors/ReferencePeriod.py

@@ -0,0 +1,51 @@
+from framcore import Base
+
+
+class ReferencePeriod(Base):
+    """ReferencePeriod class represents a period of one or more years."""
+
+    def __init__(self, start_year: int, num_years: int) -> None:
+        """
+        Initialize a ReferencePeriod with the start year and number of years.
+
+        Args:
+            start_year (int): The first year in the reference period. Must be a positive integer.
+            num_years (int): The number of years in the reference period. Must be a positive non-zero integer.
+
+        """
+        self._check_type(start_year, int)
+        self._check_type(num_years, int)
+
+        if start_year < 0:
+            message = f"start_year must be a positive integer. Got {start_year}."
+            raise ValueError(message)
+
+        if num_years <= 0:
+            message = f"num_years must be a positive non-zero integer. Got {num_years}."
+            raise ValueError(message)
+
+        self._start_year = start_year
+        self._num_years = num_years
+
+    def get_start_year(self) -> int:
+        """Get the start_year from a ReferencePeriod instance."""
+        return self._start_year
+
+    def get_num_years(self) -> int:
+        """Get the number of years in the ReferencePeriod."""
+        return self._num_years
+
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if self and other are equal."""
+        if not isinstance(other, type(self)):
+            return False
+        return self._start_year == other._start_year and self._num_years == other._num_years
+
+    def __hash__(self) -> int:
+        """Compute hash value.."""
+        return hash(
+            (
+                self._start_year,
+                self._num_years,
+            ),
+        )

framcore/timevectors/TimeVector.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from numpy.typing import NDArray
+
+from framcore import Base
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+
+if TYPE_CHECKING:
+    from framcore.loaders import TimeVectorLoader
+
+
+# TODO: Floating point precision
+class TimeVector(Base, ABC):
+    """TimeVector interface class for defining timeseries data."""
+
+    def __init__(self) -> None:
+        """Initialize the TimeVector class."""
+        super().__init__()
+
+    @abstractmethod
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if two TimeVectors are equal."""
+        pass
+
+    @abstractmethod
+    def __hash__(self) -> int:
+        """Compute hash value."""
+        pass
+
+    @abstractmethod
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the values of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_timeindex(self) -> TimeIndex | None:
+        """Get the TimeIndex of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        pass
+
+    @abstractmethod
+    def is_max_level(self) -> bool | None:
+        """
+        Whether the TimeVector represents the maximum level, average level given a reference period, or not a level at all.
+
+        See LevelProfile for a description of Level (max or avg) and Profile (max one or mean one), and their formats.
+
+        """
+        pass
+
+    @abstractmethod
+    def is_zero_one_profile(self) -> bool | None:
+        """
+        Whether the TimeVector represents a profile with values between 0 and 1, a profile with average 1 over a given reference period, or is not a profile.
+
+        See LevelProfile for a description of Level (max or avg) and Profile (max one or mean one), and their formats.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the fingerprint of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_loader(self) -> TimeVectorLoader | None:
+        """
+        Get the TimeVectorLoader of the TimeVector if self has one.
+
+        TimeVectors can store timeseries data in Loaders that point to databases. Data is only retrieved and cached when the TimeVector is queried.
+        """
+        pass
+
+    """
+    Checks that the TimeVector is either a level or a profile.
+
+    Raises:
+        ValueError: If both is_max_level and is_zero_one_profile are None or both are not None.
+    """
+
+    def _check_is_level_or_profile(self) -> None:
+        """Ensure that the TimeVector is either a level or a profile."""
+        if (self.is_max_level() is not None and self.is_zero_one_profile() is not None) or (self.is_max_level() is None and self.is_zero_one_profile() is None):
+            message = (
+                f"Invalid input arguments for {self}: Must have exactly one 'non-None' value for "
+                "is_max_level and is_zero_one_profile. A TimeVector is either a level or a profile."
+            )
+            raise ValueError(message)

framcore/timevectors/__init__.py

@@ -0,0 +1,17 @@
+# framcore/timevectors/__init__.py
+
+from framcore.timevectors.ReferencePeriod import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector
+from framcore.timevectors.ConstantTimeVector import ConstantTimeVector
+from framcore.timevectors.LinearTransformTimeVector import LinearTransformTimeVector
+from framcore.timevectors.ListTimeVector import ListTimeVector
+from framcore.timevectors.LoadedTimeVector import LoadedTimeVector
+
+__all__ = [
+    "ConstantTimeVector",
+    "LinearTransformTimeVector",
+    "ListTimeVector",
+    "LoadedTimeVector",
+    "ReferencePeriod",
+    "TimeVector",
+]