docstrings, signatures

wradlib/atten.py

@@ -64,14 +64,15 @@ def correct_attenuation_hb(
         polar form with `m` azimuths and `n` range-bins the input array's
         shape can be either (l,m,n) or (m,l,n)
         data has to be provided in decibel representation of reflectivity [dBZ]
-    a : float
-        proportionality factor of the k-Z relation (:math:`k=a \\cdot Z^{b}`).
-        Per default set to 1.67e-4.
-    b : float
-        exponent of the k-Z relation ( :math:`k=a \\cdot Z^{b}` ). Per default
-        set to 0.7.
-    gate_length : float
-        length of a range gate [km]. Per default set to 1.0.
+    coefficients : dict
+        - a : float
+          proportionality factor of the k-Z relation (:math:`k=a \\cdot Z^{b}`).
+          Per default set to 1.67e-4.
+        - b : float
+          exponent of the k-Z relation ( :math:`k=a \\cdot Z^{b}` ). Per default
+          set to 0.7.
+        - gate_length : float
+          length of a range gate [km]. Per default set to 1.0.
     mode : str
         controls how the function reacts, if the sum of signal and attenuation
         exceeds the threshold ``thrs``
@@ -395,45 +396,37 @@ def correct_attenuation_constrained(
         to be performed) are supposed to vary along the last array-dimension
         and the azimuths are supposed to vary along the next to last
         array-dimension.
-
         Data has to be provided in decibel representation of reflectivity
         [dBZ].
     a_max : float
         Initial value for linear coefficient of the k-Z relation
         ( :math:`k=a \\cdot Z^{b}` ).
-
         Per default set to 1.67e-4.
     a_min : float
         Minimal allowed linear coefficient of the k-Z relation
         ( :math:`k=a \\cdot Z^{b}` ) in the downwards iteration of 'a' in case
         of breaching one of thresholds ``constr_args`` of the optional
         conditions ``constraints``.
-
         Per default set to 2.33e-5.
     n_a : int
         Number of iterations from ``a_max`` to ``a_min``.
-
         Per default set to 4.
     b_max : float
         Initial value for exponential coefficient of the k-Z relation
         ( :math:`k=a \\cdot Z^{b}` ).
-
         Per default set to 0.7.
     b_min : float
         Minimal allowed exponential coefficient of the k-Z relation
         ( :math:`k=a \\cdot Z^{b}` ) in the downwards iteration of 'b' in case
         of breaching one of thresholds ``constr_args`` of the optional
         conditions ``constraints`` and the linear coefficient 'a' has already
         reached the lower limit ``a_min``.
-
         Per default set to 0.65.
     n_b : int
         Number of iterations from ``b_max`` to ``b_min``.
-
         Per default set to 6.
     gate_length : float
         Radial length of a range gate [km].
-
         Per default set to 1.0.
     constraints : list
         List of constraint functions. The signature of these functions has to

wradlib/classify.py

@@ -284,13 +284,7 @@ def filter_gabella(
     obj,
     *,
     wsize=5,
-    thrsnorain=0.0,
-    tr1=6.0,
-    n_p=6,
-    tr2=1.3,
-    rm_nans=True,
-    radial=False,
-    cartesian=False,
+    **kwargs,
 ):
     """Clutter identification filter developed by :cite:`Gabella2002`.
 
@@ -301,11 +295,11 @@ def filter_gabella(
     Parameters
     ----------
     obj : :py:class:`numpy:numpy.ndarray`
+    wsize : int, optional
+        Size of the window surrounding the central pixel, defaults to 5.
 
     Keyword Arguments
     -----------------
-    wsize : int
-        Size of the window surrounding the central pixel
     thrsnorain : float
     tr1 : float
     n_p : int
@@ -336,6 +330,14 @@ def filter_gabella(
     See :ref:`/notebooks/classify/clutter_gabella.ipynb`.
 
     """
+    thrsnorain = kwargs.get("thrsnorain", 0.0)
+    tr1 = kwargs.get("tr1", 6.0)
+    n_p = kwargs.get("n_p", 6)
+    tr2 = kwargs.get("tr2", 1.3)
+    rm_nans = kwargs.get("rm_nans", True)
+    radial = kwargs.get("radial", False)
+    cartesian = kwargs.get("cartesian", False)
+
     bad = np.isnan(obj)
     if rm_nans:
         obj = obj.copy()
@@ -435,12 +437,9 @@ def histo_cut(obj, *, upper_frequency=0.01, lower_frequency=0.01):
     ----------
     obj : :py:class:`numpy:numpy.ndarray`
         spatial array containing rain accumulation
-
-    Keyword Arguments
-    -----------------
-    upper_frequency : float
+    upper_frequency : float, optional
         Upper frequency percentage for clutter detection, defaults to 0.01.
-    lower_frequency : float
+    lower_frequency : float, optional
         Lower frequency percentage for shading detection, defaults to 0.01.
 
     Returns
@@ -1294,12 +1293,9 @@ def classify(data, *, threshold=0.0):
     data : :py:class:`numpy:numpy.ndarray`
         Array which is of size (hmc-class, data.shape), containing the
         weighted hmc-membership probability values.
-
-    Keyword Arguments
-    -----------------
-    threshold : float
+    threshold : float, optional
         Threshold value where probability is considered no precip,
-        defaults to 0
+        defaults to 0.
 
     Returns
     -------

wradlib/dp.py

@@ -90,18 +90,21 @@ def phidp_kdp_vulpiani(
         array of shape (n azimuth angles, n range gates)
     dr : float
         gate length in km
+    ndespeckle : int, optional
+        ``ndespeckle`` parameter of :func:`~wradlib.util.despeckle`,
+        defaults to 5
+    winlen : int, optional
+        ``winlen`` parameter of :func:`~wradlib.dp.kdp_from_phidp`,
+        defaults to 7
+    niter : int, optional
+        Number of iterations in which :math:`Phi_{DP}` is retrieved from
+        :math:`K_{DP}` and vice versa, defaults to 2.
+    copy : bool, optional
+        if True, the original :math:`Phi_{DP}` array will remain unchanged,
+        defaults to False
 
     Keyword Arguments
     -----------------
-    ndespeckle : int
-        ``ndespeckle`` parameter of :func:`~wradlib.util.despeckle`
-    winlen : int
-        ``winlen`` parameter of :func:`~wradlib.dp.kdp_from_phidp`
-    niter : int
-        Number of iterations in which :math:`Phi_{DP}` is retrieved from
-        :math:`K_{DP}` and vice versa
-    copy : bool
-        if True, the original :math:`Phi_{DP}` array will remain unchanged
     th1 : float
         Threshold th1 from above cited paper.
     th2 : float
@@ -247,15 +250,12 @@ def unfold_phi_vulpiani(phidp, kdp, *, th=-20, winlen=7):
         array of floats
     kdp : :class:`numpy:numpy.ndarray`
         array of floats
-
-    Keyword Arguments
-    -----------------
-    th : float
-        Threshold th3 in the above citation.
-    winlen : int
+    th : float, optional
+        Threshold th3 in the above citation, defaults to -20.
+    winlen : int, optional
         Length of window to fix possible phase over-correction. Normally
         should take the value of the length of the processing window in
-        the above citation.
+        the above citation, defaults to 7.
 
     Returns
     -------
@@ -388,9 +388,7 @@ def _fill_sweep(dat, *, kind="nan_to_num", fill_value=0.0):
 
 
 @singledispatch
-def kdp_from_phidp(
-    phidp, *, winlen=7, dr=1.0, method="lanczos_conv", skipna=True, **kwargs
-):
+def kdp_from_phidp(phidp, *, winlen=7, dr=1.0, method="lanczos_conv", **kwargs):
     """Retrieves :math:`K_{DP}` from :math:`Phi_{DP}`.
 
     In normal operation the method uses convolution to estimate :math:`K_{DP}`
@@ -422,16 +420,16 @@ def kdp_from_phidp(
     phidp : :class:`numpy:numpy.ndarray`
         multidimensional array, note that the range dimension must be the
         last dimension of the input array.
+    winlen : int, optional
+        Width of the window (as number of range gates), defaults to 7
+    dr : float, optional
+        gate length in km, defaults to 1
+    method : str, optional
+        Defaults to 'lanczos_conv'. Can also take one of 'lanczos_dot', 'lstsq',
+        'cov', 'cov_nan', 'matrix_inv'.
 
     Keyword Arguments
     -----------------
-    winlen : int
-        Width of the window (as number of range gates)
-    dr : float
-        gate length in km
-    method : str
-        Defaults to 'lanczos_conv'. Can also take one of 'lanczos_dot', 'lstsq',
-        'cov', 'cov_nan', 'matrix_inv'.
     skipna : bool
         Defaults to True. Local Linear regression removing NaN values using
         valid neighbors > min_periods
@@ -464,6 +462,7 @@ def kdp_from_phidp(
     >>> lgnd = plt.legend(("phidp_true", "phidp_raw", "kdp_true", "kdp_reconstructed"))  # noqa
     >>> plt.show()
     """
+    skipna = kwargs.pop("skipna", True)
     pad_mode = kwargs.pop("pad_mode", None)
     if pad_mode is None:
         pad_mode = "reflect"
@@ -576,13 +575,10 @@ def unfold_phi(phidp, rho, *, width=5, copy=False):
         array of shape (...,nr) with nr being the number of range bins
     rho : :class:`numpy:numpy.ndarray`
         array of same shape as ``phidp``
-
-    Keyword Arguments
-    -----------------
-    width : int
-       Width of the analysis window
-    copy : bool
-       Leaves original ``phidp`` array unchanged if set to True
+    width : int, optional
+       Width of the analysis window, defaults to 5.
+    copy : bool, optional
+       Leaves original `phidp` array unchanged if set to True
        (default: False)
 
     Returns

wradlib/georef/misc.py

@@ -45,12 +45,9 @@ def bin_altitude(r, theta, sitealt, *, re=6371000, ke=4.0 / 3.0):
         at horizontal and +90° pointing vertically upwards from the radar
     sitealt : float
         Altitude in [m] a.s.l. of the referencing radar site
-
-    Keyword Arguments
-    -----------------
-    re : float
-        earth's radius [m]
-    ke : float
+    re : float, optional
+        earth's radius [m], defaults to 6371000.
+    ke : float, optional
         adjustment factor to account for the refractivity gradient that
         affects radar beam propagation. In principle this is wavelength-
         dependend. The default of 4/3 is a good approximation for most
@@ -210,12 +207,9 @@ def site_distance(r, theta, binalt, *, re=6371000, ke=4.0 / 3.0):
         at horizontal and +90° pointing vertically upwards from the radar
     binalt : :class:`numpy:numpy.ndarray`
         site altitude [m] amsl. same shape as r.
-
-    Keyword Arguments
-    -----------------
-    re : float
-        earth's radius [m]
-    ke : float
+    re : float, optional
+        earth's radius [m], defaults to 6371000.
+    ke : float, optional
         adjustment factor to account for the refractivity gradient that
         affects radar beam propagation. In principle this is wavelength-
         dependend. The default of 4/3 is a good approximation for most

wradlib/georef/polar.py

@@ -50,8 +50,7 @@ def spherical_to_xyz(
     *,
     re=None,
     ke=4.0 / 3.0,
-    squeeze=False,
-    strict_dims=False,
+    **kwargs,
 ):
     """Transforms spherical coordinates (r, phi, theta) to cartesian
     coordinates (x, y, z) centered at site (aeqd).
@@ -71,21 +70,22 @@ def spherical_to_xyz(
     site : sequence
         the lon / lat / alt coordinates of the radar location and its altitude
         a.m.s.l. (in meters)
-
-    Keyword Arguments
-    -----------------
-    re : float
-        earth's radius [m], defaults to None (calculating from given latitude)
-    ke : float
+    re : float, optional
+        earth's radius [m], defaults to None (calculating from given latitude).
+    ke : float, optional
         adjustment factor to account for the refractivity gradient that
         affects radar beam propagation. In principle this is wavelength-
         dependend. The default of 4/3 is a good approximation for most
         weather radar wavelengths.
-    squeeze : bool
+
+    Keyword Arguments
+    -----------------
+    squeeze : bool, optional
         If True, returns squeezed array. Defaults to False.
-    strict_dims : bool
+    strict_dims : bool, optional
         If True, generates output of (theta, phi, r, 3) in any case.
         If False, dimensions with same length are "merged".
+        Defaults to False.
 
     Returns
     -------
@@ -94,6 +94,9 @@ def spherical_to_xyz(
     aeqd : :py:class:`gdal:osgeo.osr.SpatialReference`
         Destination Spatial Reference System (AEQD-Projection).
     """
+    squeeze = kwargs.get("squeeze", False)
+    strict_dims = kwargs.get("strict_dims", False)
+
     centalt = site[2]
 
     # if no radius is given, get the approximate radius of the WGS84
@@ -254,15 +257,12 @@ def spherical_to_proj(r, phi, theta, site, *, crs=None, re=None, ke=4.0 / 3.0):
         the lon / lat coordinates of the radar location and its altitude
         a.m.s.l. (in meters)
         if site is of length two, altitude is assumed to be zero
-
-    Keyword Arguments
-    -----------------
-    crs : :py:class:`gdal:osgeo.osr.SpatialReference`
+    crs : :py:class:`gdal:osgeo.osr.SpatialReference`, optional
         Destination Spatial Reference System (Projection).
         Defaults to wgs84 (epsg 4326).
-    re : float
-        earth's radius [m]
-    ke : float
+    re : float, optional
+        earth's radius [m], defaults to None (calculating from given latitude).
+    ke : float, optional
         adjustment factor to account for the refractivity gradient that
         affects radar beam propagation. In principle this is wavelength-
         dependend. The default of 4/3 is a good approximation for most
@@ -870,22 +870,19 @@ def maximum_intensity_projection(
     ----------
     data : :class:`numpy:numpy.ndarray`
         Array containing polar data (azimuth, range)
-
-    Keyword Arguments
-    -----------------
-    r : :class:`numpy:numpy.ndarray`
+    r : :class:`numpy:numpy.ndarray`, optional
         Array containing range data
-    az : :class:`numpy:numpy.ndarray`
+    az : :class:`numpy:numpy.ndarray`, optional
         Array containing azimuth data
-    angle : float
+    angle : float, optional
         angle of slice, Defaults to 0. Should be between 0 and 180.
         0. means horizontal slice, 90. means vertical slice
-    elev : float
+    elev : float, optional
         elevation angle of scan, Defaults to 0.
-    autoext : bool
+    autoext : bool, optional
         This routine uses :func:`numpy.numpy.digitize` to bin the data.
         As this function needs bounds, we create one set of coordinates more
-        than would usually be provided by `r` and `az`.
+        than would usually be provided by `r` and `az`. Defaults to True.
 
     Returns
     -------