fram-core 0.1.0a1__py3-none-any.whl → 0.1.1__py3-none-any.whl

framcore/timeindexes/ListTimeIndex.py

@@ -6,8 +6,8 @@ import numpy as np
 from numpy.typing import NDArray
 
 from framcore.fingerprints import Fingerprint
-from framcore.timeindexes import FixedFrequencyTimeIndex
-from framcore.timeindexes.TimeIndex import TimeIndex  # NB! full import path needed for inheritance to work
+from framcore.timeindexes import FixedFrequencyTimeIndex, TimeIndex
+from framcore.timeindexes._time_vector_operations import period_duration
 
 
 class ListTimeIndex(TimeIndex):
@@ -28,15 +28,33 @@ class ListTimeIndex(TimeIndex):
         extrapolate_first_point: bool,
         extrapolate_last_point: bool,
     ) -> None:
-        """Initialize the ListTimeIndex class."""
+        """
+        Initialize the ListTimeIndex class.
+
+        Args:
+            datetime_list (list[datetime]): List of datetime objects defining the time index. Must be ordered and contain more than one element.
+            is_52_week_years (bool): Whether to use 52-week years. If False, full iso calendar years are used.
+            extrapolate_first_point (bool): Whether to extrapolate the first point.
+            extrapolate_last_point (bool): Whether to extrapolate the last point.
+
+        Raises:
+            ValueError: If datetime_list has less than two elements or is not ordered.
+
+        """
         dts = datetime_list
         if len(dts) <= 1:
-            message = f"datetime_list must contain more than one element. Got {datetime_list}"
-            raise ValueError(message)
+            msg = f"datetime_list must contain more than one element. Got {datetime_list}"
+            raise ValueError(msg)
         if not all(dts[i] < dts[i + 1] for i in range(len(dts) - 1)):
-            message = f"All elements of datetime_list must be smaller/lower than the succeeding element. Dates must be ordered. Got {datetime_list}."
-            raise ValueError(message)
-        assert len(set(dt.tzinfo for dt in dts if dt is not None)) <= 1
+            msg = f"All elements of datetime_list must be smaller/lower than the succeeding element. Dates must be ordered. Got {datetime_list}."
+            raise ValueError(msg)
+        if len(set(dt.tzinfo for dt in dts if dt is not None)) > 1:
+            msg = f"Datetime objects in datetime_list have differing time zone information: {set(dt.tzinfo for dt in dts if dt is not None)}"
+            raise ValueError(msg)
+        if is_52_week_years and any(dts[i].isocalendar().week == 53 for i in range(len(dts))):  # noqa: PLR2004
+            msg = "When is_52_week_years is True, datetime_list should not contain week 53 datetimes."
+            raise ValueError(msg)
+
         self._datetime_list = datetime_list
         self._is_52_week_years = is_52_week_years
         self._extrapolate_first_point = extrapolate_first_point
@@ -103,27 +121,38 @@ class ListTimeIndex(TimeIndex):
         start_time = self._datetime_list[0]
         stop_time = self._datetime_list[-1]
         start_year, start_week, start_weekday = start_time.isocalendar()
+
+        if not start_weekday == start_week == 1:
+            return False
+
         if self._is_52_week_years:
-            return (start_weekday == 1) and (start_week == 1) and (stop_time == start_time + timedelta(weeks=52))
+            expected_stop_time = start_time + timedelta(weeks=52)
+            if expected_stop_time.isocalendar().week == 53:  # noqa: PLR2004
+                expected_stop_time += timedelta(weeks=1)
+            return stop_time == expected_stop_time
+
         stop_year, stop_week, stop_weekday = stop_time.isocalendar()
-        return (start_year + 1 == stop_year) and (start_weekday == stop_weekday == 1) and (start_week == stop_week == 1)
+        return (start_year + 1 == stop_year) and (stop_weekday == stop_week == 1)
 
     def is_whole_years(self) -> bool:
         """Return True if index covers one or more full years."""
         start_time = self._datetime_list[0]
-        start_year, start_week, start_weekday = start_time.isocalendar()
+        _, start_week, start_weekday = start_time.isocalendar()
+
         if not start_week == start_weekday == 1:
             return False
 
         stop_time = self._datetime_list[-1]
+
         if not self.is_52_week_years():
-            stop_year, stop_week, stop_weekday = stop_time.isocalendar()
-            assert stop_year >= start_year
+            _, stop_week, stop_weekday = stop_time.isocalendar()
             return stop_week == stop_weekday == 1
 
-        seconds_52_week_year = 52 * 168 * 3600
-        num_years = (stop_time - start_time).total_seconds() / seconds_52_week_year
-        return num_years.is_integer()
+        total_period = self.total_duration()
+        total_seconds = int(total_period.total_seconds())
+        seconds_per_year = 52 * 7 * 24 * 3600
+
+        return total_seconds % seconds_per_year == 0
 
     def extrapolate_first_point(self) -> bool:
         """Check if the TimeIndex should extrapolate the first point."""
@@ -135,7 +164,31 @@ class ListTimeIndex(TimeIndex):
 
     def get_period_average(self, vector: NDArray, start_time: datetime, duration: timedelta, is_52_week_years: bool) -> float:
         """Get the average over the period from the vector."""
-        # assert vector.shape == (self.get_num_periods(),), f"Vector shape {vector.shape} does not match timeindex {self}"
+        self._check_type(vector, np.ndarray)
+        self._check_type(start_time, datetime)
+        self._check_type(duration, timedelta)
+        self._check_type(is_52_week_years, bool)
+
+        if vector.shape != (self.get_num_periods(),):
+            msg = f"Vector shape {vector.shape} does not match number of periods {self.get_num_periods()} of timeindex ({self})."
+            raise ValueError(msg)
+
+        if not self.extrapolate_first_point():
+            if start_time < self._datetime_list[0]:
+                msg = f"start_time {start_time} is before start of timeindex {self._datetime_list[0]}, and extrapolate_first_point is False."
+                raise ValueError(msg)
+            if (start_time + duration) < self._datetime_list[0]:
+                msg = f"End time {start_time + duration} is before start of timeindex {self._datetime_list[0]}, and extrapolate_first_point is False."
+                raise ValueError(msg)
+
+        if not self.extrapolate_last_point():
+            if (start_time + duration) > self._datetime_list[-1]:
+                msg = f"End time {start_time + duration} is after end of timeindex {self._datetime_list[-1]}, and extrapolate_last_point is False."
+                raise ValueError(msg)
+            if start_time > self._datetime_list[-1]:
+                msg = f"start_time {start_time} is after end of timeindex {self._datetime_list[-1]}, and extrapolate_last_point is False."
+                raise ValueError(msg)
+
         target_timeindex = FixedFrequencyTimeIndex(
             start_time=start_time,
             period_duration=duration,
@@ -144,6 +197,7 @@ class ListTimeIndex(TimeIndex):
             extrapolate_first_point=self.extrapolate_first_point(),
             extrapolate_last_point=self.extrapolate_last_point(),
         )
+
         target_vector = np.zeros(1, dtype=vector.dtype)
         self.write_into_fixed_frequency(
             target_vector=target_vector,
@@ -158,18 +212,22 @@ class ListTimeIndex(TimeIndex):
         target_timeindex: FixedFrequencyTimeIndex,
         input_vector: NDArray,
     ) -> None:
-        """Write the input vector into the target vector using the target timeindex."""
+        """Write the input vector into the target vector using the target FixedFrequencyTimeIndex."""
+        self._check_type(target_vector, np.ndarray)
+        self._check_type(target_timeindex, FixedFrequencyTimeIndex)
+        self._check_type(input_vector, np.ndarray)
+
         dts: list[datetime] = self._datetime_list
 
-        durations = set(self._microseconds(dts[i + 1] - dts[i]) for i in range(len(dts) - 1))
+        durations = set(self._microseconds(period_duration(dts[i], dts[i + 1], self._is_52_week_years)) for i in range(len(dts) - 1))
         smallest_common_period_duration = functools.reduce(math.gcd, durations)
 
-        num_periods_ff = self._microseconds(dts[-1] - dts[0]) // smallest_common_period_duration
+        num_periods_ff = self._microseconds(self.total_duration()) // smallest_common_period_duration
         input_vector_ff = np.zeros(num_periods_ff, dtype=target_vector.dtype)
 
         i_start_ff = 0
         for i in range(len(dts) - 1):
-            num_periods = self._microseconds(dts[i + 1] - dts[i]) // smallest_common_period_duration
+            num_periods = self._microseconds(period_duration(dts[i], dts[i + 1], self._is_52_week_years)) // smallest_common_period_duration
             i_stop_ff = i_start_ff + num_periods
             input_vector_ff[i_start_ff:i_stop_ff] = input_vector[i]
             i_start_ff = i_stop_ff
@@ -189,9 +247,31 @@ class ListTimeIndex(TimeIndex):
             input_vector=input_vector_ff,
         )
 
+    def total_duration(self) -> timedelta:
+        """
+        Return the total duration covered by the time index.
+
+        Returns
+        -------
+        timedelta
+            The duration from the first to the last datetime in the index, skipping all weeks 53 periods if 52-week time format.
+
+        """
+        start_time = self._datetime_list[0]
+        end_time = self._datetime_list[-1]
+        return period_duration(start_time, end_time, self.is_52_week_years())
+
     def _microseconds(self, duration: timedelta) -> int:
         return int(duration.total_seconds() * 1e6)
 
     def is_constant(self) -> bool:
-        """Check if the time index is constant."""
-        return super().is_constant()
+        """
+        Return True if the time index is constant (single period and both extrapolation flags are True).
+
+        Returns
+        -------
+        bool
+            True if the time index is constant, False otherwise.
+
+        """
+        return self.get_num_periods() == 1 and self.extrapolate_first_point() == self.extrapolate_last_point() is True

framcore/timeindexes/ModelYear.py

@@ -4,10 +4,16 @@ from framcore.timeindexes.SinglePeriodTimeIndex import SinglePeriodTimeIndex  #
 
 
 class ModelYear(SinglePeriodTimeIndex):
-    """ModelYear represent one 52-week-year. No extrapolation."""
+    """ModelYear represent a period of 52 weeks starting from the iso calendar week 1 of a specified year. No extrapolation."""
 
     def __init__(self, year: int) -> None:
-        """Represent a specified year. Use 52-week-year starting on monday in week 1. No extrapolation."""
+        """
+        Initialize ModelYear to a period of 52 weeks starting from the iso calendar week 1 of the specified year. No extrapolation.
+
+        Args:
+            year (int): Year to represent.
+
+        """
         super().__init__(
             start_time=datetime.fromisocalendar(year, 1, 1),
             period_duration=timedelta(weeks=52),

framcore/timeindexes/ModelYears.py

@@ -4,10 +4,19 @@ from framcore.timeindexes.ListTimeIndex import ListTimeIndex  # NB! full import
 
 
 class ModelYears(ListTimeIndex):
-    """ModelYears represents a collection of years as a ListTimeIndex."""
+    """ModelYears represents a collection of years as a ListTimeIndex. Extrapolation is enabled and full iso calendar is used."""
 
     def __init__(self, years: list[int]) -> None:
-        """Initialize ModelYears with a list of years."""
+        """
+        Initialize ModelYears with a list of years.
+
+        Args:
+            years (list[int]): List of years to represent.
+
+        """
+        if not years:
+            raise ValueError("At least one year must be provided.")
+
         datetime_list = [datetime.fromisocalendar(year, 1, 1) for year in years]
         datetime_list.append(datetime.fromisocalendar(years[-1] + 1, 1, 1))
         super().__init__(

framcore/timeindexes/OneYearProfileTimeIndex.py

@@ -4,12 +4,20 @@ from framcore.timeindexes.ProfileTimeIndex import ProfileTimeIndex  # NB! full i
 
 
 class OneYearProfileTimeIndex(ProfileTimeIndex):
-    """Fixed frequency over one year."""
+    """
+    ProfileTimeIndex with fixed frequency over one year of either 52 or 53 weeks. No extrapolation inherited from ProfileTimeIndex.
+
+    Attributes:
+        period_duration (timedelta): Duration of each period.
+        is_52_week_years (bool): Whether to use 52-week years.
+
+    """
 
     def __init__(self, period_duration: timedelta, is_52_week_years: bool) -> None:
         """
-        Initialize a OneYearProfileTimeIndex with a fixed frequency over one year.
+        Initialize a ProfileTimeIndex with a fixed frequency over one year.
 
+        If is_52_week_years is True, the period_duration must divide evenly into 52 weeks. If False, it must divide evenly into 53 weeks.
         We use 1982 for 52-week years and 1981 for 53-week years.
 
         Args:

framcore/timeindexes/ProfileTimeIndex.py

@@ -4,7 +4,7 @@ from framcore.timeindexes.FixedFrequencyTimeIndex import FixedFrequencyTimeIndex
 
 
 class ProfileTimeIndex(FixedFrequencyTimeIndex):
-    """ProfileTimeIndex represent one or more whole years with fixed time resolution standard."""
+    """ProfileTimeIndex represent one or more whole years with fixed time resolution standard. No extrapolation."""
 
     def __init__(
         self,
@@ -13,14 +13,25 @@ class ProfileTimeIndex(FixedFrequencyTimeIndex):
         period_duration: timedelta,
         is_52_week_years: bool,
     ) -> None:
-        """Initialize the ProfileTimeIndex."""
+        """
+        Initialize the ProfileTimeIndex. No extrapolation.
+
+        Args:
+            start_year (int): First year in the index.
+            num_years (int): Number of years in the index.
+            period_duration (timedelta): Duration of each period in the index.
+            is_52_week_years (bool): Whether to use 52-week years. If False, full iso calendar years are used.
+
+        """
         start_time = datetime.fromisocalendar(start_year, 1, 1)
         if not is_52_week_years:
             stop_time = datetime.fromisocalendar(start_year + num_years, 1, 1)
             num_periods = (stop_time - start_time).total_seconds() / period_duration.total_seconds()
         else:
             num_periods = timedelta(weeks=52 * num_years).total_seconds() / period_duration.total_seconds()
-        assert num_periods.is_integer()
+        if not num_periods.is_integer():
+            msg = f"Number of periods derived from input arguments must be an integer/whole number. Got {num_periods}."
+            raise ValueError(msg)
         num_periods = int(num_periods)
         super().__init__(
             start_time=start_time,

framcore/timeindexes/SinglePeriodTimeIndex.py

@@ -6,7 +6,7 @@ from framcore.timeindexes.FixedFrequencyTimeIndex import FixedFrequencyTimeIndex
 
 
 class SinglePeriodTimeIndex(FixedFrequencyTimeIndex):
-    """FrequencyTimeIndex with just one single step."""
+    """FixedFrequencyTimeIndex with just one single step."""
 
     def __init__(
         self,

framcore/timeindexes/TimeIndex.py

@@ -48,8 +48,7 @@ class TimeIndex(Base, ABC):
         """
         Check if the TimeIndex represents a single year.
 
-        Must be False if
-        extrapolate_first_point and or extrapolate_last_point is True.
+        Must be False if extrapolate_first_point and or extrapolate_last_point is True.
 
         When True, can be repeted in profiles.
         """
@@ -57,6 +56,7 @@ class TimeIndex(Base, ABC):
 
     @abstractmethod
     def is_whole_years(self) -> bool:
+        """Check if the TimeIndex represents whole years."""
         pass
 
     @abstractmethod
@@ -81,7 +81,20 @@ class TimeIndex(Base, ABC):
         target_timeindex: FixedFrequencyTimeIndex,
         input_vector: NDArray,
     ) -> None:
-        """Write the input vector into the target vector based on the target FixedFrequencyTimeIndex."""
+        """
+        Write the input vector into the target vector based on the target FixedFrequencyTimeIndex.
+
+        Main functionality in FRAM to extracts data to the correct time period and resolution.
+        A conversion of the data into a specific time period and resolution follows these steps:
+        - If the TimeIndex is not a FixedFrequencyTimeIndex, convert the TimeIndex and the vector to this format.
+        - Then convert the data according to the target TimeIndex.
+        - It is easier to efficiently do time series operations between FixedFrequencyTimeIndex
+            and we only need to implement all the other conversion functionality once here.
+            For example, converting between 52-week and ISO-time TimeVectors, selecting a period, extrapolation or changing the resolution.
+        - And when we implement a new TimeIndex, we only need to implement the conversion to FixedFrequencyTimeIndex
+            and the rest of the conversion functionality can be reused.
+
+        """
         pass
 
     @abstractmethod

framcore/timeindexes/WeeklyIndex.py

@@ -4,7 +4,11 @@ from framcore.timeindexes.ProfileTimeIndex import ProfileTimeIndex  # NB! full i
 
 
 class WeeklyIndex(ProfileTimeIndex):
-    """One or more whole years with weekly resolution."""
+    """
+    ProfileTimeIndex with one or more whole years with weekly resolution. Either years with 52 weeks or full iso calendar years.
+
+    No extrapolation inherited from ProfileTimeIndex.
+    """
 
     def __init__(
         self,
@@ -12,7 +16,15 @@ class WeeklyIndex(ProfileTimeIndex):
         num_years: int,
         is_52_week_years: bool = True,
     ) -> None:
-        """One or more whole years with weekly resolution."""
+        """
+        Initialize WeeklyIndex with one or more whole years with weekly resolution. Either years with 52 weeks or full iso calendar years.
+
+        Args:
+            start_year (int): First year in the index.
+            num_years (int): Number of years in the index.
+            is_52_week_years (bool, optional): Whether to use 52-week years. If False, full iso calendar years are used. Defaults to True.
+
+        """
         super().__init__(
             start_year=start_year,
             num_years=num_years,

framcore/{expressions → timeindexes}/_time_vector_operations.py

@@ -80,7 +80,11 @@ def convert_to_modeltime(input_vector: NDArray, startdate: datetime, period_dura
     # check if the remaining period is compatible with the target period duration
     if remaining_period % period_duration != timedelta(0):
         suggested_period_duration = _common_compatible_period_duration(whole_duration, remaining_period)
-        err_message = f"Incompatible period duration detected! The resulting vector would be incompatible with period duration of {period_duration} after week 53 data is removed. Solution: use period duration that is compatible with both input and resulting vectors. Suggested period duration: {suggested_period_duration}."
+        err_message = (
+            f"Incompatible period duration detected! The resulting vector would be incompatible with period duration of {period_duration} "
+            f"after week 53 data is removed. Solution: use period duration that is compatible with both input and resulting vectors. "
+            f"Suggested period duration: {suggested_period_duration}."
+        )
         raise ValueError(err_message)
 
     sub_periods = _find_all_sub_periods(startdate, end_date, week_53_periods)
@@ -199,7 +203,12 @@ def convert_to_isotime(
     # check if the extended period is compatible with the target period duration
     if extended_total_duration % period_duration != timedelta(0):
         suggested_period_duration = _common_compatible_period_duration(total_duration, extended_total_duration)
-        err_message = f"Incompatible period duration detected when converting to ISO-time! The resulting vector would be incompatible with period duration of {period_duration} after week 53 data is added. Solution: use period duration that is compatible with both input and resulting vectors. Suggested period duration: {suggested_period_duration}."
+        err_message = (
+            f"Incompatible period duration detected when converting to ISO-time! "
+            f"The resulting vector would be incompatible with period duration of {period_duration} "
+            f"after week 53 data is added. Solution: use period duration that is compatible with both "
+            f"input and resulting vectors. Suggested period duration: {suggested_period_duration}."
+        )
         raise ValueError(err_message)
 
     sub_periods = _find_all_sub_periods(startdate,  end_date, week_53_periods)
@@ -613,3 +622,68 @@ def _find_all_week_53_periods(startdate: datetime, enddate: datetime) -> list[tu
             if start < end:
                 week_53_periods.append((start, end))
     return week_53_periods
+
+def calculate_52_week_years_stop_time(
+    start_time: datetime,
+    period_duration: timedelta,
+    num_periods: int,
+) -> datetime:
+    """
+    Calculate the stop time of an isotime time series.
+
+    Args:
+        start_time (datetime): The start date of the time series.
+        period_duration (timedelta): The duration of each period in the time series.
+        num_periods (int): The number of periods in the time series.
+
+    Returns:
+        datetime: The calculated stop time of the time series.
+
+    """
+    assert isinstance(start_time, datetime)
+    assert isinstance(period_duration, timedelta)
+    assert period_duration.total_seconds() > 0, "Period duration must be greater than zero."
+    assert isinstance(num_periods, int)
+    assert num_periods > 0, "Number of periods must be greater than zero."
+
+    stop_time = start_time + period_duration * num_periods
+    week_53_periods = _find_all_week_53_periods(startdate=start_time, enddate=stop_time)
+
+    if week_53_periods:
+        stop_time += timedelta(weeks=len(week_53_periods))
+
+    if stop_time.isocalendar().week == 53:
+        stop_time += timedelta(weeks=1)
+
+    return stop_time
+
+def period_duration(start_time: datetime, end_time: datetime, is_52_week_years: bool) -> timedelta:
+    if not is_52_week_years:
+        return end_time - start_time
+
+    return _period_duration_excluded_weeks_53(start_time, end_time)
+
+def _period_duration_excluded_weeks_53(start_time: datetime, end_time: datetime) -> timedelta:
+    """
+    Calculate the period duration excluding all week 53 periods.
+
+    Parameters
+    ----------
+    start_time : datetime
+        The start datetime.
+    end_time : datetime
+        The end datetime.
+
+    Returns
+    -------
+    timedelta
+        The period duration excluding all week 53 periods.
+
+    """
+    if end_time < start_time:
+        raise ValueError("end_time must be after or equal to start_time")
+
+    week_53_periods = _find_all_week_53_periods(startdate=start_time, enddate=end_time)
+    excluded_duration = _total_duration(week_53_periods)
+    total_duration = end_time - start_time
+    return total_duration - excluded_duration

framcore/timevectors/ConstantTimeVector.py

@@ -19,14 +19,14 @@ class ConstantTimeVector(TimeVector):
         reference_period: ReferencePeriod | None = None,
     ) -> None:
         """
-        Initialize the ListTimeVector class.
+        Initialize the ConstantTimeVector class.
 
         Args:
-            scalar (float): Constant float value of the timevector.
+            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 aprofile with values between 0 and 1, a
+            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
@@ -39,14 +39,6 @@ class ConstantTimeVector(TimeVector):
         """
         self._scalar = float(scalar)
         self._unit = unit
-
-        if (is_max_level is not None and is_zero_one_profile is not None) or (is_max_level is None and is_zero_one_profile is None):
-            message = (
-                f"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)
         self._is_max_level = is_max_level
         self._is_zero_one_profile = is_zero_one_profile
         self._reference_period = reference_period
@@ -57,13 +49,14 @@ class ConstantTimeVector(TimeVector):
         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()
-            assert num_years > 0
             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 ""
@@ -73,7 +66,7 @@ class ConstantTimeVector(TimeVector):
     def __eq__(self, other: object) -> bool:
         """Check equality between two ConstantTimeVector objects."""
         if not isinstance(other, ConstantTimeVector):
-            return NotImplemented
+            return False
         return (
             self._scalar == other._scalar
             and self._unit == other._unit
@@ -88,7 +81,10 @@ class ConstantTimeVector(TimeVector):
 
     def get_expr_str(self) -> str:
         """Simpler representation of self to show in Expr."""
-        return f"{self._scalar} {self._unit if self._unit else ''}"
+        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."""
@@ -105,11 +101,11 @@ class ConstantTimeVector(TimeVector):
         """Check if the TimeVector is constant."""
         return True
 
-    def is_max_level(self) -> bool:
+    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:
+    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
 

framcore/timevectors/LinearTransformTimeVector.py

@@ -9,7 +9,7 @@ from framcore.timevectors.TimeVector import TimeVector  # NB! full import path n
 
 
 class LinearTransformTimeVector(TimeVector):
-    """LinearTransformTimeVector(TimeVector). Immutable."""
+    """LinearTransformTimeVector represents a TimeVector as scale * timevector + shift. Immutable."""
 
     def __init__(
         self,
@@ -22,9 +22,24 @@ class LinearTransformTimeVector(TimeVector):
         reference_period: ReferencePeriod | None = None,
     ) -> None:
         """
-        Transform timevector into scale * timevector + shift.
+        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.
 
-        May also override unit, is_max_level,  is_zero_one_profile and reference_period.
         """
         self._check_type(timevector, TimeVector)
         self._check_type(scale, float)
@@ -41,6 +56,8 @@ class LinearTransformTimeVector(TimeVector):
         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)