rangekeeper 0.1.0__py3-none-any.whl

rangekeeper/segmentation.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import enum
+import math
+from typing import List, Dict, Union, Tuple
+from collections import namedtuple
+
+import pandas as pd
+import numpy as np
+from aenum import Enum
+
+
+class Characteristic(Enum):
+    _init_ = 'value'
+
+    use = 'Use'
+    tenure = 'Tenure'
+    span = 'Span'
+    type = 'Type'
+
+
+class Type:
+    name: str
+    code: str
+    supertype: Type
+    subtypes: [Type]
+
+    def __init__(
+            self,
+            name: str,
+            code: str = None,
+            supertype: Type = None):
+        self.name = name
+        self.code = code
+        self.supertype = supertype
+        self.subtypes = []
+
+        if supertype is not None:
+            supertype.subtypes.append(self)
+
+    def __str__(self):
+        code = ' :' + self.code if self.code is not None else ''
+        return self.name + code
+
+    def add_subtypes(
+            self,
+            subtypes: [Type]):
+        for subtype in subtypes:
+            self.subtypes.append(subtype)
+            subtype.supertype = self
+
+    def ancestors(self) -> [Type]:
+        ancestors = []
+        supertype = self.supertype
+        while supertype is not None:
+            ancestors.append(supertype)
+            supertype = supertype.supertype
+        return ancestors
+
+    def primogenitor(self) -> Type:
+        return self.ancestors()[-1]
+
+    def display(self):
+        print(' > '.join([ancestor.__str__() for ancestor in self.ancestors()]))
+
+
+class Interval(pd.Interval):
+    def __init__(
+            self,
+            right: float,
+            left: float = 0.):
+        super().__init__(
+            left=left,
+            right=right)
+
+    def __str__(self):
+        return f'({self.left}, {self.right})'
+
+    def split(
+            self,
+            proportion: float) -> tuple[Interval, Interval]:
+        if proportion < 0 or proportion > 1:
+            raise ValueError('Error: proportion must be between 0 and 1')
+
+        split_point = self.left + (proportion * self.length)
+        left_interval = self.__class__(
+            right=split_point,
+            left=self.left)
+        right_interval = self.__class__(
+            right=self.right,
+            left=split_point)
+        return left_interval, right_interval
+
+    def subdivide(
+            self,
+            values: Union[int, List[float]]) -> List[Interval]:
+        if isinstance(values, int):
+            if values < 0:
+                raise ValueError('Error: divisors must be greater than 0')
+            lengths = [self.length / values for i in range(values)]
+        elif all(isinstance(fraction, float) for fraction in values):
+            if math.isclose(sum(values), 1) and all(0 < fraction < 1 for fraction in values):
+                lengths = [self.length * fraction for fraction in values]
+            else:
+                raise ValueError('Error: Sum of divisors must complete unit interval')
+        else:
+            raise TypeError('Error: values must be either number of divisors or split proportions')
+
+        parameters = [self.left + sum(lengths[:i]) for i in range(1, len(lengths) + 1)]
+        parameters.insert(0, self.left)
+        results = []
+        for i in range(len(parameters) - 1):
+            results.append(
+                self.__class__(
+                    left=parameters[i],
+                    right=parameters[i + 1]))
+        return results
+
+    def interval_value(self):
+        return self.right - self.left
+
+
+class Segment:
+    name: str
+    bounds: Interval
+    parent: Segment
+    children: List[Segment]
+    characteristics: Dict[Characteristic, str]
+
+    def __init__(
+            self,
+            bounds: Interval,
+            characteristics: Dict[Characteristic, str] = None,
+            parent: Segment = None,
+            children: List[Segment] = None,
+            name: str = None):
+        self.name = name
+        self.bounds = bounds
+        self.characteristics = {} if characteristics is None else characteristics
+
+        if parent is not None:
+            parent.children.append(self)
+        self.parent = parent
+
+        if children is not None: # Need to run tests on this to check this works.
+            for child in children:
+                child.parent = self
+        self.children = [] if children is None else children
+
+    def to_frame(self):
+        frame = pd.DataFrame(
+            data=[list(self.characteristics.values())],
+            index=pd.IntervalIndex(data=[self.bounds]),
+            columns=[characteristic.value for characteristic in self.characteristics.keys()])
+        frame['Amount'] = self.bounds.length
+
+        if self.parent is not None:
+            frame['Proportion (of Parent)'] = "{:.0%}".format(self.bounds.length / self.parent.bounds.length)
+
+        return frame
+
+    def display(self):
+        print('\n')
+        floatfmt = "." + str(2) + "f"
+        print(self.to_frame().to_markdown(
+            tablefmt='github',
+            floatfmt=floatfmt))
+
+    def display_children(
+            self,
+            pivot: Characteristic = None,
+            decimals: int = 2,
+            ):
+        if len(self.children) == 0:
+            raise ValueError("Error: Segment has no children")
+
+        frame = pd.concat([child.to_frame() for child in self.children])
+        pivot_name = ''
+        if pivot is not None:
+            frame = pd.pivot_table(
+                data=frame,
+                index=[pivot.value],
+                aggfunc=np.sum
+                # columns=['Amount', 'Use', 'Proportion (of Parent)']
+                )
+            frame['Proportion (of Parent)'] = frame['Amount'] / self.bounds.length
+            frame['Proportion (of Parent)'] = frame['Proportion (of Parent)'].map("{:.0%}".format)
+            pivot_name = ' by ' + pivot.value
+
+        floatfmt = "." + str(decimals) + "f"
+
+        print('Children' + pivot_name)
+        print(frame.to_markdown(
+            tablefmt='github',
+            floatfmt=floatfmt))
+
+    # def display_hierarchy(self):
+
+    def split(self, proportion: float) -> tuple[Segment, Segment]:
+        split_lower, split_upper = self.bounds.split(proportion)
+        lower = Segment(
+            bounds=split_lower,
+            parent=self)
+        upper = Segment(
+            bounds=split_upper,
+            parent=self)
+        return (lower, upper)
+
+    def subdivide(
+            self,
+            divisions: List[Tuple[str, Dict[Characteristic, str], float]]) -> List[Segment]:
+        result = []
+        intervals = self.bounds.subdivide([division[2] for division in divisions])
+        for name, division, interval in zip([division[0] for division in divisions],[division[1] for division in divisions], intervals):
+            result.append(Segment(
+                name=name,
+                bounds=interval,
+                characteristics=division,
+                parent=self))
+        return result

rangekeeper/setup.py

@@ -0,0 +1,14 @@
+from setuptools import setup
+
+setup(
+    name='Rangekeeper',
+    version='0.2.0-alpha',
+    packages=['models', 'dynamics'],
+    package_dir={'': 'rangekeeper'},
+    url='https://github.com/daniel-fink/rangekeeper',
+    license='MPL-2.0',
+    author='Daniel Fink',
+    author_email='danfink@mit.edu',
+    description='Rangekeeper is a library assisting financial modelling in real estate scenario planning, decision-making, cashflow forecasting, and the like.'
+    )
+

rangekeeper/space.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+from typing import Dict, List, Union, Optional
+from decimal import Decimal
+from pint import Quantity
+
+import rangekeeper as rk
+
+
+class Space(rk.graph.Element):
+    def __init__(
+            self,
+            name: str,
+            type: str,
+            measurements: Dict[rk.measure.Measure, Quantity] = None,
+            events: List[rk.graph.Event] = None,
+            attributes: Dict = None):
+        super().__init__(
+            name=name,
+            type=type,
+            measurements=measurements,
+            events=events,
+            attributes=attributes)
+
+
+class Apartment(Space):
+    num_bed: int
+    num_bath: Decimal
+    num_balcony: int
+
+    def __init__(
+            self,
+            name: str,
+            type: str,
+            num_bed: int,
+            num_bath: Union[int, Decimal],
+            num_balcony: Optional[int] = None,
+            measurements: Dict[rk.measure.Measure, Quantity] = None,
+            attributes: Dict = None):
+        super().__init__(name, type, measurements, attributes)
+        self.num_bed = num_bed
+        self.num_bath = num_bath
+        self.num_balcony = num_balcony

rangekeeper/span.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+import rangekeeper as rk
+
+class Span:
+    start_date: pd.Timestamp
+    end_date: pd.Timestamp
+    name: str = None
+    """
+    A `Span` is a pd.Interval of pd.Timestamps that bound its start and end dates
+    """
+
+    def __init__(
+            self,
+            start_date: pd.Timestamp,
+            end_date: pd.Timestamp = None,
+            name: str = None):
+        """
+        Define a Span using dates and a name. If no end date is provided, it is
+        assumed to be a one-day Span (ie, the start and end dates are the same)
+        :param start_date:
+        :param end_date:
+        :param name:
+        """
+        if end_date is None:
+            end_date = start_date
+        elif end_date < start_date:
+            raise Exception('Error: end_date cannot be before start_date')
+
+        if name is None:
+            self.name = ''
+        else:
+            self.name = name
+
+        self._interval = pd.Interval(left=start_date, right=end_date)
+        self.start_date = self._interval.left
+        self.end_date = self._interval.right
+
+    def __str__(self):
+        return 'Span: {}\n' \
+               'Start Date: {}\n' \
+               'End Date: {}'.format(self.name, self.start_date.date(), self.end_date.date())
+
+    def __repr__(self):
+        return self.__str__()
+
+    @classmethod
+    def merge(
+            cls,
+            name: str,
+            spans: [Span]) -> Span:
+        """
+        Merge a set of Spans into a single Span
+        """
+        start_date = spans[0].start_date
+        end_date = spans[0].end_date
+        for span in spans:
+            if span.start_date < start_date:
+                start_date = span.start_date
+            if span.end_date > end_date:
+                end_date = span.end_date
+        return cls(name=name,
+                   start_date=start_date,
+                   end_date=end_date)
+
+    def shift(self,
+              num_periods: int,
+              period_type: rk.periodicity.Type,
+              bound: str = 'end',
+              name: str = None) -> Span:
+        """
+        Shift the Span's bounds by a specified period increment
+
+        :param num_periods: The number of periods to shift the bounds
+        :param period_type: The period type of the shift
+        :param bound: The bound to shift. Options are 'start', 'end', or 'both'
+        """
+        name = self.name if name is None else name
+        if bound == 'start':
+            return Span(
+                name=name,
+                start_date=rk.periodicity.offset_date(
+                    date=self.start_date,
+                    period_type=period_type,
+                    num_periods=num_periods),
+                end_date=self.end_date)
+        elif bound == 'end':
+            return Span(
+                name=name,
+                start_date=self.start_date,
+                end_date=rk.periodicity.offset_date(
+                    date=self.end_date,
+                    period_type=period_type,
+                    num_periods=num_periods))
+        elif bound == 'both':
+            return Span(
+                name=name,
+                start_date=rk.periodicity.offset_date(
+                    date=self.start_date,
+                    period_type=period_type,
+                    num_periods=num_periods),
+                end_date=rk.periodicity.offset_date(
+                    date=self.end_date,
+                    period_type=period_type,
+                    num_periods=num_periods))
+        else:
+            raise Exception('Error: invalid bound specified')
+
+    def to_index(
+            self,
+            period_type: rk.periodicity.Type) -> pd.PeriodIndex:
+        """
+        Return a pd.PeriodIndex of the Span at the specified periodicity
+        """
+        return rk.periodicity.period_index(
+            include_start=self.start_date,
+            period_type=period_type,
+            bound=self.end_date)
+
+    def duration(
+            self,
+            period_type: rk.periodicity.Type,
+            inclusive: bool = False) -> int:
+        """
+        Return the whole-period duration of the Span in the specified period_type
+        """
+        return rk.periodicity.duration(
+            start_date=self.start_date,
+            end_date=self.end_date,
+            period_type=period_type,
+            inclusive=inclusive)
+
+    @classmethod
+    def from_num_periods(
+            cls,
+            name: str,
+            date: pd.Timestamp,
+            period_type: rk.periodicity.Type,
+            num_periods: int) -> Span:
+        """
+        Create a Span from a date with a set number of periods of specified type.
+        If the number of periods is negative, the Span will end on the date specified.
+        If the number of periods is positive, the Span will start on the date specified.
+        """
+        if num_periods < 0:
+            end_date = date
+            start_date = rk.periodicity.offset_date(
+                date=date,
+                period_type=period_type,
+                num_periods=num_periods)
+            start_date = rk.periodicity.offset_date(
+                date=start_date,
+                period_type=rk.periodicity.Type.DAY,
+                num_periods=1)
+            return cls(name=name, start_date=start_date, end_date=end_date)
+        else:
+            start_date = date
+            end_date = rk.periodicity.offset_date(
+                date=date,
+                period_type=period_type,
+                num_periods=num_periods)
+            end_date = rk.periodicity.offset_date(
+                date=end_date,
+                period_type=rk.periodicity.Type.DAY,
+                num_periods=-1)
+            return cls(name=name, start_date=start_date, end_date=end_date)
+
+    @classmethod
+    def from_date_sequence(
+            cls,
+            names: [str],
+            dates: [pd.Timestamp]) -> [Span]:
+        """
+        Create a set of Spans from a sequence of dates.
+        Note: dates list length must be 1 longer than names
+        :param names:
+        :type names:
+        :param dates:
+        :type dates:
+        :return:
+        :rtype:
+        """
+        if len(names) != len(dates) - 1:
+            raise Exception('Error: number of Span names must equal number of Spans created'
+                            ' (i.e. one less than number of dates)')
+
+        date_pairs = list(zip(dates, dates[1:]))
+        date_pairs = [(start, rk.periodicity.offset_date(end, rk.periodicity.Type.DAY, -1)) for (start, end) in date_pairs]
+
+        spans = []
+        for i in range(len(names)):
+            spans.append(cls(name=names[i], start_date=date_pairs[i][0], end_date=date_pairs[i][1]))
+        return spans
+
+    @classmethod
+    def from_num_periods_sequence(
+            cls,
+            names: [str],
+            period_type: rk.periodicity.Type,
+            durations: [int],
+            start_date: pd.Timestamp) -> [Span]:
+        """
+        Create a set of Spans from a sequence of durations of specified period type
+        :param names:
+        :type names:
+        :param period_type:
+        :type period_type:
+        :param durations:
+        :type durations:
+        :param start_date:
+        :type start_date:
+        :return:
+        :rtype:
+        """
+        if len(names) != len(durations):
+            raise Exception('Error: number of Span names must equal number of Spans')
+
+        dates = []
+        cumulative_durations = np.cumsum(durations)
+        for duration in cumulative_durations:
+            dates.append(rk.periodicity.offset_date(date=start_date, period_type=period_type, num_periods=duration))
+
+        return cls.from_date_sequence(names=names, dates=dates)