Add new data encapsulation

examples/03_variogram/README.rst

@@ -1,3 +1,5 @@
+.. _tutorial_03_variogram:
+
 Tutorial 3: Variogram Estimation
 ================================
 

examples/08_mesh/00_mesh_intro.py

@@ -0,0 +1,75 @@
+"""
+Example: Using a mesh for GSTools
+---------------------------------
+
+This example shows how external data can be analysed with GSTools.
+
+
+Pretending we have some Data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We will pretend that we have some external data, by creating some random data
+with GSTools, but we will delete the objects and only use the data, without the
+backend GSTools provides.
+"""
+from datetime import date
+import numpy as np
+import gstools as gs
+
+# create a circular mesh
+point_no = 10000
+rng = np.random.RandomState(20170521)
+r = 50.0 * np.sqrt(rng.uniform(size=point_no))
+theta = 2.0 * np.pi * rng.uniform(size=point_no)
+x = r * np.cos(theta)
+y = r * np.sin(theta)
+
+tmp_model = gs.Exponential(dim=2, var=1.5, len_scale=10.0)
+tmp_srf = gs.SRF(tmp_model)
+field = tmp_srf((x, y))
+tmp_srf.plot()
+
+# Now that we have our data, let's delete everything GSTools related and pretend
+# that this has never happend
+del(tmp_model)
+del(tmp_srf)
+
+
+# Creating the Mesh
+# ^^^^^^^^^^^^^^^^^
+#
+# Starting out fresh, we want to feed the mesh with our data
+mesh = gs.Mesh(2, pos=(x, y), values=field)
+
+# We can add meta data too
+mesh.set_field_data("Süderbrarup", "location")
+mesh.set_field_data(date(year=2020, month=2, day=28), "date")
+
+# This can be conviniently accessed
+print(mesh.location)
+print(mesh.date)
+
+# But the meta data is also collected as a dictionary in case you want to export
+# it
+print(mesh.field_data)
+
+
+# Estimating the Variogram
+# ^^^^^^^^^^^^^^^^^^^^^^^^
+# Now, with our mesh, which was loaded from completely external sources, we can
+# estimate the variogram of the data.
+# To speed things up, we will only use a fraction of the available data
+
+bins = np.linspace(0, 50, 50)
+bin_centre, gamma = gs.vario_estimate_unstructured(
+    (x, y), field, bins, sampling_size=2000, sampling_seed=19900408)
+
+# As we are experts, we'll do an expert guess and say, that we will most likely
+# have data that has an exponential variogram. Non-experts can have a look at
+# the "Finding the best fitting variogram model" tutorial in
+# :ref:`tutorial_03_variogram`.
+fit_model = gs.Exponential(dim=2)
+fit_model.fit_variogram(bin_centre, gamma, nugget=False)
+
+ax = fit_model.plot(x_max=max(bin_centre))
+ax.plot(bin_centre, gamma)

examples/08_mesh/README.rst

@@ -0,0 +1,12 @@
+.. _tutorial_08_mesh:
+
+Tutorial 8: Working With Meshes
+===============================
+
+In case you have external data, which does not come from the spatial random
+generation or similar methods of GSTools and you want to analyse this data, e.g.
+estimate the variogram, you can load the data into a mesh class and conveniently
+manipulate, analyse, visualise, and export the data with GSTools.
+
+Gallery
+-------

gstools/__init__.py

@@ -33,6 +33,8 @@
 
 .. autosummary::
    SRF
+   Field
+   Mesh
 
 Covariance Base-Class
 ^^^^^^^^^^^^^^^^^^^^^
@@ -100,6 +102,7 @@
 """
 
 from gstools import field, variogram, random, covmodel, tools, krige, transform
+from gstools.field.mesh import Mesh
 from gstools.field import SRF
 from gstools.tools import (
     vtk_export,

gstools/field/__init__.py

@@ -17,10 +17,14 @@
 
 .. autosummary::
    SRF
+   Field
+   Mesh
 
 ----
 """
 
+from gstools.field.mesh import Mesh
+from gstools.field.base import Field
 from gstools.field.srf import SRF
 
-__all__ = ["SRF"]
+__all__ = ["SRF", "Field", "Mesh"]