feat(ts, asv): Add Thermal Sensation and Actual Sensation Vote modules

* Add thermal sensation module

* Add Actual Sensation Vote module

* rename as.py -> asv.py

* add tests for thermal sensation module

* add tests for ASV module

ladybug_comfort/asv.py

@@ -0,0 +1,69 @@
+# coding=utf-8
+"""Utility functions for calculating Actual Sensation Vote (ASV)"""
+
+
+def actual_sensation_vote(ta, ws, rh, sr):
+    """Calculate Actual Sensation Vote (ASV) from air temperature, wind speed,
+    relative humidity and solar radiation.
+
+    Actual Sensation Vote is an index which estimates human thermal sensation
+    based on the empirical data gathered from field and human surveys,
+    interviews and questionnaires.
+    Actual Sensation Vote is derived from original work carried out by Givoni and
+    Noguchi [1].
+
+    Note:
+        [1] Zambrano, Letícia & Malafaia, Cristina & Bastos, Leopoldo.
+        (2006). Thermal comfort evaluation in outdoor space of tropical humid
+        climate.
+
+    Args:
+        ta: Air temperature [C]
+        ws: Wind speed [m/s]
+        rh: Relative humidity [%]
+        sr: Solar radiation [Wh/m2]
+
+    Returns:
+        asv: Actual sensation vote [unitless]
+    """
+    asv = 0.049 * ta + 0.001 * sr - 0.051 * ws + 0.014 * rh - 2.079
+
+    return asv
+
+
+def actual_sensation_vote_effect_category(asv):
+    """Get the category of effect associated with a given actual sensation vote
+    (ASV).
+
+    Each number (from -2 to 2) represents a certain ASV thermal sensation
+    category. With categories being the following:
+        -2 = Very cold
+        -1 = Cold
+         0 = Comfort
+         1 = Hot
+         2 = Very Hot
+
+    Args:
+        asv: Actual Sensation Vote [unitless]
+
+    Returns:
+        category: An integer indicating the level of effect associated with the
+        thermal sensation. Values are one of the following:
+                -2 = Very cold
+                -1 = Cold
+                 0 = Comfort
+                 1 = Hot
+                 2 = Very Hot
+    """
+    if asv > 2:
+        category = 2
+    elif asv > 1:
+        category = 1
+    elif asv >= -1:
+        category = 0
+    elif asv >= -2:
+        category = -1
+    else:
+        category = -2
+
+    return category

ladybug_comfort/ts.py

@@ -0,0 +1,80 @@
+# coding=utf-8
+"""Utility functions for calculating Thermal Sensation (TS)."""
+
+
+def thermal_sensation(ta, ws, rh, sr, tground):
+    """Calculate Thermal Sensation (TS) from air temperature, wind speed,
+    relative humidity, solar radiation and groud temperature.
+
+    Thermal Sensation is an index which predicts sensation of
+    satisfaction/dissatisfaction under the prevailing outdoor climatic
+    conditions.
+    Thermal Sensation is derived from original work carried out by Givoni and
+    Noguchi [1].
+
+    Note:
+        [1] Givoni, Baruch & Noguchi, Mikiko & Saaroni, Hadas & Potchter,
+        Oded & Yaakov, Yaron & Feller, Noa & Becker, Stefan. (2003). Outdoor
+        comfort research issues. Energy and Buildings. 35. 77-86.
+        10.1016/S0378-7788(02)00082-8.
+
+    Args:
+        ta: Air temperature [C]
+        ws: Wind speed [m/s]
+        rh: Relative humidity [%]
+        sr: Solar radiation [Wh/m2]
+        tground: Ground temperature [C]
+
+    Returns:
+        ts: Thermal sensation [unitless]
+    """
+    ts = 1.7 + 0.1118 * ta + 0.0019 * sr - 0.322 * ws - 0.0073 * rh + 0.0054 \
+        * tground
+
+    return ts
+
+
+def thermal_sensation_effect_category(ts):
+    """Get the category of effect associated with a given thermal sensation
+    (TS).
+
+    Each number (from -3 to 3) represents a certain TS thermal sensation
+    category. With categories being the following:
+    -3 = Very cold
+    -2 = Quite cold
+    -1 = Cold
+     0 = Comfort
+     1 = Hot
+     2 = Quite Hot
+     3 = Very hot
+
+    Args:
+        ts: Thermal Sensation [unitless]
+
+    Returns:
+        category: An integer indicating the level of effect associated with the
+        thermal sensation. Values are one of the following:
+                -3 = Very cold
+                -2 = Quite cold
+                -1 = Cold
+                 0 = Comfort
+                 1 = Hot
+                 2 = Quite Hot
+                 3 = Very hot
+    """
+    if ts >= 7:
+        category = 3
+    elif ts >= 6:
+        category = 2
+    elif ts >= 5:
+        category = 1
+    elif ts >= 4:
+        category = 0
+    elif ts >= 3:
+        category = -1
+    elif ts >= 2:
+        category = -2
+    else:
+        category = -3
+
+    return category

tests/asv_test.py

@@ -0,0 +1,22 @@
+# coding utf-8
+import pytest
+
+from ladybug_comfort.asv import actual_sensation_vote
+from ladybug_comfort.asv import actual_sensation_vote_effect_category
+
+
+def test_actual_sensation_vote():
+    """Test the actual_sensation_vote function."""
+    assert actual_sensation_vote(40, 10, 15, 10) == pytest.approx(-0.4090,
+                                                                  rel=1e-3)
+    assert actual_sensation_vote(20, 50, 34, 48) == pytest.approx(-3.1250,
+                                                                  rel=1e-3)
+
+
+def test_actual_sensation_vote_effect_category():
+    """Test the actual_sensation_vote_effect_category function"""
+    assert actual_sensation_vote_effect_category(2.5) == 2
+    assert actual_sensation_vote_effect_category(1.4) == 1
+    assert actual_sensation_vote_effect_category(0.5) == 0
+    assert actual_sensation_vote_effect_category(-1.4) == -1
+    assert actual_sensation_vote_effect_category(-2.5) == -2

tests/ts_test.py

@@ -0,0 +1,24 @@
+# coding utf-8
+import pytest
+
+from ladybug_comfort.ts import thermal_sensation
+from ladybug_comfort.ts import thermal_sensation_effect_category
+
+
+def test_thermal_sensation():
+    """Test the thermal_sensation function."""
+    assert thermal_sensation(40, 10, 15, 10, 11) == pytest.approx(2.9208,
+                                                                  rel=1e-3)
+    assert thermal_sensation(20, 50, 34, 48, 32) == pytest.approx(-12.1482,
+                                                                  rel=1e-3)
+
+
+def test_thermal_sensation_effect_category():
+    """Test the thermal_sensation_effect_category function"""
+    assert thermal_sensation_effect_category(7.5) == 3
+    assert thermal_sensation_effect_category(6.4) == 2
+    assert thermal_sensation_effect_category(5.2) == 1
+    assert thermal_sensation_effect_category(4.8) == 0
+    assert thermal_sensation_effect_category(3.7) == -1
+    assert thermal_sensation_effect_category(2.5) == -2
+    assert thermal_sensation_effect_category(-4) == -3