fix(analyze): Expose UTCI comfort parameters

ladybug_grasshopper/json/LB_UTCI_Comfort.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.6.0", 
+  "version": "1.6.1", 
   "nickname": "UTCI", 
   "outputs": [
     [
@@ -69,6 +69,13 @@
       "type": "System.Object", 
       "default": null
     }, 
+    {
+      "access": "item", 
+      "name": "utci_par_", 
+      "description": "Optional comfort parameters from the \"LB UTCI Comfort Parameters\"\ncomponent to specify the temperatures (in Celcius) that are\nconsidered acceptable/comfortable. The default will assume a that\nthe comfort range is between 9C and 26C.", 
+      "type": "System.Object", 
+      "default": null
+    }, 
     {
       "access": "item", 
       "name": "_run", 
@@ -78,7 +85,7 @@
     }
   ], 
   "subcategory": "1 :: Analyze Data", 
-  "code": "\ntry:\n    from ladybug.datatype.temperature import Temperature\n    from ladybug.datacollection import BaseCollection\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_comfort.collection.utci import UTCI\n    from ladybug_comfort.parameter.utci import UTCIParameter\n    from ladybug_comfort.utci import universal_thermal_climate_index\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_comfort:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\ndef extract_collections(input_list):\n    \"\"\"Process inputs into collections and floats.\"\"\"\n    defaults = [None, _air_temp, 0.5, None]\n    data_colls = []\n    for i, input in enumerate(input_list):\n        if input is None:\n            input_list[i] = defaults[i]\n        elif isinstance(input, BaseCollection):\n            data_colls.append(input)\n        else:\n            try:\n                input_list[i] = float(input)\n            except ValueError as e:\n                raise TypeError('input {} is not valid. Expected float or '\n                                'DataCollection. Got {}'.format(input, type(input)))\n    return input_list, data_colls\n\nif all_required_inputs(ghenv.Component) and _run is True:\n    # Process inputs and assign defaults.\n    input_list = [_air_temp, _mrt_, _wind_vel_, _rel_humid]\n    input, data_colls = extract_collections(input_list)\n    \n    if data_colls == []:\n        # The inputs are all individual values.\n        utci = universal_thermal_climate_index(\n            input[0], float(input[1]), input[2], input[3])\n        utci_par = UTCIParameter()\n        comfort = utci_par.is_comfortable(utci)\n        condition = utci_par.thermal_condition(utci)\n        category = utci_par.thermal_condition_eleven_point(utci)\n    else:\n        # The inputs include Data Collections.\n        if not isinstance(_air_temp, BaseCollection):\n            _air_temp = data_colls[0].get_aligned_collection(\n                float(_air_temp), Temperature(), 'C')\n        \n        comf_obj = UTCI(_air_temp, _rel_humid, _mrt_, _wind_vel_)\n        utci = comf_obj.universal_thermal_climate_index\n        comfort = comf_obj.is_comfortable\n        condition = comf_obj.thermal_condition\n        category = comf_obj.thermal_condition_eleven_point", 
+  "code": "\ntry:\n    from ladybug.datatype.temperature import Temperature\n    from ladybug.datacollection import BaseCollection\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_comfort.collection.utci import UTCI\n    from ladybug_comfort.parameter.utci import UTCIParameter\n    from ladybug_comfort.utci import universal_thermal_climate_index\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_comfort:\\n\\t{}'.format(e))\n\ntry:\n    from ladybug_{{cad}}.{{plugin}} import all_required_inputs\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_{{cad}}:\\n\\t{}'.format(e))\n\n\ndef extract_collections(input_list):\n    \"\"\"Process inputs into collections and floats.\"\"\"\n    defaults = [None, _air_temp, 0.5, None]\n    data_colls = []\n    for i, input in enumerate(input_list):\n        if input is None:\n            input_list[i] = defaults[i]\n        elif isinstance(input, BaseCollection):\n            data_colls.append(input)\n        else:\n            try:\n                input_list[i] = float(input)\n            except ValueError as e:\n                raise TypeError('input {} is not valid. Expected float or '\n                                'DataCollection. Got {}'.format(input, type(input)))\n    return input_list, data_colls\n\nif all_required_inputs(ghenv.Component) and _run is True:\n    # Process inputs and assign defaults.\n    input_list = [_air_temp, _mrt_, _wind_vel_, _rel_humid]\n    input, data_colls = extract_collections(input_list)\n    utci_par = utci_par_ or UTCIParameter()\n\n    if data_colls == []:\n        # The inputs are all individual values.\n        utci = universal_thermal_climate_index(\n            input[0], float(input[1]), input[2], input[3])\n        utci_par = UTCIParameter()\n        comfort = utci_par.is_comfortable(utci)\n        condition = utci_par.thermal_condition(utci)\n        category = utci_par.thermal_condition_eleven_point(utci)\n    else:\n        # The inputs include Data Collections.\n        if not isinstance(_air_temp, BaseCollection):\n            _air_temp = data_colls[0].get_aligned_collection(\n                float(_air_temp), Temperature(), 'C')\n\n        comf_obj = UTCI(_air_temp, _rel_humid, _mrt_, _wind_vel_, utci_par)\n        utci = comf_obj.universal_thermal_climate_index\n        comfort = comf_obj.is_comfortable\n        condition = comf_obj.thermal_condition\n        category = comf_obj.thermal_condition_eleven_point", 
   "category": "Ladybug", 
   "name": "LB UTCI Comfort", 
   "description": "Calculate Universal Thermal Climate Index (UTCI).\n-\nUTCI is a thermal comfort model strictly for the outdoors. It is an international\nstandard for outdoor temperature sensation (aka. \"feels-like\" temperature) and\nis one of the most common of such \"feels-like\" temperatures used by\nmeteorologists. UTCI that attempts to satisfy the following requirements:\n_\n1) Thermo-physiological significance in the whole range of heat exchange conditions.\n2) Valid in all climates, seasons, and scales.\n3) Useful for key applications in human biometeorology.\n_\nWhile UTCI is designed to be valid in all climates and seasons, it assumes\nthat human subjects are walking (with a metabolic rate around 2.4 met) and\nthat they naturally adapt their clothing with the outdoor temperature.\nFor outdoor situations that do not fit these criteria, the Physiological\nEquivalent Temperature (PET) model is recommended.\n-"

ladybug_grasshopper/json/LB_UTCI_Comfort_Parameters.json

@@ -0,0 +1,36 @@
+{
+  "version": "1.6.0", 
+  "nickname": "UTCIPar", 
+  "outputs": [
+    [
+      {
+        "access": "None", 
+        "name": "utci_par", 
+        "description": "A UTCI comfort parameter object that can be plugged into\nany of the components that compute UTCI thermal comfort.", 
+        "type": null, 
+        "default": null
+      }
+    ]
+  ], 
+  "inputs": [
+    {
+      "access": "item", 
+      "name": "_cold_thresh_", 
+      "description": "Temperature in Celsius below which the UTCI represents\ncold stress. (Default: 9C).", 
+      "type": "double", 
+      "default": null
+    }, 
+    {
+      "access": "item", 
+      "name": "_heat_thresh_", 
+      "description": "A number between 0 and 1 indicating the upper limit of\nhumidity ratio that is considered acceptable.\nDefault is 1 for essentially no limit.", 
+      "type": "double", 
+      "default": null
+    }
+  ], 
+  "subcategory": "4 :: Extra", 
+  "code": "\ntry:\n    from ladybug_comfort.parameter.utci import UTCIParameter\nexcept ImportError as e:\n    raise ImportError('\\nFailed to import ladybug_comfort:\\n\\t{}'.format(e))\n\nmoderate_cold, moderate_heat = None, None\nif _cold_thresh_ and _cold_thresh_ < 0:\n    moderate_cold = _cold_thresh_\nif _heat_thresh_ and _heat_thresh_ > 28:\n    moderate_heat = _heat_thresh_\n\nutci_par = UTCIParameter(\n    cold_thresh=_cold_thresh_,\n    heat_thresh=_heat_thresh_,\n    moderate_cold_thresh=moderate_cold,\n    moderate_heat_thresh=moderate_heat\n)\n", 
+  "category": "Ladybug", 
+  "name": "LB UTCI Comfort Parameters", 
+  "description": "Create a set of parameters that define the acceptable conditions of the\nUniversal Thermal Climate Index (UTCI) comfort model.\n-\nThese parameters can be plugged into any of the components that compute UTCI comfort.\n-"
+}

ladybug_grasshopper/src/LB UTCI Comfort Parameters.py

@@ -0,0 +1,51 @@
+# Ladybug: A Plugin for Environmental Analysis (GPL)
+# This file is part of Ladybug.
+#
+# Copyright (c) 2023, Ladybug Tools.
+# You should have received a copy of the GNU Affero General Public License
+# along with Ladybug; If not, see <http://www.gnu.org/licenses/>.
+# 
+# @license AGPL-3.0-or-later <https://spdx.org/licenses/AGPL-3.0-or-later>
+
+"""
+Create a set of parameters that define the acceptable conditions of the
+Universal Thermal Climate Index (UTCI) comfort model.
+-
+These parameters can be plugged into any of the components that compute UTCI comfort.
+-
+
+    Args:
+        _cold_thresh_: Temperature in Celsius below which the UTCI represents
+            cold stress. (Default: 9C).
+        heat_thresh: Temperature in Celsius above which the UTCI represents
+            heat stress. (Default: 26C).
+    
+    Returns:
+        utci_par: A UTCI comfort parameter object that can be plugged into
+            any of the components that compute UTCI thermal comfort.
+"""
+
+ghenv.Component.Name = 'LB UTCI Comfort Parameters'
+ghenv.Component.NickName = 'UTCIPar'
+ghenv.Component.Message = '1.6.0'
+ghenv.Component.Category = 'Ladybug'
+ghenv.Component.SubCategory = '4 :: Extra'
+ghenv.Component.AdditionalHelpFromDocStrings = '0'
+
+try:
+    from ladybug_comfort.parameter.utci import UTCIParameter
+except ImportError as e:
+    raise ImportError('\nFailed to import ladybug_comfort:\n\t{}'.format(e))
+
+moderate_cold, moderate_heat = None, None
+if _cold_thresh_ and _cold_thresh_ < 0:
+    moderate_cold = _cold_thresh_
+if _heat_thresh_ and _heat_thresh_ > 28:
+    moderate_heat = _heat_thresh_
+
+utci_par = UTCIParameter(
+    cold_thresh=_cold_thresh_,
+    heat_thresh=_heat_thresh_,
+    moderate_cold_thresh=moderate_cold,
+    moderate_heat_thresh=moderate_heat
+)

ladybug_grasshopper/src/LB UTCI Comfort.py

@@ -40,6 +40,10 @@
             human subject by 1.5 will make them a suitable input for this
             component. Default is a low speed of 0.5 m/s, which is the lowest
             input speed that is recommended for the UTCI model.
+        utci_par_: Optional comfort parameters from the "LB UTCI Comfort Parameters"
+            component to specify the temperatures (in Celcius) that are
+            considered acceptable/comfortable. The default will assume a that 
+            the comfort range is between 9C and 26C.
         _run: Set to True to run the component.
 
     Returns:
@@ -79,7 +83,7 @@
 
 ghenv.Component.Name = 'LB UTCI Comfort'
 ghenv.Component.NickName = 'UTCI'
-ghenv.Component.Message = '1.6.0'
+ghenv.Component.Message = '1.6.1'
 ghenv.Component.Category = 'Ladybug'
 ghenv.Component.SubCategory = '1 :: Analyze Data'
 ghenv.Component.AdditionalHelpFromDocStrings = '5'
@@ -124,7 +128,8 @@ def extract_collections(input_list):
     # Process inputs and assign defaults.
     input_list = [_air_temp, _mrt_, _wind_vel_, _rel_humid]
     input, data_colls = extract_collections(input_list)
-
+    utci_par = utci_par_ or UTCIParameter()
+
     if data_colls == []:
         # The inputs are all individual values.
         utci = universal_thermal_climate_index(
@@ -138,8 +143,8 @@ def extract_collections(input_list):
         if not isinstance(_air_temp, BaseCollection):
             _air_temp = data_colls[0].get_aligned_collection(
                 float(_air_temp), Temperature(), 'C')
-        
-        comf_obj = UTCI(_air_temp, _rel_humid, _mrt_, _wind_vel_)
+
+        comf_obj = UTCI(_air_temp, _rel_humid, _mrt_, _wind_vel_, utci_par)
         utci = comf_obj.universal_thermal_climate_index
         comfort = comf_obj.is_comfortable
         condition = comf_obj.thermal_condition