honeybee-energy 1.116.106__py3-none-any.whl

honeybee_energy/result/colorobj.py

@@ -0,0 +1,648 @@
+# coding=utf-8
+"""Module for coloring Model geometry with energy simulation results."""
+from __future__ import division
+
+from .match import match_rooms_to_data, match_faces_to_data
+
+from honeybee.face import Face
+from honeybee.room import Room
+from honeybee.facetype import Floor
+from honeybee.typing import int_in_range
+
+from ladybug.dt import Date, DateTime
+from ladybug.analysisperiod import AnalysisPeriod
+from ladybug.datacollection import MonthlyCollection, DailyCollection, \
+    MonthlyPerHourCollection, HourlyContinuousCollection, HourlyDiscontinuousCollection
+from ladybug.graphic import GraphicContainer
+from ladybug.legend import LegendParameters
+
+from ladybug_geometry.geometry3d.pointvector import Point3D
+
+
+class _ColorObject(object):
+    """Base class for coloring geometry with simulation results.
+
+    Properties:
+        * data_collections
+        * legend_parameters
+        * simulation_step
+        * geo_unit
+        * title_text
+        * data_type_text
+        * data_type
+        * unit
+        * analysis_period
+        * min_point
+        * max_point
+    """
+    __slots__ = ('_data_collections', '_legend_parameters', '_simulation_step',
+                 '_normalize', '_geo_unit', '_matched_objects', '_base_collection',
+                 '_base_type', '_base_unit', '_min_point', '_max_point')
+
+    UNITS = ('m', 'mm', 'ft', 'in', 'cm')
+
+    def __init__(self, data_collections, legend_parameters=None,
+                 simulation_step=None, geo_unit='m'):
+        """Initialize ColorObject."""
+        # check the input collections
+        acceptable_colls = (MonthlyCollection, DailyCollection, MonthlyPerHourCollection,
+                            HourlyContinuousCollection, HourlyDiscontinuousCollection)
+        try:
+            data_collections = list(data_collections)
+        except TypeError:
+            raise TypeError('Input data_collections must be an array. Got {}.'.format(
+                type(data_collections)))
+        assert len(data_collections) > 0, \
+            'ColorObject must have at least one data_collection.'
+        for i, coll in enumerate(data_collections):
+            assert isinstance(coll, acceptable_colls), 'Expected data collection for ' \
+                'ColorObject data_collections. Got {}.'.format(type(coll))
+            if not coll.validated_a_period:
+                data_collections[i] = coll.validate_analysis_period()
+        self._base_collection = data_collections[0]
+        self._base_type = self._base_collection.header.data_type
+        self._base_unit = self._base_collection.header.unit
+        for coll in data_collections[1:]:
+            assert coll.header.unit == self._base_unit, \
+                'ColorObject data_collections must all have matching units. ' \
+                '{} != {}.'.format(coll.header.unit, self._base_unit)
+            assert len(coll.values) == len(self._base_collection.values), \
+                'ColorObject data_collections must all be aligned with one another.' \
+                '{} != {}'.format(len(coll.values), len(self._base_collection.values))
+        self._data_collections = data_collections
+
+        # assign the other properties of this object
+        self.legend_parameters = legend_parameters
+        self.simulation_step = simulation_step
+        self.geo_unit = geo_unit
+        self._normalize = False
+
+    @property
+    def data_collections(self):
+        """Get a tuple of data collections assigned to this object."""
+        return tuple(self._data_collections)
+
+    @property
+    def legend_parameters(self):
+        """Get or set the legend parameters."""
+        return self._legend_parameters
+
+    @legend_parameters.setter
+    def legend_parameters(self, value):
+        if value is not None:
+            assert isinstance(value, LegendParameters), \
+                'Expected LegendParameters. Got {}.'.format(type(value))
+            self._legend_parameters = value.duplicate()
+        else:
+            self._legend_parameters = LegendParameters()
+
+    @property
+    def simulation_step(self):
+        """Get or set an integer to select a specific step of the data collections."""
+        return self._simulation_step
+
+    @simulation_step.setter
+    def simulation_step(self, value):
+        if value is not None:
+            value = int_in_range(
+                value, 0, len(self._base_collection) - 1, 'simulation_step')
+        self._simulation_step = value
+
+    @property
+    def geo_unit(self):
+        """Text to note the units that the object geometry is in.
+
+        This will be used to ensure the legend units display correctly when
+        data is floor-normalized. Examples include 'm', 'mm', 'ft'.
+        """
+        return self._geo_unit
+
+    @geo_unit.setter
+    def geo_unit(self, value):
+        self._geo_unit = str(value)
+        assert self._geo_unit in self.UNITS, \
+            'Unit "{}" is not supported in color object.'.format(self._geo_unit)
+
+    @property
+    def title_text(self):
+        """Text string for the title of the color zones."""
+        d_type_text = self.data_type_text
+        if self._simulation_step is not None:  # specific index from all collections
+            time_text = self.time_interval_text(self.simulation_step)
+            if self._base_type.normalized_type is not None and self._normalize:
+                d_type_text = '{} {}'.format(d_type_text, 'Intensity')
+        else:  # average or total the data
+            time_text = str(self.analysis_period).split('@')[0]
+            if self._base_type.normalized_type is None or not self._normalize:
+                if not self._base_type.cumulative:
+                    d_type_text = '{} {}'.format('Average', d_type_text)
+                else:
+                    d_type_text = '{} {}'.format('Total', d_type_text)
+            else:
+                if not self._base_type.cumulative:
+                    d_type_text = '{} {} {}'.format('Average', d_type_text, 'Intensity')
+                else:
+                    d_type_text = '{} {} {}'.format('Total', d_type_text, 'Intensity')
+        return '{}\n{}'.format('{} ({})'.format(d_type_text, self.unit), time_text)
+
+    @property
+    def data_type_text(self):
+        """Text for the data type.
+
+        This will be the full name of the EnergyPlus output if the DataCollection
+        header metadata contains a 'type' key. Otherwise, this will be the name
+        of the data_type object.
+        """
+        m_data = self._base_collection.header.metadata
+        return m_data['type'] if 'type' in m_data else str(self.data_type)
+
+    @property
+    def data_type(self):
+        """The data type of this object's data collections."""
+        if self._base_type.normalized_type is None or not self._normalize:
+            return self._base_type
+        else:
+            return self._base_type.normalized_type()
+
+    @property
+    def unit(self):
+        """The unit of this object's data collections."""
+        if self._base_type.normalized_type is not None and self._normalize:
+            _geo_unit = 'ft' if self._geo_unit in ('ft', 'in') else 'm'
+            return '{}/{}2'.format(self._base_unit, _geo_unit) if '/' not in \
+                self._base_unit else '{}-{}2'.format(self._base_unit, _geo_unit)
+        else:
+            return self._base_unit
+
+    @property
+    def analysis_period(self):
+        """The analysis_period of this object's data collections."""
+        return self._base_collection.header.analysis_period
+
+    @property
+    def min_point(self):
+        """Get a Point3D for the minimum of the box around the rooms."""
+        return self._min_point
+
+    @property
+    def max_point(self):
+        """Get a Point3D for the maximum of the box around the rooms."""
+        return self._max_point
+
+    def time_interval_text(self, simulation_step):
+        """Get text for a specific time simulation_step of the data collections.
+
+        Args:
+            simulation_step: An integer for the step of simulation for which
+                text should be generated.
+        """
+        hourly_colls = (HourlyContinuousCollection, HourlyDiscontinuousCollection)
+        if isinstance(self._base_collection, hourly_colls):
+            return str(self._base_collection.datetimes[simulation_step])
+        elif isinstance(self._base_collection, MonthlyCollection):
+            month_names = AnalysisPeriod.MONTHNAMES
+            return month_names[self._base_collection.datetimes[simulation_step]]
+        elif isinstance(self._base_collection, DailyCollection):
+            return str(Date.from_doy(self._base_collection.datetimes[simulation_step]))
+        elif isinstance(self._base_collection, MonthlyPerHourCollection):
+            dt_tuple = self._base_collection.datetimes[simulation_step]
+            date_time = DateTime(month=dt_tuple[0], hour=dt_tuple[1])
+            return date_time.strftime('%b %H:%M')
+
+    def _calculate_min_max(self, hb_objs):
+        """Calculate maximum and minimum Point3D for a set of rooms."""
+        st_rm_min, st_rm_max = hb_objs[0].geometry.min, hb_objs[0].geometry.max
+        min_pt = [st_rm_min.x, st_rm_min.y, st_rm_min.z]
+        max_pt = [st_rm_max.x, st_rm_max.y, st_rm_max.z]
+
+        for room in hb_objs[1:]:
+            rm_min, rm_max = room.geometry.min, room.geometry.max
+            if rm_min.x < min_pt[0]:
+                min_pt[0] = rm_min.x
+            if rm_min.y < min_pt[1]:
+                min_pt[1] = rm_min.y
+            if rm_min.z < min_pt[2]:
+                min_pt[2] = rm_min.z
+            if rm_max.x > max_pt[0]:
+                max_pt[0] = rm_max.x
+            if rm_max.y > max_pt[1]:
+                max_pt[1] = rm_max.y
+            if rm_max.z > max_pt[2]:
+                max_pt[2] = rm_max.z
+
+        self._min_point = Point3D(min_pt[0], min_pt[1], min_pt[2])
+        self._max_point = Point3D(max_pt[0], max_pt[1], max_pt[2])
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Color Object:'
+
+
+class ColorRoom(_ColorObject):
+    """Object for visualization zone-level simulation results on Honeybee Room geometry.
+
+    Args:
+        data_collections: An array of data collections of the same data type,
+            which will be used to color Rooms with simulation results. Data collections
+            can be of any class (eg. MonthlyCollection, DailyCollection) but they
+            should all have headers with metadata dictionaries with 'Zone' or
+            'System' keys. These keys will be used to match the data in the collections
+            to the input rooms.
+        rooms: An array of honeybee Rooms, which will be matched to the data_collections.
+            The length of these Rooms does not have to match the data_collections
+            and this object will only create visualizations for rooms that are
+            found to be matching.
+        legend_parameters: An optional LegendParameter object to change the display
+            of the ColorRooms (Default: None).
+        simulation_step: An optional integer (greater than or equal to 0) to select
+            a specific step of the data collections for which result values will be
+            generated. If None, the geometry will be colored with the total of
+            results in the data_collections if the data type is cumulative or with
+            the average of results if the data type is not cumulative. Default: None.
+        normalize_by_floor: Boolean to note whether results should be normalized
+            by the floor area of the Room if the data type of the data_collections
+            supports it. If False, values will be generated using sum total of
+            the data collection values. Note that this input has no effect if
+            the data type of the data_collections is not normalizable since data
+            collection values will always be averaged for this case. Default: True.
+        geo_unit: Optional text to note the units that the Room geometry is in.
+            This will be used to ensure the legend units display correctly when
+            data is floor-normalized. Examples include 'm', 'mm', 'ft'.
+            (Default: 'm' for meters).
+        space_based: Boolean to note whether the result is reported on the EnergyPlus
+            Space level instead of the Zone level. In this case, the matching to
+            the Room will account for the fact that the Space name is the Room
+            name with _Space added to it. (Default: False).
+
+    Properties:
+        * data_collections
+        * rooms
+        * legend_parameters
+        * simulation_step
+        * normalize_by_floor
+        * geo_unit
+        * space_based
+        * matched_rooms
+        * matched_data
+        * matched_values
+        * matched_floor_faces
+        * matched_floor_areas
+        * graphic_container
+        * title_text
+        * data_type_text
+        * data_type
+        * unit
+        * analysis_period
+        * min_point
+        * max_point
+    """
+    __slots__ = ('_rooms', '_space_based')
+
+    def __init__(self, data_collections, rooms, legend_parameters=None,
+                 simulation_step=None, normalize_by_floor=True, geo_unit='m',
+                 space_based=False):
+        """Initialize ColorRoom."""
+        # initialize the base object
+        _ColorObject.__init__(self, data_collections, legend_parameters,
+                              simulation_step, geo_unit)
+        for coll in self._data_collections:
+            assert 'Zone' in coll.header.metadata or 'System' in coll.header.metadata, \
+                'ColorRoom data collection does not have metadata associated with Zones.'
+
+        try:  # check the input rooms
+            rooms = tuple(rooms)
+        except TypeError:
+            raise TypeError('Input rooms must be an array. Got {}.'.format(type(rooms)))
+        assert len(rooms) > 0, 'ColorRooms must have at least one room.'
+        for room in rooms:
+            assert isinstance(room, Room), 'Expected honeybee Room for ' \
+                'ColorRoom rooms. Got {}.'.format(type(room))
+        self._rooms = rooms
+        self._calculate_min_max(self._rooms)
+
+        # match the rooms with the data collections
+        self._space_based = bool(space_based)
+        self._matched_objects = match_rooms_to_data(
+            data_collections, rooms, space_based=self._space_based,
+            zone_correct_mult=False)
+        if len(self._matched_objects) == 0:
+            raise ValueError('None of the ColorRoom data collections could be '
+                             'matched to the input rooms')
+
+        # assign the normalize property
+        self.normalize_by_floor = normalize_by_floor
+
+    @property
+    def rooms(self):
+        """Get a tuple of honeybee Rooms assigned to this object."""
+        return self._rooms
+
+    @property
+    def normalize_by_floor(self):
+        """Get or set a boolean for whether results should be normalized by floor area.
+        """
+        return self._normalize
+
+    @normalize_by_floor.setter
+    def normalize_by_floor(self, value):
+        self._normalize = bool(value)
+
+    @property
+    def space_based(self):
+        """Get a boolean for whether results are set to be space-based."""
+        return self._space_based
+
+    @property
+    def matched_rooms(self):
+        """Get a tuple of honeybee Rooms that have been matched to the data."""
+        return tuple(obj[0] for obj in self._matched_objects)
+
+    @property
+    def matched_data(self):
+        """Get a tuple of data collections that have been matched to the rooms."""
+        return tuple(obj[1] for obj in self._matched_objects)
+
+    @property
+    def matched_values(self):
+        """Get an array of numbers that correspond to the matched_rooms.
+
+        These values are derived from the data_collections but they will be
+        averaged/totaled and normalized by Room floor area depending on the
+        other inputs to this object.
+        """
+        if self._simulation_step is not None:  # specific index from all collections
+            if self._base_type.normalized_type is None or not self._normalize:
+                return tuple(obj[1][self._simulation_step] for obj in
+                             self._matched_objects)
+            else:  # normalize the data by the floor area
+                vals = []
+                for obj, f_area in zip(self._matched_objects, self.matched_floor_areas):
+                    try:
+                        vals.append(obj[1][self._simulation_step] / (f_area * obj[2]))
+                    except ZeroDivisionError:  # no floor faces in the Room
+                        vals.append(0)
+                return vals
+        else:  # average or total the data based on data type
+            if self._base_type.normalized_type is None or not self._normalize:
+                if self._base_type.cumulative:
+                    return tuple(obj[1].total for obj in self._matched_objects)
+                else:
+                    return tuple(obj[1].average for obj in self._matched_objects)
+            else:  # normalize the data by floor area
+                vals = []
+                zip_obj = zip(self._matched_objects, self.matched_floor_areas)
+                if self._base_type.cumulative:  # divide total values by floor area
+                    for obj, f_area in zip_obj:
+                        try:
+                            vals.append(obj[1].total / (f_area * obj[2]))
+                        except ZeroDivisionError:  # no floor faces in the Room
+                            vals.append(0)
+                else:  # divide average values by floor area
+                    for obj, f_area in zip_obj:
+                        try:
+                            vals.append(obj[1].average / f_area)
+                        except ZeroDivisionError:  # no floor faces in the Room
+                            vals.append(0)
+                return vals
+
+    @property
+    def matched_floor_faces(self):
+        """Get a nested array with each sub-array having all floor Face3Ds of each room.
+        """
+        flr_faces = []
+        for room in self.matched_rooms:
+            flr_faces.append(
+                [face.geometry for face in room.faces if isinstance(face.type, Floor)])
+        return flr_faces
+
+    @property
+    def matched_floor_areas(self):
+        """Get a list for all of the room floor areas that were matches with data.
+
+        These floor areas will always be in either square meters or square feet
+        depending on whether the geo_unit is either SI or IP.
+        """
+        # correct for more than one room in a zone
+        if not self.space_based:
+            zones = {}
+            for room in self.matched_rooms:
+                try:
+                    zones[room.zone] += room.floor_area
+                except KeyError:  # first room to be found in the zone
+                    zones[room.zone] = room.floor_area
+            floor_areas = [zones[room.zone] for room in self.matched_rooms]
+        else:
+            floor_areas = [room.floor_area for room in self.matched_rooms]
+        # convert units if they are not conventional
+        if self._geo_unit in ('m', 'ft'):  # no need to do unit conversions
+            return floor_areas
+        elif self._geo_unit == 'mm':  # convert to meters
+            return [ar / 1000000.0 for ar in floor_areas]
+        elif self._geo_unit == 'in':  # convert to feet
+            return [ar / 144.0 for ar in floor_areas]
+        else:  # assume it's cm; convert to meters
+            return [ar / 10000.0 for ar in floor_areas]
+
+    @property
+    def graphic_container(self):
+        """Get a ladybug GraphicContainer that relates to this object.
+
+        The GraphicContainer possesses almost all things needed to visualize the
+        ColorRoom object including the legend, value_colors, lower_title_location,
+        upper_title_location, etc.
+        """
+        return GraphicContainer(
+            self.matched_values, self.min_point, self.max_point,
+            self.legend_parameters, self.data_type, str(self.unit))
+
+    def __repr__(self):
+        """Color Room representation."""
+        return 'Color Room: [{} Rooms] [{}]'.format(
+            len(self._matched_objects), self._base_collection.header)
+
+
+class ColorFace(_ColorObject):
+    """Object for visualization face and sub-face-level simulation results on geometry.
+
+    Args:
+        data_collections: An array of data collections of the same data type,
+            which will be used to color Faces with simulation results. Data collections
+            can be of any class (eg. MonthlyCollection, DailyCollection) but they
+            should all have headers with metadata dictionaries with 'Surface'
+            keys. These keys will be used to match the data in the collections
+            to the input faces.
+        faces: An array of honeybee Faces, Apertures, and/or Doors which will be
+            matched to the data_collections.
+        legend_parameters: An optional LegendParameter object to change the display
+            of the ColorFace (Default: None).
+        simulation_step: An optional integer (greater than or equal to 0) to select
+            a specific step of the data collections for which result values will be
+            generated. If None, the geometry will be colored with the total of
+            results in the data_collections if the data type is cumulative or with
+            the average of results if the data type is not cumulative. Default: None.
+        normalize: Boolean to note whether results should be normalized by the
+            face/sub-face area if the data type of the data_collections supports it.
+            If False, values will be generated using sum total of the data collection
+            values. Note that this input has no effect if the data type of the
+            data_collections is not normalizable since data collection values will
+            always be averaged for this case. Default: True.
+        geo_unit: Optional text to note the units that the Face geometry is in.
+            This will be used to ensure the legend units display correctly when
+            data is floor-normalized. Examples include 'm', 'mm', 'ft'.
+            (Default: 'm' for meters).
+
+    Properties:
+        * data_collections
+        * faces
+        * legend_parameters
+        * simulation_step
+        * normalize
+        * geo_unit
+        * matched_flat_faces
+        * matched_data
+        * matched_values
+        * matched_flat_geometry
+        * matched_flat_areas
+        * graphic_container
+        * title_text
+        * data_type_text
+        * data_type
+        * unit
+        * analysis_period
+        * min_point
+        * max_point
+    """
+    __slots__ = ('_faces',)
+
+    def __init__(self, data_collections, faces, legend_parameters=None,
+                 simulation_step=None, normalize=True, geo_unit='m'):
+        """Initialize ColorFace."""
+        # initialize the base object
+        _ColorObject.__init__(self, data_collections, legend_parameters,
+                              simulation_step, geo_unit)
+        for coll in self._data_collections:
+            assert 'Surface' in coll.header.metadata, 'ColorFace data collection ' \
+                'does not have metadata associated with Surfaces.'
+
+        try:  # check the input faces
+            faces = tuple(faces)
+        except TypeError:
+            raise TypeError('Input faces must be an array. Got {}.'.format(type(faces)))
+        assert len(faces) > 0, 'ColorFaces must have at least one face.'
+        self._faces = faces
+        self._calculate_min_max(faces)
+
+        # match the faces with the data collections
+        self._matched_objects = match_faces_to_data(data_collections, faces)
+        if len(self._matched_objects) == 0:
+            raise ValueError('None of the ColorFace data collections could be '
+                             'matched to the input faces')
+
+        # assign the normalize property
+        self.normalize = normalize
+
+    @property
+    def faces(self):
+        """Get the honeybee Faces, Apertures, Doors and Shades assigned to this object.
+        """
+        return self._faces
+
+    @property
+    def normalize(self):
+        """Get or set a boolean for whether results are normalized by face/sub-face area.
+        """
+        return self._normalize
+
+    @normalize.setter
+    def normalize(self, value):
+        self._normalize = bool(value)
+
+    @property
+    def matched_flat_faces(self):
+        """Get a tuple of honeybee objects that have been matched to the data."""
+        return tuple(obj[0] for obj in self._matched_objects)
+
+    @property
+    def matched_data(self):
+        """Get a tuple of data collections that have been matched to the flat_faces."""
+        return tuple(obj[1] for obj in self._matched_objects)
+
+    @property
+    def matched_values(self):
+        """Get an array of numbers that correspond to the matched_flat_faces.
+
+        These values are derived from the data_collections but they will be
+        averaged/totaled and normalized by the face/sub-face area depending on the
+        other inputs to this object.
+        """
+        if self._simulation_step is not None:  # specific index from all collections
+            if self._base_type.normalized_type is None or not self._normalize:
+                return tuple(obj[1][self._simulation_step] for obj in
+                             self._matched_objects)
+            else:  # normalize the data by the face area
+                vals = []
+                for obj, f_area in zip(self._matched_objects, self.matched_flat_areas):
+                    vals.append(obj[1][self._simulation_step] / f_area)
+                return vals
+        else:  # average or total the data based on data type
+            if self._base_type.normalized_type is None or not self._normalize:
+                if self._base_type.cumulative:
+                    return tuple(obj[1].total for obj in self._matched_objects)
+                else:
+                    return tuple(obj[1].average for obj in self._matched_objects)
+            else:  # normalize the data by face area
+                vals = []
+                zip_obj = zip(self._matched_objects, self.matched_flat_areas)
+                if self._base_type.cumulative:  # divide total values by face area
+                    for obj, f_area in zip_obj:
+                        vals.append(obj[1].total / f_area)
+                else:  # divide average values by face area
+                    for obj, f_area in zip_obj:
+                        vals.append(obj[1].average / f_area)
+                return vals
+
+    @property
+    def matched_flat_geometry(self):
+        """Get non-nested array of faces/sub-faces on this object.
+
+        The geometries here align with the attributes and graphic_container colors.
+        """
+        return tuple(face.geometry if not isinstance(face, Face)
+                     else face.punched_geometry for face in self.matched_flat_faces)
+
+    @property
+    def matched_flat_areas(self):
+        """Get a list numbers for the area of each of the matched_flat_faces.
+
+        These areas will always be in either square meters or square feet
+        depending on whether the geo_unit is either SI or IP. They also use
+        punched geometry in the case of a Face with child Apertures.
+        """
+        if self._geo_unit in ('m', 'ft'):  # no need to do unit conversions
+            return [face.area for face in self.matched_flat_geometry]
+        elif self._geo_unit == 'mm':  # convert to meters
+            return [face.area / 1000000.0 for face in self.matched_flat_geometry]
+        elif self._geo_unit == 'in':  # convert to feet
+            return [face.area / 144.0 for face in self.matched_flat_geometry]
+        else:  # assume it's cm; convert to meters
+            return [face.area / 10000.0 for face in self.matched_flat_geometry]
+
+    @property
+    def graphic_container(self):
+        """Get a ladybug GraphicContainer that relates to this object.
+
+        The GraphicContainer possesses almost all things needed to visualize the
+        ColorFace object including the legend, value_colors, lower_title_location,
+        upper_title_location, etc.
+        """
+        return GraphicContainer(
+            self.matched_values, self.min_point, self.max_point,
+            self.legend_parameters, self.data_type, str(self.unit))
+
+    def __repr__(self):
+        """Color Face representation."""
+        return 'Color Face: [{} Objects] [{}]'.format(
+            len(self._matched_objects), self._base_collection.header)