ladybug_comfort.collection.utci module

Object for calculating UTCI comfort from DataCollections.

class ladybug_comfort.collection.utci.UTCI(air_temperature, rel_humidity, rad_temperature=None, wind_speed=None, comfort_parameter=None)[source]

Bases: ComfortCollection

UTCI comfort DataCollection object.

Parameters
  • air_temperature – Data Collection of air temperature values in Celsius.

  • rel_humidity – Data Collection of relative humidity values in % or a single relative humidity value to be used for the whole analysis.

  • rad_temperature – Data Collection of mean radiant temperature (MRT) values in degrees Celsius or a single MRT value to be used for the whole analysis. If None, this will be the same as the air_temperature.

  • wind_speed – Data Collection of meteorological wind speed values in m/s (measured 10 m above the ground) or a single wind speed value to be used for the whole analysis. If None, this will default to a low wind speed of 0.5 m/s, which is the lowest input speed that is recommended for the UTCI model.

  • comfort_parameter – Optional UTCIParameter object to specify parameters under which conditions are considered acceptable. If None, default will assume comfort thresholds consistent with those used by meteorologists to categorize outdoor conditions.

Properties:
  • air_temperature

  • rad_temperature

  • air_speed

  • rel_humidity

  • comfort_parameter

  • universal_thermal_climate_index

  • is_comfortable

  • thermal_condition

  • thermal_condition_five_point

  • thermal_condition_seven_point

  • thermal_condition_nine_point

  • thermal_condition_eleven_point

  • original_utci_category

  • percent_comfortable

  • percent_uncomfortable

  • percent_neutral

  • percent_hot

  • percent_cold

  • percent_extreme_cold_stress

  • percent_very_strong_cold_stress

  • percent_strong_cold_stress

  • percent_moderate_cold_stress

  • percent_slight_cold_stress

  • percent_slight_heat_stress

  • percent_moderate_heat_stress

  • percent_strong_heat_stress

  • percent_very_strong_heat_stress

  • percent_extreme_heat_stress

ToString()

Overwrite .NET ToString.

classmethod from_epw(epw, include_wind=True, include_sun=True, utci_parameter=None)[source]

Get a UTCI comfort object from the conditions within an EPW file.

Parameters
  • epw – A ladybug EPW object from which the UTCI object will be created.

  • include_wind – Set to True to include the EPW wind speed in the calculation. Setting to False will assume a condition that is shielded from wind where the human subject experiences a low wind speed of 0.5 m/s, which is the lowest input speed that is recommended for the UTCI model. Default: True to include wind.

  • include_sun – Set to True to include the mean radiant temperature (MRT) delta from both shortwave solar falling directly on people and long wave radiant exchange with the sky. Setting to False will assume a shaded condition with MRT being equal to the EPW dry bulb temperature. When set to True, this calculation will assume no surrounding shade context, standing human geometry, and a solar horizontal angle relative to front of person (SHARP) of 135 degrees. A SHARP of 135 essentially assumes that a person typically faces their side or back to the sun to avoid glare. Default: True to include sun.

  • utci_parameter – Optional UTCIParameter object to specify parameters under which conditions are considered acceptable. If None, default will assume comfort thresholds consistent with those used by meterologists to categorize outdoor conditions.

Returns

A UTCI object with data collections of the results as properties.

Usage:

from ladybug.epw import EPW
from ladybug_comfort.collection.utci import UTCI

epw_file_path = './tests/epw/chicago.epw'
epw = EPW(epw_file_path)
utci_exposed = UTCI.from_epw(epw, include_wind=True, include_sun=True)
utci_protected = UTCI.from_epw(epw, include_wind=False, include_sun=False)

print(utci_exposed.percent_neutral)  # comfortable % with sun + wind
print(utci_protected.percent_neutral)  # comfortable % without sun + wind
property air_temperature

Data Collection of air temperature values in degrees C.

property calc_length

The number of values in the Data Collections of this object.

property comfort_model

Return the name of the model to which the comfort datacollection belongs.

property comfort_parameter

UTCI comfort parameters that are assigned to this object.

property is_comfortable

Data Collection of integers noting whether the input conditions are acceptable according to the assigned comfort_parameter.

Values are one of the following:

  • 0 = uncomfortable

  • 1 = comfortable

property original_utci_category

Data Collection of integers noting the original UTCI assessment scale.

Glossary of Terms for Thermal Physiology (2003). Journal of Thermal Biology 28, 75-106

Values are one of the following:

  • 0 = extreme cold stress

  • 1 = very strong cold stress

  • 2 = strong cold stress

  • 3 = moderate cold stress

  • 4 = slight cold stress

  • 5 = no thermal stress

  • 6 = moderate heat stress

  • 7 = strong heat stress

  • 8 = strong heat stress

  • 9 = extreme heat stress

property percent_cold

The percent of time that the thermal_condition is cold.

property percent_comfortable

The percent of time comfortabe given by the assigned comfort_parameter.

property percent_extreme_cold_stress

The percent of time that conditions have very strong cold stress.

property percent_extreme_heat_stress

The percent of time that conditions have very strong heat stress.

property percent_hot

The percent of time that the thermal_condition is hot.

property percent_moderate_cold_stress

The percent of time that conditions have moderate cold stress.

property percent_moderate_heat_stress

The percent of time that conditions have moderate heat stress.

property percent_neutral

The percent of time that the thermal_condition is neutral.

property percent_slight_cold_stress

The percent of time that conditions have slight cold stress.

property percent_slight_heat_stress

The percent of time that conditions have slight heat stress.

property percent_strong_cold_stress

The percent of time that conditions have strong cold stress.

property percent_strong_heat_stress

The percent of time that conditions have strong heat stress.

property percent_uncomfortable

The percent of time uncomfortable given by the assigned comfort_parameter.

property percent_very_strong_cold_stress

The percent of time that conditions have very strong cold stress.

property percent_very_strong_heat_stress

The percent of time that conditions have very strong heat stress.

property rad_temperature

Data Collection of mean radiant temperature (MRT) values in degrees C.

property rel_humidity

Data Collection of relative humidity values in %.

property thermal_condition

Data Collection of integers noting the thermal status of a subject according to the assigned comfort_parameter.

Values are one of the following:

  • -1 = cold

  • 0 = netural

  • +1 = hot

property thermal_condition_eleven_point

Data Collection of integers noting the thermal status on an eleven-point scale.

Values are one of the following:

  • -5 = extreme cold stress

  • -4 = very strong cold stress

  • -3 = strong cold stress

  • -2 = moderate cold stress

  • -1 = slight cold stress

  • 0 = no thermal stress

  • +1 = slight heat stress

  • +2 = moderate heat stress

  • +3 = strong heat stress

  • +4 = very strong heat stress

  • +5 = extreme heat stress

property thermal_condition_five_point

Data Collection of integers noting the thermal status on a five-point scale.

Values are one of the following:

  • -2 = strong/extreme cold stress

  • -1 = moderate cold stress

  • 0 = no thermal stress

  • +1 = moderate heat stress

  • +2 = strong/extreme heat stress

property thermal_condition_nine_point

Data Collection of integers noting the thermal status on a nine-point scale.

Values are one of the following:

  • -4 = very strong/extreme cold stress

  • -3 = strong cold stress

  • -2 = moderate cold stress

  • -1 = slight cold stress

  • 0 = no thermal stress

  • +1 = slight heat stress

  • +2 = moderate heat stress

  • +3 = strong heat stress

  • +4 = very strong/extreme heat stress

property thermal_condition_seven_point

Data Collection of integers noting the thermal status on a seven-point scale.

Values are one of the following:

  • -3 = very strong/extreme cold stress

  • -2 = strong cold stress

  • -1 = moderate cold stress

  • 0 = no thermal stress

  • +1 = moderate heat stress

  • +2 = strong heat stress

  • +3 = very strong/extreme heat stress

property universal_thermal_climate_index

A Data Collection of Universal Thermal Climate Index (UTCI) in C.

property wind_speed

Data Collection of air speed values in m/s.