honeybee_energy.result.colorobj module

Module for coloring Model geometry with energy simulation results.

class honeybee_energy.result.colorobj.ColorFace(data_collections, faces, legend_parameters=None, simulation_step=None, normalize=True, geo_unit='m')[source]

Bases: _ColorObject

Object for visualization face and sub-face-level simulation results on geometry.

Parameters:

  • 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

ToString()

Overwrite .NET ToString.

time_interval_text(simulation_step)

Get text for a specific time simulation_step of the data collections.

Parameters:

simulation_step – An integer for the step of simulation for which text should be generated.

UNITS = ('m', 'mm', 'ft', 'in', 'cm')
property analysis_period

The analysis_period of this object’s data collections.

property data_collections

Get a tuple of data collections assigned to this object.

property data_type

The data type of this object’s data collections.

property data_type_text

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.

property faces

Get the honeybee Faces, Apertures, Doors and Shades assigned to this object.

property geo_unit

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’.

property graphic_container

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.

property legend_parameters

Get or set the legend parameters.

property matched_data

Get a tuple of data collections that have been matched to the flat_faces.

property matched_flat_areas

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.

property matched_flat_faces

Get a tuple of honeybee objects that have been matched to the data.

property matched_flat_geometry

Get non-nested array of faces/sub-faces on this object.

The geometries here align with the attributes and graphic_container colors.

property matched_values

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.

property max_point

Get a Point3D for the maximum of the box around the rooms.

property min_point

Get a Point3D for the minimum of the box around the rooms.

property normalize

Get or set a boolean for whether results are normalized by face/sub-face area.

property simulation_step

Get or set an integer to select a specific step of the data collections.

property title_text

Text string for the title of the color zones.

property unit

The unit of this object’s data collections.

class honeybee_energy.result.colorobj.ColorRoom(data_collections, rooms, legend_parameters=None, simulation_step=None, normalize_by_floor=True, geo_unit='m', space_based=False)[source]

Bases: _ColorObject

Object for visualization zone-level simulation results on Honeybee Room geometry.

Parameters:

  • 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

ToString()

Overwrite .NET ToString.

time_interval_text(simulation_step)

Get text for a specific time simulation_step of the data collections.

Parameters:

simulation_step – An integer for the step of simulation for which text should be generated.

UNITS = ('m', 'mm', 'ft', 'in', 'cm')
property analysis_period

The analysis_period of this object’s data collections.

property data_collections

Get a tuple of data collections assigned to this object.

property data_type

The data type of this object’s data collections.

property data_type_text

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.

property geo_unit

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’.

property graphic_container

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.

property legend_parameters

Get or set the legend parameters.

property matched_data

Get a tuple of data collections that have been matched to the rooms.

property matched_floor_areas

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.

property matched_floor_faces

Get a nested array with each sub-array having all floor Face3Ds of each room.

property matched_rooms

Get a tuple of honeybee Rooms that have been matched to the data.

property matched_values

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.

property max_point

Get a Point3D for the maximum of the box around the rooms.

property min_point

Get a Point3D for the minimum of the box around the rooms.

property normalize_by_floor

Get or set a boolean for whether results should be normalized by floor area.

property rooms

Get a tuple of honeybee Rooms assigned to this object.

property simulation_step

Get or set an integer to select a specific step of the data collections.

property space_based

Get a boolean for whether results are set to be space-based.

property title_text

Text string for the title of the color zones.

property unit

The unit of this object’s data collections.