chore: improve fuction and coefficient documentation

Author: yuriishizawa

physics/rainfall_intensity.py

@@ -3,42 +3,61 @@
 ==================
 This module contains functions to calculate the intensity of
 a rainfall event for a given duration and return period.
+
+This function uses the Sherman intensity-duration-frequency curve.
+
+References
+----------
+- Aparicio, F. (1997): Fundamentos de Hidrología de Superficie.
+    Balderas, México, Limusa. 303 p.
+- https://en.wikipedia.org/wiki/Intensity-duration-frequency_curve
 """
 
 
 def rainfall_intensity(
-    k: float, a: float, b: float, c: float, tr: float, t: float
+    coefficient_k: float,
+    coefficient_a: float,
+    coefficient_b: float,
+    coefficient_c: float,
+    return_period: float,
+    duration: float,
 ) -> float:
     """
     Calculate the intensity of a rainfall event for a given duration and return period.
-    The coefficients K, a, b, and c are obtained from the Sherman
-    intensity-duration-frequency curve for a specific location.
+    It's based on the Sherman intensity-duration-frequency curve:
+
+    I = K * T^a / (D + b)^c
+
+    where:
+        I = Intensity of the rainfall event [mm/h]
+        k, a, b, c = Coefficients obtained through statistical distribution adjust
+        T = Return period in years
+        D = Rainfall event duration in minutes
 
     Parameters
     ----------
-    k : float
-        Coefficient [adm].
-    a : float
-        Coefficient [adm].
-    b : float
-        Coefficient [adm].
-    c : float
-        Coefficient [adm].
-    tr : float
+    coefficient_k : float
+        Coefficient obtained through statistical distribution adjust.
+    coefficient_a : float
+        Coefficient obtained through statistical distribution adjust.
+    coefficient_b : float
+        Coefficient obtained through statistical distribution adjust.
+    coefficient_c : float
+        Coefficient obtained through statistical distribution adjust.
+    return_period : float
         Return period in years.
-    t : float
+    duration : float
         Rainfall event duration in minutes.
 
     Returns
     -------
     intensity : float
         Intensity of the rainfall event in mm/h.
 
-    References
-    ----------
-    - Aparicio, F. (1997): Fundamentos de Hidrología de Superficie.
-        Balderas, México, Limusa. 303 p.
-    - https://en.wikipedia.org/wiki/Intensity-duration-frequency_curve
+    Raises
+    ------
+    ValueError
+        If any of the parameters are not positive.
 
     Examples
     --------
@@ -55,57 +74,66 @@ def rainfall_intensity(
     >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, -0.2, 11.6, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, -11.6, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, 11.6, -0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0, 11.6, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, 0, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, 11.6, 0, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 0, 60)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 10, 0)
     Traceback (most recent call last):
     ...
-    ValueError: Please ensure that all parameters are positive.
+    ValueError: All parameters must be positive.
 
     """
-    if k <= 0 or a <= 0 or b <= 0 or c <= 0 or tr <= 0 or t <= 0:
-        raise ValueError("Please ensure that all parameters are positive.")
-    intensity = (k * (tr**a)) / ((t + b) ** c)
+    if (
+        coefficient_k <= 0
+        or coefficient_a <= 0
+        or coefficient_b <= 0
+        or coefficient_c <= 0
+        or return_period <= 0
+        or duration <= 0
+    ):
+        raise ValueError("All parameters must be positive.")
+    intensity = (coefficient_k * (return_period**coefficient_a)) / (
+        (duration + coefficient_b) ** coefficient_c
+    )
     return intensity