apply intrinsic method added and more math annotations

Author: n0228a

src/gstools/cokriging/base.py

@@ -27,9 +27,10 @@ class CollocatedCokriging(Krige):
 
     Both variants assume the cross-covariance follows:
 
-        C_YZ(h) = ρ_YZ(0) · √(C_Z(h) · C_Y(h))
+    .. math::
+       C_{YZ}(h) = \\rho_{YZ}(0) \\cdot \\sqrt{C_Z(h) \\cdot C_Y(h)}
 
-    where ρ_YZ(0) is the cross-correlation at zero lag. This assumption
+    where :math:`\\rho_{YZ}(0)` is the cross-correlation at zero lag. This assumption
     requires that primary and secondary variables have similar spatial
     correlation structures. Violations of MM1 can lead to suboptimal
     estimates and unreliable variance.
@@ -38,11 +39,11 @@ class CollocatedCokriging(Krige):
 
     - **Simple Collocated** ("simple"):
       Uses only collocated secondary at estimation point. Simpler but
-      may show variance inflation (σ²_SCCK > σ²_SK).
+      may show variance inflation :math:`\\sigma^2_{\\text{SCCK}} > \\sigma^2_{\\text{SK}}`.
 
     - **Intrinsic Collocated** ("intrinsic"):
       Uses collocated secondary plus secondary at all primary locations.
-      Provides accurate variance: σ²_ICCK = (1-ρ₀²)·σ²_SK ≤ σ²_SK.
+      Provides accurate variance: :math:`\\sigma^2_{\\text{ICCK}} = (1-\\rho_0^2) \\cdot \\sigma^2_{\\text{SK}} \\leq \\sigma^2_{\\text{SK}}`.
 
     Parameters
     ----------
@@ -235,27 +236,13 @@ def __call__(self, pos=None, secondary_data=None, **kwargs):
         sk_field, sk_var = super().__call__(pos=pos, **kwargs_with_var)
         secondary_data = np.asarray(secondary_data, dtype=np.double)
 
+        # apply algorithm-specific post-processing
         if self.algorithm == "simple":
             cokriging_field, cokriging_var = self._apply_simple_collocated(
                 sk_field, sk_var, secondary_data, user_return_var)
         elif self.algorithm == "intrinsic":
-            # apply collocated secondary contribution
-            collocated_contribution = self._lambda_Y0 * (
-                secondary_data - self.secondary_mean)
-            cokriging_field = sk_field + collocated_contribution
-
-            # compute intrinsic variance
-            if user_return_var:
-                C_Z0, C_Y0, C_YZ0 = self._compute_covariances()
-                if C_Y0 * C_Z0 < 1e-15:
-                    rho_squared = 0.0
-                else:
-                    rho_squared = (C_YZ0**2) / (C_Y0 * C_Z0)
-                icck_var = (1.0 - rho_squared) * sk_var
-                icck_var = np.maximum(0.0, icck_var)
-                cokriging_var = icck_var
-            else:
-                cokriging_var = None
+            cokriging_field, cokriging_var = self._apply_intrinsic_collocated(
+                sk_field, sk_var, secondary_data, user_return_var)
         else:
             raise ValueError(f"Unknown algorithm: {self.algorithm}")
 
@@ -292,6 +279,34 @@ def _apply_simple_collocated(self, sk_field, sk_var, secondary_data, return_var)
             scck_variance = None
         return scck_field, scck_variance
 
+    def _apply_intrinsic_collocated(self, sk_field, sk_var, secondary_data, return_var):
+        """
+        Apply intrinsic collocated cokriging.
+
+        Adds the collocated secondary contribution at estimation locations
+        and computes ICCK variance.
+
+        Note: The secondary-at-primary contribution is already added during
+        the kriging solve in _summate().
+        """
+        # apply collocated secondary contribution
+        collocated_contribution = self._lambda_Y0 * (
+            secondary_data - self.secondary_mean)
+        icck_field = sk_field + collocated_contribution
+
+        # compute intrinsic variance
+        if return_var:
+            C_Z0, C_Y0, C_YZ0 = self._compute_covariances()
+            if C_Y0 * C_Z0 < 1e-15:
+                rho_squared = 0.0
+            else:
+                rho_squared = (C_YZ0**2) / (C_Y0 * C_Z0)
+            icck_var = (1.0 - rho_squared) * sk_var
+            icck_var = np.maximum(0.0, icck_var)
+        else:
+            icck_var = None
+        return icck_field, icck_var
+
     def _summate(self, field, krige_var, c_slice, k_vec, return_var):
         """Apply intrinsic collocated cokriging during kriging solve."""
         if self.algorithm == "simple":

src/gstools/cokriging/methods.py

@@ -76,11 +76,11 @@ class SimpleCollocated(CollocatedCokriging):
     secondary_var : :class:`float`
         Variance of the secondary variable. Must be positive.
     mean : :class:`float`, optional
-        Mean value for simple kriging (primary variable mean m_Z). Default: 0.0
+        Mean value for simple kriging (primary variable mean :math:`m_Z`). Default: 0.0
     secondary_mean : :class:`float`, optional
-        Mean value of the secondary variable (m_Y).
+        Mean value of the secondary variable (:math:`m_Y`).
         Required for simple collocated cokriging to properly handle
-        the anomaly-space formulation: Y(u) - m_Y.
+        the anomaly-space formulation: :math:`Y(u) - m_Y`.
         Default: 0.0
     normalizer : :any:`None` or :any:`Normalizer`, optional
         Normalizer to be applied to the input data to gain normality.
@@ -242,11 +242,11 @@ class IntrinsicCollocated(CollocatedCokriging):
     secondary_var : :class:`float`
         Variance of the secondary variable. Must be positive.
     mean : :class:`float`, optional
-        Mean value for simple kriging (primary variable mean m_Z). Default: 0.0
+        Mean value for simple kriging (primary variable mean :math:`m_Z`). Default: 0.0
     secondary_mean : :class:`float`, optional
-        Mean value of the secondary variable (m_Y).
+        Mean value of the secondary variable (:math:`m_Y`).
         Required for intrinsic collocated cokriging to properly handle
-        the anomaly-space formulation: Y(u) - m_Y.
+        the anomaly-space formulation: :math:`Y(u) - m_Y`.
         Default: 0.0
     normalizer : :any:`None` or :any:`Normalizer`, optional
         Normalizer to be applied to the input data to gain normality.