Merge pull request #162 from GeoStat-Framework/variogram_normalizer_return

return fitted normalizer

Author: MuellerSeb

gstools/normalizer/tools.py

@@ -77,7 +77,7 @@ def apply_mean_norm_trend(
 
     Returns
     -------
-    :class:`numpy.ndarray`
+    field : :class:`numpy.ndarray`
         The transformed field.
     """
     normalizer = _check_normalizer(normalizer)
@@ -153,8 +153,11 @@ def remove_trend_norm_mean(
 
     Returns
     -------
-    :class:`numpy.ndarray`
+    field : :class:`numpy.ndarray`
         The cleaned field.
+    normalizer : :any:`Normalizer`, optional
+        The fitted normalizer for the given data.
+        Only provided if `fit_normalizer` is True.
     """
     normalizer = _check_normalizer(normalizer)
     if check_shape:
@@ -179,4 +182,5 @@ def remove_trend_norm_mean(
     field = normalizer.normalize(field)
     for i in range(field_cnt):
         field[i] -= eval_func(mean, pos, dim, mesh_type, value_type, True)
-    return field if stacked else field[0]
+    out = field if stacked else field[0]
+    return (out, normalizer) if fit_normalizer else out

gstools/variogram/variogram.py

@@ -131,8 +131,8 @@ def vario_estimate(
         same points, with the same statistical properties.
     bin_edges : :class:`numpy.ndarray`, optional
         the bins on which the variogram will be calculated.
-        If :any:`None` are given, standard bins provided by the :any:`standard_bins`
-        routine will be used. Default: :any:`None`
+        If :any:`None` are given, standard bins provided by the
+        :any:`standard_bins` routine will be used. Default: :any:`None`
     sampling_size : :class:`int` or :any:`None`, optional
         for large input data, this method can take a long
         time to compute the variogram, therefore this argument specifies
@@ -217,11 +217,18 @@ def vario_estimate(
 
     Returns
     -------
-    :class:`tuple` of :class:`numpy.ndarray`
-        1. the bin centers
-        2. the estimated variogram values at bin centers
-        3. (optional) the number of points found at each bin center
-           (see argument return_counts)
+    bin_center : (n), :class:`numpy.ndarray`
+        The bin centers.
+    gamma : (n) or (d, n), :class:`numpy.ndarray`
+        The estimated variogram values at bin centers.
+        Is stacked if multiple `directions` (d>1) are given.
+    counts : (n) or (d, n), :class:`numpy.ndarray`, optional
+        The number of point pairs found for each bin.
+        Is stacked if multiple `directions` (d>1) are given.
+        Only provided if `return_counts` is True.
+    normalizer : :any:`Normalizer`, optional
+        The fitted normalizer for the given data.
+        Only provided if `fit_normalizer` is True.
 
     Notes
     -----
@@ -321,12 +328,14 @@ def vario_estimate(
         bin_edges = standard_bins(pos, dim, latlon)
         bin_centres = (bin_edges[:-1] + bin_edges[1:]) / 2.0
     # normalize field
-    field = remove_trend_norm_mean(
+    norm_field_out = remove_trend_norm_mean(
         *(pos, field, mean, normalizer, trend),
         check_shape=False,
         stacked=True,
         fit_normalizer=fit_normalizer,
     )
+    field = norm_field_out[0] if fit_normalizer else norm_field_out
+    norm_out = (norm_field_out[1],) if fit_normalizer else ()
     # select variogram estimator
     cython_estimator = _set_estimator(estimator)
     # run
@@ -355,9 +364,8 @@ def vario_estimate(
         )
         if dir_no == 1:
             estimates, counts = estimates[0], counts[0]
-    if return_counts:
-        return bin_centres, estimates, counts
-    return bin_centres, estimates
+    est_out = (estimates, counts)
+    return (bin_centres,) + est_out[: 2 if return_counts else 1] + norm_out
 
 
 def vario_estimate_axis(

tests/test_normalize.py

@@ -204,14 +204,14 @@ def test_auto_fit(self):
             places=4,
         )
         # test fitting during vario estimate
-        emp_vario = gs.vario_estimate(
+        bin_center, gamma, normalizer = gs.vario_estimate(
             cond_pos,
             cond_val,
             normalizer=gs.normalizer.BoxCox,
             fit_normalizer=True,
         )
         model = gs.Stable(dim=2)
-        model.fit_variogram(*emp_vario)
+        model.fit_variogram(bin_center, gamma)
         self.assertAlmostEqual(model.var, 0.6426670183, places=4)
         self.assertAlmostEqual(model.len_scale, 9.635193952, places=4)
         self.assertAlmostEqual(model.nugget, 0.001617908408, places=4)