rangekeeper 0.1.0__py3-none-any.whl

rangekeeper/periodicity.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import math
+from typing import Union, Optional
+
+import aenum
+import enum
+from datetime import datetime
+import dateutil.relativedelta
+import pandas as pd
+
+import rangekeeper as rk
+
+class Type(enum.Enum):
+    YEAR = 'A-DEC'  # Anchored on end of December
+    QUARTER = 'Q-DEC'  # Anchored on end of March, June, September, & December
+    MONTH = 'M'  # Anchored on end-of-month
+    SEMIMONTH = 'SM'  # Twice-monthly periods anchored on mid-month and end-of-month dates
+    WEEK = 'W'  # Anchored on Sundays
+    DAY = 'D'  # Daily
+
+
+def from_value(value: str):
+    if value == 'A-DEC':
+        return Type.YEAR
+    if value == 'Q-DEC':
+        return Type.QUARTER
+    if value == 'M':
+        return Type.MONTH
+    if value == 'SM':
+        return Type.SEMIMONTH
+    if value == 'W':
+        return Type.WEEK
+    if value == 'D':
+        return Type.DAY
+
+
+def include_date(
+        date: pd.Timestamp,
+        duration: Type) -> pd.Period:
+    """
+    Returns a pd.Period that encompasses the given date
+    """
+
+    return pd.Period(year=date.year, month=date.month, day=date.day, freq=duration.value)
+
+
+def period_index(
+        include_start: pd.Timestamp,
+        period_type: Type,
+        bound: Union[pd.Timestamp, int] = None) -> pd.PeriodIndex:
+    """
+    Returns a pd.PeriodIndex from a start date with periods of given duration.
+    Either an end date, or number of periods must be given to bound the sequence.
+
+    :param include_start: pd.Timestamp start date
+    :param period_type: Period frequency
+    :param bound: A terminating condition; either a pd.Timestamp end date or a (integer) number of periods
+    """
+    if isinstance(bound, pd.Timestamp):
+        return pd.period_range(
+            start=include_start,
+            end=bound,
+            freq=period_type.value,
+            name='periods')
+    elif isinstance(bound, int):
+        return pd.period_range(
+            start=include_start,
+            periods=bound,
+            freq=period_type.value,
+            name='periods')
+
+def offset_periodindex(
+        index: pd.PeriodIndex,
+        offset_start: Optional[int] = None,
+        offset_end: Optional[int] = None) -> pd.PeriodIndex:
+    """
+    Returns a pd.PeriodIndex with periods offset by given number of periods (of type given by the index)
+    """
+    start = index[0].to_timestamp()
+    if offset_start is not None:
+        start = offset_date(
+            date=period_index[0].to_timestamp(),
+            period_type=from_value(index.freq),
+            num_periods=offset_start)
+    end = index[-1].to_timestamp()
+    if offset_end is not None:
+        end = offset_date(
+            date=index[-1].to_timestamp(),
+            period_type=from_value(index.freq),
+            num_periods=offset_end)
+    return period_index(
+        include_start=start,
+        period_type=from_value(index.freq),
+        bound=end)
+
+def to_span(period_index: pd.PeriodIndex):
+    """
+    Returns a Span encompassing a pd.PeriodIndex
+    """
+    return rk.span.Span(
+        start_date=period_index[0].to_timestamp(how='start'),
+        end_date=period_index[-1].to_timestamp(how='end'))
+
+def single_period_index(period: pd.Period) -> pd.PeriodIndex:
+    return pd.period_range(
+        start=period,
+        periods=1)
+
+
+def to_datestamps(
+        period_index: pd.PeriodIndex,
+        end: bool = True) -> pd.DatetimeIndex:
+    """
+    Returns a pd.DatetimeIndex from a pd.PeriodIndex with Datetimes being Dates
+    :param end: If True, the end of the period is used. If False, the start of the period is used.
+    """
+    if end:
+        timestamps = period_index.to_timestamp(how='end')
+    else:
+        timestamps = period_index.to_timestamp(how='start')
+    datestamps = timestamps.date
+    return pd.DatetimeIndex(datestamps)
+
+
+def periods_per_year(period_type: Type) -> int:
+    return {
+        Type.YEAR: 1,
+        Type.QUARTER: 4,
+        Type.MONTH: 12,
+        Type.SEMIMONTH: 24,
+        Type.WEEK: 52,
+        Type.DAY: 365
+        }.get(period_type, None)
+
+
+def offset_date(
+        date: pd.Timestamp,
+        period_type: Type = Type.DAY,
+        num_periods: int = 1) -> pd.Timestamp:
+    """
+    Offsets a date by a given number of periods
+    :param date:
+    :type date:
+    :param period_type:
+    :type period_type:
+    :param num_periods:
+    :type num_periods:
+    :return:
+    :rtype:
+    """
+    if period_type.value == Type.YEAR.value:
+        return date + pd.DateOffset(years=num_periods)
+    elif period_type.value == Type.QUARTER.value:
+        return date + pd.DateOffset(months=3 * num_periods)
+    elif period_type.value == Type.MONTH.value:
+        return date + pd.DateOffset(months=num_periods)
+    elif period_type.value == Type.WEEK.value:
+        return date + pd.DateOffset(weeks=num_periods)
+    elif period_type.value == Type.DAY.value:
+        return date + pd.DateOffset(days=num_periods)
+
+
+def duration(
+        start_date: pd.Timestamp,
+        end_date: pd.Timestamp,
+        period_type: Type,
+        inclusive: bool = False) -> int:
+    """
+    Returns the whole integer (i.e. no remainder) number of periods between
+    given dates.
+    If inclusive is True, the end_date is included in the calculation.
+    """
+    calc_end_date = end_date
+    if inclusive:
+        calc_end_date = offset_date(
+            date=end_date,
+            period_type=Type.DAY,
+            num_periods=1)
+
+    delta = dateutil.relativedelta.relativedelta(calc_end_date, start_date)
+
+    if period_type.value == Type.YEAR.value:
+        result = delta.years
+    elif period_type.value == Type.QUARTER.value:
+        result = (delta.years * 4) + math.floor(delta.months / 3)
+    elif period_type.value == Type.MONTH.value:
+        result = (delta.years * 12) + delta.months
+    elif period_type.value == Type.SEMIMONTH.value:
+        result = (delta.years * 24) + delta.months * 2
+    elif period_type.value == Type.WEEK.value:
+        result = math.floor((calc_end_date - start_date).days / 7)
+    elif period_type.value == Type.DAY.value:
+        result = (calc_end_date - start_date).days
+    else:
+        raise ValueError('Unsupported period type: {0}'.format(period_type))
+
+    def direction(rd: dateutil.relativedelta.relativedelta) -> int:
+        """
+        Check whether a relativedelta object is negative
+        From https://stackoverflow.com/a/57906103/10964780
+        """
+        try:
+            datetime.min + rd
+            return 1
+        except OverflowError:
+            return -1
+
+    return result * direction(delta)
+
+
+def to_range_index(
+        period_index: pd.PeriodIndex,
+        start_period: pd.Period = None,
+        end_period: pd.Period = None) -> pd.RangeIndex:
+    """
+    Returns a RangeIndex that maps a PeriodIndex to a range of integers.
+    """
+
+    index_offset = None
+    if start_period is None:
+        start_period = period_index[0]
+    if end_period is None:
+        end_period = period_index[-1]
+    bounds_index = pd.period_range(
+        start=start_period,
+        end=end_period,
+        freq=period_index.freq)
+
+    for i in range(bounds_index.size):
+        if period_index.__contains__(bounds_index[i]):
+            index_offset = i
+            break
+        else:
+            continue
+    return pd.RangeIndex(start=index_offset, stop=period_index.size + index_offset, step=1)

rangekeeper/policy.py

@@ -0,0 +1,20 @@
+from abc import abstractmethod
+from typing import Callable, List, Any, Dict
+
+import rangekeeper as rk
+
+
+class Policy:
+    def __init__(
+            self,
+            condition: Callable[[rk.flux.Flow], List[bool]],
+            action: Callable[[object, List[bool]], object]):
+        self.condition = condition
+        self.action = action
+
+    def execute(
+            self,
+            args: tuple) -> object:
+        state, model = args  # This is done to assist multiprocessing
+        decision = self.condition(state)
+        return self.action(model, decision)

rangekeeper/projection.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import enum
+import typing
+from typing import Optional, Union, Tuple
+
+import enum
+import numpy as np
+import pandas as pd
+import scipy.stats as ss
+
+import rangekeeper as rk
+
+
+class Padding(enum.Enum):
+    """
+    Enum for padding types.
+    """
+    NIL = 'nil'  # Zero out factors or densities until bound
+    UNITIZE = 'unitize'  # Repeat unit factor or density until bound
+    EXTEND = 'extend'  # 'Repeat last factor or density until bound'
+
+
+class Projection:
+    sequence: pd.PeriodIndex
+    bounds: Tuple[pd.Period, pd.Period]
+
+    def __init__(
+            self,
+            sequence: pd.PeriodIndex,
+            bounds: Tuple[pd.Period, pd.Period] = None):
+        self.sequence = sequence
+
+        if bounds is None:
+            self.bounds = (sequence[0], sequence[-1])
+        else:
+            self.bounds = bounds
+
+    # def __init__(
+    #         self,
+    #         sequence: Union[pd.RangeIndex, pd.PeriodIndex],
+    #         bounds: Union[Tuple[int, int], Tuple[pd.Period, pd.Period]] = None):
+    #
+    #     if isinstance(sequence, pd.RangeIndex):
+    #         if bounds is None:
+    #             self.sequence = sequence
+    #             self.bounds = (0, len(sequence))
+    #         elif isinstance(bounds[0], int):
+    #             self.sequence = sequence
+    #             self.bounds = bounds
+    #         else:
+    #             raise ValueError(f"sequence and bounds must match in type (int or pd.Period)")
+    #
+    #     elif isinstance(sequence, pd.PeriodIndex):
+    #         if bounds is None:
+    #             self.sequence = periodicity.to_range_index(
+    #                 period_index=sequence)
+    #             self.bounds = (0, len(sequence))
+    #         elif isinstance(bounds[0], pd.Period):
+    #             self.sequence = periodicity.to_range_index(
+    #                 period_index=sequence,
+    #                 start=bounds[0],
+    #                 end=bounds[1])
+    #             bounds_range = pd.period_range(
+    #                 start=bounds[0],
+    #                 end=bounds[1],
+    #                 freq=sequence.freq)
+    #             self.bounds = (0, len(bounds_range))
+    #         else:
+    #             raise ValueError(f"sequence and bounds must match in type (int or pd.Period)")
+    #
+    #     else:
+    #         raise ValueError(f"sequence must be of type (pd.RangeIndex or pd.PeriodIndex)")
+
+    @staticmethod
+    def _pad(
+            value: float,
+            length: int,
+            type: Optional[Padding]) -> np.ndarray:
+        if type == Padding.NIL:
+            return np.zeros(shape=length)
+        elif type == Padding.UNITIZE:
+            return np.ones(shape=length)
+        elif type == Padding.EXTEND:
+            return np.full(shape=length, fill_value=value)
+        elif type is None:
+            return np.empty(shape=0)
+
+
+class Extrapolation(Projection):
+    form: rk.extrapolation.Form
+    padding: Tuple[Optional[Padding], Optional[Padding]]
+
+    def __init__(
+            self,
+            form: rk.extrapolation.Form,
+            sequence: pd.PeriodIndex,
+            bounds: Tuple[pd.Period, pd.Period] = None,
+            padding: Tuple[Padding, Padding] = None):
+        super().__init__(
+            sequence=sequence,
+            bounds=bounds)
+        self.form = form
+
+        if padding is None:
+            if self.bounds[0] == sequence[0] and self.bounds[1] == sequence[-1]:
+                self.padding = (None, None)
+            else:
+                raise ValueError('Error: Since the bounds do not match sequence start & end,'
+                                 ' padding must be specified.')
+        else:
+            self.padding = padding
+
+    def terms(self) -> pd.Series:
+        terms = self.form.terms(
+            sequence=rk.periodicity.to_range_index(period_index=self.sequence))
+        left_length = self.sequence[0] - self.bounds[0]
+        right_length = self.bounds[1] - self.sequence[-1]
+        left = self._pad(
+            value=terms[0],
+            length=left_length.n,
+            type=self.padding[0])
+        right = self._pad(
+            value=terms[-1],
+            length=right_length.n,
+            type=self.padding[1])
+        data = np.concatenate((left, terms, right))
+
+        return pd.Series(
+            data=data,
+            index=rk.periodicity.to_datestamps(
+                rk.periodicity.period_index(
+                    include_start=self.bounds[0].to_timestamp(how='start'),
+                    period_type=rk.periodicity.from_value(self.sequence.freq),
+                    bound=self.bounds[1].to_timestamp(how='start'))))
+
+
+class Distribution(Projection):
+    form: rk.distribution.Form
+
+    def __init__(
+            self,
+            form: rk.distribution.Form,
+            sequence: pd.PeriodIndex,
+            bounds: Tuple[pd.Period, pd.Period] = None):
+        super().__init__(
+            sequence=sequence)
+        self.form = form
+
+        if bounds is None:
+            self.bounds = (sequence[0], sequence[-1])
+        elif (bounds[0] > sequence[0]) or (bounds[1] < sequence[-1]):
+            raise ValueError('Error: Bounds cannot be within the sequence for '
+                             'Distribution Projections')
+        else:
+            self.bounds = bounds
+
+        self._parameters = self._seq_to_params()
+
+        left_length = self.sequence[0] - self.bounds[0]
+        right_length = self.bounds[1] - self.sequence[-1]
+        self._left_padding = self._pad(
+            value=0,
+            length=left_length.n,
+            type=Padding.NIL)
+        self._right_padding = self._pad(
+            value=0,
+            length=right_length.n,
+            type=Padding.NIL)
+
+        # self._index = periodicity.period_index(
+        #     include_start=self.bounds[0].to_timestamp(),
+        #     period_type=periodicity.from_value(self.sequence.freq),
+        #     bound=self.bounds[1].to_timestamp())
+
+    def _seq_to_params(self) -> [float]:
+        range_index = rk.periodicity.to_range_index(
+            period_index=self.sequence)
+        range_index = range_index.insert(
+            loc=len(range_index),
+            item=range_index[-1] + 1)
+        max = range_index[-1]
+        return [index / max for index in range_index]
+
+    def interval_density(self) -> pd.Series:
+        densities = self.form.interval_density(parameters=self._parameters)
+        data = np.concatenate((self._left_padding, densities, self._right_padding))
+
+        return pd.Series(
+            data=data,
+            index=rk.periodicity.to_datestamps(
+                rk.periodicity.period_index(
+                    include_start=self.bounds[0].to_timestamp(),
+                    period_type=rk.periodicity.from_value(self.sequence.freq),
+                    bound=self.bounds[1].to_timestamp())))
+
+    def cumulative_density(self) -> [float]:
+        densities = self.form.cumulative_density(parameters=self._parameters)
+        data = np.concatenate((self._left_padding, densities, self._right_padding))
+
+        period_index = rk.periodicity.period_index(
+            include_start=self.bounds[0].to_timestamp(),
+            period_type=rk.periodicity.from_value(self.sequence.freq),
+            bound=self.bounds[1].to_timestamp())
+        datestamp_index = rk.periodicity.to_datestamps(period_index=period_index)
+        datestamp_index = datestamp_index.insert(loc=0, item=self.bounds[0].start_time)
+
+        return pd.Series(
+            data=data,
+            index=datestamp_index)
+
+# class DistributiveInterpolation(Interpolation):
+#     """
+#     A projection that apportions values over a range, according to a specified
+#     distribution type.
+#     """
+#     dist: distribution.Form
+#
+#     def __init__(
+#             self,
+#             dist: distribution.Form,
+#             sequence: Union[pd.RangeIndex, pd.PeriodIndex],
+#             bounds: Union[Tuple[int, int], Tuple[pd.Period, pd.Period]]):
+#         super().__init__(
+#             sequence=sequence,
+#             bounds=bounds)
+#         self.dist = dist
+
+# def map(
+#         self,
+#         left_padding: Padding = None,
+#         right_padding: Padding = None) -> pd.Series:
+
+
+# if isinstance(self.sequence, pd.RangeIndex):
+#     if isinstance(self, Extrapolation):
+#         factors = self.factor()
+#         left = self.pad(
+#             value=factors[0],
+#             length=self.sequence[0] - self.bounds[0],
+#             type=left_padding)
+#         right = self.pad(
+#             value=factors[-1],
+#             length=self.bounds[1] - self.sequence[-1],
+#             type=right_padding)
+#         return pd.Series(
+#             data=np.concatenate((left, factors, right)),
+#             index=range(self.bounds[0], self.bounds[1]))