Updated sill descriptions in documentation, updated spatial dependenc…

CHANGELOG.rst

@@ -1,8 +1,8 @@
 Changes - from version >= 1.x
 =============================
 
-2025-0
-------
+2025-10-11
+----------
 
 **version 1.1.0**
 
@@ -12,6 +12,7 @@ Changes - from version >= 1.x
 * [docs] updated missing DOI in Indicator Variogram
 * [enhancement] representative point in `Blocks` is sampled from the largest `Polygon` when `MultiPolygon` is passed
 * [enhancement] `Blocks` object might be altered during CRS transformation or new object might be created (`inplace` parameter and copying mechanism)
+* [bug] incosistent documenation - `sill` represents *partial sill*, not *total sill*, and documentation might be misleading
 
 2025-07-17
 ----------

README.md

@@ -2,7 +2,7 @@
 
 # Pyinterpolate
 
-**version 1.0.3**
+**version 1.1.0**
 
 ![Logo](pyinterpolate-banner.png)
 

docs/build/html/_modules/pyinterpolate/core/data_models/blocks.html

@@ -434,6 +434,7 @@ <h1>Source code for pyinterpolate.core.data_models.blocks</h1><div class="highli
 <span class="sd">- Package doesn&#39;t read data files, data must be loaded into DataFrame and</span>
 <span class="sd">  then passed into the Blocks object.</span>
 <span class="sd">&quot;&quot;&quot;</span>
+<span class="kn">import</span> <span class="nn">copy</span>
 <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Union</span><span class="p">,</span> <span class="n">Hashable</span><span class="p">,</span> <span class="n">Dict</span>
 <span class="kn">from</span> <span class="nn">numpy.typing</span> <span class="kn">import</span> <span class="n">ArrayLike</span>
 
@@ -927,10 +928,9 @@ <h1>Source code for pyinterpolate.core.data_models.blocks</h1><div class="highli
                 <span class="k">return</span> <span class="n">df</span><span class="o">.</span><span class="n">loc</span><span class="p">[</span><span class="n">block_id</span><span class="p">,</span> <span class="n">other_blocks</span><span class="p">]</span></div>
 
 
-    <span class="c1"># TODO manage copying and inplace transformations</span>
 <div class="viewcode-block" id="Blocks.transform_crs">
 <a class="viewcode-back" href="../../../../api/core/core.html#pyinterpolate.Blocks.transform_crs">[docs]</a>
-    <span class="k">def</span> <span class="nf">transform_crs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">target_crs</span><span class="p">):</span>
+    <span class="k">def</span> <span class="nf">transform_crs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">target_crs</span><span class="p">,</span> <span class="n">inplace</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Function transforms Blocks CRS</span>
 
 <span class="sd">        Parameters</span>
@@ -940,23 +940,46 @@ <h1>Source code for pyinterpolate.core.data_models.blocks</h1><div class="highli
 <span class="sd">            :meth:`pyproj.CRS.from_user_input()</span>
 <span class="sd">            &lt;pyproj.crs.CRS.from_user_input&gt;`,</span>
 <span class="sd">            such as an authority string (eg &quot;EPSG:4326&quot;) or a WKT string.</span>
+
+<span class="sd">        inplace : bool, default = True</span>
+<span class="sd">            When set to `True` then transform object&#39;s instance on the fly,</span>
+<span class="sd">            otherwise return modified object and do leave the old instance</span>
+<span class="sd">            unchanged.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="c1"># Transform core dataset</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">ds</span><span class="o">.</span><span class="n">to_crs</span><span class="p">(</span><span class="n">target_crs</span><span class="p">,</span> <span class="n">inplace</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">inplace</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">ds</span><span class="o">.</span><span class="n">to_crs</span><span class="p">(</span><span class="n">target_crs</span><span class="p">,</span> <span class="n">inplace</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
 
-        <span class="c1"># representative points</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_get_representative_points</span><span class="p">()</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_points_to_floats</span><span class="p">()</span>
+            <span class="c1"># representative points</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_get_representative_points</span><span class="p">()</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_points_to_floats</span><span class="p">()</span>
 
-        <span class="c1"># distances</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">distances</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">calculate_distances_between_rep_points</span><span class="p">(</span>
-            <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
-        <span class="p">)</span>
+            <span class="c1"># distances</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">distances</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">calculate_distances_between_rep_points</span><span class="p">(</span>
+                <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
+            <span class="p">)</span>
+
+            <span class="c1"># angles</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">angles</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">calculate_angles_between_rep_points</span><span class="p">(</span>
+                <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
+            <span class="p">)</span>
+            <span class="k">return</span> <span class="kc">None</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">new_object</span> <span class="o">=</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
+
+            <span class="n">new_object</span><span class="o">.</span><span class="n">ds</span><span class="o">.</span><span class="n">to_crs</span><span class="p">(</span><span class="n">target_crs</span><span class="p">,</span> <span class="n">inplace</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+            <span class="n">new_object</span><span class="o">.</span><span class="n">_get_representative_points</span><span class="p">()</span>
+            <span class="n">new_object</span><span class="o">.</span><span class="n">_points_to_floats</span><span class="p">()</span>
+
+            <span class="n">new_object</span><span class="o">.</span><span class="n">distances</span> <span class="o">=</span> <span class="n">new_object</span><span class="o">.</span><span class="n">calculate_distances_between_rep_points</span><span class="p">(</span>
+                <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
+            <span class="p">)</span>
+
+            <span class="n">new_object</span><span class="o">.</span><span class="n">angles</span> <span class="o">=</span> <span class="n">new_object</span><span class="o">.</span><span class="n">calculate_angles_between_rep_points</span><span class="p">(</span>
+                <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
+            <span class="p">)</span>
 
-        <span class="c1"># angles</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">angles</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">calculate_angles_between_rep_points</span><span class="p">(</span>
-            <span class="n">update</span><span class="o">=</span><span class="kc">False</span>
-        <span class="p">)</span></div>
+            <span class="k">return</span> <span class="n">new_object</span></div>
 
 
     <span class="k">def</span> <span class="nf">_delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">block_index</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Hashable</span><span class="p">]):</span>

docs/build/html/_modules/pyinterpolate/kriging/point/ordinary.html

@@ -7,7 +7,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>pyinterpolate.kriging.point.ordinary &#8212; pyinterpolate 1.0.2 documentation</title>
+    <title>pyinterpolate.kriging.point.ordinary &#8212; pyinterpolate 1.1.0 documentation</title>
 
 
 
@@ -38,7 +38,7 @@
   <link rel="preload" as="script" href="../../../../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="../../../../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="../../../../_static/documentation_options.js?v=1ed6394b"></script>
+    <script src="../../../../_static/documentation_options.js?v=fc837d61"></script>
     <script src="../../../../_static/doctools.js?v=9bcbadda"></script>
     <script src="../../../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../../../_static/clipboard.min.js?v=a7894cd8"></script>
@@ -111,7 +111,7 @@
 
 
 
-    <p class="title logo__title">pyinterpolate 1.0.2 documentation</p>
+    <p class="title logo__title">pyinterpolate 1.1.0 documentation</p>
 
 </a></div>
 
@@ -665,7 +665,7 @@ <h1>Source code for pyinterpolate.kriging.point.ordinary</h1><div class="highlig
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
 <span class="sd">    theoretical_model : TheoreticalVariogram</span>
-<span class="sd">        A trained theoretical variogram model.</span>
+<span class="sd">        Fitted theoretical variogram model.</span>
 
 <span class="sd">    known_locations : numpy array</span>
 <span class="sd">        The known locations: ``[x, y, value]``.</span>
@@ -674,7 +674,9 @@ <h1>Source code for pyinterpolate.kriging.point.ordinary</h1><div class="highlig
 <span class="sd">        Point where you want to estimate value ``(x, y) &lt;-&gt; (lon, lat)``.</span>
 
 <span class="sd">    sill : float</span>
-<span class="sd">        The sill (``c(0)``) of a dataset.</span>
+<span class="sd">        Partial sill, or sill when nugget is set to zero. Total sill is a sum</span>
+<span class="sd">        of partial sill and nugget. If given, then partial sill is fixed to</span>
+<span class="sd">        this value.</span>
 
 <span class="sd">    neighbors_range : float, default=None</span>
 <span class="sd">        The maximum distance where we search for neighbors. If ``None`` is</span>

docs/build/html/_modules/pyinterpolate/semivariogram/indicator/indicator.html

@@ -810,7 +810,9 @@ <h1>Source code for pyinterpolate.semivariogram.indicator.indicator</h1><div cla
 <span class="sd">            ``min_range`` and ``max_range``.</span>
 
 <span class="sd">        sill : float, default = None</span>
-<span class="sd">            If given, then sill is fixed to this value.</span>
+<span class="sd">            Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">            a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">            is fixed to this value.</span>
 
 <span class="sd">        n_sill_values : int, default = 5</span>
 <span class="sd">            The last n experimental semivariance records for sill estimation.</span>
@@ -819,17 +821,13 @@ <h1>Source code for pyinterpolate.semivariogram.indicator.indicator</h1><div cla
 <span class="sd">        sill_from_variance : bool, default = False</span>
 <span class="sd">            Estimate sill from the variance (semivariance at distance 0).</span>
 
-<span class="sd">        min_sill : float, default = 1</span>
-<span class="sd">            The minimal fraction of the value chosen with the sill estimation</span>
-<span class="sd">            method. The value is: for ``sill_from_values`` - the mean of</span>
-<span class="sd">            the last ``n_sill_values`` number of experimental semivariances,</span>
-<span class="sd">            for ``sill_from_variance`` - the experimental variogram variance.</span>
-
-<span class="sd">        max_sill : float, default = 5</span>
-<span class="sd">            The maximum fraction of the value chosen with the sill estimation</span>
-<span class="sd">            method. The value is: for ``sill_from_values`` - the mean of</span>
-<span class="sd">            the last ``n_sill_values`` number of experimental semivariances,</span>
-<span class="sd">            for ``sill_from_variance`` - the experimental variogram variance.</span>
+<span class="sd">        min_sill : float, default = 0.5</span>
+<span class="sd">            The minimal fraction of the variogram variance at lag 0 to</span>
+<span class="sd">            find partial sill, ``0 &lt;= min_sill &lt;= max_sill``.</span>
+
+<span class="sd">        max_sill : float, default = 2</span>
+<span class="sd">            The maximum fraction of the variogram variance at lag 0 to find</span>
+<span class="sd">            partial sill.</span>
 
 <span class="sd">        number_of_sills : int, default = 16</span>
 <span class="sd">            How many equally spaced sill values are tested between</span>

docs/build/html/_modules/pyinterpolate/semivariogram/theoretical/classes/theoretical_variogram.html

@@ -7,7 +7,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>pyinterpolate.semivariogram.theoretical.classes.theoretical_variogram &#8212; pyinterpolate 1.0.2 documentation</title>
+    <title>pyinterpolate.semivariogram.theoretical.classes.theoretical_variogram &#8212; pyinterpolate 1.1.0 documentation</title>
 
 
 
@@ -38,7 +38,7 @@
   <link rel="preload" as="script" href="../../../../../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="../../../../../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="../../../../../_static/documentation_options.js?v=1ed6394b"></script>
+    <script src="../../../../../_static/documentation_options.js?v=fc837d61"></script>
     <script src="../../../../../_static/doctools.js?v=9bcbadda"></script>
     <script src="../../../../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../../../../_static/clipboard.min.js?v=a7894cd8"></script>
@@ -111,7 +111,7 @@
 
 
 
-    <p class="title logo__title">pyinterpolate 1.0.2 documentation</p>
+    <p class="title logo__title">pyinterpolate 1.1.0 documentation</p>
 
 </a></div>
 
@@ -478,8 +478,9 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">        The nugget parameter (bias at the zero distance).</span>
 
 <span class="sd">    sill : float, default=0</span>
-<span class="sd">        A value at which dissimilarity is close to its maximum if model is</span>
-<span class="sd">        bounded. Otherwise, it is usually close to the observations variance.</span>
+<span class="sd">       Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">       a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">       is fixed to this value.</span>
 
 <span class="sd">    rang : float, default=0</span>
 <span class="sd">        The semivariogram range is a distance at which spatial correlation</span>
@@ -649,8 +650,9 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">            - &#39;spherical&#39;.</span>
 
 <span class="sd">        sill : float, default=0</span>
-<span class="sd">            A value at which dissimilarity is close to its maximum if model is</span>
-<span class="sd">            bounded. Otherwise, it is usually close to observations variance.</span>
+<span class="sd">            Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">            a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">            is fixed to this value.</span>
 
 <span class="sd">        rang : float, default=0</span>
 <span class="sd">            The semivariogram range is a distance at which spatial correlation</span>
@@ -788,7 +790,9 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">            ``min_range`` and ``max_range``.</span>
 
 <span class="sd">        sill : float, default = None</span>
-<span class="sd">            If given, then sill is fixed to this value.</span>
+<span class="sd">            Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">            a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">            is fixed to this value.</span>
 
 <span class="sd">        n_sill_values : int, default = 5</span>
 <span class="sd">            The last n experimental semivariance records for sill estimation.</span>
@@ -797,13 +801,13 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">        sill_from_variance : bool, default = False</span>
 <span class="sd">            Estimate sill from the variance (semivariance at distance 0).</span>
 
-<span class="sd">        min_sill : float, default = 1</span>
+<span class="sd">        min_sill : float, default = 0.5</span>
 <span class="sd">            The minimal fraction of the value chosen with the sill estimation</span>
 <span class="sd">            method. The value is: for ``sill_from_values`` - the mean of</span>
 <span class="sd">            the last ``n_sill_values`` number of experimental semivariances,</span>
 <span class="sd">            for ``sill_from_variance`` - the experimental variogram variance.</span>
 
-<span class="sd">        max_sill : float, default = 5</span>
+<span class="sd">        max_sill : float, default = 2</span>
 <span class="sd">            The maximum fraction of the value chosen with the sill estimation</span>
 <span class="sd">            method. The value is: for ``sill_from_values`` - the mean of</span>
 <span class="sd">            the last ``n_sill_values`` number of experimental semivariances,</span>
@@ -1370,6 +1374,9 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">        nugget : float</span>
 
 <span class="sd">        sill : float</span>
+<span class="sd">            Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">            a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">            is fixed to this value.</span>
 
 <span class="sd">        rang : float</span>
 
@@ -1468,7 +1475,9 @@ <h1>Source code for pyinterpolate.semivariogram.theoretical.classes.theoretical_
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
 <span class="sd">        sill : float, optional</span>
-<span class="sd">            Baseline sill.</span>
+<span class="sd">            Partial sill, or sill when nugget is set to zero. Total sill is</span>
+<span class="sd">            a sum of partial sill and nugget. If given, then partial sill</span>
+<span class="sd">            is fixed to this value.</span>
 
 <span class="sd">        n_sill_values : int, default=5</span>
 <span class="sd">            Number of the last N experimental semivariances to use for sill</span>