honeybee_radiance_postprocess.results.annual_irradiance module

class honeybee_radiance_postprocess.results.annual_irradiance.AnnualIrradiance(folder, schedule: list = None, load_arrays: bool = False)

Bases: Results

Annual Daylight Results class.

Parameters:

• folder – Path to results folder.

• schedule – 8760 values as a list. Values must be either 0 or 1. Values of 1 indicates occupied hours. If no schedule is provided a default schedule will be used. (Default: None).

• load_arrays – Set to True to load all NumPy arrays. If False the arrays will be loaded only once they are needed. In both cases the loaded array(s) will be stored in a dictionary under the arrays property. (Default: False).

Properties:

• schedule

• occ_pattern

• total_occ

• sun_down_occ_hours

• occ_mask

• arrays

• valid_states

• datatype

annual_data(states: DynamicSchedule = None, grids_filter: str = '*', sensor_index: dict = None, res_type: str = 'total') → Tuple[List[List[HourlyContinuousCollection]], List[dict], dict]

Get annual data for one or multiple sensors.

Parameters:

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• sensor_index – A dictionary with grids as keys and a list of sensor indices as values. Defaults to None.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with Data Collections for each sensor, grid information,

and a dictionary of the sensors.

Return type:

Tuple

annual_data_to_folder(target_folder: str, states: DynamicSchedule = None, grids_filter: str = '*', sensor_index: dict = None, res_type: str = 'total')

Get annual data for one or multiple sensors and write the data to a folder as Data Collections.

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• sensor_index – A dictionary with grids as keys and a list of sensor indices as values. Defaults to None.

• res_type – Type of results to load. Defaults to ‘total’.

annual_metrics(hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*') → Tuple[List[ndarray], List[ndarray], List[ndarray], List[dict]]

Calculate multiple annual irradiance metrics.

This method will calculate the following metrics:

• Average Irradiance (W/m2)

• Peak Irradiance (W/m2)

• Cumulative Radiation (kWh/m2)

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

Returns:

A tuple with the three annual irradiance metrics and grid information.

Return type:

Tuple

annual_metrics_to_folder(target_folder: str, hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*')

Calculate and write multiple annual irradiance metrics to a folder.

This command generates 3 files for each input grid.

• average_irradiance/{grid-name}.res – Average Irradiance (W/m2)

• peak_irradiance/{grid-name}.res – Peak Irradiance (W/m2)

• cumulative_radiation/{grid-name}.res – Cumulative Radiation (kWh/m2)

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

average_values(hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get average values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with the average value for each sensor and grid information.

Return type:

Tuple

average_values_to_folder(target_folder: str, hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total')

Get average values for each sensor over a given period and write the values to a folder.

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

cumulative_values(hoys: list = [], states: DynamicSchedule = None, t_step_multiplier: float = 1000, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get cumulative values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• t_step_multiplier – A value that will be multiplied with the timestep.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with the cumulative value for each sensor and grid

information.

Return type:

Tuple

cumulative_values_to_folder(target_folder: str, hoys: list = [], states: DynamicSchedule = None, t_step_multiplier: float = 1000, grids_filter: str = '*', res_type: str = 'total')

Get cumulative values for each sensor over a given period and write the values to a folder.

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• t_step_multiplier – A value that will be multiplied with the timestep.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

median_values(hoys: list = [], states: dict = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get median values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period. If hoys is left empty the median values will likely be 0 since there are likely more sun down hours than sun up hours.

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with the median value for each sensor and grid information.

Return type:

Tuple

median_values_to_folder(target_folder: str, hoys: list = [], states: dict = None, grids_filter: str = '*', res_type: str = 'total')

Get median values for each sensor over a given period and write the values to a folder.

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

peak_values(hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*', coincident: bool = False, res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get peak values for each sensor over a given period.

The hoys input can be used to filter the data for a particular time period.

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• coincident – Boolean to indicate whether output values represent the peak value for each sensor throughout the entire analysis (False) or they represent the highest overall value across each sensor grid at a particular timestep (True). Defaults to False.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with the peak value for each sensor and grid information.

Return type:

Tuple

peak_values_to_folder(target_folder: str, hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*', coincident: bool = False, res_type='total')

Get peak values for each sensor over a given period and write the values to a folder.

Parameters:

• target_folder – Folder path to write peak values in. Usually this folder is called ‘metrics’.

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids.

• coincident – Boolean to indicate whether output values represent the peak value for each sensor throughout the entire analysis (False) or they represent the highest overall value across each sensor grid at a particular timestep (True). Defaults to False.

• res_type – Type of results to load. Defaults to ‘total’.

point_in_time(datetime: float | DateTime, states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get point in time values.

Parameters:

• datetime – Hour of the year as a float or DateTime object.

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with point in time values and grid information.

Return type:

Tuple

point_in_time_to_folder(target_folder: str, datetime: float | DateTime, states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get point in time values and write the values to a folder.

Parameters:

• target_folder – Folder path to write annual metrics in. Usually this folder is called ‘metrics’.

• datetime – Hour of the year as a float or DateTime object.

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with point in time values and grid information.

Return type:

Tuple

total(hoys: list = [], states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total') → Tuple[List[ndarray], List[dict]]

Get summed values for each sensor.

Parameters:

• hoys – An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. Defaults to [].

• states – A dictionary of states. Defaults to None.

• grids_filter – The name of a grid or a pattern to filter the grids. Defaults to ‘*’.

• res_type – Type of results to load. Defaults to ‘total’.

Returns:

A tuple with total values and grid information.

Return type:

Tuple

static values_to_annual(hours: ~typing.List[float] | ~numpy.ndarray, values: ~typing.List[float] | ~numpy.ndarray, timestep: int, base_value: int = 0, dtype: ~numpy.dtype = <class 'numpy.float32'>) → ndarray

Map a 1D NumPy array based on a set of hours to an annual array.

This method creates an array with a base value of length 8760 and replaces the base value with the input ‘values’ at the indices of the input ‘hours’.

Parameters:

• hours – A list of hours. This can be a regular list or a 1D NumPy array.

• values – A list of values to map to an annual array. This can be a regular list or a 1D NumPy array.

• timestep – Time step of the simulation.

• base_value – A value that will be applied for all the base array.

• dtype – A NumPy dtype for the annual array.

Returns:

A 1D NumPy array.

property arrays

Return a dictionary of all the NumPy arrays that have been loaded.

property datatype

Return a Ladybug DataType object.

property datetimes

Return DateTimes for sun up hours.

property default_states

Return default states as a dictionary.

property folder

Return full path to results folder as a string.

property grid_states

Return grid states as a dictionary.

property grids_info

Return grids information as list of dictionaries for each grid.

property light_paths

Return the identifiers of the light paths.

property occ_mask

Return an occupancy mask as a NumPy array that can be used to mask the results.

property occ_pattern

Return a filtered version of the annual schedule that only includes the sun-up-hours.

property schedule

Return schedule.

property study_hours

Return study hours as a list.

property sun_down_hours

Return sun down hours.

property sun_down_hours_mask

Return sun down hours masking array.

property sun_down_occ_hours

Return an integer for the number of occupied hours where the sun is down and there’s no possibility of being daylit or experiencing glare.

property sun_up_hours

Return sun up hours.

property sun_up_hours_mask

Return sun up hours masking array.

property timestep

Return timestep as an integer.

property total_occ

Return an integer for the total occupied hours of the schedule.

property unit

Return unit of hourly values.

property valid_states

Return a dictionary with valid states. Each light path is represented by a key-value pair where the light path identifier is the key and the value is a list of valid states, e.g., [0, 1, 2, …].