589427110

Build Type

github

Committed by GitHub

Commit Message

<a href="https://github.com/GeoStat-Framework/GSTools/commit/<a class=hub.com/GeoStat-Framework/GSTools/commit/c4502892c98f564b28ee5c682876f2d43f8e322c">c4502892c<a href="https://github.com/GeoStat-Framework/GSTools/commit/c4502892c98f564b28ee5c682876f2d43f8e322c">">Merge </a><a class="double-link" href="https://github.com/GeoStat-Framework/GSTools/commit/<a class="double-link" href="https://github.com/GeoStat-Framework/GSTools/commit/7f4af3cea143ee62d1c743400b88d239b260c64e">7f4af3cea</a>">7f4af3cea</a><a href="https://github.com/GeoStat-Framework/GSTools/commit/c4502892c98f564b28ee5c682876f2d43f8e322c"> into f8e6339a0">f8e6339a0</a>

Pull Request Pull Request #124: Mean, Normalizer, Trend and Fitting

Run Details

522 of 522 new or added lines in 14 files covered. (100.0%)

2450 of 2702 relevant lines covered (90.67%)

13.6 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

93.55

/gstools/field/base.py

# -*- coding: utf-8 -*-
"""
GStools subpackage providing a base class for spatial fields.

.. currentmodule:: gstools.field.base

The following classes are provided

.. autosummary::
   Field
"""
# pylint: disable=C0103
from functools import partial
import numpy as np
from gstools.covmodel.base import CovModel
from gstools.tools.geometric import format_struct_pos_dim, gen_mesh
from gstools.field.tools import mesh_call, to_vtk_helper, fmt_mean_norm_trend
from gstools.normalizer.tools import apply_mean_norm_trend, _check_normalizer

__all__ = ["Field"]

VALUE_TYPES = ["scalar", "vector"]
""":class:`list` of :class:`str`: valid field value types."""


def _set_mean_trend(value, dim):
    if callable(value) or value is None:
        return value
    value = np.array(value, dtype=np.double).ravel()
    if value.size > 1 and value.size != dim:  # vector mean
        raise ValueError("Mean/Trend: Wrong size ({})".format(value))
    return value if value.size > 1 else value.item()


class Field:
    """A base class for random fields, kriging fields, etc.

    Parameters
    ----------
    model : :any:`CovModel`
        Covariance Model related to the field.
    value_type : :class:`str`, optional
        Value type of the field. Either "scalar" or "vector".
        The default is "scalar".
    mean : :any:`None` or :class:`float` or :any:`callable`, optional
        Mean of the field if wanted. Could also be a callable.
        The default is None.
    normalizer : :any:`None` or :any:`Normalizer`, optional
        Normalizer to be applied to the field.
        The default is None.
    trend : :any:`None` or :class:`float` or :any:`callable`, optional
        Trend of the denormalized fields. If no normalizer is applied,
        this behaves equal to 'mean'.
        The default is None.
    """

    def __init__(
        self,
        model,
        value_type="scalar",
        mean=None,
        normalizer=None,
        trend=None,
    ):
        # initialize attributes
        self.pos = None
        self.mesh_type = None
        self.field = None
        # initialize private attributes
        self._model = None
        self._value_type = None
        self._mean = None
        self._normalizer = None
        self._trend = None
        # set properties
        self.model = model
        self.value_type = value_type
        self.mean = mean
        self.normalizer = normalizer
        self.trend = trend

    def __call__(*args, **kwargs):
        """Generate the field."""
        pass

    def structured(self, *args, **kwargs):
        """Generate a field on a structured mesh.

        See :any:`Field.__call__`
        """
        call = partial(self.__call__, mesh_type="structured")
        return call(*args, **kwargs)

    def unstructured(self, *args, **kwargs):
        """Generate a field on an unstructured mesh.

        See :any:`Field.__call__`
        """
        call = partial(self.__call__, mesh_type="unstructured")
        return call(*args, **kwargs)

    def mesh(
        self, mesh, points="centroids", direction="all", name="field", **kwargs
    ):
        """Generate a field on a given meshio or ogs5py mesh.

        Parameters
        ----------
        mesh : meshio.Mesh or ogs5py.MSH or PyVista mesh
            The given meshio, ogs5py, or PyVista mesh
        points : :class:`str`, optional
            The points to evaluate the field at.
            Either the "centroids" of the mesh cells
            (calculated as mean of the cell vertices) or the "points"
            of the given mesh.
            Default: "centroids"
        direction : :class:`str` or :class:`list`, optional
            Here you can state which direction should be choosen for
            lower dimension. For example, if you got a 2D mesh in xz direction,
            you have to pass "xz". By default, all directions are used.
            One can also pass a list of indices.
            Default: "all"
        name : :class:`str` or :class:`list` of :class:`str`, optional
            Name(s) to store the field(s) in the given mesh as point_data or
            cell_data. If to few names are given, digits will be appended.
            Default: "field"
        **kwargs
            Keyword arguments forwareded to `Field.__call__`.

        Notes
        -----
        This will store the field in the given mesh under the given name,
        if a meshio or PyVista mesh was given.

        See: https://github.com/nschloe/meshio
        See: https://github.com/pyvista/pyvista

        See: :any:`Field.__call__`
        """
        return mesh_call(self, mesh, points, direction, name, **kwargs)

    def pre_pos(self, pos, mesh_type="unstructured"):
        """
        Preprocessing positions and mesh_type.

        Parameters
        ----------
        pos : :any:`iterable`
            the position tuple, containing main direction and transversal
            directions
        mesh_type : :class:`str`, optional
            'structured' / 'unstructured'
            Default: `"unstructured"`

        Returns
        -------
        iso_pos : (d, n), :class:`numpy.ndarray`
            the isometrized position tuple
        shape : :class:`tuple`
            Shape of the resulting field.
        """
        # save mesh-type
        self.mesh_type = mesh_type
        # save pos tuple
        if mesh_type != "unstructured":
            pos, shape = format_struct_pos_dim(pos, self.dim)
            self.pos = pos
            pos = gen_mesh(pos)
        else:
            pos = np.array(pos, dtype=np.double).reshape(self.dim, -1)
            self.pos = pos
            shape = np.shape(pos[0])
        # prepend dimension if we have a vector field
        if self.value_type == "vector":
            shape = (self.dim,) + shape
            if self.model.latlon:
                raise ValueError("Field: Vector fields not allowed for latlon")
        # return isometrized pos tuple and resulting field shape
        return self.model.isometrize(pos), shape

    def post_field(self, field, name="field", process=True, save=True):
        """
        Postprocessing field values.

        Parameters
        ----------
        field : :class:`numpy.ndarray`
            Field values.
        name : :class:`str`, optional
            Name. to store the field.
            The default is "field".
        process : :class:`bool`, optional
            Whether to process field to apply mean, normalizer and trend.
            The default is True.
        save : :class:`bool`, optional
            Whether to store the field under the given name.
            The default is True.

        Returns
        -------
        field : :class:`numpy.ndarray`
            Processed field values.
        """
        if process:
            if self.pos is None:
                raise ValueError("post_field: no 'pos' tuple set for field.")
            field = apply_mean_norm_trend(
                pos=self.pos,
                field=field,
                mesh_type=self.mesh_type,
                value_type=self.value_type,
                mean=self.mean,
                normalizer=self.normalizer,
                trend=self.trend,
                check_shape=False,
                stacked=False,
            )
        if save:
            setattr(self, name, field)
        return field

    def to_pyvista(
        self, field_select="field", fieldname="field"
    ):  # pragma: no cover
        """Create a VTK/PyVista grid of the stored field.

        Parameters
        ----------
        field_select : :class:`str`, optional
            Field that should be stored. Can be:
            "field", "raw_field", "krige_field", "err_field" or "krige_var".
            Default: "field"
        fieldname : :class:`str`, optional
            Name of the field in the VTK file. Default: "field"
        """
        grid = to_vtk_helper(
            self, filename=None, field_select=field_select, fieldname=fieldname
        )
        return grid

    def vtk_export(
        self, filename, field_select="field", fieldname="field"
    ):  # pragma: no cover
        """Export the stored field to vtk.

        Parameters
        ----------
        filename : :class:`str`
            Filename of the file to be saved, including the path. Note that an
            ending (.vtr or .vtu) will be added to the name.
        field_select : :class:`str`, optional
            Field that should be stored. Can be:
            "field", "raw_field", "krige_field", "err_field" or "krige_var".
            Default: "field"
        fieldname : :class:`str`, optional
            Name of the field in the VTK file. Default: "field"
        """
        if not isinstance(filename, str):
            raise TypeError("Please use a string filename.")
        return to_vtk_helper(
            self,
            filename=filename,
            field_select=field_select,
            fieldname=fieldname,
        )

    def plot(self, field="field", fig=None, ax=None):  # pragma: no cover
        """
        Plot the spatial random field.

        Parameters
        ----------
        field : :class:`str`, optional
            Field that should be plotted.
            Default: "field"
        fig : :class:`Figure` or :any:`None`
            Figure to plot the axes on. If `None`, a new one will be created.
            Default: `None`
        ax : :class:`Axes` or :any:`None`
            Axes to plot on. If `None`, a new one will be added to the figure.
            Default: `None`
        """
        # just import if needed; matplotlib is not required by setup
        from gstools.field.plot import plot_field, plot_vec_field

        if self.value_type is None:
            raise ValueError(
                "Field value type not set! "
                "Specify 'scalar' or 'vector' before plotting."
            )

        elif self.value_type == "scalar":
            r = plot_field(self, field, fig, ax)

        elif self.value_type == "vector":
            if self.model.dim == 2:
                r = plot_vec_field(self, field, fig, ax)
            else:
                raise NotImplementedError(
                    "Streamflow plotting only supported for 2d case."
                )
        else:
            raise ValueError(
                "Unknown field value type: {}".format(self.value_type)
            )

        return r

    @property
    def model(self):
        """:any:`CovModel`: The covariance model of the field."""
        return self._model

    @model.setter
    def model(self, model):
        if isinstance(model, CovModel):
            self._model = model
        else:
            raise ValueError(
                "Field: 'model' is not an instance of 'gstools.CovModel'"
            )

    @property
    def mean(self):
        """:class:`float` or :any:`callable`: The mean of the field."""
        return self._mean

    @mean.setter
    def mean(self, mean):
        self._mean = _set_mean_trend(mean, self.dim)

    @property
    def normalizer(self):
        """:any:`Normalizer`: Normalizer of the field."""
        return self._normalizer

    @normalizer.setter
    def normalizer(self, normalizer):
        self._normalizer = _check_normalizer(normalizer)

    @property
    def trend(self):
        """:class:`float` or :any:`callable`: The trend of the field."""
        return self._trend

    @trend.setter
    def trend(self, trend):
        self._trend = _set_mean_trend(trend, self.dim)

    @property
    def value_type(self):
        """:class:`str`: Type of the field values (scalar, vector)."""
        return self._value_type

    @value_type.setter
    def value_type(self, value_type):
        if value_type not in VALUE_TYPES:
            raise ValueError("Field: value type not in {}".format(VALUE_TYPES))
        self._value_type = value_type

    @property
    def dim(self):
        """:class:`int`: Dimension of the field."""
        return self.model.field_dim

    @property
    def name(self):
        """:class:`str`: The name of the class."""
        return self.__class__.__name__

    def _fmt_mean_norm_trend(self):
        return fmt_mean_norm_trend(self)

    def __repr__(self):
        """Return String representation."""
        return "{0}(model={1}, value_type='{2}'{3})".format(
            self.name,
            self.model.name,
            self.value_type,
            self._fmt_mean_norm_trend(),
        )

1	# -- coding: utf-8 --
2	"""	15✔
3	GStools subpackage providing a base class for spatial fields.
4
5	.. currentmodule:: gstools.field.base
6
7	The following classes are provided
8
9	.. autosummary::
10	Field
11	"""
12	# pylint: disable=C0103
13	from functools import partial	15✔
14	import numpy as np	15✔
15	from gstools.covmodel.base import CovModel	15✔
16	from gstools.tools.geometric import format_struct_pos_dim, gen_mesh	15✔
17	from gstools.field.tools import mesh_call, to_vtk_helper, fmt_mean_norm_trend	15✔
18	from gstools.normalizer.tools import apply_mean_norm_trend, _check_normalizer	15✔
19
20	__all__ = ["Field"]	15✔
21
22	VALUE_TYPES = ["scalar", "vector"]	15✔
23	""":class:`list` of :class:`str`: valid field value types."""
24
25
26	def _set_mean_trend(value, dim):	15✔
27	if callable(value) or value is None:	15✔
28	return value	15✔
29	value = np.array(value, dtype=np.double).ravel()	15✔
30	if value.size > 1 and value.size != dim: # vector mean	15✔
31	raise ValueError("Mean/Trend: Wrong size ({})".format(value))	×
32	return value if value.size > 1 else value.item()	15✔
33
34
35	class Field:	15✔
36	"""A base class for random fields, kriging fields, etc.
37
38	Parameters
39	----------
40	model : :any:`CovModel`
41	Covariance Model related to the field.
42	value_type : :class:`str`, optional
43	Value type of the field. Either "scalar" or "vector".
44	The default is "scalar".
45	mean : :any:`None` or :class:`float` or :any:`callable`, optional
46	Mean of the field if wanted. Could also be a callable.
47	The default is None.
48	normalizer : :any:`None` or :any:`Normalizer`, optional
49	Normalizer to be applied to the field.
50	The default is None.
51	trend : :any:`None` or :class:`float` or :any:`callable`, optional
52	Trend of the denormalized fields. If no normalizer is applied,
53	this behaves equal to 'mean'.
54	The default is None.
55	"""
56
57	def __init__(	15✔
58	self,
59	model,
60	value_type="scalar",
61	mean=None,
62	normalizer=None,
63	trend=None,
64	):
65	# initialize attributes
66	self.pos = None	15✔
67	self.mesh_type = None	15✔
68	self.field = None	15✔
69	# initialize private attributes
70	self._model = None	15✔
71	self._value_type = None	15✔
72	self._mean = None	15✔
73	self._normalizer = None	15✔
74	self._trend = None	15✔
75	# set properties
76	self.model = model	15✔
77	self.value_type = value_type	15✔
78	self.mean = mean	15✔
79	self.normalizer = normalizer	15✔
80	self.trend = trend	15✔
81
82	def __call__(args, *kwargs):	15✔
83	"""Generate the field."""
84	pass	×
85
86	def structured(self, args, *kwargs):	15✔
87	"""Generate a field on a structured mesh.
88
89	See :any:`Field.__call__`
90	"""
91	call = partial(self.__call__, mesh_type="structured")	15✔
92	return call(args, *kwargs)	15✔
93
94	def unstructured(self, args, *kwargs):	15✔
95	"""Generate a field on an unstructured mesh.
96
97	See :any:`Field.__call__`
98	"""
99	call = partial(self.__call__, mesh_type="unstructured")	15✔
100	return call(args, *kwargs)	15✔
101
102	def mesh(	15✔
103	self, mesh, points="centroids", direction="all", name="field", **kwargs
104	):
105	"""Generate a field on a given meshio or ogs5py mesh.
106
107	Parameters
108	----------
109	mesh : meshio.Mesh or ogs5py.MSH or PyVista mesh
110	The given meshio, ogs5py, or PyVista mesh
111	points : :class:`str`, optional
112	The points to evaluate the field at.
113	Either the "centroids" of the mesh cells
114	(calculated as mean of the cell vertices) or the "points"
115	of the given mesh.
116	Default: "centroids"
117	direction : :class:`str` or :class:`list`, optional
118	Here you can state which direction should be choosen for
119	lower dimension. For example, if you got a 2D mesh in xz direction,
120	you have to pass "xz". By default, all directions are used.
121	One can also pass a list of indices.
122	Default: "all"
123	name : :class:`str` or :class:`list` of :class:`str`, optional
124	Name(s) to store the field(s) in the given mesh as point_data or
125	cell_data. If to few names are given, digits will be appended.
126	Default: "field"
127	**kwargs
128	Keyword arguments forwareded to `Field.__call__`.
129
130	Notes
131	-----
132	This will store the field in the given mesh under the given name,
133	if a meshio or PyVista mesh was given.
134
135	See: https://github.com/nschloe/meshio
136	See: https://github.com/pyvista/pyvista
137
138	See: :any:`Field.__call__`
139	"""
140	return mesh_call(self, mesh, points, direction, name, **kwargs)	15✔
141
142	def pre_pos(self, pos, mesh_type="unstructured"):	15✔
143	"""
144	Preprocessing positions and mesh_type.
145
146	Parameters
147	----------
148	pos : :any:`iterable`
149	the position tuple, containing main direction and transversal
150	directions
151	mesh_type : :class:`str`, optional
152	'structured' / 'unstructured'
153	Default: `"unstructured"`
154
155	Returns
156	-------
157	iso_pos : (d, n), :class:`numpy.ndarray`
158	the isometrized position tuple
159	shape : :class:`tuple`
160	Shape of the resulting field.
161	"""
162	# save mesh-type
163	self.mesh_type = mesh_type	15✔
164	# save pos tuple
165	if mesh_type != "unstructured":	15✔
166	pos, shape = format_struct_pos_dim(pos, self.dim)	15✔
167	self.pos = pos	15✔
168	pos = gen_mesh(pos)	15✔
169	else:
170	pos = np.array(pos, dtype=np.double).reshape(self.dim, -1)	15✔
171	self.pos = pos	15✔
172	shape = np.shape(pos[0])	15✔
173	# prepend dimension if we have a vector field
174	if self.value_type == "vector":	15✔
175	shape = (self.dim,) + shape	15✔
176	if self.model.latlon:	15✔
177	raise ValueError("Field: Vector fields not allowed for latlon")	×
178	# return isometrized pos tuple and resulting field shape
179	return self.model.isometrize(pos), shape	15✔
180
181	def post_field(self, field, name="field", process=True, save=True):	15✔
182	"""
183	Postprocessing field values.
184
185	Parameters
186	----------
187	field : :class:`numpy.ndarray`
188	Field values.
189	name : :class:`str`, optional
190	Name. to store the field.
191	The default is "field".
192	process : :class:`bool`, optional
193	Whether to process field to apply mean, normalizer and trend.
194	The default is True.
195	save : :class:`bool`, optional
196	Whether to store the field under the given name.
197	The default is True.
198
199	Returns
200	-------
201	field : :class:`numpy.ndarray`
202	Processed field values.
203	"""
204	if process:	15✔
205	if self.pos is None:	15✔
206	raise ValueError("post_field: no 'pos' tuple set for field.")	×
207	field = apply_mean_norm_trend(	15✔
208	pos=self.pos,
209	field=field,
210	mesh_type=self.mesh_type,
211	value_type=self.value_type,
212	mean=self.mean,
213	normalizer=self.normalizer,
214	trend=self.trend,
215	check_shape=False,
216	stacked=False,
217	)
218	if save:	15✔
219	setattr(self, name, field)	15✔
220	return field	15✔
221
222	def to_pyvista(
223	self, field_select="field", fieldname="field"
224	): # pragma: no cover
225	"""Create a VTK/PyVista grid of the stored field.
226
227	Parameters
228	----------
229	field_select : :class:`str`, optional
230	Field that should be stored. Can be:
231	"field", "raw_field", "krige_field", "err_field" or "krige_var".
232	Default: "field"
233	fieldname : :class:`str`, optional
234	Name of the field in the VTK file. Default: "field"
235	"""
236	grid = to_vtk_helper(
237	self, filename=None, field_select=field_select, fieldname=fieldname
238	)
239	return grid
240
241	def vtk_export(
242	self, filename, field_select="field", fieldname="field"
243	): # pragma: no cover
244	"""Export the stored field to vtk.
245
246	Parameters
247	----------
248	filename : :class:`str`
249	Filename of the file to be saved, including the path. Note that an
250	ending (.vtr or .vtu) will be added to the name.
251	field_select : :class:`str`, optional
252	Field that should be stored. Can be:
253	"field", "raw_field", "krige_field", "err_field" or "krige_var".
254	Default: "field"
255	fieldname : :class:`str`, optional
256	Name of the field in the VTK file. Default: "field"
257	"""
258	if not isinstance(filename, str):
259	raise TypeError("Please use a string filename.")
260	return to_vtk_helper(
261	self,
262	filename=filename,
263	field_select=field_select,
264	fieldname=fieldname,
265	)
266
267	def plot(self, field="field", fig=None, ax=None): # pragma: no cover
268	"""
269	Plot the spatial random field.
270
271	Parameters
272	----------
273	field : :class:`str`, optional
274	Field that should be plotted.
275	Default: "field"
276	fig : :class:`Figure` or :any:`None`
277	Figure to plot the axes on. If `None`, a new one will be created.
278	Default: `None`
279	ax : :class:`Axes` or :any:`None`
280	Axes to plot on. If `None`, a new one will be added to the figure.
281	Default: `None`
282	"""
283	# just import if needed; matplotlib is not required by setup
284	from gstools.field.plot import plot_field, plot_vec_field
285
286	if self.value_type is None:
287	raise ValueError(
288	"Field value type not set! "
289	"Specify 'scalar' or 'vector' before plotting."
290	)
291
292	elif self.value_type == "scalar":
293	r = plot_field(self, field, fig, ax)
294
295	elif self.value_type == "vector":
296	if self.model.dim == 2:
297	r = plot_vec_field(self, field, fig, ax)
298	else:
299	raise NotImplementedError(
300	"Streamflow plotting only supported for 2d case."
301	)
302	else:
303	raise ValueError(
304	"Unknown field value type: {}".format(self.value_type)
305	)
306
307	return r
308
309	@property	15✔
310	def model(self):	6✔
311	""":any:`CovModel`: The covariance model of the field."""
312	return self._model	15✔
313
314	@model.setter	15✔
315	def model(self, model):	6✔
316	if isinstance(model, CovModel):	15✔
317	self._model = model	15✔
318	else:
319	raise ValueError(	×
320	"Field: 'model' is not an instance of 'gstools.CovModel'"
321	)
322
323	@property	15✔
324	def mean(self):	6✔
325	""":class:`float` or :any:`callable`: The mean of the field."""
326	return self._mean	15✔
327
328	@mean.setter	15✔
329	def mean(self, mean):	6✔
330	self._mean = _set_mean_trend(mean, self.dim)	15✔
331
332	@property	15✔
333	def normalizer(self):	6✔
334	""":any:`Normalizer`: Normalizer of the field."""
335	return self._normalizer	15✔
336
337	@normalizer.setter	15✔
338	def normalizer(self, normalizer):	6✔
339	self._normalizer = _check_normalizer(normalizer)	15✔
340
341	@property	15✔
342	def trend(self):	6✔
343	""":class:`float` or :any:`callable`: The trend of the field."""
344	return self._trend	15✔
345
346	@trend.setter	15✔
347	def trend(self, trend):	6✔
348	self._trend = _set_mean_trend(trend, self.dim)	15✔
349
350	@property	15✔
351	def value_type(self):	6✔
352	""":class:`str`: Type of the field values (scalar, vector)."""
353	return self._value_type	15✔
354
355	@value_type.setter	15✔
356	def value_type(self, value_type):	6✔
357	if value_type not in VALUE_TYPES:	15✔
358	raise ValueError("Field: value type not in {}".format(VALUE_TYPES))	×
359	self._value_type = value_type	15✔
360
361	@property	15✔
362	def dim(self):	6✔
363	""":class:`int`: Dimension of the field."""
364	return self.model.field_dim	15✔
365
366	@property	15✔
367	def name(self):	6✔
368	""":class:`str`: The name of the class."""
369	return self.__class__.__name__	15✔
370
371	def _fmt_mean_norm_trend(self):	15✔
372	return fmt_mean_norm_trend(self)	15✔
373
374	def __repr__(self):
375	"""Return String representation."""
376	return "{0}(model={1}, value_type='{2}'{3})".format(
377	self.name,
378	self.model.name,
379	self.value_type,
380	self._fmt_mean_norm_trend(),
381	)

GeoStat-Framework / GSTools / 589427110

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous