honeybee_radiance_postprocess.results.annual_irradiance module

class honeybee_radiance_postprocess.results.annual_irradiance.AnnualIrradiance(folder, schedule: list = None, load_arrays: bool = False, cache_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 ‘*’.

annual_statistics(hoys: list = None, states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total', axis: int = 1)

Compute annual statistics (average, median, minimum, maximum, cumulative) for each sensor or timestep.

If hoys is left as None, the average will be computed for all study hours, i.e., including sun down hours. This will likely lead to low average and median values for a usual annual study.

Parameters:

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

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

• axis –

  Axis along which statistics are computed: - 1: compute per-sensor statistics over time (default) - 0: compute per-timestep statistics across sensors; results are

  converted into HourlyContinuousCollection objects.

Returns:

(

average_values, median_values, minimum_values, maximum_values, cumulative_values, grids_info

)

Where each element except grids_info is a list with one entry per sensor grid:

• If axis == 1: each entry is a 1D NumPy array of per-sensor values.

• If axis == 0: each entry is an HourlyContinuousCollection.

grids_info contains metadata for each processed grid.

Return type:

A tuple of the form

annual_statistics_to_folder(target_folder: str, hoys: list = None, states: DynamicSchedule = None, grids_filter: str = '*', res_type: str = 'total', axis: int = 1)

Compute summary statistics (average, median, minimum, maximum, cumulative) for each sensor or timestep and write the values to a folder.

If hoys is left as None, the average will be computed for all study hours, i.e., including sun down hours. This will likely lead to low average and median values for a usual annual study.

Parameters:

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

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

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

• axis –

  Axis along which statistics are computed: - 1: compute per-sensor statistics over time (default) - 0: compute per-timestep statistics across sensors; results are

  converted into HourlyContinuousCollection objects.

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

clear_cached_arrays(res_type: str = None)

Clear the cached arrays.

This method will simply clear the arrays property to remove arrays from memory, unless the res_type is selected in which case only ‘total’ or ‘direct’ arrays will be deleted.

Parameters:

res_type – Which type of results to clear. This can be either ‘total’ or ‘direct’.

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

static pad_array_for_median(array: ndarray, hoys: list, sun_down_hours: list, sensor_count: int) → ndarray

Pad a filtered 2D result array with zeros so that median values correctly account for sun-down hours.

• If no HOYs are given, pad with all sun-down hours.

• If HOYs are given, pad only with those HOYs that fall in sun-down hours.

Parameters:

• array – 2D NumPy array of shape (sensor_count, N_filtered_hours).

• hoys – List of selected hours-of-year (empty means all sun-up hours).

• sun_down_hours – List of HOYs when the sun is down.

• sensor_count – Number of sensors in the grid (array rows).

Returns:

A new 2D NumPy array padded with zero columns for sun-down hours.

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 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 cache_arrays

Return a boolean to indicate whether arrays are cached.

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, …].